diff --git a/pages/experiments.md b/pages/experiments.md index ca2cd9b..088d921 100644 --- a/pages/experiments.md +++ b/pages/experiments.md @@ -28,7 +28,10 @@ against the same network, with the results tabulated side by side. `companion_version`, `path_hash_mode`, `rep_path_hash`, `loop_detect`, `cad`, `spread_ms` and `set`; any other field, or a value the setting cannot take, is refused with `bad_params` and the arms already defined are - kept, so a misspelt setting cannot run as a second control arm. + kept, so a misspelt setting cannot run as a second control arm. An arm + that pins a setting onto a node whose build does not take MeshCore's console + commands is refused when the experiment starts; see + [firmware that is not MeshCore](firmware-integration.html#firmware-that-is-not-meshcore). 5. **Choose seeds and senders.** Pick senders spread across the map rather than the first few in the list: a cluster of neighbours contends with itself instead of with the mesh. `experiment.senders` takes the node names. diff --git a/pages/firmware-integration.md b/pages/firmware-integration.md index 9b2abba..5d45850 100644 --- a/pages/firmware-integration.md +++ b/pages/firmware-integration.md @@ -114,6 +114,43 @@ real traffic and are a fact about that node. Before them a node is not broken - and not useful either. +### Firmware that is not MeshCore + +Provisioning, and every setting an experiment arm pins, is MeshCore's command +line typed at the node's console. A firmware that is not MeshCore refuses each +line, and the only trace is a line in its console: + +``` +set name Deck Error: unknown config: name Deck +``` + +So a build declares the console vocabulary it speaks, its **dialect**: +`meshcore`, the default; `none`, for a firmware with no console; or another +firmware's name. A node running a build whose dialect is not `meshcore` is sent +none of the script. In its place the Provisioning panel shows one comment line +saying why: + +``` +# Deck runs wadamesh firmware, which does not take MeshCore's console commands: nothing is sent +``` + +The dialect is set in three places: + +- **In the firmware library**, the build's own window has a switch, *takes + MeshCore's console commands*, on by default. Turned off, a build that has + not named another dialect is recorded as `none`. +- **On import**, `firmware.import` takes `dialect`, so a third-party image is + never provisioned on its first run. +- **Afterwards**, `firmware.update` takes `dialect`, and `firmware.details` + reports it. + +An [experiment](experiments.html) arm that pins a setting (a path-hash size, +loop detection, CAD, or a `set` line) onto a node whose build does not take +MeshCore's commands is refused by `experiment.start` before the run, naming the +arm and the nodes: a setting that does not apply makes two cells that differ by +nothing. Each node is judged on the build that arm runs it on, and an arm that +only chooses builds is not refused. + **The region half of this is shared code**, in `internal/app/fixture`, used by both the workbench and the headless test runner. It contains the `#` asymmetry, which this project has paid for twice, and two copies of that rule would eventually diff --git a/pages/firmware-library.md b/pages/firmware-library.md index bf7e079..3ca15e7 100644 --- a/pages/firmware-library.md +++ b/pages/firmware-library.md @@ -76,3 +76,9 @@ and testing is one keypress: It reads the board and role out of the environment name and names the build after the branch it came from, so two local builds appear separately rather than overwriting each other. + +A build that is not MeshCore, or that has no console, is marked so in its own +window: turn off *takes MeshCore's console commands*, or pass `dialect` to +`firmware.import`. Nodes running it are then not sent MeshCore's provisioning +lines, which they would refuse one by one; see +[running real firmware](firmware-integration.html#firmware-that-is-not-meshcore).