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.
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.
| Build | Target | Code + rodata | Static RAM | Heap | TLS | Delta apply |
|---|---|---|---|---|---|---|
| ew-agent-min | Bare metal, Cortex-M | 168 KB | 24 KB | none | supplied by host | yes, 4 KB scratch |
| ew-agent-rtos | Zephyr, FreeRTOS, NuttX | 246 KB | 38 KB | 32 KB | host or bundled mbedTLS | yes, 8 KB scratch |
| ew-agent-posix | Linux, static musl | 1.1 MB | 2.4 MB RSS | dynamic | bundled | yes |
| ew-agent-posix-dyn | Linux, shared libc | 318 KB | 1.9 MB RSS | dynamic | system library | yes |
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
Integration
Four calls. The agent does not own main(), does not create threads on bare metal, and does not block.
#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();
}
}
[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. |