pub-release / release (push) Successful in 32m57s
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
573 lines
33 KiB
Markdown
573 lines
33 KiB
Markdown
## O tomto forku (meshcore-tth)
|
||
|
||
*English version [below](#about-this-fork-meshcore-tth).*
|
||
|
||
Fork projektu [meshcore-dev/MeshCore](https://github.com/meshcore-dev/MeshCore),
|
||
na kterém běží repeatery, senzory a testovací desky malé české sítě na CZ
|
||
meshi (869,432 MHz). Upstreamové větve `main` a `dev` se slučují automaticky
|
||
dvakrát denně; všechno níže je navíc nad nimi. Náš kód je ve zdrojácích
|
||
označený `CUSTOM (TeTeHacko)`. Nic z toho nemění protokol na rádiu.
|
||
|
||
### Repeater: antispam (všechno vypínatelné, nic z toho není v upstreamu)
|
||
|
||
* **FairnessLimiter** – token buckety na přeposílané floody podle 1bajtových
|
||
identifikátorů, které jsou v paketu stejně v čitelné podobě (hash kanálu,
|
||
hash odesílatele, původce advertu). Port návrhu Beanowa
|
||
[#1502](https://github.com/meshcore-dev/MeshCore/pull/1502), limity
|
||
přepočítané z 30 dní skutečného provozu CZ meshe.
|
||
`fairness [on|off|grid|cap|refill]`; přímo směrovaný provoz se neomezuje nikdy.
|
||
* **Okno na adverty podle původce** – flood advert každého uzlu se přepošle
|
||
nejvýš jednou za N hodin (`fairness advert <h>|clear`), převzato
|
||
z AdvertLimiteru [DutchMeshCore](https://github.com/Dutch-MeshCore/MeshCore).
|
||
Míří na uzly, které advertují každou minutu.
|
||
* **Dry-run** – `fairness dryrun on` započítá každý verdikt, ale přepošle
|
||
i tak; `fairness air` ukáže ušetřený (nebo ušetřitelný) airtime podle důvodu.
|
||
* **Filtr kanálů** – na kanálech, jejichž klíč repeater zná (Public
|
||
a `#hashtag` kanály), přestane přeposílat zprávy uvedených jmen odesílatelů
|
||
(`filter add|del|list`). Jméno se dá podvrhnout: je to brzda na utrženého
|
||
bota, ne bezpečnost.
|
||
* **Blokace přeposílání podle hashe kanálu** – `filter hash add <hex> [s]`:
|
||
bez klíče, takže funguje i na soukromých kanálech; příjem se nemění, jen
|
||
přeposílání. S `s` se kanál neodřízne, ale přiškrtí (jeden paket za `s`
|
||
sekund).
|
||
* **Limit stáří zprávy** – `filter age <min>|off` (volitelné, 1–10080 min):
|
||
nepřeposílá skupinové zprávy na dešifrovaných kanálech, jejichž čas od
|
||
odesílatele je starší; bez nastavených hodin repeateru neplatí. Posuzuje
|
||
hodiny odesílatele, takže zahodí i companiony bez synchronizace času –
|
||
nastavuj ho na dny.
|
||
* `filter dryrun on` započítá každý verdikt `filter`, ale přepošle i tak.
|
||
|
||
### Repeater: diagnostika a provoz
|
||
|
||
* Pasivní analyzátor v konzoli: `nodes` (slyšené repeatery a roomy, klíč pro
|
||
spojení více cest), `rxlog` (každý slyšený rámec: typ, cesta, SNR, RSSI),
|
||
`pktlog` (surové rámce pro feed observeru), velké stránkované odpovědi.
|
||
* Kanálový bot v analyzer buildu (`!link`, dotazy na cestu, cooldown na
|
||
odesílatele, ignore list) – odpovídá, aniž by přeposílal.
|
||
* `dfu [uf2|serial|ota]` (spolehlivý reboot do bootloaderu), `blink`, `txpwr`
|
||
s verdiktem RadioLibu, `i2c` sken sběrnice, čítače chyb vysílání ve stavové
|
||
odpovědi, důvod resetu vypsaný při startu.
|
||
* Textová konzole přes BLE vedle USB, `ble on|off` uložené přes reboot
|
||
(`RPT_BLE_DEFAULT_OFF`: startuje vypnuté), vlastní BLE PIN (`ble pin`),
|
||
uložený vysílací výkon spojení (`blepwr`), `bleconn`, neblokující BLE
|
||
vysílání a parametry spojení, které vydrží i na slabém linku.
|
||
* Build flag `RADIO_DIAG`: `radiostat` / `radiokick` na přijímač SX1262, který
|
||
přestal přijímat.
|
||
* Provoz bez DIO1 (`LORA_POLL_IRQ`) pro desku s mrtvou linkou přerušení.
|
||
|
||
### Opravy jádra
|
||
|
||
* TRACE už nepřipisuje cestu za konec payloadu; parsování TRACE/PATH
|
||
a `Packet::readFrom` hlídají meze.
|
||
* `markSeen` je zase idempotentní (odesílací cesta ujídala okno deduplikace).
|
||
* Záložní výpočet v `calcMaxPacketMillis` už nepodteče (uzel na tom ohluchl).
|
||
* Šířka path hashe se bere z nastavení uzlu na všech cestách vysílání včetně
|
||
`sendZeroHop`; výchozí jsou 2bajtové path hashe (`PATH_HASH_MODE_DEFAULT`).
|
||
* Nepovedené vysílání se zařadí znovu s odstupem, místo aby se zahodilo.
|
||
* RSSI každého paketu se zaznamená při příjmu; `ContactInfo` se před
|
||
částečným vyplněním vynuluje.
|
||
|
||
### Napájení, hodiny, GPS
|
||
|
||
* GPS duty cycle (`gps duty`), i na T1000-E, kde nebyl: přijímač běží jen
|
||
kolem synchronizace hodin (jednou denně, po neúspěšném okně znovu za 6 h).
|
||
Dotaz na polohu přijímač probudí pro příští dotaz.
|
||
* Uzel bez GPS startuje na čase sestavení firmwaru, ne v roce 2024; hodiny
|
||
a záznam o hardfaultu přežijí teplý reset (`.noinit`); `clkreboot`.
|
||
* Na solárních uzlech žádná blikající LED a pomalejší BLE advertising; stav
|
||
baterie jako ikona na konci advertovaného jména (volitelné).
|
||
* Volitelný RX duty cycle (`set radio.rxps`, port PowerSaving z EasySkyMesh):
|
||
SX1262 mezi krátkými okny poslechu spí. Ve veřejných buildech je zabudovaný
|
||
a **vypnutý**; `max` na lavici ušetřil ~2,3 mA bez ztráty paketů
|
||
([docs/power.md](docs/power.md)). Jen SX1262, ne LR1110 (T1000-E).
|
||
* Podpěťová pojistka při startu (`PWRMGT_VOLTAGE_BOOTLOCK`) je na nRF52
|
||
**vypnutá**, stejně jako v upstreamu od v1.18.0
|
||
([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): pevný práh
|
||
3,3 V nepouštěl k životu uzly na LiFePO4 nebo LTO. Firmware tak naběhne na
|
||
jakékoli chemii článku; před hlubokým vybitím má chránit BMS nebo ochranná
|
||
destička článku. Konfigurovatelná pojistka podle chemie čeká na upstream
|
||
([#2088](https://github.com/meshcore-dev/MeshCore/pull/2088)).
|
||
|
||
### Senzory a companiony
|
||
|
||
* `simple_sensor`: telemetrie z externí stanice po UART
|
||
(`BudkaLinkSensorManager`, jeden LPP kanál na veličinu), `sensor read`.
|
||
* Senzory, které jinak měří nepřetržitě (INA219, INA226, INA260, INA3221,
|
||
BMP280), mezi čteními telemetrie spí a měří jen na vyžádání (nápad a první
|
||
patch pro INA219: Alkel Brostl). Čipy INA se rozlišují podle ID, takže
|
||
INA226 už se nedetekuje jako INA219. Odpor bočníku se nastavuje za běhu
|
||
a ukládá se: `sensor set ina.shunt <mΩ>`.
|
||
* Companion: `gps duty` přežije reboot, export klíče a PIN jsou na
|
||
neověřeném USB spojení zamčené, kopie data sestavení má hlídanou délku.
|
||
KISS modem: oprava o jedna vedle při zkracování jména.
|
||
|
||
### Veřejné buildy: výchozí nastavení pro český mesh
|
||
|
||
Releasy z tohoto repozitáře (`pub-release`) jsou přednastavené pro český
|
||
mesh podle wiki [meshcore.cz](https://meshcore.cz/), takže čerstvě nahraný
|
||
uzel nepotřebuje obvyklé kolečko nastavování:
|
||
|
||
* rádio 869,432 MHz / 62,5 kHz / SF7 / CR5 (všechny buildy);
|
||
* repeater a room server: zero-hop advert vypnutý, flood advert každých 25 h,
|
||
duty cycle 10 % (`get dutycycle` → `10.0%`; zastaralé `af` je 9);
|
||
* repeater: regiony `cz` a `cs` vedle `*` – vlastní `cz-<kraj>` přidáš přes
|
||
`region put cz-xxx cz` + `region save`;
|
||
* 2bajtové path hashe (výchozí v tomto forku);
|
||
* repeater: filtr kanálů (`filter add <jméno>`) je zabudovaný pro Public,
|
||
`#meshcore` a `#test`, s prázdným seznamem – nedělá nic, dokud do něj
|
||
nepřidáš jméno.
|
||
|
||
Platí jen pro uzel bez uloženého nastavení (nový nebo po `erase`): nové
|
||
nahrání ponechá, co už uzel má, a regiony, které jsi smazal a uložil,
|
||
zůstanou smazané. Jméno a admin heslo si nastav sám.
|
||
|
||
Varianty observer (`*_repeater-observer-*`) nRF52 repeaterů (XIAO, SenseCAP
|
||
Solar, RAK4631, T1000-E, Heltec T114) přidávají buffery `nodes` / `rxlog` /
|
||
`pktlog` a textovou konzoli přes BLE, aby šel repeater číst přes USB nebo BLE
|
||
([meshcore-repeater-observer](https://git.rfa.cz/tth-pub/meshcore-repeater-observer)).
|
||
BLE konzole je po nahrání **vypnutá** (`RPT_BLE_DEFAULT_OFF`). Nemá vlastní
|
||
přihlášení, jen BLE PIN, a PIN v buildu je veřejný zástupný `123456`. Nejdřív
|
||
si proto nastav vlastní – v USB konzoli, nebo jako admin přes mesh (vzdálené
|
||
CLI v aplikaci): `ble pin <6 číslic>` (uloží se a přežije reboot i nové
|
||
nahrání; zároveň smaže všechny bondy, takže spárovaná zařízení se párují
|
||
znovu). Teprve pak `ble on` – dokud je PIN zástupný, tyhle buildy ho odmítnou.
|
||
`ble` ukáže, jestli je PIN `own` nebo `build default`, samotný PIN nikdy.
|
||
Releasy do `tth-654d53f3` `ble pin` nemají: BLE tam nech vypnuté a používej USB.
|
||
|
||
### Nahrání releasu
|
||
|
||
Soubory jsou v [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases).
|
||
Release se jmenuje podle upstreamové verze a data, např.
|
||
`v1.18.0+tth.20261112` (druhý téhož dne `.2`), a v popisu má změny od
|
||
předchozího releasu. Pro každou desku a roli je jedna sada
|
||
(`<deska>_<role>-<release>`, např. `Xiao_nrf52_repeater-v1.18.0+tth.20261112.zip`):
|
||
`.zip` a `.uf2` pro nRF52, `.bin` pro ESP32 (`-merged.bin` je celý obraz pro
|
||
prázdnou desku, obyčejný `.bin` aktualizace). Kontrolní součty jsou
|
||
v `SHA256SUMS`. Releasy do 12. 11. 2026 se jmenovaly `tth-<sha>`.
|
||
|
||
**nRF52 (XIAO, RAK4631, SenseCAP Solar, T1000-E, T114) přes
|
||
[webový flasher MeshCore](https://flasher.meshcore.io)** – Chrome, Edge nebo
|
||
Chromium na počítači (Web Serial; ne Firefox ani Safari):
|
||
|
||
1. Připoj desku přes USB.
|
||
2. Klikni na **Custom Firmware** a vyber `.zip` pro svou desku.
|
||
3. Klikni na **Enter DFU mode** a vyber sériový port desky. Deska se
|
||
restartuje do bootloaderu a objeví se jako nový port.
|
||
4. Klikni na **Flash!** a vyber ten nový port. Zhruba 30 s, pak se deska
|
||
restartuje do nového firmwaru.
|
||
5. **Console** ve flasheru (nebo jakýkoli sériový terminál, 115200) ověří
|
||
výsledek: `ver` ukáže `v1.xx.x-tth<sha>`, stejně jako řádek „Verze v uzlu“
|
||
v popisu releasu.
|
||
|
||
**Neklikej na Erase Flash**, pokud nechceš nový uzel: smaže identitu (klíč
|
||
uzlu a všechno, co ho zná) i veškeré nastavení. Obyčejné nahrání je zachová.
|
||
|
||
Vyzkoušeno na XIAO (repeater-observer, 3. 11. 2026). ESP32 `.bin` přes stejné
|
||
tlačítko Custom Firmware tu vyzkoušené není.
|
||
|
||
Bez webového flasheru: na většině desek otevře dvojí stisk resetu bootloader
|
||
jako USB disk; zkopíruj na něj `.uf2`. Nebo
|
||
`adafruit-nrfutil dfu serial -pkg <soubor>.zip -p <port> -b 115200` s deskou
|
||
v bootloaderu.
|
||
|
||
Nový uzel po nahrání nastav v konzoli: `set name <jméno>`,
|
||
`password <admin heslo>` (nejvýš 15 znaků), vlastní region přes
|
||
`region put cz-<kraj> cz` + `region save`. Repeater přeposílá od prvního
|
||
startu (výchozí v upstreamu) a tyhle buildy jsou na ostré CZ frekvenci: na
|
||
stole bez antény dej `set repeat off`, dokud není na místě.
|
||
|
||
### Experimentální: aktualizace firmwaru od admina (`*-ota`)
|
||
|
||
Každý nRF52 build s textovou konzolí (repeater, observer, room server,
|
||
senzor) je v releasu ještě jednou jako **experimentální** `*-ota` /
|
||
`*-observer-ota`. Ten umí přijmout nový firmware od admina příkazy `fw …`:
|
||
v USB nebo BLE konzoli, nebo **přes mesh jako vzdálené admin CLI**. Bez změny
|
||
bootloaderu a bez druhé banky: uzel si balíček uloží do volné flash,
|
||
zkontroluje ho celý (podpis, hashe, nanečisto provedená delta) a přepíše se
|
||
až na `fw apply`, rutinou běžící z RAM. Když během přepisu vypadne napájení,
|
||
zůstane v bootloaderu a vrátí se přes USB/BLE DFU.
|
||
|
||
* V releasu je ke každému `*-ota` obrazu plný balíček
|
||
`<deska>_<role>-ota-<release>.mcfw` (jen přes USB/BLE) a delta
|
||
`….from-<starší release>.mcfw` od každého drženého předchozího releasu,
|
||
typicky jednotky kB.
|
||
* **Přes mesh uzel přijme jen deltu, a nikdy ne starší verzi, než má** –
|
||
vynucuje to uzel, ne nástroj. Plný obraz nebo návrat ke starší verzi jen
|
||
lokálně (`fw apply downgrade`). `fw apply` čeká na baterii ≥ 3,8 V, pokud
|
||
uzel neběží z USB.
|
||
* Balíčky i `SHA256SUMS` jsou podepsané klíčem `meshcore-ota@tth-pub`
|
||
a `*-ota` obraz jiný podpis nepřijme. Ověření stažených souborů:
|
||
`ssh-keygen -Y verify -f tools/ota_allowed_signers -I meshcore-ota@tth-pub
|
||
-n meshcore-ota -s SHA256SUMS.sig < SHA256SUMS`. Vlastní build s vlastním
|
||
klíčem: `[ota] pubkey` v `platformio.local.ini`.
|
||
* První `*-ota` obraz se nahraje obyčejně (viz výše), další už jako delta.
|
||
Nástroje: `tools/ota_push.py` (USB), `tools/ota_mesh_push.py` (přes mesh
|
||
skrz companion; potřebuje pythonovou knihovnu `meshcore`, admin heslo bere
|
||
z `[secrets] admin_pw` v `platformio.local.ini`), `tools/ota_pack.py info`.
|
||
Postup a čísla: [docs/ota.md](docs/ota.md).
|
||
* **Experimentální**: vyzkoušeno na XIAO na lavici přes USB i přes mesh
|
||
(1 hop). Vadný nový firmware nemá kam se vrátit (není druhá banka) – nový
|
||
release nejdřív na jednom uzlu na dosah. Stojí ~10 kB RAM navíc.
|
||
|
||
### Sestavení
|
||
|
||
* Razítko verze v každém nRF52 envu (`v1.18.0-tth<sha>`, `+` = neuklizený
|
||
strom), základní verze z upstreamového tagu (`tools/build_version.py`).
|
||
* `tools/`: nástroje na uzly – konzole (USB, BLE), flashování, testy na
|
||
lavici, diagnostika ([tools/README.md](tools/README.md)). Desky podle jména
|
||
bere z lokálního configu mimo repo (`tools/config.example.ini`).
|
||
* `hardware/cavity-box`: parametrická krabička pro dutinový filtr na stožár.
|
||
|
||
---
|
||
|
||
## About this fork (meshcore-tth)
|
||
|
||
*Česká verze [výše](#o-tomto-forku-meshcore-tth).*
|
||
|
||
A fork of [meshcore-dev/MeshCore](https://github.com/meshcore-dev/MeshCore)
|
||
that runs the repeaters, sensors and bench boards of a small Czech network on
|
||
the CZ mesh (869.432 MHz). Upstream `main` and `dev` are merged automatically
|
||
twice a day; everything below is on top of that. Our code is marked
|
||
`CUSTOM (TeTeHacko)` in the source. Nothing here changes the wire protocol.
|
||
|
||
### Repeater: antispam (all of it off-switchable, none of it upstream)
|
||
|
||
* **FairnessLimiter** -- token buckets on forwarded floods, keyed on the 1-byte
|
||
ids already in the clear (channel hash, sender hash, advert origin). Port of
|
||
Beanow's proposal [#1502](https://github.com/meshcore-dev/MeshCore/pull/1502),
|
||
limits re-sized from 30 days of real CZ traffic.
|
||
`fairness [on|off|grid|cap|refill]`; direct-routed traffic is never limited.
|
||
* **Per-origin advert window** -- each node's flood advert forwarded at most
|
||
once per N hours (`fairness advert <h>|clear`), ported from
|
||
[DutchMeshCore](https://github.com/Dutch-MeshCore/MeshCore)'s AdvertLimiter.
|
||
Aimed at nodes that re-advertise every minute.
|
||
* **Dry-run** -- `fairness dryrun on` counts every verdict but forwards anyway;
|
||
`fairness air` reports the airtime shed (or that would be) per reason.
|
||
* **Channel filter** -- on channels whose key the repeater knows (Public and
|
||
`#hashtag` channels), stop forwarding messages of listed sender names
|
||
(`filter add|del|list`). Names are spoofable: it contains a runaway bot,
|
||
it is not security.
|
||
* **Channel-hash deny-forward** -- `filter hash add <hex> [secs]`: keyless,
|
||
works on private channels too; reception is unaffected, only forwarding.
|
||
With `secs` the channel is throttled (one packet per `secs`) instead of cut.
|
||
* **Message age limit** -- `filter age <min>|off` (opt-in, 1-10080 min): do not
|
||
forward group texts on the decrypted channels whose sender timestamp is
|
||
older; inactive while the repeater clock is unset. It judges the sender's
|
||
clock, so companions without a time sync are dropped too -- keep it in days.
|
||
* `filter dryrun on` counts every `filter` verdict but forwards anyway.
|
||
|
||
### Repeater: diagnostics and operations
|
||
|
||
* Passive analyzer in the console: `nodes` (heard repeaters/rooms, multi-path
|
||
join key), `rxlog` (every frame heard, type/path/SNR/RSSI), `pktlog` (raw
|
||
frames for an observer feed), big paged replies.
|
||
* Channel bot for the analyzer build (`!link`, path questions, per-sender
|
||
cooldown, ignore list) -- answers without repeating.
|
||
* `dfu [uf2|serial|ota]` (deterministic reboot into the bootloader), `blink`,
|
||
`txpwr` with RadioLib's verdict, `i2c` bus scan, TX-failure counters in the
|
||
status reply, reset reason printed at boot.
|
||
* Text console over BLE next to USB, `ble on|off` saved across reboots
|
||
(`RPT_BLE_DEFAULT_OFF`: starts off), own BLE PIN (`ble pin`), persisted
|
||
connection TX power (`blepwr`), `bleconn`, a
|
||
non-blocking BLE TX pump and connection parameters that hold on a weak link.
|
||
* `RADIO_DIAG` build flag: `radiostat` / `radiokick` for an SX1262 receiver
|
||
that stops receiving.
|
||
* DIO1-less operation (`LORA_POLL_IRQ`) for a board with a dead IRQ line.
|
||
|
||
### Core fixes
|
||
|
||
* TRACE no longer appends its path past the end of the payload; TRACE/PATH
|
||
parsing and `Packet::readFrom` are bounds-checked.
|
||
* `markSeen` is idempotent again (the send path was eating the dedup window).
|
||
* `calcMaxPacketMillis` fallback no longer underflows (a node went deaf on it).
|
||
* Path-hash width comes from the node's prefs on every TX path, including
|
||
`sendZeroHop`; 2-byte path hashes are the default (`PATH_HASH_MODE_DEFAULT`).
|
||
* Failed transmits are re-queued with backoff instead of dropped.
|
||
* Per-packet RSSI captured at RX; `ContactInfo` zeroed before a partial fill.
|
||
|
||
### Power, clock, GPS
|
||
|
||
* GPS duty cycle (`gps duty`), also on the T1000-E, which had none: the
|
||
receiver runs only around a clock sync (once a day, after a window without
|
||
a fix again in 6 h). A position request warms it for the next request.
|
||
* A node without GPS starts at its build epoch, not in 2024; the clock and a
|
||
hardfault record survive a warm reset (`.noinit`); `clkreboot`.
|
||
* No blinking LED and slower BLE advertising on solar nodes; battery level as
|
||
an icon at the end of the advertised name (opt-in).
|
||
* Optional RX duty cycle (`set radio.rxps`, ported from EasySkyMesh
|
||
PowerSaving): the SX1262 sleeps between short listening windows. Built into
|
||
the public releases and **off**; `max` saved ~2.3 mA on the bench with no
|
||
packet loss ([docs/power.md](docs/power.md)). SX1262 only, not the LR1110
|
||
(T1000-E).
|
||
* The nRF52 boot undervoltage lock (`PWRMGT_VOLTAGE_BOOTLOCK`) is **off**,
|
||
as in upstream since v1.18.0
|
||
([#2377](https://github.com/meshcore-dev/MeshCore/pull/2377)): its fixed
|
||
3.3 V threshold kept LiFePO4 and LTO nodes from booting. The firmware boots
|
||
on any cell chemistry; deep-discharge protection is up to the BMS or the
|
||
cell's protection board. A configurable, chemistry-aware lock is waiting
|
||
for upstream ([#2088](https://github.com/meshcore-dev/MeshCore/pull/2088)).
|
||
|
||
### Sensors and companions
|
||
|
||
* `simple_sensor`: telemetry from an external station over UART
|
||
(`BudkaLinkSensorManager`, one LPP channel per meter), `sensor read`.
|
||
* Sensors that would otherwise convert continuously (INA219, INA226, INA260,
|
||
INA3221, BMP280) sleep between telemetry reads and measure on demand (idea
|
||
and first INA219 patch: Alkel Brostl). INA chips are told apart by their ID,
|
||
so an INA226 is no longer taken for an INA219. The shunt is set at runtime
|
||
and saved: `sensor set ina.shunt <mOhm>`.
|
||
* Companion: `gps duty` persists, key export / PIN gated on an unauthenticated
|
||
USB link, bounded build-date copy. KISS modem: off-by-one in the name clamp.
|
||
|
||
### Public builds: Czech mesh defaults
|
||
|
||
Releases built from this repository (`pub-release`) come preset for the
|
||
Czech mesh, following the [meshcore.cz](https://meshcore.cz/) wiki, so a
|
||
freshly flashed node does not need the usual round of settings:
|
||
|
||
* radio 869.432 MHz / 62.5 kHz / SF7 / CR5 (all builds);
|
||
* repeater and room server: zero-hop advert off, flood advert every 25 h,
|
||
10 % duty cycle (`get dutycycle` → `10.0%`; the deprecated `af` reads 9);
|
||
* repeater: regions `cz` and `cs` next to `*` -- add your own `cz-<kraj>`
|
||
with `region put cz-xxx cz` + `region save`;
|
||
* 2-byte path hashes (this fork's default);
|
||
* repeater: the channel filter (`filter add <name>`) is built in for Public,
|
||
`#meshcore` and `#test`, with an empty list -- it does nothing until you
|
||
add a name.
|
||
|
||
They apply only to a node with no saved settings (new, or after an erase):
|
||
a reflash keeps whatever the node already has, and regions you removed and
|
||
saved stay removed. Set a name and an admin password yourself.
|
||
|
||
Observer variants (`*_repeater-observer-*`) of the nRF52 repeaters (XIAO,
|
||
SenseCAP Solar, RAK4631, T1000-E, Heltec T114) add the `nodes` / `rxlog` /
|
||
`pktlog` rings and a text console over BLE, for reading the repeater over
|
||
USB or BLE ([meshcore-repeater-observer](https://git.rfa.cz/tth-pub/meshcore-repeater-observer)).
|
||
The BLE console is **off** after flashing (`RPT_BLE_DEFAULT_OFF`). It has no
|
||
login of its own, only the BLE PIN, and the build's PIN is the public
|
||
placeholder `123456`. So first set your own -- in the USB console, or as
|
||
admin over the mesh (remote CLI in the app): `ble pin <6 digits>` (saved, survives a reboot and a reflash; it also drops
|
||
every existing bond, so paired devices pair again). Only then `ble on` --
|
||
these builds refuse it while the PIN is still the placeholder. `ble` shows
|
||
whether the PIN is `own` or `build default`, never the PIN itself. Releases
|
||
up to `tth-654d53f3` do not have `ble pin`: keep BLE off there and use USB.
|
||
|
||
### Flashing a release
|
||
|
||
Files are in [Releases](https://git.rfa.cz/tth-pub/meshcore-tth/releases).
|
||
A release is named after the upstream version and the date, e.g.
|
||
`v1.18.0+tth.20261112` (a second one that day `.2`), and its notes list the
|
||
changes since the previous release. One set per board and role
|
||
(`<board>_<role>-<release>`, e.g. `Xiao_nrf52_repeater-v1.18.0+tth.20261112.zip`):
|
||
`.zip` and `.uf2` for nRF52 boards, `.bin` for ESP32 (`-merged.bin` is the
|
||
full image for a blank board, the plain `.bin` an update). `SHA256SUMS` lists
|
||
the checksums. Releases up to 12. 11. 2026 were named `tth-<sha>`.
|
||
|
||
**nRF52 (XIAO, RAK4631, SenseCAP Solar, T1000-E, T114) with the
|
||
[MeshCore web flasher](https://flasher.meshcore.io)** -- Chrome, Edge or
|
||
Chromium on a computer (Web Serial; not Firefox or Safari):
|
||
|
||
1. Connect the board over USB.
|
||
2. Click **Custom Firmware** and choose the `.zip` for your board.
|
||
3. Click **Enter DFU mode** and pick the board's serial port. The board
|
||
restarts into its bootloader and shows up as a new port.
|
||
4. Click **Flash!** and pick that new port. About 30 s, then the board
|
||
restarts into the new firmware.
|
||
5. **Console** in the flasher (or any serial terminal, 115200) checks the
|
||
result: `ver` shows `v1.xx.x-tth<sha>`, the same as the "Verze v uzlu"
|
||
(node version) line in the release notes.
|
||
|
||
**Do not click Erase Flash** unless you want a new node: it wipes the
|
||
identity (the node's key and everything that knows it) together with all
|
||
settings. A plain flash keeps them.
|
||
|
||
Tried on a XIAO (repeater-observer, 3. 11. 2026). ESP32 `.bin` through the
|
||
same Custom Firmware button is untested here.
|
||
|
||
Without the web flasher: on most boards a double-tap of reset opens the
|
||
bootloader as a USB drive; copy the `.uf2` onto it. Or
|
||
`adafruit-nrfutil dfu serial -pkg <file>.zip -p <port> -b 115200` with the
|
||
board in the bootloader.
|
||
|
||
After flashing a new node, set it up in the console: `set name <name>`,
|
||
`password <admin password>` (at most 15 characters), your own region with
|
||
`region put cz-<kraj> cz` + `region save`. A repeater forwards from its
|
||
first boot (upstream default) and these builds are on the live CZ frequency:
|
||
on a desk without its antenna, `set repeat off` until it is in place.
|
||
|
||
### Experimental: firmware update pushed by the admin (`*-ota`)
|
||
|
||
Every nRF52 build with a text console (repeater, observer, room server,
|
||
sensor) is in the release once more as an **experimental** `*-ota` /
|
||
`*-observer-ota` image. It takes a new firmware from its admin with the
|
||
`fw …` commands: on the USB or BLE console, or **over the mesh as remote admin
|
||
CLI**. No bootloader change, no second bank: the node stores the package in
|
||
free flash, checks all of it (signature, hashes, the delta applied dry) and
|
||
rewrites itself only on `fw apply`, from a routine running in RAM. A power
|
||
cut during the rewrite leaves it in the bootloader, back via USB/BLE DFU.
|
||
|
||
* Each `*-ota` image comes with a full package
|
||
`<board>_<role>-ota-<release>.mcfw` (USB/BLE only) and a delta
|
||
`….from-<earlier release>.mcfw` from every kept earlier release, typically
|
||
a few kB.
|
||
* **Over the mesh a node takes only a delta, and never an older version than
|
||
it runs** -- enforced by the node, not by the tool. A full image or a step
|
||
back only locally (`fw apply downgrade`). `fw apply` wants the battery at
|
||
3.8 V or more unless the node runs on USB.
|
||
* Packages and `SHA256SUMS` are signed by `meshcore-ota@tth-pub`, and an
|
||
`*-ota` image accepts no other signature. Checking the downloads:
|
||
`ssh-keygen -Y verify -f tools/ota_allowed_signers -I meshcore-ota@tth-pub
|
||
-n meshcore-ota -s SHA256SUMS.sig < SHA256SUMS`. Your own build with your own
|
||
key: `[ota] pubkey` in `platformio.local.ini`.
|
||
* The first `*-ota` image is flashed the usual way (above), later ones go as
|
||
deltas. Tools: `tools/ota_push.py` (USB), `tools/ota_mesh_push.py` (over the
|
||
mesh through a companion; needs the `meshcore` Python library, takes the
|
||
admin password from `[secrets] admin_pw` in `platformio.local.ini`),
|
||
`tools/ota_pack.py info`. How it works and bench numbers:
|
||
[docs/ota.md](docs/ota.md).
|
||
* **Experimental**: tried on XIAO boards on the bench over USB and over the
|
||
mesh (1 hop). A bad new firmware has nothing to fall back to (no second
|
||
bank) -- try a new release on one node within reach first. Costs ~10 kB of
|
||
RAM.
|
||
|
||
### Build
|
||
|
||
* Version stamping in every nRF52 env (`v1.18.0-tth<sha>`, `+` = dirty tree),
|
||
base version from the upstream tag (`tools/build_version.py`).
|
||
* `tools/`: host tools for the nodes -- consoles (USB, BLE), flashing, bench
|
||
tests, diagnostics ([tools/README.md](tools/README.md)). Board names come
|
||
from a local config outside the repo (`tools/config.example.ini`).
|
||
* `hardware/cavity-box`: parametric enclosure for a cavity filter on a mast.
|
||
|
||
---
|
||
|
||
## About MeshCore
|
||
|
||
MeshCore is a lightweight, portable C++ library that enables multi-hop packet routing for embedded projects using LoRa and other packet radios. It is designed for developers who want to create resilient, decentralized communication networks that work without the internet.
|
||
|
||
## 🔍 What is MeshCore?
|
||
|
||
MeshCore now supports a range of LoRa devices, allowing for easy flashing without the need to compile firmware manually. Users can flash a pre-built binary using tools like Adafruit ESPTool and interact with the network through a serial console.
|
||
MeshCore provides the ability to create wireless mesh networks, similar to Meshtastic and Reticulum but with a focus on lightweight multi-hop packet routing for embedded projects. Unlike Meshtastic, which is tailored for casual LoRa communication, or Reticulum, which offers advanced networking, MeshCore balances simplicity with scalability, making it ideal for custom embedded solutions, where devices (nodes) can communicate over long distances by relaying messages through intermediate nodes. This is especially useful in off-grid, emergency, or tactical situations where traditional communication infrastructure is unavailable.
|
||
|
||
## ⚡ Key Features
|
||
|
||
* Multi-Hop Packet Routing
|
||
* Devices can forward messages across multiple nodes, extending range beyond a single radio's reach.
|
||
* Supports up to a configurable number of hops to balance network efficiency and prevent excessive traffic.
|
||
* Nodes use fixed roles where "Companion" nodes are not repeating messages at all to prevent adverse routing paths from being used.
|
||
* Supports LoRa Radios – Works with Heltec, RAK Wireless, and other LoRa-based hardware.
|
||
* Decentralized & Resilient – No central server or internet required; the network is self-healing.
|
||
* Low Power Consumption – Ideal for battery-powered or solar-powered devices.
|
||
* Simple to Deploy – Pre-built example applications make it easy to get started.
|
||
|
||
## 🎯 What Can You Use MeshCore For?
|
||
|
||
* Off-Grid Communication: Stay connected even in remote areas.
|
||
* Emergency Response & Disaster Recovery: Set up instant networks where infrastructure is down.
|
||
* Outdoor Activities: Hiking, camping, and adventure racing communication.
|
||
* Tactical & Security Applications: Military, law enforcement, and private security use cases.
|
||
* IoT & Sensor Networks: Collect data from remote sensors and relay it back to a central location.
|
||
|
||
## 🚀 How to Get Started
|
||
|
||
- Watch the [MeshCore QuickStart Playlist](https://www.youtube.com/watch?v=iaFltojJrAc&list=PLshzThxhw4O4WU_iZo3NmNZOv6KMrUuF9) by The Comms Channel
|
||
- Watch the [MeshCore Technical Presentation](https://www.youtube.com/watch?v=OwmkVkZQTf4) by Liam Cottle.
|
||
- Read through our [Frequently Asked Questions](./docs/faq.md) and [Documentation](https://docs.meshcore.io).
|
||
- Flash the MeshCore firmware on a supported device.
|
||
- Connect with a supported client.
|
||
|
||
For developers:
|
||
|
||
- Install [PlatformIO](https://docs.platformio.org) in [Visual Studio Code](https://code.visualstudio.com).
|
||
- Clone and open the MeshCore repository in Visual Studio Code.
|
||
- For the LilyGO T3 STM32, see the [board build and flashing guide](./variants/lilygo_t3_stm32/README.md).
|
||
- See the example applications you can modify and run:
|
||
- [Companion Radio](./examples/companion_radio) - For use with an external chat app, over BLE, USB or Wi-Fi.
|
||
- [KISS Modem](./examples/kiss_modem) - Serial KISS protocol bridge for host applications. ([protocol docs](./docs/kiss_modem_protocol.md))
|
||
- [Simple Repeater](./examples/simple_repeater) - Extends network coverage by relaying messages.
|
||
- [Simple Room Server](./examples/simple_room_server) - A simple BBS server for shared Posts.
|
||
- [Simple Secure Chat](./examples/simple_secure_chat) - Secure terminal based text communication between devices.
|
||
- [Simple Sensor](./examples/simple_sensor) - Remote sensor node with telemetry and alerting.
|
||
|
||
The Simple Secure Chat example can be interacted with through the Serial Monitor in Visual Studio Code, or with a Serial USB Terminal on Android.
|
||
|
||
## ⚡️ MeshCore Flasher
|
||
|
||
We have prebuilt firmware ready to flash on supported devices.
|
||
|
||
- Launch https://meshcore.io/flasher
|
||
- Select a supported device
|
||
- Flash one of the firmware types:
|
||
- Companion, Repeater or Room Server
|
||
- Once flashing is complete, you can connect with one of the MeshCore clients below.
|
||
|
||
## 📱 MeshCore Clients
|
||
|
||
**Companion Firmware**
|
||
|
||
The companion firmware can be connected to via BLE, USB or Wi-Fi depending on the firmware type you flashed.
|
||
|
||
- Web: https://app.meshcore.nz
|
||
- Android: https://play.google.com/store/apps/details?id=com.liamcottle.meshcore.android
|
||
- iOS: https://apps.apple.com/us/app/meshcore/id6742354151?platform=iphone
|
||
- NodeJS: https://github.com/liamcottle/meshcore.js
|
||
- Python: https://github.com/fdlamotte/meshcore-cli
|
||
|
||
**Repeater and Room Server Firmware**
|
||
|
||
The repeater and room server firmware can be set up via USB in the web config tool.
|
||
|
||
- https://config.meshcore.io
|
||
|
||
They can also be managed via LoRa in the mobile app by using the Remote Management feature.
|
||
|
||
## 🛠 Hardware Compatibility
|
||
|
||
MeshCore is designed for devices listed in the [MeshCore Flasher](https://meshcore.io/flasher)
|
||
|
||
## 📜 License
|
||
|
||
MeshCore is open-source software released under the MIT License. You are free to use, modify, and distribute it for personal and commercial projects.
|
||
|
||
## Contributing
|
||
|
||
Please submit PR's using 'dev' as the base branch!
|
||
For minor changes just submit your PR and we'll try to review it, but for anything more 'impactful' please open an Issue first and start a discussion. It is better to sound out what it is you want to achieve first, and try to come to a consensus on what the best approach is, especially when it impacts the structure or architecture of this codebase.
|
||
|
||
Here are some general principles you should try to adhere to:
|
||
* Keep it simple. Please, don't think like a high-level lang programmer. Think embedded, and keep code concise, without any unnecessary layers.
|
||
* No dynamic memory allocation, except during setup/begin functions.
|
||
* Use the same brace and indenting style that's in the core source modules. (A .clang-format is probably going to be added soon, but please do NOT retroactively re-format existing code. This just creates unnecessary diffs that make finding problems harder)
|
||
|
||
Help us prioritize! Please react with thumbs-up to issues/PRs you care about most. We look at reaction counts when planning work.
|
||
|
||
### Running unit tests
|
||
|
||
To run unit tests, run the following command:
|
||
|
||
```bash
|
||
pio test --environment native --verbose
|
||
```
|
||
|
||
## Road-Map / To-Do
|
||
|
||
There are a number of fairly major features in the pipeline, with no particular time-frames attached yet. In very rough chronological order:
|
||
- [X] Companion radio: UI redesign
|
||
- [X] Repeater + Room Server: add ACL's (like Sensor Node has)
|
||
- [X] Standardise Bridge mode for repeaters
|
||
- [ ] Repeater/Bridge: Standardise the Transport Codes for zoning/filtering
|
||
- [X] Core + Repeater: enhanced zero-hop neighbour discovery
|
||
- [ ] Core: round-trip manual path support
|
||
- [ ] Companion + Apps: support for multiple sub-meshes (and 'off-grid' client repeat mode)
|
||
- [ ] Core + Apps: support for LZW message compression
|
||
- [ ] Core: dynamic CR (Coding Rate) for weak vs strong hops
|
||
- [ ] Core: new framework for hosting multiple virtual nodes on one physical device
|
||
- [ ] V2 protocol spec: discussion and consensus around V2 packet protocol, including path hashes, new encryption specs, etc
|
||
|
||
## 📞 Get Support
|
||
|
||
- Report bugs and request features on the [GitHub Issues](https://github.com/meshcore-dev/meshcore/issues) page.
|
||
- Find additional guides and components on [my site](https://buymeacoffee.com/ripplebiz).
|
||
- Join [MeshCore Discord](https://meshcore.gg) to chat with the developers and get help from the community.
|