Files
meshcore-tth/tools/README.md
T
tthandClaude Opus 5.5 d22005a6fd
pub-release / release (push) Successful in 32m57s
OTA phase 5: tools and docs ready for the public export
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 18:07:39 +01:00

75 lines
3.7 KiB
Markdown

<!-- SPDX-License-Identifier: MIT -->
# tools/
Host-side tools for MeshCore nodes of this fork: consoles, flashing, bench
tests and diagnostics. Every script answers `--help` without touching a port,
a node or the network.
## Your boards: the local config
The tools carry no board serial, MAC or host of anyone's bench. Names like
`b1` resolve through one file outside the repo:
~/.config/meshcore-tools/config.ini (or $MESHCORE_TOOLS_CONFIG)
Start from [`config.example.ini`](config.example.ini); the format and the shell
interface are in `mctools_config.py --help`. Without a config everything still
works with full USB serial numbers, BLE MACs and port paths. Two fields matter
for safety: `protect` (flashing tools refuse the board unless told to) and
`refuse` (console tools do not open it at all, e.g. the radio of an observer
running other firmware). No secrets go in there.
Serial ports are always matched in `/dev/serial/by-id` by the USB serial
number: a `ttyACM` number changes with every replug and would point a tool at
a different board.
## Consoles
| tool | what |
|---|---|
| `serial_cli.py` | text console over USB: send commands, print the replies |
| `ble_cli.py` | the same console over BLE (Nordic UART); needs a bonded node |
| `ble_pair.py` | non-interactive BLE pairing by PIN (bluetoothctl over a pty) |
| `serial_tcp_proxy.py` | a board's USB console on a localhost TCP port, for a board on another host (SSH tunnel) |
## Flashing
| tool | what |
|---|---|
| `flash_node.sh` | flash any board: picks USB DFU, UF2 or BLE from what the board is doing, refuses `protect`ed boards |
| `xiao_uf2_flash.sh` | XIAO nRF52840 through its UF2 drive, to a named board, verified by reading the version back |
| `xiao_serial_dfu.sh` | XIAO with a text console over USB serial DFU: no drive, no mount, no root |
| `ble_flash_node.sh` | BLE OTA of a node out of reach of a cable, with the checks around it (silence, services, version) |
| `ble_dfu.py` | legacy Nordic DFU over BLE for the Adafruit nRF52 bootloader (buttonless, both phases) |
| `build_version.py` | PlatformIO pre-script: real version and build time for `ver` |
## Admin-pushed firmware update (experimental `-ota` images)
| tool | what |
|---|---|
| `ota_pack.py` | `fetch` a signed package of a release and check it; `info`; build and sign your own (`pack`, `diff`) |
| `ota_push.py` | push a package over the USB console (text, or the mesh protocol via `fw bin`) |
| `ota_mesh_push.py` | push a delta over the mesh through a companion, as admin |
| `ota_ramlib.py` | PlatformIO script: runs the delta applier from RAM (a build dependency) |
| `ota_check_ramfunc.sh` | checks that an `-ota` build's RAM code never calls into flash |
| `ota_allowed_signers` | the release signer (`ssh-keygen -Y verify`) |
How it works: [docs/ota.md](../docs/ota.md).
## Bench and diagnostics
| tool | what |
|---|---|
| `board_probe.py` | what runs on each board on USB, and whether that changed |
| `fleet_test.py` | regression smoke test of the bench boards after a firmware change |
| `bench_soak.py` | long run: who hears whom over time, when a board reboots or goes deaf |
| `radio_stall_watch.py` | watch a `RADIO_DIAG` node until its receiver stalls |
| `mesh_sniffer.py` | passive sniffer: every frame the radio hears, decoded on the host |
| `preset_trace.py` | TRACE along a fixed path on a chosen radio preset |
| `fw_room_smoke.py` | smoke test of a firmware room server over the air |
| `power_ab.py` | A/B current measurement with a UC96 meter (alternating cells) |
| `companion_backup.py` | back up a companion (contacts, channels, settings) before flashing, diff and restore after |
| `gen_node_id.py` | a node identity whose path hash collides with no known repeater |
`fleet.py` and `mctools_config.py` are the shared board lookup.