Milestones · M4

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-dev in the build image and in CI) and find Arduino.h and Stream.h in test/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.py now leaves libssh's ed25519.c, fe25519.c, ge25519.c and sc25519.c out, 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 one ssh-keygen -lf prints, and the key the device made before ("Accepted publickey") still logs in.

Cost, release build:

BuildFlashStatic RAM
main at 21adee12,509,123 bytes58,628 bytes
libssh on libsodium's Ed255192,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:

CheckResult
lora mesh on, nothing elseListening 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 MeshCoreRing 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 LongFastThe radio goes back to MeshCore for the mesh, ring of 8
lora mesh offAsleep, as before M4

Step 4, the Mesh Service (2026-11-10).

  • lib/mesh (host-tested, test/test_mesh_node, 9 tests): MeshNode, upstream's BaseChatMesh given 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; MeshNode counts 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 while Settings > 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 from nodes.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_random gives 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:

CheckResult
An advert with a position"new node 50b29e9f "Ann" (chat)... with a position"
The same advert againNothing: a duplicate
A repeater's advert, one hopA new node, "repeater", 1 hop
Ann's key, an older timestampDropped, replays 1
One bit of a signature changedDropped, counted as forged
Ann's key, newerThe same node, its name updated
A message on #test, after mesh channel add #testRead on channel 1; #elsewhere counted as not followed
/mesh/nodes.log, public-11.log, test-d9.logA 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 onAbout 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:

StateFree heapLowest
Mesh off84.1 KB
Mesh on, idle72.3 KB: 11.8 KB for the mesh
Mesh, IRC on TLS, the VPN and the Debug Console31.6 KB19.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:

CheckResult
Its flood advert"new node 3062d5ca "Heltec V4" (chat), -34 dBm, SNR 13.2, 0 hops, with a position": signature checked
A message on PublicRead: "Heltec V4: Test", -36 dBm
On #roro-test, not followedCounted as "on channels not followed"
On #roro-test once followedRead: the hashtag key worked out as upstream's app does
On a private channel, its secret typed inRead, -33 dBm
The Scanner on LongFast, a message sentNot heard, the mesh saying it was paused; heard again once back on MeshCore
Screen off, IRC connected on TLSRead; nothing dropped
The card out, a message sentRead, kept in RAM; the App and mesh status said "not saved"; nothing written
RestartedThe 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
Q287MeshCore is the device's mesh protocol (ADR 0011, superseding ADR 0001 in part). Meshtastic stays in the LoRa Scanner: its presets and header decoder.
Q288M4 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).
Q289A 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.
Q290The 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.
Q291The 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.
Q292One 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.
Q293Upstream'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.
Q294Pinned, 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.
Q295Ed25519 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.
Q296A 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.
Q297Changed 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.
Q298Channels: 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).
Q299History 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".
Q300History 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.
Q301A 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.
Q302Console: 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.
Q303A reference node is required (Q104 carried over): the Heltec V4 above. Every "Done when" is checked against it.
Q304MeshCore'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.
Q313Decided 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).
Q314Decided 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 #hashtag channel 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

  1. 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.
  2. Crypto on libsodium (host-tested): the identity and key-exchange adapter, upstream's vectors as tests.
  3. Radio Service, second user: packets handed to both the Scanner and the Mesh Service, the pause and resume (Q291), the fixed preset.
  4. 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), mesh commands.
  5. Mesh App: Channels, Nodes, adding channels, Status Bar dot, Notifications; the Settings switch.
  6. 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.