Firmware updates and OTA

Devices ship pre-flashed and update themselves over the air against whichever server they are provisioned to. You host the image, you decide which device is offered what, and the device verifies the checksum before it flashes and reports back honestly including rollbacks — so you can tell what a customer's fleet is actually running rather than what you hoped you shipped.

Checking for an update

curl -s https://api.yourcompany.com/api/devices/AA:BB:CC:DD:EE:FF/ota/check

{
  "update_available": true,
  "update_id": 17,
  "version": "2.2.0",
  "release_type": "STABLE",
  "download_url": "https://.../firmware-2.2.0.bin",
  "checksum_sha256": "9f2c...",
  "release_notes": "..."
}

Reporting progress

BASE=https://api.yourcompany.com/api/devices/AA:BB:CC:DD:EE:FF/ota/17/progress

curl -X PATCH $BASE -H "Content-Type: application/json" \
  -d '{"status":"DOWNLOADING","progress_percent":45}'

curl -X PATCH $BASE -H "Content-Type: application/json" \
  -d '{"status":"SUCCESS"}'

curl -X PATCH $BASE -H "Content-Type: application/json" \
  -d '{"status":"FAILED","error_message":"checksum mismatch"}'

Statuses are DOWNLOADING, INSTALLING, SUCCESS, FAILED and ROLLED_BACK. FAILED and ROLLED_BACK automatically open a HIGH severity OTA_FAIL incident and mark the device DEGRADED — you do not need to file that yourself.

What the device does with the image

1. 1Downloads to the inactive partition. The running image is never overwritten in place.
2. 2Verifies checksum_sha256 over the downloaded bytes before it flashes anything.
3. 3Marks the new partition bootable and restarts.
4. 4If the new image fails to come up healthy, the bootloader returns to the previous partition and the device reports ROLLED_BACK rather than pretending the update worked.

Staging a rollout

Releases carry a release_type of STABLE, BETA or CRITICAL_PATCH, and an optional min_hardware_version. Stage rather than ship at once:

1. 1Promote the build as BETA and target a handful of units.
2. 2Watch OTA_FAIL incidents and post-update health_status on those units for a full operating day.
3. 3Promote to STABLE. Record firmware_version from every heartbeat and version distribution across a customer's fleet becomes a query rather than a spreadsheet.