Overview

The Xyte platform delivers Firmware files to Devices securely. The manufacturer uploads Firmware files under a Device Model — either uploaded to Xyte or hosted by you and added as a link — and Devices obtain them through the Device API.

An upgrade can start in two ways:

• Customer-scheduled — the End Customer (or you, on their behalf) schedules an upgrade Command and selects the file. This gives you server-side orchestration: Command status transitions and an audit trail per Device.
• Device-initiated — the Device sees a newer Firmware version in its Telemetry response and updates itself, with no user involvement. This is the pattern for unattended or automatic updates.

Both can be enabled on the same Device Model: automatic by default, with a manual override available.

Customer-scheduled upgrade

The recommended pattern is to define a Custom Command on the Device Model that requires a File parameter with filetype set to firmware (or a similar tag). The manufacturer's uploaded Firmware files are then selectable when scheduling the upgrade Command for any End Customer.

1. The End Customer schedules the firmware upgrade Command and selects one of the manufacturer's uploaded Firmware files (or uploads a custom file).
2. On the next Send Telemetry API call, the response sets the Command pending flag to true.
3. The Device calls Get Command API to retrieve the Command details, including the link to the Firmware file.
4. The Device calls Update Command API with status in_progress.
5. The Device downloads the file and performs the firmware upgrade locally.
6. The Device calls Update Device API to report the new firmware version.
7. The Device calls Update Command API with the final status.

📘

Firmware upgrades often reboot the Device. Persist the fact that an upgrade is in progress before rebooting, so the Device can finalize the reporting (Command completion, new firmware version, and any other side effects) once it comes back online.

Device-initiated upgrade

Every Send Telemetry API response tells the Device what Firmware is available to it:

• latest_fw_version — the version string of the newest Firmware file offered to this Device.
• latest_fw_file_id — that file's UUID.

No Command, no scheduling and no user action are involved. The upgrade flow is:

1. On each Telemetry cycle, compare latest_fw_version with the version the Device is running. Compare the version, not the file id — replacing a file should not trigger a reinstall.
2. If it is newer, and the Device's own update policy allows installing now, call Get File API with latest_fw_file_id to obtain the file's url, version, checksum and signature.
3. Download the file from url and verify it before flashing. The checksum and signature you provide when adding the file are carried by the platform for the Device to check — the verification itself happens on the Device, against a key in its own trust chain. Pair this with rollback protection.
4. Persist the fact that an upgrade is in progress, then install and reboot.
5. Report the new version with Update Device API, and log the upgrade with Add Event API so it appears in the Device's history.

Base the decision on the Telemetry response — it is the authoritative statement of what a given Device should be offered.

📘

Devices communicating over MQTT do not have to wait for the next Telemetry cycle: the v1/device/{DEVICE_ID}/firmware topic pushes a notification when a newer Firmware file becomes available. See Subscribe Topics.

Which Firmware a Device is offered

A Firmware file is only advertised to Devices when all of the following hold:

• its File Type is firmware;
• its Version is a valid semantic version — a file with a non-semver version string is silently never advertised;
• it is published. A file added with Available for lab accounts only enabled is offered to lab Devices only, which is how you validate a release before it reaches customers.

When more than one file qualifies, the highest version wins.

Publishing applies to every Device of that Device Model — there is no per-Device pinning and no percentage rollout. If you want a phased deployment, put the pacing in the Device: for example a randomized delay before applying an update, or a version gate based on conditions only the Device knows.

Upgrade side effects

A firmware upgrade can change how data is stored or reported on the Device. Two cases need explicit handling.

Configuration shape changes

If the upgrade changes the shape of the Configuration object, the upgrade routine must translate the previous Configuration to the new shape and call Set Config API to push the migrated value to the server.

Telemetry keys change

If the upgrade adds or removes Telemetry keys (especially when keys are retired), send a full Send Telemetry API call with the override flag set to true. This clears the deprecated keys from the Device's state on the server.