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

package/resource/knowledge/iot/device/ai-voice-chat/advanced-features/smart-device-control.md

@@ -0,0 +1,721 @@
+---
+product: iot
+framework:
+  - '*'
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+借助智能体的**工具配置**能力，结合 [腾讯云物联网开发平台](https://cloud.tencent.com/document/product/1081/34726) 的 [物模型通信](https://cloud.tencent.com/document/product/1081/135031) 能力，可以实现设备的智能控制。
+
+本文以电量查询、音量控制两个案例，分别介绍如何获取设备自身属性（电量查询）与修改设备属性（音量控制）。如果有这方面的业务需求，可以按照我们提供的实践案例来进行定制改造。
+
+## 前置条件
+1. 已经熟悉 自定义智能体 的相关配置和使用。
+
+2. 已经熟悉 [物模型通信](https://cloud.tencent.com/document/product/1081/135031) 并跑通完整 Demo。
+
+3. 已经跑通 AI 对话 [接入指引](https://cloud.tencent.com/document/product/1081/137894)，能正常对话。
+
+## 实践案例
+
+### 案例一：查询设备电量
+1. 在腾讯云物联网开发平台 [控制台](https://console.cloud.tencent.com/iotexplorer/v2) 产品详情页的功能定义页面，单击**新增功能**，定义一个电量查询行为。
+
+2. 在控制台 **TWeTalk 智能体配置**页面，进入对应智能体的**工具配置**，单击**创建工具**：
+
+   |配置项|说明|
+   |---------|---------|
+   |工具类型|默认选择 **IoT 工具**。|
+   |工具名称|和定义行为中的标识符保持一致，当前为：**get_battery**。|
+   |工具描述|和定义行为中的描述保持一致，当前为：**获取设备当前电量**。|
+   |工具参数|当前只是获取设备属性，不涉及控制下发，该项留空，后续在控制音量案例中介绍。|
+   |输出参数|行为执行结果的数据项：**battery**（整型，当前电量百分比），需与物模型定义的输出参数保持一致。|
+
+3. 在 [AI 对话的设备端 SDK](https://cloud.tencent.com/document/product/1081/137894) 集成 [物模型通信](https://cloud.tencent.com/document/product/1081/135031) 能力：
+
+   ``` c
+   #include <stdbool.h>
+   #include <stdlib.h>
+   #include <string.h>
+
+   #include "tc_iot.h"
+   #include "tc_iot_aitalk.h"
+   #include "tc_iot_data_model.h"
+
+   /* 登录和开始对话均为异步操作，回调中记录结果，主流程据此继续或退出。 */
+   static volatile bool s_login_done = false;
+   static volatile bool s_start_done = false;
+   static volatile bool s_aitalk_error = false;
+   static volatile bool s_data_model_done = false;
+   static tc_iot_error_e s_login_result = TC_IOT_ERR_SUCCESS;
+   static tc_iot_error_e s_start_result = TC_IOT_ERR_SUCCESS;
+
+   static data_model_data_item_t s_action_output[1];
+
+   static void on_login(tc_iot_error_e error_code, const char *error_message) {
+       s_login_result = error_code;
+       s_login_done = true;
+       // 登录失败时，可在这里记录 error_message 并通知上层业务。
+   }
+
+   static void on_start_speak(tc_iot_error_e error_code, const char *error_message) {
+       s_start_result = error_code;
+       s_start_done = true;
+       // 开始对话失败时，可在这里记录 error_message 并通知上层业务。
+   }
+
+   static void on_receive_bot_audio(const tc_iot_audio_frame *frame, void *user_data) {
+       (void)user_data;
+       if (!frame || !frame->data || frame->data_size == 0) {
+           return;
+       }
+       // 这里收到的音频是经过解码后的 PCM 音频
+       // 将 frame->data 推送到具体的音频设备播放。
+       // 例如：调用芯片平台的扬声器播放、PCM 输出或音频框架接口。
+   }
+
+   static void on_receive_bot_text(const char *text, void *user_data) {
+       (void)user_data;
+       if (!text) {
+           return;
+       }
+       // 将机器人回复文本显示到屏幕，或上传到您的业务服务。
+   }
+
+   static void on_receive_asr_text(const char *text, void *user_data) {
+       (void)user_data;
+       if (!text) {
+           return;
+       }
+       // 将用户语音识别结果显示到屏幕，或用于本地业务处理。
+   }
+
+   static void on_bot_state_changed(tc_iot_aitalk_bot_state_e old_state,
+                                    tc_iot_aitalk_bot_state_e new_state,
+                                    void *user_data) {
+       (void)old_state;
+       (void)user_data;
+       // 根据 new_state 更新设备指示灯、屏幕或其他交互状态。
+   }
+
+   static void on_aitalk_error(tc_iot_error_e error_code, const char *error_message,
+                               void *user_data) {
+       (void)user_data;
+       s_aitalk_error = true;
+       // 记录 error_code 和 error_message，并停止或重试业务流程。
+   }
+
+   /*
+    * 在平台麦克风的数据回调中调用本函数。
+    * data、size、codec 和 pts_ms 均来自当前平台的音频采集结果。
+    */
+   static void on_mic_captured(const uint8_t *data, uint32_t size,
+                               tc_iot_audio_codec_e codec, uint64_t pts_ms,
+                               void *user_data) {
+       (void)user_data;
+       if (!data || size == 0) {
+           return;
+       }
+
+       tc_iot_audio_frame frame = {0};
+       frame.codec = codec;
+       frame.sample_rate = TC_IOT_AUDIO_SAMPLE_RATE_16000;
+       frame.channels = TC_IOT_AUDIO_CHANNEL_MONO;
+       frame.frame_duration_ms = 20;
+       frame.data = (uint8_t *)data;
+       frame.data_size = size;
+       frame.pts_ms = pts_ms;
+
+       tc_iot_error_e rc = tc_iot_aitalk_send_audio(&frame);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           // 记录发送失败原因；必要时停止采集或触发重连。
+       }
+   }
+
+   // ==================== 物模型通信 ====================
+   // 属性上报结果回调
+   static void on_report_property_result_cb(char *property_id, void *user_data,
+                                            data_model_report_result_t result_code) {
+       (void)user_data;
+       printf("[demo] report property result: id=%s, code=%d\n",
+              property_id ? property_id : "(null)", (int)result_code);
+   }
+
+   // 事件上报结果回调
+   static void on_report_event_result_cb(char *event_id, void *user_data,
+                                         data_model_report_result_t result_code) {
+       (void)user_data;
+       printf("[demo] report event result: id=%s, code=%d\n",
+              event_id ? event_id : "(null)", (int)result_code);
+   }
+
+   // 云端修改属性
+   static void on_receive_property_changed_cb(char *property_id,
+                                              tc_iot_data_model_property_t *data_model_property) {
+       if (!property_id || !data_model_property) {
+           return;
+       }
+       data_model_data_item_t *item = &data_model_property->property;
+       printf("[demo] property changed: id=%s, type=%d\n", item->data_id, (int)item->data_type);
+       // 按 item->data_type 解析 item->data_value 并更新本地状态 ...
+   }
+
+   // 云端下发行为
+   static int on_receive_new_action_cb(char *action_id,
+                                       tc_iot_data_model_action_t *data_model_action) {
+       if (!action_id || !data_model_action) {
+           return -1;
+       }
+       printf("[demo] receive new action: id=%s, input_num=%u\n", action_id,
+              (unsigned)data_model_action->action_input_data_num);
+       // 查询电量
+       if (!strcmp(action_id, "get_battery")) {
+           // 模拟电量，真实业务请接入真实电量百分比
+           static int battery = 58;
+           s_action_output[0].data_id = "battery";
+           s_action_output[0].data_type = DATA_MODEL_DATA_TYPE_INT;
+           s_action_output[0].data_value.value_int = battery--;
+           // 先填好数据再设置数量，避免出现数量与列表不一致的中间状态
+           data_model_action->action_output_data_num = 1;
+           data_model_action->action_output_data_list = s_action_output;
+           printf("[demo] current battery: %d\n", s_action_output[0].data_value.value_int);
+       }
+       return 0;
+   }
+
+   int main(void) {
+       bool sdk_inited = false;
+       bool aitalk_inited = false;
+       bool speak_started = false;
+       bool conversation_completed = false;
+       tc_iot_error_e rc;
+
+       // 1. 配置并初始化 SDK。
+       tc_iot_config_s sdk_config = {0};
+       sdk_config.storage_path = "./";
+       sdk_config.log_level = TC_IOT_LOG_LEVEL_INFO;
+       rc = tc_iot_init(&sdk_config);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       sdk_inited = true;
+
+       // 2. 从安全配置中读取设备三元组并登录平台。
+       tc_iot_device_info_s device_info = {0};
+       device_info.product_id = get_product_id();
+       device_info.device_id = get_device_name();
+       device_info.device_secret = get_device_secret();
+       device_info.region = "ap-guangzhou";
+
+       s_login_done = false;
+       rc = tc_iot_login(&device_info, on_login);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+
+       // 等待 on_login 回调或超时；休眠接口请替换为具体平台实现。
+       wait_until(&s_login_done, 30000);
+       if (!s_login_done || s_login_result != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+
+       // 3. 初始化物模型
+       tc_iot_data_model_callback_t callback = {
+           .on_report_property_result_cb = on_report_property_result_cb,
+           .on_receive_property_changed_cb = on_receive_property_changed_cb,
+           .on_report_event_result_cb = on_report_event_result_cb,
+           .on_receive_new_action_cb = on_receive_new_action_cb,
+       };
+       rc = tc_iot_data_model_init(callback);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       s_data_model_done = true;
+
+       // 4. 注册 AI 对话事件回调并初始化模块。
+       tc_iot_aitalk_observer_s observer = {0};
+       observer.on_receive_bot_audio = on_receive_bot_audio;
+       observer.on_receive_bot_text = on_receive_bot_text;
+       observer.on_receive_asr_text = on_receive_asr_text;
+       observer.on_bot_state_changed = on_bot_state_changed;
+       observer.on_error = on_aitalk_error;
+
+       tc_iot_aitalk_init_params_s init_params = {0};
+       // 根据实际情况配置 agent-id prompt_variables_json
+       // 根据实际采集参数设置编码、采样率和单帧时长。
+       init_params.audio_option = get_platform_audio_option();
+       rc = tc_iot_aitalk_init(&init_params, &observer, NULL);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       aitalk_inited = true;
+
+       // 5. 如需机器人触发联系人呼叫，在开始对话前注册联系人。
+       // tc_iot_aitalk_register_contacts(contacts, contact_count, on_register_contacts);
+
+       // 6. 初始化具体平台的麦克风和扬声器。
+       // 麦克风采集到一帧音频后，调用 on_mic_captured() 发送给 AI 对话服务。
+
+       // 7. 异步开始持续对话，成功后再启动麦克风采集。
+       s_start_done = false;
+       rc = tc_iot_aitalk_start_speak(TC_IOT_AITALK_MODE_CONTINUOUS, on_start_speak);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       wait_until(&s_start_done, 30000);
+       if (!s_start_done || s_start_result != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       speak_started = true;
+
+       // 启动具体平台的麦克风采集流程。
+       // 采集线程或回调中不要阻塞过久，按帧调用 on_mic_captured()。
+
+       while (!s_aitalk_error && !is_exit_requested()) {
+           // 使用具体平台的休眠、事件循环或任务调度机制。
+       }
+       conversation_completed = !s_aitalk_error;
+
+   cleanup:
+       // 先停止具体平台的麦克风采集和扬声器播放。
+       if (speak_started) {
+           tc_iot_aitalk_stop_speak();
+       }
+       if (aitalk_inited) {
+           tc_iot_aitalk_deinit();
+       }
+       if (s_data_model_done) {
+           tc_iot_data_model_deinit();
+       }
+       if (sdk_inited) {
+           tc_iot_deinit();
+       }
+       return conversation_completed ? 0 : 1;
+   }
+   ```
+4. 设备端运行，然后说：“查询当前电量”，观察是否生效。
+
+   ``` bash
+   [aitalk] asr: 查一下现在电量是多少
+   [aitalk] bot_state changed: 1 -> 2
+   [IOT_SDK] 2026-09-15 17:11:23.311 I 37213-1799483392|data_model_action.c:71|create_data_model_action_from_json_string|-action parsed: action_id=get_battery, token=v2528563118rKTQu::bb0adb2e-f960-43a9-b15e-e9c945b7458f, input_data_num=0
+   [aitalk] [demo] receive new action: id=get_battery, input_num=0
+
+   [aitalk] [demo] current battery: 58
+   [IOT_SDK] 2026-09-15 17:11:23.311 I 37213-1799483392|data_model_action.c:202|data_model_on_receive_action_message|-action callback executed, action_id=get_battery, result=0
+   [IOT_SDK] 2026-09-15 17:11:23.348 I 37213-1799483392|mqtt_connection.c:1022|_mqtt_on_puback_packet_received|-puback received: packet_id=10 topic=$thing/up/action/YDBF3QFF7F/test_002
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 小明，
+   [aitalk] bot: 现在电量是百分之五十八。
+   ```
+
+### 案例二：控制设备音量
+1. 在腾讯云物联网开发平台 [控制台](https://console.cloud.tencent.com/iotexplorer/v2) 产品详情页的功能定义页面，单击**新增功能**，定义一个音量控制行为。
+
+2. 在控制台 **TWeTalk 智能体配置**页面，进入对应智能体的**工具配置**，单击**创建工具**：
+
+| 配置项 | 说明 |  |
+| --- | --- | --- |
+| 工具类型 | 默认选择 <strong>IoT 工具</strong>。 |  |
+| 工具名称 | 和定义行为中的标识符保持一致，当前为：<strong>control_volume</strong>。 |  |
+| 工具描述 | 和定义行为中的描述保持一致，当前为：当用户要查询当前设备音量，或需要调高、调低、调整音量时调用。 |  |
+| 工具参数 | control_type | 设备控制类型，枚举类型。取值如下：<br>- 0：只查询当前设备音量。<br>- 1：设置设备音量。<br>- 2：步进增大音量。<br>- 3：步进减少音量。 |
+| volume | 取值含义与 control_type 相关：<br>- 0：该值无意义。<br>- 1：表示需要设置的音量。<br>- 2：表示音量增量，未指定时默认10。<br>- 3：表示音量减量，未指定时默认10。 |  |
+| 输出参数 | 行为执行结果的数据项：<strong>current_volume</strong>（整型，当前音量），需与物模型定义的输出参数保持一致。 |  |
+
+   > **说明：**
+   >
+   > - 工具参数数量需与自定义行为（物模型）中定义的参数数量一致。
+   > - 工具参数的描述应尽量详细，便于 LLM 准确调用，减少幻觉。
+   > - 工具描述也要尽可能准确，如果发现 LLM 执行工具情况不理想，则需要调整这里的描述，提高工具调用命中率。
+
+3. 在 [AI 对话的设备端 SDK](https://cloud.tencent.com/document/product/1081/137894) 集成 [物模型通信](https://cloud.tencent.com/document/product/1081/135031) 能力：
+
+   ``` c
+   #include <stdbool.h>
+   #include <stdlib.h>
+   #include <string.h>
+
+   #include "tc_iot.h"
+   #include "tc_iot_aitalk.h"
+   #include "tc_iot_data_model.h"
+
+   /* 登录和开始对话均为异步操作，回调中记录结果，主流程据此继续或退出。 */
+   static volatile bool s_login_done = false;
+   static volatile bool s_start_done = false;
+   static volatile bool s_aitalk_error = false;
+   static volatile bool s_data_model_done = false;
+   static tc_iot_error_e s_login_result = TC_IOT_ERR_SUCCESS;
+   static tc_iot_error_e s_start_result = TC_IOT_ERR_SUCCESS;
+
+   static data_model_data_item_t s_action_output[1];
+
+   static void on_login(tc_iot_error_e error_code, const char *error_message) {
+       s_login_result = error_code;
+       s_login_done = true;
+       // 登录失败时，可在这里记录 error_message 并通知上层业务。
+   }
+
+   static void on_start_speak(tc_iot_error_e error_code, const char *error_message) {
+       s_start_result = error_code;
+       s_start_done = true;
+       // 开始对话失败时，可在这里记录 error_message 并通知上层业务。
+   }
+
+   static void on_receive_bot_audio(const tc_iot_audio_frame *frame, void *user_data) {
+       (void)user_data;
+       if (!frame || !frame->data || frame->data_size == 0) {
+           return;
+       }
+       // 这里收到的音频是经过解码后的 PCM 音频
+       // 将 frame->data 推送到具体的音频设备播放。
+       // 例如：调用芯片平台的扬声器播放、PCM 输出或音频框架接口。
+   }
+
+   static void on_receive_bot_text(const char *text, void *user_data) {
+       (void)user_data;
+       if (!text) {
+           return;
+       }
+       // 将机器人回复文本显示到屏幕，或上传到您的业务服务。
+   }
+
+   static void on_receive_asr_text(const char *text, void *user_data) {
+       (void)user_data;
+       if (!text) {
+           return;
+       }
+       // 将用户语音识别结果显示到屏幕，或用于本地业务处理。
+   }
+
+   static void on_bot_state_changed(tc_iot_aitalk_bot_state_e old_state,
+                                    tc_iot_aitalk_bot_state_e new_state,
+                                    void *user_data) {
+       (void)old_state;
+       (void)user_data;
+       // 根据 new_state 更新设备指示灯、屏幕或其他交互状态。
+   }
+
+   static void on_aitalk_error(tc_iot_error_e error_code, const char *error_message,
+                               void *user_data) {
+       (void)user_data;
+       s_aitalk_error = true;
+       // 记录 error_code 和 error_message，并停止或重试业务流程。
+   }
+
+   /*
+    * 在平台麦克风的数据回调中调用本函数。
+    * data、size、codec 和 pts_ms 均来自当前平台的音频采集结果。
+    */
+   static void on_mic_captured(const uint8_t *data, uint32_t size,
+                               tc_iot_audio_codec_e codec, uint64_t pts_ms,
+                               void *user_data) {
+       (void)user_data;
+       if (!data || size == 0) {
+           return;
+       }
+
+       tc_iot_audio_frame frame = {0};
+       frame.codec = codec;
+       frame.sample_rate = TC_IOT_AUDIO_SAMPLE_RATE_16000;
+       frame.channels = TC_IOT_AUDIO_CHANNEL_MONO;
+       frame.frame_duration_ms = 20;
+       frame.data = (uint8_t *)data;
+       frame.data_size = size;
+       frame.pts_ms = pts_ms;
+
+       tc_iot_error_e rc = tc_iot_aitalk_send_audio(&frame);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           // 记录发送失败原因；必要时停止采集或触发重连。
+       }
+   }
+
+   // ==================== 物模型通信 ====================
+   // 属性上报结果回调
+   static void on_report_property_result_cb(char *property_id, void *user_data,
+                                            data_model_report_result_t result_code) {
+       (void)user_data;
+       printf("[demo] report property result: id=%s, code=%d\n",
+              property_id ? property_id : "(null)", (int)result_code);
+   }
+
+   // 事件上报结果回调
+   static void on_report_event_result_cb(char *event_id, void *user_data,
+                                         data_model_report_result_t result_code) {
+       (void)user_data;
+       printf("[demo] report event result: id=%s, code=%d\n",
+              event_id ? event_id : "(null)", (int)result_code);
+   }
+
+   // 云端修改属性
+   static void on_receive_property_changed_cb(char *property_id,
+                                              tc_iot_data_model_property_t *data_model_property) {
+       if (!property_id || !data_model_property) {
+           return;
+       }
+       data_model_data_item_t *item = &data_model_property->property;
+       printf("[demo] property changed: id=%s, type=%d\n", item->data_id, (int)item->data_type);
+       // 按 item->data_type 解析 item->data_value 并更新本地状态 ...
+   }
+
+   // 云端下发行为
+   static int on_receive_new_action_cb(char *action_id,
+                                       tc_iot_data_model_action_t *data_model_action) {
+       if (!action_id || !data_model_action) {
+           return -1;
+       }
+       printf("[demo] receive new action: id=%s, input_num=%u\n", action_id,
+              (unsigned)data_model_action->action_input_data_num);
+       // 查询电量
+       if (!strcmp(action_id, "get_battery")) {
+           // 模拟电量，真实业务请接入真实电量百分比
+           static int battery = 58;
+           s_action_output[0].data_id = "battery";
+           s_action_output[0].data_type = DATA_MODEL_DATA_TYPE_INT;
+           s_action_output[0].data_value.value_int = battery--;
+           // 先填好数据再设置数量，避免出现数量与列表不一致的中间状态
+           data_model_action->action_output_data_num = 1;
+           data_model_action->action_output_data_list = s_action_output;
+           printf("[demo] current battery: %d\n", s_action_output[0].data_value.value_int);
+       } else if (!strcmp(action_id, "control_volume")) {
+           // 模拟音量控制
+           static int volume = 50;
+           // 先校验参数个数与列表指针，避免越界访问
+           if (data_model_action->action_input_data_num < 2 ||
+               !data_model_action->action_input_data_list) {
+               return -1;
+           }
+           data_model_data_item_t *in0 = &data_model_action->action_input_data_list[0];
+           data_model_data_item_t *in1 = &data_model_action->action_input_data_list[1];
+           if (!in0->data_id || !in1->data_id) {
+               return -1;
+           }
+           if (!strcmp(in0->data_id, "control_type") && in0->data_type == DATA_MODEL_DATA_TYPE_INT) {
+               // 未携带增减量时按工具描述约定的默认值 10 处理
+               int step = (in1->data_value.value_int > 0) ? in1->data_value.value_int : 10;
+               switch (in0->data_value.value_int) {
+                   // 获取当前音量
+                   case 0:
+                       printf("[demo] volume control: get\n");
+                       break;
+                   // 设置音量
+                   case 1:
+                       printf("[demo] volume control: set\n");
+                       volume = in1->data_value.value_int;
+                       break;
+                   // 调高音量
+                   case 2:
+                       printf("[demo] volume control: increase\n");
+                       volume += step;
+                       break;
+                   // 调低音量
+                   case 3:
+                       printf("[demo] volume control: decrease\n");
+                       volume -= step;
+                       break;
+                   default:
+                       printf("[demo] volume control: unknown type %d\n", in0->data_value.value_int);
+               }
+               // 音量统一收敛到 0 ~ 100
+               if (volume < 0) {
+                   volume = 0;
+               } else if (volume > 100) {
+                   volume = 100;
+               }
+               s_action_output[0].data_id = "current_volume";
+               s_action_output[0].data_type = DATA_MODEL_DATA_TYPE_INT;
+               s_action_output[0].data_value.value_int = volume;
+               // 先填好数据再设置数量，避免出现数量与列表不一致的中间状态
+               data_model_action->action_output_data_num = 1;
+               data_model_action->action_output_data_list = s_action_output;
+               printf("[demo] current volume: %d\n", s_action_output[0].data_value.value_int);
+           }
+       }
+       return 0;
+   }
+
+   int main(void) {
+       bool sdk_inited = false;
+       bool aitalk_inited = false;
+       bool speak_started = false;
+       bool conversation_completed = false;
+       tc_iot_error_e rc;
+
+       // 1. 配置并初始化 SDK。
+       tc_iot_config_s sdk_config = {0};
+       sdk_config.storage_path = "./";
+       sdk_config.log_level = TC_IOT_LOG_LEVEL_INFO;
+       rc = tc_iot_init(&sdk_config);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       sdk_inited = true;
+
+       // 2. 从安全配置中读取设备三元组并登录平台。
+       tc_iot_device_info_s device_info = {0};
+       device_info.product_id = get_product_id();
+       device_info.device_id = get_device_name();
+       device_info.device_secret = get_device_secret();
+       device_info.region = "ap-guangzhou";
+
+       s_login_done = false;
+       rc = tc_iot_login(&device_info, on_login);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+
+       // 等待 on_login 回调或超时；休眠接口请替换为具体平台实现。
+       wait_until(&s_login_done, 30000);
+       if (!s_login_done || s_login_result != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+
+       // 3. 初始化物模型
+       tc_iot_data_model_callback_t callback = {
+           .on_report_property_result_cb = on_report_property_result_cb,
+           .on_receive_property_changed_cb = on_receive_property_changed_cb,
+           .on_report_event_result_cb = on_report_event_result_cb,
+           .on_receive_new_action_cb = on_receive_new_action_cb,
+       };
+       rc = tc_iot_data_model_init(callback);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       s_data_model_done = true;
+
+       // 4. 注册 AI 对话事件回调并初始化模块。
+       tc_iot_aitalk_observer_s observer = {0};
+       observer.on_receive_bot_audio = on_receive_bot_audio;
+       observer.on_receive_bot_text = on_receive_bot_text;
+       observer.on_receive_asr_text = on_receive_asr_text;
+       observer.on_bot_state_changed = on_bot_state_changed;
+       observer.on_error = on_aitalk_error;
+
+       tc_iot_aitalk_init_params_s init_params = {0};
+       // 根据实际情况配置 agent-id prompt_variables_json
+       // 根据实际采集参数设置编码、采样率和单帧时长。
+       init_params.audio_option = get_platform_audio_option();
+       rc = tc_iot_aitalk_init(&init_params, &observer, NULL);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       aitalk_inited = true;
+
+       // 5. 如需机器人触发联系人呼叫，在开始对话前注册联系人。
+       // tc_iot_aitalk_register_contacts(contacts, contact_count, on_register_contacts);
+
+       // 6. 初始化具体平台的麦克风和扬声器。
+       // 麦克风采集到一帧音频后，调用 on_mic_captured() 发送给 AI 对话服务。
+
+       // 7. 异步开始持续对话，成功后再启动麦克风采集。
+       s_start_done = false;
+       rc = tc_iot_aitalk_start_speak(TC_IOT_AITALK_MODE_CONTINUOUS, on_start_speak);
+       if (rc != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       wait_until(&s_start_done, 30000);
+       if (!s_start_done || s_start_result != TC_IOT_ERR_SUCCESS) {
+           goto cleanup;
+       }
+       speak_started = true;
+
+       // 启动具体平台的麦克风采集流程。
+       // 采集线程或回调中不要阻塞过久，按帧调用 on_mic_captured()。
+
+       while (!s_aitalk_error && !is_exit_requested()) {
+           // 使用具体平台的休眠、事件循环或任务调度机制。
+       }
+       conversation_completed = !s_aitalk_error;
+
+   cleanup:
+       // 先停止具体平台的麦克风采集和扬声器播放。
+       if (speak_started) {
+           tc_iot_aitalk_stop_speak();
+       }
+       if (aitalk_inited) {
+           tc_iot_aitalk_deinit();
+       }
+       if (s_data_model_done) {
+           tc_iot_data_model_deinit();
+       }
+       if (sdk_inited) {
+           tc_iot_deinit();
+       }
+       return conversation_completed ? 0 : 1;
+   }
+   ```
+4. 设备端运行，然后说出音量相关指令，观察是否生效。
+
+   ``` bash
+   [aitalk] asr: 现在音量是多少
+   [aitalk] bot_state changed: 1 -> 2
+   [IOT_SDK] 2026-09-15 20:42:52.735 I 7611-1878175744|data_model_action.c:71|create_data_model_action_from_json_string|-action parsed: action_id=control_volume, token=v2342464055QgFuz::0cf5e3ee-71ef-4d73-9f1f-ce90193f2705, input_data_num=2
+   [aitalk] [demo] receive new action: id=control_volume, input_num=2
+   [aitalk] [demo] volume control: get
+   [aitalk] [demo] current volume: 50
+   [IOT_SDK] 2026-09-15 20:42:52.735 I 7611-1878175744|data_model_action.c:202|data_model_on_receive_action_message|-action callback executed, action_id=control_volume, result=0
+   [IOT_SDK] 2026-09-15 20:42:52.767 I 7611-1878175744|mqtt_connection.c:1022|_mqtt_on_puback_packet_received|-puback received: packet_id=10 topic=$thing/up/action/YDBF3QFF7F/test_002
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 现在音量是百分之五十。
+   [aitalk] bot:
+   [aitalk] bot_state changed: 3 -> 5
+   [aitalk] bot_state changed: 5 -> 1
+   [aitalk] asr: 调高音量
+   [aitalk] bot_state changed: 1 -> 2
+   [IOT_SDK] 2026-09-15 20:43:00.311 I 7611-1878175744|data_model_action.c:71|create_data_model_action_from_json_string|-action parsed: action_id=control_volume, token=v2520474960gcquE::78fb4b5c-d422-44d4-8518-c9a7613892f6, input_data_num=2
+   [aitalk] [demo] receive new action: id=control_volume, input_num=2
+   [aitalk] [demo] volume control: increase
+   [aitalk] [demo] current volume: 60
+   [IOT_SDK] 2026-09-15 20:43:00.311 I 7611-1878175744|data_model_action.c:202|data_model_on_receive_action_message|-action callback executed, action_id=control_volume, result=0
+   [IOT_SDK] 2026-09-15 20:43:00.343 I 7611-1878175744|mqtt_connection.c:1022|_mqtt_on_puback_packet_received|-puback received: packet_id=11 topic=$thing/up/action/YDBF3QFF7F/test_002
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 已经帮你调高啦，
+   [aitalk] bot: 现在音量是百分之六十。
+   [aitalk] bot:
+   [aitalk] bot_state changed: 3 -> 5
+   [aitalk] bot_state changed: 5 -> 1
+   [aitalk] asr: 音量调到27%
+   [aitalk] bot_state changed: 1 -> 2
+   [IOT_SDK] 2026-09-15 20:43:10.239 I 7611-1878175744|data_model_action.c:71|create_data_model_action_from_json_string|-action parsed: action_id=control_volume, token=v2521859385OnQNt::4c3df927-ed64-4a19-add4-f54ee70f0533, input_data_num=2
+   [aitalk] [demo] receive new action: id=control_volume, input_num=2
+   [aitalk] [demo] volume control: set
+   [aitalk] [demo] current volume: 27
+   [IOT_SDK] 2026-09-15 20:43:10.240 I 7611-1878175744|data_model_action.c:202|data_model_on_receive_action_message|-action callback executed, action_id=control_volume, result=0
+   [IOT_SDK] 2026-09-15 20:43:10.272 I 7611-1878175744|mqtt_connection.c:1022|_mqtt_on_puback_packet_received|-puback received: packet_id=12 topic=$thing/up/action/YDBF3QFF7F/test_002
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 好，
+   [aitalk] bot: 已经调到百分之二十七了。
+   [aitalk] bot:
+   [aitalk] bot_state changed: 3 -> 5
+   [aitalk] bot_state changed: 5 -> 1
+   [aitalk] asr: 音量调低5
+   [aitalk] bot_state changed: 1 -> 2
+   [IOT_SDK] 2026-09-15 20:43:18.861 I 7611-1878175744|data_model_action.c:71|create_data_model_action_from_json_string|-action parsed: action_id=control_volume, token=v2342464055ebTar::92929726-51af-4197-b2e0-0fd6cdbe1f1f, input_data_num=2
+   [aitalk] [demo] receive new action: id=control_volume, input_num=2
+   [aitalk] [demo] volume control: decrease
+   [aitalk] [demo] current volume: 22
+   [IOT_SDK] 2026-09-15 20:43:18.861 I 7611-1878175744|data_model_action.c:202|data_model_on_receive_action_message|-action callback executed, action_id=control_volume, result=0
+   [IOT_SDK] 2026-09-15 20:43:18.894 I 7611-1878175744|mqtt_connection.c:1022|_mqtt_on_puback_packet_received|-puback received: packet_id=13 topic=$thing/up/action/YDBF3QFF7F/test_002
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 好，
+   [aitalk] bot: 降了五个点，现在音量是百分之二十二。
+   [aitalk] bot:
+   [aitalk] bot_state changed: 3 -> 5
+   [aitalk] bot_state changed: 5 -> 1
+   [aitalk] asr: 当前音量是多少
+   [aitalk] bot_state changed: 1 -> 2
+   [IOT_SDK] 2026-09-15 20:43:29.919 I 7611-1878175744|data_model_action.c:71|create_data_model_action_from_json_string|-action parsed: action_id=control_volume, token=v2342464055rmPhU::c44aad0c-2633-44e9-bc75-2da1f087babd, input_data_num=2
+   [aitalk] [demo] receive new action: id=control_volume, input_num=2
+   [aitalk] [demo] volume control: get
+   [aitalk] [demo] current volume: 22
+   [IOT_SDK] 2026-09-15 20:43:29.919 I 7611-1878175744|data_model_action.c:202|data_model_on_receive_action_message|-action callback executed, action_id=control_volume, result=0
+   [IOT_SDK] 2026-09-15 20:43:29.951 I 7611-1878175744|mqtt_connection.c:1022|_mqtt_on_puback_packet_received|-puback received: packet_id=14 topic=$thing/up/action/YDBF3QFF7F/test_002
+   [aitalk] bot_state changed: 2 -> 3
+   [aitalk] bot: 现在音量是百分之二十二。
+   [aitalk] bot:
+   [aitalk] bot_state changed: 3 -> 5
+   [aitalk] bot_state changed: 5 -> 1
+   ```