概述
本文档描述设备端公开 C API。接口线程安全（可任意线程调用），异步回调契约为：同步返回成功则一定回调，同步返回失败则一定不回调（个别接口另有说明）。推荐生命周期：tc_iot_init → tc_iot_login → 各业务模块 init → 业务运行 → 各业务模块 deinit → tc_iot_deinit。
SDK 模块一览：
API 索引：
核心生命周期（tc_iot.h）
函数列表 | 描述 |
初始化 SDK 核心（创建 iot 消息循环并异步完成内部模块初始化）。 | |
反初始化 SDK；阻塞等待内部清理完成后返回。 | |
使用三元组登录（异步 MQTT 连接，内部可重试）。 | |
登出并清除本地凭证（异步，无独立完成回调）。 | |
动态注册设备（同一时刻仅允许一路）。 | |
读取 NTP 同步后的 UTC 毫秒时间戳。 |
物模型（tc_iot_data_model.h）
函数列表 | 描述 |
初始化物模型并订阅下行 topic。 | |
上报属性。 | |
上报事件。 | |
反初始化；同步清除单例后异步退订。 |
音视频（tc_iot_av.h）
函数列表 | 描述 |
初始化 AV 模块并注册观察者（内部拷贝 observer）。 | |
反初始化 AV；同步清除单例后异步退订信令。 | |
拉取联系人列表。 | |
发起呼出。 | |
接听呼入；仅在振铃态有效，否则回调 AV_ON_*。 | |
拒绝呼入；仅在振铃态有效。 | |
创建视频推流通道。 | |
创建全局唯一音频推流通道。 | |
销毁视频通道。 | |
销毁音频通道。 | |
推送一帧视频（调用方线程同步）。 | |
推送一帧音频（调用方线程同步）。 |
AI 对话（tc_iot_aitalk.h）
函数列表 | 描述 |
初始化 AITalk。 | |
反初始化；阻塞等待内部 teardown 完成。 | |
开始对话。 | |
停止对话（异步投递，空闲时幂等成功）。 | |
发送一帧上行音频。 | |
发送文本给 LLM。 | |
注册可供机器人呼叫的联系人。 | |
打断机器人当前播报（连续模式下有效）。 |
OTA 升级（tc_iot_ota.h）
函数列表 | 描述 |
初始化 OTA，注册回调并上报当前固件版本。 | |
反初始化 OTA，停止下载并释放资源。 | |
发起固件下载，由 SDK 下载并校验固件。 | |
上报固件刷写进度。 | |
上报固件刷写结果。 |
核心生命周期（tc_iot.h）
核心生命周期（连接与设备身份）
线程模型
本头文件接口可在任意线程调用；内部序列化到名为 "iot" 的消息循环执行。
回调 / 通知模型
on_log：日志回调线程由内部日志模块决定，可能与调用方线程不同。
on_device_event：在 iot 消息循环侧触发；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 登录。
函数列表 | 描述 |
初始化 SDK 核心（创建 iot 消息循环并异步完成内部模块初始化）。 | |
反初始化 SDK；阻塞等待内部清理完成后返回。 | |
使用三元组登录（异步 MQTT 连接，内部可重试）。 | |
登出并清除本地凭证（异步，无独立完成回调）。 | |
动态注册设备（同一时刻仅允许一路）。 | |
读取 NTP 同步后的 UTC 毫秒时间戳。 |
tc_iot_init
tc_iot_init
初始化 SDK 核心（创建 iot 消息循环并异步完成内部模块初始化）
参数 | 描述 |
config | 初始化配置，不可为 NULL。 |
返回值 | 描述 |
任务已投递。 | |
参数非法。 | |
已初始化。 | |
内存不足。 |
tc_iot_deinit
tc_iot_deinit
(void) |
反初始化 SDK；阻塞等待内部清理完成后返回
返回值 | 描述 |
成功。 | |
未初始化。 | |
动态注册进行中。 | |
内存不足。 |
tc_iot_login
tc_iot_login
使用三元组登录（异步 MQTT 连接，内部可重试）
参数 | 描述 |
device_info | 设备三元组；product_id/device_id/device_secret 必填。 |
callback | 登录结果回调；同步 SUCCESS 则一定回调，失败则不回调。 |
返回值 | 描述 |
任务已投递。 | |
参数非法。 | |
未 init。 | |
内存不足。 |
tc_iot_logout
tc_iot_logout
(void) |
登出并清除本地凭证（异步，无独立完成回调）
返回值 | 描述 |
任务已投递。 | |
未 init。 | |
内存不足。 |
tc_iot_dynamic_register
tc_iot_dynamic_register
动态注册设备（同一时刻仅允许一路）
成功后用回调中的 device_key 作为 device_secret 登录。
参数 | 描述 |
param | 注册参数。 |
callback | 注册结果回调；同步 SUCCESS 则一定回调，失败则不回调。 |
返回值 | 描述 |
任务已投递。 | |
参数非法。 | |
未 init。 | |
已有注册进行中。 | |
内存不足。 |
tc_iot_get_ntp_time
tc_iot_get_ntp_time
(uint64_t *utc_time_ms) |
读取 NTP 同步后的 UTC 毫秒时间戳
MQTT ONLINE 后异步触发同步；未完成前返回 NTP_TIME_NOT_READY。
参数 | 描述 |
utc_time_ms | 输出 UTC 毫秒时间戳，不可为 NULL。 |
返回值 | 描述 |
已同步并写入。 | |
参数非法。 | |
尚未同步完成。 |
tc_iot_log_level_e
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
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
tc_iot_login_cb
登录结果回调
参数 | 描述 |
error_code | |
error_message | 错误描述，可为 NULL。 |
tc_iot_dynamic_register_cb
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 | |
error_message | 错误描述，可为 NULL。 |
device_key | 成功时为设备密钥；须在回调返回前拷贝并写入非易失存储， 再作为后续 login 的 device_secret。 |
物模型（tc_iot_data_model.h）
物模型（属性 / 事件 / 行为）
线程模型
本头文件接口可在任意线程调用；上报与下行处理在 iot 消息循环执行。
回调 / 通知模型
on_report_*_result_cb：上报结果（含超时）；user_data 为 report 传入值。
on_receive_property_changed_cb：云端属性控制。
on_receive_new_action_cb：收到行为调用；调用方填充 action_output_data_* 后返回 0 表示成功回复，非 0 表示失败回复； 回调返回后 action 对象即释放，禁止缓存指针。
生命周期
业务约束
标量类型用 data_value 对应字段；STRING 指针在构建 JSON 期间须有效。
可一次 report 多条；每条结果经 on_report_*_result_cb 返回。
OBJECT / ARRAY 枚举已预留，当前实现未支持，请勿使用。
函数列表 | 描述 |
初始化物模型并订阅下行 topic。 | |
上报属性。 | |
上报事件。 | |
反初始化；同步清除单例后异步退订。 |
tc_iot_data_model_init
tc_iot_data_model_init
初始化物模型并订阅下行 topic
须 login 成功。
参数 | 描述 |
data_model_callback | 回调表。 |
返回值 | 描述 |
成功。 | |
重复初始化。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
投递到 iot 消息循环失败。 | |
通用失败。 |
tc_iot_data_model_report_property
tc_iot_data_model_report_property
上报属性
property_num > 0；同步 SUCCESS 表示发布任务已投递， 逐条结果经 on_report_property_result_cb 返回。
参数 | 描述 |
data_model_property | 属性数组。 |
property_num | 数量。 |
report_cb_user_data | 透传到结果回调。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
投递到 iot 消息循环失败。 | |
通用失败。 |
tc_iot_data_model_report_event
tc_iot_data_model_report_event
上报事件
语义与 report_property 相同，结果经 on_report_event_result_cb。
参数 | 描述 |
data_model_event | 事件数组。 |
event_num | 数量。 |
event_cb_user_data | 透传到结果回调。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
投递到 iot 消息循环失败。 | |
通用失败。 |
tc_iot_data_model_deinit
tc_iot_data_model_deinit
(void) |
反初始化；同步清除单例后异步退订
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 |
data_model_data_type_t
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_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_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
data_model_bool_t
布尔属性值类型
data_model_int_t
data_model_int_t
整型属性值类型
data_model_float_t
data_model_float_t
浮点属性值类型
data_model_string_t
data_model_string_t
字符串属性值类型（调用方持有指针）
data_model_enum_t
data_model_enum_t
枚举属性值类型
data_model_time_t
data_model_time_t
时间属性值类型（通常为 Unix 秒）
tc_iot_data_model_callback_t
tc_iot_data_model_callback_t
物模型回调表
音视频（tc_iot_av.h）
音视频通话 / IPC 监控
线程模型
本头文件接口可在任意线程调用；信令类操作投递到 iot 消息循环。 push_* 在调用方线程同步执行（写入 media_stream）。
回调 / 通知模型
tc_iot_av_observer_s：init 时拷贝；信令回调在 iot 消息循环触发； 音视频帧回调可能来自 TRTC 媒体线程；所有回调须尽快返回、勿阻塞。
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 只写入 media_stream， 是否进房/上云由会话侧决定。
业务约束
视频通道槽位最多 4 个，channel_id 须唯一（可为任意正整数）。
音频通道全局仅 1 路；已存在时 create 返回 NULL，须复用指针。
push_audio_frame 仅接受 16-bit PCM；非 PCM 返回 INVALID_ARGUMENT。
视频 Annex-B；IDR 须含 SPS/PPS（H265 含 VPS）；不支持 B 帧。
监控与 VOIP 互斥由状态机约束（冲突时 AV_ON_*）。
tc_iot_av_get_contacts 当前为占位实现。
函数列表 | 描述 |
初始化 AV 模块并注册观察者（内部拷贝 observer）。 | |
反初始化 AV；同步清除单例后异步退订信令。 | |
拉取联系人列表。 | |
发起呼出。 | |
接听呼入；仅在振铃态有效，否则回调 AV_ON_*。 | |
拒绝呼入；仅在振铃态有效。 | |
创建视频推流通道。 | |
创建全局唯一音频推流通道。 | |
销毁视频通道。 | |
销毁音频通道。 | |
推送一帧视频（调用方线程同步）。 | |
推送一帧音频（调用方线程同步）。 |
tc_iot_av_init
tc_iot_av_init
初始化 AV 模块并注册观察者（内部拷贝 observer）
须在 login 成功且设备身份就绪后调用。
参数 | 描述 |
observer | 事件观察者，不可为 NULL。 |
返回值 | 描述 |
成功。 | |
参数非法（空指针、非法取值等）。 | |
重复初始化。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
内存不足。 | |
投递到 iot 消息循环失败。 | |
通用失败。 |
tc_iot_av_deinit
tc_iot_av_deinit
(void) |
反初始化 AV；同步清除单例后异步退订信令
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 |
tc_iot_av_get_contacts
tc_iot_av_get_contacts
拉取联系人列表
参数 | 描述 |
cursor | 分页游标；首页传 NULL 或空串。 |
limit | 单页条数上限。 |
callback | 结果回调；占位实现下不会触发。 |
返回值 | 描述 |
占位实现固定返回成功。 |
注意
当前为占位实现：同步返回 SUCCESS 且不触发 callback。
tc_iot_av_call
tc_iot_av_call
(const tc_iot_contact_s *contact, tc_iot_call_option_t option, tc_iot_av_operation_cb callback) |
发起呼出
参数 | 描述 |
contact | 被叫联系人。 |
option | 媒体选项。 |
callback | 操作结果回调。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
投递到 iot 消息循环失败。 |
tc_iot_av_accept
tc_iot_av_accept
接听呼入；仅在振铃态有效，否则回调 AV_ON_ *
参数 | 描述 |
contact | 主叫联系人。 |
callback | 操作结果回调，不可为 NULL。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
投递到 iot 消息循环失败。 |
tc_iot_av_reject
tc_iot_av_reject
拒绝呼入；仅在振铃态有效
参数 | 描述 |
contact | 主叫联系人。 |
callback | 操作结果回调，不可为 NULL。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
投递到 iot 消息循环失败。 |
tc_iot_av_hangup
tc_iot_av_hangup
参数 | 描述 |
contact | 对端联系人。 |
callback | 操作结果回调，不可为 NULL。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
投递到 iot 消息循环失败。 |
tc_iot_create_video_channel
tc_iot_create_video_channel
创建视频推流通道
channel_id 全局唯一；同时最多 4 路。
参数 | 描述 |
channel_id | 通道 ID。 |
quality | 画质档位。 |
返回值 | 描述 |
通道句柄；失败返回 NULL（未 init / id 冲突 / 已满 / OOM）。 |
tc_iot_create_audio_channel
tc_iot_create_audio_channel
() |
tc_iot_destroy_video_channel
tc_iot_destroy_video_channel
tc_iot_destroy_audio_channel
tc_iot_destroy_audio_channel
tc_iot_push_video_frame
tc_iot_push_video_frame
推送一帧视频（调用方线程同步）
须为视频通道。格式见 tc_iot_def.h（Annex-B；IDR 含参数集）。
参数 | 描述 |
av_channel | 视频通道。 |
frame | 视频帧。 |
返回值 | 描述 |
成功。 | |
参数非法（空指针、非法取值等）。 |
tc_iot_push_audio_frame
tc_iot_push_audio_frame
推送一帧音频（调用方线程同步）
须为音频通道；仅接受 16-bit PCM。 同一通道生命周期内 sample_rate / channels 应保持稳定。
参数 | 描述 |
av_channel | 音频通道。 |
frame | 音频帧。 |
返回值 | 描述 |
成功。 | |
参数非法（空指针、非法取值等）。 |
ptz_command_e
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
tc_iot_av_channel_t
不透明 AV 推流通道句柄
tc_iot_call_option_t
tc_iot_call_option_t
呼叫 / 监控媒体选项
tc_iot_av_operation_cb
tc_iot_av_operation_cb
呼叫操作完成回调（MQTT puback / 状态冲突结果）
参数 | 描述 |
error_code | 结果码。 |
error_message | 错误描述，可为 NULL。 |
tc_iot_av_contacts_cb
tc_iot_av_contacts_cb
联系人列表回调（当前 get_contacts 为占位，不会触发）
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)
宏定义
宏 | 取值 | 描述 |
MAX_CUSTOM_DATA_LENGTH | 20 | call_option.custom_data 最大字节数（含结尾 '\\0' 由调用方自行保证）。 |
AI 对话（tc_iot_aitalk.h）
AI 对话（AITalk）
线程模型
回调 / 通知模型
observer：init 时保存；user_data 透传到各回调。
on_receive_bot_audio 等媒体/文本回调可能来自通道线程，须尽快返回。
on_error 尽量投递到 iot 消息循环。
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。
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）。
函数列表 | 描述 |
初始化 AITalk。 | |
反初始化；阻塞等待内部 teardown 完成。 | |
开始对话。 | |
停止对话（异步投递，空闲时幂等成功）。 | |
发送一帧上行音频。 | |
发送文本给 LLM。 | |
注册可供机器人呼叫的联系人。 | |
打断机器人当前播报（连续模式下有效）。 |
tc_iot_aitalk_init
tc_iot_aitalk_init
(const tc_iot_aitalk_init_params_s *init_params, const tc_iot_aitalk_observer_s *observer, void *user_data) |
初始化 AITalk
参数 | 描述 |
init_params | 初始化参数。 |
observer | 事件观察者。 |
user_data | 透传到各 observer 回调。 |
返回值 | 描述 |
成功。 | |
参数非法（空指针、非法取值等）。 | |
重复初始化。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
内存不足。 |
tc_iot_aitalk_deinit
tc_iot_aitalk_deinit
(void) |
反初始化；阻塞等待内部 teardown 完成
若处于 Starting/Running，会先停止会话。
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 |
tc_iot_aitalk_start_speak
tc_iot_aitalk_start_speak
开始对话
仅支持 CONTINUOUS；会话已有效时立即成功回调。
参数 | 描述 |
mode | 对话模式。 |
callback | 结果回调。 |
返回值 | 描述 |
成功。 | |
参数非法（空指针、非法取值等）。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
内存不足。 | |
投递到 iot 消息循环失败。 | |
通用失败。 |
tc_iot_aitalk_stop_speak
tc_iot_aitalk_stop_speak
(void) |
停止对话（异步投递，空闲时幂等成功）
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
内存不足。 | |
通用失败。 |
tc_iot_aitalk_send_audio
tc_iot_aitalk_send_audio
发送一帧上行音频
同步 SUCCESS 表示任务已投递；未进房时内部可能丢弃。
参数 | 描述 |
frame | 音频帧。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
通用失败。 |
tc_iot_aitalk_send_text
tc_iot_aitalk_send_text
(const char *text) |
发送文本给 LLM
参数 | 描述 |
text | 文本；长度上限见实现（当前 1024）。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
通用失败。 |
tc_iot_aitalk_register_contacts
tc_iot_aitalk_register_contacts
注册可供机器人呼叫的联系人
count ∈ [1, TC_IOT_AITALK_MAX_CONTACT_COUNT]。 结果缓存至下次会话；callback 报告缓存结果。
参数 | 描述 |
contacts | 联系人数组。 |
contact_count | 数量。 |
callback | 结果回调。 |
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
参数非法（空指针、非法取值等）。 | |
内存不足。 | |
通用失败。 |
tc_iot_aitalk_interrupt
tc_iot_aitalk_interrupt
(void) |
打断机器人当前播报（连续模式下有效）
返回值 | 描述 |
成功。 | |
核心或业务模块尚未 init / 内部 impl 未就绪。 | |
通用失败。 | |
TC_IOT_ERR_AITALK_* | TC_IOT_ERR_AITALK_NOT_SUPPORT：AITalk：能力或模式不支持（亦可经 on_error）。 TC_IOT_ERR_AITALK_BOT_LEAVED：AITalk：机器人已离开会话。 TC_IOT_ERR_AITALK_INVALID_PARAM：AITalk：参数非法。 TC_IOT_ERR_AITALK_INTERNAL_ERROR：AITalk：内部错误。 TC_IOT_ERR_AITALK_NOT_ACTIVATED：AITalk：服务未开通 / 未激活。 TC_IOT_ERR_AITALK_SERVICE_EXPIRED：AITalk：服务已过期。 TC_IOT_ERR_AITALK_ASR_ERROR：AITalk：ASR 错误。 TC_IOT_ERR_AITALK_TTS_ERROR：AITalk：TTS 错误。 TC_IOT_ERR_AITALK_LLM_ERROR：AITalk：LLM 错误。 |
tc_iot_aitalk_mode_e
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_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
tc_iot_aitalk_operation_cb
异步操作结果回调（start_speak / register_contacts）
宏定义
宏 | 取值 | 描述 |
TC_IOT_AITALK_BOT_ID_MAX_LEN | 16 | bot_id 最大长度（不含结尾 '\\0'）。 |
TC_IOT_AITALK_MAX_CONTACT_COUNT | 10 | register_contacts 单次最多联系人数。 |
OTA 升级（tc_iot_ota.h）
固件下载、校验及固件刷写状态上报。
线程模型
本头文件接口可在任意线程调用；操作投递到 iot 消息循环执行。
回调 / 通知模型
OTA 回调在 iot 消息循环执行，回调内不得执行耗时或阻塞操作；固件刷写应在独立升级线程中执行。
接口返回
TC_IOT_ERR_SUCCESS 表示请求已提交。下载结果通过 on_download_firmware_result 回调通知。回调中的
firmware_info、error_message 和 file_path 仅在回调期间有效，延后使用时须复制内容。生命周期
业务约束
运行环境须提供文件读写接口；设备没有文件系统时，可联系技术支持。
初始化时填写各模块当前运行的固件版本，模块名称不可重复。
SDK 同一时间只能处理一个 OTA 任务。
函数列表 | 描述 |
初始化 OTA，注册回调并上报当前固件版本。 | |
反初始化 OTA，停止下载并释放资源。 | |
发起固件下载，由 SDK 下载并校验固件。 | |
上报固件刷写进度。 | |
上报固件刷写结果。 |
tc_iot_ota_init
tc_iot_ota_init
tc_iot_error_e tc_iot_ota_init | (const tc_iot_ota_config_t *config, const tc_iot_ota_observer_t *observer, void *user_data) |
初始化 OTA，注册回调并上报当前固件版本
须先完成 SDK 初始化和登录。初始化后，SDK 上报各模块当前版本，并在有可用升级时通过回调通知升级任务。
参数 | 描述 |
config | |
observer | tc_iot_ota_observer_t 回调表，不可为 NULL； on_receive_firmware_upgrade_notify 和 on_download_firmware_result 为必选回调。 |
user_data | 自定义回调上下文，可为 NULL；其指向的对象须在 OTA 反初始化和相关回调完成前保持有效。 |
返回值 | 描述 |
初始化请求已提交。 | |
OTA 已初始化。 | |
配置或模块数组为空、模块数量为 0、模块信息非法或模块名称重复。 | |
回调表为空或必选回调未注册。 | |
SDK 未初始化。 | |
尚未登录，须先完成登录。 | |
内存不足。 | |
请求提交失败。 |
tc_iot_ota_deinit
tc_iot_ota_deinit
tc_iot_error_e tc_iot_ota_deinit | (void) |
反初始化 OTA，停止下载并释放资源
设备退出登录或释放 SDK 前调用。反初始化会中止正在进行的下载，不触发该下载的结果回调。已下载完成的固件文件不会删除。
返回值 | 描述 |
反初始化请求已提交。 | |
SDK 或 OTA 未初始化。 | |
请求提交失败。 |
tc_iot_ota_download_firmware
tc_iot_ota_download_firmware
tc_iot_error_e tc_iot_ota_download_firmware | (const tc_iot_ota_firmware_info_t *firmware_info, const char *download_directory) |
发起固件下载，由 SDK 下载并校验固件
收到
on_receive_firmware_upgrade_notify 通知后，设备检查本地状态，确认满足更新条件后调用。下载进行中不得重复调用。参数 | 描述 |
firmware_info | |
download_directory | 固件保存目录，不可为 NULL 或空字符串；目录须可写且有足够空间。 |
返回值 | 描述 |
下载请求已提交，结果通过下载结果回调通知。 | |
SDK 或 OTA 未初始化。 | |
固件信息非法，或下载目录为空。 | |
内存不足。 | |
请求提交失败。 |
接口返回失败时，直接处理返回的错误码，无需等待下载结果回调。
tc_iot_ota_report_upgrade_progress
tc_iot_ota_report_upgrade_progress
tc_iot_error_e tc_iot_ota_report_upgrade_progress | (const tc_iot_ota_firmware_info_t *firmware_info, uint32_t upgrade_progress) |
上报固件刷写进度
SDK 通知固件下载及校验成功后，设备在固件刷写过程中按实际进度调用。
参数 | 描述 |
firmware_info | |
upgrade_progress | 固件刷写百分比，取值为 0～100。 |
返回值 | 描述 |
进度上报请求已提交。 | |
SDK 或 OTA 未初始化。 | |
固件信息为空、模块名称或版本为空，或字符串未以 \\0 结尾。 | |
固件刷写进度超出 0～100。 | |
内存不足。 | |
请求提交失败。 |
tc_iot_ota_report_upgrade_result
tc_iot_ota_report_upgrade_result
tc_iot_error_e tc_iot_ota_report_upgrade_result | (const tc_iot_ota_firmware_info_t *firmware_info, int32_t result_code, const char *description) |
上报固件刷写结果
须在固件下载及校验成功后调用。固件刷写完成后，设备调用此接口，上报固件刷写结果（刷写成功/失败），后台会据此更新设备升级状态。
参数 | 描述 |
firmware_info | |
result_code | 固件刷写结果： 0 为成功，-1 为失败。 |
description | 结果说明，需填写以 \\0 结尾的字符串；不需要时可设为 NULL。 |
返回值 | 描述 |
结果上报请求已提交。 | |
SDK 或 OTA 未初始化。 | |
固件信息非法，或 result_code 不是 0、-1。 | |
内存不足。 | |
请求提交失败。 |
tc_iot_ota_firmware_info_t
tc_iot_ota_firmware_info_t
固件模块及版本信息
初始化配置中的版本表示当前运行的固件版本；升级通知、下载及固件刷写上报中的版本表示目标版本。
字段 | 类型 | 描述 |
module_name | char[64] | 模块名称，以 \\0 结尾；须与后台固件模块名称一致。 |
module_version | char[32] | 固件版本，以 \\0 结尾。 |
tc_iot_ota_config_t
tc_iot_ota_config_t
OTA 初始化配置
字段 | 类型 | 描述 |
firmware_info | 各模块当前固件信息数组，不可为 NULL；模块名称不可重复。 | |
firmware_info_count | uint32_t | firmware_info 数组中有效元素的数量，必须大于0。 |
tc_iot_ota_observer_t
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
on_receive_firmware_upgrade_notify
固件升级通知回调
有可用升级时，SDK 通过此回调通知目标模块和目标版本。设备检查本地状态，确认满足更新条件后，调用
tc_iot_ota_download_firmware 发起下载。参数 | 描述 |
firmware_info | 目标模块和目标版本，仅在回调期间有效；延后处理时须复制内容。 |
user_data | tc_iot_ota_init 传入的值。 |
on_download_firmware_progress
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
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 传入的值。 |
错误码 | 描述 |
固件下载、文件大小和 MD5 校验成功。 | |
升级任务不匹配或重复发起下载；检查模块名称、目标版本及下载接口的调用时机。 | |
下载、文件读写失败或文件大小不匹配。 | |
MD5 校验失败。 | |
下载过程中内存不足。 | |
其他非零错误码 | 下载失败，原因见 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）。SDK 内部可再编码为 AAC 供 TRTC。
AV 下行音频：observer 收到 PCM；sample_rate/channels 透传自解码帧 （由远端编码决定；当前未按进房 obtain 参数重采样）。
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_e
音频编码类型
枚举 | 取值 | 描述 |
TC_IOT_AUDIO_CODEC_UNKNOWN | 0 | 未知 / 未指定 |
TC_IOT_AUDIO_CODEC_PCM | 1 | PCM（AV push 仅接受此类型） |
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
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_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_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_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_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
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_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_model_data_item_t
物模型数据项
字段 | 类型 | 描述 |
data_id | char * | 标识符（属性 / 事件参数 / 行为参数 ID）。 |
data_type | 数据类型。 | |
data_value | 数据值；按 data_type 选用联合体字段。 |
data_model_data_value_t
data_model_data_value_t
物模型数据值联合体（按 data_type 选用对应字段）
字段 | 类型 | 描述 |
value_bool | ||
value_int | ||
value_float | ||
value_string | ||
value_enum | ||
value_time |
tc_iot_aitalk_audio_option_s
tc_iot_aitalk_audio_option_s
会话音频参数
字段 | 类型 | 描述 |
codec | 会话编码；须为 AAC / OPUS / G722。 | |
sample_rate | 采样率；推荐 16000。 | |
frame_duration_ms | uint32_t | 单帧时长（毫秒）；须与 codec 匹配，推荐 20。 |
tc_iot_aitalk_init_params_s
tc_iot_aitalk_init_params_s
AITalk 初始化参数
字段 | 类型 | 描述 |
bot_id | char | 机器人 ID；长度 ≤ TC_IOT_AITALK_BOT_ID_MAX_LEN。 |
audio_option | 会话音频参数。 | |
prompt_variables_json | const char * | 可选；prompt 变量 JSON 字符串，生命周期须覆盖 init 异步过程。 |
tc_iot_aitalk_observer_s
tc_iot_aitalk_observer_s
AITalk 事件观察者
字段 | 类型 | 描述 |
on_receive_bot_audio | 机器人下行音频；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 | 机器人发起呼叫联系人（需配合 register_contacts）。 | |
on_error | 会话或通道错误（含 AITALK_*）。 |
tc_iot_audio_frame
tc_iot_audio_frame
音频帧
字段 | 类型 | 描述 |
codec | 音频编码类型。 | |
sample_rate | 采样率（Hz）。 | |
channels | 声道数。 | |
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
tc_iot_av_observer_s
AV 事件观察者；字段可为 NULL 表示不关心该事件
字段 | 类型 | 描述 |
on_call_requested | App 呼入邀请。 | |
on_call_accepted | 对端接听（呼出场景）。 | |
on_call_rejected | 对端拒绝。 | |
on_call_timeout | 呼叫超时。 | |
on_call_hangup | 对端挂断或会话中止。 | |
on_monitor_begin | IPC 监控：App 开始拉流。 | |
on_monitor_switch | IPC 监控：切换画质。 | |
on_monitor_end | void(* on_monitor_end) (int channel_id) | IPC 监控：结束拉流。 |
on_ptz_command_received | 收到云台控制命令；speed 为速度档位。 | |
on_audio_frame_received | 远端音频：PCM；sample_rate/channels 透传自解码帧（随远端编码， 未按进房 obtain 重采样）；frame 仅回调内有效。 | |
on_video_frame_received | 远端视频；frame 仅回调内有效。 |
tc_iot_call_option_s
tc_iot_call_option_s
呼叫 / 监控媒体选项
字段 | 类型 | 描述 |
media_content | 媒体内容类型（音频 / 视频 / 音视频）。 | |
video_quality | 视频画质档位。 | |
custom_data | char | 自定义附带数据；长度受 MAX_CUSTOM_DATA_LENGTH 约束。 |
tc_iot_config_s
tc_iot_config_s
SDK 初始化配置
字段 | 类型 | 描述 |
storage_path | const char * | 本地持久化目录；可为 NULL；非空时长度须合法（实现侧上限约 256）。 |
log_level | ||
on_log | 可选；为 NULL 时不向外抛日志文本。 | |
on_device_event | 可选；为 NULL 时不通知在线状态。 |
tc_iot_contact_s
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
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 | 输入参数列表。 | |
action_output_data_num | int | 输出参数个数；在 on_receive_new_action_cb 内填写。 |
action_output_data_list | 输出参数列表；在 on_receive_new_action_cb 内填写后由 SDK 回复云端。 |
tc_iot_data_model_callback
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 | 收到行为调用。 |
tc_iot_data_model_event_t
tc_iot_data_model_event_t
事件
字段 | 类型 | 描述 |
event_id | char * | 事件 ID。 |
event_type | 事件类型。 | |
event_data_num | int | event_data_list 元素个数。 |
event_data_list | 事件参数列表。 |
tc_iot_data_model_property_t
tc_iot_data_model_property_t
属性
字段 | 类型 | 描述 |
property | 属性数据项。 |
tc_iot_device_info_s
tc_iot_device_info_s
设备三元组（login 用）
字段 | 类型 | 描述 |
product_id | const char * | 产品 ID，必填。 |
device_id | const char * | 设备名 / 设备 ID，必填。 |
device_secret | const char * | 设备密钥，必填。 |
region | const char * | 地域字符串（如 "ap-guangzhou"）；校验存在，当前登录链路未使用。 |
tc_iot_dynamic_register_param_s
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
tc_iot_video_frame
视频帧（Annex-B 裸流）
字段 | 类型 | 描述 |
codec | 视频编码类型。 | |
type | IDR 缓冲须含 SPS/PPS（H265 含 VPS）；P 帧不含参数集即可。 | |
rotation | 画面旋转角度。 | |
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
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 / 内部 impl 未就绪。 |
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 | 投递到 iot 消息循环失败。 |
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_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_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：版本或进度、结果上报失败。 |
