ESP32 SDK Reference

<!-- Generated from OneSay canonical specs. Source SHA-256: b4b9c06106eeaacd9b3d12592b48d82b4247853bea70c203aa8fe5e76500d37f. DO NOT EDIT. -->
# ESP32 SDK Contract

Status: `owner-approved/protocol-connectivity-local-candidate`; runtime implemented: `false`; publishable: `false`.

- Component: `onesay-esp32@0.0.0-e8-runtime`
- Framework: ESP-IDF protocol/connectivity; hardware ownership: onesay-os
- Audio: 16000 Hz mono pcm_s16le, 40 ms frames
- Default replay: 3000 ms / 96000 bytes, bounded with explicit overflow
- Credential access: caller-supplied secure-store interface; storage implementation belongs to onesay-os
- TLS/WebSocket runtime: `TRANSPORT-INTERFACE-IMPLEMENTED`
- ESP-IDF TLS/WebSocket adapter: `IMPLEMENTED-LOCAL-CANDIDATE`
- Audio input: caller-supplied canonical PCM; acquisition implementations forbidden
- Protocol conformance: incomplete Mock Device; physical validation belongs to onesay-os

The fixed-capacity C protocol client exercises canonical bootstrap binding, framing, replay, ACK, event ordering, callback dispatch and reconnect behavior. It accepts caller-supplied PCM and secure credential access. It does not implement acquisition, storage hardware policy or physical validation. Software-only Mock Device conformance and external service integration remain incomplete; component publication is not authorized.

## Task voice

- Entry points: `onesay_client_init`, `onesay_client_connect`, `onesay_client_start_dictation`, `onesay_client_write_audio`, `onesay_client_replay_unacked`, `onesay_client_reconnect`, `onesay_client_end_signal`, `onesay_client_dispatch`, `onesay_client_disconnect`
- Transport: onesay.realtime.v1 WebSocket with canonical PCM frames, contiguous ACK, unacked-only replay and bounded resume
- Results: Task events through the bounded event queue

## Realtime RTC

- Entry points: `onesay_esp32_rtc_prepare`, `onesay_esp32_rtc_connect_audio`, `onesay_esp32_rtc_read_media_status`, `onesay_esp32_rtc_read_binding`, `onesay_esp32_rtc_close`
- Transport: OneSay RTC binding over the pinned official ESP32 runtime behind one internal adapter
- Results: RTC audio, packet send, stream receive, RPC callee and explicit Agent Control

## Declared capabilities

| Capability | Support | Detail |
|---|---|---|
| Task voice (WSS, ACK, replay, resume) | supported | Supported |
| RTC audio | supported | RTC audio owner |
| Packets | partial | Send only: the pinned upstream receive callback omits reliable/lossy mode (`LIM-ESP32-PACKET-RECEIVE-MODE-ABSENT-FBF09EDF`) |
| Streams | partial | Receive only: pinned open/write options lack a destination selector (`LIM-ESP32-STREAM-TARGETED-SEND-ABSENT-FBF09EDF`) |
| RPC | partial | Callee only (answers 1–4 `app.*` methods, replies to the original caller only); no caller: the pinned runtime has no invoke API (`LIM-GX09-RPC-OUTBOUND-INVOKE-FBF09EDF`) |
| DataTrack | unsupported | Unsupported: no upstream API; no substitute transport (`LIM-ESP32-DATATRACK-API-ABSENT-FBF09EDF`) |
| Agents | supported | Explicit Agent Control (create, get, stop) |
| State, device, error, release | supported | Binding and media status, OneSay error codes, close |
| Selected-mode media encryption | unsupported | Unsupported: any selected value is refused before any request (`LIM-ESP32-MEDIA-ENCRYPTION-UNSUPPORTED-FBF09EDF`) |

Not exposed: native room or track handles; native token or connection material; the upstream ESP32 runtime API. Unsupported entries fail explicitly; generated profile types confer no runtime support.

`runtime_implemented: false` is the pinned E8 contract gate of this specification, not a statement that no code exists: the local component candidate above builds and runs on the host, while the required real-device SDK smoke, native network delivery on hardware and Staging are NOT-RUN. See the [capability and compatibility page](sdk-compatibility.md).