What is real, and what is modelled
MeshBench runs real MeshCore firmware. MeshBench models the air.
That one sentence is the whole design. MeshBench does not simulate the firmware's behaviour: every node is the actual MeshCore application, compiled and running as its own process, keeping its own state, making its own routing decisions. What MeshBench provides is everything the firmware cannot bring with it: the radio spectrum, the terrain, the distances, the noise, and a clock all the nodes share.
Why the interface sits there#
A simulator that re-implements the protocol tests the re-implementation. By running the real firmware and substituting only the radio, what MeshBench measures is MeshCore's actual behaviour: its flood suppression, its CSMA timing, its region filtering, exactly as they ship. When a packet is not relayed, it is because the real code decided not to relay it.
The interface has two placements, described in Native and emulated:
- Native: MeshCore compiled for this machine, with a radio shim linked in where the SPI driver would be. Deterministic, hundreds of nodes, the mode every measurement uses.
- Emulated: the published board image, unmodified, on an emulated CPU talking to a modelled SX1262 over emulated SPI. Wall-clock time, about eight nodes, the mode for checking a release boots and transmits.
What happens to a transmission#
The firmware hands bytes to its radio. The channel prices the path to every listener: transmit power, antenna gain in the true direction, free-space loss, terrain diffraction, buildings if loaded, then noise at each receiver. Whether each listener decodes is judged one of two ways:
- Calculated RF (the default): signal-to-noise arithmetic against the demodulator's floor. Fast enough for a national network.
- Waveform RF: the actual chirps are synthesised as IQ samples, overlaps sum coherently, and a real demodulator recovers the frame or does not. Capture and collision emerge from the physics. 20 to 50 times the cost.
RF simulation compares them; the RF chain walks the stages both share. Either way, the verdict and its cause land in the event log, which is what every result is read from.
The words, in one place#
The terms below are the project's own, used consistently by the application, the fixtures and the clients.
| term | meaning |
|---|---|
| network | the nodes on the map and the links between them |
| scenario | a network plus everything that makes a run repeatable: seed, radio settings, schedule |
| fixture | a scenario shipped as JSON, with assertions; the runnable, testable form |
| run | one execution of a scenario; run.save keeps its results for comparison |
| seed | the run's randomness; same seed, same scenario, same result (native firmware) |
| arm | one variant in an experiment: a firmware version or setting under comparison |
| region | a transport region a repeater forwards flood traffic for, e.g. sco |
| scope | the region a packet is sent on; written #sco on the wire, and hashed |
| kind | what a node is: simple-repeater, companion, room-server, sdr-observer, emitter |
| role | the MeshCore application a node runs: simple_repeater, companion_radio, simple_room_server |
| native | MeshCore compiled for this machine, radio shim linked in; deterministic |
| emulated | the published board image on an emulated chip; wall-clock time |
| calculated RF | reception decided by link-budget arithmetic against the demodulator floor |
| waveform RF | reception decided by a real demodulator over synthesised samples |
| boundary | the study area; nodes outside it (plus a margin) are not simulated |
| demodulator floor | the weakest signal the radio can still decode; everything quieter is noise |
| margin | how many dB a link clears the demodulator floor by |
| cause | why a reception failed, recorded per event: below the floor, corrupted by overlap, radio elsewhere |
| provenance | the caveats stamped into a result: RF mode, realism switches, seed |
Two pairs are worth keeping apart because both words appear in the interface: a region is held by a node and decides what it relays; a scope is carried by a packet and decides who relays it. A kind is what a node is on the map; a role is which MeshCore application it boots.
Where to go next#
- Getting started: install and launch.
- Your first simulation: a real network relaying real packets, in about fifteen minutes.
- Reading a result: what the numbers mean, and how much to trust them.