# 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.