Protocol

This page is everything a server needs to implement. Over MQTT that is about
60 lines in any language with an MQTT client; OtaServer in this library is
the same server side in C++.

Binary frames

Every transport uses the same frames. They're little-endian, and every frame
starts with the same six bytes:

Request (node → server), 16 bytes

The server slices the range into chunks no bigger than max chunk (and its own
limit) and sends them in order. A node may send a new request before the last
one is finished. If its offset is where the previous range ended, it extends
that range; otherwise it replaces it (the node is asking again from where it
really is).

Chunk (server → node), 14 + n bytes

A node keeps a chunk only if its offset is exactly the next one expected and
its CRC matches. Anything else is dropped; a gap triggers an immediate
re-request.

Offer (server → node)

The frame ends exactly after the signature; a frame with bytes left over is
refused.

Status (node → server)

Command (server → node), 7 bytes

Job 0 means "whatever is running". A command for any other job is ignored,
except status, which is always answered.

The signature

The signature covers exactly these 114 bytes:

"modbee-ota-v1" 0x00 | sha256[32] | size u32 LE | board[32] | version[32]

Board and version are zero padded (so each is at most 31 bytes).
ota_signedMessage() builds it on the node. The node's verifier decides the
scheme; both signatures are 64 bytes:

Put it in the offer as hex (JSON "signature") or raw (binary Offer frame).
Make a key once (openssl genpkey -algorithm ed25519 -out ota-key.pem, or
-algorithm EC -pkeyopt ec_paramgen_curve:P-256 for P-256), then sign each
image. In Python, with the cryptography package:

import hashlib, struct
from cryptography.hazmat.primitives import serialization

def signed_message(image: bytes, board: str, version: str) -> bytes:
    pad = lambda text: text.encode().ljust(32, b"\0")
    return (b"modbee-ota-v1\0" + hashlib.sha256(image).digest()
            + struct.pack("<I", len(image)) + pad(board) + pad(version))

image = open("firmware.bin", "rb").read()
key = serialization.load_pem_private_key(open("ota-key.pem", "rb").read(), None)
signature = key.sign(signed_message(image, "my-board", "1.0.1"))   # Ed25519
public_key = key.public_key().public_bytes(serialization.Encoding.Raw,
                                           serialization.PublicFormat.Raw)

Keep the private key off the devices and out of version control.

MQTT topics

Under a base chosen per node, for example modbee/node-uio-1/ota:

A server subscribes to +/ota/req and +/ota/status (or the equivalent
wildcard for its layout) to serve every node at once.

JSON offer

{"job": 17, "version": "1.4.0", "board": "modbee-node-uio", "size": 1048576,
 "sha256": "<64 hex>", "signature": "<128 hex>", "apply": "auto", "force": false}

signature, apply ("auto" or "manual") and force are optional.
Unknown keys are skipped, so a platform can add its own (notes, url, …).

JSON status

{"state":"downloading","outcome":"none","result":"ok","job":17,
 "received":524288,"size":1048576,"progress":50,"board":"modbee-node-uio",
 "running":"1.3.2","offered":"1.4.0"}

The status is published on every state change, every second or so while
downloading, on every reconnect, and once after boot. After boot it reports
how the last job ended.

Sparkplug B metrics

Two ways to use them. Beside the MQTT topics (OpenPLC's OTA_SPARKPLUG):
the image travels on <base>/data over the same connection, and Sparkplug
carries the status and the controls:

Instead of them (OtaSparkplugLink), for a host that can only speak
Sparkplug - the image rides in metrics:

The host writes one chunk per request it sees. A metric only holds its latest
write, so the node never has more than one chunk in flight on this link.

Security

A signature protects the image: with a verifier set, the node installs only
what the key signed, for its board, at that version. It does not protect the
commands (abort, apply, confirm, rollback), or the status the node
publishes. Use the broker's access control so only the server can write a
node's offer, data and cmd topics, and TLS where the network is not
trusted.

Result codes

0 ok, 1 pending, 2 busy, 3 invalid_argument, 4 not_ready, 5 no_memory, 6 unsupported, 7 io_error, 8 wrong_board, 9 too_large, 10 same_version, 11 downgrade, 12 unsigned, 13 bad_signature, 14 refused, 15 timeout, 16 bad_chunk, 17 hash_mismatch, 18 bad_image, 19 aborted, 20 rolled_back, 21 not_confirmed.

Append only: the numbers are in Status frames and in the OpenPLC
OTA_RESULT datatype.