lucky-cat/docs/ota-firmware-integration.md

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.