Instalar un observer para el Hub de Mesh Galicia

Un observer escucha el tráfico MeshCore recibido por una radio y envía al Hub de Mesh Galicia los paquetes y el estado del dispositivo. El Hub permite reunir observaciones propias e incorporarlas después al mapa de Mesh Noroeste.

Los tres métodos escuchan la misma red de radio y publican en el mismo Hub. La diferencia está en el firmware utilizado y en dónde se ejecuta el puente entre LoRa y MQTT.

Para este método Mesh Galicia publica una compilación experimental basada en Offband v1.3.0. Está pensada para dejar una Heltec encendida de forma permanente, conectada porWi-Fi y enviando al Hub de Mesh Galicia los paquetes MeshCore que recibe por LoRa.

La aplicación MeshCore se utiliza para la configuración inicial y para revisar el dispositivo. Después no es necesario dejar el móvil, Bluetooth, un ordenador o una Raspberry Pi conectados al observer.

1. Descarga el firmware de tu placa

Abre el repositorio de Mesh Galicia y entra en la versión publicada. Hay dos carpetas:

heltec-v3/
heltec-v4/

Elige heltec-v3 para una Heltec V3 o heltec-v4 para una Heltec V4.3.

Dentro encontrarás, entre otros, estos dos archivos:

firmware-merged.bin

Para una instalación completa, una placa nueva, una placa que viene de otro firmware o una recuperación.

firmware.bin

Para actualizar una instalación compatible de Offband que ya funciona, sin hacer una instalación completa.

2. Instalación completa desde MeshCore Flasher

Para una placa nueva, una instalación desde otro firmware o una recuperación:

1. Conecta primero una antena adecuada para 868 MHz.
2. Conecta la Heltec al ordenador con un cable USB que admita datos.
3. AbreMeshCore Flasher.
4. En la lista de dispositivos eligeCustom Firmware.
5. Selecciona elfirmware-merged.bincorrespondiente a tu placa.
6. Si quieres una instalación completamente limpia o la placa viene de otro firmware y no necesitas conservar la identidad anterior, activa Erase device. Esta opción borra la identidad y la configuración guardadas.
7. Inicia el flasheo, selecciona el puerto USB de la Heltec cuando lo solicite el navegador y no desconectes la placa hasta que termine.

3. Si se queda en Connecting…

Si el flasher no detecta la placa o queda esperando enConnecting…, entra manualmente en el bootloader:

1. Mantén pulsado PRG/BOOT.
2. Sin soltar PRG/BOOT, pulsa y sueltaRST/RESET.
3. Mantén PRG/BOOT uno o dos segundos más.
4. Suelta PRG/BOOT.
5. Vuelve a seleccionar el puerto USB e inicia de nuevo el flasheo.

Este procedimiento no es necesario siempre: úsalo únicamente cuando la placa no entre automáticamente en modo de programación.

Si el flasheo termina pero la placa no arranca automáticamente, pulsa una vez RST/RESET.

4. Actualizar una instalación existente

Si la placa ya ejecuta una instalación compatible deOffband Companion Observer Wi-Fi y solo quieres actualizar la aplicación, descarga:

firmware.bin

En MeshCore Flasher elige de nuevoCustom Firmware y carga ese archivo. En una actualización normal no actives Erase device: un borrado completo eliminaría la identidad y la configuración guardadas.

Después de la actualización reinicia la placa y comprueba que conserva la conexión Wi-Fi y MQTT.

1. Conecta la Heltec con la aplicación

Después del primer arranque, abre la aplicación MeshCore y conecta por Bluetooth con la Heltec. Elige un nombre claro para poder identificar fácilmente el observer en el Hub.

Bluetooth solo se necesita para configurar o revisar la placa. Cuando termines, el observer funcionará de manera autónoma mediante Wi-Fi.

2. Configura la radio

Aplica el preset Portugal 868. Los valores esperados son:

Frecuencia: 869.618 MHz
Bandwidth: 62.5 kHz
Spreading Factor: 7
Coding Rate: 6

Mantén la repetición desactivada. Un observer debe escuchar y enviar por Internet lo que recibe, no actuar como repeater.

repeat=off

3. Configura la posición

Si el observer va a quedar en un lugar fijo, configura en la aplicación su posición real.

Guardar la posición en la placa no la publica automáticamente en el Hub. Al final de la configuración habrá que enviar un advert del propio nodo que incluya esas coordenadas.

4. Entra en Canales y abre _sys

Los siguientes comandos no se escriben en un terminal del ordenador. En la aplicación MeshCore abreCanales y entra en la conversación de sistema_sys.

