Files
MeshCore/tools/motatool
Valentin Kivachuk Burda 8953214761 ota: fragment-level want_mask requests (anti-burst) + warm-start leaf-diff capture
Protocol: OTA_REQ and OTA_GET_MANIFEST now carry a want_mask bitmap, so a fetcher asks for specific fragments (all on the first request, only the still-missing holes on a retry) instead of a whole block/manifest window. The WANT_MANIFEST and FETCHING retry loops re-ask only on a no-progress tick, so a lost fragment costs one fragment to recover and a re-request can't collide with an in-flight multi-fragment burst on half-duplex radios.

Warm-start (motatool folder-capture only): new OTA_GET_LEAVES/OTA_LEAVES let `ota pull <#> folder validate` bulk-fetch the target's merkle leaves, authenticate them against the manifest root, diff a similar seed build already staged in the destination, and pull DATA over LoRa only for the blocks that differ. Leaves are bitmap-fragmented + no-progress retry-gated like the manifest, capped at OTA_DIFF_MAX_BLOCKS so the want_mask stays a fixed uint16, and the diff runs a bounded batch per loop tick so it never starves the mesh loop. motatool `serve --seed <build.mota>` injects the seed payload into the destination .part on OP_BEGIN.
2026-07-02 19:03:28 +02:00
..

motatool — self-contained MeshCore OTA host tool (C++)

A small, portable C++17 tool that builds, verifies, and serves MeshCore .mota firmware-update containers. It is an independent project (its own CMakeLists.txt) that compiles on a laptop, a Raspberry Pi, or any architecture with a C++17 compiler — so it can run as a lightweight folder-relay daemon on small hardware.

