OpenWrt Raspberry Pi 3 WiFi USB: guía paso a paso
OpenWrt Raspberry Pi 3 WiFi USB: si tenés una Raspberry Pi 3 con OpenWrt y conectaste un TP-Link Archer T2U Plus, es probable que el adaptador aparezca en lsusb pero no funcione. En algunos casos, el router se queda colgado al usar iw dev o wifi reload.
Eso me pasó a mí. En este artículo te cuento qué falló, cómo compilé el driver correcto con el SDK oficial de OpenWrt y cómo dejé el adaptador como salida a internet (WAN) mientras el WiFi integrado de la Pi queda para la red del homelab.
Es un tutorial con bastante comandos, así que te recomiendo leerlo completo antes de empezar.
Índice de artículo
Lo que necesitás
- Una Raspberry Pi 3 Model B o B+.
- Una tarjeta microSD con OpenWrt 25.12 para
bcm27xx/bcm2710. - Un adaptador TP-Link Archer T2U Plus (chip RTL8821AU, ID USB
2357:0120). Verificalo conlsusbantes de seguir. - Una fuente oficial de 5 V / 2.5 A.
- Una PC con Linux. En mi caso usé Linux Mint 21.3, que está basado en Ubuntu 22.04.
- Entre 20 y 30 GB libres en disco para el SDK y la compilación.
Tené en cuenta que el Ethernet de la Raspberry Pi 3 es de 100 Mbps. No es un problema del driver: el chip va conectado por USB 2.0. Por eso este artículo se enfoca en que la conexión sea estable, no en la velocidad máxima.
Paso 1: hacé un respaldo antes de tocar nada
Antes de cambiar la configuración, conectate por cable Ethernet, no por WiFi, y guardá una copia:
B=/root/backup-$(date +%F-%H%M) mkdir -p "$B" cp -a /etc/config/. "$B/" sysupgrade -b "$B/sysupgrade-backup.tar.gz" ip route > "$B/routes.txt"
Esto te sirve para volver atrás si algo sale mal. Ojo: el respaldo contiene las claves WiFi en texto plano, así que no lo subas a ningún lado público.
Paso 2: entendé por qué no funcionaba
En OpenWrt 25.12 el gestor de paquetes es apk, no opkg. Lo primero que probé fue kmod-rtl8812au-ct, un driver de la comunidad que aparece en el feed. Con mi adaptador, el driver se cargaba, pero cualquier comando de red (iw dev, ip a) quedaba bloqueado.
Los logs mostraban esto:
- El adaptador se enumeraba bien (
usb 1-1.2, ID2357:0120). netifdintentaba configurarphy1y fallaba conPHY is undefined for device.- Después de un
wifi reload, los comandos de red se colgaban.
Como lo que estába probando no funcionaba, lo desinsté:
apk info -W /lib/modules/$(uname -r)/rtl8812au.ko apk del kmod-rtl8812au-ct rm -f /etc/modules.d/rtl8812au-ct reboot
El comando apk info -W te dice qué paquete instaló el módulo. Así no adivinás el nombre.
Paso 3: compilá el driver con el SDK oficial
El driver que mejor funcionó es el que mantiene el proyecto rtw88 para OpenWrt, en el repositorio LuisMitaHL/rtw88-openwrt. Lo compilé con el SDK de la misma versión que corre el router, porque si el kernel no coincide, el módulo no se carga.
3.1. Preparar el entorno en Linux Mint
sudo apt update sudo apt install -y build-essential clang flex bison g++ gawk \ gcc-multilib g++-multilib gettext git libncurses-dev libssl-dev \ python3-distutils python3-setuptools rsync swig unzip zlib1g-dev \ file wget zstd
Verificá que las herramientas estén instaladas:
gcc --version | head -n 1 python3 --version git --version zstd --version
3.2. Descargar el SDK
Creá una carpeta de trabajo y descargá el SDK desde el servidor de OpenWrt:
mkdir -p ~/openwrt-build && cd ~/openwrt-build URL="https://downloads.openwrt.org/releases/25.12.6/targets/bcm27xx/bcm2710/" SDK="openwrt-sdk-25.12.6-bcm27xx-bcm2710_gcc-14.3.0_musl.Linux-x86_64.tar.zst" wget -c "$URL$SDK" tar --zstd -xf "$SDK" cd "openwrt-sdk-25.12.6-bcm27xx-bcm2710_gcc-14.3.0_musl.Linux-x86_64"
Si el nombre del archivo cambió en el servidor, listá los SDK disponibles con curl -s "$URL" | grep -o 'openwrt-sdk-[^"]*\.tar\.zst' | sort -u.
3.3. Agregar el paquete y ajustar los parches
./scripts/feeds update -a ./scripts/feeds install -a git clone https://github.com/LuisMitaHL/rtw88-openwrt package/kernel/rtw88-backports ls package/kernel/rtw88-backports/patches/
El repositorio trae un parche de compatibilidad por cada versión de OpenWrt. Para 25.12 necesitás 999-openwrt-25.12-compat.patch. Eliminá el de 24.10:
rm package/kernel/rtw88-backports/patches/999-openwrt-24.10-compat.patch
No borres los parches 0400 a 0910. Son correcciones del driver, no de versión.
3.4. Compilar
make defconfig make package/rtw88-backports/compile -j$(nproc) 2>&1 | tee build-rtw88.log
Al principio vas a ver muchos mensajes WARNING y recursive dependency detected. Vienen de otros feeds y no impiden compilar nuestro paquete. Lo que importa es que el proceso termine sin errores. Si se detiene, revisá el log:
grep -nE "Error|error:|\*\*\*" build-rtw88.log | tail -n 30
Cuando termine, buscá los paquetes generados:
find bin -name "rtw88-backports-firmware-*.apk" find bin -name "kmod-rtw88-backports-usb-*.apk"
Si la compilación tarda, es normal. En la primera vez puede llevar bastante tiempo.
Paso 4: instalá el driver en el router
Con el adaptador desconectado, copiá los dos paquetes a la Raspberry Pi e instalalos. Primero el firmware y después el módulo:
scp rtw88-backports-firmware-*.apk kmod-rtw88-backports-usb-*.apk root@192.168.1.1:/tmp/
En el router:
apk add --allow-untrusted /tmp/rtw88-backports-firmware-*.apk apk add --allow-untrusted /tmp/kmod-rtw88-backports-usb-*.apk reboot
Después del reinicio, conectá el adaptador al mismo puerto USB que usaste antes y revisá:
lsmod | grep -iE "rtw|8821" dmesg | grep -iE "rtw_8821au|Firmware" iw dev
Deberías ver rtw_8821au cargado y una línea parecida a Firmware version 42.4.0.
Importante: los nombres phy0 y phy1 cambian en cada arranque. No los uses como referencia fija. Para identificar cada radio, usá la MAC y la ruta:
for p in /sys/class/ieee80211/phy*; do echo "== $(basename $p)" cat $p/macaddress readlink -f $p/device done
El adaptador TP-Link tiene una ruta con 1-1.2. El WiFi integrado tiene una ruta con mmc.
Paso 5: ajustá la ruta de la radio USB
En mi configuración, la sección radio1 tenía una ruta vieja, de cuando el adaptador estaba en otro puerto. Eso hacía que netifd no encontrara la radio y entrara en bucle con PHY is undefined.
Revisá la ruta actual:
readlink -f /sys/class/ieee80211/phy1/device uci get wireless.radio1.path
Si no coinciden, corregí la ruta sin el prefijo /sys/devices/:
uci set wireless.radio1.path='platform/soc/3f980000.usb/usb1/1-1/1-1.2/1-1.2:1.0' uci commit wireless
Ajustá la ruta a lo que te devuelva tu sistema. Si cambiás el adaptador de puerto, tenés que revisarla de nuevo.
Paso 6: configurá el país regulatorio
Este fue el paso que más me costó. Con el país en 00, el adaptador no se asociaba a la red de 5 GHz. Lo verifiqué con iw reg get, que mostraba country 00: DFS-UNSET.
Configurá el país que corresponda donde esté usando esta solución, en mi caso es Argentina:
uci set wireless.radio0.country='AR' uci set wireless.radio1.country='AR' uci commit wireless
Paso 7: el adaptador como WAN (cliente)
Para que el TP-Link sea la salida a internet, lo configuramos como cliente en la interfaz wwan:
uci set wireless.radio1.disabled='0' uci set wireless.wifinet_usb=wifi-iface uci set wireless.wifinet_usb.device='radio1' uci set wireless.wifinet_usb.mode='sta' uci set wireless.wifinet_usb.network='wwan' uci set wireless.wifinet_usb.ssid='TU_RED_5GHZ' uci set wireless.wifinet_usb.encryption='psk2' read -s -p "Clave WiFi WAN: " K; echo uci set wireless.wifinet_usb.key="$K" unset K uci commit wireless
El comando read -s hace que la clave no quede en el historial del shell. Reemplazá TU_RED_5GHZ por el nombre de tu red de 5 GHz.
Después de aplicar, reiniciá el router. No uses wifi reload, porque con este driver puede dejar el sistema colgado. Después revisá:
iw dev iw dev phy0-sta0 link
En mi caso, la asociación se completó y el log mostró CTRL-EVENT-CONNECTED. El nombre de la interfaz puede variar según el arranque, así que usá el que aparezca en iw dev.
Paso 8: el WiFi integrado como punto de acceso
Este paso es el que tenés que verificar en tu equipo, porque yo no lo dejé confirmado en el registro al momento de escribir esto.
La idea es que el WiFi integrado de la Raspberry Pi sea un punto de acceso (AP) conectado a la LAN, igual que el puerto Ethernet:
uci delete wireless.wifinet1 2>/dev/null uci set wireless.radio0.htmode='HT20' uci set wireless.radio0.channel='6' uci set wireless.homelab=wifi-iface uci set wireless.homelab.device='radio0' uci set wireless.homelab.mode='ap' uci set wireless.homelab.network='lan' uci set wireless.homelab.ssid='HomeLab' uci set wireless.homelab.encryption='psk2' read -s -p "Clave WiFi HomeLab: " K; echo uci set wireless.homelab.key="$K" unset K uci commit wireless
En 2.4 GHz usá HT20 y el canal 6, que no se superpone con el 1 ni con el 11. Después reiniciá y comprobá con un celular que la red HomeLab aparece y que obtiene IP en 192.168.1.x.
Verificación final
Revisá la tabla de ruteo: debe haber una sola ruta por defecto, por la interfaz wwan:
ip route ping -c 3 8.8.8.8 ubus call network.wireless status | grep -E '"up"|"ssid"|"mode"'
Si algo no funciona, revisá los logs de WiFi:
logread | grep -iE "wpa_supplicant|CTRL-EVENT|netifd" | tail -n 40
Errores comunes
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
iw dev o ip a se cuelgan | Driver de la comunidad incompatible | Desinstalar kmod-rtl8812au-ct e instalar el driver rtw88 compilado |
PHY is undefined for device | La ruta de radio1 no coincide con el puerto USB | Corregir wireless.radio1.path |
| El adaptador no se asocia a 5 GHz | País regulatorio en 00 | Configurar country='AR' |
command failed: Not supported (-95) | Ajuste de antenas no soportado por el driver | Aparece en el arranque normal y no impide la conexión |
| No se encuentra el paquete | Nombre incorrecto | Usar apk info -W sobre el módulo instalado |
Comandos opkg que no funcionan | OpenWrt 25.12 usa apk | Usar apk add, apk del y apk info |
Conclusión
Con un adaptador que OpenWrt no soporta de fábrica, el driver es lo más delicado. En mi caso, el paquete de la comunidad no funcionaba, pero compilar el driver rtw88 con el SDK de la misma versión del router resolvió el problema. Después fueron necesarios dos ajustes de configuración: la ruta de la radio y el país regulatorio.
Si después de esto la conexión es estable, el adaptador puede ser tu WAN y el WiFi integrado puede dar servicio a tu homelab. Si tenés dudas o te aparece un error que no está en la tabla, dejalo en los comentarios con la salida de logread y lo revisamos.
📢 ¡Sumate a nuestra comunidad!
Si no querés perderte ninguna de nuestras guías prácticas, tutoriales de SysAdmin y novedades de tecnología, te invitamos a seguirnos en todos nuestros canales:
- YouTube: Suscribite a Apuntes IT y activá la campanita para apoyarnos y ver los videos antes que nadie.
- Redes Sociales: Seguinos para contenido diario y tips rápidos en LinkedIn, X (Twitter) e Instagram.
- El Blog: Guardá apuntesit.com en tus marcadores para tener siempre a mano nuestro repositorio técnico de comandos.
Trabajando desde el año 1990 en el mercado de la tecnología. Técnico en Electrónica. Administrador de Sistemas. Administrador de Redes. Técnico en telecomunicaciones. Técnico de plataforma satelital. Incursiono en el Software Libre desde mediados del 1997. Desde entonces utilicé varias distribuciones GNU/Linux comenzando con un RedHat 5.0
Formé parte del Core Team y miembro del grupo de desarrollo del Proyecto UTUTO.








