Milestones · M5

The mesh, transmitting: MeshCore

The device takes part in the mesh. It has its own identity, advertises itself, posts on channels and exchanges Direct Messages with acknowledgements, within the airtime the band allows. Still a chat node: it never relays (Q289)…

Status: done. Everything below was checked on the device with a Heltec V4 but what "Not checked" lists; released as v0.27.0.

Goal: the device takes part in the mesh. It has its own identity, advertises itself, posts on channels and exchanges Direct Messages with acknowledgements, within the airtime the band allows. Still a chat node: it never relays (Q289); that is M6.

Reference node: the Heltec V4 of M4 (Q303).

The airtime rule

The MeshCore preset (869.618 MHz, 62.5 kHz wide) sits in the 869.40–869.65 MHz sub-band. CEPT ERC/REC 70-03 Annex 1 (tested to ETSI EN 300 220) allows 500 mW e.r.p. there and at most 10% duty cycle, unless the device does listen-before-talk and adaptive frequency agility, which a single-frequency mesh can't. Duty cycle is counted over an hour: 360 s of transmitting in any hour. Checked in step 1 against the text itself: ERC/REC 70-03, edition of February 2025, Annex 1, band h1.7: 869.4–869.65 MHz, 500 mW e.r.p., ≤ 10% duty cycle or LBT+AFA (the same band was "h1.6" in editions up to 2016); Appendix 5: duty cycle is Σ(Ton)/(Tobs) for one transmitter, Tobs a continuous one-hour period unless the Annex says otherwise. Not read: the EU's Decision 2006/771/EC as amended by (EU) 2019/1345 (EUR-Lex gave nothing to a script), and Belgium's own table (EFIS), which follow the Recommendation.

Upstream MeshCore paces itself with an airtime factor: after sending for T, it waits T × factor, a duty cycle of 1/(1 + factor). Its default is 1.0, so 50%: one firmware for every region, tuned per region by the operator (af). We don't change the protocol, only that setting, to what the law here asks. Other nodes can't tell.

In practice: at this preset a 60-byte message is about 0.6 s on air, an advert about 1.2 s. 360 s is about 300 messages an hour, retries included. A chat node never comes near it; the cap is a net against bugs (a retry loop, a stuck send). It starts to matter with relaying, in M6.

Decisions (design round 2026-11-10)

