The Factory

1 One egg, three parts

The factory image

A brand-new board is empty — no name, no job, no idea it's a Canary. To wake it up, everything it needs is merged into one file, called the factory image, and written over USB starting at the very first byte of its flash memory.

Think of it as an egg: the shell (the bootloader that wakes the chip), the map of what goes where (the partition table), and the bird itself (the app). One egg, nothing missing.

For makers: exactly how the egg is packed

firmware/scripts/make_factory.py merges bootloader.bin, partitions.bin, and firmware.bin with esptool's merge_bin. It reads the app's flash offset straight out of the compiled partition table rather than hard-coding it, so the image is correct for whatever layout a variant uses — offsets can't silently drift. On ESP32-S3/C3/C6 the bootloader sits at offset 0; classic ESP32 uses 0x1000.

2 The hatch

First flash, first memory

The first USB flash is the Canary's birthday. Because the factory image covers the flash from byte zero, it also wipes and re-seeds the little notebook where the device keeps what it learns — its WiFi, its settings, its name. That notebook is called NVS, and the first flash is what gives it one.

Hatching only happens once. After that, the Canary keeps its memories — updates never take them away.

For makers: the first-flash-seeds-NVS model

A factory image spans 0 to the end of the app, so flashing it re-initializes NVS — deliberately. SecuraCV's update model (docs/firmware_ota.md) is: a USB flash seeds NVS; every later OTA inherits it. That is also why a re-flash over USB is the honest "start over" — see the difference from a settings reset in step 5.

3 Growing up

Factory vs. everyday updates

After it hatches, a Canary doesn't go back to the Factory for every update. Over-the-air (OTA) updates ship just the app — the bird learns a new song without being re-hatched. The bootloader installs the new app into a spare slot, and only switches over once it's safely written.

Factory image = being born. OTA update = growing up. Your Canary's memory survives growing up.

For makers: app-only images and slots

The OTA channel ships app-only firmware.bin images that the running bootloader installs into a spare OTA slot (ota_0/ota_1), keeping NVS and the rest of flash untouched. The browser flasher instead writes the whole factory blob to a blank board — the two paths exist for the two different moments in a device's life.

4 The birth certificate

Check where its brain came from

You should never have to trust that a Canary's firmware is the real thing — you should be able to check. Every release publishes a signed manifest saying exactly which files are official, and the build itself leaves a public, append-only record of where and how it was made.

It's a birth certificate anyone can read: which factory, which day, which blueprints. If a single byte were different, the certificate wouldn't match.

For makers: the provenance trail, end to end

The flasher catalog (canary-local/devices/flash.json) points at a signed release manifest (manifest-flash.json) with a published release key, and builds carry SLSA provenance recorded in the Rekor transparency log — so the chain from source commit to the bytes on your chip is publicly verifiable, not a promise. The How It Works page walks the same idea for evidence; the Factory applies it to the firmware itself.

5 Hatch one yourself

Three doors into the Factory

One more thing, because the words look alike: a factory reset (on your Canary's help page) clears settings on a device you already have. A factory image makes a device from scratch. Reset forgets; the Factory begins.