Skip to content

OTA Updates Module

Over-the-air firmware updates for Espilon agents. Download and apply new firmware from an HTTPS URL, with certificate validation and automatic rollback on failure.

Configuration

Enable in idf.py menuconfig → Espilon Bot Configuration → Modules → OTA Updates

Config flag: CONFIG_ESPILON_OTA_ENABLED

Overview

The OTA module allows remote firmware updates without physical access to the device. It uses the ESP-IDF OTA framework with a dual partition scheme (A/B) for safe updates and rollback.

┌─────────────────────────────────────────┐
│            OTA Update Flow              │
│                                         │
│  C2 Server                              │
│    │                                    │
│    ├─ ota_update <url>                  │
│    │                                    │
│  Agent (ESP32)                          │
│    ├─ Download firmware (HTTPS)         │
│    ├─ Validate image                    │
│    ├─ Write to inactive partition       │
│    ├─ Set boot partition                │
│    └─ Reboot                            │
│                                         │
│  Partition Layout:                      │
│    ┌────────┐ ┌────────┐               │
│    │ OTA_0  │ │ OTA_1  │  (A/B scheme) │
│    │ (app)  │ │ (app)  │               │
│    └────────┘ └────────┘               │
│    ┌────────┐                           │
│    │OTA data│  (boot selection)         │
│    └────────┘                           │
└─────────────────────────────────────────┘

Configuration

Option Default Description
CONFIG_ESPILON_OTA_ENABLED y Enable OTA updates
CONFIG_ESPILON_OTA_ALLOW_HTTP n Allow plaintext HTTP downloads (insecure)

HTTP Mode

Enabling CONFIG_ESPILON_OTA_ALLOW_HTTP disables TLS certificate validation. Only use on trusted networks during development.

Partition Table

OTA requires a dual-partition layout. The partition table (partitions.csv) must include:

Partition Type Size Purpose
otadata data 8 KB Boot partition selector
ota_0 app ~1.5 MB Application slot A
ota_1 app ~1.5 MB Application slot B
fctry data 24 KB Factory NVS (master key)

Commands

ota_update

Download and apply a firmware update from an HTTPS URL. Async.

Syntax:

c2:> send <device_id> ota_update <url>

Parameters:

Parameter Type Required Description
url string Yes HTTPS URL of the firmware binary (.bin)

Behavior:

  1. Validate URL (HTTPS required unless HTTP allowed)
  2. Begin streaming download with TLS certificate validation
  3. Write to inactive OTA partition
  4. Report progress to C2 (every 10%)
  5. Validate firmware image integrity
  6. Set new boot partition
  7. Reboot device

Progress output:

OTA: downloading from https://c2.example.com/firmware/esp001.bin
OTA: progress 10%
OTA: progress 20%
...
OTA: progress 100%
OTA: image validated, rebooting...

Error handling:

  • Invalid URL → error message, no reboot
  • Download failure → error message, no reboot
  • Image validation failure → error message, no reboot, partition unchanged
  • On any failure, the device stays on the current firmware

ota_status

Show current firmware information.

Syntax:

c2:> send <device_id> ota_status

Response:

running=ota_0 boot=ota_0 version=v2.1.0 idf=v5.3.2
Field Description
running Currently running partition label
boot Partition selected for next boot
version Firmware version string
idf ESP-IDF version

Usage Examples

Update from C2

# Build firmware with deploy.py or build manager
# Upload .bin to a web server

# Trigger update
c2:> send esp001 ota_update https://c2.example.com/firmware/esp001-latest.bin

# Check status after reboot
c2:> send esp001 ota_status

Update via Web Dashboard

The C3PO web dashboard provides an OTA management page at /ota:

  1. Select target device(s)
  2. Upload or select firmware binary
  3. Click "Update" — progress is displayed in real-time
  4. Device reboots automatically on success

Batch Update

# Update multiple devices
c2:> group add fleet esp001 esp002 esp003
c2:> send @fleet ota_update https://c2.example.com/firmware/v2.1.0.bin

Security

  • HTTPS with certificate validation by default (ESP-IDF mbedTLS cert bundle)
  • Image integrity check before committing the update
  • Dual partition scheme ensures rollback if the new firmware crashes at boot
  • No downgrade protection by default — any valid firmware image is accepted

Best Practice

Always test firmware on a single device before batch-updating a fleet.

Previous: CAN Bus | Next: Command Reference