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

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.