42 lines
2.3 KiB
Markdown
42 lines
2.3 KiB
Markdown
# OTA Firmware Integration
|
|
|
|
The control plane owns a managed OTA worker. After Wi-Fi is available, it
|
|
obtains a device JWT with the `ota:report` scope and posts the running device
|
|
identity and firmware version to `CONFIG_TQ_OTA_REPORT_URL`.
|
|
|
|
The service returns `204` when the running image is current. A `200` response
|
|
with `data.notUptodate=1` includes the target version, HTTPS download URL,
|
|
exact byte size, SHA-256, and the `force`/`update` decision. Non-forced images
|
|
wait for the mini-program confirmation (`update=1`); forced images proceed
|
|
without that confirmation.
|
|
|
|
After an update is approved, the control plane checks the latest valid battery
|
|
snapshot before downloading the image. A battery percentage below
|
|
`CONFIG_TQ_OTA_MIN_BATTERY_PERCENT`, an unavailable sample, or a stale sample
|
|
puts the worker in `CONTROL_PLANE_OTA_STATE_WAITING_FOR_POWER`. This is a
|
|
deferred safety condition rather than an OTA failure, so it does not increment
|
|
the failure counter. Forced updates do not bypass the gate. The worker releases
|
|
voice resources and reports the version again after
|
|
`CONFIG_TQ_OTA_POWER_RETRY_MS`, which also obtains a fresh expiring download
|
|
URL. Once installation starts, later percentage changes do not cancel it.
|
|
|
|
Before an HTTPS exchange, the worker quiesces local wake and multimodal voice
|
|
services, waits for transport teardown, and checks internal/DMA memory
|
|
headroom. The platform layer streams the image into the inactive OTA
|
|
partition, verifies the exact byte count and raw-file SHA-256, validates the
|
|
ESP-IDF image, selects the new boot partition, and restarts. Any failure
|
|
aborts the OTA handle and leaves the current partition active.
|
|
|
|
The first normal runtime startup of a pending image confirms it with the
|
|
ESP-IDF rollback API. A failed or unhealthy boot therefore rolls back to the
|
|
previous image.
|
|
|
|
The running version is embedded in the application descriptor at build time.
|
|
Update the repository-root `version.txt` before publishing a release; the
|
|
device reads it at runtime through `esp_app_get_description()->version`.
|
|
|
|
The device report route should normally be exempted from service-to-service
|
|
HMAC authentication while retaining device JWT authentication. The optional
|
|
`CONFIG_TQ_OTA_INTERNAL_AUTH_SECRET` exists only for deployments that require
|
|
the documented `X-Internal-*` headers.
|