baiyibai/pico-usb-wifiFirmware für Raspberry Pi Pico W, das einen treiberlosen USB-WLAN-Adapter mit transparenter Layer-2-Brücke, WPA2/WPA3-Authentifizierung und Out-of-Band-Verwaltungskonsole erstellt.
= pico-usb-wifi :toc: macro :toclevels: 3 :idprefix: :idseparator: -
pico-usb-wifi ist eine Firmware für den Raspberry Pi Pico W, die ihn in einen treiberlosen USB-WLAN-Adapter verwandelt, der als USB-CDC-NCM-Gerät erkannt wird.
:figure-caption: KI-Schrott
.pico-usb-wifi Diagramm image::images/openrouter-banana2-rpi-pico.png[]
Die Firmware arbeitet als transparente Layer-2-Brücke, die Frames zwischen der WLAN-Schnittstelle des Pico W und seiner USB-Schnittstelle weiterleitet. Die USB-Schnittstelle des Hosts übernimmt die MAC-Adresse der Pico-W-WLAN-Station, sodass durchgängig eine einzige MAC- und IP-Identität besteht.
Es wird kein hostseitiger Treiber, Kernelmodul oder WLAN-Stack benötigt; siehe <<no-host-side-wi-fi-stack,Kein hostseitiger WLAN-Stack>>.
Der Host benötigt nur die integrierten cdc_ncm- und cdc_acm-Treiber, die in jedem modernen Linux, macOS, Windows und mobilen Betriebssystem enthalten sind.
== Funktionen
pico-usb-wifi bietet diese Funktionen:
.Eine reale Situation image::images/slop_2.png[]
== Warum es das gibt
Ich brauchte einen USB-WLAN-Adapter für ein anstehendes Embedded-Linux-Projekt. Ich hatte keinen günstigen USB-WLAN-Dongle, also anstatt für fünf USD in einen stationären Laden zu gehen und einen zu kaufen, verbrachte ich zwei Tage eines langen Feiertagswochenendes und etwa eine Million Claude-Code-Token mit dem Bau dieser Firmware.
白一百, Autor von pico-usb-wifi
Google sagte, es sei nicht machbar:
.pico-usb-wifi "Nicht machbar" image::images/gemini_says_not_possible.png[]
toc::[]
== Kein hostseitiger WLAN-Stack
Anders als ein USB-WLAN-Dongle stellt dieser Adapter dem Host nur eine Ethernet-ähnliche Schnittstelle zur Verfügung. Der Pico W enthält die gesamte WLAN-Seite: das Funkmodul, die Assoziation, den WPA2/WPA3-Supplikanten und die Regulierungsdomäne.
Dadurch können Systeme die Installation von wpa_supplicant, dem cfg80211/mac80211-WLAN-Stack, einer Regulierungsdatenbank sowie Chipsatz-Firmware oder einem Herstellertreiber vermeiden.
Die Bereitstellung der WLAN-Anmeldedaten erfolgt auf dem Gerät über die Out-of-Band-Verwaltungskonsole, nicht über hostseitige WLAN-Tools.
So behält ein eingeschränkter oder Appliance-Host, oder einer ohne WLAN-Treiber oder dessen Herstellerkernel diese nicht enthält, die Möglichkeit, sich nur mit universellen CDC-Klassentreibern mit WLAN-Netzwerken zu verbinden.
== Wie es funktioniert
[#fig-topologie] .Topologie-Diagramm image::images/topology.svg[Transparente Layer-2-Brückentopologie,820]
Der USB-Schnittstelle des Hosts wird die MAC-Adresse der Pico-W-WLAN-Station zugewiesen, sodass eine einzelne MAC durchgängig existiert und der Pico W Ethernet-Frames unverändert zwischen USB und WLAN weiterleiten kann. Eine WLAN-Station kann nicht mehrere MAC-Adressen brücken, daher ist die Verschmelzung von Host und Station auf eine MAC das, was eine transparente Brücke überhaupt erst möglich macht. Die vollständige Begründung, der Datenpfad und die IPv6-/Multicast-Behandlung werden in <<architektur,Architektur>> beschrieben.
== Host-Anforderungen
Der Host benötigt die integrierten cdc_ncm- und cdc_acm-Treiber.
Beide sind seit über einem Jahrzehnt Teil des Mainline-Linux, daher enthält jeder aktuell unterstützte Kernel sie.
Es ist kein Out-of-Tree-Modul, Firmware-Blob oder Herstellertreiber erforderlich.
Dieselben Klassentreiber gibt es für macOS, Windows 10 und höher, Android und iOS.
[HINWEIS] Andere Betriebssysteme wurden nicht getestet.
== Bauen
Das Projekt ist ein Standard-pico-sdk-CMake-Projekt. Es werden die ARM-Embedded-Toolchain, CMake, ein Build-Backend (Ninja oder Make), Python 3 und ein Checkout des pico-sdk mit seinen Submodulen benötigt. Das im pico-sdk gebündelte TinyUSB und lwIP werden unverändert verwendet.
=== Abhängigkeiten
Auf Arch-basierten Systemen (Arch, CachyOS, Manjaro) stammt die Toolchain aus den offiziellen Repositories:
arm-none-eabi-newlib stellt die eingebettete C-Bibliothek und Header bereit; ohne sie findet der Cross-Compiler stdint.h und ähnliche Header nicht.
libusb wird nur für picotool benötigt, das das pico-sdk während der ersten Konfiguration aus den Quellen baut, um die UF2 zu erzeugen; es ist kein separates picotool-Paket erforderlich.
=== Build-Schritte
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 # dann SSID/Passwort bearbeiten oder leer lassen cmake -S . -B build -G Ninja -DPICO_BOARD=pico_w -DCMAKE_BUILD_TYPE=Release cmake --build build
Das Flag -G Ninja ist optional; lassen Sie es weg, um den standardmäßigen Make-Generator zu verwenden (dann cmake --build build -j).
wifi_config.h enthält die kompilierten Standard-Anmeldedaten und ist in der Git-Ignore-Liste.
Wenn Sie es leer lassen, wird ein Image ohne fest eingebaute Anmeldedaten erstellt, das zur Laufzeit über die Verwaltungskonsole bereitgestellt wird (<<management-console,Verwaltungskonsole>>); wenn Sie es ausfüllen, wird ein Standardnetzwerk fest eingebaut.
== Firmware schreiben
Die Schritte hier laden die Firmware auf das Board.
. Halten Sie die BOOTSEL-Taste gedrückt, während Sie das Board über USB anschließen.
Es wird als USB-Massenspeichervolumen RPI-RP2 eingebunden, üblicherweise unter /run/media/<user>/RPI-RP2 oder /media/<user>/RPI-RP2.
. Kopieren Sie pico-usb-wifi.uf2 auf dieses Volumen.
Das Board startet automatisch in die Firmware neu.
. Verbinden Sie das Board mit dem Host, der WLAN-Konnektivität erhalten soll.
== Verwendung auf einem Linux-Host
Schließen Sie das Gerät an den Host an und stellen Sie die WLAN-Anmeldedaten einmalig über die Verwaltungskonsole bereit (<<management-console,Verwaltungskonsole>>). Die Schnittstelle des Hosts verhält sich dann wie jede kabelgebundene Verbindung im Netzwerk des Zugangspunkts.
Ein Host, der Schnittstellen automatisch verwaltet (NetworkManager, systemd-networkd, dhcpcd), benötigt keine Einrichtung: Er führt DHCP und SLAAC über die Brücke aus und erhält eine einzelne IPv4-Adresse, eine IPv6-Adresse, das Gateway des Zugangspunkts und DNS – genau wie ein kabelgebundener Client.
Es gibt keine geräteseitige Adresse oder Gateway zu konfigurieren, da der Pico keine besitzt.
Die MAC-Adresse der Schnittstelle ist die der WLAN-Station, wodurch eine Identität im Netzwerk präsentiert wird.
Die Ausgabe des ip-Befehls hier zeigt die resultierende Schnittstelle: ein gewöhnlicher DHCP/SLAAC-Client im eigenen Subnetz des Zugangspunkts, mit der MAC der Station und ohne Spur des Pico.
== Verwaltungskonsole
