Firmware Updates

How It Works

A firmware groups the versions of the software that runs on a device model. A firmware release distributes one version to a device or to a device group: the platform sends every target device a firmwareRelease command with the address of the file, and the devices report the outcome by acknowledging the command.

The platform does not host firmware files: each version points to a file at a URL that the devices can download from.

1. Create the Firmware

{
  "name": "ACME Energy Meter 500 firmware",
  "description": "Firmware of the ACME Energy Meter 500"
}

Link the firmware to the device type of the model with the device type’s firmwareId field.

2. Add a Version

{
  "versionNumber": 3,
  "fileUrl": "https://downloads.example.com/acme-em500/firmware-3.bin",
  "fileName": "firmware-3.bin",
  "fileSize": 524288
}

The response is the firmware, with the new version in versions. To remove a version:

Managing firmware and versions requires the apio.core.firmwares.write permission.

3. Release It

To release a version to a single device:

{
  "versionNumber": 3,
  "deviceId": "my-device-uuid"
}

The response is the release:

{
  "status": true,
  "data": {
    "uuid": "5f1c2a9e-7a51-4d8f-9c55-3c2a1f0e8b21",
    "projectId": "my-project-id",
    "firmwareId": "my-firmware-uuid",
    "firmwareVersion": 3,
    "targetType": "devices",
    "deviceIds": ["my-device-uuid"],
    "deviceGroupIds": [],
    "commandIds": ["810b7efb-f648-47eb-b03b-8edf290e0a27"]
  }
}

Each target device receives a firmwareRelease command on its downlink topic:

{
  "uuid": "810b7efb-f648-47eb-b03b-8edf290e0a27",
  "name": "firmwareRelease",
  "projectId": "my-project-id",
  "deviceId": "my-device-uuid",
  "status": "pending",
  "parameters": {
    "firmwareId": "my-firmware-uuid",
    "versionNumber": 3,
    "fileUrl": "https://downloads.example.com/acme-em500/firmware-3.bin",
    "timestamp": "2026-10-01T10:00:00.000Z"
  }
}

Releasing requires the apio.core.firmwares.releases.write permission.

Releasing to a group

To update many devices at once, add them to a device group and release to the group:

{
  "versionNumber": 3,
  "deviceGroupId": "my-device-group-uuid"
}

The platform sends a command to every device in the group, and records the list of devices in the release’s deviceIds. Devices added to the group later are not part of the release. A release to an empty group fails with 400 Bad Request.

4. Update the Device

On receiving a firmwareRelease command, a device should:

1. Acknowledge the command with received
2. Download the file from parameters.fileUrl and install it
3. Acknowledge the command with completed, or with failed and the reason of the failure:

{
  "uuid": "810b7efb-f648-47eb-b03b-8edf290e0a27",
  "status": "failed",
  "reason": "checksum mismatch"
}

5. Track the Release

List the releases of a firmware to follow their progress:

Each release includes its commands, so you can see the status of every target device at a glance: pending for devices that haven’t answered yet, then received, completed or failed. Listing releases requires the apio.core.firmwares.releases.read permission.