#!/usr/bin/env python3 # SPDX-License-Identifier: MIT """Text console of a MeshCore node over BLE (Nordic UART Service). The same console you get on USB serial, but wireless -- which is the only way in once a node is mounted somewhere without a cable. Works against any build that has `BLE_PIN_CODE` set (repeater, room server, companion_radio_ble). Why this exists as a tool rather than a snippet: the NUS write has a size limit that is easy to miss and fails in a misleading way (see CHUNK below), and the BlueZ/bleak connect path needs retries to be usable for anything longer than a single command. Every ad-hoc script re-learned both the hard way. # single command (a MAC, or a board name from the local config) ble_cli.py AA:BB:CC:DD:EE:10 ver ble_cli.py hill-rpt ver # several, one connection ble_cli.py AA:BB:CC:DD:EE:10 "get radio" "get name" stats-radio # from a file, one command per line, '#' comments ignored ble_cli.py AA:BB:CC:DD:EE:10 -f provision.txt # {epoch} expands to the host's current unix time -- the point being that a # provisioning FILE can carry `time {epoch}`, which a shell cannot reach ble_cli.py AA:BB:CC:DD:EE:10 "time {epoch}" # keep reconnecting per command (slow, but survives a flaky link) ble_cli.py AA:BB:CC:DD:EE:10 --per-command "gps on" "set af 9" PAIRING: the console characteristics are SECMODE_ENC_WITH_MITM, so the node must be bonded first or the connect pops a passkey dialog on the desktop: bluetoothctl --agent KeyboardOnly # then: pair , enter the BLE PIN `erase` on the node wipes the bond too (bonds live in InternalFS), so re-pair after one. CAUTION: one console at a time. USB and BLE read into the same command buffer in the firmware (`simple_repeater/main.cpp`, "commands share the buffer"), so two consoles at once interleave into one line and can crash the node. """ import argparse import asyncio import sys import time from bleak import BleakClient, BleakScanner NUS_RX = "6e400002-b5a3-f393-e0a9-e50e24dcca9e" # write (host -> node) NUS_TX = "6e400003-b5a3-f393-e0a9-e50e24dcca9e" # notify (node -> host) # A NUS write carries at most ATT_MTU-3 bytes, and BlueZ will not split it for # you. At the default MTU of 23 that is 20 bytes -- and MeshCore nodes are # routinely left at 23. A longer write is rejected with # "[org.bluez.Error.Failed] Failed to initiate write", which reads like a # dropped link rather than "your command was too long": commands up to 18 # characters work and everything longer fails, deterministically. Hence chunking # every write, always. CHUNK = 20 def log(*a): print(*a, file=sys.stderr, flush=True) async def send(client, buf, cmd, wait): buf.clear() # {epoch} -> host unix time, expanded HERE rather than at parse time so that # it is the time the command is actually sent: --per-command reconnects cost # seconds each, and a whole -f file can take minutes. # # It exists for `time {epoch}` in a provisioning file. -f reads lines verbatim, # so a `$(date +%s)` in one is sent as literal text and the node answers # "Unknown command" -- which is why the clock line in a provisioning file # was a commented-out note telling you to substitute the epoch by hand. Every # clock in this firmware is volatile without GPS or an I2C RTC, and a node # whose RTC still says May 2024 has its adverts dropped as replays. cmd = cmd.replace("{epoch}", str(int(time.time()))) data = (cmd + "\r\n").encode() for i in range(0, len(data), CHUNK): await client.write_gatt_char(NUS_RX, data[i:i + CHUNK], response=False) await asyncio.sleep(0.15) await asyncio.sleep(wait) out = bytes(buf).decode("utf-8", "replace").strip() # the node echoes nothing, but replies are prefixed "-> " or "> " for p in ("-> ", "> "): if out.startswith(p): out = out[len(p):] # the EXPANDED command goes back too, so the printout says what was really # sent rather than the `{epoch}` template return cmd, out.strip() async def run(mac, cmds, wait, per_command, tries): async def connect(): last = None for attempt in range(tries): try: dev = await BleakScanner.find_device_by_address(mac, timeout=20) if dev is None: # a connected peripheral stops advertising; a stale link on # the adapter is the usual reason it cannot be found raise RuntimeError(f"{mac} not advertising (already connected?)") c = BleakClient(dev, timeout=30) await c.connect() return c except Exception as e: # noqa: BLE001 last = e log(f" [connect {attempt + 1}/{tries}] {type(e).__name__}: {e}") await asyncio.sleep(4) raise SystemExit(f"cannot connect to {mac}: {last}") results = [] if per_command: for cmd in cmds: c = await connect() try: buf = bytearray() await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d)) results.append(await send(c, buf, cmd, wait)) finally: await c.disconnect() await asyncio.sleep(2) else: c = await connect() try: buf = bytearray() await c.start_notify(NUS_TX, lambda _h, d: buf.extend(d)) for cmd in cmds: results.append(await send(c, buf, cmd, wait)) finally: await c.disconnect() return results def _mac(key): """A board name from the local config (tools/mctools_config.py) -> its MAC. Optional on purpose: ble_flash_node.sh --via copies this file ALONE to a remote host, where there is no config and a MAC is given anyway.""" try: from mctools_config import mac_for except ImportError: return key return mac_for(key) or key def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("mac", help="BLE address of the node, or its name in the local config") ap.add_argument("cmds", nargs="*", help="console commands") ap.add_argument("-f", "--file", help="read commands from a file, one per line") ap.add_argument("-w", "--wait", type=float, default=3.0, help="seconds to collect the reply (default 3; raise for " "paged output like rxlog/nodes)") ap.add_argument("--per-command", action="store_true", help="reconnect for every command -- slower, but survives a " "link that drops mid-sequence") ap.add_argument("--tries", type=int, default=5, help="connect attempts") # intermixed, not plain parse_args: with a trailing `cmds` of nargs="*", an # option BETWEEN the MAC and the commands (` -w 8 rxlog`, the form this # tool's own help suggests) makes argparse on Python <= 3.12 drop the # commands with "unrecognized arguments". 3.13 fixed it, so it works on an # Arch workstation and fails on the Debian hosts (bridge-host, cabin-host) that are # the only way to reach a mast node -- exactly where you cannot debug it. a = ap.parse_intermixed_args() a.mac = _mac(a.mac) cmds = list(a.cmds) if a.file: with open(a.file) as fh: cmds += [ln.strip() for ln in fh if ln.strip() and not ln.lstrip().startswith("#")] if not cmds: ap.error("no commands given") for cmd, out in asyncio.run(run(a.mac, cmds, a.wait, a.per_command, a.tries)): print(f"{cmd}\t{out}") if __name__ == "__main__": main()