baiyibai/pico-usb-wifiFirmware para Raspberry Pi Pico W que cria um adaptador Wi-Fi USB sem driver, com bridging transparente de camada 2, autenticação WPA2/WPA3 e console de gerenciamento fora de banda.
= pico-usb-wifi :toc: macro :toclevels: 3 :idprefix: :idseparator: -
pico-usb-wifi é um firmware para o Raspberry Pi Pico W que o transforma em um adaptador Wi-Fi USB sem driver, enumerando-se como um dispositivo USB CDC-NCM.
:figure-caption: IA Generativa
.Diagrama do pico-usb-wifi image::images/openrouter-banana2-rpi-pico.png[]
O firmware funciona como uma ponte transparente de camada 2 que encaminha quadros entre a interface sem fio do Pico W e sua interface USB. A interface USB do host adota o endereço MAC da estação Wi-Fi do Pico W, o que fornece uma identidade MAC e IP de ponta a ponta.
Nenhum driver, módulo de kernel ou pilha sem fio do lado do host é necessário; consulte <<no-host-side-wi-fi-stack,Nenhuma Pilha Wi-Fi do Lado do Host>>.
O host precisa apenas dos drivers cdc_ncm e cdc_acm que já vêm integrados em todo Linux, macOS, Windows e sistemas operacionais móveis modernos.
== Funcionalidades
O pico-usb-wifi oferece estas funcionalidades:
.Uma Situação do Mundo Real image::images/slop_2.png[]
== Por Que Isso Existe
Eu precisava de um adaptador Wi-Fi USB para usar em um projeto Linux embarcado futuro. Eu não tinha um dongle Wi-Fi USB barato, então, em vez de ir comprar um em uma loja física por cinco dólares, passei dois dias de um fim de semana prolongado de feriado e cerca de um milhão de tokens do Claude Code construindo este firmware.
白一百, Autor do pico-usb-wifi
O Google disse que não era viável:
.pico-usb-wifi "Não Viável" image::images/gemini_says_not_possible.png[]
toc::[]
== Nenhuma Pilha Wi-Fi do Lado do Host
Ao contrário de um dongle Wi-Fi USB, este adaptador expõe apenas uma interface semelhante a Ethernet para o host. O Pico W contém todo o lado sem fio: o rádio, a associação, o supplicant WPA2/WPA3 e o domínio regulatório.
Isso permite que os sistemas evitem instalar wpa_supplicant, a pilha sem fio cfg80211/mac80211, um banco de dados regulatório e firmware de chipset ou driver de fornecedor.
O provisionamento das credenciais Wi-Fi ocorre no dispositivo, por meio de seu console de gerenciamento fora da banda, não por qualquer ferramenta sem fio do lado do host.
Isso mantém um host restrito ou eletrodoméstico, ou um sem drivers sem fio, ou cujo kernel do fornecedor não os possui, com a capacidade de se conectar a redes sem fio usando apenas drivers de classe CDC universais.
== Como Funciona
[#fig-topology] .Diagrama de Topologia image::images/topology.svg[Topologia de ponte transparente de camada 2,820]
A interface USB do host recebe o endereço MAC da estação Wi-Fi do Pico W, de modo que existe um único MAC de ponta a ponta e o Pico W pode encaminhar quadros Ethernet literalmente entre USB e Wi-Fi. Uma estação Wi-Fi não pode fazer ponte com vários endereços MAC, portanto, colapsar o host e a estação em um único MAC é o que torna uma ponte transparente possível. A lógica completa, o caminho de dados e o tratamento de IPv6/multicast são descritos em <<architecture,Arquitetura>>.
== Requisitos do Host
O host requer os drivers internos cdc_ncm e cdc_acm.
Ambos fazem parte do Linux mainline há mais de uma década, portanto, qualquer kernel atualmente suportado os inclui.
Nenhum módulo fora da árvore, blob de firmware ou driver de fornecedor está envolvido.
Os mesmos drivers de classe existem no macOS, Windows 10 e posteriores, Android e iOS.
[NOTA] Nenhum outro sistema operacional foi testado.
== Compilando
O projeto é um projeto CMake padrão do pico-sdk. Requer o conjunto de ferramentas ARM embarcado, CMake, um backend de compilação (Ninja ou Make), Python 3 e uma cópia do pico-sdk com seus submódulos. O TinyUSB e o lwIP incluídos no pico-sdk são usados sem modificação.
=== Dependências
Em sistemas baseados em Arch (Arch, CachyOS, Manjaro), o conjunto de ferramentas vem dos repositórios oficiais:
arm-none-eabi-newlib fornece a biblioteca C embarcada e os cabeçalhos; sem ela, o cross-compilador não consegue encontrar stdint.h e cabeçalhos semelhantes.
libusb só é necessário para picotool, que o pico-sdk compila a partir do código-fonte durante a primeira configuração para gerar o UF2; nenhum pacote picotool separado é necessário.
=== Etapas de Compilação
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 # depois edite SSID/senha, ou deixe em branco cmake -S . -B build -G Ninja -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Release cmake --build build
O sinalizador -G Ninja é opcional; omita-o para usar o gerador Make padrão (então cmake --build build -j).
wifi_config.h contém as credenciais padrão de tempo de compilação e está no .gitignore.
Deixá-lo em branco produz uma imagem sem credenciais incorporadas, que é provisionada em tempo de execução através do console de gerenciamento (<<management-console,Console de Gerenciamento>>); preenchê-lo incorpora uma rede padrão.
== Gravando o Firmware
As etapas aqui carregam o firmware na placa.
. Segure o botão BOOTSEL enquanto conecta a placa via USB.
Ela é montada como um volume de armazenamento em massa USB RPI-RP2, geralmente em /run/media/<user>/RPI-RP2 ou /media/<user>/RPI-RP2.
. Copie pico-usb-wifi.uf2 para esse volume.
A placa reinicia no firmware automaticamente.
. Conecte a placa ao host que receberá a conectividade Wi-Fi.
== Usando em um Host Linux
Conecte o dispositivo ao host e provisione suas credenciais Wi-Fi uma vez através do console de gerenciamento (<<management-console,Console de Gerenciamento>>). A interface do host então se comporta como qualquer conexão com fio na rede do ponto de acesso.
Um host que gerencia interfaces automaticamente (NetworkManager, systemd-networkd, dhcpcd) não precisa de configuração: ele executa DHCP e SLAAC através da ponte e recebe um único endereço IPv4, um endereço IPv6, o gateway do ponto de acesso e DNS, exatamente como um cliente com fio faria.
Não há endereço ou gateway do lado do dispositivo para configurar, porque o Pico não possui nenhum.
O endereço MAC da interface é o MAC da estação Wi-Fi, que é como uma identidade é apresentada à rede.
A saída do comando ip aqui mostra a interface resultante: um cliente DHCP/SLAAC comum na própria sub-rede do ponto de acesso, com o MAC da estação e nenhum traço do Pico.
== Console de Gerenciamento
O console de gerenciamento é a interface de configuração, na primeira função serial CDC-ACM (geralmente /dev/ttyACM0).
Ele é acessível assim que o dispositivo é enumerado, antes da associação Wi-Fi, portanto, o provisionamento nunca requer uma rede.
