De una tarjeta vacía a una red que habla.

00 · Antes de tocar nada

Vamos a construirlo entendiendo cada pieza.

No hace falta ser informático, electrónico ni experto en radio. La ruta está pensada para que distintas personas del Circular FAB puedan colaborar, dejar evidencia y continuar el trabajo de otra persona.

Un equipo multidisciplinar, tres miradas

01 · Conocer el gateway

Preparar el gateway sin adivinar.

El equipo del piloto no es una caja misteriosa: es un pequeño ordenador con un oído de radio especializado. Antes de instalar nada, vamos a reconocerlo.

hostnamectl
timedatectl status
ip -brief address
getent hosts deb.debian.org
ls -l /dev/spidev*

Referencia técnica genérica: HAL oficial SX1302/SX1303 y packet forwarder.

02 · Crear la microSD

Instalar Raspberry Pi OS desde una tarjeta vacía.

La microSD es el disco duro del gateway. “Grabar una imagen” significa copiar en ella un sistema operativo completo y arrancable.

1. Descarga Raspberry Pi Imager. Hazlo desde la web oficial de Raspberry Pi e instálalo en el ordenador.
2. Conecta la microSD. Comprueba su capacidad. Desconecta otros discos externos para que sea más difícil equivocarse.
3. Elige el dispositivo. Selecciona Raspberry Pi 4.
4. Elige el sistema. Selecciona Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit). “Lite” no tiene escritorio: consume menos y se administra por red.
5. Elige el almacenamiento. Señala únicamente la microSD. Imager va a borrar por completo el dispositivo seleccionado.
6. Abre la personalización. Define lorafab-sede como patrón de nombre, sustituyendo sede por una palabra corta y única. Crea un usuario nominal y una contraseña larga.
7. Configura la red. Si usarás Ethernet, no necesitas guardar Wi-Fi. Si es imprescindible, añade SSID, contraseña y país ES sin documentar esas credenciales.
8. Activa SSH. Preferiblemente con clave pública. Si el equipo aún no usa claves, permite contraseña solo durante el taller y planifica el cambio.
9. Ajusta idioma y hora. Zona horaria Europe/Madrid y teclado correspondiente al equipo.
10. Escribe y verifica. Confirma el borrado, espera la escritura y deja que Imager complete su verificación. Expulsa la tarjeta de forma segura.

Guía oficial: instalación con Raspberry Pi Imager.

03 · Montaje seguro

Montar el “sándwich” de ordenador y radio.

Si el gateway ya está ensamblado, no lo desmontes: inspecciona visualmente y continúa. Si las piezas están separadas, trabaja sobre una mesa limpia, sin alimentación y sin forzar conectores.

04 · Primer arranque

Entrar en la Raspberry Pi y comprobar que está sana.

SSH permite usar la Raspberry desde otro ordenador. Verás una terminal: una conversación de texto donde escribimos una orden y el sistema responde.

1. Espera el primer arranque. Conecta la alimentación y espera dos o tres minutos. No retires la corriente durante esta preparación inicial.
2. Localiza el equipo. Desde otro ordenador prueba ping lorafab-sede.local. Si no responde, busca la dirección IP en el router o conecta monitor.
3. Entra por SSH. Usa el usuario creado en Imager: ssh TU_USUARIO@lorafab-sede.local. Acepta la huella solo si estás en la red correcta.
4. Actualiza la lista de software. Ejecuta los comandos del bloque siguiente. Puede tardar; lee cualquier pregunta antes de responder.
5. Abre la configuración. En raspi-config activa SPI e I²C. En Serial, desactiva la consola de login y activa el hardware del puerto serie.
6. Reinicia de forma limpia. Usa sudo reboot, espera y vuelve a entrar por SSH.

sudo apt update
sudo apt full-upgrade -y
sudo raspi-config
sudo reboot

hostnamectl
timedatectl status
ip -brief address
getent hosts deb.debian.org
ls -l /dev/spidev*

05 · Cómo viaja el dato

Entender la ruta antes de instalarla.

El mismo kit puede servir como laboratorio autocontenido o como gateway de una red territorial. La decisión cambia dónde viven ChirpStack, MQTT y las copias.

06 · Software del gateway

