Update ANX OS Firmware Over the Air (OTA)

OTA (over-the-air) updates let your ANX module download and apply firmware updates over Wi-Fi without ever connecting a USB cable — making them essential for devices that are already deployed in the field, installed in enclosures, or simply inconvenient to reach. Once OTA is configured, your devices stay current with security patches and new firmware features automatically, or on demand from the CLI or from within your application code.

Ensure your device has a stable power source before starting an OTA update. A power loss mid-update can corrupt the incoming firmware partition. If your device runs on battery, charge it above 50% or connect a power supply before triggering an update in production.

How OTA Works

The ANX OS OTA engine follows a safe, multi-stage process designed to protect against bad updates:

Poll — the device contacts the ANX update server and checks whether a newer firmware version is available on the configured release channel.
Download — if an update is found, the engine downloads a delta patch (not a full image) to minimize bandwidth and flash wear.
Verify — the downloaded patch is verified against a cryptographic signature from ANX Labs. Tampered or corrupted patches are rejected before any write occurs.
Write — the patch is applied to the inactive firmware partition. The currently running firmware is never touched during this step.
Health check and reboot — the device reboots into the new firmware. ANX OS monitors the new firmware for 60 seconds. If it passes the health check, the new partition becomes the active boot target. If it crashes or hangs, ANX OS automatically reverts to the previous partition.

This dual-partition scheme means a failed update never leaves your device in an unbootable state.

Prerequisites

Before enabling OTA updates, confirm the following:

Wi-Fi configured — the wifi.ssid, wifi.password, and wifi.mode fields must be set in config.json. OTA requires an active internet connection. See the Configuration guide if you have not set up Wi-Fi yet.
Firmware 1.0.0 or later — the OTA engine shipped in ANX OS 1.0.0. Devices running older firmware must be updated once via USB before they can receive OTA updates. See Flashing.

Enabling Automatic OTA

Add or update the ota section in your device’s config.json to turn on background update checks:

config.json

{
  "ota": {
    "channel": "stable",
    "auto_check": true,
    "check_interval_hours": 24
  }
}

Push the updated config to your device, then reboot to apply it:

anx config write config.json
anx device reboot

With auto_check enabled, the device silently polls the ANX update server every 24 hours and applies any available update during its next idle window.

Triggering a Manual OTA Check

To check for an available update immediately without waiting for the next scheduled poll, run:

anx ota check

To check for an update and apply it immediately if one is available, run:

anx ota update

The CLI streams progress to your terminal as the download, verification, and write steps complete, then prompts you before the device reboots.

Triggering OTA from Device Code

You can initiate an OTA check directly from your application using the ANX SDK. This is useful when you want to gate updates on application-level conditions — for example, only checking for updates when the device is idle or after a successful sensor reading cycle.

ota_trigger.c

#include "anx/ota.h"

void check_for_update(void) {
    anx_ota_result_t result = anx_ota_check();
    if (result == ANX_OTA_UPDATE_AVAILABLE) {
        anx_ota_apply(); // downloads, verifies, writes, and reboots
    }
}

The anx_ota_check() call is non-blocking at the network level but does require an active Wi-Fi connection. anx_ota_apply() is a blocking call — it takes over the main execution context for the duration of the download and write, then reboots the device automatically.

Result Codes
Full Example with Error Handling

Code	Value	Meaning
`ANX_OTA_UP_TO_DATE`	`0`	The device is already running the latest firmware on the configured channel.
`ANX_OTA_UPDATE_AVAILABLE`	`1`	A newer firmware version is available. Call `anx_ota_apply()` to install it.
`ANX_OTA_NO_WIFI`	`2`	The Wi-Fi radio is not connected. Ensure `wifi.mode` is `"station"` and the network is reachable.
`ANX_OTA_SERVER_ERROR`	`3`	The ANX update server returned an unexpected response. Retry after a delay.
`ANX_OTA_VERIFY_FAILED`	`4`	The downloaded patch failed signature verification. Do not apply it.

ota_with_error_handling.c

#include "anx/ota.h"
#include "anx/log.h"

void try_ota_update(void) {
    ANX_LOG_INFO("Checking for firmware update...");

    anx_ota_result_t result = anx_ota_check();

    switch (result) {
        case ANX_OTA_UP_TO_DATE:
            ANX_LOG_INFO("Firmware is up to date.");
            break;

        case ANX_OTA_UPDATE_AVAILABLE:
            ANX_LOG_INFO("Update available. Applying...");
            anx_ota_apply(); // device will reboot; code below does not run
            break;

        case ANX_OTA_NO_WIFI:
            ANX_LOG_WARN("OTA skipped: Wi-Fi not connected.");
            break;

        case ANX_OTA_VERIFY_FAILED:
            ANX_LOG_ERROR("OTA patch verification failed. Aborting.");
            break;

        default:
            ANX_LOG_ERROR("OTA check failed with code: %d", result);
            break;
    }
}

Rollback

If the newly installed firmware crashes or stops responding within 60 seconds of boot, ANX OS detects the failed health check and automatically reverts to the previous firmware partition. The device reboots a second time into the known-good version without any manual intervention. You can also trigger a manual rollback at any time from the CLI:

anx ota rollback

This immediately reboots the device into the previously active firmware partition, regardless of whether the current firmware is healthy. Use this when an update introduces a regression that does not cause a crash — for example, a performance issue or unexpected behavior change.

Monitoring OTA Status

Check the current OTA state, partition versions, and last check time with:

anx ota status

Sample output:

OTA Status
──────────────────────────────────────────────
Current firmware:    1.2.0  (stable)
Previous firmware:   1.1.5  (stable)
Channel:             stable
Auto-check:          enabled
Check interval:      24 hours
Last check:          2h ago
Next check:          in 22h
Pending update:      none

Always test OTA updates on a bench device running the same firmware version as your fleet before enabling auto_check in production. This lets you catch any application-level regressions before they propagate to all deployed units.

Get Started

Dev Module

OS Firmware

Example Applications

Troubleshooting

Update ANX OS Firmware Over the Air (OTA)

How OTA Works

Prerequisites

Enabling Automatic OTA

Triggering a Manual OTA Check

Triggering OTA from Device Code

Rollback

Monitoring OTA Status

​How OTA Works

​Prerequisites

​Enabling Automatic OTA

​Triggering a Manual OTA Check

​Triggering OTA from Device Code

​Rollback

​Monitoring OTA Status

How OTA Works

Prerequisites

Enabling Automatic OTA

Triggering a Manual OTA Check

Triggering OTA from Device Code

Rollback

Monitoring OTA Status