From 22f85e3d512b00ebc18a71e527b2d6a932bd58a3 Mon Sep 17 00:00:00 2001 From: Jean-Pierre Martineau Date: Fri, 24 Jul 2026 03:32:06 -0400 Subject: [PATCH] scripts: add the SPI-radio bridge helper Expose an SPI-attached MeshCore radio (uConsole AIO, Waveshare HATs) to MeshTerm over the companion protocol on local TCP. A single stdlib-only file that is both a plain-text setup menu and the bridge process: it finds the pymc_core runtime and re-execs the bridge under it, offers run-now / install-as-a-service / uninstall, and can add a [profiles.bridge] block so the endpoint shows up in MeshTerm's device picker. Co-Authored-By: Claude Opus 4.8 (1M context) --- scripts/README.md | 64 +++ scripts/meshterm-spi-bridge | 748 ++++++++++++++++++++++++++++++++++++ 2 files changed, 812 insertions(+) create mode 100644 scripts/README.md create mode 100755 scripts/meshterm-spi-bridge diff --git a/scripts/README.md b/scripts/README.md new file mode 100644 index 0000000..a06241a --- /dev/null +++ b/scripts/README.md @@ -0,0 +1,64 @@ +# meshterm-spi-bridge + +Expose an **SPI-attached** MeshCore radio to MeshTerm. + +Some boards wire the LoRa chip straight to the host's SPI bus — the ClockworkPi +uConsole with the hackergadgets AIO, Waveshare LoRa HATs, and similar. There is +**no companion microcontroller and no firmware to flash**: the mesh node runs in +software on the host via the [`pymc_core`](https://pypi.org/project/pymc-core/) +library (on the uConsole this arrives with the `meshcore-uconsole` apt package, +which also ships the `meshcore-console` GUI). + +MeshTerm, however, speaks the MeshCore **companion protocol** over serial / BLE / +TCP and expects to talk to a *node*, not to drive a bare radio. This bridge fills +the gap: it runs the `pymc_core` node itself and puts the standard companion +protocol in front of it on a local TCP port, so that + +``` +meshterm --tcp 127.0.0.1:5000 +``` + +connects exactly as if a real companion device were plugged in. + +## Usage + +Copy `meshterm-spi-bridge` onto the radio host and run it with any Python 3 — +it finds the `pymc_core` runtime and re-execs the bridge under it for you: + +``` +./meshterm-spi-bridge # interactive setup menu +./meshterm-spi-bridge --check # run prerequisite checks and exit +./meshterm-spi-bridge --run # run the bridge now, in this terminal +``` + +The menu offers: + +1. **Run now** — runs in the foreground; Ctrl+C stops it. +2. **Install as a service** — a `systemd --user` unit that starts on boot and + restarts on failure, running as you (so it uses your node identity). +3. **Uninstall** — removes only the bridge service + its helper copy. It never + touches the `meshcore-console` / `pymc_core` packages. + +## Caveats + +- **Only one program may use the radio at a time.** Run *either* the + `meshcore-console` GUI *or* this bridge — never both. The bridge preflight + warns you when the GUI is running. +- The bridge and MeshTerm are two cooperating processes; keep the bridge running + while you use MeshTerm. +- **Same identity as the GUI:** when the `meshcore-console` stack is present, the + bridge loads the node key from `~/.local/share/meshcore-uconsole/identity.key`, + so MeshTerm sees the same node. On a generic `pymc_core`-only install it mints + and persists its own key under `~/.local/share/meshterm-spi-bridge/`. +- **Trace is not wired yet.** Messaging, contacts, adverts and config work + today; the node's trace / path-discovery replies aren't yet pushed to the + companion server, so MeshTerm's Trace screen won't populate until that's added. + +## Overriding hardware pins + +Defaults match the hackergadgets uConsole AIO. For other SPI boards, set env +vars before launching (read by the direct-`pymc_core` path): +`MESHCORE_BUS_ID`, `MESHCORE_CS_ID`, `MESHCORE_RESET_PIN`, `MESHCORE_BUSY_PIN`, +`MESHCORE_IRQ_PIN`, `MESHCORE_FREQUENCY`, `MESHCORE_TX_POWER`, +`MESHCORE_SPREADING_FACTOR`, `MESHCORE_BANDWIDTH`, `MESHCORE_CODING_RATE`. To +force a specific interpreter, set `MESHTERM_PYMC_PYTHON`. diff --git a/scripts/meshterm-spi-bridge b/scripts/meshterm-spi-bridge new file mode 100755 index 0000000..d8b3762 --- /dev/null +++ b/scripts/meshterm-spi-bridge @@ -0,0 +1,748 @@ +#!/usr/bin/env python3 +""" +meshterm-spi-bridge — expose an SPI-attached MeshCore radio to MeshTerm. + +Some boards (the ClockworkPi uConsole hackergadgets AIO, Waveshare LoRa HATs) +wire the LoRa chip straight to the host's SPI bus — there is no companion MCU +and no firmware to flash. The node runs *in software* on the host via the +`pymc_core` library. MeshTerm, though, speaks the MeshCore companion protocol +over serial/BLE/TCP and expects to talk to a node, not to drive a bare radio. + +This tool bridges the two: it runs the pymc_core node itself and puts the +standard companion protocol in front of it on a local TCP port, so that + + meshterm --tcp 127.0.0.1:5000 + +connects exactly as if a real companion device were plugged in. + +It is BOTH a friendly setup menu and the bridge process. Run it with any +Python 3 — it finds the pymc_core runtime for you and re-execs the bridge half +under that interpreter automatically. You never need to know about venvs. + + ./meshterm-spi-bridge # interactive menu + ./meshterm-spi-bridge --check # run prerequisite checks and exit + ./meshterm-spi-bridge --run # run the bridge now in this terminal +""" +from __future__ import annotations + +import argparse +import os +import shutil +import socket +import subprocess +import sys +from pathlib import Path + +# --------------------------------------------------------------------------- # +# Configuration +# --------------------------------------------------------------------------- # + +APP_NAME = "meshterm-spi-bridge" +DEFAULT_HOST = "127.0.0.1" +DEFAULT_PORT = 5000 +DEFAULT_NODE_NAME = "uConsole" + +# Interpreters likely to have pymc_core, in preference order. The hackergadgets +# uConsole .deb installs everything into this private virtualenv. +VENV_CANDIDATES = ["/opt/venvs/meshcore-uconsole/bin/python"] + +HOME = Path.home() +INSTALL_PATH = HOME / ".local" / "bin" / APP_NAME +UNIT_NAME = f"{APP_NAME}.service" +UNIT_PATH = HOME / ".config" / "systemd" / "user" / UNIT_NAME +MESHTERM_CONFIG = HOME / ".meshterm" / "config.toml" + +RULE = "=" * 62 +THIN = "-" * 62 + + +# --------------------------------------------------------------------------- # +# Colour (restrained — off when piped, dumb terminal, or NO_COLOR is set) +# --------------------------------------------------------------------------- # + +_USE_COLOR = ( + sys.stdout.isatty() + and not os.environ.get("NO_COLOR") + and not os.environ.get("MESHTERM_NO_COLOR") + and os.environ.get("TERM", "") != "dumb" +) + + +def _c(text: str, code: str) -> str: + return f"\033[{code}m{text}\033[0m" if _USE_COLOR else text + + +def bold(t: str) -> str: + return _c(t, "1") + + +def dim(t: str) -> str: + return _c(t, "2") + + +def green(t: str) -> str: + return _c(t, "32") + + +def red(t: str) -> str: + return _c(t, "1;31") + + +def yellow(t: str) -> str: + return _c(t, "33") + + +def cyan(t: str) -> str: + return _c(t, "36") + + +def cmd(t: str) -> str: + """Highlight a command the user should type/copy.""" + return bold(cyan(t)) + + +# --------------------------------------------------------------------------- # +# Small text helpers (deliberately plain — a little colour, no flourish) +# --------------------------------------------------------------------------- # + + +def tag(ok: bool, warn: bool = False) -> str: + if warn: + return yellow("[warn]") + return green("[ ok ]") if ok else red("[FAIL]") + + +def ask(prompt: str, default: str = "") -> str: + try: + return input(prompt).strip() + except (EOFError, KeyboardInterrupt): + print() + return default + + +def confirm(prompt: str, default_yes: bool = False) -> bool: + suffix = " [Y/n] " if default_yes else " [y/N] " + ans = ask(prompt + suffix).lower() + if not ans: + return default_yes + return ans in ("y", "yes") + + +# --------------------------------------------------------------------------- # +# Runtime discovery +# --------------------------------------------------------------------------- # + + +def python_has_pymc(python: str) -> bool: + """Return whether `python` can import pymc_core.""" + if not python or not os.path.exists(python): + return False + try: + r = subprocess.run( + [python, "-c", "import pymc_core"], + stdout=subprocess.DEVNULL, + stderr=subprocess.DEVNULL, + timeout=20, + ) + return r.returncode == 0 + except Exception: + return False + + +def _meshcore_console_python() -> str | None: + """Resolve the interpreter behind the `meshcore-console` command, if present.""" + exe = shutil.which("meshcore-console") + if not exe: + return None + try: + first = Path(exe).resolve().read_text(errors="replace").splitlines()[0] + except Exception: + return None + if first.startswith("#!"): + cand = first[2:].strip().split()[0] + if cand.endswith("python") or "python" in os.path.basename(cand): + return cand + return None + + +def find_pymc_python() -> str | None: + """Find an interpreter that has pymc_core, or None. + + Order: explicit override, this interpreter, known venv paths, then the + interpreter behind an installed `meshcore-console`. + """ + seen: set[str] = set() + candidates = [os.environ.get("MESHTERM_PYMC_PYTHON", ""), sys.executable] + candidates += VENV_CANDIDATES + mcc = _meshcore_console_python() + if mcc: + candidates.append(mcc) + for c in candidates: + if c and c not in seen: + seen.add(c) + if python_has_pymc(c): + return c + return None + + +# --------------------------------------------------------------------------- # +# Preflight checks +# --------------------------------------------------------------------------- # + + +def _dev_ok(path: str) -> tuple[bool, str]: + if not os.path.exists(path): + return False, "missing" + if not os.access(path, os.R_OK | os.W_OK): + return False, "present but no read/write permission" + return True, "present, read/write ok" + + +def _first_spidev() -> str | None: + import glob + + devs = sorted(glob.glob("/dev/spidev*")) + if "/dev/spidev1.0" in devs: + return "/dev/spidev1.0" + return devs[0] if devs else None + + +def port_listening(host: str, port: int) -> bool: + """Return whether something is already accepting connections on host:port.""" + try: + with socket.create_connection((host, port), timeout=1.5): + return True + except OSError: + return False + + +def meshcore_console_running() -> list[str]: + """Best-effort list of running meshcore-console (GUI/CLI) command lines.""" + try: + out = subprocess.check_output( + ["pgrep", "-af", "meshcore-console"], text=True, stderr=subprocess.DEVNULL + ) + except Exception: + return [] + lines = [] + for line in out.splitlines(): + # our own bridge invokes the meshcore-uconsole venv python, not the + # meshcore-console binary, so it never matches — but guard anyway. + if "--run-bridge" in line or APP_NAME in line: + continue + lines.append(line.strip()) + return lines + + +def systemctl_user(*args: str) -> subprocess.CompletedProcess: + return subprocess.run( + ["systemctl", "--user", *args], + stdout=subprocess.PIPE, + stderr=subprocess.PIPE, + text=True, + ) + + +def service_installed() -> bool: + return UNIT_PATH.exists() + + +def service_active() -> bool: + return systemctl_user("is-active", UNIT_NAME).stdout.strip() == "active" + + +class Preflight: + def __init__(self) -> None: + self.python = find_pymc_python() + self.spidev = _first_spidev() + self.spidev_ok, self.spidev_detail = ( + _dev_ok(self.spidev) if self.spidev else (False, "no /dev/spidev* found") + ) + self.gpio_ok, self.gpio_detail = _dev_ok("/dev/gpiochip0") + self.svc_active = service_active() + self.port_busy = port_listening(DEFAULT_HOST, DEFAULT_PORT) + self.gui = meshcore_console_running() + + @property + def can_run(self) -> bool: + return bool(self.python) and self.spidev_ok and self.gpio_ok + + def print(self) -> None: + print(bold("Prerequisite check:")) + # 1. runtime + if self.python: + print(f" {tag(True)} pymc_core runtime {self.python}") + else: + print(f" {tag(False)} pymc_core runtime not found") + print(" fix: install the radio stack, e.g. on the uConsole:") + print(" sudo apt install meshcore-uconsole") + print(" (or set MESHTERM_PYMC_PYTHON to a python that has it)") + # 2. spi + print(f" {tag(self.spidev_ok)} SPI device {self.spidev or '-'} — {self.spidev_detail}") + if not self.spidev_ok and self.spidev is None: + print(" fix: enable SPI in /boot/firmware/config.txt") + print(" (dtoverlay=spi1-1cs on the uConsole) and reboot") + elif not self.spidev_ok: + print(" fix: add your user to the 'spi' group, then log out/in:") + print(" sudo usermod -aG spi $USER") + # 3. gpio + print(f" {tag(self.gpio_ok)} GPIO chip /dev/gpiochip0 — {self.gpio_detail}") + if not self.gpio_ok and "permission" in self.gpio_detail: + print(" fix: sudo usermod -aG gpio $USER (then log out/in)") + # 4. radio availability (informational) + if self.svc_active: + print(f" {tag(True)} bridge service running (radio in use by the boot service)") + elif self.gui: + print(f" {tag(False, warn=True)} radio in use meshcore-console is running:") + for line in self.gui[:2]: + print(f" {line[:70]}") + print(" note: only one program can use the radio at a time —") + print(" close meshcore-console before running the bridge") + elif self.port_busy: + print(f" {tag(False, warn=True)} port {DEFAULT_PORT} busy something is already on {DEFAULT_HOST}:{DEFAULT_PORT}") + else: + print(f" {tag(True)} radio is free nothing else is using it") + + +# --------------------------------------------------------------------------- # +# Caveats banner +# --------------------------------------------------------------------------- # + +CAVEATS = """\ +How this works, briefly: + * Your LoRa radio is wired to the host's SPI bus — there is no separate + MCU and no firmware to flash. The mesh node runs as software here. + * This bridge runs that node and exposes it on a local network port so + MeshTerm can connect with: meshterm --tcp {host}:{port} + * Two processes cooperate: this bridge (owns the radio) and MeshTerm + (the terminal you use). Keep the bridge running while you use MeshTerm. + +Caveat — only ONE program may use the radio at a time: + * Run EITHER the meshcore-console GUI, OR this bridge — never both. + * If the bridge won't start, close meshcore-console first.""" + + +def print_caveats() -> None: + text = CAVEATS.format(host=DEFAULT_HOST, port=DEFAULT_PORT) + for line in text.splitlines(): + if line.endswith(":") and not line.startswith(" "): + print(bold(line)) + elif "meshterm --tcp" in line: + print(line.replace( + f"meshterm --tcp {DEFAULT_HOST}:{DEFAULT_PORT}", + cmd(f"meshterm --tcp {DEFAULT_HOST}:{DEFAULT_PORT}"), + )) + else: + print(line) + + +# --------------------------------------------------------------------------- # +# Actions +# --------------------------------------------------------------------------- # + + +def action_run_now(pre: Preflight) -> None: + if pre.svc_active: + print() + print("The bridge is already running as a boot service, so the radio is") + print("in use and MeshTerm can connect right now:") + print(" " + cmd(f"meshterm --tcp {DEFAULT_HOST}:{DEFAULT_PORT}")) + print("To run it in this terminal instead, stop the service first (menu") + print("option 3, or: systemctl --user stop " + UNIT_NAME + ").") + return + if pre.gui: + print() + print("meshcore-console is running and holding the radio. Close it first,") + print("then try again.") + return + if not pre.can_run: + print("\nCan't run yet — resolve the [FAIL] items above first.") + return + + print() + print(dim(THIN)) + print("Starting the bridge. Leave this running, open another terminal, and:") + print(" " + cmd(f"meshterm --tcp {DEFAULT_HOST}:{DEFAULT_PORT}")) + print("Press Ctrl+C here to stop the bridge.") + print(dim(THIN)) + offer_meshterm_profile() + print() + run_cmd = [pre.python, os.path.abspath(__file__), "--run-bridge", + "--host", DEFAULT_HOST, "--port", str(DEFAULT_PORT), "--name", DEFAULT_NODE_NAME] + try: + subprocess.run(run_cmd) + except KeyboardInterrupt: + pass + print("\nBridge stopped. Back to the menu.") + + +def _write_unit(python: str) -> None: + UNIT_PATH.parent.mkdir(parents=True, exist_ok=True) + exec_start = ( + f"{python} {INSTALL_PATH} --run-bridge " + f"--host {DEFAULT_HOST} --port {DEFAULT_PORT} --name {DEFAULT_NODE_NAME}" + ) + UNIT_PATH.write_text( + "[Unit]\n" + "Description=MeshTerm SPI-radio companion bridge (pymc_core -> TCP)\n" + "After=network.target\n\n" + "[Service]\n" + "Type=simple\n" + f"ExecStart={exec_start}\n" + "Restart=on-failure\n" + "RestartSec=3\n\n" + "[Install]\n" + "WantedBy=default.target\n" + ) + + +def action_install_service(pre: Preflight) -> None: + if not pre.python: + print("\nCan't install — the pymc_core runtime wasn't found (see above).") + return + if pre.gui: + print("\nmeshcore-console is running. The service would fight it for the") + print("radio. Close meshcore-console first, then install the service.") + if not confirm("Install anyway?"): + return + + print() + print("This will install a background service that:") + print(f" * runs the bridge on {DEFAULT_HOST}:{DEFAULT_PORT}") + print(" * starts automatically on boot and restarts if it crashes") + print(" * runs as YOU, using your node identity (same as the GUI)") + print("Reminder: while it's running, don't also open the meshcore-console GUI.") + if not confirm("\nInstall and start it now?", default_yes=True): + print("Cancelled.") + return + + # Install a stable copy of this script for the unit to point at. + INSTALL_PATH.parent.mkdir(parents=True, exist_ok=True) + if os.path.abspath(__file__) != str(INSTALL_PATH): + shutil.copyfile(os.path.abspath(__file__), INSTALL_PATH) + INSTALL_PATH.chmod(0o755) + + _write_unit(pre.python) + systemctl_user("daemon-reload") + r = systemctl_user("enable", "--now", UNIT_NAME) + if r.returncode != 0: + print("\nFailed to start the service:") + print(" " + (r.stderr.strip() or "unknown error")) + return + + # Try to make it start at boot even before you log in. + linger = subprocess.run( + ["loginctl", "enable-linger", os.environ.get("USER", "")], + stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, + ) + + print(green("\nInstalled and started.")) + if service_active(): + print(f" {tag(True)} service is running") + print(f" unit: {UNIT_PATH}") + print(f" logs: journalctl --user -u {UNIT_NAME} -f") + if linger.returncode != 0: + print("\nOne extra step for start-on-boot without logging in first:") + print(f" sudo loginctl enable-linger {os.environ.get('USER','')}") + offer_meshterm_profile() + print("\nConnect from MeshTerm with: " + cmd(f"meshterm --tcp {DEFAULT_HOST}:{DEFAULT_PORT}")) + + +def action_uninstall_service() -> None: + if not service_installed(): + print("\nNo bridge service is installed. Nothing to remove.") + print("(This never touches the hackergadgets meshcore-console package.)") + return + print("\nThis removes ONLY the bridge service and its helper script.") + print("It does NOT remove meshcore-console or the radio stack.") + if not confirm("Remove the bridge service now?", default_yes=True): + print("Cancelled.") + return + systemctl_user("disable", "--now", UNIT_NAME) + try: + UNIT_PATH.unlink() + except FileNotFoundError: + pass + systemctl_user("daemon-reload") + # Remove the installed helper copy (but not a repo checkout you ran from). + if INSTALL_PATH.exists() and os.path.abspath(__file__) != str(INSTALL_PATH): + try: + INSTALL_PATH.unlink() + except OSError: + pass + print(green("\nRemoved.") + " The radio is free again for the meshcore-console GUI.") + if MESHTERM_CONFIG.exists() and "[profiles.bridge]" in MESHTERM_CONFIG.read_text(errors="replace"): + print("Note: a [profiles.bridge] block remains in your MeshTerm config;") + print(f" edit {MESHTERM_CONFIG} to remove it if you like.") + + +def action_status(pre: Preflight) -> None: + print() + print(bold("Bridge service:")) + if not service_installed(): + print(" not installed") + else: + print(f" installed {UNIT_PATH}") + print(f" active: {'yes' if service_active() else 'no'}") + print(f" logs: journalctl --user -u {UNIT_NAME} -f") + listening = port_listening(DEFAULT_HOST, DEFAULT_PORT) + print(f"\nEndpoint {DEFAULT_HOST}:{DEFAULT_PORT}: {'listening' if listening else 'not listening'}") + if listening: + print(" MeshTerm can connect now: " + cmd(f"meshterm --tcp {DEFAULT_HOST}:{DEFAULT_PORT}")) + + +def offer_meshterm_profile() -> None: + """Optionally add a MeshTerm TCP profile so bare `meshterm` connects here.""" + if MESHTERM_CONFIG.exists() and "[profiles.bridge]" in MESHTERM_CONFIG.read_text(errors="replace"): + return # already there + if not confirm( + f"\nAdd a 'bridge' profile to {MESHTERM_CONFIG} so you can just run " + "`meshterm`?", + default_yes=False, + ): + return + block = ( + "\n# Added by meshterm-spi-bridge — the local SPI-radio bridge.\n" + "[profiles.bridge]\n" + f'host = "{DEFAULT_HOST}"\n' + f"tcp_port = {DEFAULT_PORT}\n" + 'description = "Local SPI radio via meshterm-spi-bridge"\n' + ) + try: + MESHTERM_CONFIG.parent.mkdir(parents=True, exist_ok=True) + with MESHTERM_CONFIG.open("a", encoding="utf-8") as fh: + fh.write(block) + print("Added [profiles.bridge]. It'll show up in MeshTerm's device") + print("picker as 'bridge' — just select it there, or run: meshterm -p bridge") + except OSError as exc: + print(f"Couldn't write the profile ({exc}); add it by hand if you want it.") + + +# --------------------------------------------------------------------------- # +# Interactive menu +# --------------------------------------------------------------------------- # + + +def menu() -> int: + while True: + pre = Preflight() + print() + print(cyan(RULE)) + print(bold(cyan(" MeshTerm SPI-radio bridge — setup"))) + print(cyan(RULE)) + print_caveats() + print() + pre.print() + print() + print(bold("What would you like to do?")) + print(f" {bold('1')}) Run the bridge now (stays in this terminal; Ctrl+C to stop)") + print(f" {bold('2')}) Install as a service (starts on boot, restarts on failure)") + print(f" {bold('3')}) Uninstall the service") + print(f" {bold('4')}) Show status") + print(f" {bold('5')}) Quit") + choice = ask("\n> ") + if choice == "1": + action_run_now(pre) + elif choice == "2": + action_install_service(pre) + elif choice == "3": + action_uninstall_service() + elif choice == "4": + action_status(pre) + elif choice in ("5", "q", "quit", "exit", ""): + print("Bye.") + return 0 + else: + print("Please choose 1-5.") + ask("\nPress Enter to continue…") + + +# --------------------------------------------------------------------------- # +# The bridge itself (runs under the pymc_core interpreter via --run-bridge) +# --------------------------------------------------------------------------- # + + +def run_bridge(host: str, port: int, node_name: str) -> int: + import asyncio + import logging + + logging.basicConfig( + level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s" + ) + log = logging.getLogger(APP_NAME) + + try: + import pymc_core # noqa: F401 + except ImportError: + sys.stderr.write( + "This must run under a Python that has pymc_core. Run the menu instead " + "(it finds the right one), or set MESHTERM_PYMC_PYTHON.\n" + ) + return 2 + + from pymc_core.companion import CompanionFrameServer, CompanionRadio + + # Prefer the hackergadgets meshcore_console helpers (correct board pins + + # the SAME node identity the GUI uses). Fall back to a direct pymc_core + # setup for a generic install (e.g. a Waveshare HAT with pip'd pymc_core). + identity = None + radio = None + try: + from meshcore_console.meshcore.config import load_hardware_config_from_env + from meshcore_console.meshcore.paths import identity_key_path + from meshcore_console.meshcore.runtime import create_radio, import_pymc_core + + SX1262Radio, _ES, _ESub, _MN, LocalIdentity = import_pymc_core() + hw = load_hardware_config_from_env() + log.info("radio config %s", hw.to_log_string()) + radio = create_radio(SX1262Radio, hw, log.info) + key_path = identity_key_path() + if key_path.exists(): + identity = LocalIdentity(key_path.read_bytes()) + log.info("using existing node identity at %s", key_path) + radio_config = { + "frequency": hw.frequency, "bandwidth": hw.bandwidth, + "spreading_factor": hw.spreading_factor, "coding_rate": hw.coding_rate, + "tx_power": hw.tx_power, + } + except ImportError: + log.info("meshcore_console not present — using direct pymc_core defaults") + from pymc_core.hardware.sx1262_wrapper import SX1262Radio + from pymc_core.protocol.identity import LocalIdentity + + radio = SX1262Radio( + bus_id=int(os.environ.get("MESHCORE_BUS_ID", 1)), + cs_id=int(os.environ.get("MESHCORE_CS_ID", 0)), + cs_pin=int(os.environ.get("MESHCORE_CS_PIN", -1)), + reset_pin=int(os.environ.get("MESHCORE_RESET_PIN", 25)), + busy_pin=int(os.environ.get("MESHCORE_BUSY_PIN", 24)), + irq_pin=int(os.environ.get("MESHCORE_IRQ_PIN", 26)), + frequency=int(os.environ.get("MESHCORE_FREQUENCY", 910_525_000)), + tx_power=int(os.environ.get("MESHCORE_TX_POWER", 22)), + spreading_factor=int(os.environ.get("MESHCORE_SPREADING_FACTOR", 7)), + bandwidth=int(os.environ.get("MESHCORE_BANDWIDTH", 62_500)), + coding_rate=int(os.environ.get("MESHCORE_CODING_RATE", 5)), + ) + radio_config = { + "frequency": 910_525_000, "bandwidth": 62_500, + "spreading_factor": 7, "coding_rate": 5, "tx_power": 22, + } + key_path = HOME / ".local" / "share" / APP_NAME / "identity.key" + if key_path.exists(): + identity = LocalIdentity(key_path.read_bytes()) + + if identity is None: + # No persisted identity anywhere — mint one and save it so the node + # keeps a stable identity across restarts. + from pymc_core.protocol.identity import LocalIdentity as _LI + + tmp = _LI() + seed = tmp.get_signing_key_bytes() + save_path = HOME / ".local" / "share" / APP_NAME / "identity.key" + save_path.parent.mkdir(parents=True, exist_ok=True) + save_path.write_bytes(seed) + identity = _LI(seed) + log.info("generated a new node identity at %s", save_path) + + async def _main() -> int: + # radio.begin() with backoff — GPIO lines may still be held briefly by + # a just-closed session. + import time + + for attempt in range(4): + log.info("radio.begin() attempt %d/4", attempt + 1) + try: + if not radio.begin(): + raise RuntimeError("radio.begin() returned False") + break + except SystemExit: + if attempt == 3: + raise RuntimeError("GPIO pins still busy after retries") + try: + radio.cleanup() + except Exception: + pass + time.sleep(2.0 * (attempt + 1)) + log.info("radio ready") + + companion = CompanionRadio(radio, identity, node_name=node_name, radio_config=radio_config) + await companion.start() + pub = companion.get_public_key() + log.info("node identity %s… (hash 0x%02x, name %r)", pub.hex()[:16], pub[0], node_name) + + server = CompanionFrameServer( + bridge=companion, + companion_hash=f"{pub[0]:02x}", + port=port, + bind_address=host, + local_hash=pub[0], + device_model="pyMC-spi-bridge", + ) + await server.start() + log.info("READY — connect with: meshterm --tcp %s:%d", host, port) + + import signal + + stop = asyncio.Event() + loop = asyncio.get_running_loop() + for sig in (signal.SIGINT, signal.SIGTERM): + try: + loop.add_signal_handler(sig, stop.set) + except NotImplementedError: + pass + try: + await stop.wait() + finally: + log.info("shutting down…") + try: + await server.stop() + await companion.stop() + except Exception: + pass + return 0 + + try: + return asyncio.run(_main()) + except KeyboardInterrupt: + return 0 + except Exception as exc: # surface a clean message, not a traceback wall + log.error("bridge failed: %s", exc) + return 1 + + +# --------------------------------------------------------------------------- # +# Entry point +# --------------------------------------------------------------------------- # + + +def main() -> int: + ap = argparse.ArgumentParser( + description="Expose an SPI-attached MeshCore radio to MeshTerm over TCP." + ) + ap.add_argument("--check", action="store_true", help="run prerequisite checks and exit") + ap.add_argument("--run", action="store_true", help="run the bridge now (finds the runtime)") + ap.add_argument("--run-bridge", action="store_true", help=argparse.SUPPRESS) + ap.add_argument("--host", default=DEFAULT_HOST) + ap.add_argument("--port", type=int, default=DEFAULT_PORT) + ap.add_argument("--name", default=DEFAULT_NODE_NAME) + args = ap.parse_args() + + # Internal: we've already been re-execed under the pymc_core interpreter. + if args.run_bridge: + return run_bridge(args.host, args.port, args.name) + + if args.check: + Preflight().print() + return 0 + + if args.run: + pre = Preflight() + pre.print() + action_run_now(pre) + return 0 + + return menu() + + +if __name__ == "__main__": + raise SystemExit(main())