baiyibai/pico-usb-wifiFirmware per Raspberry Pi Pico W che crea un adattatore Wi-Fi USB senza driver con bridging trasparente di livello 2, autenticazione WPA2/WPA3 e console di gestione fuori banda.
= pico-usb-wifi :toc: macro :toclevels: 3 :idprefix: :idseparator: -
pico-usb-wifi è un firmware per il Raspberry Pi Pico W che lo trasforma in un adattatore Wi-Fi USB senza driver, enumerandosi come dispositivo USB CDC-NCM.
:figure-caption: AI Slop
.Diagramma di pico-usb-wifi image::images/openrouter-banana2-rpi-pico.png[]
Il firmware funziona come un bridge trasparente di livello 2 che inoltra i frame tra l'interfaccia wireless del Pico W e la sua interfaccia USB. L'interfaccia USB dell'host adotta l'indirizzo MAC della stazione Wi-Fi del Pico W, fornendo un'unica identità MAC e IP end-to-end.
Non è richiesto alcun driver lato host, modulo del kernel o stack wireless; vedi <<no-host-side-wi-fi-stack,Nessuno Stack Wi-Fi Lato Host>>.
L'host ha bisogno solo dei driver cdc_ncm e cdc_acm inclusi nel sistema, presenti in ogni sistema operativo moderno: Linux, macOS, Windows e mobile.
== Caratteristiche
pico-usb-wifi offre queste funzionalità:
.Una situazione del mondo reale image::images/slop_2.png[]
== Perché Esiste
Mi serviva un adattatore Wi-Fi USB per un prossimo progetto embedded Linux. Non avevo un dongle Wi-Fi USB economico, quindi invece di andare a comprarne uno in un negozio fisico per cinque USD, ho passato due giorni di un lungo weekend festivo e circa un milione di token di Claude Code a costruire questo firmware.
白一百, Autore di pico-usb-wifi
Google ha detto che non era fattibile:
.pico-usb-wifi "Non fattibile" image::images/gemini_says_not_possible.png[]
toc::[]
[#no-host-side-wi-fi-stack] == Nessuno Stack Wi-Fi Lato Host
A differenza di un dongle Wi-Fi USB, questo adattatore espone all'host solo un'interfaccia simile a Ethernet. Il Pico W contiene l'intero lato wireless: la radio, l'associazione, il supplicant WPA2/WPA3 e il dominio regolatorio.
Questo consente ai sistemi di evitare l'installazione di wpa_supplicant, dello stack wireless cfg80211/mac80211, di un database regolatorio e del firmware del chipset o di un driver del vendor.
La configurazione delle credenziali Wi-Fi avviene sul dispositivo, tramite la sua console di gestione fuori banda, non attraverso strumenti wireless lato host.
Questo consente a un host vincolato o appliance, o a un host privo di driver wireless, o il cui kernel del vendor ne è privo, di connettersi a reti wireless usando solo driver universali di classe CDC.
== Come Funziona
[#fig-topology] .Diagramma di topologia image::images/topology.svg[Topologia bridge trasparente layer-2,820]
All'interfaccia USB dell'host viene assegnato l'indirizzo MAC della stazione Wi-Fi del Pico W, quindi esiste un unico MAC end-to-end e il Pico W può inoltrare i frame Ethernet così come sono tra USB e Wi-Fi. Una stazione Wi-Fi non può fare da bridge per più indirizzi MAC, quindi ricondurre host e stazione a un unico MAC è ciò che rende possibile un bridge trasparente. La motivazione completa, il percorso dei dati e la gestione IPv6/multicast sono descritti in <<architecture,Architettura>>.
== Requisiti dell'host
L'host richiede i driver cdc_ncm e cdc_acm inclusi nel kernel.
Entrambi fanno parte del kernel Linux mainline da oltre un decennio, quindi qualsiasi kernel attualmente supportato li include.
Non è coinvolto alcun modulo fuori tree, blob di firmware o driver del vendor.
Gli stessi driver di classe esistono su macOS, Windows 10 e successivi, Android e iOS.
[NOTE] Nessun altro sistema operativo è stato testato.
== Compilazione
Il progetto è un progetto CMake standard del pico-sdk. Richiede la toolchain embedded ARM, CMake, un backend di build (Ninja o Make), Python 3 e un checkout del pico-sdk con i suoi sottomoduli. TinyUSB e lwIP inclusi nel pico-sdk vengono usati senza modifiche.
=== Dipendenze
Sui sistemi basati su Arch (Arch, CachyOS, Manjaro), la toolchain proviene dai repository ufficiali:
arm-none-eabi-newlib fornisce la libreria C embedded e gli header; senza di essa il cross-compilatore non riesce a trovare stdint.h e header simili.
libusb serve solo per picotool, che il pico-sdk compila dai sorgenti durante la prima configurazione per generare il file UF2; non è richiesto alcun pacchetto picotool separato.
=== Passaggi di compilazione
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
Il flag -G Ninja è opzionale; omettilo per usare il generatore Make predefinito (quindi cmake --build build -j).
wifi_config.h contiene le credenziali predefinite a tempo di compilazione ed è ignorato da git.
Lasciarlo vuoto produce un'immagine senza credenziali incorporate, che viene configurata a runtime tramite la console di gestione (<<management-console,Console di Gestione>>); riempirlo incorpora una rete predefinita.
== Scrittura del firmware
I passaggi seguenti caricano il firmware sulla scheda.
. Tieni premuto il pulsante BOOTSEL mentre colleghi la scheda tramite USB.
Viene montata come volume di memorizzazione di massa USB RPI-RP2, di solito in /run/media/<user>/RPI-RP2 o /media/<user>/RPI-RP2.
. Copia pico-usb-wifi.uf2 su quel volume.
La scheda si riavvia automaticamente avviando il firmware.
. Collega la scheda all'host che deve ricevere la connettività Wi-Fi.
== Uso su un host Linux
Collega il dispositivo all'host e configura una volta le sue credenziali Wi-Fi tramite la console di gestione (<<management-console,Console di Gestione>>). L'interfaccia dell'host si comporta quindi come qualsiasi connessione cablata sulla rete dell'access point.
Un host che gestisce le interfacce automaticamente (NetworkManager, systemd-networkd, dhcpcd) non richiede configurazione: esegue DHCP e SLAAC sul bridge e riceve un singolo indirizzo IPv4, un indirizzo IPv6, il gateway dell'access point e il DNS, esattamente come farebbe un client cablato.
Non esiste alcun indirizzo o gateway lato dispositivo da configurare, perché il Pico non ne possiede.
L'indirizzo MAC dell'interfaccia è il MAC della stazione Wi-Fi, ed è così che un'unica identità viene presentata alla rete.
L'output del comando ip qui mostra l'interfaccia risultante: un normale client DHCP/SLAAC sulla sottorete dell'access point, con il MAC della stazione e nessuna traccia del Pico.
[#management-console] == Console di Gestione
La console di gestione è il front-end di configurazione, sulla prima funzione seriale CDC-ACM (di solito /dev/ttyACM0).
È raggiungibile appena il dispositivo si enumera, prima che il Wi-Fi sia associato, quindi la configurazione non richiede mai una rete.
