Files
meshcore-tth/tools/ble_cli.py
T

185 lines
7.6 KiB
Python
Executable File

#!/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 <MAC>, 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 (`<MAC> -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()