baiyibai/pico-usb-wifiFirmware para Raspberry Pi Pico W que crea un adaptador Wi-Fi USB sin controlador con puenteo transparente de capa 2, autenticación WPA2/WPA3 y consola de administración fuera de banda.
= pico-usb-wifi :toc: macro :toclevels: 3 :idprefix: :idseparator: -
pico-usb-wifi es un firmware para la Raspberry Pi Pico W que la convierte en un adaptador USB Wi-Fi sin controlador, enumerándose como un dispositivo USB CDC-NCM.
:figure-caption: Slop de IA
.Diagrama de pico-usb-wifi image::images/openrouter-banana2-rpi-pico.png[]
El firmware funciona como un puente transparente de capa 2 que reenvía tramas entre la interfaz inalámbrica de la Pico W y su interfaz USB. La interfaz USB del host adopta la dirección MAC de la estación Wi-Fi de la Pico W, lo que proporciona una única identidad MAC e IP de extremo a extremo.
No se requiere un controlador del lado del host, un módulo del kernel ni una pila inalámbrica; consulte <<no-host-side-wi-fi-stack,No se necesita pila Wi-Fi del lado del host>>.
El host solo necesita los controladores integrados cdc_ncm y cdc_acm que vienen con todos los sistemas operativos modernos: Linux, macOS, Windows y móviles.
== Características
pico-usb-wifi ofrece las siguientes características:
.Una Situación del Mundo Real image::images/slop_2.png[]
== Por Qué Existe Esto
Necesitaba un adaptador USB Wi-Fi para usar en un próximo proyecto de Linux embebido. No tenía un dongle USB Wi-Fi barato, así que en lugar de ir a comprar uno a una tienda física por cinco dólares, pasé dos días de un fin de semana festivo largo y aproximadamente un millón de tokens de Claude Code construyendo este firmware.
白一百, Autor de pico-usb-wifi
Google dijo que no era factible:
.pico-usb-wifi "No Factible" image::images/gemini_says_not_possible.png[]
toc::[]
== No se necesita pila Wi-Fi del lado del host
A diferencia de un dongle USB Wi-Fi, este adaptador expone solo una interfaz similar a Ethernet al host. La Pico W contiene todo el lado inalámbrico: la radio, la asociación, el suplicante WPA2/WPA3 y el dominio regulatorio.
Esto permite que los sistemas eviten instalar wpa_supplicant, la pila inalámbrica cfg80211/mac80211, una base de datos regulatoria y el firmware del chipset o un controlador del proveedor.
El aprovisionamiento de las credenciales Wi-Fi ocurre en el dispositivo, a través de su consola de gestión fuera de banda, no mediante ninguna herramienta inalámbrica del lado del host.
Esto permite que un host limitado o de electrodoméstico, o uno sin controladores inalámbricos, o cuyo kernel del proveedor carece de ellos, tenga la capacidad de conectarse a redes inalámbricas utilizando solo controladores de clase CDC universales.
== Cómo Funciona
[#fig-topology] .Diagrama de Topología image::images/topology.svg[Transparent layer-2 bridge topology,820]
La interfaz USB del host recibe la dirección MAC de la estación Wi-Fi de la Pico W, por lo que existe una única MAC de extremo a extremo y la Pico W puede reenviar tramas Ethernet tal cual entre USB y Wi-Fi. Una estación Wi-Fi no puede puentear varias direcciones MAC, por lo que colapsar el host y la estación en una sola MAC es lo que hace posible un puente transparente. La justificación completa, la ruta de datos y el manejo de IPv6/multidifusión se describen en <<architecture,Arquitectura>>.
== Requisitos del Host
El host requiere los controladores integrados cdc_ncm y cdc_acm.
Ambos han sido parte del kernel principal de Linux durante más de una década, por lo que cualquier kernel compatible actualmente los incluye.
No se requiere ningún módulo fuera del árbol, blob de firmware o controlador de proveedor.
Los mismos controladores de clase existen en macOS, Windows 10 y posteriores, Android e iOS.
[NOTA] No se probaron otros sistemas operativos.
== Compilación
El proyecto es un proyecto CMake estándar de pico-sdk. Necesita la cadena de herramientas ARM embebida, CMake, un backend de compilación (Ninja o Make), Python 3 y un clon de pico-sdk con sus submódulos. TinyUSB y lwIP incluidos en pico-sdk se usan sin modificar.
=== Dependencias
En sistemas basados en Arch (Arch, CachyOS, Manjaro), la cadena de herramientas proviene de los repositorios oficiales:
arm-none-eabi-newlib proporciona la biblioteca C embebida y los encabezados; sin él, el compilador cruzado no puede encontrar stdint.h y encabezados similares.
libusb solo es necesario para picotool, que pico-sdk compila desde la fuente durante la primera configuración para generar el UF2; no se requiere un paquete separado de picotool.
=== Pasos de Compilación
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
La bandera -G Ninja es opcional; omítela para usar el generador Make predeterminado (luego cmake --build build -j).
wifi_config.h contiene las credenciales predeterminadas en tiempo de compilación y está en .gitignore.
Dejarlo en blanco produce una imagen sin credenciales incorporadas que se aprovisiona en tiempo de ejecución a través de la consola de gestión (<<management-console,Consola de Gestión>>); llenarlo incorpora una red predeterminada.
== Carga del Firmware
Los pasos aquí cargan el firmware en la placa.
. Mantén presionado el botón BOOTSEL mientras conectas la placa por USB.
Se monta como un volumen de almacenamiento masivo USB RPI-RP2, comúnmente en /run/media/<usuario>/RPI-RP2 o /media/<usuario>/RPI-RP2.
. Copia pico-usb-wifi.uf2 en ese volumen.
La placa se reinicia automáticamente en el firmware.
. Conecta la placa al host que recibirá la conectividad Wi-Fi.
== Uso en un Host Linux
Conecta el dispositivo al host y aprovisiona sus credenciales Wi-Fi una vez a través de la consola de gestión (<<management-console,Consola de Gestión>>). La interfaz del host se comporta entonces como cualquier conexión por cable en la red del punto de acceso.
Un host que gestiona interfaces automáticamente (NetworkManager, systemd-networkd, dhcpcd) no necesita configuración: ejecuta DHCP y SLAAC a través del puente y recibe una sola dirección IPv4, una dirección IPv6, la puerta de enlace del punto de acceso y DNS, exactamente como lo haría un cliente por cable.
No hay ninguna dirección o puerta de enlace del lado del dispositivo para configurar, porque la Pico no tiene ninguna.
La dirección MAC de la interfaz es la MAC de la estación Wi-Fi, que es como se presenta una identidad a la red.
La salida del comando ip aquí muestra la interfaz resultante: un cliente DHCP/SLAAC ordinario en la propia subred del punto de acceso, con la MAC de la estación y sin rastro de la Pico.
== Consola de Gestión
