OTA Firmware Workflow
Upload, publish, create a campaign, and monitor updates
This guide covers the complete over-the-air firmware update workflow — from uploading a binary to monitoring deployment across your device fleet.
Prerequisites
- ADMIN or ENGINEER role
- A compiled firmware binary file
- Target devices registered and online
- Devices that support OTA updates via MQTT commands
Steps
Prepare Your Firmware
Before uploading, make sure your firmware:
- Has been tested locally on a physical device
- Has a clear version identifier (e.g.,
1.2.0,2.0.0-rc1) - Is a single binary file (
.bin,.hex, or.uf2)
Document what changed in this version — you'll add release notes during upload.
Upload Firmware
Navigate to OTA Updates → Firmware and click Upload Firmware.
- Version: Semantic version string (e.g.,
1.2.0) - File: Select your firmware binary
- Release Notes: Describe changes in this version
- Device Profile: Select which device profile this firmware targets
The firmware is created in DRAFT status. It is not yet available for deployment.
Review and Publish
Open the firmware detail page to review:
- File size and checksum
- Target device profile
- Release notes
When ready, click Publish. The firmware status changes to PUBLISHED and becomes available for campaigns.
Publishing is irreversible. Once published, the firmware can be used in campaigns. Make sure you've tested thoroughly before publishing.
Create an OTA Campaign
Navigate to OTA Updates → Campaigns and click Create Campaign.
- Name: e.g., "v1.2.0 Rollout — Factory Sensors"
- Firmware: Select the published firmware version
- Target Devices: Choose how to select devices:
- By Device Profile: All devices using a specific profile
- Specific Devices: Hand-pick individual devices
- Strategy:
- All at Once: Send the update to all targets simultaneously
- Batched: Roll out in batches (e.g., 10 devices at a time) to limit risk
Start the Campaign
Review the campaign summary (target device count, firmware version, strategy) and click Start.
The platform begins sending firmware update commands to target devices via MQTT. Each device:
- Receives the update command on its
/cmdtopic - Downloads the firmware binary
- Installs the update
- Reports success or failure back to the platform
Monitor Progress
The campaign detail page shows real-time progress:
| Status | Meaning |
|---|---|
| PENDING | Device hasn't received the command yet |
| DOWNLOADING | Device is downloading the firmware |
| INSTALLING | Device is installing the update |
| COMPLETED | Update successful |
| FAILED | Update failed (see error details) |
Track the overall progress bar and per-device status. For batched campaigns, you can see which batch is currently active.
Handle Failures
If some devices fail to update:
- Check the error details on the campaign page
- Common issues: device offline, insufficient storage, network timeout
- Fix the underlying issue (e.g., bring device online)
- Use Retry Failed to re-send the update to failed devices only
You don't need to create a new campaign for retries.
Tips
- Start with a small batch: For the first rollout of new firmware, use batched strategy with a small batch size (5–10 devices) to catch issues early
- Keep previous firmware: Don't delete old firmware versions — you may need to roll back
- Test on a single device first: Before creating a campaign, manually send the update to one device and verify it works
- Monitor device reconnection: After a firmware update, devices typically reboot and reconnect to the MQTT broker