tthandClaude Opus 5.5 0da25dd15b
ci / test (push) Successful in 1m15s
meshcore-repeater-observer 0.1.0
Reads a MeshCore repeater's console over BLE or USB and publishes what it
hears: the `pktlog` raw-frame feed in the meshcoretomqtt format (community
analyzer with a JWT signed by the node's key, audience = broker hostname, or
an own broker without auth) and optionally stats, `nodes`, `rxlog` to a local
MQTT broker. Needs the observer build of meshcore-tth.

Tested on a XIAO with the observer build over USB and over BLE: feed in the
meshcoretomqtt format, packet hashes matching those of other observers.
Unit tests for the parsers, the packet transform, the Ed25519 signature
(checked against `cryptography`), the JWT and paho-mqtt 1.x/2.x; README
(Czech), AGENTS.md, CI, Renovate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00
2026-11-03 00:20:03 +01:00

meshcore-repeater-observer

Udělá z MeshCore repeateru observer: přes jeho konzoli (Bluetooth nebo USB) průběžně čte, co repeater slyší, a posílá to do MQTT — do komunitního analyzeru (analyzer.meshcore.cz), do vlastního CoreScope, nebo obojí. Žádné druhé rádio vedle repeateru není potřeba.

repeater ── BLE / USB ── meshcore-repeater-observer ──┬── MQTT ── komunitní analyzer
 (observer build)                                     └── MQTT ── vlastní broker / CoreScope

English: turns a MeshCore repeater into an observer by reading its console (pktlog, rxlog, nodes) over BLE or USB and publishing to MQTT in the meshcoretomqtt format. Docs below are Czech; --help is English.

Kdy to dává smysl

  • Repeater už stojí (stožár, střecha) a vedle něj nejde nebo nechcete dát další rádio. Počítač s Bluetooth v dosahu, nebo USB kabel, stačí.
  • Jinak je jednodušší samostatný observer na openHopu, který MQTT do analyzerů umí sám a repeater nechá na pokoji.

Co je potřeba

  1. Repeater s observer buildem firmwaru meshcore-tth: soubory *_repeater-observer-* v Releases (XIAO, SenseCAP Solar, RAK4631, T1000-E, Heltec T114; .uf2 přetažením na disk bootloaderu, .zip pro DFU přes BLE nebo USB). Běžný MeshCore firmware příkazy pktlog/rxlog nemá; observer pak feed tiše vynechá. Observer build má Bluetooth konzoli po flashi vypnutou a zástupný PIN 123456: nejdřív si nastavte vlastní PIN a admin heslo, pak ble on.
  2. Linux s Pythonem 3.10+ (Raspberry Pi stačí), u BLE s BlueZ.
  3. Pro komunitní analyzer: repeater na českém nastavení (869,432 MHz / 62,5 kHz / SF7 / CR5) — komunita chce jen uzly na CZ presetu.

Instalace

pipx install git+https://git.rfa.cz/tth-pub/meshcore-repeater-observer
meshcore-repeater-observer --help

USB (doporučeno)

Repeater na USB kabelu; port najdete v ls -l /dev/serial/by-id/ (trvalé jméno, /dev/ttyACM0 se po přepojení mění).

MC_SERIAL_PORT=/dev/serial/by-id/usb-…-if00 \
MC_OBS_ENABLE=1 MC_OBS_IATA=PRG \
meshcore-repeater-observer

USB se s rádiem repeateru nepere a čte se nepřetržitě.

Bluetooth

  1. Na repeateru (USB konzole, nebo z aplikace přes admin CLI) nastavte vlastní PIN a heslo a zapněte konzoli — po flashi je vypnutá: ble on (uloží se). Pozor: dokud má nějaký počítač otevřený jeho USB port, Bluetooth konzole se neukáže (neběží BLE advertising, nejde se připojit). Na repeater jako takový to vliv nemá — přijímá, přeposílá a posílá LoRa adverty dál normálně. Jen BLE a USB konzole se střídají.

  2. Jednou spárujte:

    bluetoothctl
      agent KeyboardOnly
      default-agent
      scan on          # počkejte na MAC repeateru
      pair AA:BB:CC:DD:EE:FF
      trust AA:BB:CC:DD:EE:FF
      quit
    
  3. Spusťte s MC_BLE_ADDR=AA:BB:CC:DD:EE:FF místo MC_SERIAL_PORT.

Observer se po každém vyčtení odpojí a MC_BLE_OFF_INTERVAL sekund (výchozí 120) počká: starší firmware s připojeným BLE klientem zahazoval přímé (DIRECT) pakety, které měl přeposlat. V meshcore-tth je to opravené, interval jde zkrátit; pokud log hlásí pktlog DROP, ring se během pauzy přepsal.

Jako služba (systemd)