#Decision
Q305Airtime cap: 10%, a build-time constant. MESH_AIRTIME_CAP_PERMILLE = 100 in one header; the Radio Service enforces it over a rolling hour, so nothing above it can get past it. Upstream's airtime factor is derived from it (9), so MeshCore paces itself first and the hard cap never fires in normal use. No runtime way to change either: no setting, no file on the card, no console command. A dev PlatformIO environment may override the cap and the factor separately with -D flags, for tests into a dummy load, through attenuators or in a shielded box. CI refuses to sign a release whose cap isn't 100 (ADR 0008). When the budget is spent, sending waits and the Mesh App shows how long.
Q306Identity: an Ed25519 key made on the device the first time transmit is switched on, kept in flash (NVS), not on the card: changing cards doesn't change who you are on the mesh. Export and import only from the USB console, as token (ADR 0010), so it can survive a full erase. Adverts carry the long name from Settings (M0).
Q307No position in adverts by default. Settings → Mesh opts in, exact or rounded to about 1 km. An advert travels far and every node that hears it keeps it.
Q308No transmitting without a valid clock (GNSS or NTP); the Mesh App says why. Adverts whose timestamp isn't newer than the last are dropped as replays, so a device that boots in 1970 is ignored, and later looks like a replay.
Q309Adverts: a zero-hop advert (direct neighbours only) when the mesh starts with a valid clock. A flood advert (relayed across the mesh) only from a Mesh App menu item: automatic periodic flooding is what makes a mesh noisy.
Q310Direct Messages: every chat node in the verified node list can be messaged; no separate contacts list or approval. A message from a sender we never heard advertise can't be decrypted (no key): counted in mesh status, not shown.
Q311Delivery: upstream's retries (up to 3 attempts, flood when the direct path fails). A Direct Message shows sending → sent → delivered (its ACK) or failed, and a failed one can be sent again. A channel message has no ACK: sent, then heard repeated if a repeater's echo is heard.
Q312Console: mesh advert [flood] and mesh send, on both consoles like the other commands. Identity export and import are USB-only (Q306).
Q315Decided in step 1 (2026-11-10). Transmit power: +22 dBm, fixed, the SX1262's most (158 mW), under 500 mW e.r.p. with the Cap's antenna. No setting. The chip's current limit is raised to 140 mA for it (RadioLib leaves 60).
Q316Decided in step 2 (2026-11-10). Settings → Mesh: Off, Listening (the default), Sending. Nothing transmits after an update until the owner chooses Sending, and Sending needs the region confirmed. The device's key is made the first time Sending is chosen: this is what Q306's "the first time transmit is switched on" means. `mesh send on
Q317Decided in step 2. "Rounded" (Q307) is to 0.01 degree: about 1.1 km north-south and 0.7 km east-west at Brussels. Settings → Mesh position: Not sent (the default), Exact, Rounded.
Q318Decided in step 5 (2026-11-10). Accepted: with Mesh on Sending, the VPN up and IRC connecting over TLS, free memory fell to 4.5 KB for a moment (M4 had seen 7.1 KB). The mesh costs about 16 KB now (11.8 KB in M4) and the rest of the firmware about 5 KB more; where it went wasn't looked for. Released as it is, a known risk, as Q86 and Q314 accepted theirs.

Measured

Step 1, the airtime rule and transmitting (2026-11-10).

  • The rule checked against ERC/REC 70-03 itself (above).
  • lib/lora/airtime (host-tested, test/test_airtime, 8 tests): a packet's time on air (Semtech's formula; LoRaWAN's published 46.3 ms and 1155.1 ms come out); the cap as a build-time constant, MESH_AIRTIME_CAP_PERMILLE 100 (airtime_cap.h), 360 s an hour; MeshCore's factor derived from it, 9; AirtimeBudget, the last hour in 60 one-minute buckets (240 bytes), counting a minute too many rather than too few, across millis() wrapping.
  • The Radio Service transmits, through transmit() only: refused unless the region is confirmed (EU868), the mesh has the radio on MeshCore's setting, nothing else is going out, and the packet's airtime still fits the hour; then sent by the radio task at +22 dBm, the radio listening again at once. lora status shows the airtime used; lora tx <hex> sends a packet as it is. MeshNode paces itself with the same factor.
  • Releases can't change the cap: scripts/release_build.sh builds with RORO_RELEASE_BUILD, and then airtime_cap.h refuses any cap but 100, or a factor of its own. scripts/check_airtime_guard.sh, run by CI, proves the guard holds. [env:cardputer-adv-airtime-test] builds with 0.1% for tests (RORO_ENV=... scripts/flash.sh --ota).

On the device, with the Heltec V4 (upstream's companion firmware) in the room:

CheckResult
The first transmission: a message on the private test channel, routed direct with an empty path (no repeater relays it), 53 bytesShown by the Heltec's phone app: "Cardputer: first words on the air". 0.6 s of airtime
The 0.1% build (3.6 s an hour), the same packet again and again6 sent, then "over the hour's airtime"
The wait it gave"47 s": wrong. Just after boot the hour before now reached back past minute 0, and the start was clamped to it, so a minute's sends left the hour after a minute. Minutes are now numbered from an hour before start; a host test for it
1 in 6, then 1 in 12, transmissions failedTX_TIMEOUT after 2.9 s: the chip never said it was done. RadioLib's transmit() clears the flags that would say why. Started and waited for here instead (yielding 1 ms at a time, where RadioLib's loop kept the core), with the chip's mode and error flags printed on a failure: 40 sent out of 40 since. The cause isn't known; the print stays

Not checked: the guard against an actual release build with another cap (the check compiles the header the same way the build does); the airtime refused while another node is sending (no listen-before-talk: the rule doesn't ask for it).

Step 2, the device's identity (2026-11-10).

  • lib/mesh/mesh_identity (host-tested, test/test_mesh_identity, 5 tests): a key made until upstream's own check takes it; kept as upstream writes it, private then public, 192 hex digits, in Settings (MeshKey, flash, never shown); read back with or without the check; a private key alone gives its public one (upstream's known-good key does); someone else's public key with ours is refused. Where adverts say the device is (Q307, Q317).
  • Settings → GNSS and radio: Mesh with three values, and Mesh position (Q316, Q317).
  • The Mesh Service makes the key the first time Mesh is Sending, keeps it, and starts the node with it from then on. mesh status says sending or listening, the key's start, the advert's name (the long name, Q306) and what position adverts give. mesh key shows the public key anywhere; mesh key export and mesh key import <hex> work from USB and the device's own Shell only (as debug token, ADR 0010). A line importing a key is echoed nowhere and isn't kept in the Shell's history; debug token <value> isn't kept there any more either.

On the device: mesh send on made the key ("this device's key made: 43b6ef3ea886f5d2") and restarted the node with it; mesh key export over the Debug Console said "over USB only".

A stack overflow, found there. mesh status asked for the public key, which read the kept key with upstream's check: two key exchanges, whose curve arithmetic (ge25519_is_on_main_subgroup) overflowed the main loop's stack from inside a console command. Three such commands in a row, and the device went to Safe Mode (ADR 0005), from which the next update brought it back. Now a kept key is read without arithmetic (it was checked when it came), the public key straight from its hex, and making or checking a key runs on a task of its own with an 8 KB stack, as the SSH App makes its key. mesh status and mesh key again and again since: fine; the main loop keeps 1,668 bytes of stack.

Not checked on the device: export and import over USB (the device isn't on a USB port here; the Shell would show the private key on the screen, and in any screenshot of it).

Step 3, adverts (2026-11-10).

  • The node sends through its host (mesh::Host::send, sendDone, airtimeFor): upstream queues, paces itself at 10% (its own one-hour budget, the factor 9 of step 1) and gives a packet 1.5 times its airtime to go out. MeshNode::advertise(flood, name, position) makes upstream's signed advert and sends it zero-hop or flood. Host-tested: another node hears it, signed by our key, with our name and position; zero-hop is direct with no path, flood is flood; a refused packet is dropped, not kept (test_mesh_node, 2 more tests).
  • The Mesh Service sends only while Mesh is Sending (Q316) and the time is known (Q308: refused and counted otherwise), through the Radio Service. A zero-hop advert goes out by itself once a start is Sending, with its key and the time (Q309). mesh advert [flood]; in the Mesh App's node list, a asks, then sends a flood advert. Its position follows Mesh position and the GNSS (none without a fix).

On the device, with the Heltec V4:

CheckResult
The first buildCrashed at start, "stack smashing protect failure" in our ed25519_sign, and went back to the build before by itself. The firmware links two libsodiums: ESP-IDF's (whose SHA-512 is mbedTLS's) keeps a larger crypto_hash_sha512_state than the header compiled against declares, and signing kept one on the stack. Signing now hashes in one go (crypto_hash_sha512), in a buffer wiped after; RFC 8032's vectors still pass
Started, Sending, the time knownOne zero-hop advert, 1.1 s on the air; the Heltec's app lists "roro9stack proto", key 43b6ef3e…, no position
mesh advert with Mesh position Rounded and no GNSS fixSent without a position: none is made up
The same once the GNSS had a fixSent with a position; the Heltec's app shows the contact on its map, rounded to two decimals

Not tried on the device: a flood advert (the owner chose not to make the device a visible node on the public mesh yet; the route is host-tested); refusal without the time (the device always had it).

Step 4, messages (2026-11-10).

  • MeshNode sends a channel message (flood, "name: text", 160 bytes in all) and private ones to chat nodes heard advertising (Q310): one in flight at a time, up to 8 waiting; direct when the route is known, flood otherwise; up to 3 attempts, the route forgotten after a direct one fails (Q311). Upstream computes the ACK each message expects, and the receiver sends it back by itself, with the way back when the message came flood. Upstream clears its one timer after processAck() and onSendTimeout(): those only note what happened, and loop() sends next. A channel message's packet hash is kept: a repeater's copy of it makes it heard repeated. A private message heard again (a retry, its ACK lost) is shown once: upstream doesn't tell them apart. Host-tested with two nodes on a link the test controls (test_mesh_messages, 6 tests: delivered, then direct; failed after three attempts; queued in turn; refusals; a channel message and its echo).
  • History: this device's own messages with their state (sending, sent, delivered, failed, heard repeated), private conversations (the 8 most recent, 3 KB of text), all on the card (dm-<key>.log; own lines have "me" where the hops go; states aren't written).
  • The Mesh App: a channel or a conversation has a line to write in (Enter sends); conversations are listed after the channels with their unread messages; m on a node's page starts one; ctrl+r sends the last failed private message again. Notifications for private messages follow Mesh sound, as channels' do. Console: mesh send <channel> <text>, mesh dm <key's start or name> <text>, mesh dms.

On the device, with the Heltec V4:

CheckResult
mesh dm 3062d5ca …"sent", then "delivered" on the first attempt; the Heltec's app shows it
A private reply from the HeltecRead, in the Heltec V4 conversation, unread until opened
mesh send 2 … on roro-privateThe Heltec's app shows it on roro-private
From the Mesh App: the Heltec's page, m, typed, Enter"Hi, from the App [delivered]"; the reply listed as "@ Heltec V4 · 1 new", the dot by L, read when opened

Not tried on the device: failure after three attempts, and ctrl+r (the Heltec always answered); heard repeated (no repeater passed a message on: none was sent on Public, and no repeater was in reach for the private channel's).

Step 5, the rest (2026-11-10).

CheckResult
A private message to the Heltec, unplugged"[failed]" after 3 attempts, about 30 s
Plugged in again, ctrl+r in the conversationSent again, "[delivered]"; the Heltec's owner answered, read in the conversation
The 0.1% build: messages until the hour is spent, then one from the App"the hour's airtime is spent: 59 minutes to wait", above the line being written. It is spent as soon as the longest message wouldn't fit (1.8 s of 3.6 s used): a message that goes now isn't stopped at the radio after all
Free memory, Mesh on Sending, VPN up, IRC connecting on TLS, then a private message23 KB free, 4.5 KB at the lowest (Q318); the message delivered
The mesh off, then on78.6 KB, then 62.5 KB free

Fixed on the way: the App's short messages ("Sent again", why not) were drawn over the line being written; they go just above it.

Found, not changed: the airtime count lives in RAM, so a restart starts a fresh hour, as MeshCore's own pacing does: a device restarting again and again could pass 10% in a real hour. A screenshot taken over the Debug Console copies the screen while the main loop may be drawing it, and can come out torn (the screen itself was right: three in a row agreed).

Not checked on the device: the key's export and import over USB (no USB cable here); refusal without the time; a flood advert, and posting on Public or a hashtag channel (kept off the public mesh by choice); heard repeated.

The user guide: the Mesh page rewritten for sending (Off, Listening, Sending; states; adverts; the rules it keeps; the key), Settings (Mesh's three values, Mesh position), the FAQ ("Can I send messages?", "Does it ever transmit?"), the guide's front page, the memory how-to, and the Apps page, whose planned App is now M6's.

Later, from the architecture re-check (2026-11-19). Three holes in what this milestone decided, found by reading and closed:

  • mesh key export printed the key with the console's ordinary output, which the Debug Console's ring copies: with the console on, a client read it, and a client connecting later got it from the backlog. A client could also type the command into the Shell with key and read the screen with screenshot. Export and import are now refused while the Debug Console is on (debug off first), and the key is printed past the ring in any case.
  • The lines kept out of the echo and the Shell's history were two prefixes tested on the line before it was trimmed: debug token X, with a space first, was echoed. One rule now (lib/debug/console_lines, host-tested), on the trimmed line, and it covers mesh login with a password, mesh channel add with a secret and wifi add with a password too.
  • lora tx sent whatever came out of a loose hex read (lora tx hello sent two zero bytes), and in Listening as well, against Q316. It now needs Mesh Sending and strict hex. Choosing Sending makes the start's zero-hop advert go out, so a lora tx test puts an advert on the air first: test into a dummy load or with Mesh position off.

Done when

  • The airtime figures above are checked against the current ERC/REC 70-03 Annex 1 and cited. Met.
  • The Heltec's phone app sees the device's advert, zero-hop at start and flood from the menu, with the Settings long name and no position; with the setting on, an exact or a rounded one.
  • A message the device posts on Public, a private and a #hashtag channel shows on the Heltec. The private channel: met. Public and a hashtag channel: not posted, to keep test messages off the public mesh.
  • Direct Messages both ways: the device's shows delivered; with the Heltec off it shows failed, and resending once it's back delivers it. Delivered both ways: met. Failed and resent: host-tested, not yet on the device.
  • Without a valid clock, nothing transmits and the Mesh App says why. Built and host-tested through the refusal; the device always had the time.
  • In a dev build with a tiny cap, into a dummy load or attenuated, the cap is reached: sending waits, the Mesh App shows how long, mesh status shows the airtime used. CI refuses to sign a release built with another cap. Met for the Radio Service (on air: a 0.1% cap is no risk to anyone) and the guard; the Mesh App's part waits for step 4.
  • The identity survives a card change and a restart; exported over USB, erased, imported, it is the same node to the Heltec. The console over TCP can't export it. Restarts: met (the key is in flash). TCP refused: met. USB export and import: not checked.
  • Free heap stays above the floors (Q86) while sending, with IRC on TLS. Not met: 4.5 KB at the lowest, accepted (Q318).

Work breakdown

  1. The airtime rule checked against the official text; the cap in the Radio Service (host-tested), its transmit function, the factor derived; the CI check.
  2. Identity: made, stored, exported and imported; the Settings name and position options.
  3. Adverts: zero-hop at start, flood from the menu, the clock rule.
  4. Sending: channel messages, Direct Messages, ACKs, retries and states in the Mesh App.
  5. With the Heltec: every "Done when"; measurements and the user guide's Mesh page updated, with the Settings page (Mesh: Off, Listening, Sending; Mesh position) and the console's new commands, at the release.

This page is generated from docs/milestones/M5.md in the repository. To change it, change that file and run site/tools/gen_dev_docs.py.