81 lines
4.5 KiB
Markdown
81 lines
4.5 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. They serve an experimental fork that is not meant for
|
|
regular users (see the [README](../README.md)); several of them transmit or
|
|
reflash a node.
|
|
|
|
## 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` |
|
|
| `bl_sign_pkg.py` | DFU zip for a board with the signed (`SIGNED_FW`) Adafruit bootloader: `adafruit-nrfutil dfu genpkg --key-file` with its two Python 3 bugs on that path fixed |
|
|
| `bl_verify_pkg.py` | checks a DFU zip the way the signed bootloader will (device type, ECDSA P-256 over the init packet, image length and hash) |
|
|
| `bl_allowed_key` | the public key the signed bootloader carries (`SIGNED_FW_QX`/`QY`) |
|
|
|
|
## 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 (`--side`: on a side channel via `tempradio`) |
|
|
| `ota_collection.py` | finds the OTA engine both push tools run: the tth.meshcore Ansible collection's module_utils |
|
|
| `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.
|