# /etc/systemd/system/meshcore-repeater-observer.service
[Unit]
Description=MeshCore repeater observer
Wants=network-online.target bluetooth.target
After=network-online.target bluetooth.target

[Service]
EnvironmentFile=/etc/meshcore-repeater-observer.env
ExecStart=/opt/meshcore-repeater-observer/bin/meshcore-repeater-observer
StateDirectory=meshcore-repeater-observer
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

V /etc/meshcore-repeater-observer.env řádky MC_…=… z tabulky níž. StateDirectory drží pozici v ringu repeateru, takže restart nic neztratí.

Nastavení (proměnné prostředí)

proměnná výchozí
MC_SERIAL_PORT — USB konzole repeateru (/dev/serial/by-id/…)
MC_BLE_ADDR / MC_BLE_NAME — BLE: MAC, nebo jméno, které repeater advertuje
MC_NODE repeater jméno v lokálních MQTT tématech
MC_OBS_ENABLE vypnuto 1 = observer feed z pktlog
MC_OBS_IATA — povinné s feedem: kód letiště regionu (PRG, BRQ, OSR, …)
MC_OBS_MQTT_HOST mqtt1.meshcore.cz broker feedu
MC_OBS_MQTT_PORT / MC_OBS_TRANSPORT / MC_OBS_TLS 443 / websockets / 1
MC_OBS_AUTH token token = JWT podepsaný klíčem uzlu; none = vlastní broker bez hesla
MC_OBS_AUDIENCE = MC_OBS_MQTT_HOST audience v JWT; komunitní brokery chtějí svůj hostname
MC_OBS_OWNER / MC_OBS_EMAIL / MC_OBS_MODEL — / — / MeshCore repeater volitelné údaje do tokenu a statusu
MC_MQTT_HOST — lokální MQTT (volitelné): stats, nodes, rxlog, kopie paketů
MC_MQTT_PORT / MC_MQTT_TLS / MC_MQTT_USER / MC_MQTT_PASS 1883 / —
MC_MQTT_TOPIC repeater-observer/<MC_NODE> kořen lokálních témat
MC_INTERVAL 300 s mezi plným čtením (stats, senzory, sousedé)
MC_NODES_INTERVAL / MC_RXLOG_INTERVAL 60 / 5 registr nodes / vyčítání rxlog+pktlog
MC_BLE_OFF_INTERVAL 120 BLE: pauza bez spojení mezi vyčteními
MC_CURSOR_FILE $STATE_DIRECTORY/cursors.json pozice v ringu repeateru

Komunitní brokery: mqtt1.meshcore.cz, mqtt2.meshcore.website, mqtt.meshcore-analyzer.eu (všechny WSS :443, JWT). Audience musí být hostname brokeru — s jinou broker odpoví not authorised.

Vlastní CoreScope: MC_OBS_MQTT_HOST=<broker> MC_OBS_MQTT_PORT=1883 MC_OBS_TRANSPORT=tcp MC_OBS_TLS=0 MC_OBS_AUTH=none.

Klíč uzlu

Pro komunitní feed se observer přihlašuje tokenem podepsaným klíčem repeateru, takže si při spojení přečte z konzole get prv.key. Klíč drží jen v paměti procesu, nikam ho nezapisuje ani neloguje, a před použitím ověří, že k němu patří veřejný klíč uzlu. S MC_OBS_AUTH=none se klíč nečte vůbec.

Co se publikuje

  • Feed (MC_OBS_ENABLE=1): meshcore/<IATA>/<PUBKEY>/packets a …/status ve formátu meshcoretomqtt.
  • Lokálně (MC_MQTT_HOST), pod MC_MQTT_TOPIC: neighbours, stats, sensors, nodes (retained), rxlog, packets, ble/serial stav.

Observer navíc srovnává hodiny repeateru bez GPS (time <epoch>), když jsou pozadu: starý čas v advertech by ostatní uzly zahazovaly jako replay.

Když to nejde

příznak příčina
config: … a konec chybí transport (MC_SERIAL_PORT/MC_BLE_ADDR), IATA, nebo není kam publikovat
BLE … nenalezen ve scanu repeater má BLE vypnuté (ble on), má otevřený USB port (BLE se pak neukazuje), nebo BlueZ visí na starém spojení: bluetoothctl disconnect <MAC> — nikdy remove, to zruší spárování
FW nezná pktlog repeater nemá observer build
broker odmítl spojení rc=5 špatná audience, nebo uzel není na CZ presetu
pktlog DROP ring repeateru se přepsal dřív, než se vyčetl: kratší MC_BLE_OFF_INTERVAL, nebo USB

Licence

MIT.

S
Description
Observer feed and stats from a MeshCore repeater console over BLE or USB
Readme MIT
92 KiB
0 Stars 1 Watchers 0 Forks
Languages
Python 100%