@tencentcloud/sdk-mcp 1.7.7 → 1.7.9-beta.1

package/resource/knowledge/iot/client-api/device/linux-rtos-device.md

@@ -0,0 +1,2027 @@
+---
+product: iot
+framework:
+  - linux
+types:
+  - api
+retrievable_scope: always
+feature_domain: client_api
+---
+
+## 概述
+
+本文档描述设备端公开 C API。接口线程安全（可任意线程调用），异步回调契约为：同步返回成功则一定回调，同步返回失败则一定不回调（个别接口另有说明）。推荐生命周期：​tc_iot_init → ​tc_iot_login → 各业务模块 init → 业务运行 → 各业务模块 deinit → ​tc_iot_deinit。
+
+SDK 模块一览：
+
+|模块|说明|
+|---------|---------|
+|核心生命周期|核心生命周期（连接与设备身份）。|
+|物模型|物模型（属性 / 事件 / 行为）。|
+|音视频|音视频通话 / IPC 监控。|
+|云存储|云存储（全时 / 事件录像与抓图上报）。|
+|AI 对话|AI 对话（AITalk）。|
+|录音卡|录音卡（当前经 BLE 传输；本地落盘尚未启用）。|
+|OTA 升级|固件下载、校验及固件刷写状态上报。|
+|类型定义|音视频公共类型（AV / AITalk / 录音卡共用）。|
+|错误码|SDK 统一错误码。|
+
+API 索引：
+
+### 核心生命周期（tc_iot.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_init|初始化 SDK 核心（异步完成初始化）。|
+|tc_iot_deinit|反初始化 SDK；阻塞等待内部清理完成后返回。|
+|tc_iot_login|使用三元组登录（异步 MQTT 连接，内部可重试）。|
+|tc_iot_logout|登出并清除本地凭证（异步，无独立完成回调）。|
+|tc_iot_dynamic_register|动态注册设备（同一时刻仅允许一路）。|
+|tc_iot_get_ntp_time|读取 NTP 同步后的 UTC 毫秒时间戳。|
+|tc_iot_get_sdk_version|读取 SDK 版本字符串。|
+
+### 物模型（tc_iot_data_model.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_data_model_init|初始化物模型并订阅下行 topic。|
+|tc_iot_data_model_report_property|上报属性。|
+|tc_iot_data_model_report_event|上报事件。|
+|tc_iot_data_model_deinit|反初始化；同步清除单例后异步退订。|
+
+### 音视频（tc_iot_av.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_av_init|初始化 AV 模块并注册观察者（内部拷贝 observer）。|
+|tc_iot_av_deinit|反初始化 AV；同步清除单例后异步退订信令。|
+|tc_iot_av_get_contacts|拉取联系人列表。|
+|tc_iot_av_call|发起呼出。|
+|tc_iot_av_accept|接听呼入；仅在振铃态有效，否则回调 AV_ON_*。|
+|tc_iot_av_reject|拒绝呼入；仅在振铃态有效。|
+|tc_iot_av_hangup|挂断当前会话；无对应会话时回调 ​TC_IOT_ERR_AV_ON_IDLE。|
+|tc_iot_create_video_channel|创建视频推流通道。|
+|tc_iot_create_audio_channel|创建全局唯一音频推流通道。|
+|tc_iot_destroy_video_channel|销毁视频通道。|
+|tc_iot_destroy_audio_channel|销毁音频通道。|
+|tc_iot_push_video_frame|推送一帧视频（调用方线程同步）。|
+|tc_iot_push_audio_frame|推送一帧音频（调用方线程同步）。|
+
+### 云存储（tc_iot_cloud_storage.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_cloud_storage_init|初始化云存储并查询套餐。|
+|tc_iot_cloud_storage_deinit|反初始化云存储，停止录像并释放资源。|
+|tc_iot_cloud_storage_get_plan_type|查询指定通道当前云存套餐类型。|
+|tc_iot_cloud_storage_start_continuous_recording|开始全时录像。|
+|tc_iot_cloud_storage_stop_continuous_recording|停止全时录像。|
+|tc_iot_cloud_storage_start_event_recording|开始事件录像。|
+|tc_iot_cloud_storage_stop_event_recording|停止事件录像。|
+|tc_iot_cloud_storage_report_event_snapshot|上报事件抓图。|
+
+### AI 对话（tc_iot_aitalk.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_aitalk_init|初始化 AITalk。|
+|tc_iot_aitalk_deinit|反初始化；阻塞等待内部清理完成。|
+|tc_iot_aitalk_start_speak|开始对话。|
+|tc_iot_aitalk_stop_speak|停止对话（异步投递，空闲时幂等成功）。|
+|tc_iot_aitalk_send_audio|发送一帧上行音频。|
+|tc_iot_aitalk_send_text|发送文本给 LLM。|
+|tc_iot_aitalk_register_contacts|注册可供机器人呼叫的联系人。|
+|tc_iot_aitalk_interrupt|打断机器人当前播报（连续模式下有效）。|
+
+### 录音卡（tc_iot_audio_recorder.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_audio_recorder_init|初始化录音卡并注册观察者。|
+|tc_iot_audio_recorder_deinit|反初始化；阻塞等待内部清理完成。|
+|tc_iot_audio_recorder_start|开始录音。|
+|tc_iot_audio_recorder_stop|停止录音（异步投递）。|
+|tc_iot_audio_recorder_send_audio|发送一帧录音音频。|
+
+### OTA 升级（tc_iot_ota.h）
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_ota_init|初始化 OTA，注册回调并上报当前固件版本。|
+|tc_iot_ota_deinit|反初始化 OTA，停止下载并释放资源。|
+|tc_iot_ota_download_firmware|发起固件下载，由 SDK 下载并校验固件。|
+|tc_iot_ota_report_upgrade_progress|上报固件刷写进度。|
+|tc_iot_ota_report_upgrade_result|上报固件刷写结果。|
+
+## 核心生命周期（tc_iot.h）
+
+核心生命周期（连接与设备身份）
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用。
+>
+
+> **回调 / 通知模型**
+>
+> - on_log：日志回调线程可能与调用方线程不同。
+> - on_device_event：event_data 当前恒为 NULL；回调内勿做耗时操作。ONLINE 仅表示 MQTT 已连，不携带校时，壁钟请用 ​tc_iot_get_ntp_time（未就绪返回 NTP_TIME_NOT_READY）。
+> - tc_iot_login_cb / ​tc_iot_dynamic_register_cb： 同步返回 SUCCESS 则一定会回调；同步失败则一定不回调。
+
+> **生命周期**
+>
+> 推荐顺序：​tc_iot_init → ​tc_iot_login（等待回调成功）→ 各业务模块 init → 业务运行 → 各业务模块 deinit → ​tc_iot_deinit。 ​tc_iot_logout 可选；deinit 会断开 MQTT。
+>
+
+> **业务约束**
+>
+> - 重复 init 返回 ALREADY_INITIALIZED；未 init 调用业务接口返回 NOT_INITIALIZED。
+> - tc_iot_init 同步 SUCCESS 仅表示任务已投递；异步初始化失败时后续 login 会以回调失败体现。
+> - tc_iot_deinit 为阻塞接口；动态注册进行中时拒绝 deinit （DYNAMIC_REGISTER_BUSY）。
+> - 动态注册成功后的 device_key 须由调用方写入非易失存储， 再作为 device_secret 登录。
+> - region 取值见 ​tc_iot_config_s。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_init|初始化 SDK 核心（异步完成初始化）。|
+|tc_iot_deinit|反初始化 SDK；阻塞等待内部清理完成后返回。|
+|tc_iot_login|使用三元组登录（异步 MQTT 连接，内部可重试）。|
+|tc_iot_logout|登出并清除本地凭证（异步，无独立完成回调）。|
+|tc_iot_dynamic_register|动态注册设备（同一时刻仅允许一路）。|
+|tc_iot_get_ntp_time|读取 NTP 同步后的 UTC 毫秒时间戳。|
+|tc_iot_get_sdk_version|读取 SDK 版本字符串。|
+
+### tc_iot_init
+
+**初始化 SDK 核心（异步完成初始化）**
+
+|参数|描述|
+|---------|---------|
+|config|初始化配置，不可为 NULL。region 见 ​tc_iot_config_s。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_INVALID_ARGUMENT|config 为空、storage_path / region 非法，或 region 不在允许取值内。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|已初始化。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+|TC_IOT_ERR_FAILURE|内部 AV 通道初始化失败。|
+
+### tc_iot_deinit
+
+**反初始化 SDK；阻塞等待内部清理完成后返回**
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|未初始化。|
+|TC_IOT_ERR_DYNAMIC_REGISTER_BUSY|动态注册进行中。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+
+### tc_iot_login
+
+**使用三元组登录（异步 MQTT 连接，内部可重试）**
+
+同步返回 SUCCESS 仅表示任务已投递；最终结果以 `callback` 为准。 已连接时回调 ​TC_IOT_ERR_ALREADY_CONNECTED。
+
+|参数|描述|
+|---------|---------|
+|device_info|设备三元组；product_id/device_id/device_secret 必填。|
+|callback|登录结果回调；同步 SUCCESS 则一定回调，失败则不回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法。|
+|TC_IOT_ERR_NOT_INITIALIZED|未 init。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+
+### tc_iot_logout
+
+**登出并清除本地凭证（异步，无独立完成回调）**
+
+进行中的 login 会被取消并以 ​TC_IOT_ERR_NOT_CONNECTED 回调。
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_NOT_INITIALIZED|未 init。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+
+### tc_iot_dynamic_register
+
+**动态注册设备（同一时刻仅允许一路）**
+
+成功后用回调中的 device_key 作为 device_secret 登录。
+
+|参数|描述|
+|---------|---------|
+|param|注册参数。|
+|callback|注册结果回调；同步 SUCCESS 则一定回调，失败则不回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法。|
+|TC_IOT_ERR_NOT_INITIALIZED|未 init。|
+|TC_IOT_ERR_DYNAMIC_REGISTER_BUSY|已有注册进行中。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+
+### tc_iot_get_ntp_time
+
+**读取 NTP 同步后的 UTC 毫秒时间戳**
+
+MQTT ONLINE 后异步触发同步；未完成前返回 NTP_TIME_NOT_READY。
+
+|参数|描述|
+|---------|---------|
+|utc_time_ms|输出 UTC 毫秒时间戳，不可为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|已同步并写入。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法。|
+|TC_IOT_ERR_NTP_TIME_NOT_READY|尚未同步完成。|
+
+### tc_iot_get_sdk_version
+
+**读取 SDK 版本字符串**
+
+可在任意时刻调用，包括 init 之前。返回值为静态字符串，无需释放。
+
+|返回值|描述|
+|---------|---------|
+|const char *|SDK 版本号字符串；不会为 NULL。|
+
+### tc_iot_log_level_e
+
+**日志输出阈值（数值越大输出越详细）。 设置为某级别时，输出该级别及更严重的日志（不含更详细级别）。**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_LOG_LEVEL_NONE|0|关闭日志输出。|
+|TC_IOT_LOG_LEVEL_ERROR|1|仅输出错误。|
+|TC_IOT_LOG_LEVEL_WARN|2|输出警告与错误。|
+|TC_IOT_LOG_LEVEL_INFO|3|输出信息、警告与错误。|
+|TC_IOT_LOG_LEVEL_DEBUG|4|输出全部日志（含调试，最详细）。|
+
+### tc_iot_device_event_type_e
+
+**设备在线状态事件（MQTT 连接态映射；不含墙钟时间）**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_DEV_EVENT_ONLINE|0|MQTT 已连接（≠ NTP 已同步）。|
+|TC_IOT_DEV_EVENT_OFFLINE|1|MQTT 已断开。|
+|TC_IOT_DEV_EVENT_RECONNECTING|2|MQTT 重连中。|
+
+### tc_iot_login_cb
+
+**登录结果回调**
+
+typedef void(* ​tc_iot_login_cb) (​tc_iot_error_e error_code, const char *error_message)
+
+|参数|描述|
+|---------|---------|
+|error_code|成功时为 ​TC_IOT_ERR_SUCCESS。|
+|error_message|错误描述，可为 NULL。|
+
+### tc_iot_dynamic_register_cb
+
+**动态注册结果回调**
+
+typedef void(* ​tc_iot_dynamic_register_cb) (​tc_iot_error_e error_code, const char *error_message, const char *device_key)
+
+|参数|描述|
+|---------|---------|
+|error_code|成功时为 ​TC_IOT_ERR_SUCCESS。|
+|error_message|错误描述，可为 NULL。|
+|device_key|成功时为设备密钥；须在回调返回前拷贝并写入非易失存储， 再作为后续 login 的 device_secret。|
+
+## 物模型（tc_iot_data_model.h）
+
+物模型（属性 / 事件 / 行为）
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用。
+>
+
+> **回调 / 通知模型**
+>
+> - on_report_*_result_cb：上报结果（含超时）；user_data 为 report 传入值。
+> - on_receive_property_changed_cb：云端属性控制。
+> - on_receive_new_action_cb：收到行为调用；调用方填充 action_output_data_* 后返回 0 表示成功回复，非 0 表示失败回复； 回调返回后 action 对象即释放，禁止缓存指针。
+
+> **生命周期**
+>
+> tc_iot_login 成功 → ​tc_iot_data_model_init → report_* → ​tc_iot_data_model_deinit
+>
+
+> **业务约束**
+>
+> - 标量类型用 data_value 对应字段；STRING 指针在构建 JSON 期间须有效。
+> - 可一次 report 多条；每条结果经 on_report_*_result_cb 返回。
+> - OBJECT / ARRAY 枚举已预留，当前实现未支持，请勿使用。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_data_model_init|初始化物模型并订阅下行 topic。|
+|tc_iot_data_model_report_property|上报属性。|
+|tc_iot_data_model_report_event|上报事件。|
+|tc_iot_data_model_deinit|反初始化；同步清除单例后异步退订。|
+
+### tc_iot_data_model_init
+
+**初始化物模型并订阅下行 topic**
+
+须 login 成功。
+
+|参数|描述|
+|---------|---------|
+|data_model_callback|回调表。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|重复初始化。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+|TC_IOT_ERR_FAILURE|通用失败。|
+
+### tc_iot_data_model_report_property
+
+**上报属性**
+
+property_num > 0；同步 SUCCESS 表示发布任务已投递， 逐条结果经 on_report_property_result_cb 返回。
+
+|参数|描述|
+|---------|---------|
+|data_model_property|属性数组。|
+|property_num|数量。|
+|report_cb_user_data|透传到结果回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+|TC_IOT_ERR_FAILURE|通用失败。|
+
+### tc_iot_data_model_report_event
+
+**上报事件**
+
+语义与 report_property 相同，结果经 on_report_event_result_cb。
+
+|参数|描述|
+|---------|---------|
+|data_model_event|事件数组。|
+|event_num|数量。|
+|event_cb_user_data|透传到结果回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+|TC_IOT_ERR_FAILURE|通用失败。|
+
+### tc_iot_data_model_deinit
+
+**反初始化；同步清除单例后异步退订**
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### data_model_data_type_t
+
+**物模型数据类型**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|DATA_MODEL_DATA_TYPE_BOOL|0|布尔。|
+|DATA_MODEL_DATA_TYPE_INT|1|整数。|
+|DATA_MODEL_DATA_TYPE_FLOAT|2|浮点。|
+|DATA_MODEL_DATA_TYPE_STRING|3|字符串。|
+|DATA_MODEL_DATA_TYPE_ENUM|4|枚举。|
+|DATA_MODEL_DATA_TYPE_TIME|5|时间。|
+|DATA_MODEL_DATA_TYPE_OBJECT|6|预留；当前实现未支持。|
+|DATA_MODEL_DATA_TYPE_ARRAY|7|预留；当前实现未支持。|
+
+### data_model_event_type_t
+
+**事件类型**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|DATA_MODEL_EVENT_TYPE_INFO|0|信息类事件。|
+|DATA_MODEL_EVENT_TYPE_ALERT|1|告警类事件。|
+|DATA_MODEL_EVENT_TYPE_FAULT|2|故障类事件。|
+
+### data_model_report_result_t
+
+**上报结果**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|DATA_MODEL_REPORT_SUCCESS|0|云端接受。|
+|DATA_MODEL_REPORT_REJECTED|1|云端拒绝。|
+|DATA_MODEL_REPORT_NO_RESPONSE|2|无云端响应。|
+|DATA_MODEL_REPORT_LOCAL_TIMEOUT|3|本地等待超时。|
+
+### data_model_bool_t
+
+**布尔属性值类型**
+
+typedef bool ​data_model_bool_t
+
+### data_model_int_t
+
+**整型属性值类型**
+
+typedef int32_t ​data_model_int_t
+
+### data_model_float_t
+
+**浮点属性值类型**
+
+typedef double ​data_model_float_t
+
+### data_model_string_t
+
+**字符串属性值类型（调用方持有指针）**
+
+typedef char* ​data_model_string_t
+
+### data_model_enum_t
+
+**枚举属性值类型**
+
+typedef uint32_t ​data_model_enum_t
+
+### data_model_time_t
+
+**时间属性值类型（通常为 Unix 秒）**
+
+typedef uint32_t ​data_model_time_t
+
+### tc_iot_data_model_callback_t
+
+**物模型回调表**
+
+typedef struct ​tc_iot_data_model_callback ​tc_iot_data_model_callback_t
+
+## 音视频（tc_iot_av.h）
+
+音视频通话 / IPC 监控
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用；信令类操作异步执行。push_* 在调用方线程同步执行。
+>
+
+> **回调 / 通知模型**
+>
+> - tc_iot_av_observer_s：init 时拷贝；信令与帧回调可能不在调用方线程；音视频帧回调可能来自媒体线程；所有回调须尽快返回、勿阻塞。
+> - tc_iot_av_operation_cb：call/accept/reject/hangup 的 MQTT 发布结果； 同步 SUCCESS 则一定回调，同步失败则一定不回调。
+> - accept/reject/hangup 要求 callback 非 NULL；call 也应提供有效 callback。
+
+> **生命周期**
+>
+> tc_iot_init + ​tc_iot_login 成功 → ​tc_iot_av_init → （可选提前）create_*channel → 按会话推流 / 呼叫 API → destroy* / hangup → ​tc_iot_av_deinit
+>
+
+> **推流时机**
+>
+> - 监控：收到 on_monitor_begin 后持续 push_*；on_monitor_end 后可停。 多路监控复用同一音频通道，每路视频会话期间仍须送音频。
+> - VOIP：通话建立后再推（呼出等 on_call_accepted；呼入等 accept 成功）。
+> - 通道可预先 create；无活跃会话时 push 仅缓存，是否进房/上云由会话侧决定。
+> - 云存：创建与套餐通道 ID 对应的视频通道及全局音频通道后持续 push_*；全时 / 事件录像均从该通道取流。仅云存场景无需 tc_iot_av_init。
+
+> **业务约束**
+>
+> - 视频通道槽位最多 4 个，channel_id 须唯一；0 合法。与云存联用时须为 0～4。
+> - 音频通道全局仅 1 路；已存在时 create 返回 NULL，须复用指针。
+> - push_audio_frame 上行应送 16-bit PCM。非 PCM 当前仍返回 SUCCESS，但不编码、不供云存使用。
+> - 视频 Annex-B；IDR 须含 SPS/PPS（H265 含 VPS）；不支持 B 帧。
+> - 监控与 VOIP 互斥（冲突时返回 AV_ON_*）。
+> - tc_iot_av_get_contacts 异步拉取联系人；callback 不可为 NULL，limit 合法范围为 (0, 1024]。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_av_init|初始化 AV 模块并注册观察者（内部拷贝 observer）。|
+|tc_iot_av_deinit|反初始化 AV；同步清除单例后异步退订信令。|
+|tc_iot_av_get_contacts|拉取联系人列表。|
+|tc_iot_av_call|发起呼出。|
+|tc_iot_av_accept|接听呼入；仅在振铃态有效，否则回调 AV_ON_*。|
+|tc_iot_av_reject|拒绝呼入；仅在振铃态有效。|
+|tc_iot_av_hangup|挂断当前会话；无对应会话时回调 ​TC_IOT_ERR_AV_ON_IDLE。|
+|tc_iot_create_video_channel|创建视频推流通道。|
+|tc_iot_create_audio_channel|创建全局唯一音频推流通道。|
+|tc_iot_destroy_video_channel|销毁视频通道。|
+|tc_iot_destroy_audio_channel|销毁音频通道。|
+|tc_iot_push_video_frame|推送一帧视频（调用方线程同步）。|
+|tc_iot_push_audio_frame|推送一帧音频（调用方线程同步）。|
+
+### tc_iot_av_init
+
+**初始化 AV 模块并注册观察者（内部拷贝 observer）**
+
+须在 login 成功且设备身份就绪后调用。
+
+|参数|描述|
+|---------|---------|
+|observer|事件观察者，不可为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|重复初始化。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+|TC_IOT_ERR_FAILURE|通用失败。|
+
+### tc_iot_av_deinit
+
+**反初始化 AV；同步清除单例后异步退订信令**
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+
+### tc_iot_av_get_contacts
+
+**拉取联系人列表**
+
+同步返回 SUCCESS 仅表示请求已投递；列表结果或 MQTT 发布失败经 callback 返回。contacts / next_cursor 仅回调期间有效。
+
+|参数|描述|
+|---------|---------|
+|cursor|分页游标；首页传 NULL 或空串。|
+|limit|单页条数上限，合法范围 (0, 1024]。|
+|callback|结果回调，不可为 NULL。同步 SUCCESS 则一定回调，失败则不回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_NOT_INITIALIZED|AV 尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|callback 为空，或 limit 不在 (0, 1024]。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_av_call
+
+**发起呼出**
+
+contact->user_id 必填；建议提供非 NULL callback。 若已有非监控会话进行中，回调 ​TC_IOT_ERR_AV_ON_CALLING。
+
+|参数|描述|
+|---------|---------|
+|contact|被叫联系人。|
+|option|媒体选项。|
+|callback|操作结果回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_av_accept
+
+**接听呼入；仅在振铃态有效，否则回调 AV_ON_** *
+
+|参数|描述|
+|---------|---------|
+|contact|主叫联系人。|
+|callback|操作结果回调，不可为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_av_reject
+
+**拒绝呼入；仅在振铃态有效**
+
+|参数|描述|
+|---------|---------|
+|contact|主叫联系人。|
+|callback|操作结果回调，不可为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_av_hangup
+
+**挂断当前会话；无对应会话时回调 ​**TC_IOT_ERR_AV_ON_IDLE
+
+|参数|描述|
+|---------|---------|
+|contact|对端联系人。|
+|callback|操作结果回调，不可为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_create_video_channel
+
+**创建视频推流通道**
+
+channel_id 全局唯一，同时最多 4 路；0 合法。与云存联用时须为 0～4。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID；须唯一。0 合法。云存联用时须为 0～4。|
+|quality|画质档位。|
+
+|返回值|描述|
+|---------|---------|
+|tc_iot_av_channel_t *|通道句柄；失败返回 NULL（未 init / id 冲突 / 已满 / OOM）。|
+
+### tc_iot_create_audio_channel
+
+**创建全局唯一音频推流通道**
+
+已存在或未 init 时返回 NULL。多路监控须复用同一指针。
+
+|返回值|描述|
+|---------|---------|
+|tc_iot_av_channel_t *|通道句柄；失败返回 NULL。|
+
+### tc_iot_destroy_video_channel
+
+**销毁视频通道**
+
+|参数|描述|
+|---------|---------|
+|av_channel|视频通道。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+
+### tc_iot_destroy_audio_channel
+
+**销毁音频通道**
+
+|参数|描述|
+|---------|---------|
+|av_channel|音频通道。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+
+### tc_iot_push_video_frame
+
+**推送一帧视频（调用方线程同步）**
+
+须为视频通道。格式见 tc_iot_def.h（Annex-B；IDR 含参数集）。
+
+|参数|描述|
+|---------|---------|
+|av_channel|视频通道。|
+|frame|视频帧。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+
+### tc_iot_push_audio_frame
+
+**推送一帧音频（调用方线程同步）**
+
+须为音频通道。上行应送 16-bit PCM；非 PCM 仍返回 SUCCESS，但不编码、不供云存使用。同一通道生命周期内 sample_rate / channels 应保持稳定。
+
+|参数|描述|
+|---------|---------|
+|av_channel|音频通道。|
+|frame|音频帧。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。非 PCM 时亦返回 SUCCESS，但不编码。|
+|TC_IOT_ERR_INVALID_ARGUMENT|空指针或非音频通道。|
+
+### ptz_command_e
+
+**云台控制命令**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|PTZ_CMD_UP|0|上仰|
+|PTZ_CMD_DOWN|1|下俯|
+|PTZ_CMD_LEFT|2|左转|
+|PTZ_CMD_RIGHT|3|右转|
+|PTZ_CMD_ZOOM_IN|4|放大|
+|PTZ_CMD_ZOOM_OUT|5|缩小|
+|PTZ_CMD_STOP|6|停止运动|
+
+### tc_iot_av_channel_t
+
+**不透明 AV 推流通道句柄**
+
+typedef struct ​tc_iot_av_channel_s ​tc_iot_av_channel_t
+
+### tc_iot_call_option_t
+
+**呼叫 / 监控媒体选项**
+
+typedef struct ​tc_iot_call_option_s ​tc_iot_call_option_t
+
+### tc_iot_av_operation_cb
+
+**呼叫操作完成回调**
+
+typedef void(* ​tc_iot_av_operation_cb) (​tc_iot_error_e error_code, const char *error_message)
+
+|参数|描述|
+|---------|---------|
+|error_code|结果码。|
+|error_message|错误描述，可为 NULL。|
+
+### tc_iot_av_contacts_cb
+
+**联系人列表回调**
+
+typedef void(* ​tc_iot_av_contacts_cb) (​tc_iot_error_e error_code, const char *error_message, const ​tc_iot_contact_s *contacts, uint32_t count, const char *next_cursor)
+
+contacts、error_message、next_cursor 仅回调期间有效，须在返回前拷贝。
+
+### 宏定义
+
+|宏|取值|描述|
+|---------|---------|---------|
+|MAX_CUSTOM_DATA_LENGTH|256|call_option.custom_data 数组容量（含结尾 '\0'）。|
+
+## 云存储（tc_iot_cloud_storage.h）
+
+全时 / 事件录像与抓图上报。
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用；不得在云存回调内调用会阻塞的接口。
+>
+> init / deinit / report_event_snapshot：提交后立即返回。
+>
+> get_plan_type：同步读取当前套餐。
+>
+> start/stop_continuous_recording、start/stop_event_recording：提交后阻塞等待完成后返回。
+>
+
+> **回调 / 通知模型**
+>
+> - 回调须尽快返回；回调内不得调用会阻塞的云存接口。
+> - on_init_result：同步返回 SUCCESS 则一定会回调；同步失败则一定不回调。
+> - on_event_result：事件上报与图片上传完成后通知；event_result 仅在回调期间有效。
+> - on_plan_type_changed：云端套餐变更时通知。
+> - picture_data 须在对应 on_event_result 触发前始终有效。
+
+> **生命周期**
+>
+> tc_iot_init → ​tc_iot_login 成功 → （按通道 ​tc_iot_create_video_channel / ​tc_iot_create_audio_channel 并持续 push 帧）→ ​tc_iot_cloud_storage_init → 等待 on_init_result → 按套餐开始录像 / 抓图 → ​tc_iot_cloud_storage_deinit。
+>
+
+> **业务约束**
+>
+> - channel_id 合法范围为 0～4；同时在线通道不超过 4 路。
+> - 录像从与 channel_id 对应的视频通道及全局音频通道取流。仅云存场景无需调用 tc_iot_av_init，create/push 即可。
+> - 视频为 H264/H265 Annex-B 裸流；音频经 tc_iot_push_audio_frame 送 16-bit PCM。
+> - 全时套餐才可 start_continuous_recording；事件或全时套餐可 start_event_recording。
+> - 图片套餐或视频套餐可 report_event_snapshot。
+> - 同一通道同一 event_id 不可并发；重复开始返回失败。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_cloud_storage_init|初始化云存储并查询套餐。|
+|tc_iot_cloud_storage_deinit|反初始化云存储，停止录像并释放资源。|
+|tc_iot_cloud_storage_get_plan_type|查询指定通道当前云存套餐类型。|
+|tc_iot_cloud_storage_start_continuous_recording|开始全时录像。|
+|tc_iot_cloud_storage_stop_continuous_recording|停止全时录像。|
+|tc_iot_cloud_storage_start_event_recording|开始事件录像。|
+|tc_iot_cloud_storage_stop_event_recording|停止事件录像。|
+|tc_iot_cloud_storage_report_event_snapshot|上报事件抓图。|
+
+### tc_iot_cloud_storage_init
+
+**初始化云存储并查询套餐**
+
+须先完成 SDK 初始化和登录。初始化请求提交后，SDK 向云端查询各通道套餐，结果通过 on_init_result 回调。
+
+|参数|描述|
+|---------|---------|
+|cloud_storage_callback|tc_iot_cloud_storage_callback_t 回调表，不可为 NULL；on_init_result 为必选回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|初始化请求已提交，结果通过 on_init_result 回调。|
+|TC_IOT_ERR_INVALID_ARGUMENT|回调表为空，或未注册 on_init_result。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|云存储已初始化。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 未初始化。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_cloud_storage_deinit
+
+**反初始化云存储，停止录像并释放资源**
+
+设备退出登录或释放 SDK 前调用。反初始化会停止正在进行的录像；未完成的事件可能以 EVENT_CANCELLED 结束。无独立完成回调。
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|反初始化请求已提交。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 未初始化。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_cloud_storage_get_plan_type
+
+**查询指定通道当前云存套餐类型**
+
+可在任意线程调用。优先返回视频套餐（全时 / 事件）；无视频套餐且开通图片套餐时返回 IMAGE。通道不存在、尚未 init 完成或 channel_id 非法时返回 UNKNOWN。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID，合法范围 0～4。|
+
+|返回值|描述|
+|---------|---------|
+|tc_iot_cloud_storage_plan_type_t|当前套餐类型；见枚举说明。|
+
+### tc_iot_cloud_storage_start_continuous_recording
+
+**开始全时录像**
+
+仅在该通道套餐为 FULL_TIME 时有效。调用方须已创建对应视频通道和全局音频通道，并持续 push 音视频帧。本接口阻塞等待内部启动完成。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID，合法范围 0～4。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|已开始全时录像。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或云存储未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|channel_id 超出合法范围。|
+|TC_IOT_ERR_CLOUD_STORAGE_CHANNEL_NOT_FOUND|该 channel_id 无云存套餐。|
+|TC_IOT_ERR_CLOUD_STORAGE_NO_PLAN|当前不是全时套餐。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败或内部启动失败。|
+
+### tc_iot_cloud_storage_stop_continuous_recording
+
+**停止全时录像**
+
+停止指定通道的全时录像。未在录像时也返回成功。本接口阻塞等待内部停止完成。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID，合法范围 0～4。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|已停止，或当前未在全时录像。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或云存储未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|channel_id 超出合法范围。|
+|TC_IOT_ERR_CLOUD_STORAGE_CHANNEL_NOT_FOUND|该 channel_id 无云存套餐。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败或内部停止失败。|
+
+### tc_iot_cloud_storage_start_event_recording
+
+**开始事件录像**
+
+在事件或全时套餐下开始一段事件录像。同步 SUCCESS 表示事件已受理；上报与图片上传结果通过 on_event_result 回调。本接口阻塞等待内部启动完成。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID，合法范围 0～4。|
+|event_params|tc_iot_cloud_storage_event_params_t 事件参数，不可为 NULL。picture_data 若非空，须在 on_event_result 前保持有效。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|事件录像已开始，结果通过 on_event_result 回调。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数为空或 channel_id 超出合法范围。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或云存储未初始化。|
+|TC_IOT_ERR_CLOUD_STORAGE_CHANNEL_NOT_FOUND|该 channel_id 无云存套餐。|
+|TC_IOT_ERR_CLOUD_STORAGE_NO_PLAN|当前不是事件或全时套餐。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败、event_id 重复或内部启动失败。|
+
+### tc_iot_cloud_storage_stop_event_recording
+
+**停止事件录像**
+
+结束指定 event_id 的事件录像。本接口阻塞等待内部停止完成；事件最终结果仍通过 on_event_result 回调。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID，合法范围 0～4。|
+|event_id|须与 start_event_recording 时传入的 event_id 一致。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|停止请求已完成。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或云存储未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|channel_id 超出合法范围。|
+|TC_IOT_ERR_CLOUD_STORAGE_CHANNEL_NOT_FOUND|该 channel_id 无云存套餐。|
+|TC_IOT_ERR_CLOUD_STORAGE_EVENT_NOT_FOUND|未找到对应事件。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败或内部停止失败。|
+
+### tc_iot_cloud_storage_report_event_snapshot
+
+**上报事件抓图**
+
+上报一张事件图片，不启动录像。同步 SUCCESS 表示请求已投递；结果通过 on_event_result 回调。picture_data 须在回调前保持有效。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID，合法范围 0～4。|
+|event_params|tc_iot_cloud_storage_event_params_t 事件参数，不可为 NULL。抓图场景忽略 pre_record_seconds。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|请求已投递，结果通过 on_event_result 回调。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数为空或 channel_id 超出合法范围。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或云存储未初始化。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_cloud_storage_plan_type_t
+
+**云存套餐类型**
+
+get_plan_type 与 on_plan_type_changed 使用该枚举。视频套餐优先于图片套餐。
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_CLOUD_STORAGE_PLAN_TYPE_UNKNOWN|0|尚未查询到套餐、通道不存在或参数非法。|
+|TC_IOT_CLOUD_STORAGE_PLAN_TYPE_NONE|1|通道存在但无有效云存套餐。|
+|TC_IOT_CLOUD_STORAGE_PLAN_TYPE_FULL_TIME|2|全时录像套餐。|
+|TC_IOT_CLOUD_STORAGE_PLAN_TYPE_EVENT|3|事件录像套餐。|
+|TC_IOT_CLOUD_STORAGE_PLAN_TYPE_IMAGE|4|仅图片 / 抓图套餐。|
+
+### tc_iot_cloud_storage_event_params_t
+
+**事件录像 / 抓图参数**
+
+start_event_recording 与 report_event_snapshot 共用。picture_data 由调用方持有，回调返回前不得释放。
+
+|字段|类型|描述|
+|---------|---------|---------|
+|event_id|uint32_t|事件 ID；同一通道内不可与未结束事件重复。|
+|picture_data|const uint8_t *|事件配图，可为 NULL 表示无图；非空时须在 on_event_result 前保持有效。|
+|picture_size|uint32_t|配图像素数据长度；picture_data 为 NULL 时须为 0。|
+|pre_record_seconds|uint32_t|事件录像预录秒数；仅 start_event_recording 使用，抓图忽略。|
+|extra_info|const char *|附加信息 JSON 字符串，可为 NULL。|
+
+### tc_iot_cloud_storage_event_result_t
+
+**事件处理结果**
+
+通过 on_event_result 回传；仅在回调期间有效。
+
+|字段|类型|描述|
+|---------|---------|---------|
+|event_id|uint32_t|对应请求中的事件 ID。|
+|event_report_result|tc_iot_error_e|事件上报结果；成功为 SUCCESS，失败常见为 REPORT_FAILED 或 EVENT_CANCELLED。|
+|picture_upload_result|tc_iot_error_e|图片上传结果；无图时为 SUCCESS，失败常见为 PIC_UPLOAD_FAILED 或 EVENT_CANCELLED。|
+
+### tc_iot_cloud_storage_callback_t
+
+**云存储回调表**
+
+init 时拷贝函数指针。on_init_result 必填；其余可选。
+
+|字段|类型|描述|
+|---------|---------|---------|
+|on_init_result|void(* on_init_result) (tc_iot_error_e error_code, const char *error_message)|必填；套餐查询完成或失败时回调。|
+|on_event_result|void(* on_event_result) (uint8_t channel_id, const tc_iot_cloud_storage_event_result_t *event_result)|可选；事件录像或抓图处理完成时回调。|
+|on_plan_type_changed|void(* on_plan_type_changed) (uint8_t channel_id, tc_iot_cloud_storage_plan_type_t plan_type)|可选；云端套餐变更时回调。|
+
+### on_init_result
+
+**云存储初始化结果回调**
+
+套餐查询成功时 error_code 为 SUCCESS，之后可通过 get_plan_type 读取各通道套餐。失败时常见为 PLANS_QUERY_FAILED。
+
+|参数|描述|
+|---------|---------|
+|error_code|成功时为 ​TC_IOT_ERR_SUCCESS。|
+|error_message|错误描述，可为 NULL。仅在回调期间有效。|
+
+### on_event_result
+
+**事件处理结果回调**
+
+事件录像结束或抓图上报完成后回调。收到回调后，对应 picture_data 即可释放。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID。|
+|event_result|tc_iot_cloud_storage_event_result_t 结果，仅在回调期间有效。|
+
+### on_plan_type_changed
+
+**套餐变更回调**
+
+云端套餐开通、变更或失效时回调。全时套餐失效时 SDK 会停止该通道录像；业务应按新套餐决定是否重新 start_continuous_recording。
+
+|参数|描述|
+|---------|---------|
+|channel_id|通道 ID。|
+|plan_type|tc_iot_cloud_storage_plan_type_t 变更后的套餐类型。|
+
+## AI 对话（tc_iot_aitalk.h）
+
+AI 对话（AITalk）
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用；多数操作为异步提交。 ​tc_iot_aitalk_deinit 为阻塞等待清理完成。
+>
+
+> **回调 / 通知模型**
+>
+> - observer：init 时拷贝函数指针；user_data 透传到各回调。
+> - on_receive_bot_audio 等媒体/文本回调可能来自通道线程，须尽快返回。
+> - on_error 可能不在调用方线程。
+> - tc_iot_aitalk_operation_cb（start_speak / register_contacts）： 同步 SUCCESS 则一定回调；同步失败则一定不回调 （非法 mode 例外：同步返回 INVALID_ARGUMENT 且同步调用 callback）。
+
+> **生命周期**
+>
+> tc_iot_init → ​tc_iot_login → ​tc_iot_aitalk_init → （可选）register_contacts → start_speak → send_audio / send_text → stop_speak → ​tc_iot_aitalk_deinit
+>
+
+> **业务约束**
+>
+> - 当前仅支持 ​TC_IOT_AITALK_MODE_CONTINUOUS。
+> - interrupt 仅连续模式有效；PTT 模式下经 on_error 通知 AITALK_NOT_SUPPORT，同步仍可能返回 SUCCESS（任务已投递）。
+> - init 的 codec 须为 AAC / OPUS / G722。
+> - send_audio：帧 codec 与 init 一致，或送 16-bit PCM（可由 SDK 编码）。
+> - 推荐 16 kHz 单声道；frame_duration_ms 与 codec 匹配（如 20）。
+> - 下行 bot 音频格式由通道侧决定，以 on_receive_bot_audio 的 frame 字段为准（常见为 PCM）。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_aitalk_init|初始化 AITalk。|
+|tc_iot_aitalk_deinit|反初始化；阻塞等待内部清理完成。|
+|tc_iot_aitalk_start_speak|开始对话。|
+|tc_iot_aitalk_stop_speak|停止对话（异步投递，空闲时幂等成功）。|
+|tc_iot_aitalk_send_audio|发送一帧上行音频。|
+|tc_iot_aitalk_send_text|发送文本给 LLM。|
+|tc_iot_aitalk_register_contacts|注册可供机器人呼叫的联系人。|
+|tc_iot_aitalk_interrupt|打断机器人当前播报（连续模式下有效）。|
+
+### tc_iot_aitalk_init
+
+**初始化 AITalk**
+
+须已 ​tc_iot_init。
+
+|参数|描述|
+|---------|---------|
+|init_params|初始化参数。|
+|observer|事件观察者。|
+|user_data|透传到各 observer 回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|重复初始化。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+
+### tc_iot_aitalk_deinit
+
+**反初始化；阻塞等待内部清理完成**
+
+若会话进行中，会先停止会话。
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_aitalk_start_speak
+
+**开始对话**
+
+仅支持 CONTINUOUS；会话已有效时立即成功回调。
+
+|参数|描述|
+|---------|---------|
+|mode|对话模式。|
+|callback|结果回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_aitalk_stop_speak
+
+**停止对话（异步投递，空闲时幂等成功）**
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_aitalk_send_audio
+
+**发送一帧上行音频**
+
+同步 SUCCESS 表示任务已投递；未进房时内部可能丢弃。
+
+|参数|描述|
+|---------|---------|
+|frame|音频帧。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_aitalk_send_text
+
+**发送文本给 LLM**
+
+|参数|描述|
+|---------|---------|
+|text|文本；长度不超过 1024。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_aitalk_register_contacts
+
+**注册可供机器人呼叫的联系人**
+
+count ∈ [1, TC_IOT_AITALK_MAX_CONTACT_COUNT]。 结果缓存至下次会话；callback 报告缓存结果。
+
+|参数|描述|
+|---------|---------|
+|contacts|联系人数组。|
+|contact_count|数量。|
+|callback|结果回调。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|成功。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_INVALID_ARGUMENT|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_aitalk_interrupt
+
+**打断机器人当前播报（连续模式下有效）**
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|任务已投递。|
+|TC_IOT_ERR_NOT_INITIALIZED|核心或业务模块尚未 init。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+> **注意**
+>
+> 同步 SUCCESS 仅表示任务已投递。PTT 模式不支持 interrupt，经 on_error 通知 ​TC_IOT_ERR_AITALK_NOT_SUPPORT。
+>
+
+### tc_iot_aitalk_mode_e
+
+**对话模式**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_AITALK_MODE_CONTINUOUS|0|连续对话（当前唯一可用模式）。|
+|TC_IOT_AITALK_MODE_PUSH_TO_TALK|1|按键说话；当前 start_speak 不接受该模式。|
+
+### tc_iot_aitalk_bot_state_e
+
+**机器人状态**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_AITALK_BOT_STATE_LISTENING|1|正在聆听用户语音。|
+|TC_IOT_AITALK_BOT_STATE_THINKING|2|正在思考 / 推理。|
+|TC_IOT_AITALK_BOT_STATE_SPEAKING|3|正在播报回复。|
+|TC_IOT_AITALK_BOT_STATE_INTERRUPTED|4|播报被打断。|
+|TC_IOT_AITALK_BOT_STATE_FINISHED|5|本轮对话结束。|
+
+### tc_iot_aitalk_operation_cb
+
+**异步操作结果回调（start_speak / register_contacts）**
+
+typedef void(* ​tc_iot_aitalk_operation_cb) (​tc_iot_error_e error_code, const char *error_message)
+
+### 宏定义
+
+|宏|取值|描述|
+|---------|---------|---------|
+|TC_IOT_AITALK_BOT_ID_MAX_LEN|16|bot_id 最大长度（不含结尾 '\0'）。|
+|TC_IOT_AITALK_MAX_CONTACT_COUNT|10|register_contacts 单次最多联系人数。|
+
+## 录音卡（tc_iot_audio_recorder.h）
+
+经 BLE 通道录制上行音频（当前版本本地落盘尚未启用）。
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用；init / start / stop / send_audio 为异步提交。 ​tc_iot_audio_recorder_deinit 阻塞等待内部清理完成后返回。
+>
+
+> **回调 / 通知模型**
+>
+> - observer：init 时拷贝函数指针；user_data 透传到各回调。回调须尽快返回。
+> - on_audio_recorder_start / on_audio_recorder_stop：录音会话真正开始或结束后通知。params 仅在回调期间有效。
+> - on_error：无可用输出、传输断开等异常路径通知。
+> - tc_iot_audio_recorder_operation_cb（start）：若 callback 非 NULL，同步 SUCCESS 则一定会回调；同步失败则一定不回调。
+
+> **生命周期**
+>
+> tc_iot_init → ​tc_iot_audio_recorder_init → （等待 BLE 传输就绪）→ start → send_audio → stop → ​tc_iot_audio_recorder_deinit。录音卡不依赖 AV / AITalk 初始化。
+>
+
+> **业务约束**
+>
+> - start 前须 BLE 传输就绪（当前版本本地落盘尚未启用）。
+> - 当前版本本地落盘尚未启用，start 依赖 BLE 传输就绪；未就绪时 start 回调 ​TC_IOT_ERR_NOT_CONNECTED，并通过 on_error 通知。
+> - send_audio 同步 SUCCESS 表示帧已拷贝并投递，调用返回后即可释放 frame->data。未在录音中时同步仍可能 SUCCESS，该帧会被丢弃，并通过 on_error 通知 NOT_CONNECTED。
+> - 重复 start（已在录音）会回调 FAILURE；未在录音时 stop 内部忽略。
+> - storage_path 只保存指针，不拷贝字符串；非空时须在 deinit 前保持有效。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_audio_recorder_init|初始化录音卡并注册观察者。|
+|tc_iot_audio_recorder_deinit|反初始化；阻塞等待内部清理完成。|
+|tc_iot_audio_recorder_start|开始录音。|
+|tc_iot_audio_recorder_stop|停止录音（异步投递）。|
+|tc_iot_audio_recorder_send_audio|发送一帧录音音频。|
+
+### tc_iot_audio_recorder_init
+
+**初始化录音卡并注册观察者**
+
+须先完成 SDK 初始化。内部拷贝 params 与 observer 函数指针。同步 SUCCESS 表示任务已投递，无独立 init 完成回调。
+
+|参数|描述|
+|---------|---------|
+|init_params|tc_iot_audio_recorder_params_s 初始化配置，不可为 NULL。|
+|observers|tc_iot_audio_recorder_observer_s 回调表，不可为 NULL；各回调指针均可为 NULL。|
+|user_data|自定义回调上下文，可为 NULL；须在 deinit 及回调完成前保持有效。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|初始化请求已提交。|
+|TC_IOT_ERR_INVALID_ARGUMENT|init_params 或 observers 为空。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|录音卡已初始化。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 未初始化。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足或请求提交失败。|
+
+### tc_iot_audio_recorder_deinit
+
+**反初始化；阻塞等待内部清理完成**
+
+停止会话并释放资源后返回。deinit 后 start / send_audio / stop 返回 NOT_INITIALIZED。
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|已完成反初始化。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或录音卡未初始化。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_audio_recorder_start
+
+**开始录音**
+
+请求已提交。BLE 就绪后建立录音会话；成功时触发 on_audio_recorder_start。若提供 callback，结果通过该回调返回。
+
+|参数|描述|
+|---------|---------|
+|callback|tc_iot_audio_recorder_operation_cb 开始结果回调，可为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|请求已提交；若提供 callback 则一定会回调。|
+|TC_IOT_ERR_NOT_INITIALIZED|录音卡未初始化。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_audio_recorder_stop
+
+**停止录音（异步投递）**
+
+同步 SUCCESS 表示请求已投递。无独立完成回调；会话结束后通过 on_audio_recorder_stop 通知。未在录音时内部忽略。
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|停止请求已提交。|
+|TC_IOT_ERR_NOT_INITIALIZED|录音卡未初始化。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_audio_recorder_send_audio
+
+**发送一帧录音音频**
+
+同步 SUCCESS 表示帧数据已拷贝并受理，调用返回后即可释放 frame->data。未在录音中时同步仍可能 SUCCESS，随后经 on_error 通知 NOT_CONNECTED 并丢弃该帧。
+
+|参数|描述|
+|---------|---------|
+|frame|tc_iot_audio_frame 音频帧，不可为 NULL；data 不可为 NULL，data_size 须大于 0。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|帧已拷贝并投递。未在录音中时仍可能返回此值，随后经 on_error 丢弃。|
+|TC_IOT_ERR_NOT_INITIALIZED|录音卡未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|frame / data 为空，或 data_size 为 0。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_FAILURE|请求提交失败。|
+
+### tc_iot_audio_recorder_params_s
+
+**录音卡初始化配置**
+
+init 时按值拷贝结构体；storage_path 字符串本身不拷贝。
+
+|字段|类型|描述|
+|---------|---------|---------|
+|storage_path|const char *|本地录音目录，可为 NULL；非空时须在 deinit 前保持有效。|
+
+### tc_iot_audio_recorder_observer_s
+
+**录音卡回调表**
+
+init 时拷贝函数指针。各字段均可为 NULL。
+
+|字段|类型|描述|
+|---------|---------|---------|
+|on_audio_recorder_start|void(* on_audio_recorder_start) (const char *params, void *user_data)|录音会话开始。|
+|on_audio_recorder_stop|void(* on_audio_recorder_stop) (const char *params, void *user_data)|录音会话结束。|
+|on_error|void(* on_error) (tc_iot_error_e error_code, const char *error_msg, void *user_data)|异常通知，如无可用输出或传输断开。|
+
+### tc_iot_audio_recorder_operation_cb
+
+**录音卡操作结果回调**
+
+typedef void(* ​tc_iot_audio_recorder_operation_cb) (​tc_iot_error_e error_code, const char *error_message)
+
+|参数|描述|
+|---------|---------|
+|error_code|成功时为 ​TC_IOT_ERR_SUCCESS；无输出就绪为 NOT_CONNECTED；非空闲 start 为 FAILURE。|
+|error_message|结果描述，可为 NULL。仅在回调期间有效。|
+
+### on_audio_recorder_start
+
+**录音开始回调**
+
+BLE 会话真正开始后触发。params 为 SDK 提供的状态描述，仅在回调期间有效。
+
+|参数|描述|
+|---------|---------|
+|params|状态描述字符串，仅在回调期间有效。|
+|user_data|init 传入的值。|
+
+### on_audio_recorder_stop
+
+**录音停止回调**
+
+录音会话结束后触发。params 为 SDK 提供的状态描述，仅在回调期间有效。
+
+|参数|描述|
+|---------|---------|
+|params|状态描述字符串，仅在回调期间有效。|
+|user_data|init 传入的值。|
+
+### on_error
+
+**录音卡错误回调**
+
+无可用输出、传输断开等路径触发。error_msg 仅在回调期间有效。
+
+|参数|描述|
+|---------|---------|
+|error_code|错误码，常见为 ​TC_IOT_ERR_NOT_CONNECTED 或 ​TC_IOT_ERR_FAILURE。|
+|error_msg|错误描述，可为 NULL。|
+|user_data|init 传入的值。|
+
+## OTA 升级（tc_iot_ota.h）
+
+固件下载、校验及固件刷写状态上报。
+
+> **线程模型**
+>
+> 本头文件接口可在任意线程调用。
+>
+
+> **回调 / 通知模型**
+>
+> - OTA 回调内不得执行耗时或阻塞操作；固件刷写应在独立升级线程中执行。
+> - 接口返回 `TC_IOT_ERR_SUCCESS` 表示请求已提交。下载结果通过 `on_download_firmware_result` 回调通知。
+> - 回调中的 `firmware_info`、`error_message` 和 `file_path` 仅在回调期间有效，延后使用时须复制内容。
+
+> **生命周期**
+>
+> SDK 登录成功后调用 ​tc_iot_ota_init；退出登录或释放 SDK 前调用 ​tc_iot_ota_deinit。
+>
+
+> **业务约束**
+>
+> - 运行环境须提供文件读写接口；设备没有文件系统时，可联系技术支持。
+> - 初始化时填写各模块当前运行的固件版本，模块名称不可重复。
+> - SDK 同一时间只能处理一个 OTA 任务。
+
+|函数列表|描述|
+|---------|---------|
+|tc_iot_ota_init|初始化 OTA，注册回调并上报当前固件版本。|
+|tc_iot_ota_deinit|反初始化 OTA，停止下载并释放资源。|
+|tc_iot_ota_download_firmware|发起固件下载，由 SDK 下载并校验固件。|
+|tc_iot_ota_report_upgrade_progress|上报固件刷写进度。|
+|tc_iot_ota_report_upgrade_result|上报固件刷写结果。|
+
+### tc_iot_ota_init
+
+**初始化 OTA，注册回调并上报当前固件版本**
+
+须先完成 SDK 初始化和登录。初始化后，SDK 上报各模块当前版本，并在有可用升级时通过回调通知升级任务。
+
+|参数|描述|
+|---------|---------|
+|config|tc_iot_ota_config_t 初始化配置，不可为 NULL。|
+|observer|tc_iot_ota_observer_t 回调表，不可为 NULL；`on_receive_firmware_upgrade_notify` 和 `on_download_firmware_result` 为必选回调。|
+|user_data|自定义回调上下文，可为 NULL；其指向的对象须在 OTA 反初始化和相关回调完成前保持有效。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|初始化请求已提交。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|OTA 已初始化。|
+|TC_IOT_ERR_OTA_INIT_PARAM_INVALID|配置或模块数组为空、模块数量为 0、模块信息非法或模块名称重复。|
+|TC_IOT_ERR_OTA_INIT_OBSERVER_NULL|回调表为空或必选回调未注册。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 未初始化。|
+|TC_IOT_ERR_NOT_CONNECTED|尚未登录，须先完成登录。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_ota_deinit
+
+**反初始化 OTA，停止下载并释放资源**
+
+设备退出登录或释放 SDK 前调用。反初始化会中止正在进行的下载，不触发该下载的结果回调。已下载完成的固件文件不会删除。
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|反初始化请求已提交。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或 OTA 未初始化。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_ota_download_firmware
+
+**发起固件下载，由 SDK 下载并校验固件**
+
+收到 `on_receive_firmware_upgrade_notify` 通知后，设备检查本地状态，确认满足更新条件后调用。下载进行中不得重复调用。
+
+|参数|描述|
+|---------|---------|
+|firmware_info|tc_iot_ota_firmware_info_t 目标固件信息，不可为 NULL；模块名称和目标版本须与本次升级通知一致。|
+|download_directory|固件保存目录，不可为 NULL 或空字符串；目录须可写且有足够空间。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|下载请求已提交，结果通过下载结果回调通知。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或 OTA 未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|固件信息非法，或下载目录为空。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+接口返回失败时，直接处理返回的错误码，无需等待下载结果回调。
+
+### tc_iot_ota_report_upgrade_progress
+
+**上报固件刷写进度**
+
+SDK 通知固件下载及校验成功后，设备在固件刷写过程中按实际进度调用。
+
+|参数|描述|
+|---------|---------|
+|firmware_info|tc_iot_ota_firmware_info_t 目标固件信息，不可为 NULL；须与下载成功回调中的模块名称和目标版本一致。|
+|upgrade_progress|固件刷写百分比，取值为 0～100。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|进度上报请求已提交。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或 OTA 未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|固件信息为空、模块名称或版本为空，或字符串未以 `\0` 结尾。|
+|TC_IOT_ERR_OTA_PROGRESS_TYPE_INVALID|固件刷写进度超出 0～100。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_ota_report_upgrade_result
+
+**上报固件刷写结果**
+
+须在固件下载及校验成功后调用。固件刷写完成后，设备调用此接口，上报固件刷写结果（刷写成功/失败），后台会据此更新设备升级状态。
+
+|参数|描述|
+|---------|---------|
+|firmware_info|tc_iot_ota_firmware_info_t 目标固件信息，不可为 NULL；须与下载成功回调中的模块名称和目标版本一致。|
+|result_code|固件刷写结果：`0` 为成功，`-1` 为失败。|
+|description|结果说明，需填写以 `\0` 结尾的字符串；不需要时可设为 NULL。|
+
+|返回值|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|结果上报请求已提交。|
+|TC_IOT_ERR_NOT_INITIALIZED|SDK 或 OTA 未初始化。|
+|TC_IOT_ERR_INVALID_ARGUMENT|固件信息非法，或 `result_code` 不是 `0`、`-1`。|
+|TC_IOT_ERR_OUT_OF_MEMORY|内存不足。|
+|TC_IOT_ERR_POST_TASK_FAILED|请求提交失败。|
+
+### tc_iot_ota_firmware_info_t
+
+**固件模块及版本信息**
+
+初始化配置中的版本表示当前运行的固件版本；升级通知、下载及固件刷写上报中的版本表示目标版本。
+
+|字段|类型|描述|
+|---------|---------|---------|
+|module_name|char[64]|模块名称，以 `\0` 结尾；须与后台固件模块名称一致。|
+|module_version|char[32]|固件版本，以 `\0` 结尾。|
+
+### tc_iot_ota_config_t
+
+**OTA 初始化配置**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|firmware_info|tc_iot_ota_firmware_info_t *|各模块当前固件信息数组，不可为 NULL；模块名称不可重复。|
+|firmware_info_count|uint32_t|`firmware_info` 数组中有效元素的数量，必须大于0。|
+
+### tc_iot_ota_observer_t
+
+**OTA 回调表**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|on_receive_firmware_upgrade_notify|void(* on_receive_firmware_upgrade_notify) (const ​tc_iot_ota_firmware_info_t *firmware_info, void *user_data)|必填；SDK 通知需要更新的目标模块和目标版本。|
+|on_download_firmware_progress|void(* on_download_firmware_progress) (const ​tc_iot_ota_firmware_info_t *firmware_info, uint32_t current_size, uint32_t total_size, void *user_data)|可选；SDK 通知已下载字节数和固件总字节数。|
+|on_download_firmware_result|void(* on_download_firmware_result) (const ​tc_iot_ota_firmware_info_t *firmware_info, ​tc_iot_error_e error_code, const char *error_message, const char *file_path, void *user_data)|必填；SDK 通知下载结果，成功时提供保存固件的路径。|
+
+### on_receive_firmware_upgrade_notify
+
+**固件升级通知回调**
+
+有可用升级时，SDK 通过此回调通知目标模块和目标版本。设备检查本地状态，确认满足更新条件后，调用 `tc_iot_ota_download_firmware` 发起下载。
+
+|参数|描述|
+|---------|---------|
+|firmware_info|目标模块和目标版本，仅在回调期间有效；延后处理时须复制内容。|
+|user_data|`tc_iot_ota_init` 传入的值。|
+
+### on_download_firmware_progress
+
+**固件下载进度回调**
+
+SDK 在下载过程中调用。下载百分比可按 `(uint64_t)current_size * 100 / total_size` 计算。
+
+|参数|描述|
+|---------|---------|
+|firmware_info|本次下载的目标模块和目标版本，仅在回调期间有效。|
+|current_size|已下载字节数。|
+|total_size|固件总字节数。|
+|user_data|`tc_iot_ota_init` 传入的值。|
+
+### on_download_firmware_result
+
+**固件下载结果回调**
+
+SDK 通知固件下载结果。仅在 `error_code` 为 `TC_IOT_ERR_SUCCESS` 时，复制固件信息和文件路径，交由**独立升级线程**执行固件刷写。
+
+|参数|描述|
+|---------|---------|
+|firmware_info|本次下载的目标模块和目标版本，仅在回调期间有效。|
+|error_code|固件下载结果；`TC_IOT_ERR_SUCCESS` 表示成功。|
+|error_message|失败原因；成功时为 NULL，失败时提供错误描述；仅在回调期间有效。|
+|file_path|成功时为下载并校验通过的固件文件路径；失败时为 NULL；指针仅在回调期间有效。|
+|user_data|`tc_iot_ota_init` 传入的值。|
+
+|错误码|描述|
+|---------|---------|
+|TC_IOT_ERR_SUCCESS|固件下载、文件大小和 MD5 校验成功。|
+|TC_IOT_ERR_OTA_START_FAILED|升级任务不匹配或重复发起下载；检查模块名称、目标版本及下载接口的调用时机。|
+|TC_IOT_ERR_OTA_DOWNLOAD_FAILED|下载、文件读写失败或文件大小不匹配。|
+|TC_IOT_ERR_OTA_VERIFY_FAILED|MD5 校验失败。|
+|TC_IOT_ERR_OUT_OF_MEMORY|下载过程中内存不足。|
+|其他非零错误码|下载失败，原因见 `error_message`。|
+
+## 类型定义（tc_iot_def.h 及公共结构体）
+
+音视频公共类型（AV / AITalk / 录音卡共用）
+
+> **帧所有权**
+>
+> tc_iot_*_frame 中的 data 由调用方持有。push / send 接口在返回前会拷贝 或同步消费完毕；回调中的 frame->data 仅在回调返回前有效，调用方如需 异步使用须自行拷贝。
+>
+
+> **格式约定**
+>
+> - AV 上行音频：应送 PCM，16-bit 小端交错（单声道连续样本，立体声 LRLR…）；data_size 须与 sample_rate/channels/frame_duration_ms 一致（推荐 20ms）。非 PCM 当前返回 SUCCESS 但不编码、不供云存使用。
+> - AV 下行音频：observer 收到 PCM；sample_rate/channels 透传自解码帧 （由远端编码决定；当前不按进房参数重采样）。
+> - AV 上行视频：Annex-B 裸流（H264/H265）；不支持 B 帧。 type=IDR 时须将 SPS/PPS（H265 另含 VPS）与 IDR 放在同一缓冲； 先送 IDR 再送 P 帧，否则对端可能无法起播。
+> - AITalk：init 指定编码格式；send_audio 可送同格式编码帧，或 PCM （init 为 AAC/OPUS/G722 时可由 SDK 编码）。
+
+### tc_iot_audio_codec_e
+
+**音频编码类型**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_AUDIO_CODEC_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_AUDIO_CODEC_PCM|1|PCM（AV 上行编码依赖此类型；非 PCM 仍 SUCCESS 但不编码）|
+|TC_IOT_AUDIO_CODEC_AAC|2|AAC|
+|TC_IOT_AUDIO_CODEC_OPUS|3|Opus|
+|TC_IOT_AUDIO_CODEC_G722|4|G.722|
+
+### tc_iot_audio_sample_rate_e
+
+**音频采样率（Hz）**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_AUDIO_SAMPLE_RATE_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_AUDIO_SAMPLE_RATE_8000|8000|8 kHz|
+|TC_IOT_AUDIO_SAMPLE_RATE_16000|16000|16 kHz（推荐）|
+|TC_IOT_AUDIO_SAMPLE_RATE_32000|32000|32 kHz|
+|TC_IOT_AUDIO_SAMPLE_RATE_48000|48000|48 kHz|
+
+### tc_iot_audio_channel_e
+
+**音频声道数**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_AUDIO_CHANNEL_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_AUDIO_CHANNEL_MONO|1|单声道|
+|TC_IOT_AUDIO_CHANNEL_STEREO|2|立体声（样本交错 LRLR…）|
+
+### tc_iot_video_codec_e
+
+**视频编码类型**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_VIDEO_CODEC_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_VIDEO_CODEC_H264|1|H.264 / AVC|
+|TC_IOT_VIDEO_CODEC_H265|2|H.265 / HEVC|
+|TC_IOT_VIDEO_CODEC_MJPEG|3|Motion JPEG|
+
+### tc_iot_video_frame_type_e
+
+**视频帧类型**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_VIDEO_FRAME_TYPE_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_VIDEO_FRAME_TYPE_IDR|1|关键帧 / IDR（缓冲须含 SPS/PPS，H265 另含 VPS）|
+|TC_IOT_VIDEO_FRAME_TYPE_P|2|P 帧（预测帧）|
+
+### tc_iot_video_rotation_e
+
+**视频旋转角度（度）**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_VIDEO_ROTATION_0|0|不旋转|
+|TC_IOT_VIDEO_ROTATION_90|90|顺时针 90°|
+|TC_IOT_VIDEO_ROTATION_180|180|180°|
+|TC_IOT_VIDEO_ROTATION_270|270|顺时针 270°|
+
+### tc_iot_video_quality_e
+
+**视频画质档位（呼叫 option / 监控切换 / 建视频通道时使用）**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_VIDEO_QUALITY_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_VIDEO_QUALITY_LD|1|流畅（LD）|
+|TC_IOT_VIDEO_QUALITY_SD|2|标清（SD）|
+|TC_IOT_VIDEO_QUALITY_HD|3|高清（HD）|
+|TC_IOT_VIDEO_QUALITY_FHD|4|超清（FHD）|
+
+### tc_iot_media_content_e
+
+**会话媒体内容类型**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_MEDIA_CONTENT_UNKNOWN|0|未知 / 未指定|
+|TC_IOT_MEDIA_CONTENT_AUDIO|1|仅音频|
+|TC_IOT_MEDIA_CONTENT_VIDEO|2|仅视频|
+|TC_IOT_MEDIA_CONTENT_AUDIO_VIDEO|3|音视频|
+
+### data_model_data_item_t
+
+**物模型数据项**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|data_id|char *|标识符（属性 / 事件参数 / 行为参数 ID）。|
+|data_type|data_model_data_type_t|数据类型。|
+|data_value|data_model_data_value_t|数据值；按 data_type 选用联合体字段。|
+
+### data_model_data_value_t
+
+**物模型数据值联合体（按 data_type 选用对应字段）**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|value_bool|data_model_bool_t|DATA_MODEL_DATA_TYPE_BOOL|
+|value_int|data_model_int_t|DATA_MODEL_DATA_TYPE_INT|
+|value_float|data_model_float_t|DATA_MODEL_DATA_TYPE_FLOAT|
+|value_string|data_model_string_t|DATA_MODEL_DATA_TYPE_STRING|
+|value_enum|data_model_enum_t|DATA_MODEL_DATA_TYPE_ENUM|
+|value_time|data_model_time_t|DATA_MODEL_DATA_TYPE_TIME|
+
+### tc_iot_aitalk_audio_option_s
+
+**会话音频参数**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|codec|tc_iot_audio_codec_e|会话编码；须为 AAC / OPUS / G722。|
+|sample_rate|tc_iot_audio_sample_rate_e|采样率；推荐 16000。|
+|frame_duration_ms|uint32_t|单帧时长（毫秒）；须与 codec 匹配，推荐 20。|
+
+### tc_iot_aitalk_init_params_s
+
+**AITalk 初始化参数**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|bot_id|char[TC_IOT_AITALK_BOT_ID_MAX_LEN + 1]|机器人 ID；长度 ≤ TC_IOT_AITALK_BOT_ID_MAX_LEN（数组含结尾 '\0'）。|
+|audio_option|tc_iot_aitalk_audio_option_s|会话音频参数。|
+|prompt_variables_json|const char *|可选；prompt 变量 JSON 字符串，生命周期须覆盖 init 异步过程。|
+
+### tc_iot_aitalk_observer_s
+
+**AITalk 事件观察者**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|on_receive_bot_audio|void(* on_receive_bot_audio) (const ​tc_iot_audio_frame *frame, void *user_data)|机器人下行音频；frame 仅在回调内有效。|
+|on_receive_bot_text|void(* on_receive_bot_text) (const char *text, void *user_data)|机器人下行文本。|
+|on_receive_asr_text|void(* on_receive_asr_text) (const char *text, void *user_data)|ASR 文本；仅最终结果（is_final）会回调。|
+|on_bot_state_changed|void(* on_bot_state_changed) (​tc_iot_aitalk_bot_state_e old_state, ​tc_iot_aitalk_bot_state_e new_state, void *user_data)|机器人状态变化。|
+|on_launch_call|void(* on_launch_call) (const ​tc_iot_contact_s *contact, void *user_data)|机器人发起呼叫联系人（需配合 register_contacts）。|
+|on_error|void(* on_error) (​tc_iot_error_e error_code, const char *error_msg, void *user_data)|会话或通道错误（含 AITALK_*）。|
+
+### tc_iot_audio_frame
+
+**音频帧**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|codec|tc_iot_audio_codec_e|音频编码类型。|
+|sample_rate|tc_iot_audio_sample_rate_e|采样率（Hz）。|
+|channels|tc_iot_audio_channel_e|声道数。|
+|frame_duration_ms|uint32_t|单帧时长（毫秒）；须与 data_size 匹配；推荐 20。|
+|data|uint8_t *|PCM 时为 16-bit 小端样本；调用方持有。|
+|data_size|size_t|data 字节数。|
+|pts_ms|uint64_t|呈现时间戳，毫秒；调用方保证单调。|
+
+### tc_iot_av_observer_s
+
+**AV 事件观察者；字段可为 NULL 表示不关心该事件**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|on_call_requested|void(* on_call_requested) (const ​tc_iot_contact_s *contact, ​tc_iot_call_option_t option)|App 呼入邀请。|
+|on_call_accepted|void(* on_call_accepted) (const ​tc_iot_contact_s *contact)|对端接听（呼出场景）。|
+|on_call_rejected|void(* on_call_rejected) (const ​tc_iot_contact_s *contact)|对端拒绝。|
+|on_call_timeout|void(* on_call_timeout) (const ​tc_iot_contact_s *contact)|呼叫超时。|
+|on_call_hangup|void(* on_call_hangup) (const ​tc_iot_contact_s *contact)|对端挂断或会话中止。|
+|on_monitor_begin|void(* on_monitor_begin) (int channel_id, ​tc_iot_call_option_t option)|IPC 监控：App 开始拉流。|
+|on_monitor_switch|void(* on_monitor_switch) (int channel_id, ​tc_iot_video_quality_e quality)|IPC 监控：切换画质。|
+|on_monitor_end|void(* on_monitor_end) (int channel_id)|IPC 监控：结束拉流。|
+|on_ptz_command_received|void(* on_ptz_command_received) (int channel_id, ​ptz_command_e ptz_command, int speed)|收到云台控制命令；speed 为速度档位。|
+|on_audio_frame_received|void(* on_audio_frame_received) (const ​tc_iot_audio_frame *frame)|远端音频：PCM；sample_rate/channels 透传自解码帧（随远端编码，不按进房参数重采样）；frame 仅回调内有效。|
+|on_video_frame_received|void(* on_video_frame_received) (const ​tc_iot_video_frame *frame)|远端视频；frame 仅回调内有效。|
+
+### tc_iot_call_option_s
+
+**呼叫 / 监控媒体选项**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|media_content|tc_iot_media_content_e|媒体内容类型（音频 / 视频 / 音视频）。|
+|video_quality|tc_iot_video_quality_e|视频画质档位。|
+|custom_data|char[MAX_CUSTOM_DATA_LENGTH]|自定义附带数据；数组容量为 MAX_CUSTOM_DATA_LENGTH（含结尾 '\0'）。|
+
+### tc_iot_config_s
+
+**SDK 初始化配置**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|storage_path|const char *|本地持久化目录；可为 NULL；非空时长度不超过 256。|
+|log_level|tc_iot_log_level_e|日志输出阈值，见 ​tc_iot_log_level_e。|
+|on_log|void(* on_log) (​tc_iot_log_level_e level, const char *log)|可选；为 NULL 时不向外抛日志文本。|
+|on_device_event|void(* on_device_event) (​tc_iot_device_event_type_e event_type, const void *event_data)|可选；为 NULL 时不通知在线状态。|
+|region|const char *|接入地域。国内版：""；海外版："us-east"、"europe"、"ap-bangkok"。可为 NULL（与 "" 等价）。非法取值 init 返回 INVALID_ARGUMENT。|
+
+### tc_iot_contact_s
+
+**联系人；呼叫相关 API 至少需要 user_id**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|user_id|const char *|用户 ID，必填。|
+|user_name|const char *|显示名，可选。|
+|avatar_url|const char *|头像 URL，可选。|
+
+### tc_iot_data_model_action_t
+
+**行为（下行调用 + 上行输出）**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|action_id|char *|行为 ID。|
+|token|char *|云端下发的请求 token，回复时须原样带回。|
+|timestamp|uint32_t|时间戳。|
+|action_input_data_num|int|输入参数个数。|
+|action_input_data_list|data_model_data_item_t *|输入参数列表。|
+|action_output_data_num|int|输出参数个数；在 on_receive_new_action_cb 内填写。|
+|action_output_data_list|data_model_data_item_t *|输出参数列表；在 on_receive_new_action_cb 内填写后由 SDK 回复云端。|
+
+### tc_iot_data_model_callback
+
+**物模型回调表**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|on_report_property_result_cb|void(* on_report_property_result_cb) (char *property_id, void *user_data, ​data_model_report_result_t result_code)|属性上报结果（含超时）；user_data 为 report_property 传入值。|
+|on_receive_property_changed_cb|void(* on_receive_property_changed_cb) (char *property_id, ​tc_iot_data_model_property_t *data_model_property)|云端下发属性变更。|
+|on_report_event_result_cb|void(* on_report_event_result_cb) (char *event_id, void *user_data, ​data_model_report_result_t result_code)|事件上报结果（含超时）；user_data 为 report_event 传入值。|
+|on_receive_new_action_cb|int(* on_receive_new_action_cb) (char *action_id, ​tc_iot_data_model_action_t *data_model_action)|收到行为调用。|
+
+### tc_iot_data_model_event_t
+
+**事件**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|event_id|char *|事件 ID。|
+|event_type|data_model_event_type_t|事件类型。|
+|event_data_num|int|event_data_list 元素个数。|
+|event_data_list|data_model_data_item_t *|事件参数列表。|
+
+### tc_iot_data_model_property_t
+
+**属性**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|property|data_model_data_item_t|属性数据项。|
+
+### tc_iot_device_info_s
+
+**设备三元组（login 用）**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|product_id|const char *|产品 ID，必填。|
+|device_id|const char *|设备名 / 设备 ID，必填。|
+|device_secret|const char *|设备密钥，必填。|
+
+### tc_iot_dynamic_register_param_s
+
+**动态注册参数**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|product_id|const char *|产品 ID，必填。|
+|device_id|const char *|设备名 / 设备 ID，必填。|
+|product_secret|const char *|产品密钥；长度须满足 16, 64)。|
+
+### tc_iot_video_frame
+
+**视频帧（Annex-B 裸流）**
+
+|字段|类型|描述|
+|---------|---------|---------|
+|codec|[tc_iot_video_codec_e|视频编码类型。|
+|type|tc_iot_video_frame_type_e|IDR 缓冲须含 SPS/PPS（H265 含 VPS）；P 帧不含参数集即可。|
+|rotation|tc_iot_video_rotation_e|画面旋转角度。|
+|width|uint32_t|像素宽度。|
+|height|uint32_t|像素高度。|
+|data|uint8_t *|Annex-B 裸流；调用方持有；不可为 NULL，data_size > 0。|
+|data_size|size_t|data 字节数。|
+|pts_ms|uint64_t|呈现时间戳，毫秒；调用方保证单调（热路径不做校验）。|
+
+## 错误码（tc_iot_err.h）
+
+SDK 统一错误码
+
+0 为成功，负数为失败。各模块返回值子集以对应头文件函数注释为准； 此处给出全量枚举含义。
+
+### tc_iot_error_e
+
+**SDK 统一错误码**
+
+|枚举|取值|描述|
+|---------|---------|---------|
+|TC_IOT_ERR_SUCCESS|0|成功。|
+|TC_IOT_ERR_FAILURE|-1|通用失败。|
+|TC_IOT_ERR_OUT_OF_MEMORY|-2|内存不足。|
+|TC_IOT_ERR_INVALID_ARGUMENT|-3|参数非法（空指针、非法取值等）。|
+|TC_IOT_ERR_NOT_INITIALIZED|-4|核心或业务模块尚未 init。|
+|TC_IOT_ERR_ALREADY_INITIALIZED|-5|重复初始化。|
+|TC_IOT_ERR_NOT_CONNECTED|-6|MQTT 未连接，或操作因登出被取消。|
+|TC_IOT_ERR_ALREADY_CONNECTED|-7|已处于已连接状态（如重复 login）。|
+|TC_IOT_ERR_CONNECT_FAILED|-8|MQTT / 网络连接失败（非 CONNACK 细分码）。|
+|TC_IOT_ERR_POST_TASK_FAILED|-9|请求提交失败。|
+|TC_IOT_ERR_AV_ON_IDLE|-10|AV：空闲，无对应会话（操作与当前会话冲突）。|
+|TC_IOT_ERR_AV_ON_OUTGOING|-11|AV：正在呼出。|
+|TC_IOT_ERR_AV_ON_RINGING|-12|AV：正在振铃（呼入）。|
+|TC_IOT_ERR_AV_ON_CALLING|-13|AV：已在通话中。|
+|TC_IOT_ERR_AV_ON_IPC_MONITOR|-14|AV：处于 IPC 监控会话。|
+|TC_IOT_ERR_DYNAMIC_REGISTER_BUSY|-20|动态注册：已有注册进行中（含阻塞 deinit）。|
+|TC_IOT_ERR_DYNAMIC_REGISTER_REQUEST_FAILED|-21|动态注册：请求发送或网络失败。|
+|TC_IOT_ERR_DYNAMIC_REGISTER_RESPONSE_INVALID|-22|动态注册：响应解析失败或内容非法。|
+|TC_IOT_ERR_NTP_TIME_NOT_READY|-30|NTP 尚未同步完成（ONLINE 之后仍可能短暂返回此值）。|
+|TC_IOT_ERR_CLOUD_STORAGE_CHANNEL_NOT_FOUND|-100|云存储：该 channel_id 无云存套餐。套餐类型不匹配见 -102。|
+|TC_IOT_ERR_CLOUD_STORAGE_PLANS_QUERY_FAILED|-101|云存储：套餐查询失败（经 on_init_result）。|
+|TC_IOT_ERR_CLOUD_STORAGE_NO_PLAN|-102|云存储：当前套餐不支持该操作。|
+|TC_IOT_ERR_CLOUD_STORAGE_EVENT_NOT_FOUND|-103|云存储：未找到对应事件。|
+|TC_IOT_ERR_CLOUD_STORAGE_REPORT_FAILED|-104|云存储：事件上报失败（经 on_event_result）。|
+|TC_IOT_ERR_CLOUD_STORAGE_PIC_UPLOAD_FAILED|-105|云存储：图片上传失败（经 on_event_result）。|
+|TC_IOT_ERR_CLOUD_STORAGE_EVENT_CANCELLED|-106|云存储：事件被取消（如反初始化）。|
+|TC_IOT_ERR_AITALK_NOT_SUPPORT|-200|AITalk：能力或模式不支持（亦可经 on_error）。|
+|TC_IOT_ERR_AITALK_BOT_LEAVED|-201|AITalk：机器人已离开会话。|
+|TC_IOT_ERR_AITALK_INVALID_PARAM|-202|AITalk：参数非法。|
+|TC_IOT_ERR_AITALK_INTERNAL_ERROR|-203|AITalk：内部错误。|
+|TC_IOT_ERR_AITALK_NOT_ACTIVATED|-204|AITalk：服务未开通 / 未激活。|
+|TC_IOT_ERR_AITALK_SERVICE_EXPIRED|-205|AITalk：服务已过期。|
+|TC_IOT_ERR_AITALK_ASR_ERROR|-206|AITalk：ASR 错误。|
+|TC_IOT_ERR_AITALK_TTS_ERROR|-207|AITalk：TTS 错误。|
+|TC_IOT_ERR_AITALK_LLM_ERROR|-208|AITalk：LLM 错误。|
+|TC_IOT_ERR_AITALK_START_CONVERSATION_TIMEOUT|-209|AITalk：开始对话超时。|
+|TC_IOT_ERR_CONNECT_UNACCEPTABLE_PROTOCOL_VERSION|-301|MQTT CONNACK：不接受的协议版本。|
+|TC_IOT_ERR_CONNECT_IDENTIFIER_REJECTED|-302|MQTT CONNACK：客户端标识被拒绝。|
+|TC_IOT_ERR_CONNECT_SERVER_UNAVAILABLE|-303|MQTT CONNACK：服务端不可用。|
+|TC_IOT_ERR_CONNECT_BAD_USERNAME_OR_PASSWORD|-304|MQTT CONNACK：用户名或密码错误。|
+|TC_IOT_ERR_CONNECT_NOT_AUTHORIZED|-305|MQTT CONNACK：未授权。|
+|TC_IOT_ERR_OTA_INIT_PARAM_INVALID|-400|OTA：初始化配置非法（模块数组为空、数量为 0、模块信息非法或模块名称重复）。|
+|TC_IOT_ERR_OTA_INIT_OBSERVER_NULL|-401|OTA：回调表为空或必选回调未注册。|
+|TC_IOT_ERR_OTA_START_FAILED|-402|OTA：升级任务不匹配或操作时机不正确。|
+|TC_IOT_ERR_OTA_PROGRESS_TYPE_INVALID|-403|OTA：固件刷写进度超出 0～100。|
+|TC_IOT_ERR_OTA_DOWNLOAD_FAILED|-404|OTA：固件下载或文件读写失败，或文件大小不匹配。|
+|TC_IOT_ERR_OTA_VERIFY_FAILED|-405|OTA：固件 MD5 校验失败。|
+|TC_IOT_ERR_OTA_REPORT_FAILED|-406|OTA：版本或进度、结果上报失败。|