Skip to content
Emberwire OTA firmware delivery

On-device software

The part that has to fit in 168 KB and never brick anything.

The agent is a state machine, a hash function, a signature check and a resumable transfer. It does not contain a scripting runtime, a telemetry pipeline or a remote shell, because each of those is a way for a firmware updater to become the reason a device needs updating.

168 KBsmallest build, code and rodata
24 KBstatic RAM, no heap required
2.9.0current release, 16 September 2026
1.6 MBidle traffic per device per month

Footprint by build

Measured with -Os, link-time optimisation on, for the 2.9.0 release. Your figures will differ by a few kilobytes depending on toolchain and how much of the crypto you supply from the platform.

Agent 2.9.0 — resource budget per build variant
Build Target Code + rodata Static RAM Heap TLS Delta apply
ew-agent-min Bare metal, Cortex-M 168 KB24 KBnone supplied by hostyes, 4 KB scratch
ew-agent-rtos Zephyr, FreeRTOS, NuttX 246 KB38 KB32 KB host or bundled mbedTLSyes, 8 KB scratch
ew-agent-posix Linux, static musl 1.1 MB2.4 MB RSSdynamic bundledyes
ew-agent-posix-dyn Linux, shared libc 318 KB1.9 MB RSSdynamic system libraryyes

The I/O buffer is yours

The agent never allocates. You hand it a buffer — 4 KB minimum, 16 KB recommended, 64 KB above which there is nothing to gain — and it streams through it. Larger buffers mean fewer flash writes per block, not faster transfers.

Crypto can come from the platform

If your part has a hardware SHA-256 engine or your stack already carries an Ed25519 implementation, register them through ew_crypto_ops_t and the bundled versions are not linked in. That is worth about 31 KB on a Cortex-M target.

No dynamic code

Nothing the agent downloads is ever executed by the agent. It writes bytes to a slot and asks the bootloader to consider them. There is no interpreter, no plugin mechanism and no way for a manifest to change the agent's behaviour beyond the fields documented in the reference.

Storage layouts

This is the decision that determines whether your product can be updated safely. Make it before you finalise the flash map, not after.

Layout Storage required How an update lands Power-loss behaviour Verdict
A/B slots in internal flash 2 × image + 8 KB Written into the inactive slot, digest checked, slot pointer flipped, device reboots. Active slot is never touched. Any interruption means the device boots what it had. recommended
Single slot + external staging 1 × image internal, 1 × image on SPI NOR or eMMC + 8 KB Staged externally and verified, then copied in by the bootloader on the next boot. An interrupted copy is retried from the verified staging copy. Longer exposure window than A/B, but bounded. supported
Single slot + compressed staging 1 × image + ~0.6 × image As above, with the staged copy compressed. Adds decompression time to the boot that applies it. Same as external staging. Requires the bootloader to carry the decompressor. case by case
Single slot, write in place 1 × image Not offered. A power cut during the write leaves no bootable image and no path back. not supported

If your flash map has no room for a second copy

Add external flash, or reduce the image. We will not ship a configuration that writes over the only bootable copy of your firmware on a device you cannot physically reach. The cost of the smallest serial NOR part that fits your image is lower than the cost of one field visit.

Flash wear

One erase-write cycle of the inactive slot per update. Twelve releases a year for a ten-year service life is 120 cycles — against a typical NOR endurance of 100,000. Delta application writes only the blocks that changed, which for a meter image is around 6 % of the slot.

Metadata region

The agent keeps 8 KB of persistent state: active slot, trial flag, current build digest, last confirmed build, resume offset and the candidate node list. Written with an A/B journal of its own, so a power cut during a metadata write cannot produce an unreadable record.

The update state machine

confirmed — the new build becomes the active slot no update offered idle 15 min timer check-in 590 bytes fetch resumable verify chain + digest stage inactive slot swap flip + reboot confirm 20 min window link lost → resume at byte offset digest mismatch or signature does not chain no ew_confirm() within the watchdog window discard nothing written roll back previous slot, next boot the device keeps working the whole time; the platform records a failed confirm
Every arrow that leaves the happy path returns to idle with the device running a build that has already booted successfully at least once. There is no state in which the device has no bootable image.

