Manual de uso de Yubox Gateway OS

¿Qué es Yubox Gateway OS?

Yubox Gateway OS es una imagen de sistema operativo basada en Raspberry Pi OS que convierte una Raspberry Pi con un HAT concentrador LoRaWAN en un gateway completo y listo para producción. Se graba en una microSD, se arranca la Raspberry Pi y todo lo demás — driver del concentrador, packet forwarder, conexión al Network Server — ya viene instalado y compilado.

Toda la configuración se hace con yubox-tool, una herramienta de menús que corre en la terminal del gateway (por SSH o con teclado y monitor). Desde ella puedes ver el estado, ejecutar un diagnóstico completo, conectar el gateway a tu red WiFi, elegir la región y sub-banda LoRaWAN, y configurar la conexión al Network Server.

La misma imagen incluye cuatro métodos de conexión al Network Server, y puedes cambiar de uno a otro cuando quieras:

Solo un método queda activo a la vez: al aplicar uno, la herramienta detiene y deshabilita los demás automáticamente.

Si todavía no tienes la imagen, solicítala en la página de descarga de Yubox Gateway OS.

Hardware necesario

• Raspberry Pi 4 o 3B+, con fuente de 5 V / 3 A y una microSD de 16 GB o más (clase A1/A2 recomendada).
• HAT concentrador LoRaWAN conectado por SPI: RAK2287 (SX1302), Semtech CoreCell o equivalente, montado sobre su Pi HAT.
• Antena LoRa de tu banda (915 MHz en gran parte de América, 868 MHz en Europa), conectada al concentrador antes de encender.

¿Prefieres un equipo ya armado, para exteriores y con garantía? Mira el Gateway LoRaWAN de Yubox.

Grabar la imagen en la microSD

El archivo que recibes por correo es una imagen comprimida (yubox-<REGION>-<fecha>-....img.xz). No hace falta descomprimirla: las herramientas de grabado la aceptan tal cual.

1. Descarga e instala Raspberry Pi Imager (o Balena Etcher).
2. En Imager elige Usar imagen personalizada y selecciona el archivo .img.xz.
3. En las opciones avanzadas de personalización (ícono de engranaje o Ctrl+Shift+X) define tu usuario y contraseña. La imagen no trae usuarios por defecto, por seguridad; el que definas aquí será el que uses para entrar por SSH. Puedes activar SSH y precargar tu red WiFi en ese mismo panel.
4. Graba la microSD, insértala en la Raspberry Pi con el HAT y la antena ya montados, y enciende.

El primer arranque

En el primer arranque, el servicio de aprovisionamiento de Yubox Gateway OS configura solo todo lo esencial:

• Genera el Gateway ID (EUI de 64 bits) a partir de la dirección MAC de la Raspberry Pi. Por ejemplo, con la MAC d8:3a:dd:3b:c8:c9 el Gateway ID resultante es D83ADDFFFE3BC8C9. Este es el identificador que registrarás en tu Network Server.
• Escribe la configuración del packet forwarder (servidor, puertos, región de la imagen).
• Configura los pines GPIO de reset del concentrador.
• Levanta el punto de acceso WiFi del gateway (si la imagen lo trae habilitado).
• Arranca el modo de conexión inicial.

Este aprovisionamiento corre una sola vez; si algo queda incompleto (por ejemplo, sin red), se reintenta en el siguiente arranque. Después de uno o dos minutos, el gateway está listo para que te conectes.

Acceder al gateway

Tienes tres caminos, en orden de comodidad:

1. Por el punto de acceso WiFi del gateway. La imagen levanta una red WiFi propia cuyo nombre termina en los últimos 6 dígitos de la MAC, por ejemplo Yubox-Gateway-3bc8c9 (contraseña por defecto yubox1234, salvo que tu imagen se haya generado con otra). Conéctate a esa red y entra por SSH a la IP fija del gateway:

ssh tu_usuario@192.168.4.1

2. Por cable Ethernet. Conecta el gateway a tu router, averigua la IP que le asignó (en la lista de clientes del router) y entra por SSH a esa IP.

3. Con monitor y teclado conectados directamente a la Raspberry Pi.

La herramienta yubox-tool

Ya dentro del gateway, ejecuta:

sudo yubox-tool

Las opciones de solo lectura (1 y 2) funcionan sin privilegios, pero las de configuración exigen sudo, así que lo más simple es ejecutarla siempre como sudo yubox-tool.

Ver estado del gateway

La opción 1 muestra el resumen del gateway en una sola pantalla:

• Gateway ID — el EUI que debes registrar en el Network Server.
• Región y destino del packet forwarder.
• Conexión activa y destino remoto — el método en uso y a qué servidor apunta.
• El estado (RUNNING, STOPPED, FAILED) de cada servicio: packet forwarder, MQTT Forwarder (v4), Gateway Bridge (v3), Basics Station y el punto de acceso WiFi.