It implements the wire spec in ../../docs/ota_protocol.md and is cross-checked byte-for-byte against the Python reference packager tools/mota/motalib.py (a full signed .mota built by motatool is identical to the reference's output).

What it does

Command Purpose
build Create a full or delta .mota from a firmware (local file or http(s) URL).
verify Validate one or more .mota (merkle tree, leaves vs payload, image hash, Ed25519 signature). --pub requires a specific signer; --base confirms a sequential delta rebuilds its image.
inspect Print every field of a .mota's manifest (debugging).
serve Serve a folder of .mota to a node over USB serial (--serial) or WiFi (--tcp). Invalid files are warned about and skipped — one corrupt file never sinks the rest. The same link also stores a node's ota pull … folder captures into that folder as <id>.mota — pull a device's exact firmware off the mesh to build deltas against firmware you don't otherwise have.
keygen Generate an Ed25519 signing keypair (hex).

Every command has detailed, example-rich help: motatool <command> --help.

Build

Dependencies: a C++17 compiler, CMake, and OpenSSL (libcrypto: SHA-256 + Ed25519). For URL input and delta creation, see the notes below.

sudo apt install build-essential cmake libssl-dev      # Debian / Ubuntu / Raspberry Pi OS
cmake -S tools/motatool -B tools/motatool/build
cmake --build tools/motatool/build -j
# -> tools/motatool/build/motatool

Tests

Unit tests (a tiny built-in harness — no external framework) cover the crypto, EndF, build/verify, merkle, parse rejection, the folder scanner + seeder protocol, and a real detools delta round-trip (auto-skipped if detools isn't installed):

ctest --test-dir tools/motatool/build --output-on-failure
# or directly:  tools/motatool/build/motatool_tests

Usage

MT=tools/motatool/build/motatool

# 1. signing keypair (64-char hex)
$MT keygen --out signer.key            # writes signer.key + signer.key.pub

# 2a. FULL .mota — payload IS the flashable image (identity is auto-read from the firmware's EndF)
$MT build --fw firmware.bin --sign signer.key --out-dir ./motas/

# 2b. FULL .mota straight from a URL
$MT build --fw https://example.org/Heltec_v3_repeater.bin --sign signer.key --out-dir ./motas/

# 2c. DELTA .mota against a previous release (codec auto-selected from the hardware tag:
#     nRF52 -> in-place, ESP32 -> sequential; override with --codec)
$MT build --fw new.bin --base old.bin --sign signer.key --out-dir ./motas/
$MT build --fw new.bin --base old.bin --codec sequential --out-dir ./motas/

# 3. validate a folder of .mota (optionally require a signer / check a delta against its base)
$MT verify ./motas/*.mota
$MT verify update.mota --pub signer.key.pub
$MT verify delta.mota  --base old_firmware.bin

# 4. dump a single .mota's manifest fields
$MT inspect ./motas/RAK4631_04D413FD_v1.16.0_full_ABCD1234.mota

# 5. serve a folder to a node (recursive; skips non-.mota; warns on corrupt)
$MT serve --dir ./motas --serial /dev/ttyUSB0 --baud 115200 -v   # over USB serial
$MT serve --dir ./motas --tcp 192.168.1.50:5001 -v               # …or over WiFi (ESP32 companion, port 5001)

# 5b. warm-start a capture: seed the pull with a SIMILAR build, then `ota pull <#> folder validate` on the
#     node pulls only the blocks that differ (fast capture of a non-deterministic rebuild of the same fw)
$MT serve --dir ./captured --tcp 192.168.1.50:5001 --seed ./similar_build.mota -v

serve doubles as the pull-to-folder storage: a node's ota pull <#> folder captures the firmware it's fetching off-mesh into --dir as <mid>.mota. With --seed <similar.mota>, that seed's payload is staged into each capture so a ota pull <#> folder validate on the node bulk-fetches the target's merkle leaves, keeps every block the seed already matches, and transfers over LoRa only the differing ones — a byte-exact, verifiable capture in seconds instead of a full-image download (see ../../docs/ota_protocol.md §8, "warm-start").

build notes:

  • Identity is self-described. A firmware built by the project's pio_endf.py carries its target_id/fw_version/hw_id in its 56-byte EndF trailer; build reads them, so --target-env/--target-id, --fw-version, and --hw-id are optional (explicit flags override).
  • Cross-hardware delta guard. A delta is refused if the base and target firmware identities differ (read from their EndF, not filenames); pass --force to override.
  • Delta codec needs the detools encoder (the project's pinned codec — never reimplemented). Install it (pip install detools) and ensure it's on PATH, or pass --detools <path>. Full builds, verify, and serve need no detools. In-place defaults: --inplace-memory 0xAE000 (nRF52 workspace), --inplace-segment 4096.
  • URL input uses the system curl (falling back to wget) — no link-time dependency.
  • All output is written into one folder (--out-dir, default .) with a descriptive, unique name: <hw>_<target>_v<ver>_<full|seqdelta|ipdelta>_<mid>.mota.

Serving is transport-agnostic (USB serial today, BLE later)

The protocol is split so the serving logic is reusable across links:

  • SeederCore (src/serve.{h,cpp}) is transport-free: it maps a request (op, args) to a response (status, payload) — COUNT / DESCRIBE(idx) / READ(idx, off, len) over the validated catalog.
  • Transport + serve_loop() wrap it with the byte-stream framing (magic + XOR checksum + resync, MotaSeederProto.h). Two transports ship: SerialTransport (--serial, USB-UART) and TcpTransport (--tcp <host[:port]>, WiFi — connects to the node's dedicated seeder port, default 5001, which the ESP32 companion runs alongside its phone-app port so both work at once).

To serve the same folder over BLE (e.g. an Android phone relaying to a MeshCore node), implement the transport at the GATT layer — a request characteristic write hands (op, args) straight to SeederCore::handle() and the reply is sent as a notification. No byte-stream framing is needed there (BLE is reliable/segmented), and SeederCore + Folder are reused unchanged. OpenSSL builds for the Android NDK, so the validation path ports as-is.

Relationship to tools/mota/

motatool is the user-facing CLI: it replaced the old Python mota.py (build/verify/inspect/keygen), mota_seeder.py (serve), and dev_motas.py (CI .mota packaging — its nRF52 .hex extraction is now a built-in motatool input format), all removed. The Python tools/mota/ directory remains as the reference implementation (motalib.py, the spec oracle + unit tests) and the firmware build/test glue (pio_endf.py build hook, gen_vectors.py test vectors). Their .mota output is byte-identical (verified by cross-checks).