get chip tells the silicon and whether SWD can read the flash
O tomto forku (meshcore-tth)
English version below -- experimental firmware, not meant for regular users.
Warning
Experimentální firmware – není určený pro běžné uživatele. Tenhle fork i všechny jeho releasy jsou osobní vývojová větev pro uzly jedné malé sítě: rolling release nad upstreamovou větví
dev, sestavovaný automaticky zhruba dvakrát denně, bez stabilního kanálu, bez podpory a vyzkoušený jen na našich deskách. Může obsahovat chyby, které uzel vyřadí z provozu, a vrátit ho pak jde jen s USB nebo BLE v ruce. Pro běžný provoz nahrajte oficiální MeshCore (flasher.meshcore.io).
Fork projektu 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)
Po nahrání je zapnutý jen FairnessLimiter, s limity se zhruba
dvojnásobnou rezervou nad 30 dní skutečného provozu CZ meshe: na kanál dávka
100 zpráv a pak jedna za 30 s, na odesílatele 150 a jedna za 10 s, na
původce advertu 30 a jeden za 10 min. Je to síť na utržené floody, ne kvóta;
fairness off ho vypne natrvalo. Okno na adverty, filtry a dry-run jsou
vypnuté, dokud je nezapnete.
- 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, 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. Míří na uzly, které advertují každou minutu. - Dry-run –
fairness dryrun onzapočítá každý verdikt, ale přepošle i tak;fairness airukáže ušetřený (nebo ušetřitelný) airtime podle důvodu. - Filtr kanálů – na kanálech, jejichž klíč repeater zná (Public
a
#hashtagkaná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í. Ssse kanál neodřízne, ale přiškrtí (jeden paket zassekund). - 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 onzapočítá každý verdiktfilter, ale přepošle i tak.
Diagnostika a provoz
Všechny příkazy forku, kde je který build má a výchozí hodnoty: docs/tth-commands.md.
Repeater, room server i senzor (všechno s textovou konzolí) mají:
- Watchdogy rádia. Hardwarový watchdog chytí jen zamrzlou smyčku; dva naše
uzly ale byly nalezeny hluché s běžící smyčkou a pomohl až restart.
set radio.silence <min>– hluchý přijímač: když se za<min>minut nepohne čítač přijatých rámců (počítá se i rámec s chybou CRC), uzel napřed znovu nahodí příjem, a když ani to nepomůže, restartuje se. Každý takový restart zdvojnásobí práh pro příští start (až 16×), první přijatý rámec ho vrátí, takže tiché místo neskončí ve smyčce restartů. Uloží se; ve výchozím stavu vypnutý (0) – práh volte s rezervou nad nejdelší běžné ticho na místě.- Zaseknuté vysílání (jen repeater): pakety čekají ve frontě a čítač
odeslaných se nehýbe → znovu nahodí rádio, pak restart. Prázdná fronta se
nepočítá. Zapnutý, 15 min (
RADIO_TXSTALL_MIN);set radio.txstall <min>|offplatí jen do restartu. get radio.reboots– kolik restartů watchdogy udělaly (přežije i výpadek napájení);get boot– proč se deska naposledy resetovala a záznam o hardfaultu (vypíše se i při startu).
dfu [uf2|serial|ota]– spolehlivý reboot do bootloaderu (jen z lokální konzole);i2c– sken sběrnice.
Repeater navíc:
blink(rozbliká LED, i přes mesh – najdete uzel na stožáru),txpwr(vysílací výkon do restartu, s verdiktem RadioLibu), čítače chyb vysílání ve stavové odpovědi.- Jen observer varianty (
*-observer): textová konzole přes BLE vedle USB,ble on|offulož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. - Taky jen observer varianty: 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. - Jen vlastní buildy, ne releasy:
- kanálový bot (
BOT_CHANNEL_PSK:!link,!path,!snr,!heard,!noise,!ping,!help, výběr přesBOT_COMMANDS, cooldown na odesílatele, ignore list) – odpovídá, aniž by přeposílal; RADIO_DIAG:radiostat(stav přijímače SX1262 bez zásahu) aradiokick rx|clrirq|standby|agc(jeden krok obnovy, od nejjemnějšího – první, který pomůže, ukáže rozbitou vrstvu);PIN_DIAG:dio1(stav přerušení v čipu proti úrovni na pinu – který konec mrtvé linky DIO1 je přerušený);LORA_POLL_IRQ: provoz bez DIO1 pro desku s mrtvou linkou přerušení.
- kanálový bot (
Opravy jádra
- Ochrana proti přehrání admin příkazů přežije reboot. Upstream si
poslední timestamp klienta drží jen v RAM, takže po každém restartu projde
libovolný zachycený příkaz znovu – zachycený
rebootuzel restartuje pořád dokola. Repeater, room server i sensor ho teď zapíšou do flash dřív, než příkaz provedou (/s_acl_ts0|1, střídavě s kontrolním součtem, takže ho nesmaže ani výpadek napájení při zápisu). Timestamp víc než den před hodinami uzlu (ACL_TS_MAX_AHEAD) se přijme, ale neuloží, aby companion s rozhozenými hodinami nezamkl admina. Ukládá se jen u adminů: host smí jen číst a s prázdným guest heslem se jím stane kdokoli, takže by každý jeho dotaz znamenal zápis do flash. Klientů se to nijak netýká. - Hesla nejde hádat přes éter plnou rychlostí. Upstream kontroluje každý
login bez omezení a na špatné heslo ani neodpoví. Po 4 špatných heslech
během 3 minut (
LOGIN_FAIL_MAX,LOGIN_FAIL_SECS) se hesla do konce okna nekontrolují. Klient, který už je v ACL jako admin, projde vždy – login jeho jménem nikdo jiný poslat nedokáže, takže útok adminy nezamkne. - Přehraný login bez hesla už nevyvolá flood odpověď. Login klienta z ACL s prázdným heslem neměl ochranu proti přehrání; útočník tím nic nezískal, ale každá kopie donutila uzel poslat odpověď floodem přes celý mesh.
- TRACE už nepřipisuje cestu za konec payloadu; parsování TRACE/PATH
a
Packet::readFromhlídají meze. markSeenje zase idempotentní (odesílací cesta ujídala okno deduplikace).- Záložní výpočet v
calcMaxPacketMillisuž 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;
ContactInfose 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:
set batt.icon on, prahyset batt.icon.lo|hi <mV>(výchozí vypnuté; dlouhé jméno ikonu nepojme a příkaz na to upozorní). - Volitelný RX duty cycle (
set radio.rxps off|on|balanced|max, jemnějilevel <1-10>; port PowerSaving z EasySkyMesh): SX1262 mezi krátkými okny poslechu spí. Ve veřejných buildech je zabudovaný a vypnutý;maxna lavici ušetřil ~2,3 mA bez ztráty paketů (docs/power.md), na ostrém meshi ale jeden náš stožár ztratil 16 % příjmu – zapínat s rozmyslem. 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): 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).
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 dutypřežije reboot, kopie data sestavení má hlídanou délku. Export privátního klíče, čtení BLE PINu a jeho změna (i přes CLIset pin) jdou jen přes spárované BLE, ne přes USB, UART ani WiFi/TCP, a odpověď s klíčem či PINem jde jen tam, odkud přišel dotaz. (Merge v1.17 tu kontrolu potichu vyřadil; build bez BLE bere své jediné rozhraní dál jako důvěryhodné.) 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, 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éafje 9); - repeater: regiony
czacsvedle*– vlastnícz-<kraj>přidáš přesregion 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,#meshcorea#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.
BLE PIN companionu je veřejný 123456 (desky s displejem si losují
vlastní a ukážou ho). Kdo se s ním spáruje, má companion celý: zprávy,
kontakty, export privátního klíče. Po prvním spárování ho proto změň
v aplikaci. A s deskou v ruce nechrání nic ani PIN, ani heslo: flash není
zamčená a bootloader přijme jakýkoli firmware. Ztracený nebo ukradený uzel
ber jako vyzrazený – u repeateru změň admin heslo všude, kde bylo stejné,
a vyhoď jeho klíč z ACL; u companionu ber kanály, které na něm byly, jako
zná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).
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
Každý release je automatický build nad upstreamovým dev (viz upozornění
nahoře), ne stabilní verze. Nahrávejte ho jen na uzly, na které dosáhnete,
a nový release vždy nejdřív na jeden z nich.
Soubory jsou v 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 – Chrome, Edge nebo Chromium na počítači (Web Serial; ne Firefox ani Safari):
- Připoj desku přes USB.
- Klikni na Custom Firmware a vyber
.zippro svou desku. - Klikni na Enter DFU mode a vyber sériový port desky. Deska se restartuje do bootloaderu a objeví se jako nový port.
- Klikni na Flash! a vyber ten nový port. Zhruba 30 s, pak se deska restartuje do nového firmwaru.
- Console ve flasheru (nebo jakýkoli sériový terminál, 115200) ověří
výsledek:
verukážev1.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
*-otaobrazu plný balíček<deska>_<role>-ota-<release>.mcfw(jen přes USB/BLE) a delta….from-<starší release>.mcfwod 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
SHA256SUMSjsou podepsané klíčemmeshcore-ota@tth-puba*-otaobraz 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] pubkeyvplatformio.local.ini. - První
*-otaobraz 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 knihovnumeshcore, admin heslo bere z[secrets] admin_pwvplatformio.local.ini; s--sidejde přenos po vedlejším kanálu mimo sdílený mesh),tools/ota_pack.py info. Přenos samotný je OTA engine kolekce tth.meshcore (modulmeshcore_fw_ota), stejný kód pro nástroje i Ansible. Z telefonu: fork aplikace meshcore-open, správa repeateru → Firmware update (OTA), deltu si najde v releasu sám. Postup a čísla: docs/ota.md. - Experimentální i v rámci tohoto forku: obrazy přicházejí s každým
releasem (viz upozornění nahoře) a nemají druhou banku ani automatický
návrat. Vadný firmware, který nabootuje, běží, dokud nepošlete další;
takový, který nenabootuje, chce USB/BLE DFU v ruce. Vyzkoušeno na lavici
(XIAO, USB, mesh, vedlejší kanál) a od 13. 11. 2026 na dvou našich
stožárech. Proti obrazu, který nabootuje s mrtvým rádiem, jsou watchdogy
rádia (viz Diagnostika a provoz): pro uzly, kam posíláte OTA, zapněte
set radio.silence. 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). 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.
Warning
Experimental firmware -- not meant for regular users. This fork and all its releases are a personal development branch for the nodes of one small network: a rolling release on upstream
dev, built automatically about twice a day, with no stable channel, no support, and tried only on our own boards. It may carry bugs that take a node out of service, and getting one back then needs USB or BLE in hand. For everyday use flash the official MeshCore (flasher.meshcore.io).
A fork of 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)
After flashing only the FairnessLimiter is on, with limits about twice
above 30 days of real CZ mesh traffic: per channel a burst of 100 messages,
then one per 30 s; per sender 150 and one per 10 s; per advert origin 30 and
one per 10 min. It is a net for runaway floods, not a quota; fairness off
switches it off for good. The advert window, the filters and dry-run stay
off until you turn them on.
- 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,
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's AdvertLimiter. Aimed at nodes that re-advertise every minute. - Dry-run --
fairness dryrun oncounts every verdict but forwards anyway;fairness airreports the airtime shed (or that would be) per reason. - Channel filter -- on channels whose key the repeater knows (Public and
#hashtagchannels), 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. Withsecsthe channel is throttled (one packet persecs) 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 oncounts everyfilterverdict but forwards anyway.
Diagnostics and operations
Every command of the fork, which builds have it and the defaults: docs/tth-commands.md.
Repeater, room server and sensor (everything with a text console) have:
- Radio watchdogs. The hardware watchdog only catches a frozen loop; two
of our nodes were found deaf with the loop running, and only a reboot
helped.
set radio.silence <min>-- deaf receiver: when the received-frame counter does not move for<min>minutes (a frame with a CRC error counts), the node re-arms its receiver first and reboots if that does not help either. Each such reboot doubles the threshold for the next boot (up to 16x) and the first frame received resets it, so a quiet site does not end in a reboot loop. Saved; off by default (0) -- pick a threshold well above the longest normal quiet spell of the site.- Stalled TX (repeater only): packets wait in the queue and the sent
counter does not move -> re-arm the radio, then reboot. An empty queue
never counts. On, 15 min (
RADIO_TXSTALL_MIN);set radio.txstall <min>|offholds until the next reboot. get radio.reboots-- reboots done by the watchdogs (survives power loss);get boot-- why the board last reset, and the hardfault record (also printed at boot).
dfu [uf2|serial|ota]-- a deterministic reboot into the bootloader (local console only);i2c-- bus scan.
The repeater also has:
blink(flashes the LED, also over the mesh -- finds a node on a mast),txpwr(TX power until reboot, with RadioLib's verdict), TX-failure counters in the status reply.- Observer variants only (
*-observer): text console over BLE next to USB,ble on|offsaved 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. - Also observer variants only: a 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. - Own builds only, not in the releases:
- channel bot (
BOT_CHANNEL_PSK:!link,!path,!snr,!heard,!noise,!ping,!help, narrowed byBOT_COMMANDS, per-sender cooldown, ignore list) -- answers without repeating; RADIO_DIAG:radiostat(SX1262 receiver state, hands off) andradiokick rx|clrirq|standby|agc(one recovery step at a time, gentlest first -- the first that helps names the broken layer);PIN_DIAG:dio1(the chip's IRQ status against the level on the pin -- which end of a dead DIO1 line is broken);LORA_POLL_IRQ: DIO1-less operation for a board with a dead IRQ line.
- channel bot (
Core fixes
- Replay protection of admin commands survives a reboot. Upstream keeps a
client's last timestamp in RAM only, so after every restart any captured
command is accepted again -- a captured
rebootreboots the node forever. Repeater, room server and sensor now write it to flash before acting on the command (/s_acl_ts0|1, alternating with a checksum, so a power cut mid-write does not lose it). A timestamp more than a day ahead of the node's clock (ACL_TS_MAX_AHEAD) is accepted but not stored, so a companion with a runaway clock cannot lock its admin out. Only admins are stored: a guest can only read, and with the empty guest password anybody is one, so its every request would be a flash write. Nothing changes for clients. - Passwords can no longer be guessed over the air at full speed. Upstream
checks every login without a limit and does not even answer a wrong one.
After 4 wrong passwords within 3 minutes (
LOGIN_FAIL_MAX,LOGIN_FAIL_SECS) no password is checked until the window ends. A client that is already an admin in the ACL always gets through -- nobody else can send a login in its name, so the attack cannot lock the admins out. - A replayed blank-password login no longer floods a reply. A login from a client in the ACL with an empty password had no replay check; replayed, it gained nothing, but every copy made the node flood its reply over the mesh.
- TRACE no longer appends its path past the end of the payload; TRACE/PATH
parsing and
Packet::readFromare bounds-checked. markSeenis idempotent again (the send path was eating the dedup window).calcMaxPacketMillisfallback 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;
ContactInfozeroed 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:
set batt.icon on, thresholdsset batt.icon.lo|hi <mV>(off by default; a long name has no room for it and the command says so). - Optional RX duty cycle (
set radio.rxps off|on|balanced|max, finerlevel <1-10>; ported from EasySkyMesh PowerSaving): the SX1262 sleeps between short listening windows. Built into the public releases and off;maxsaved ~2.3 mA on the bench with no packet loss (docs/power.md), but on the live mesh one of our masts lost 16 % of its reception -- switch it on with care. 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): 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).
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 dutypersists, bounded build-date copy. Private key export, reading the BLE PIN and changing it (CLIset pinincluded) work only over paired BLE, never over USB, a UART or WiFi/TCP, and the reply that carries the key or PIN goes back only where the request came from. (The v1.17 merge had silently disabled that gate; a build without BLE still trusts its one transport.) 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 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 deprecatedafreads 9); - repeater: regions
czandcsnext to*-- add your owncz-<kraj>withregion 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,#meshcoreand#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.
The companion's BLE PIN is the public 123456 (boards with a display
draw their own and show it). Whoever pairs with it owns the companion:
messages, contacts, private key export. So change it in the app after the
first pairing. And with the board in hand neither the PIN nor a password
protects anything: the flash is not locked and the bootloader takes any
firmware. Treat a lost or stolen node as compromised -- for a repeater,
change the admin password wherever it was the same and drop its key from
ACLs; for a companion, treat the channels it held as known.
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).
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
Every release is an automatic build on upstream dev (see the warning
above), not a stable version. Flash it only on nodes you can reach, and each
new release on one of them first.
Files are in 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 -- Chrome, Edge or Chromium on a computer (Web Serial; not Firefox or Safari):
- Connect the board over USB.
- Click Custom Firmware and choose the
.zipfor your board. - Click Enter DFU mode and pick the board's serial port. The board restarts into its bootloader and shows up as a new port.
- Click Flash! and pick that new port. About 30 s, then the board restarts into the new firmware.
- Console in the flasher (or any serial terminal, 115200) checks the
result:
vershowsv1.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
*-otaimage comes with a full package<board>_<role>-ota-<release>.mcfw(USB/BLE only) and a delta….from-<earlier release>.mcfwfrom 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 applywants the battery at 3.8 V or more unless the node runs on USB. - Packages and
SHA256SUMSare signed bymeshcore-ota@tth-pub, and an*-otaimage 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] pubkeyinplatformio.local.ini. - The first
*-otaimage 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 themeshcorePython library, takes the admin password from[secrets] admin_pwinplatformio.local.ini;--sidecarries the transfer on a side channel, off the shared mesh),tools/ota_pack.py info. The transfer itself is the OTA engine of the tth.meshcore Ansible collection (modulemeshcore_fw_ota), one code for the tools and Ansible. From a phone: the meshcore-open fork, repeater management → Firmware update (OTA), which finds the delta in the release by itself. How it works and bench numbers: docs/ota.md. - Experimental even within this fork: the images come with every
release (see the warning above) and have no second bank and no automatic
rollback. A bad firmware that boots keeps running until you push the next
one; one that does not boot needs USB/BLE DFU in hand. Tried on the bench
(XIAO, USB, mesh, side channel) and on two of our masts since 13. 11. 2026.
The radio watchdogs (see Diagnostics and operations) catch an image that
boots with a dead radio: switch
set radio.silenceon for nodes you push to. 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). 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.
Níže je README upstreamového MeshCore. Jeho flasher, klienti a návody se týkají oficiálního firmwaru, ne releasů tohoto forku. / Below is upstream MeshCore's README: its flasher, clients and guides refer to the official firmware, not to this fork's releases.
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 by The Comms Channel
- Watch the MeshCore Technical Presentation by Liam Cottle.
- Read through our Frequently Asked Questions and Documentation.
- Flash the MeshCore firmware on a supported device.
- Connect with a supported client.
For developers:
- Install PlatformIO in Visual Studio Code.
- Clone and open the MeshCore repository in Visual Studio Code.
- For the LilyGO T3 STM32, see the board build and flashing guide.
- See the example applications you can modify and run:
- Companion Radio - For use with an external chat app, over BLE, USB or Wi-Fi.
- KISS Modem - Serial KISS protocol bridge for host applications. (protocol docs)
- Simple Repeater - Extends network coverage by relaying messages.
- Simple Room Server - A simple BBS server for shared Posts.
- Simple Secure Chat - Secure terminal based text communication between devices.
- 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.
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
📜 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:
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:
- Companion radio: UI redesign
- Repeater + Room Server: add ACL's (like Sensor Node has)
- Standardise Bridge mode for repeaters
- Repeater/Bridge: Standardise the Transport Codes for zoning/filtering
- 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 page.
- Find additional guides and components on my site.
- Join MeshCore Discord to chat with the developers and get help from the community.