Dentro de _sys los comandos se envían como mensajes. Envía siempreun comando cada vez y espera la respuesta antes de escribir el siguiente.

5. Configura el Wi-Fi

En _sys envía estas tres órdenes, una por una:

set wifi.ssid NOMBRE_DE_LA_RED
set wifi.pwd CONTRASEÑA
wifi enable

Sustituye NOMBRE_DE_LA_RED yCONTRASEÑA por los datos reales de tu red Wi-Fi.

Algunas respuestas pueden indicarreboot. No reinicies entre comando y comando. Termina primero las tres órdenes y después pulsauna sola vez RST/RESET.

Espera a que la placa arranque, vuelve a conectarla con la aplicación y abre de nuevo Canales → _sys. Comprueba:

wifi status

Debe indicar que el Wi-Fi está conectado y mostrar una dirección IP.

6. Configura el MQTT de Mesh Galicia

Primero consulta los slots MQTT existentes:

mqtt status

Los siguientes ejemplos utilizan el slot 5. Si ese slot está ocupado por una configuración que quieres conservar, elige otro número y sustituye el 5 por el mismo número en todas las órdenes.

En Canales → _sys, envía uno por uno:

set mqtt.broker.5.url wss://mqtt.mesh.gal:443/
set mqtt.broker.5.transport wss
set mqtt.broker.5.port 443
set mqtt.broker.5.auth_type jwt
set mqtt.broker.5.jwt_audience mqtt.mesh.gal
set mqtt.broker.5.iata_override GAL
set mqtt.broker.5.ca_cert letsencrypt

Si alguna respuesta pide reiniciar, continúa hasta completar este bloque. No es necesario reiniciar entre cada orden.

Revisa antes de activar:

mqtt view 5

Ahora activa el slot y comprueba su estado:

mqtt enable 5
mqtt status

Un estado correcto debe mostrar el slot habilitado, transportewss/jwt ystate=up. Si la conexión está estable, normalmente también mostraráretries=0.

Cuando termines todos los comandos MQTT, pulsa una vez RST/RESET. Espera a que la placa arranque de nuevo.

7. Publica la posición con un advert

Si configuraste una posición fija, vuelve a la aplicación MeshCore y utiliza la opción de enviar un advert del propio nodo.

El advert debe enviarse después de guardar la posición. Cuando el Hub reciba ese anuncio con las coordenadas, podrá asociar la ubicación al observer.

No es necesario dejar adverts automáticos frecuentes. Este advert sirve para publicar la identidad y la posición del observer.

8. Comprueba que todo funciona

Vuelve a Canales → _sys y comprueba:

wifi status
mqtt status

La publicación periódica destatus confirma que funcionan el Wi-Fi y MQTT. Cuando exista tráfico LoRa real, la llegada depackets confirma la cadena completa:

LoRa → Heltec → Wi-Fi → MQTT → Hub

Puede pasar un tiempo hasta que la radio reciba el primer paquete. No concluyas que el observer no funciona simplemente porque no aparezca tráfico inmediatamente.

Si la placa se bloquea

Si deja de responder durante la configuración, espera unos segundos y pulsa una vez RST/RESET. El reset reinicia la placa pero no debería borrar la configuración guardada.

Si sigue sin arrancar o no puede ser detectada para reflashear, utiliza el procedimiento PRG/BOOT + RST/RESETexplicado en la sección anterior y, si necesitas una recuperación completa, instala de nuevofirmware-merged.bin.

Otra opción es el firmware MQTT Observer publicado por Gessaman. El flasher permite preparar un Repeater o un Room Server y configurar después radio, Wi-Fi y MQTT desde un asistente web, sin necesitar una Raspberry Pi.

1. Flashea el dispositivo

1. Conecta primero una antena adecuada para 868 MHz.
2. Conecta la placa al ordenador mediante USB.
3. Abre el flasher de Gessaman.
4. Elige el modelo exacto de la placa.
5. Elige Room Server si quieres que el mismo nodo ofrezca además una sala con historial, oRepeater si prefieres ese rol.
6. Si buscas un observer listen-only, la repetición se desactivará posteriormente en la configuración.
7. Para una instalación limpia desde otro firmware, utiliza la opción de borrado completo cuando corresponda.
8. Inicia el flasheo y espera a que termine.

Si la placa queda esperando enConnecting…, utiliza el mismo procedimiento PRG/BOOT + RST/RESET explicado para Offband.

2. Configura primero radio y rol

Después del flasheo entra en Configure via USB y selecciona manualmente el preset Portugal 868. Comprueba:

