Firmware Updates / OTA
Firmware updates, sometimes called OTA updates, let a host app offer a newer device firmware release while keeping update orchestration inside the Eixam SDK. The host app presents availability, blockers, confirmation, progress, failure, and recovery messaging. The SDK owns release eligibility, artifact handling, transfer orchestration, progress state, reconnect handling, and installed-version verification where supported.
Expose firmware update UX only when the product and deployment enable it. Do not auto-start firmware updates. The user must explicitly confirm before the app starts an update session.
Technical Flow
- Check update availability for the connected device.
- Inspect the selected release metadata and SDK eligibility blockers.
- Ask the user for explicit confirmation.
- Start the update through the SDK using the release returned by the availability check.
- Observe progress until the SDK reports a terminal state.
- Handle success, cancellation, failure, or recovery-required outcomes.
- Refresh firmware/device state and rely on SDK installed-version verification where supported.
The SDK exposes this flow through:
| Step | Public surface |
|---|---|
| Read current firmware context | getFirmwareInfo({deviceId}) |
| Check availability and blockers | checkFirmwareUpdate({deviceId, policy}) |
| Start a user-confirmed update | startFirmwareUpdate(deviceId:, releaseId:, policy:) |
| Observe progress | watchFirmwareUpdateProgress({deviceId}) |
| Request cancellation | cancelFirmwareUpdate(sessionId) |
See Public API, Model Reference, and Practical Examples.
Platform Support
| Area | Support | Notes |
|---|---|---|
| Shared SDK behavior | Supported | Availability checks, eligibility blockers, sessions, progress states, cancellation request, reconnect state, and installed-version verification are exposed through the shared Dart API. |
| Android | Supported where the host app has the normal device/BLE prerequisites and the connected device/release are compatible. | The SDK uses a native DFU transport under the public SDK API. Host apps should not call native DFU APIs directly. |
| iOS | Supported where the host app has the normal device/BLE prerequisites and the connected device/release are compatible. | iOS BLE/background behavior can be more constrained by platform conditions. Keep the app foregrounded during user-driven updates. |
| Web, desktop, other platforms | Not supported for device firmware transfer. | Availability checks may still fail or report blockers depending on runtime configuration, but native transfer is unavailable. |
Platform behavior can differ during disconnect, reconnect, cancellation, or recovery-required paths. Keep user copy careful and state-based instead of promising exact timing.
Prerequisites And Blockers
Before starting an update, the host app should have:
- An initialized SDK with the expected session/runtime configuration.
- A connected Eixam device selected by the user or current device context.
- A known current firmware version and compatible hardware model where available.
- An update check result with an eligible release.
- Bluetooth available and app/device close enough for a stable transfer.
- Battery and runtime preconditions accepted by the SDK policy and eligibility result.
The SDK can report blockers such as:
- No connected device.
- Unknown firmware version.
- Unsupported hardware or incompatible release.
- Low device battery.
- Unstable BLE connection when detectable.
- Active SOS or PRE-SOS countdown.
- Active or overdue Death Man Protocol.
- Protection runtime using BLE or pending critical work.
- App backgrounded when foreground is required.
- Missing artifact or hash metadata.
Render blockers as user-actionable messages. Do not bypass SDK blockers in host UI.
Release Metadata
FirmwareRelease identifies the update selected by the SDK/backend release check. Host apps may show user-safe fields such as target version and release notes when product copy approves them. Treat artifact hashes, artifact kind, bootloader type, and package details as technical metadata for SDK/debug/support surfaces rather than ordinary end-user copy.
Always start with the releaseId returned by checkFirmwareUpdate(...). Do not construct release identifiers or download package URLs in the host app.
Progress States
Use FirmwareUpdateProgress.state as the source of truth for UI. The public states include:
| State group | User-facing interpretation |
|---|---|
checking, available, notAvailable, blocked | Availability and eligibility. |
downloading, verifying, readyToTransfer | SDK is preparing the update. |
transferring | Firmware is being transferred to the device. Show percentage when available. |
reconnecting, verifyingInstalledVersion | Device/app connection is being restored and the SDK is checking the installed version. |
completed | SDK verified the update result. |
failed, cancelled, recoveryRequired | Terminal states requiring retry, user guidance, or support/recovery flow. |
Do not mark the update as complete from upload percentage alone. Treat completion as successful only when the SDK reports completed after installed-version verification.
Cancellation
Cancellation is a request, not a guarantee that every platform can stop every phase immediately.
- Before transfer starts, cancellation is generally safest because the SDK may still be preparing or downloading.
- During transfer or install, cancellation behavior depends on the native platform, current DFU phase, and device state.
- After the device has entered a critical update phase, the result may become
failedorrecoveryRequiredinstead of a clean cancellation.
Only show a cancel action when your app has a real update session id and can call the SDK cancellation API. If cancellation is requested, keep listening to progress until the SDK reports a terminal state.
Failure And Recovery
A failed update does not automatically mean the device is unusable. It means the SDK could not complete and verify the requested update in that session.
For failed:
- Tell the user the previous firmware may still be running.
- Offer retry only after the SDK and device state are ready.
- Keep the app open and device nearby for the next attempt.
- Avoid promising that retry will always succeed.
For recoveryRequired:
- Show clear support-oriented guidance.
- Ask the user to keep the device nearby, powered, and not in an SOS/DMP flow.
- Direct the user to the deployment-approved support or recovery path.
- Do not promise remote recovery, exact timing, or emergency-service behavior.
Do not hide installed-version mismatch failures. If the SDK reports that the installed version does not match the target, keep the update in a failed state and let the user retry or contact support according to the deployment plan.
Host-App UI Obligations
Host apps should:
- Check availability after SDK/device readiness, and debounce repeated checks.
- Show current version and target version where approved.
- Explain blockers in plain language.
- Require explicit user confirmation before starting.
- Warn the user to keep the app open and the device nearby.
- Warn the user not to start SOS, PRE-SOS, or DMP during the update.
- Show progress step-by-step, including percentage when available.
- Keep listening through reconnect and installed-version verification.
- Show retry or recovery guidance from terminal states.
Host apps should not:
- Auto-start updates.
- Download firmware artifacts outside the SDK-owned flow.
- Call native DFU APIs directly.
- Mark completion from upload percentage, native completion alone, or optimistic UI state.
- Suppress SDK blockers or installed-version mismatch failures.
- Promise hard timing, background completion, BLE stability, or guaranteed device recovery.
Responsibility Split
| Responsibility | Owner |
|---|---|
| Release availability and eligibility | SDK/backend release flow |
| Safety gates and blockers | SDK |
| Firmware artifact download, verification, and transfer orchestration | SDK |
| Native DFU transport | SDK |
| Installed-version verification where supported | SDK |
| User confirmation and update copy | Host app |
| Progress, blockers, failure, and recovery UI | Host app |
| Support/recovery wording | Product/support/deployment agreement |
Keep Partner KB wording conceptual. Method names, models, release metadata fields, platform details, and code examples belong in Flutter SDK documentation.