OTA and Updates

OTA and Firmware Updates

v6.x supports over-the-air firmware updates via the web UI — drag-drop a .bin file and the device reboots into the new firmware. The bootloader rollback path is armed, so if the new firmware fails to boot, the device falls back to the previous slot on next power cycle.

Update from a release

1. Go to the releases page.
2. Pick a release. For v6.x the current pre-release is v6.1.0-alpha.1.
3. Download ambisense-c3-v6.1.0-alpha.1.bin (the app image — you don't need to re-flash the bootloader for an OTA).
4. Open your device's web UI → System → Firmware update.
5. Drag the .bin onto the upload area, or click to browse.
6. Watch the progress bar. Upload takes 5–15 s on home Wi-Fi.
7. The device reboots; the UI shows a 30 s "rebooting" overlay polling /api/version until the new build responds.
8. The version string in System → About should show the new tag.

Update from a local build

If you're building from source and want to test on a deployed device without re-flashing over USB:

cd firmware
. ~/esp/esp-idf-v5.5.2/export.sh
idf.py build

# Then upload the resulting build/ambisense.bin via the web UI.

Or via curl if you'd rather skip the UI:

curl -X POST http://ambisense-XXXX.local/api/ota \
  --data-binary @build/ambisense.bin \
  -H "Content-Type: application/octet-stream"

If you've set an admin password, the OTA endpoint requires authentication — log in via the UI first to get the cookie, or POST to /api/auth/login first.

What gets updated

OTA only replaces the app partition (the ~1.1 MB main firmware). It does not touch:

• Bootloader (0x0000) — only updatable via USB flash.
• Partition table (0x8000) — only updatable via USB flash.
• NVS (0x9000) — your settings (Wi-Fi password, LED config, motion knobs, hostname, admin password) survive OTA.
• OTA data (0xD000) — points to which app slot is current; updated automatically by the OTA driver.

If a release notes a partition-table change, you must re-flash all binaries via USB, not OTA. v6.1.0-alpha.1 uses the same partition table as v6.0.0, so OTA from v6.0 to v6.1.0-alpha.1 is safe.

Rollback

The ESP-IDF OTA system writes the new image to the inactive app slot (slot 0 or 1, whichever isn't currently running), then sets a "pending verification" flag in OTA data. On reboot:

1. The bootloader sees the pending flag and boots the new image.
2. If app_main runs to completion and reaches ota_mark_valid() (which v6.x calls late in boot), the pending flag is cleared and the new image becomes the canonical one.
3. If app_main crashes or panics before ota_mark_valid(), the bootloader will, on the next reset, see the pending-verification flag still set, decide the new image is broken, and boot the previous slot.

Net effect: a broken firmware update self-recovers on the next power cycle. You don't need to USB-flash to recover.

If a really broken firmware boots successfully but is broken in a way that prevents OTA (e.g. the web server crashes), you can still recover via USB by holding the BOOT button and re-flashing.

Versioning

v6.x firmware reports its version in /api/version:

{
  "version": "v6.1.0-alpha.1",
  "git_sha": "29ebac7",
  "idf_ver": "v5.5.2",
  "target": "esp32c3",
  "free_heap": 60384,
  "uptime": 12345
}

The version string comes from the git tag at build time. If you build from a commit that's not a tag, you'll see v6.x-NN-gSHORTSHA (the format is <latest-tag>-<commits-since>-g<short-sha>).

Auto-update?

There's no auto-update mechanism in v6.x. Check the releases page periodically, or watch the repo on GitHub for release notifications.

Signed OTA?

v6.x ships unsigned. The bootloader rollback path is armed (so a bad OTA is recoverable), but anyone who can reach /api/ota on your local network and authenticate could install arbitrary firmware. Mitigations:

• Set an admin password via System → Admin password. This forces auth on every settings/OTA POST.
• Don't expose the device to the internet. It's a LAN-only device. If you VPN in, that's fine. If you port-forward to it, that's not.

Signed OTA with esp_secure_boot is on the roadmap; signing keys + UI workflow are pending.

Changelog discipline

When a v6.x release ships:

• The release page lists every change.
• The git tag is annotated with the same summary.
• This wiki's Version History gets updated.
• The docs/V6-ROADMAP.md marks the release as shipped.

If you're bisecting a regression, all that gives you a tight window: the git log between two tags is what to read.