baiyibai/pico-usb-wifiПрошивка для Raspberry Pi Pico W, создающая беспроводной USB-адаптер Wi-Fi без драйверов с прозрачным мостом уровня L2, аутентификацией WPA2/WPA3 и консолью управления внеполосного доступа.
= 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[]
Прошивка работает как прозрачный мост на уровне 2 (L2), пересылающий кадры между беспроводным интерфейсом Pico W и её USB-интерфейсом. USB-интерфейс хоста принимает MAC-адрес Wi-Fi станции Pico W, что обеспечивает единый MAC и IP-адрес на всём пути.
Не требуется никакого драйвера, модуля ядра или стека беспроводной связи со стороны хоста; см. <<no-host-side-wi-fi-stack,Отсутствие стека Wi-Fi на стороне хоста>>.
Хосту нужны только встроенные драйверы cdc_ncm и cdc_acm, которые поставляются с каждой современной ОС Linux, macOS, Windows и мобильной ОС.
== Возможности
pico-usb-wifi предоставляет следующие возможности:
.Реальная ситуация image::images/slop_2.png[]
== Зачем это существует
Мне понадобился USB Wi-Fi адаптер для предстоящего проекта на встраиваемом Linux. У меня не было дешёвого USB Wi-Fi донгла, поэтому вместо того, чтобы пойти и купить его в обычном магазине за пять долларов, я потратил два дня длинных праздничных выходных и примерно миллион токенов Claude Code на создание этой прошивки.
白一百, Автор pico-usb-wifi
Google сказал, что это невозможно:
.pico-usb-wifi "Невозможно" image::images/gemini_says_not_possible.png[]
toc::[]
== Отсутствие стека Wi-Fi на стороне хоста
В отличие от USB Wi-Fi донгла, этот адаптер предоставляет хосту только интерфейс, подобный Ethernet. Pico W содержит всю беспроводную часть: радио, ассоциацию, клиент WPA2/WPA3 и регуляторный домен.
Это позволяет системам избежать установки wpa_supplicant, стека беспроводной связи cfg80211/mac80211, базы данных регуляции, а также прошивки чипсета или драйвера вендора.
Настройка учётных данных Wi-Fi происходит на устройстве через его внеполосную консоль управления, а не через какие-либо инструменты беспроводной связи хоста.
Это позволяет ограниченному или встраиваемому хосту, или хосту без драйверов беспроводной связи, или ядру вендора, в котором они отсутствуют, подключаться к беспроводным сетям, используя только универсальные драйверы класса CDC.
== Как это работает
[#fig-topology] .Топологическая схема image::images/topology.svg[Топология прозрачного моста L2,820]
USB-интерфейсу хоста присваивается MAC-адрес Wi-Fi станции Pico W, так что существует единый MAC на всём пути, и Pico W может пересылать Ethernet-кадры без изменений между USB и Wi-Fi. Станция Wi-Fi не может прозрачно мостить несколько MAC-адресов, поэтому объединение хоста и станции в один MAC — это то, что делает возможным прозрачный мост. Полное обоснование, путь данных и обработка IPv6/многоадресной рассылки описаны в <<architecture,Архитектура>>.
== Требования к хосту
Хосту требуются встроенные драйверы cdc_ncm и cdc_acm.
Оба являются частью основного ядра Linux уже более десяти лет, поэтому любое поддерживаемое ядро их включает.
Не требуется никаких внешних модулей, бинарных прошивок или драйверов вендора.
Те же драйверы класса существуют на macOS, Windows 10 и новее, Android и iOS.
[NOTE] Другие операционные системы не тестировались.
== Сборка
Проект является стандартным проектом CMake для pico-sdk. Для него требуются инструментарий ARM Embedded, CMake, система сборки (Ninja или Make), Python 3 и копия pico-sdk с подмодулями. TinyUSB и lwIP, входящие в состав pico-sdk, используются без изменений.
=== Зависимости
В системах на основе 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 # then edit SSID/password, or leave blank 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 содержит учётные данные по умолчанию, устанавливаемые на этапе компиляции, и этот файл игнорируется git.
Если оставить его пустым, получится образ без встроенных учётных данных, которые можно настроить во время выполнения через консоль управления (<<management-console,Консоль управления>>); если заполнить его, то задаётся сеть по умолчанию.
== Запись прошивки
Действия ниже загружают прошивку на плату.
. Удерживайте кнопку BOOTSEL при подключении платы к компьютеру через USB.
Она смонтируется как USB-накопитель RPI-RP2, обычно по адресу /run/media/<user>/RPI-RP2 или /media/<user>/RPI-RP2.
. Скопируйте pico-usb-wifi.uf2 на том.
Плата автоматически перезагрузится в прошивку.
. Подключите плату к хосту, который должен получить Wi-Fi-подключение.
== Использование на хосте с Linux
Подключите устройство к хосту и один раз настройте его учётные данные Wi-Fi через консоль управления (<<management-console,Консоль управления>>). Затем интерфейс хоста будет вести себя как любое проводное подключение в сети точки доступа.
Хост, автоматически управляющий интерфейсами (NetworkManager, systemd-networkd, dhcpcd), не требует настройки: он запускает DHCP и SLAAC через мост и получает один IPv4-адрес, IPv6-адрес, шлюз точки доступа и DNS, точно как проводной клиент.
На стороне устройства не нужно настраивать адрес или шлюз, потому что Pico не имеет таковых.
MAC-адрес интерфейса — это MAC Wi-Fi станции, поэтому сеть видит единую идентичность.
Вывод команды ip здесь показывает результирующий интерфейс: обычный DHCP/SLAAC-клиент в собственной подсети точки доступа, с MAC-адресом станции и без следов Pico.
== Консоль управления
Консоль управления — это интерфейс для настройки, расположенный на первой последовательной функции CDC-ACM (обычно /dev/ttyACM0).
Она доступна сразу после обнаружения устройства, до ассоциации Wi-Fi, поэтому настройка никогда не требует сети.
Откройте её с помощью последовательного терминала, например picocom или screen; скорость передачи не имеет значения для USB CDC.
Консоль отображает ввод и показывает приглашение, каждая команда печатает полное состояние устройства.
Аутентификация Wi-Fi осуществляется либо WPA2-PSK, либо WPA3-SAE (AES).
Пароль — это сетевая фраза доступа, или открытая сеть, если пароль пустой.
Защищённый паролем профиль использует режим перехода WPA2/WPA3, поэтому он подключается к любой точке доступа.
