Set up a device for OTA

For over-the-air updates, a device or gateway's firmware has to understand the Firmcraft IoT Dashboard's update command and report its progress. This page is for the engineer who writes or configures that firmware.

The two paths

Set these in the device's or gateway's settings, under Firmware Update (step 4 of the Add Device wizard, step 3 of the Add Gateway wizard, or later in its edit form):

Setting	Direction	What travels on it
Publish Path	IoT Dashboard → device	The update command. Example: gateway/GW-1/ota
Subscribe Path	Device → IoT Dashboard	Progress reports. Example: gateway/GW-1/progress

Both use the same broker as the device's readings.

The update command

When a deployment reaches the device, the IoT Dashboard publishes this JSON on its Publish Path:

{
  "firmware_version": "1.2.3",
  "firmware_url": "https://dashboard.firmcraft.in/…",
  "checksum": "<SHA-256 of the file>",
  "timestamp": "2026-09-29T10:15:00Z"
}

The device should download the file from firmware_url, check that its SHA-256 matches checksum, install it and restart.

Change the command

If your firmware expects a different format, edit Command JSON in the same Firmware Update section. It's sent exactly as you write it, with these placeholders filled in:

, , , , , ,

Example for firmware that expects nested fields:

{
  "cmd": "ota",
  "fw": { "ver": "{{firmware_version}}", "url": "{{firmware_url}}", "sha256": "{{checksum}}" },
  "job": "{{deployment_id}}"
}

Click Reset to default to go back to the standard command. Leave it empty to use the default.

Progress reports

While updating, the device publishes JSON on its Subscribe Path:

{ "device_id": "GW-1", "deployment_id": "…", "status": "downloading", "progress": 40 }

Field	Notes
device_id	The device's ID. gateway_id also works.
deployment_id	Optional. Include it if the command carried one.
status	Any word. These are understood: pending, downloading, installing, rebooting, verifying, completed, failed, stopped, and common variants such as flashing or success.
progress	0–100. percent or percentage also work.
error_message	Optional, when the update fails.

Confirm the new version

After restarting, the device must report its new firmware version in its normal readings. That's what marks the update completed in the deployment. Reporting "status": "completed" alone isn't enough.