Skip to main content
Model-based catalogue integration is available in production. The platform resolves the device model; integrations do not supply a hardware revision. Download metadata adds version, which must be passed unchanged to the App SDK for post-reboot verification. Internal and external projects use the same APIs with their own authorization.
Bota distributes firmware updates through Bota-managed over-the-air (OTA) releases. Firmware images are built and released by Bota, including customer-specific builds. Customers cannot upload arbitrary firmware images or bring their own firmware through the public product flow. If your deployment requires a custom firmware build, contact Bota support and Bota will manage the release.

Platform Release Selection

OTA publication makes a firmware version available for review. Each platform project chooses when to release it to its users and devices. Select the intended project, then in Firmware Releases, choose an Available version and select Release. This requires firmware-management permission and replaces the released version for that model. Select Bota Pin and Bota Note separately; they may use the same version/artifact. Projects in the same organization can choose different versions. Later OTA publications wait for another explicit selection. The public API and app update choices expose only the selected, still-available service version. Bluetooth grants and device assignments enforce the same gate. Automatic network updates also require auto-update enabled and the OTA service selected; choosing a version does not override downgrade restrictions. Stop release removes the selection for this project and prevents new authorizations/deliveries. Other projects are unaffected. Previously issued download URLs, grants and updates already in progress may finish. If no version is selected, no service firmware is offered to your users or devices.

OTA Updates

For devices with WiFi or 4G connectivity, Bota can assign a firmware release to the device. The device receives the update manifest on its next heartbeat, downloads the firmware directly, validates it, applies the update, and reports the new firmware version on a later heartbeat.

Assignment Status

What the Device Does

Once the device receives an OTA manifest:
  1. Downloads the firmware from a Bota-provided URL
  2. Validates the downloaded image
  3. Writes the update to flash storage
  4. Reboots and applies the update
  5. Reports the new firmware version on the next heartbeat
The device continues operating normally during download. A reboot is required to apply the firmware, so the device will briefly go offline.

Monitoring

The device reports its firmware version in every heartbeat. When it matches the assigned release version, the assignment is automatically marked as applied.
You can check assignment status in the portal under Devices -> device -> OTA tab.

Driving Updates from the API

Everything above is also available over the API, so a fleet can be updated from your own backend rather than device by device in the portal.
Step 3 answers with the device’s most recent assignment whatever became of it, so a poll can distinguish still installing from installed from failed without keeping state of its own. A device that was never assigned firmware returns { "data": null }. If you assigned the wrong release, DELETE /v1/devices/{id}/ota calls it off — but only until the device has the update in hand. See Cancel Device OTA Assignment.

Firmware API reference

Firmware endpoints, with request and response shapes.

Bluetooth Updates through the App SDK

Your backend can request a Bluetooth OTA grant using POST /v1/devices/{id}/ota-grant with firmware_release_id. Use a secret API key or a restricted key with devices:write, kept on your backend. Authorize the signed-in user’s access to the device before making this request. List compatible releases with device_id, obtain the same release’s download URL with type=ufw, and pass the returned opaque grant and download metadata to the Bota App SDK’s Bluetooth update operation. The grant is bound to the enrolled device key, target version, and image digest. Request a fresh grant after expiry. A grant authorizes transfer; it does not create a WiFi/cellular assignment or prove installation. Keep showing the device’s current version separately from the available version and verify the reported version after reboot/reconnection. Without Bluetooth, use the assignment endpoint for delivery over WiFi/cellular.

Firmware Control

Bota firmware is closed source and released by Bota. Customer-uploaded firmware is not supported in production. This protects fleet integrity and avoids unsupported third-party firmware running on Bota-managed devices. A third-party firmware image cannot be used to bypass Bota’s backend authorization, tenant isolation, or API access controls. If a device is lost, stolen, or suspected to be compromised, revoke or reset the device from the portal and contact Bota support.

Key Constraints

  • Bota-managed releases only — firmware builds and releases are managed by Bota.
  • No customer firmware upload — public product flows do not support arbitrary firmware upload.
  • Two delivery paths — WiFi/cellular uses an assignment; Bluetooth uses a backend-issued grant and the App SDK.
  • One active assignment — a device can only have one pending OTA assignment at a time.
  • No active recording — firmware updates are rejected while recording is active.
  • Heartbeat delay — OTA is delivered on the next heartbeat. Allow up to 2 minutes from assignment to delivery.
  • Bluetooth pauses delivery — a device connected to the mobile app over Bluetooth stops its own heartbeat, so it will not receive an assignment until that connection closes.