The mesh, receiving: MeshCore
The device is a MeshCore chat node that listens. A Mesh Service runs in the background on the Radio Service, keeps a node list from the adverts it hears and the messages of the channels you follow, and a Mesh App shows them.…
Status: done, released as v0.26.0. Every "Done when" was checked against a Heltec V4 but range outside, which waits for a battery for the Heltec.
Goal: the device is a MeshCore chat node that listens. A Mesh Service runs in the background on the Radio Service, keeps a node list from the adverts it hears and the messages of the channels you follow, and a Mesh App shows them. Nothing in M4 transmits: identity, adverts, sending and Direct Messages are M5 (docs/milestones/M5.md). Why MeshCore and not Meshtastic: ADR 0011.
Reference node: a Heltec V4 flashed with upstream's BLE companion build (heltec_v4_companion_radio_ble), driven from the official MeshCore phone app, with af 9 set so it stays within 10% airtime (M5, Q305). It sends the known adverts and messages every "Done when" below is checked against. Whoever else is on the air in Brussels is a bonus, not a test.
What we already have: M3's Radio Service and LoRa Scanner, and lib/meshcore (PR #96): MeshCore's header and path, adverts read, the public channel decrypted. Two discovery packets were decoded on the device; no advert or message has been heard on air yet.
Known limits:
- A device that is off hears nothing. The G0 long press is deep sleep; messages sent meanwhile are lost. Nothing stores them for us until M6 (room servers).
- The device is deafer than it should be: about 15 dB of its noise floor is its own (issue #20). Range against the Heltec gets measured, not assumed.
Measured
Step 1, the vendored core (2026-11-10). Upstream at 81dbae5, unchanged, in lib/meshcore_upstream (README, PATCHES.md), with port/ standing in for the libraries upstream builds with.
- Host tests (
test/test_meshcore_upstream, 9 tests): RFC 8032's keys and signatures, made orlp's way, are the standard's; 32 random keys and signatures are libsodium's own; upstream's known-good test key derives its public key and passes upstream's own key-exchange check; the key exchange is libsodium's X25519 on the converted keys, and gives nothing for a small-order key; identities sign, verify, exchange keys and survive being written out and read back; HMAC-SHA256 gives RFC 4231's result; upstream's code reads test_meshcore's public channel message (made with openssl) and refuses it with one bit changed; what it encrypts it decrypts.Aes128(lib/meshcore) gained encryption, with FIPS 197's block as its test. The host tests now link libsodium (libsodium-devin the build image and in CI) and findArduino.handStream.hintest/arduino_shim. - libssh had to give up its own Ed25519. libsodium's verification object also defines
crypto_sign_ed25519_open, which libssh's copy defines too: the two didn't link.scripts/libssh_filter.pynow leaves libssh'sed25519.c,fe25519.c,ge25519.candsc25519.cout, and it uses libsodium's, which keeps its keys the same way (the seed, then the public key). Checked on the device against OpenSSH in a container: the server's fingerprint is the onessh-keygen -lfprints, and the key the device made before ("Accepted publickey") still logs in.
Cost, release build:
| Build | Flash | Static RAM |
|---|---|---|
main at 21adee1 | 2,509,123 bytes | 58,628 bytes |
| libssh on libsodium's Ed25519 | 2,416,199 (−90.7 KB) | 58,684 |
and upstream's chat mesh linked in (a throwaway probe: BaseChatMesh with stub radio, clocks, tables and an 8-packet pool) | 2,453,991 (+36.9 KB) | 69,812 (+10.9 KB) |
The core costs 36.9 KB of flash, less than libssh's table freed. Most of the probe's RAM is upstream's own contact table: BaseChatMesh keeps MAX_CONTACTS (32) plus 8 anonymous ContactInfos of 184 bytes each, 7.4 KB, and the pool's 8 packets of 260 bytes, 2 KB.
For Q297: upstream keeps its contacts in RAM itself, so the node list is that table. At 184 bytes each, Q297's 100 nodes would have been about 20 KB, not the 10–12 KB estimated; Q297 now keeps 50 (2026-11-10).
Step 3, the radio shared (2026-11-10). The Radio Service has a fourth kind of client, Mesh, always on MeshCore's settings (Q292). Who gets the radio is lora::planRadio (lib/lora, test/test_radio_plan, 8 tests): the Scanner's clients (its App, a Capture, lora rx) come first; on the same settings as the mesh, preset or typed in, both read the same packets; on others, or during a Sweep, the mesh is paused. The ring is 32 packets while the Scanner listens and 8 for the mesh alone: a new length keeps the newest packets. Until the Mesh Service exists, lora mesh on|off holds the radio for it. Checked on the device:
| Check | Result |
|---|---|
lora mesh on, nothing else | Listening on MeshCore, ring of 8; 2.4 KB of heap (84,128 free against 86,588 asleep), where the Scanner's ring was 9.8 KB |
| The Scanner opened on MeshCore | Ring of 32, the mesh listening; a packet received before it opened is in its list |
| The Scanner on LongFast | "the mesh is paused, the Scanner has the radio"; lora status: "paused, the Scanner is on LongFast" |
| Back to MeshCore | "the mesh listens again", no restart of the radio for the same settings |
| A Sweep | "the mesh is paused by a Sweep"; stopped, both listen again on MeshCore |
| The Scanner closed while on LongFast | The radio goes back to MeshCore for the mesh, ring of 8 |
lora mesh off | Asleep, as before M4 |
Step 4, the Mesh Service (2026-11-10).
lib/mesh(host-tested,test/test_mesh_node, 9 tests):MeshNode, upstream'sBaseChatMeshgiven packets and never a way to send. Upstream checks the signature, drops replays and duplicates (a repeater's copy is the same packet), keeps 50 nodes and drops the least recently heard (shouldOverwriteWhenFull), and reads the channels;MeshNodecounts what upstream drops silently (forged, replayed, on channels not followed) and keeps each node's RSSI, SNR and hops, which upstream's table doesn't. Its identity is made at each start and never sent (Q288). Upstream's packet pool and duplicate table (StaticPoolPacketManager,SimpleMeshTables) are vendored too. Channels (mesh_channels): Public, hashtag channels from their name (upstream's own example,#test, gives its key), private ones from 32 hex digits; at most 8, kept in Settings (MeshChannels). The card's formats (mesh_log):/mesh/nodes.log, a line per verified advert, the newest for a key winning;/mesh/<name>-<hash>.log, a line per message; tab-separated plain text (Q300).MeshService(src): on whileSettings > Mesh(MeshEnabled, on by default) is; reads the Radio Service's packets received on MeshCore's settings, writes nodes and messages to the card, keeps the newest messages in RAM (50 a channel, 12 KB in all, the oldest anywhere going first), and at start gives upstream the 50 most recently heard nodes fromnodes.log.mesh status,mesh nodes,mesh channels,mesh channel add|remove,mesh rx on|off,mesh on|off(Q302).- libsodium had no random source. Its
sodium_init()reads/dev/urandom, which the ESP32 doesn't have, and aborts: the first build crashed at start (the device went back to the previous firmware by itself, ADR 0005).platform/sodium_randomgives it the chip's generator at boot. Step 1 missed it: verifying a signature doesn't ask for random numbers; making a key does. Since step 1, the SSH App making a new key would have crashed the same way: not tried on the device, which would have replaced the owner's key.
Checked on the device with packets made on the PC (Ed25519 and AES from Python's cryptography) and lora inject; a console line holds 240 characters, so adverts of 114 bytes at most:
| Check | Result |
|---|---|
| An advert with a position | "new node 50b29e9f "Ann" (chat)... with a position" |
| The same advert again | Nothing: a duplicate |
| A repeater's advert, one hop | A new node, "repeater", 1 hop |
| Ann's key, an older timestamp | Dropped, replays 1 |
| One bit of a signature changed | Dropped, counted as forged |
| Ann's key, newer | The same node, its name updated |
A message on #test, after mesh channel add #test | Read on channel 1; #elsewhere counted as not followed |
/mesh/nodes.log, public-11.log, test-d9.log | A line each, as mesh_log writes them |
| Restarted | "3 nodes from the card", #test still followed; Ann's older advert still a replay |
| Free heap, mesh on | About 64 KB, against about 86 KB off: 21 KB for the node (upstream's tables, its pool, ours), the ring and the history |
Not checked yet: a card missing or over 90 % (the history then stays in RAM: mesh status says "NOT SAVED"); real packets on air (step 6, with the Heltec); IRC on TLS with the mesh on.
Cost: 2,450,519 bytes of flash (+32.7 KB on step 3), 58,588 bytes of static RAM: the node is made on the heap, only while the mesh is on.
Step 5, the Mesh App (2026-11-10). Channels with their unread counts, a channel's messages (newest at the bottom, from the RAM history), the nodes (kind, when, distance when both sides have a position) and a node's page (signal, hops, position, distance and bearing); a adds a channel (#name, or a name and its secret), d removes one after asking. What the rows and pages say is lib/mesh/mesh_view (host-tested, test/test_mesh_view, 5 tests). The header says when the mesh is off or paused, and "not saved" without a card. Settings > GNSS and radio: "Mesh" (Q290) and "Mesh sound", off: a message's Notification is shown without the tone or the LED (NotificationLevel::Quiet). Status Bar: a dot after the radio's L while a channel has unread messages. A new Launcher icon, assets/icons/mesh.png.
Checked on the device, with screenshots: the channels; a #test message injected, giving "1 new", the dot and a silent Notification; the channel read, the count gone; the nodes, with a distance from the GNSS's own fix; a node's page, with the distance and bearing; a channel added with the keyboard and removed with the question; the header with the mesh off. One fix found doing so: a channel just added wasn't selected, since the App asked before the Mesh Service had taken the new list.
Not checked yet: the App with the Scanner holding the radio ("Paused"); a card missing ("not saved"); Mesh sound on. Older messages than the RAM holds are on the card but not shown: reading them back is left for later.
Cost: 2,464,303 bytes of flash (+13.8 KB on step 4).
Step 6, memory (2026-11-10). With the mesh on (about 21 KB then), the VPN up and IRC connected on TLS, free heap was 25.2 KB, 9.2 KB at the lowest. Worse, switching the mesh off and on again with IRC running found no room for it, and the Mesh Service tried again at every tick (100 ms), each time saying so: the heap went down to 2.7 KB. Without the mesh, the same set left 42.6 KB. Hence Q313 and Q314, and the retry every 30 s. After them, on the device:
| State | Free heap | Lowest |
|---|---|---|
| Mesh off | 84.1 KB | |
| Mesh on, idle | 72.3 KB: 11.8 KB for the mesh | |
| Mesh, IRC on TLS, the VPN and the Debug Console | 31.6 KB | 19.6 KB, during IRC's TLS handshake |
Not provoked: the mesh refused for want of memory after the change (one comparison and a timer).
Step 6, with the Heltec V4 (2026-11-10). Upstream's heltec_v4_companion_radio_ble, driven from the MeshCore phone app, a few metres from the device:
| Check | Result |
|---|---|
| Its flood advert | "new node 3062d5ca "Heltec V4" (chat), -34 dBm, SNR 13.2, 0 hops, with a position": signature checked |
| A message on Public | Read: "Heltec V4: Test", -36 dBm |
On #roro-test, not followed | Counted as "on channels not followed" |
On #roro-test once followed | Read: the hashtag key worked out as upstream's app does |
| On a private channel, its secret typed in | Read, -33 dBm |
| The Scanner on LongFast, a message sent | Not heard, the mesh saying it was paused; heard again once back on MeshCore |
| Screen off, IRC connected on TLS | Read; nothing dropped |
| The card out, a message sent | Read, kept in RAM; the App and mesh status said "not saved"; nothing written |
| Restarted | The Heltec back from the card, the channels from Settings |
Found on the way, and fixed:
- The mesh started inside
setup(), already deep in the main loop's stack: making the node's key there left 536 bytes of the loop's 8 KB stack, against 1,796 when started from a tick (measured both ways). It starts at the first tick now: 1,796 bytes with the mesh on. - Adding or removing a channel emptied every channel's messages in RAM. Each keeps its own now (
MessageHistory::remap, by name). - IRC's refusal said "close the SSH session" when the SSH App wasn't open: it says how much memory there is and what to close (SSH, the Scanner or the mesh). IRC wants 60 KB free to connect: with the mesh, the VPN and the console, a fresh start has about 70 KB; a LoRa Capture (its 32-packet ring) or a long session can leave less, and IRC then waits.
Real packets as tests: the five channel messages the Heltec sent, captured, are test_real_packets_from_upstream (test_mesh_node). Their path byte is 0x40: upstream's newer 2-byte path hashes. Its advert isn't kept, since it says where the Heltec is.
Memory with all of it: IRC connected on TLS with the mesh, the VPN and the console left 28.8 KB, and the lowest point reached 7.1 KB once, during IRC's traffic: below the ~12 KB Q86 accepted for a TLS moment. No crash; a risk to keep in mind with everything on (Q314).
Not measured: range outside. The Heltec has no battery and the device is out of the console's reach away from Wi-Fi.
The user guide's page: site/content/guide/mesh.md, with two screens that show nothing of where the device is (the node list and a node's page do).
Decisions (design round 2026-11-10)
| # | Decision |
|---|---|
| Q287 | MeshCore is the device's mesh protocol (ADR 0011, superseding ADR 0001 in part). Meshtastic stays in the LoRa Scanner: its presets and header decoder. |
| Q288 | M4 receives, M5 transmits, as M3 planned. A receive-only device can't get Direct Messages (nobody has its key before it advertises), so they are M5. "Nothing transmits" holds until airtime and identity are designed (they are, in M5). |
| Q289 | A chat node only in M4 and M5: never relays a flood or path packet, never a room server. Repeater, room server and the other roles are M6. |
| Q290 | The Mesh Service runs in the background while Settings → Mesh is on, the default. The radio stays receiving with the screen off and other Apps open (the SX1262 takes about 5 mA receiving). This replaces Q100's "radio sleeps unless the Scanner is open" whenever the mesh is on. |
| Q291 | The Scanner and the mesh share the radio. On the MeshCore preset, the Radio Service hands every packet to both, no pause. A Scanner preset with other settings, or a Sweep, takes the radio and pauses the Mesh Service visibly (as Q99 planned); it resumes when the Scanner leaves. |
| Q292 | One fixed preset: the Mesh Service always uses the EU MeshCore preset (869.618 MHz, 62.5 kHz, SF8, CR 4/8, sync word 0x12), a constant. No radio settings to change: M5's airtime cap is tied to this sub-band. Other settings are the Scanner's. |
| Q293 | Upstream's protocol core is vendored (ADR 0011): Dispatcher, Mesh, Packet, Identity, Utils, BaseChatMesh from meshcore-dev/MeshCore, MIT, with our adapters for the Radio Service, clocks and RNG, and a small Arduino.h/Stream shim for the host tests. Vendored in M4 although M4 only receives, so that M5 is mostly switching transmit on. The Scanner keeps lib/meshcore, its own small decoder. |
| Q294 | Pinned, bumped by hand. First pin: upstream 81dbae5 (2026-10-15) unless a newer one is taken at step 1. Each bump is its own pull request, upstream's changes summarised, test vectors re-run. Changes to upstream files stay in adapters; anything else goes in PATCHES.md. |
| Q295 | Ed25519 and X25519 from libsodium (already linked for WireGuard), not upstream's orlp/ed25519 and its 98 KB table. AES-128 and SHA-256 from what we have. Gate: host tests on vectors from upstream (signatures, key conversion, shared secret, a Direct Message and a channel message) prove the results byte-identical. |
| Q296 | A node is listed only once its advert's Ed25519 signature checks out. An advert whose timestamp isn't newer than the last one from the same key is a replay and dropped, as upstream does. Both counted in mesh status. |
| Q297 | Changed after step 1, then in step 6 (Q313). At most 24 nodes in RAM, upstream's own contact table (MAX_CONTACTS 24, plus its 8 anonymous ones, 184 bytes each), the least recently heard dropped first; all of them on the card. 100 was planned on an estimate of 10–12 KB, then 50 once step 1 measured 20 KB for 100; step 6 found the mesh had to be smaller still to live next to IRC on TLS and the VPN. |
| Q298 | Channels: Public, plus channels you add in the Mesh App: private (a name and a 16-byte secret typed in) and #hashtag (the secret derived from the name, as upstream does). |
| Q299 | History on the card, under /mesh/: one append-only log per channel, and the node list. Without a card, the last 50 messages per channel and the node list in RAM only, and the Mesh App says "not saved". |
| Q300 | History is plain text on the card. Anyone holding the card can read it; the Mesh guide says so. Encrypting it would need a key in the device and make the card unreadable on a computer. |
| Q301 | A Mesh App, separate from the Scanner. Channels: the list with unread counts, Enter opens a channel's messages, newest at the bottom. Nodes: name, kind, last heard, RSSI/SNR, hops, and distance and bearing when both the node and our GNSS have a position. Adding and removing channels. Status Bar: the radio mark gets an unread dot; a Notification for a new message, no sound by default. |
| Q302 | Console: mesh status (state, preset, counters: heard, verified, replays, undecodable, per channel; airtime used from M5), mesh nodes, mesh rx on/off (mesh packets on the consoles), in the style of lora. |
| Q303 | A reference node is required (Q104 carried over): the Heltec V4 above. Every "Done when" is checked against it. |
| Q304 | MeshCore's phone companion protocol (BLE or USB, for the official app to drive the device) is out of scope; M6. The device is its own UI, as ADR 0001 already said of Meshtastic's phone API. |
| Q313 | Decided in step 6 (2026-11-10). The mesh in about 12 KB (measured 11.8 KB at idle, against about 21 KB in step 4): 24 nodes in RAM (Q297); upstream's packet pool, the node's receive queue and the Radio Service's ring for the mesh at 4 packets, not 8; upstream's connections (room-server logins, nothing before M6) at 1, not 16; the messages kept in RAM at 4 KB in all, not 12 (50 a channel still, Q299). |
| Q314 | Decided in step 6. With VPN, IRC on TLS and the mesh all running, the steady floor of 40 KB (G1, Q86) isn't kept: about 31.6 KB free is accepted, as Q86 accepted the TLS dip. Without the mesh, VPN, IRC and the Debug Console already leave only 42.6 KB. Gemini's 55 KB start floor still makes a fetch refuse rather than run out. The mesh starts only with 32 KB free (20 KB left after it, Q86's floor for the firmware's own allocations), and otherwise tries again every 30 s, saying so once; the Mesh App says "Waiting for memory". |
Done when
- The upstream test vectors pass with libsodium on the host (Q295), and a tampered or replayed advert is refused (Q296). Met, and the Heltec's own messages are tests.
- The Heltec's advert puts it in the node list, with its name, kind and, if it sends one, its position, distance and bearing. Met.
- A message sent by the Heltec on Public, on a private channel and on a
#hashtagchannel shows in the Mesh App, with the unread dot and a Notification. Met. - History survives a restart with a card; without one, the Mesh App says "not saved" and still shows the session's messages. Met.
- The Mesh Service keeps receiving with the screen off and another App open, including IRC on TLS, with free heap above the floors (Q86), as Q314 lowered them with the VPN up. Met, at the floors Q314 set; once 7.1 KB at the lowest.
- The Scanner on the MeshCore preset sees the same packets while the mesh runs; another preset or a Sweep pauses the mesh visibly, and it resumes. Met.
- Range against the Heltec measured outside (RSSI/SNR at a few distances) and written here, next to issue #20. Not yet: the Heltec has no battery.
- Flash and RAM cost of the vendored core, libsodium's added use and the Mesh App measured and written here. Met.
- Nothing transmits: the Radio Service still has no transmit function (Q94); the Mesh Service's radio adapter refuses every send and counts it. Met: "sends refused 0" all along.
Work breakdown
- Vendor the core: upstream's files at the pinned commit,
PATCHES.md, the Arduino shim, a native build of it; flash and RAM cost measured. - Crypto on libsodium (host-tested): the identity and key-exchange adapter, upstream's vectors as tests.
- Radio Service, second user: packets handed to both the Scanner and the Mesh Service, the pause and resume (Q291), the fixed preset.
- Mesh Service: the Dispatcher on a receive-only radio adapter, the node list (Q296, Q297), channels (Q298), history on the card or in RAM (Q299),
meshcommands. - Mesh App: Channels, Nodes, adding channels, Status Bar dot, Notifications; the Settings switch.
- With the Heltec: every "Done when", range outside, the measurements written here; the user guide's Mesh page.
This page is generated from docs/milestones/M4.md in the repository. To change it, change that file and run site/tools/gen_dev_docs.py.