Integration

Four calls. The agent does not own main(), does not create threads on bare metal, and does not block.

bare-metal integration — ew-agent-min
#include "emberwire.h"

static ew_ctx_t ctx;
static uint8_t  io_buf[16 * 1024];

void app_main(void)
{
    ew_config_t cfg = {
        .product_line   = "pl_meter_g4",
        .device_id      = board_serial(),
        .trust_anchor   = ew_root_pubkey,   /* 32 B, in ROM */
        .slot_a         = { .base = 0x08020000,
                            .size = 0x00180000 },
        .slot_b         = { .base = 0x081A0000,
                            .size = 0x00180000 },
        .io_buffer      = io_buf,
        .io_buffer_len  = sizeof io_buf,
        .check_interval = 900,              /* seconds   */
        .jitter         = 45,               /* seconds   */
    };

    ew_init(&ctx, &cfg);

    if (ew_boot_state(&ctx) == EW_BOOT_TRIAL) {
        if (self_test_ok())
            ew_confirm(&ctx);   /* keep the new build   */
        else
            ew_reject(&ctx);    /* revert on next boot  */
    }

    for (;;) {
        ew_poll(&ctx);          /* drives the machine   */
        app_work();
    }
}
/etc/emberwire/agent.conf — ew-agent-posix
[agent]
product_line   = "pl_router_ax3"
state_dir      = "/var/lib/emberwire"
check_interval = "5m"
jitter         = "45s"

[network]
endpoint          = "https://api.{{DOMAIN}}/v1"
max_bandwidth     = "2MiB/s"
resume            = true
candidate_refresh = "6h"
keepalive         = "15m"

[storage]
layout  = "ab"
slot_a  = "/dev/mmcblk0p2"
slot_b  = "/dev/mmcblk0p3"
scratch = "/var/cache/emberwire"

[confirm]
watchdog = "20m"
command  = "/usr/local/bin/ew-healthcheck"

[log]
level  = "info"
target = "syslog"

The confirm decision is yours

Emberwire never decides that your device is healthy. It gives you a window and a callback. What counts as healthy — radio associated, sensor reading plausible, card reader answering — is your code's judgement, and it is the single most important line you will write.

Network behaviour

What an idle device costs

A check-in is a 380-byte request and a 210-byte response when there is nothing to do. At the default 15-minute interval that is 2,880 exchanges and about 1.6 MB a month. At a 5-minute interval, roughly 5.1 MB.

For metered cellular fleets, set the interval to hours and accept that a release takes longer to propagate. The agent also honours a server-side hint that tells it to back off during a wave it is not part of.

Why the connection stays open

Where the network allows it, the agent keeps one session alive rather than re-establishing it every interval. On a congested mobile link the handshake can cost more than the check-in payload itself, and failed handshakes are the single largest source of missed check-ins in the fleets we see.

Practically, this means a device holds a long-lived, almost entirely idle connection for hours or days at a time, and then transfers between 812 KB and 1.4 GB in a burst when its cohort is reached.

Jitter and backoff

Check-ins are jittered by default so that a fleet powered on by the same grid event does not arrive as a single spike. On failure the agent backs off 30 s → 1 m → 2 m → 4 m … capped at four times the check-in interval, with jitter at every step.

Bandwidth limit

A per-device ceiling keeps the updater from starving the product. A router downloading its own firmware at full line rate is a support ticket; 2 MiB/s is the default for the Linux build and is unset on constrained targets, where the link is the limit anyway.

Supported targets

Platform Minimum viable target Notes
Bare metal ARM Cortex-M M0+ · 48 MHz · 256 KB flash · 64 KB RAM Requires external staging unless the flash map holds two image slots.
Zephyr 3.x LTS Uses the MCUboot slot layout and swap semantics directly; no second bootloader.
FreeRTOS v10.4 or later One task, configurable stack, 32 KB heap.
NuttX 12.x Community port, maintained by us since agent 2.7.0.
Linux kernel 4.4+ · musl or glibc A/B partitions, dual rootfs or a dedicated update partition. systemd unit provided.
RISC-V (RV32IMC) bare metal or Zephyr Supported since agent 2.8.0. Crypto falls back to software unless you register an engine.