Muntar un Observer de MeshCore¶
Què és un Observer?¶
Un Observer és un node MeshCore (repetidor, room server o companion) que escolta el trànsit de la malla propera i reporta el que sent a un broker MQTT per internet. MeshCore Catalunya fa servir les dades dels observers per alimentar el mapa, l'anàlisi de cobertura i l'anàlisi de xarxa a través de CoreScope, el mapa en viu i Beacon. Els observers es poden configurar per compartir només advertisements —just el necessari per aparèixer al mapa— sense exposar el contingut de la resta de trànsit. Pots deixar de compartir dades quan vulguis.
Només dispositius compatibles
El firmware d'observer només està disponible per a dispositius compatibles. Comprova que el teu maquinari ho suporta abans de començar: no tots els dispositius MeshCore suporten el firmware de packet logging que requereix aquesta configuració.
Fes servir mode Repetidor sempre que puguis
No facis servir Room Server tret que tinguis un motiu concret: limita la participació a la malla i no aporta cap avantatge respecte a Repetidor en la majoria d'escenaris. Si no ho tens clar, pregunta a la comunitat abans de continuar.
Tria el teu mètode d'instal·lació¶
Hi ha tres maneres de muntar un Observer:
| Mètode | Millor per a |
|---|---|
| Firmware Observer natiu | Dispositius que suporten el firmware observer MQTT de manera nativa |
| Pont per ordinador (mctomqtt) | Repetidor o room server connectat per USB a una Raspberry Pi o equip Linux |
| Pont Companion | Nodes companion; fa servir un programari de pont diferent |
Estat actual a Catalunya
Mètodes operatius i verificats en producció (27/06/2026): el Mètode 3
(companion / packet-capture) publica a Catalunya per usuari/contrasenya, i el
Mètode 4 (Home Assistant / meshcore-ha) fa el mateix per a nodes ja integrats
a HA — la via recomanada si el node viu a HA per TCP/WiFi. El Mètode 2
(mctomqtt) fa servir la mateixa via i broker (per a repetidors/room servers). El
Mètode 1 (firmware natiu) continua per confirmar: la config documentada fa
servir token Ed25519 (camp audience), que el nostre Mosquitto no fa servir. Un
node natiu sí que pot publicar a l'analitzador global (LetsMesh / mapa oficial),
però per a Catalunya fes servir el Mètode 2, 3 o 4.
Mètode 1: Firmware Observer natiu¶
Pas 1: Descarregar i flashejar el firmware¶
Instal·lació nova¶
Fes servir el MeshCore MQTT Observer Flasher online per trobar, descarregar i flashejar el firmware correcte del teu dispositiu directament des del navegador.
Els fitxers -merged esborren el dispositiu
Els fitxers marcats com a -merged fan un esborrat complet i només són
per a instal·lacions noves. Flashejar un -merged sobre un MeshCore ja
configurat esborra tots els ajustos, claus i configuració. Si actualitzes una
instal·lació existent, fes servir sempre la variant sense -merged.
Actualitzar per OTA¶
Si ja tens MeshCore funcionant, pots actualitzar de manera sense fils amb l'app companion i un navegador en lloc del flasher web i l'USB:
- Descarrega el firmware d'app des de l'Observer Flasher (opció app firmware, no el merged).
- Obre Remote Management a l'app companion: selecciona el teu node i introdueix la contrasenya d'admin.
- Obre la línia de comandes (Command Line) i executa
start ota. - Ves a la pàgina de pujada OTA:
- Si el node no està en Wi-Fi, emet un hotspot
MeshCore-OTA: connecta-t'hi i ves ahttp://192.168.4.1/update. - Si ja està en Wi-Fi, busca la seva IP (a la pantalla del node o a la taula DHCP del
router) i ves a
http://<ip-del-node>/update.
- Si el node no està en Wi-Fi, emet un hotspot
- Puja el fitxer
.bini espera que acabi. - Verifica la versió a Remote Management.
Pas 2: Aplicar els ajustos de Catalunya¶
Amb el firmware instal·lat, obre la línia de comandes a Remote Management i introdueix:
Connexió als brokers:
Verifica el preset de l'analitzador EU
A les xarxes dels EUA el preset és analyzer-us. Per a Europa fes servir la variant
EU; confirma el nom exacte al teu firmware. Aquest preset publica a l'analitzador
global de LetsMesh i al mapa oficial de MeshCore, no al broker de Catalunya.
El broker de Catalunya per firmware natiu (mqtt2) està per confirmar
La configuració documentada del segon broker (mqtt2.server / mqtt2.audience)
fa servir autenticació per token Ed25519, que el nostre Mosquitto no fa servir.
Falta confirmar si el firmware natiu admet a més usuari/contrasenya. Fins a
verificar-ho, per publicar a Catalunya fes servir el
Mètode 2 o el
Mètode 3.
Ajustos restants del node (vàlids en qualsevol cas):
set mqtt.rx on
set mqtt.tx advert
set wifi.ssid la-teva-xarxa-wifi
set wifi.pwd la-teva-contrasenya-wifi
set bridge.enabled on
set flood.advert.interval 72
Wi-Fi sense cometes
Substitueix la-teva-xarxa-wifi i la-teva-contrasenya-wifi per les teves
credencials reals. No les posis entre cometes.
Si aquest node és només observer (no repeteix):
Opcional però recomanat, enllaça l'observer al teu companion (millora l'analítica):
Mètode 2: Pont per ordinador (USB + Raspberry Pi)¶
Aquest és el mètode recomanat i operatiu a Catalunya. Captura el trànsit des d'un
repetidor o room server connectat per USB i el publica al broker de Catalunya
(broker.livemap-meshcorecat.com). Pot publicar a diversos brokers alhora (p. ex.
LetsMesh + Catalunya) sense conflicte.
Requisits¶
- Una Raspberry Pi (Zero 2 / 3 / 4) o un altre Linux/macOS sempre encès.
- Un repetidor o room server MeshCore amb firmware amb packet-logging (Pas 1).
- Connexió USB entre el node i l'equip Linux.
- Python 3.11+.
- Les credencials de publicació de Catalunya (
cat-pub, incloses més avall).
Firmware que NO serveix
El firmware normal de xat no exposa els paquets. Tampoc serveix el fork VBart/MeshCoreTel, que només publica als seus propis brokers.
Pas 1: Firmware compatible¶
La ràdio ha d'exposar els paquets pel port sèrie. Fes servir el MeshCore MQTT Observer Flasher i selecciona la teva placa amb la variant observer / repeater amb packet logging.
- Instal·lació nova: fes servir el fitxer
-merged(esborra tot). - Actualització: fes servir la variant sense
-mergedper no perdre claus ni ajustos.
Pas 2: Preparar la Pi¶
Actualitza i instal·la les dependències base (necessàries per compilar ed25519-orlp
si no hi ha wheel precompilat):
sudo apt update
sudo apt install -y python3 python3-venv python3-dev build-essential
python3 --version # ha de ser 3.11+
Localitza el port sèrie de la ràdio (normalment /dev/ttyUSB0 o /dev/ttyACM0):
Pas 3: Connectar i executar l'instal·lador¶
Amb el node connectat per USB, executa:
L'instal·lador crea un usuari de sistema mctomqtt, instal·la a /opt/mctomqtt/ amb
la config a /etc/mctomqtt/, munta un venv de Python, configura el servei systemd
mctomqtt i et guia per una configuració interactiva (que pots saltar i editar els
fitxers a mà).
Configuració¶
Els presets van a config.d/10-<preset>.toml i els teus ajustos a 99-user.toml.
Pots tenir diversos [[broker]] actius alhora.
config.d/99-user.toml — ajustos generals i port sèrie:
Ajusta el port i l'IATA
Canvia /dev/ttyUSB0 pel port real del Pas 2. iata = "BCN" et fa publicar sota
el prefix de Catalunya; si fas servir un altre codi de la teva zona, avisa'ns per
saber sota quin tòpic buscar-te.
config.d/20-catalunya.toml — broker de Catalunya:
[[broker]]
name = "catalunya"
enabled = true
server = "broker.livemap-meshcorecat.com"
port = 8883
keepalive = 60
qos = 0
retain = true
[broker.tls]
enabled = true
verify = true
[broker.auth]
method = "password"
username = "cat-pub"
password = "CatMesh2026pub"
Sobre la contrasenya
L'usuari cat-pub (contrasenya CatMesh2026pub) és write-only: només publica,
no pot llegir res del broker, per això es pot compartir entre observers.
Alternativa per WebSocket segur
Si el TLS per TCP dona problemes a la teva xarxa, canvia al bloc del broker el port i afegeix el transport, deixant la resta igual:
Publicar també a LetsMesh o altres?
mctomqtt publica a tots els [[broker]] amb enabled = true alhora. Per afegir
LetsMesh es posa un altre bloc amb method = "token" i el seu audience.
Arrencar el servei¶
Hauries de veure el port sèrie obrint-se, paquets arribant de la ràdio i un connect
al broker catalunya sense errors de TLS ni d'auth.
Fins a 5 minuts per aparèixer
Pot trigar uns minuts des que l'observer connecta fins que surt a la llista. El node necessita que se senti un advertisement abans d'aparèixer al mapa, però les dades de paquets ja es registren mentrestant.
Mètode 3: Pont Companion¶
A diferència de repetidors i room servers, els observers companion no requereixen firmware especial: el build companion estàndard ja suporta packet logging. Aquest mètode fa servir un programari de pont diferent a mctomqtt i corre en un equip macOS o Linux connectat al companion per USB, BLE o Wi-Fi.
Requisits¶
- Un equip macOS o Linux (p. ex. Raspberry Pi) amb connexió a internet.
- Un dispositiu companion MeshCore accessible per USB, BLE o Wi-Fi.
Pas 1: Instal·lar Node.js LTS¶
Instal·la NVM i després Node.js LTS:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install --lts
Pas 2: Executar l'instal·lador¶
sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/agessaman/meshcore-packet-capture/main/install.sh)"
Fes servir aquesta sintaxi exacta
L'instal·lador necessita root. Evita bash <(curl ...) (encara que ho posi la guia
original de ChiMesh): amb sudo dona error /dev/fd/63: No such file or directory.
La forma sudo bash -c "$(curl ...)" descarrega l'script com a text dins del procés
root i funciona sempre.
Només per a companion
meshcore-packet-capture és només per a nodes companion. Si tens un repetidor
o room server, fes servir el Mètode 2.
Pas 3: Configurar l'MQTT de Catalunya¶
meshcore-packet-capture suporta autenticació usuari/contrasenya a més del mode
token, així que publica al nostre Mosquitto igual que mctomqtt. La guia original de
ChiMesh mostra els camps Server / Port / Audience perquè el seu broker fa servir
token Ed25519; per a Catalunya no es fa servir Audience: es configura el broker en
mode usuari/contrasenya.
| Ajust | Valor per a Catalunya |
|---|---|
| Server | broker.livemap-meshcorecat.com |
| Port | 8883 (TLS per TCP) |
| TLS | activat |
| Auth | usuari/contrasenya (no token) |
| Usuari | cat-pub |
| Contrasenya | CatMesh2026pub |
| Audience | (buit, no es fa servir) |
| IATA | BCN |
Si prefereixes editar el fitxer, a .env.local (els brokers 1 i 2 solen ser LetsMesh
US/EU, així que Catalunya va com a broker 3):
# MQTT Broker 3 (Catalunya)
PACKETCAPTURE_MQTT3_ENABLED=true
PACKETCAPTURE_MQTT3_SERVER=broker.livemap-meshcorecat.com
PACKETCAPTURE_MQTT3_PORT=8883
PACKETCAPTURE_MQTT3_USE_TLS=true
PACKETCAPTURE_MQTT3_USE_AUTH_TOKEN=false
PACKETCAPTURE_MQTT3_USERNAME=cat-pub
PACKETCAPTURE_MQTT3_PASSWORD=CatMesh2026pub
PACKETCAPTURE_MQTT3_KEEPALIVE=120
Alternativa WSS
Si el TLS per TCP dona problemes, fes servir PACKETCAPTURE_MQTT3_PORT=8084 i
afegeix PACKETCAPTURE_MQTT3_TRANSPORT=websockets.
Verificat en producció (27/06/2026)
USE_AUTH_TOKEN=false és el que evita que esperi l'audience. Les variables
_USERNAME / _PASSWORD estan confirmades: provat al RPi4 amb un observer
publicant a broker.livemap-meshcorecat.com, amb status i packets visibles sota
meshcore/BCN/... i sense errors de TLS ni de token.
Conflicte de port sèrie amb altres serveis (Remote Terminal, etc.)
En un mateix equip, només un procés pot obrir el port sèrie de la ràdio alhora.
Si ja corre un altre servei sobre el mateix node per USB (p. ex. Remote Terminal /
meshcore.service sobre /dev/ttyUSB0), packet-capture en mode serial l'hi
prendrà i l'altre deixarà d'arrencar. No conviuen els dos per sèrie al mateix Pi.
Solucions perquè convisquin (mateix Heltec, dos serveis):
- USB + WiFi (recomanat): deixa un servei per USB sèrie i posa l'altre en
TCP contra el port WiFi del companion (per defecte
5000). Vegeu més avall. - BLE: una de les dues vies per Bluetooth en lloc de sèrie.
- Ràdios separades: un companion per a cada servei.
- ser2net: compartir el mateix sèrie per TCP a diversos clients.
Convivència USB + TCP/WiFi (mateix node)¶
Si el Heltec té WiFi (firmware amb WiFi habilitat), exposa TCP (port 5000).
Configura packet-capture en mode tcp apuntant a la IP del node (posa-li reserva
DHCP al router perquè no canviï), deixant l'USB lliure per a l'altre servei.
Comprova abans que el port respon: nc -vz 192.168.188.XX 5000.
Una sola sessió TCP per node (provat 27/06/2026)
Molts builds del companion accepten una única connexió TCP alhora. Si el node
ja està connectat per TCP a una altra cosa (p. ex. Home Assistant),
packet-capture no pot entrar en paral·lel: es produeix un bucle de reconnexió
cada ~2 s (TCP Connection started repetit) i cap de les dues vies queda estable.
En aquest cas, no facis servir packet-capture sobre aquest node: si el node ja
viu a HA, publica a Catalunya des de HA (vegeu Mètode 4). El mode TCP només
serveix si aquest port del node està lliure.
Format de configuració segons la instal·lació. Hi ha dos esquemes; mira quin fa
servir la teva (el log ho diu en arrencar: Loading config override: ...):
A ~/.meshcore-packet-capture/.env.local:
A /etc/meshcore-packet-capture/config.d/99-user.toml — la clau TCP va
dins de [capture] (no en una secció [tcp] a part):
[capture]
connection_type = "tcp"
tcp_host = "192.168.188.XX"
tcp_port = 5000
advert_interval_hours = 11
#[serial]
#ports = ["/dev/serial/by-id/usb-..."] # comentat: ja no fa servir sèrie
En aquest esquema el broker de Catalunya també va aquí, com a [[broker]]:
La migració no copia els teus brokers custom
En migrar de .env.local a config.d/*.toml, l'instal·lador porta l'IATA i els
presets LetsMesh, però pot deixar enrere brokers afegits a mà (com Catalunya).
Verifica amb grep -i catalunya /etc/meshcore-packet-capture/config.d/99-user.toml;
si no hi és, afegeix-lo com a dalt.
Després de canviar la config: sudo systemctl restart meshcore-packet-capture.service
i al log busca Using connection type: tcp i Connecting via TCP to 192.168.188.XX:5000
(si diu localhost, la clau TCP no s'ha aplicat). Vigila uns minuts que no entri
en bucle de reconnexió.
Pas 4 (opcional): Publicar també a MeshMapper¶
El mateix observer pot publicar alhora a Catalunya, LetsMesh i MeshMapper.
MeshMapper sí que fa servir el broker WebSocket + token Ed25519, així que aquí
sí es fa servir audience (a diferència del broker de Catalunya). És la mateixa
autenticació que ja fan servir els brokers LetsMesh (MQTT1/MQTT2), de manera que si
aquests funcionen, aquest també.
Dades del broker de MeshMapper:
| Ajust | Valor |
|---|---|
| Server | mqtt.meshmapper.net |
| Port | 443 |
| Transport | websockets |
| TLS | activat (verificar certificat) |
| Auth | MeshCore Auth Token (no usuari/contrasenya) |
| Token audience | mqtt.meshmapper.net |
| IATA | BCN |
A .env.local, com a broker 4:
# MQTT Broker 4 - MeshMapper
PACKETCAPTURE_MQTT4_ENABLED=true
PACKETCAPTURE_MQTT4_SERVER=mqtt.meshmapper.net
PACKETCAPTURE_MQTT4_PORT=443
PACKETCAPTURE_MQTT4_TRANSPORT=websockets
PACKETCAPTURE_MQTT4_USE_TLS=true
PACKETCAPTURE_MQTT4_USE_AUTH_TOKEN=true
PACKETCAPTURE_MQTT4_TOKEN_AUDIENCE=mqtt.meshmapper.net
PACKETCAPTURE_MQTT4_KEEPALIVE=120
# MQTT Topics for Broker 4 (MeshMapper) - Default Pattern
PACKETCAPTURE_MQTT4_TOPIC_STATUS=meshcore/{IATA}/{PUBLIC_KEY}/status
PACKETCAPTURE_MQTT4_TOPIC_PACKETS=meshcore/{IATA}/{PUBLIC_KEY}/packets
Requereix export de clau privada
El mode token signa amb la clau Ed25519 del node, així que el firmware ha de tenir l'export de clau privada habilitat. Si LetsMesh (MQTT1/MQTT2) ja publica, aquest export ja funciona i MeshMapper connectarà igual. L'observer apareixerà a l'Admin Portal de la teva regió (pestanya Observers) amb el check del broker MeshMapper un cop rebi paquets.
Mètode 4: Publicar des de Home Assistant (meshcore-ha)¶
Si el node ja està integrat a Home Assistant (integració meshcore-ha), no
necessites packet-capture ni mctomqtt: la mateixa integració sap publicar a MQTT. És
la via recomanada per a un node que ja viu a HA, sobretot si està connectat a HA
per TCP/WiFi, perquè així un únic procés parla amb la ràdio i evites el conflicte
de "una sola sessió TCP".
Verificat en producció (27/06/2026)
Provat amb el V3 Teià (HA per WiFi/TCP) publicant a Catalunya via meshcore-ha
2.8.0: status online amb source: meshcore-ha, model i firmware correctes, i
packets entrant en viu sota meshcore/BCN/.... Un intent previ amb packet-capture
per TCP al mateix node va entrar en bucle de reconnexió per compartir el port amb
HA; publicar des de HA ho va resoldre.
meshcore-ha suporta usuari/contrasenya o token, així que el broker de Catalunya
(Mosquitto) li va directe, sense audience. A la UI de Home Assistant:
Configuració → Dispositius i serveis → MeshCore → Configurar, secció de pujada MQTT
(MQTT Upload / Broker), i afegeix un broker en una ranura lliure:
| Camp | Valor |
|---|---|
| Server / Host | broker.livemap-meshcorecat.com |
| Port | 8883 |
| TLS | activat |
| Auth | usuari/contrasenya |
| Usuari | cat-pub |
| Contrasenya | CatMesh2026pub |
| IATA | BCN |
| Mode | packets / adverts |
| Topic | per defecte (meshcore/{IATA}/{PUBLIC_KEY}/...) |
Desa (la integració es recarrega sola) i verifica des del servidor:
mosquitto_sub -h broker.livemap-meshcorecat.com -p 8883 \
-u cat-sub -P CatMesh2026sub --capath /etc/ssl/certs \
-t 'meshcore/BCN/<PUBLIC_KEY>/#' -v
Ha de sortir un status online amb "source": "meshcore-ha" i packets en viu.
Surt ONLINE però amb l'etiqueta antiga?
Si a Beacon o al broker el node apareix amb un client_version vell (p. ex.
meshcore-packet-capture/unknown), sol ser un missatge retain o la memòria cau
de Beacon. L'estat real el dona el status en viu (--no-retain); per forçar
Beacon, docker compose exec redis redis-cli FLUSHDB i recarrega.
Notes addicionals¶
-
Comprovació des del costat Catalunya (ho fem nosaltres des del servidor, amb l'usuari de només lectura
cat-sub):mosquitto_sub -h broker.livemap-meshcorecat.com -p 8883 \ -u cat-sub -P <password-sub> \ --capath /etc/ssl/certs \ -t 'meshcore/+/#' -vEl
+mostra qualsevol IATA, així es veu de seguida sota quin prefix entra el nou observer. -
Per deixar de compartir dades:
sudo systemctl stop mctomqtt(idisablesi no vols que torni a arrencar).
Problemes típics (Mètode 2)¶
| Símptoma | Causa probable | Solució |
|---|---|---|
| No obre el port sèrie | Port incorrecte o sense permisos | Revisa ls /dev/ttyUSB* /dev/ttyACM*; l'usuari mctomqtt ha d'estar al grup dialout |
| Error TLS en connectar | Rellotge desincronitzat o CA no trobada | Verifica NTP (timedatectl); prova la variant WSS pel 8084 |
| Auth rejected | Usuari/contrasenya malament | Confirma cat-pub i la contrasenya exacta (sense espais) |
| Connecta però no publica res | La ràdio no té firmware amb packet-logging | Reflasheja amb la variant observer/debug del Pas 1 |
| No apareix sota BCN | IATA diferent a [general] |
Posa iata = "BCN" a 99-user.toml i reinicia |
Dubtes durant la instal·lació?
Envia'ns la sortida de journalctl -u mctomqtt -f i ho mirem.