Ten en cuenta que en cada modo lo normal es que solo el servicio de ese modo esté en RUNNING y el resto aparezca STOPPED. El mismo resumen está disponible desde la línea de comandos con yubox-status.

Diagnóstico completo

La opción 2 ejecuta un chequeo de extremo a extremo y clasifica cada punto como [OK], [!!] (problema) o [--] (aún sin datos):

Qué revisa:

• Reloj (NTP). Sin hora correcta, las conexiones TLS fallan. Es lo primero que se comprueba.
• Concentrador. Si el chip SX1302 arrancó. Si no arranca, casi siempre es el GPIO de reset equivocado para tu placa (ver Placa / HAT) o el HAT mal asentado.
• Proceso de radio. Que el servicio correcto para el modo activo esté corriendo (y que no haya dos peleando por el concentrador).
• Conexión al servidor. Según el modo: en MQTT, si se conectó al broker o si este rechazó las credenciales; en Basics Station, si el LNS aceptó la conexión y ya envió el plan de canales, o si respondió 401/403 (credenciales o EUI sin registrar).
• Región, sub-banda y Gateway ID, con un recordatorio de dónde debe estar registrado ese ID.

Conectar el gateway a una red WiFi

La opción 3 pasa la antena WiFi de modo punto de acceso a modo cliente, para que el gateway salga a Internet por tu red:

1. La herramienta escanea las redes al alcance y te muestra la lista.
2. Eliges la red y escribes la contraseña (si la dejas vacía, te pregunta si es una red abierta).
3. El gateway se conecta y obtiene IP por DHCP.

Si el gateway va conectado por cable Ethernet, este paso no es necesario.

Configurar la radio: región LoRaWAN

La opción 4 configura todo lo relacionado con la radio. El asistente pregunta, en orden: región, placa/HAT, sub-banda (solo US915/AU915) y Gateway ID.

Las regiones disponibles son AU915, US915, EU868 y AS923. Debe coincidir con la banda de tu antena, la regulación de tu país y la región configurada en tu Network Server. En Ecuador y Brasil se usa AU915.

Placa / HAT del concentrador

Este paso define el GPIO con el que se resetea el concentrador, y es el error de configuración más común: con el pin equivocado, la radio simplemente no inicia.

Sub-banda (solo US915 y AU915)

Las regiones US915 y AU915 tienen 64 canales, pero un gateway de 8 canales escucha solo una sub-banda de 8. El asistente muestra las ocho con su rango de frecuencias:

La sub-banda debe coincidir con el id de región de tu ChirpStack (por ejemplo au915_1) y con la sub-banda en la que transmiten tus dispositivos. En TTN, el equivalente es el FSB del frequency plan (AU915 usa típicamente FSB 2, que corresponde a au915_1). Si el gateway escucha en una sub-banda y los sensores transmiten en otra, no llegará ningún paquete.

Gateway ID y GPIO de power

Gateway ID. El asistente muestra el EUI actual (derivado de la MAC en el primer arranque). Déjalo tal cual salvo que tu Network Server te exija uno específico; si lo cambias, deben ser exactamente 16 dígitos hexadecimales.

GPIO PWR (avanzado). Algunas placas tienen un pin adicional de habilitación de energía. La mayoría — incluido el RAK2287 — no lo usa, así que responde que no cuando el asistente pregunte; el valor queda en none.

Al confirmar, la herramienta regenera la configuración de radio, ajusta los servicios y reinicia la conexión con el Network Server. El cambio es inmediato, sin reiniciar el gateway.

Conexión al Network Server: elegir el método

La opción 5 configura cómo entrega el gateway los paquetes a tu Network Server:

¿Cuál elegir?

• Semtech UDP directo — el clásico y el más simple. Funciona con ChirpStack v3/v4 y con la red IoTodos de Yubox. No cifra el enlace con el servidor.
• ChirpStack MQTT seguro (TLS) — para servidores ChirpStack propios cuando quieres el enlace cifrado y autenticado.
• LoRa Basics Station — el estándar moderno (WebSocket con TLS). Es el método para The Things Network, AWS IoT Core, Actility y similares.

Si la nueva configuración no se puede aplicar, la herramienta restaura automáticamente la anterior: el gateway nunca queda a medio configurar.

Semtech UDP directo

El asistente pide tres datos:

• Servidor — hostname o IP de tu Network Server (por ejemplo, tu ChirpStack).
• Puerto UDP upstream y downstream — normalmente 1700 ambos.

