baiyibai/pico-usb-wifi드라이버 없는 USB Wi-Fi 어댑터, 투명한 레이어-2 브리징, WPA2/WPA3 인증, 대역 외 관리 콘솔을 생성하는 Raspberry Pi Pico W용 펌웨어.
= pico-usb-wifi :toc: macro :toclevels: 3 :idprefix: :idseparator: -
pico-usb-wifi는 Raspberry Pi Pico W를 드라이버 없는 USB Wi-Fi 어댑터로 변환하는 펌웨어로, USB CDC-NCM 장치로 인식됩니다.
:figure-caption: AI Slop
.pico-usb-wifi 다이어그램 image::images/openrouter-banana2-rpi-pico.png[]
이 펌웨어는 Pico W의 무선 인터페이스와 USB 인터페이스 간에 프레임을 전달하는 투명한 레이어-2 브리지 역할을 합니다. 호스트의 USB 인터페이스는 Pico W Wi-Fi 스테이션의 MAC 주소를 채택하여, 종단 간 단일 MAC 및 IP 식별자를 제공합니다.
호스트 측 드라이버, 커널 모듈 또는 무선 스택이 필요하지 않습니다. <<no-host-side-wi-fi-stack,호스트 측 Wi-Fi 스택 불필요>> 참조.
호스트는 모든 최신 Linux, macOS, Windows 및 모바일 OS에 기본 탑재된 cdc_ncm 및 cdc_acm 드라이버만 있으면 됩니다.
== 기능
pico-usb-wifi는 다음 기능을 제공합니다:
.실제 상황 image::images/slop_2.png[]
== 존재 이유
곧 진행할 임베디드 Linux 프로젝트에 사용할 USB Wi-Fi 어댑터가 필요했습니다. 저렴한 USB Wi-Fi 동글이 없었기에, 오프라인 매장에서 5 USD에 하나를 사러 가는 대신, 긴 주말 연휴 중 이틀과 약 백만 개의 Claude Code 토큰을 들여 이 펌웨어를 구축했습니다.
백일백, pico-usb-wifi 저자
Google은 불가능하다고 말했습니다:
.pico-usb-wifi "불가능" image::images/gemini_says_not_possible.png[]
toc::[]
== 호스트 측 Wi-Fi 스택 불필요
USB Wi-Fi 동글과 달리, 이 어댑터는 호스트에 이더넷과 유사한 인터페이스만 노출합니다. Pico W가 무선 측 전체(라디오, 연결, WPA2/WPA3 supplicant, 규제 도메인)를 처리합니다.
이를 통해 시스템은 wpa_supplicant, cfg80211/mac80211 무선 스택, 규제 데이터베이스, 칩셋 펌웨어 또는 벤더 드라이버를 설치할 필요가 없습니다.
Wi-Fi 자격 증명 제공은 호스트 측 무선 도구를 통하지 않고, 장치 자체의 대역 외 관리 콘솔을 통해 이루어집니다.
이렇게 하면 제약이 있거나 어플라이언스 호스트, 또는 무선 드라이버가 없거나 벤더 커널에 드라이버가 없는 호스트도 범용 CDC 클래스 드라이버만으로 무선 네트워크에 연결할 수 있습니다.
== 작동 방식
[#fig-topology] .토폴로지 다이어그램 image::images/topology.svg[투명 레이어-2 브리지 토폴로지,820]
호스트의 USB 인터페이스에는 Pico W의 Wi-Fi 스테이션 MAC 주소가 할당되므로, 종단 간 단일 MAC이 존재하며 Pico W는 USB와 Wi-Fi 간에 이더넷 프레임을 그대로 전달할 수 있습니다. Wi-Fi 스테이션은 여러 MAC 주소를 브리징할 수 없으므로, 호스트와 스테이션을 하나의 MAC으로 통합하는 것이 투명 브리지를 가능하게 하는 핵심입니다. 전체 근거, 데이터 경로 및 IPv6/멀티캐스트 처리는 <<architecture,아키텍처>>에 설명되어 있습니다.
== 호스트 요구 사항
호스트에는 내장된 cdc_ncm 및 cdc_acm 드라이버가 필요합니다.
두 드라이버 모두 10년 넘게 메인라인 Linux의 일부였으므로, 현재 지원되는 모든 커널에 포함되어 있습니다.
외부 모듈, 펌웨어 블롭 또는 벤더 드라이버가 필요하지 않습니다.
동일한 클래스 드라이버가 macOS, Windows 10 이상, Android 및 iOS에도 존재합니다.
[NOTE] 다른 운영 체제는 테스트되지 않았습니다.
== 빌드
이 프로젝트는 표준 pico-sdk CMake 프로젝트입니다. ARM 임베디드 툴체인, CMake, 빌드 백엔드(Ninja 또는 Make), Python 3, 그리고 서브모듈이 포함된 pico-sdk 체크아웃이 필요합니다. pico-sdk에 포함된 TinyUSB와 lwIP는 수정 없이 사용됩니다.
=== 의존성
Arch 기반 시스템(Arch, CachyOS, Manjaro)에서는 공식 저장소에서 툴체인을 제공합니다:
arm-none-eabi-newlib는 임베디드 C 라이브러리와 헤더를 제공합니다. 이것이 없으면 크로스 컴파일러가 stdint.h 및 유사 헤더를 찾을 수 없습니다.
libusb는 picotool에만 필요하며, pico-sdk는 첫 번째 구성 시 소스에서 이를 빌드하여 UF2를 생성합니다. 별도의 picotool 패키지는 필요하지 않습니다.
=== 빌드 단계
git clone -b 2.2.0 --recurse-submodules https://github.com/raspberrypi/pico-sdk export PICO_SDK_PATH="$PWD/pico-sdk"
cp src/wifi_config.h.example src/wifi_config.h # 그런 다음 SSID/비밀번호를 편집하거나 비워 둠 cmake -S . -B build -G Ninja -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Release cmake --build build
-G Ninja 플래그는 선택 사항입니다. 생략하면 기본 Make 생성기를 사용합니다(이 경우 cmake --build build -j).
wifi_config.h는 컴파일 타임 기본 자격 증명을 보유하며 gitignore 처리됩니다.
비워 두면 내장 자격 증명이 없는 이미지가 생성되어 관리 콘솔(<<management-console,관리 콘솔>>)을 통해 런타임에 프로비저닝됩니다. 내용을 채우면 기본 네트워크가 내장됩니다.
== 펌웨어 작성
다음 단계는 펌웨어를 보드에 로드하는 방법입니다.
. BOOTSEL 버튼을 누른 상태에서 보드를 USB에 연결합니다.
보드는 RPI-RP2 USB 대용량 저장소 볼륨으로 마운트되며, 일반적으로 /run/media/<user>/RPI-RP2 또는 /media/<user>/RPI-RP2에 위치합니다.
. pico-usb-wifi.uf2를 해당 볼륨에 복사합니다.
보드가 자동으로 펌웨어로 재부팅됩니다.
. Wi-Fi 연결을 받을 호스트에 보드를 연결합니다.
== Linux 호스트에서 사용
장치를 호스트에 연결하고 관리 콘솔(<<management-console,관리 콘솔>>)을 통해 Wi-Fi 자격 증명을 한 번 제공합니다. 그러면 호스트의 인터페이스는 액세스 포인트 네트워크에서 유선 연결처럼 작동합니다.
인터페이스를 자동으로 관리하는 호스트(NetworkManager, systemd-networkd, dhcpcd)는 설정이 필요 없습니다. DHCP 및 SLAAC를 브리지 위에서 실행하여 단일 IPv4 주소, IPv6 주소, 액세스 포인트의 게이트웨이 및 DNS를 유선 클라이언트와 동일하게 받습니다.
장치 측 주소나 게이트웨이를 구성할 필요가 없습니다. Pico는 어떤 주소도 보유하지 않기 때문입니다.
인터페이스의 MAC 주소는 Wi-Fi 스테이션의 MAC 주소로, 네트워크에 하나의 식별자로 제시됩니다.
여기 ip 명령 출력은 결과 인터페이스를 보여줍니다: 액세스 포인트 자체 서브넷의 일반 DHCP/SLAAC 클라이언트이며, 스테이션의 MAC을 가지며 Pico의 흔적은 없습니다.
== 관리 콘솔
관리 콘솔은 구성 프론트엔드로, 첫 번째 CDC-ACM 직렬 기능(일반적으로 /dev/ttyACM0)에 위치합니다.
장치가 인식되는 즉시, Wi-Fi 연결 전에도 접근 가능하므로 네트워크 없이도 프로비저닝이 가능합니다.
picocom 또는 screen과 같은 직렬 터미널로 열면 됩니다. USB CDC의 경우 전송 속도는 중요하지 않습니다.
콘솔은 입력을 에코하고 프롬프트를 표시하며, 모든 명령은 전체 장치 상태를 출력합니다.
Wi-Fi 인증은 WPA2-PSK 또는 WPA3-SAE(AES)입니다.
비밀번호는 네트워크의 패스프레이즈이며, 비워 두면 오픈 네트워크로 설정됩니다.
비밀번호로 보호된 프로파일은 WPA2/WPA3 전환 모드를 사용하므로, 두 종류의 액세스 포인트 모두에 연결할 수 있습니다.
콘솔은 최대 8개의 자격 증명 _프로파일_을 저장합니다. 하나는 활성 프로파일이며, 장치는 이 프로파일로 연결됩니다.
set ssid/set pass는 활성 프로파일을 편집하고, list/use/del은 세트를 관리하며, scan은 주변 네트워크를 검색하고 번호 목록에서 하나를 선택하여 연결합니다. 입력하기 어려운 문자가 있는 SSID에 유용합니다.
명령어는 대소문자를 구분하지 않으며, 콘솔은 소문자로 표시합니다.
아래 세션은 스캔을 통해 네트워크를 프로비저닝하는 예입니다.
$ picocom /dev/ttyACM0
변경 사항은 즉시 적용되어 활성 프로파일로 다시 연결됩니다. 재부팅이 필요하지 않습니다.
더 많은 네트워크를 저장하려면 반복하면 됩니다. list는 프로파일을 표시하고 use <n>은 활성 프로파일을 전환합니다:
save는 모든 프로파일을 플래시에 저장합니다. restore는 저장된 레코드를 다시 로드하여 저장되지 않은 편집 내용을 폐기합니다.
아래 표는 명령어 세트를 나열합니다.
[#tbl-config-commands] .관리 콘솔 명령어 [cols="2,3", options="header"] |=== |명령어 |효과
|set ssid <text>
|활성 프로파일의 SSID를 설정 (값은 공백 포함 가능)하고 다시 연결합니다. 프로파일이 없으면 첫 번째 프로파일을 생성합니다.
|set pass <text>
|활성 프로파일의 WPA2/WPA3 패스프레이즈를 설정 (오픈 네트워크는 비워 둠)하고 다시 연결합니다.
|set country <CC\|WORLDWIDE>
|규제 국가를 설정합니다 (다음 부팅 시 완전히 적용됨).
|set debug <on\|off>
|디버그 콘솔에 진단 정보를 스트리밍합니다. <<debug-console,디버그 콘솔>> 참조.
|list
|저장된 프로파일을 나열하고 활성 프로파일을 표시합니다.
|use <n>
|프로파일 _n_을 활성화하고 다시 연결합니다.
|del <n>
|프로파일 _n_을 삭제합니다.
|scan
|주변 네트워크를 검색하고 스캔 하위 메뉴로 진입합니다 (back, join <n>, scan 반복, 또는 live로 지속적인 비연결 스트림). join은 선택한 네트워크를 활성 프로파일로 준비하며, set pass를 위해 대기합니다.
|save
|모든 프로파일과 설정을 플래시에 저장합니다.
|restore
|저장된 설정을 다시 로드하여 저장되지 않은 변경 사항을 폐기합니다.
|===
호스트에 할당된 주소는 host IPv4 및 host IPv6로 상태 덤프에 표시되며, 브리지된 트래픽에서 수동적으로 스누핑됩니다. Pico는 보고할 주소를 보유하지 않기 때문입니다.
설정 섹터는 플래시의 끝에 위치하며, 시작 부분의 프로그램 이미지와 분리되어 있으므로 일반적인 pico-usb-wifi.uf2 재플래시는 저장된 프로파일을 그대로 유지합니다 (전체 칩 지우기는 프로파일을 지웁니다).
예외는 v1.1.0으로 _업그레이드_하는 경우입니다: 레코드 레이아웃이 여러 프로파일을 저장하도록 변경되었으므로, 1.1.0 이전 레코드는 폐기되며 네트워크를 한 번 다시 입력해야 합니다 (변경 로그 참조).
== 디버그 콘솔
디버그 콘솔은 두 번째 CDC-ACM 직렬 기능(일반적으로 /dev/ttyACM1)에 있는 쓰기 전용 진단 스트림입니다.
관리 콘솔에서 set debug on을 실행하기 전까지는 무음이므로, 꺼져 있을 때 비용이 없으며 관리에 방해되지 않습니다.
