Skip to content

RaftESPOTAUpdateSysMod

Rob Dobson edited this page Oct 25, 2026 · 3 revisions

ESPOTAUpdate SysMod

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.

Source: RaftSysMods/components/ESPOTAUpdate/

What it provides

  • HTTP-direct firmware push (espFwUpdate) from a host (e.g. an IDE plugin or raft CLI).
  • File-stream firmware update started by the framework when registered as the firmware handler with ProtocolExchange.
  • esp_ota_begin/write/end run 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.

SysType configuration

{
    "name": "ESPOTAUpdate",
    "OTADirect": 1
}
Key Default Meaning
OTADirect true Enable firmware updates. When false, fileStreamStart() refuses every update — over espFwUpdate and over file streams alike.

REST endpoints exposed

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.

Writes in the background

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.

Application integration

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.

Restart behaviour

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().

Related

Clone this wiki locally