Repository navigation
RaftESPOTAUpdateSysMod
Built-in SysMod that performs ESP32 OTA firmware updates. Receives the firmware image as a stream and writes it to the inactive OTA partition using
esp_ota_*APIs, then triggers a restart.
- HTTP-direct firmware push (
espFwUpdate) from a host (e.g. an IDE plugin orraftCLI). - File-stream firmware update started by the framework when registered as the firmware handler with ProtocolExchange.
-
esp_ota_begin/write/endrun on the shared file system worker (ESPOTAUpdate has no task of its own), so neither the main loop nor the network stack waits for flash writes. - Per-update statistics: total bytes, write time, throughput, CRC.
| Key | Default | Meaning |
|---|---|---|
OTADirect |
true |
Enable firmware updates. When false, fileStreamStart() refuses every update — over espFwUpdate and over file streams alike. |
| Endpoint | Method | Purpose |
|---|---|---|
espFwUpdate |
POST | Stream firmware image as POST body. Body is consumed in chunks; response is sent on completion. |
The body is read only while less than 16 KB (HTTP_PENDING_MAX_BYTES) of received firmware is waiting to be written, so a fast client is slowed by TCP flow control. The reply is deferred until the last block has been written and the update completed (up to 15 s), so it gives the real result: {"rslt":"ok"}, or "rslt":"fail" with "error" such as Failed, FailedOTAEnd or FailedSetBootPartition.
Each received block is copied (into PSRAM where available) and queued; a job on the file system worker writes the blocks in order. If there isn't the memory for a copy (with a 16 KB margin) the block fails. fileStreamWriteStatus() is RAFT_BUSY while blocks are waiting, and reports a failed write: a file-stream upload holds back its acks until the firmware is written and is cancelled if a write fails (see OTA Update Flow).
Erasing and writing the flash stalls all code running from flash unless the app runs from PSRAM — see OTA Update Flow.
To make the framework route file-stream uploads (e.g. a ufStart over BLE/WebSocket/serial with content type firmware) to this SysMod, register it with ProtocolExchange:
auto* pProtoExch = (ProtocolExchange*)getSysManager()->getSysMod("ProtoExchange");
auto* pOTA = (ESPOTAUpdate*)getSysManager()->getSysMod("ESPOTAUpdate");
if (pProtoExch && pOTA)
pProtoExch->setFWUpdateHandler(pOTA);ESPOTAUpdate::setup() does this itself, so there's normally nothing to add.
After a successful OTA write, the SysMod waits TIME_TO_WAIT_BEFORE_RESTART_MS (1000 ms) so the response can be transmitted, then triggers esp_restart() from loop().
- OTA Update Flow — both update paths end to end
- File Download Protocol (OKTO) — the inbound firmware-stream path
- ProtocolExchange — owns file/stream sessions and the FW update hook
Common Tasks
Getting Started
- Quick Start
- Architecture at a Glance
- Writing Your First SysMod
- Adding a Comms Channel
- Adding an I2C Device Type
Scaffolding & Building
- Raft CLI
- Web Apps (Device Types, Flasher)
- SysTypes
- Top-Level SysType
- Build Process
- WebUI Build Pipeline
- File System
- Partitions & Flash
- Local Dev Libraries
- Library Developer Guide
Architecture
Built-in SysMods
- NetworkManager
- WiFi Troubleshooting
- BLEManager
- WebServer
- MQTTManager
- SerialConsole
- CommandSerial
- CommandSocket
- CommandFile
- FileManager
- LogManager
- ESPOTAUpdate
- StatePublisher
- Remote Logging
- Data Source Registration
Comms & Protocols
- Stack Overview
- Comms Channels
- ProtocolExchange
- RICREST Protocol
- Real-Time Streams
- Adding REST Endpoints
- Built-in REST Endpoints
- File Download (OKTO)
- OTA Update Flow
Devices & Buses
- DeviceManager
- Device Manager REST API
- Device Factory & Classes
- Device Type Records
- Selecting Device Types
- Adding an I2C Device Type
- Device Data Publishing
- Data Logger
- I2C Bus
- I2C Device Scanning
- I2C ID & Polling
- MotorControl Overview
- MotorControl Config
- MotorControl Commands
- Camera
ROS 2
Helpers
Reference
{ "name": "ESPOTAUpdate", "OTADirect": 1 }