Enseñar a la Raspberry Pi a usar el concentrador SX130x.

Instalaremos la capa HAL y el packet forwarder de referencia para SX1302/SX1303. La HAL permite que Linux hable con el chip; el packet forwarder toma las tramas escuchadas y las entrega por red al Gateway Bridge.

sudo apt update
sudo apt install git build-essential pkg-config libusb-1.0-0-dev -y
git clone https://github.com/Lora-net/sx1302_hal.git ~/sx1302_hal
cd ~/sx1302_hal
make -j2

1. Confirma que la compilación termina. La última parte no debe contener Error. Si falla, conserva desde la primera línea roja y no continúes.
2. Elige la configuración física correcta. Dentro de packet_forwarder parte del ejemplo EU868 que coincida con interfaz, radios y reloj de la placa. Copiar un archivo “parecido” puede permitir arrancar y aun así medir o transmitir mal.
3. Configura el reset. Ajusta reset_lgw.sh a los pines documentados del HAT. El concentrador debe reiniciarse antes de abrir la HAL.
4. Define una identidad estable. Escribe un Gateway EUI único de 16 caracteres hexadecimales en local_conf.json y en el inventario. Nunca reutilices el de otra sede.
5. Indica el destino. En el laboratorio todo-en-uno usa 127.0.0.1 y los puertos 1700. Si ChirpStack vive en otro servidor, usa su IP fija.
6. Prueba en primer plano. Arranca manualmente; observa la detección del SX1302/SX1303, la región EU868 y los mensajes PUSH_DATA/PULL_DATA antes de crear un servicio automático.

{
  "gateway_conf": {
    "gateway_ID": "REEMPLAZAR_POR_16_HEX",
    "server_address": "127.0.0.1",
    "serv_port_up": 1700,
    "serv_port_down": 1700
  }
}

cd ~/sx1302_hal/packet_forwarder
sudo ./lora_pkt_fwd -c global_conf.json

Código y esquema de referencia: SX1302/SX1303 Hardware Abstraction Layer. La configuración física debe corresponder al HAT concreto.

07 · Instalar ChirpStack

Crear la oficina de correos de la red.

Para aprender, instalaremos todos los servicios en la misma Raspberry Pi. Más adelante ChirpStack puede vivir en un servidor central y el gateway permanecer en cada sede.

7.1 · Instalar las dependencias

sudo apt update
sudo apt install mosquitto mosquitto-clients redis-server redis-tools postgresql -y
sudo systemctl enable --now mosquitto redis-server postgresql

7.2 · Crear la base de datos

sudo -u postgres psql
CREATE ROLE chirpstack WITH LOGIN PASSWORD 'CAMBIAR_ESTA_CONTRASENA';
CREATE DATABASE chirpstack WITH OWNER chirpstack;
\c chirpstack
CREATE EXTENSION pg_trgm;
\q

7.3 · Añadir el repositorio oficial

sudo apt install gpg wget -y
sudo mkdir -p /etc/apt/keyrings
sudo sh -c 'wget -q -O - https://artifacts.chirpstack.io/packages/chirpstack.key | gpg --dearmor > /etc/apt/keyrings/chirpstack.gpg'
sudo nano /etc/apt/sources.list.d/chirpstack.sources

Dentro de nano, pega estas cinco líneas. Guarda con Ctrl+O, Enter, y sal con Ctrl+X.

Types: deb
URIs: https://artifacts.chirpstack.io/packages/4.x/deb
Suites: stable
Components: main
Signed-By: /etc/apt/keyrings/chirpstack.gpg

7.4 · Instalar y configurar Gateway Bridge

sudo apt update
sudo apt install chirpstack-gateway-bridge -y
sudo nano /etc/chirpstack-gateway-bridge/chirpstack-gateway-bridge.toml

En la sección MQTT, confirma que los tópicos empiezan por eu868. No borres las demás opciones del archivo.

[integration.mqtt]
event_topic_template="eu868/gateway/{{ .GatewayID }}/event/{{ .EventType }}"
command_topic_template="eu868/gateway/{{ .GatewayID }}/command/#"

7.5 · Instalar el servidor

sudo apt install chirpstack -y
sudo nano /etc/chirpstack/chirpstack.toml