Frecuencia: 869.618 MHz
Bandwidth: 62.5 kHz
Spreading Factor: 7
Coding Rate: 6

Para un observer que no deba retransmitir tráfico, dejaRepeat desactivado. En la pantalla de resumen debe aparecer:

Repeat: off (listen-only)

Si elegiste Room Server, ese nodo será la propia sala. El Room Server y el observer son funciones diferentes: puede almacenar mensajes de su sala y, al mismo tiempo, publicar en el Hub los paquetes LoRa que recibe.

3. Protege la administración

Configura una Admin password propia antes de dejar el nodo en servicio. No reutilices la clave del Wi-Fi ni publiques esta contraseña.

Si utilizas el Room Server también puedes definir la credencial de acceso de invitado que corresponda a la sala.

4. Conéctate al hotspot de configuración

Después del primer arranque, el firmware crea temporalmente una red Wi-Fi propia para completar la configuración. Elnombre exacto de la red aparece en la pantalla de la Heltec y tendrá un formato similar a:

MeshCore-Setup-XXXX

1. En el móvil u ordenador abre la lista de redes Wi-Fi disponibles.
2. Busca la red MeshCore-Setup-XXXXque aparece en la pantalla de tu placa.
3. Conéctate a esa red.
4. Es normal que el sistema indique«sin Internet»: esta red sirve únicamente para configurar el nodo.
5. Si el móvil pregunta si quieres cambiar a otra Wi-Fi o utilizar los datos móviles porque esta red no tiene Internet,mantén la conexión con MeshCore-Setup.

El portal de configuración suele abrirse automáticamente como portal cautivo. Si no aparece, abre un navegador mientras continúas conectado al hotspot y entra manualmente en:

http://192.168.4.1

5. Completa la Web config

En el asistente introduce primero la red Wi-Fi a la que quedará conectado el observer y elige un nombre claro para identificarlo.

Cuando llegues a la configuración MQTT, utiliza estos valores para Mesh Galicia:

IATA region code

GAL

Owner public key

Opcional. Puede quedar vacío si no lo necesitas.

Owner email

Opcional. Puede quedar vacío.

Admin password

Establece una contraseña propia para proteger la administración del nodo. No reutilices la clave del Wi-Fi.

Configura el Slot 1 para Mesh Galicia

En el primer slot MQTT seleccionacustom y completa:

Preset: custom
Username: vacío
Password: vacío
Server host: mqtt.mesh.gal
Port: 443
Topic template: meshcore/{iata}/{device}/{type}
JWT audience: mqtt.mesh.gal

En Packet types puedes seleccionar los tipos que quieres publicar. Para un observer completo recomendamos dejar seleccionados todos los tipos disponibles.

El firmware también publica información de estado y vecindad según su funcionamiento interno; las casillas de Packet types controlan los tipos de paquetes observados que se envían.

Desactiva los brokers que no utilices

El firmware ofrece varios slots MQTT. Si solo quieres enviar información al Hub de Mesh Galicia, abre el desplegablePreset de cada slot adicional y seleccionaNONE.

Slot 1: custom → mqtt.mesh.gal
Slot 2: NONE
Slots adicionales: NONE

De esta forma la prueba queda limitada al broker de Mesh Galicia y no envías simultáneamente las recepciones a otros servicios configurados por defecto.

6. Guarda y reinicia

Revisa el resumen antes de continuar. Para un Room Server utilizado como observer listen-only esperamos, como mínimo:

Radio: Portugal 868
Repeat: off (listen-only)
IATA: GAL
Slot 1: custom
mqtt.mesh.gal:443
JWT audience: mqtt.mesh.gal

Pulsa Save & reboot y espera el reinicio de la placa. El nodo debería conectarse al Wi-Fi y empezar a publicar su estado en el broker.

7. Comprueba tráfico real

Que el Hub muestre el nodo como observer confirma la conexión con la infraestructura, pero la prueba completa requiere que reciba tráfico LoRa de otro nodo. Un advert manual próximo es una forma sencilla de provocar una recepción de prueba.

Cuando el Hub atribuya esa recepción al nuevo observer queda validada la cadena completa:

LoRa → Heltec → Wi-Fi → MQTT → Hub

La ruta recomendada es una instalación administrada como serviciosystemd en Linux. El mismo procedimiento sirve para una Raspberry Pi con un sistema Linux compatible.

MeshCore Packet Capture publica un instalador administrado que descarga la versión publicada, crea el usuario de servicio, instala el programa bajo /opt y escribe la configuración bajo/etc.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/install.sh)"

En el menú Installation Method, selecciona:

1) System service (systemd/launchd)

En Linux se instalará el servicio:

meshcore-packet-capture.service

El instalador también ofrece Docker, pero esta guía recomienda el servicio nativo porque facilita el acceso a BLE y a los dispositivos serie.

En el menú Device Connection Configuration, selecciona la conexión que existe realmente entre el ordenador y la radio Companion.

En el menú MQTT Broker Configuration, selecciona:

2) Import a preset from a URL or local path

Introduce el preset público de Mesh Galicia:

https://mesh.gal/config/meshcore-galicia.toml

El preset configura el servidor, WebSocket, TLS, autenticación y los temas de publicación. Es público y no contiene contraseñas ni claves privadas.

Cuando el instalador solicite el código IATA de tres letras, utiliza:

GAL

El validador puede advertir que no reconoceGAL como código IATA. En ese caso selecciona Y para utilizarlo sin validación: es el identificador territorial acordado para el Hub de Mesh Galicia.

Los temas publicados seguirán esta estructura:

meshcore/GAL/<CLAVE_PUBLICA>/status
meshcore/GAL/<CLAVE_PUBLICA>/packets

La clave pública del propietario y el correo electrónico son opcionales. Puedes dejarlos vacíos durante la primera instalación y configurarlos más adelante.

Configuración principal

/etc/meshcore-packet-capture/config.toml

Directorio adicional

/etc/meshcore-packet-capture/config.d/

Preset de Mesh Galicia

/etc/meshcore-packet-capture/config.d/10-meshcore-galicia.toml

Opciones locales

/etc/meshcore-packet-capture/config.d/99-user.toml

Comprueba que el servicio está habilitado y activo:

sudo systemctl is-enabled meshcore-packet-capture.service
sudo systemctl is-active meshcore-packet-capture.service

Consulta el estado detallado:

sudo systemctl --no-pager --full status meshcore-packet-capture.service

Consulta los últimos registros:

sudo journalctl \
  --unit meshcore-packet-capture.service \
  --no-pager \
  --lines 100

Para seguirlos en tiempo real:

sudo journalctl \
  --unit meshcore-packet-capture.service \
  --follow

Mantén esta comprobación abierta durante la primera prueba y espera a que aparezcan la conexión con la radio, la conexión con el broker y la publicación de estado o paquetes.

Los registros deben permitir comprobar la conexión con la radio, el inicio de la captura, la conexión con el broker y la publicación de estado o paquetes. Los mensajes literales pueden cambiar entre versiones.

Deja que la radio reciba anuncios u otros paquetes MeshCore y comprueba primero la llegada de información al Hub. El mapa los incorpora posteriormente en sus ciclos de recogida y publicación, por lo que la aparición no tiene que ser inmediata.

Después prueba el arranque automático:

sudo reboot

Al volver a conectar con el equipo:

sudo systemctl is-enabled meshcore-packet-capture.service
sudo systemctl is-active meshcore-packet-capture.service
sudo journalctl \
  --unit meshcore-packet-capture.service \
  --boot \
  --no-pager \
  --lines 100

El resultado esperado de las dos primeras comprobaciones esenabled yactive.

Reiniciar después de un cambio

sudo systemctl restart meshcore-packet-capture.service
sudo systemctl --no-pager --full status meshcore-packet-capture.service

Actualizar o reconfigurar

Vuelve a ejecutar el instalador oficial. Antes de aceptar los cambios, comprueba que detecta la instalación existente y conserva/etc/meshcore-packet-capture/.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/install.sh)"

Desinstalar

Conserva antes una copia de la configuración cuando pueda ser necesaria para reinstalar el observer.

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/uninstall.sh)"

Comprobar los archivos del preset

sudo find /etc/meshcore-packet-capture/config.d \
  -maxdepth 1 \
  -type f \
  -name '*.toml' \
  -print

Comprobar que el preset público está accesible

curl \
  --fail \
  --location \
  --silent \
  --show-error \
  https://mesh.gal/config/meshcore-galicia.toml

• La radio utiliza firmware Companion.
• La conexión BLE, serie o TCP funciona.
• El preset de Mesh Galicia está instalado.
• El código territorial configurado es GAL.
• El servicio está habilitado y activo.
• Los registros confirman la conexión MQTT.
• El Hub recibe tráfico de la radio y la identifica como observer.
• Si se quiere publicar la posición, el nodo emitió un advert que la incluye.
• El servicio recupera la conexión tras reiniciarlo.
• El observer vuelve a funcionar después de reiniciar el equipo.
• La aparición posterior en el mapa fue comprobada cuando hubo tráfico útil.