meshbench 0.0.5__tar.gz

meshbench-0.0.5/.gitignore

@@ -0,0 +1,61 @@
+/meshbench
+/dist/
+*.exe
+
+# Build caches for MeshCore firmware refs (ADR-0009) — reproducible, large
+/firmware-cache/
+
+# DEM tiles; large and reproducible from the tile server
+/dem-cache/
+
+# Captures and IQ recordings — can be enormous (1 MB/s per receiver)
+/captures/
+*.pcapng
+*.sigmf-data
+*.cf32
+
+# Python build artifacts, from the client under pkg/client-python and from
+# anything that imports it. Reproducible from the source beside them, and here
+# rather than beside the client because a test run leaves them in the working
+# tree and the next `git add -A` on any branch picks them up - which is exactly
+# how eleven of them got committed once.
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+/pkg/client-python/build/
+/pkg/client-python/dist/
+/.venv/
+/venv/
+
+/.idea/
+/.vscode/
+*.swp
+# Local Claude Code state, but not the skills: those describe how to drive this
+# project and are worth sharing. Anything personal or machine-specific stays
+# out.
+.claude/*
+!.claude/skills/
+.claude/settings.local.json
+tools/armfw/build/
+
+# Tool binaries built at the repo root by `go build ./tools/...`. They shadow
+# the packages they are built from, so tab-completing the name gets the binary.
+# Every `package main` under tools/ produces one, named after its directory; the
+# list is the whole set, because a missing one sits untracked in `git status`
+# until a `git add -A` sweeps it in - which is how eleven Python artifacts got
+# committed once, and how these four kept reappearing.
+/clientgen
+/envgen
+/goldencap
+/licgen
+/mockup
+/render
+
+# built test binaries
+*.test
+
+# Written by `go test -coverprofile` for a Sonar scan; regenerated on demand.
+coverage.out
+.carto-key

meshbench-0.0.5/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: meshbench
+Version: 0.0.5
+Summary: Drive a MeshBench workbench: RF-accurate MeshCore simulation, from Python
+Project-URL: Homepage, https://github.com/MeshBench/meshbench
+Project-URL: Issues, https://github.com/MeshBench/meshbench/issues
+Author: MeshBench
+License-Expression: GPL-3.0-or-later
+Keywords: lora,mesh,meshcore,rf,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Communications :: Ham Radio
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# meshbench
+
+Drive a [MeshBench](https://github.com/MeshBench/meshbench) workbench from
+Python: real MeshCore firmware over a sample-accurate LoRa channel, scripted.
+
+```python
+from datetime import timedelta
+
+from meshbench import Workbench
+
+with Workbench.headless(fixture="fife-strict", seed=9001) as wb:
+    wb.sim.run(timedelta(minutes=5))
+    print(wb.provenance())
+    print(wb.events.total(), "events")
+```
+
+`headless` needs no display, no GPU and no toolkit. `Workbench.attach()`
+connects to a workbench somebody is already looking at and never closes it.
+
+Where more than one is running, `meshbench.sessions()` says which: the address
+to connect on, the process, when it started, and what it has open. Pass a row
+straight to `attach()`. A session that was killed rather than closed is not
+listed, because the check is a dial of the address and not a look at a socket
+file or a pid.
+
+## Installing
+
+```
+pip install meshbench
+```
+
+You also need the `meshbench` binary on `PATH` — the package drives it, it
+does not contain it.
+
+## What it looks like
+
+```python
+wb.project.new(place="Fife")
+wb.nodes.place_many(
+    [
+        {"name": "R1", "kind": Kind.SIMPLE_REPEATER, "lat": 56.20, "lon": -3.20},
+        {"name": "C1", "kind": Kind.COMPANION, "lat": 56.19, "lon": -3.17},
+    ]
+)
+wb.sim.start()
+wb.firmware.wait_started()  # a sensible default, or pass a timedelta
+
+node = wb.nodes["C1"]
+node.firmware = wb.firmware.find("companion-v1.17.0")
+print(node.console.ask("get region"))
+```
+
+`wb.call(verb, params)` is the whole API underneath, and stays public: anything
+this package has not shaped is one line away rather than a blocker.
+
+## Testing firmware with it
+
+The package registers a pytest plugin, so there is no `conftest.py` to copy:
+
+```python
+def test_the_flood_reaches_glenrothes(meshbench):
+    meshbench.project.open("fixtures/fixture-fife-strict.json")
+    meshbench.sim.run(timedelta(minutes=5))
+    assert meshbench.events.total() > 0
+```
+
+One workbench for the whole run — starting firmware on a real mesh is minutes,
+not milliseconds — with the scenario cleared between tests so reuse does not
+leak. `--meshbench-socket` attaches to one you are already running instead.
+
+**A failing test prints the provenance**, whether or not it asked. Somebody
+reading a failed assertion about a mesh is deciding whether their firmware
+change broke something, and they need to know what the run assumed first.
+
+## Two things that will bite otherwise
+
+**Simulated time is not your time.** Every duration here is a
+`datetime.timedelta` - Python already has a duration type, so this package does
+not invent one - but two different clocks are measured in them:
+
+- **the mesh's**, for `sim.run(...)`, `schedule.add(at=, every=)` and
+  `sim.wait_until(at=)`
+- **yours**, for every `timeout` and for `sim.run(wait=)`
+
+`sim.run(timedelta(minutes=5), wait=timedelta(minutes=60))` is five minutes of
+the mesh's clock, and up to an hour of yours waiting for it. On 155 emulated
+nodes that gap is the normal case, which is why they are separate arguments.
+Every wait has a defensible default, so `wait_started()` on its own is fine.
+
+**A node answers on its next loop.** Its loop only runs when the engine steps,
+so reading a console straight after writing to it reads the moment *before* the
+command was sent. Use `console.ask()`, which gives the mesh its own time first.
+
+## Honesty
+
+Every result comes out of a simulator that is **kinder than the air**: no
+multipath, no body loss, no oscillator error. The measured biases are nearly
+all in one direction, which is what makes a result usable — treat it as a best
+case. `wb.provenance()` says what a given run assumed, and it is meant to be
+printed above any number you publish.
+
+## Licence
+
+GPL-3.0-or-later, with the rest of MeshBench.

meshbench-0.0.5/README.md

@@ -0,0 +1,104 @@
+# meshbench
+
+Drive a [MeshBench](https://github.com/MeshBench/meshbench) workbench from
+Python: real MeshCore firmware over a sample-accurate LoRa channel, scripted.
+
+```python
+from datetime import timedelta
+
+from meshbench import Workbench
+
+with Workbench.headless(fixture="fife-strict", seed=9001) as wb:
+    wb.sim.run(timedelta(minutes=5))
+    print(wb.provenance())
+    print(wb.events.total(), "events")
+```
+
+`headless` needs no display, no GPU and no toolkit. `Workbench.attach()`
+connects to a workbench somebody is already looking at and never closes it.
+
+Where more than one is running, `meshbench.sessions()` says which: the address
+to connect on, the process, when it started, and what it has open. Pass a row
+straight to `attach()`. A session that was killed rather than closed is not
+listed, because the check is a dial of the address and not a look at a socket
+file or a pid.
+
+## Installing
+
+```
+pip install meshbench
+```
+
+You also need the `meshbench` binary on `PATH` — the package drives it, it
+does not contain it.
+
+## What it looks like
+
+```python
+wb.project.new(place="Fife")
+wb.nodes.place_many(
+    [
+        {"name": "R1", "kind": Kind.SIMPLE_REPEATER, "lat": 56.20, "lon": -3.20},
+        {"name": "C1", "kind": Kind.COMPANION, "lat": 56.19, "lon": -3.17},
+    ]
+)
+wb.sim.start()
+wb.firmware.wait_started()  # a sensible default, or pass a timedelta
+
+node = wb.nodes["C1"]
+node.firmware = wb.firmware.find("companion-v1.17.0")
+print(node.console.ask("get region"))
+```
+
+`wb.call(verb, params)` is the whole API underneath, and stays public: anything
+this package has not shaped is one line away rather than a blocker.
+
+## Testing firmware with it
+
+The package registers a pytest plugin, so there is no `conftest.py` to copy:
+
+```python
+def test_the_flood_reaches_glenrothes(meshbench):
+    meshbench.project.open("fixtures/fixture-fife-strict.json")
+    meshbench.sim.run(timedelta(minutes=5))
+    assert meshbench.events.total() > 0
+```
+
+One workbench for the whole run — starting firmware on a real mesh is minutes,
+not milliseconds — with the scenario cleared between tests so reuse does not
+leak. `--meshbench-socket` attaches to one you are already running instead.
+
+**A failing test prints the provenance**, whether or not it asked. Somebody
+reading a failed assertion about a mesh is deciding whether their firmware
+change broke something, and they need to know what the run assumed first.
+
+## Two things that will bite otherwise
+
+**Simulated time is not your time.** Every duration here is a
+`datetime.timedelta` - Python already has a duration type, so this package does
+not invent one - but two different clocks are measured in them:
+
+- **the mesh's**, for `sim.run(...)`, `schedule.add(at=, every=)` and
+  `sim.wait_until(at=)`
+- **yours**, for every `timeout` and for `sim.run(wait=)`
+
+`sim.run(timedelta(minutes=5), wait=timedelta(minutes=60))` is five minutes of
+the mesh's clock, and up to an hour of yours waiting for it. On 155 emulated
+nodes that gap is the normal case, which is why they are separate arguments.
+Every wait has a defensible default, so `wait_started()` on its own is fine.
+
+**A node answers on its next loop.** Its loop only runs when the engine steps,
+so reading a console straight after writing to it reads the moment *before* the
+command was sent. Use `console.ask()`, which gives the mesh its own time first.
+
+## Honesty
+
+Every result comes out of a simulator that is **kinder than the air**: no
+multipath, no body loss, no oscillator error. The measured biases are nearly
+all in one direction, which is what makes a result usable — treat it as a best
+case. `wb.provenance()` says what a given run assumed, and it is meant to be
+printed above any number you publish.
+
+## Licence
+
+GPL-3.0-or-later, with the rest of MeshBench.

meshbench-0.0.5/examples/01_blank_setup_with_a_board.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Example 1 from #209: a blank setup, one companion, and its screen on show.
+
+    ./01_blank_setup_with_a_board.py
+
+Costs: a minute or two. wadamesh is imported, not downloaded, so it must
+already be in the library or reachable through WADAMESH_IMAGE (see below).
+Needs a display. It opens the node's own window on the Hardware tab at the
+end, which is the point of it.
+
+"""
+
+import os
+import sys
+from datetime import timedelta
+
+from meshbench import Board, Kind, NotFound, Role, Workbench
+
+WADAMESH = "wadamesh"
+# wadamesh is imported, not in the download catalogue: a built image to
+# import if it is not already in the library. Point this at one.
+WADAMESH_IMAGE = os.environ.get("WADAMESH_IMAGE")
+BOARD = Board.LILYGO_TDECK
+
+
+def main() -> None:
+    with Workbench.launch() as wb:
+        wb.project.new(place="Fife")
+
+        deck = wb.nodes.place(
+            "Deck",
+            kind=Kind.COMPANION,
+            lat=56.19,
+            lon=-3.17,
+            board=BOARD,
+        )
+
+        # Whatever the catalogue has, so this does not go stale against a
+        # version number typed here.
+        wb.firmware.scan()
+        try:
+            build = wb.firmware.find(WADAMESH, board=BOARD)
+        except NotFound:
+            # wadamesh is imported, not downloaded - import a built image.
+            if not WADAMESH_IMAGE:
+                sys.exit(
+                    f"{WADAMESH} is not in the library; set WADAMESH_IMAGE "
+                    "to a built image, or import one in the workbench first"
+                )
+            build = wb.firmware.import_(
+                WADAMESH_IMAGE,
+                Role.COMPANION_RADIO_USB,
+                board=BOARD,
+                label=WADAMESH,
+            )
+
+        # Applied: stop, provision, start. On a board that means an emulator,
+        # which is why the wait below is generous.
+        deck.firmware = build
+
+        wb.sim.start()
+        deck.wait_running(timedelta(minutes=5))
+
+        # The Hardware tab is where the board draws its own screen, which is
+        # the whole reason for making this node a T-Deck.
+        tab = wb.window(deck, tab="Hardware")
+
+        print(f"{deck.name} is up on {build}; its window is open on {tab}")
+        print(wb.provenance())
+        # Held open for somebody looking at it, and only then. Piped or run
+        # from CI there is nobody to press enter, and input() raises EOFError
+        # there - so an example that had done everything right ended in a
+        # traceback and a non-zero-looking failure.
+        if sys.stdin.isatty():
+            input("press enter to close the workbench ")
+
+
+if __name__ == "__main__":
+    main()

meshbench-0.0.5/examples/02_two_nodes_on_a_local_build.py

@@ -0,0 +1,116 @@
+#!/usr/bin/env python3
+"""Example 2 from #209: a fixture trimmed to two, both on a build from a
+MeshCore checkout - and re-runnable without clearing anything down.
+
+    ./02_two_nodes_on_a_local_build.py ~/src/MeshCore
+
+The interesting half is the second run. It attaches to the workbench the first
+one left, stops the clock, rebuilds, repoints the nodes and starts again -
+rather than opening a fresh session and paying for the fixture twice.
+
+Costs: minutes, mostly firmware. Real firmware on two nodes, not fifty-eight,
+because trimming is what this example is about.
+"""
+
+import os
+import subprocess
+import sys
+from datetime import timedelta
+
+from meshbench import BINARY_ENV, Build, Kind, Role, Workbench
+
+# Outskirts of Glasgow, and Glenrothes.
+KEEP = {
+    "Glasgow-Outskirts": (55.8720, -4.3300),
+    "Glenrothes": (56.1980, -3.1780),
+}
+
+
+def build_from_checkout(checkout: str, wb: Workbench) -> dict[str, Build]:
+    """Build MeshCore and import what came out, one build per role.
+
+    Both roles from one invocation, deliberately. A locally built repeater
+    compiled against a stale shim once answered console output with 0x06 where
+    the host expects 0x07: it connected, misbehaved and exited. Two arms of a
+    comparison speaking different wire protocols measure the shim, not the
+    firmware - so if either arm is built by hand, both are, the same way, at
+    the same moment.
+    """
+    # The same binary the client is driving, not whatever is on PATH: a
+    # checkout usually has one built and not installed, and building with one
+    # while talking to another is how two arms end up on different code.
+    exe = os.environ.get(BINARY_ENV) or "meshbench"
+
+    out: dict[Role, Build] = {}
+    for role in (Role.SIMPLE_REPEATER, Role.COMPANION_RADIO):
+        # Named here rather than left to default to the git branch, because
+        # the build has to be found again afterwards and a name you chose is
+        # the only one you can look up.
+        name = f"local-{role}"
+        made = subprocess.run(
+            [exe, "dev", "-from", checkout, "-role", role, "-name", name],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if made.returncode != 0:
+            sys.exit(
+                f"building the {role}: {made.stderr.strip() or made.stdout.strip()}"
+            )
+        # meshbench dev puts the build in the cache; the library sees it.
+        wb.firmware.scan()
+        out[role] = wb.firmware.find(name)
+    return out
+
+
+def main() -> None:
+    if len(sys.argv) < 2:
+        sys.exit("usage: 02_two_nodes_on_a_local_build.py <path to MeshCore>")
+    checkout = sys.argv[1]
+
+    with Workbench.attach_or_launch() as wb:
+        # Whether the mesh is already the one this example is about, not
+        # whether the session is empty. A launched workbench is never empty:
+        # it opens its own default fixture, which is 311 nodes - so "is it
+        # empty" was always false, the trim below never ran, and this put a
+        # local build on a national network and reported "311 nodes" as
+        # though that had been the plan.
+        already = {n.name for n in wb.nodes.list()} == set(KEEP)
+
+        # Stop the clock before anything else. A no-op on a fresh session, and
+        # the thing that makes the second run safe on a live one.
+        wb.sim.pause()
+
+        if not already:
+            wb.project.open("fife-strict")
+            # Put them where they belong first, then delete the rest. keep is
+            # all-or-none by design, so naming a node that is not there yet
+            # refuses and removes nothing - and one of these two is never in
+            # the fixture, so the trim refused on every run that reached it.
+            for name, (lat, lon) in KEEP.items():
+                if name in wb.nodes:
+                    wb.nodes[name].move(lat, lon)
+                else:
+                    wb.nodes.place(name, Kind.COMPANION, lat, lon)
+            wb.nodes.keep(*KEEP)
+            wb.wait_idle(timedelta(minutes=10))
+
+        builds = build_from_checkout(checkout, wb)
+
+        # Repoint every node, applied - which stops, provisions and starts it.
+        for node in wb.nodes:
+            role = (
+                Role.COMPANION_RADIO
+                if node.info.kind == Kind.COMPANION
+                else Role.SIMPLE_REPEATER
+            )
+            node.firmware = builds[role]
+
+        wb.sim.start()
+        wb.firmware.wait_started(timedelta(minutes=10))
+        print(f"{len(wb.nodes)} nodes on a build from {checkout}")
+        print(wb.provenance())
+
+
+if __name__ == "__main__":
+    main()

meshbench-0.0.5/examples/03_small_mesh_with_traffic.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Example 3 from #209: two repeaters, two companions, one of them a T-Deck,
+and a message to the public channel every twenty seconds.
+
+    ./03_small_mesh_with_traffic.py
+
+Needs a display: it opens the workbench so you can watch the traffic move.
+
+Costs: about ten minutes of simulated time, and a few of yours.
+
+The repeating traffic needed no new verb: schedule.add has taken every_ms all
+along and nothing said so, which to somebody writing a script is the same as
+it not existing.
+"""
+
+from datetime import timedelta
+
+from meshbench import Board, Class, Kind, Workbench
+
+MESH = [
+    {"name": "R1", "kind": Kind.SIMPLE_REPEATER, "lat": 56.20, "lon": -3.20},
+    {"name": "R2", "kind": Kind.SIMPLE_REPEATER, "lat": 56.12, "lon": -3.02},
+    {"name": "C1", "kind": Kind.COMPANION, "lat": 56.19, "lon": -3.17},
+    {"name": "C2", "kind": Kind.COMPANION, "lat": 56.09, "lon": -3.10},
+]
+
+
+def main() -> None:
+    with Workbench.launch() as wb:
+        wb.project.new(place="Fife")
+        wb.nodes.place_many(MESH)
+        wb.wait_idle(timedelta(minutes=10))
+
+        # C1 is the T-Deck. The board goes on before the firmware is pinned,
+        # because a host image is not a board image and setting the board
+        # clears a pin that was made for different hardware.
+        wb.nodes["C1"].board = Board.LILYGO_TDECK
+
+        # Whatever this machine holds for each role that needs one, rather
+        # than a version typed here that goes stale.
+        wb.firmware.use_what_is_here()
+
+        # Every twenty seconds, from the plain companion to the public channel.
+        # Simulated seconds - the mesh's own clock, not yours.
+        wb.schedule.add(
+            "C2",
+            "public hello",
+            at=timedelta(seconds=5),
+            every=timedelta(seconds=20),
+        )
+
+        wb.sim.start()
+        wb.firmware.wait_started(timedelta(minutes=10))
+        wb.sim.run(timedelta(minutes=10), wait=timedelta(minutes=60))
+
+        received = [e for e in wb.events.recent(1000) if e.class_ == Class.RECEIVED]
+        print(wb.provenance())
+        print(f"{wb.events.total()} events, {len(received)} receptions in the tail")
+
+
+if __name__ == "__main__":
+    main()

meshbench-0.0.5/examples/04_headless_regression.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+"""Example 4: the one CI runs.
+
+    ./04_headless_regression.py [fixture] [junit.xml]
+
+No display, no GPU, no toolkit. Opens a fixture, runs it, checks its
+assertions, writes JUnit, and exits non-zero if the mesh stopped delivering.
+This is the shape a MeshCore pull request would use.
+
+Costs: as long as the fixture asks for. fife-strict at five simulated minutes
+is a couple of minutes of wall clock with no firmware, and considerably more
+with it.
+"""
+
+import sys
+from datetime import timedelta
+
+from meshbench import Workbench
+
+SEED = 9001
+
+
+def main() -> int:
+    fixture = sys.argv[1] if len(sys.argv) > 1 else "fife-strict"
+    junit = sys.argv[2] if len(sys.argv) > 2 else ""
+
+    with Workbench.headless(fixture=fixture, seed=SEED) as wb:
+        # Bring the mesh up before running the clock. sim.run only advances
+        # time; without this the firmware never starts, nothing transmits, and
+        # the run reports every assertion failed on a tree with nothing wrong
+        # with it - which is the worst thing a regression check can do.
+        wb.sim.start()
+        wb.firmware.wait_started()
+
+        wb.sim.run(timedelta(minutes=5), wait=timedelta(minutes=60))
+
+        report = wb.assertions.check()
+
+        # The report prints the caveats above the numbers itself, because this
+        # is the output somebody pastes into a pull request and the caveats are
+        # the half that gets dropped.
+        print(report)
+        print(f"{wb.events.total()} events")
+
+        if junit:
+            report.write_junit(junit)
+
+        if report.total == 0:
+            # Not a pass. A fixture with no assertions can report but cannot
+            # pass or fail, and a green tick that checked nothing is the worst
+            # outcome available here.
+            return 2
+        return 0 if report.ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

meshbench-0.0.5/examples/05_two_builds_in_one_scenario.py

@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Two builds, two nodes, one scenario - the A/B #192 was filed from.
+
+    ./05_two_builds_in_one_scenario.py <stock version> <path to a local build>
+
+The most common real use of this API, and the reason the node window grew a
+firmware control: comparing a stock build against one with a single changed
+constant, on the same mesh, at the same seed.
+
+Needs a display: it opens the workbench so you can watch both arms run.
+
+Costs: firmware on a whole fixture, so minutes.
+"""
+
+import sys
+from datetime import timedelta
+
+from meshbench import Role, Workbench
+
+SEED = 9001
+
+
+def main() -> None:
+    if len(sys.argv) < 3:
+        sys.exit(
+            "usage: 05_two_builds_in_one_scenario.py <stock version> <local build path>"
+        )
+    stock_version, local_path = sys.argv[1], sys.argv[2]
+
+    with Workbench.launch(fixture="fife-strict", seed=SEED) as wb:
+        stock = wb.firmware.find(stock_version)
+        # The application name the verbs are keyed on, not the catalogue's
+        # shorter "repeater": a build imported under a role no node has is a
+        # build nothing will ever run.
+        changed = wb.firmware.import_(local_path, Role.SIMPLE_REPEATER)
+
+        # Two nodes far enough apart to be independently interesting, one on
+        # each build. Applied, which restarts each of them.
+        a, b = list(wb.nodes)[0], list(wb.nodes)[1]
+        a.firmware = stock
+        b.firmware = changed
+
+        wb.sim.start()
+        wb.firmware.wait_started(timedelta(minutes=15))
+        wb.sim.run(timedelta(minutes=5), wait=timedelta(minutes=60))
+
+        # Per node, because the whole point is which of the two behaved
+        # differently - a total would hide it.
+        print(wb.provenance())
+        for node, build in ((a, stock), (b, changed)):
+            s = node.stat
+            print(f"{node.name:24} {str(build):32} sent {s.sent:4}  heard {s.heard:4}")
+
+        # One run of one seed is one draw. A difference here is a hypothesis,
+        # not a result: run it across seeds with experiment.* before believing
+        # anything.
+        print("\none seed, one draw - vary the seed before calling this a difference")
+
+
+if __name__ == "__main__":
+    main()