En chirpstack.toml, activa únicamente EU868 y usa la misma contraseña de PostgreSQL. Conserva el resto de la configuración generada.

enabled_regions=["eu868"]

[postgresql]
dsn="postgres://chirpstack:CAMBIAR_ESTA_CONTRASENA@localhost/chirpstack?sslmode=disable"

sudo systemctl enable --now chirpstack-gateway-bridge chirpstack
systemctl --failed
systemctl status chirpstack-gateway-bridge chirpstack --no-pager
mosquitto_sub -v -t "+/gateway/#"

Procedimiento base contrastado con la instalación oficial de ChirpStack 4 en Debian/Ubuntu.

08 · Enlazar el gateway

Hacer que el gateway aparezca en ChirpStack.

Ahora conectaremos la identidad guardada en el paso 06 con la interfaz web del servidor. Copiar exactamente el Gateway EUI es más importante que memorizarlo.

1. Abre la interfaz. Desde un ordenador de la misma red visita http://IP_DE_LA_RASPBERRY:8080.
2. Entra por primera vez. La instalación inicial usa admin / admin. Cambia esa contraseña inmediatamente y guárdala de forma segura.
3. Crea una organización de trabajo. Usa nombres que cualquier persona reconozca: por ejemplo, tenant Circular FAB y ubicación Sede piloto.
4. Añade el gateway. Copia el Gateway EUI exacto que guardaste en local_conf.json y en el inventario, selecciona EU868 y escribe una descripción física útil.
5. Espera una señal. Abre el gateway y observa Last seen at. Normalmente se actualiza en menos de un minuto si ya hay tráfico de estadísticas.
6. Mira las tramas. La pestaña de frames LoRaWAN permite distinguir que la radio escucha, incluso antes de registrar un dispositivo.

sudo tcpdump -ni any udp port 1700
sudo journalctl -f -u chirpstack-gateway-bridge

Comprobación oficial: conectar y validar un gateway.

09 · Operación

Mantener es parte de instalar.

La sede se considera sostenible cuando otra persona puede comprobarla, reiniciarla y restaurarla siguiendo este manual.

systemctl --failed
systemctl status chirpstack-gateway-bridge --no-pager
journalctl -u chirpstack-gateway-bridge -n 80 --no-pager

10 · Primer nodo Heltec

Preparar un Heltec V3 y ver su primer “hola”.

El Heltec WiFi LoRa 32 V3 combina un microcontrolador ESP32-S3, una radio SX1262, pantalla OLED y USB-C. Empezaremos con uno solo; cuando funcione, repetiremos con los otros tres.

10.1 · Preparar Arduino IDE

1. Instala Arduino IDE. Descárgalo desde su web oficial y abre File/Archivo → Preferences/Preferencias.
2. Añade el índice de Heltec. En “Additional Boards Manager URLs” pega https://resource.heltec.cn/download/package_heltec_esp32_index.json.
3. Instala la placa. Abre Boards Manager, busca heltec esp32 e instala el paquete.
4. Instala la biblioteca. En Library Manager busca HELTEC ESP32.
5. Conecta el nodo. Usa un cable USB-C de datos; algunos cables solo cargan y el ordenador no verá la placa.
6. Selecciona modelo y puerto. Elige exactamente WiFi LoRa 32 (V3) y el puerto que aparece al conectar la placa.

10.2 · Crear las identidades OTAA

Guías oficiales: preparar Heltec ESP32 y conexión LoRaWAN.

11 · Laboratorio

Experimentos que el equipo puede crear.

Cada experimento empieza con una pregunta, modifica una sola variable y termina con una evidencia. Así pueden participar diseño, territorio, electrónica, datos, educación y comunicación sin confundir demostración con resultado científico.

12 · Aceptación

Definición verificable de terminado.

Marca la lista durante la intervención. Se guarda únicamente en este navegador; no sustituye el acta de aceptación del proyecto.

13 · Diagnóstico

Encontrar la capa que falla.

Empieza por lo físico y avanza en una sola dirección. Cambiar varias capas a la vez destruye la evidencia necesaria para aislar el problema.

Glosario · Palabras sin misterio

Traducir el idioma técnico.