OTA updates: offers, downloads, status and rollback
The OTA contract for Paqett IP devices: the retained MQTT offer, the signed HTTPS image URL, the device's rules, ota_status reports, jobs and releases.
The platform offers a firmware image to one device over its MQTT session. The device downloads it over HTTPS, checks it, boots it on trial and reports how it went. The contract is the same for every chip: an ESP32 writes the image to its other app slot and uses the bootloader's rollback; a cellular modem would use its own download and DFU libraries. For the ESP32 code, see ESP32 OTA updates over MQTT.
Releases
A release is a firmware image for one model (the device type a device enrolled with) and one version (the string its hello reports as firmware). One image per model and version, never replaced: a fixed build gets a new version. The platform computes the image's SHA-256 and size when it is uploaded, and those are what a device checks. Images are at most 4 MiB.
The offer
The platform publishes the offer on devices/<device id>/ota, retained, QoS 1, so a device that is asleep or offline gets it when it next connects:
{
"job_id": "86b77f8c-...",
"version": "0.2.1",
"url": "https://api.paqett.com/v1/devices/firmware/75f8ee81-...?exp=1795000000&sig=...",
"sha256": "f2066198...",
"size": 1203456,
"model": "esp32c6-devkit"
} An empty retained payload clears the offer; the platform sends one when the job finishes or is cancelled. When a device whose job is still unfinished says hello, the platform re-sends the offer with a fresh URL: the old one may have expired while the device was away.
The download
url is a signed HTTPS link on api.paqett.com, valid for one hour after the platform made it. It needs no API key, so a plain HTTP client can fetch it.
| Behaviour | Detail |
|---|---|
| Methods | GET and HEAD |
| Body | The image, application/octet-stream. ETag is its SHA-256. |
| Ranges | One Range: bytes=a-b (or a-, -n) is answered 206 with Content-Range, for resuming. A start past the end is 416. |
| Errors | 403 for a bad or expired signature, 404 for an unknown release. |
| TLS | A public certificate, so a device verifies it with its usual public roots (the ESP-IDF certificate bundle, a modem's root store). |
The URL is a capability for one image, not a secret: an image can be read out of any device's flash anyway. What protects the device is the sha256 in the offer, which arrives over its authenticated MQTT session. It boots nothing whose digest does not match.
What the device does
- Another model.
modelis not its own: it installs nothing and reportsfailedwitherror: "model_mismatch". - Already running it.
versionis what it runs: it reportssucceeded. - Already done.
job_idis one it has finished: it reports that outcome again. A retained offer arrives on every connect until the platform clears it, so the device keeps its last job id and outcome across reboots. - Download. Otherwise it downloads
urlinto its spare slot, reportingdownloadingwithprogress(0 to 100, at most every 10 %). A download that breaks is retried a few times beforefailed(download_failed: ...). - Verify. It reports
verifying.sizeandsha256must match exactly, or it reportsfailed(size_mismatch,sha256_mismatch) and keeps the image it runs. - Apply. It marks the new image bootable, reports
applied, and reboots into it. - Trial. The new image marks itself good only once its MQTT session is up and its hello is sent. If it crashes or resets before that, or does not get online within a timeout (10 minutes in the Paqett SDK), the device boots the previous image again.
- Rolled back. Back on the previous image after
applied, it reportsfailedwitherror: "rolled_back".
ota_status
The device reports on devices/<device id>/ota_status, QoS 1, not retained:
{"job_id":"86b77f8c-...","state":"downloading","progress":40} {"job_id":"86b77f8c-...","state":"failed","error":"sha256_mismatch"} state is one of downloading, verifying, applied, succeeded, failed. error is at most 200 characters.
Jobs
A job is one update of one device. A device has at most one unfinished job.
| State | Set by |
|---|---|
offered | The platform, when it publishes the offer |
downloading, verifying, applied | The device's reports. A report never moves a job backwards. |
succeeded | After applied, the device's next hello reports the release's version |
failed | The device reports failed, or after applied its hello reports another version (it rolled back) |
cancelled | Cancelled before applied. An applied image is already the boot image, so that job is judged by the next hello. |
The platform judges an update by what the device says when it comes back, not only by what it reported on the way: the hello after a reboot is the proof.
Admin API
Releases and jobs are managed with an admin API key: projects:read to read, devices:write to change anything. Releases belong to a model, not a project: a model's image is the same for every fleet.
| Route | Scope | Does |
|---|---|---|
GET /v1/admin/firmware?model=<model> | projects:read | Releases, newest first |
POST /v1/admin/firmware?model=<model>&version=<version> | devices:write | Upload a release. The body is the image, application/octet-stream. 201; 409 if that model and version exist; 413 over 4 MiB. |
GET /v1/admin/projects/<project>/devices/<device id>/ota | projects:read | The device's jobs, newest first |
POST /v1/admin/projects/<project>/devices/<device id>/ota | devices:write | Start a job: {"releaseId": "<release id>"}. 409 when the release is for another model, the device is not an IP device, or it has an unfinished job. |
POST /v1/admin/projects/<project>/devices/<device id>/ota/<job id>/cancel | devices:write | Cancel a job. 409 once it is finished or applied. |
# Upload a build as release 0.2.1 of model esp32c6-devkit
curl -sS -X POST -H "authorization: Bearer $PAQETT_ADMIN_KEY" -H 'content-type: application/octet-stream' --data-binary @.pio/build/esp32c6/firmware.bin 'https://api.paqett.com/v1/admin/firmware?model=esp32c6-devkit&version=0.2.1'
# Offer it to one device
curl -sS -X POST -H "authorization: Bearer $PAQETT_ADMIN_KEY" -H 'content-type: application/json' -d '{"releaseId":"<release id>"}' https://api.paqett.com/v1/admin/projects/<project>/devices/<device id>/ota