Después registra el Gateway ID en el servidor (en ChirpStack: Gateways → Add gateway). UDP no confirma la entrega: si el gateway no está registrado, los paquetes se descartan en silencio y el gateway aparece como “nunca visto” — el enlace se verifica en la consola del servidor, no en el gateway.

ChirpStack MQTT seguro (TLS)

Para servidores ChirpStack propios. El asistente pregunta primero la versión del servidor:

• v4 — usa el ChirpStack MQTT Forwarder. Pide además el prefijo MQTT exacto de la región, que es el id de la configuración regional de tu servidor (visible en el menú Regions de ChirpStack v4). En US915/AU915 incluye la sub-banda: por ejemplo au915_1, no au915. Un prefijo desalineado hace que el servidor descarte los mensajes en silencio.
• v3 — usa el ChirpStack Gateway Bridge. No hay prefijo regional, pero pide el marshaler (formato de mensajes): json es lo más común en v3. Debe coincidir con el configurado en tu servidor.

Luego pide el broker MQTT y la autenticación:

• Broker remoto: ssl://tu-servidor:8883 (o wss://…), con usuario y contraseña o certificado cliente mTLS. Puedes indicar un archivo CA propio o dejarlo vacío para usar las CA del sistema.
• Si ChirpStack corre en el propio gateway, usa tcp://127.0.0.1:1883 — el tráfico no sale del equipo y no necesita TLS.

Las credenciales quedan protegidas en el gateway (/etc/yubox/backhaul.conf, solo root) y el packet forwarder pasa a entregar los paquetes localmente al componente MQTT, que es quien habla cifrado con tu servidor.

LoRa Basics Station (TTN, AWS y otros)

En este modo, el binario station reemplaza al packet forwarder y habla WebSocket con TLS directamente con el LNS. El asistente empieza recordando la diferencia clave:

1. URI del LNS. Con esquema wss://. Para TTN es el clúster donde registraste el gateway, puerto 8887:

2. Autenticación. Para TTN elige token (API key). AWS IoT Core usa certificado cliente mTLS; algunos LNS privados no piden autenticación de cliente:

3. Archivo CA. Déjalo vacío para usar las CA del sistema — suficiente para TTN, cuyos certificados firma Let’s Encrypt:

4. API key. Pega el token tal cual te lo entregó el servidor. En TTN es el key que empieza con NNSXS. generado al registrar el gateway (con el permiso Link as Gateway):

Al confirmar, la herramienta detiene el packet forwarder, escribe las credenciales y arranca Basics Station. La conexión suele establecerse en menos de diez segundos; verifícala con el diagnóstico. Recuerda que el EUI del gateway debe estar registrado en el LNS: un rechazo por EUI desconocido o key inválido aparece en los logs como 401/403.

Interfaz web

La opción 6 habilita una interfaz web para administrar el gateway desde el navegador: estado, diagnóstico, conexión a WiFi y configuración del Network Server. Por seguridad viene apagada de fábrica y solo existe cuando tú la enciendes:

1. Elige Habilitar. La herramienta pide un usuario (por defecto admin) y una contraseña de al menos 8 caracteres.
2. Se genera un certificado TLS y el servicio queda arrancado y habilitado.
3. Accede desde tu navegador a https://<ip-del-gateway>:8443.

Desde el mismo menú puedes deshabilitarla cuando ya no la necesites; el servicio se detiene y deja de escuchar en la red.

Solución de problemas

Si necesitas más detalle, los registros de cada servicio se consultan con journalctl (ver la referencia siguiente). ¿Sigues trancado? Escríbenos — y si quieres dominar todo el ecosistema con el equipo en la mano, este proceso lo practicamos en vivo en el LoRaWAN Master Training.

Referencia rápida

Comandos útiles (por SSH o consola):

sudo yubox-tool          # la herramienta de configuración (menús)
yubox-status             # estado resumido, en texto plano
yubox-tool diag          # diagnóstico completo, en texto plano

Logs de cada servicio:

sudo journalctl -u yubox-lora-pktfwd -n 50          # packet forwarder (UDP/MQTT)
sudo journalctl -u yubox-basicstation -n 50         # Basics Station
sudo journalctl -u chirpstack-mqtt-forwarder -n 50  # MQTT Forwarder (ChirpStack v4)
sudo journalctl -u chirpstack-gateway-bridge -n 50  # Gateway Bridge (ChirpStack v3)
sudo journalctl -u yubox-web -n 50                  # interfaz web

Archivos de configuración (los escribe yubox-tool; normalmente no hace falta editarlos a mano):

Manual correspondiente a la imagen Yubox Gateway OS de 2026. Las pantallas son del asistente yubox-tool incluido en la imagen. ¿Aún no la tienes? Solicita la descarga gratuita.