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

package/resource/knowledge/iot/device/demo/android-smart-device.md

@@ -0,0 +1,97 @@
+---
+product: iot
+framework:
+  - android
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device_demo
+---
+
+本文档介绍如何编译并运行 IoT 智能设备端 Android Demo，帮助您快速完成 **设备登录**、**物模型**、**音视频通话**、**监控直播**、**AI 语音对话**等核心能力的体验。
+
+## 前提条件
+
+### 开通服务
+
+在跑通 IoT 智能设备端 Android Demo 前，您需要前往控制台创建产品，并在产品下创建设备。具体步骤参见 [开通服务](https://cloud.tencent.com/document/product/1081/135239)。
+
+开通服务后，请记录以下设备三元组信息，后续在 Demo 的 登录 步骤中会用到：
+- **ProductId**（产品 ID）
+
+- **DeviceName**（设备名称）
+
+- **DeviceSecret**（设备密钥）
+
+### 环境要求
+- 使用 **AGP 8.13**，要求 **JDK 17**，并采用 **Kotlin** 实现。
+
+- **Gradle** 版本为 8.13.2。
+
+- **compileSdk / targetSdk** 均为 29。
+
+- **必须使用 Android 真机**（音视频、相机、麦克风等能力在模拟器上无法正常工作）。
+
+## Demo 说明
+
+Demo 已开源，仓库地址：[github.com/Tencent-RTC/Tencent_IoT_Device](https://github.com/Tencent-RTC/Tencent_IoT_Device)
+
+开源仓库按平台分目录，Android Demo 位于顶层 `Android` 目录：
+``` text
+Tencent_IoT_Device/
+├── Android/               # Android 设备端 Demo
+│   ├── app/               # Demo 业务代码
+│   │   └── src/main/      # 页面、布局与资源
+│   ├── gradle/            # 版本目录 libs.versions.toml
+│   ├── settings.gradle.kts
+│   ├── build.gradle.kts
+│   ├── gradlew / gradlew.bat
+│   └── local.properties
+├── Linux/
+├── RTOS/
+└── README.md
+```
+
+## 编译工程
+
+参考以下步骤编译 IoT 智能设备端 Android Demo 进行体验。
+1. 使用 `git clone` 将开源 Demo 从 GitHub 克隆到本地。
+
+2. 打开 Android Studio，单击 **Open** 将 Demo 导入。
+
+3. 在 Android Studio 工具栏单击 **Sync Now**，等待 SDK 自动下载完成。随后连接真机，点击工具栏的 **Run** 即可编译并运行到真机上；也可在控制台执行命令 `./gradlew :app:assembleDebug` 打包成 APK，发送到手机进行安装。
+
+## 功能体验
+
+Demo 的页面入口关系如下：
+``` text
+LoginActivity（登录）
+      └── HomeActivity（首页）
+              ├── AITalkActivity        AI 语音对话
+              ├── DataModelActivity      物模型
+              ├── ContactsActivity ──► CallActivity   微信通话
+              ├── CallActivity           音视频通话（由app端触发）
+              ├── MonitorActivity        监控直播（由app端触发）
+              └── DeviceDetailActivity   设备详情
+```
+1. 打开 App 进入登录页。
+
+2. 依次填入 **ProductId**、**DeviceName**、**DeviceSecret**，并选择 **Region**（默认 `ap-guangzhou`）。
+
+3. 单击**登录**，跳转主页：
+
+   至此，IoT 智能设备端 Android Demo 已成功跑通，接下来即可体验**物模型**、**音视频通话**、**监控直播**、**AI 语音对话**等核心功能**。**
+
+   > **注意：**
+   >
+   > - 设备三元组是设备登录平台的唯一身份凭证，请妥善保管 DeviceSecret。
+   > - 若需体验`微信通话功能`与 `AI 语音对话功能`，请先参考 开通服务文档 开通对应的服务。
+
+## 常见问题
+
+|现象|排查建议|
+|---------|---------|
+|Gradle 同步失败或依赖下载不下来|确认网络可正常访问 `mavenCentral()` 与 `google()` 仓库；必要时配置代理或镜像源后重试。|
+|登录一直失败（错误码 -8 / -304 / -305）|逐项核对三元组信息与地域；确认设备在控制台处于启用状态；确认真机网络可正常访问外网。|
+|监控 / 通话 / AI 对话无画面或无声音|确认已授予相机与麦克风权限；确认使用真机而非模拟器；确认 LiteAVSDK 与 IoT SDK 依赖均已成功下载。|
+

package/resource/knowledge/iot/device/demo/linux-rtos-device.md

@@ -0,0 +1,106 @@
+---
+product: iot
+framework:
+  - linux
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device_demo
+---
+
+本文档将介绍如何编译并运行设备端 Linux x64 Demo，帮助您快速实现**设备登录**、**音视频通话**等核心能力的体验。
+
+## 开通服务
+
+在跑通 Demo 前，您需要前往控制台创建产品，并在产品下创建设备，具体步骤参见 开通服务。
+
+开通服务后，请记录以下设备三元组信息，后续运行 Demo 时会用到：
+- product_id（产品 ID）
+
+- device_id（设备 ID）
+
+- device_secret（设备密钥）
+
+## 环境要求
+- 操作系统：x86_64 Linux（Ubuntu 18.04+ / CentOS 7+ 等主流发行版）。
+
+- 编译工具：CMake 3.21 及以上、GCC / Clang（支持 C11）。
+
+- 系统依赖库：`pthread`、`m`（数学库）、`dl`、`z`（zlib）。
+
+## 下载 Demo
+
+在 [GitHub](https://github.com/Tencent-RTC/Tencent_IoT_Device) 下载设备端 Demo 源码，其中 Linux x64 Demo 的目录结构：
+``` bash
+Tencent_IoT_Device/
+└── Linux/
+    └── linux_x64/
+        ├── demo/
+        │   ├── iot_video_demo/     # 音视频 Demo
+        │   └── iot_aitalk_demo/    # AI 语音对话 Demo
+        ├── sdk/
+        │   ├── include/            # SDK 的头文件
+        │   ├── lib/                # SDK 的二进制
+        │   └── module_config.cmake # SDK 开启的功能
+        ├── CMakeLists.txt          # 用来编译 Demo
+        └── README.md
+```
+
+## 编译 Demo
+
+编译音视频 Demo 和 AI 语音对话 Demo：
+``` bash
+cd ./Tencent_IoT_Device/Linux/linux_x64
+cmake -B build
+cmake --build build -j
+```
+
+编译产物：
+``` bash
+Tencent_IoT_Device/
+└── Linux/
+    └── linux_x64/
+        ├── build/
+        │   ├── iot_video_demo  # 音视频 Demo 的可执行文件
+        │   └── iot_aitalk_demo # AI 语音对话 Demo 的可执行文件
+        ├── demo/
+        │   ├── iot_video_demo/
+        │   └── iot_aitalk_demo/
+        ├── sdk/
+        │   ├── include/
+        │   ├── lib/
+        │   └── module_config.cmake
+        ├── CMakeLists.txt
+        └── README.md
+```
+
+## 设备登录
+
+使用三元组进行设备登录：
+``` bash
+export LD_LIBRARY_PATH=sdk/lib:$LD_LIBRARY_PATH
+./build/iot_video_demo -p <product_id> -d <device_id> -s <device_secret>
+```
+
+登录成功后，会打印日志 `[demo] started`：
+
+同时，可以在 App 端（App 可以在 SDK & Demo 下载，使用方式参见 跑通 Demo）看到设备处于“在线”状态：
+
+## 音视频通话
+
+> **注意：**
+> 需要先在控制台开通音视频通话服务，具体步骤参见 开通服务。
+>
+
+运行音视频 Demo：
+``` bash
+export LD_LIBRARY_PATH=sdk/lib:$LD_LIBRARY_PATH
+./build/iot_video_demo -p <product_id> -d <device_id> -s <device_secret>
+```
+
+登录成功后，会启动音视频通话功能，监听 App 端的监控和呼叫。
+
+可以在 App 端发起监控，拉取设备端的音视频：
+
+也可以在 App 端发起呼叫，设备端会自动接听：
+

package/resource/knowledge/iot/device/device-ota-upgrade.md

@@ -0,0 +1,237 @@
+---
+product: iot
+framework:
+  - '*'
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+本文将介绍 OTA 接入流程，包括**配置当前固件版本**、**处理升级通知**、**发起固件下载**、**固件刷写**以及**上报升级进度和结果**等。
+
+## 前提条件
+
+接入前需完成以下准备工作：
+1. 按照 登录与注册 文档跑通 `tc_iot_login` 登录功能。
+
+2. 按照 OTA 升级包 文档在后台为需要升级的模块创建并发布固件版本，确保模块名称与 OTA 初始化配置中的 `module_name` 完全一致。
+
+3. 确认下载目录可写且有足够空间；设备没有文件系统时，可联系技术支持。
+
+## 接入步骤
+
+### 步骤 1：配置当前固件信息并初始化 OTA
+
+SDK 登录成功后，填写各模块当前运行的固件版本，注册回调，并调用 `tc_iot_ota_init`。SDK 上报各模块当前版本，并在有可用升级时通过回调通知升级任务。
+
+|字段|说明|
+|---------|---------|
+|`module_name`|固件模块名称，以 `\0` 结尾；须与后台固件模块名称一致。|
+|`module_version`|当前运行的固件版本，以 `\0` 结尾。|
+|`firmware_info`|各模块当前固件信息数组。|
+|`firmware_info_count`|`firmware_info` 数组中的模块数量。|
+
+``` c
+#include <stdio.h>
+#include <string.h>
+
+#include "tc_iot.h"
+#include "tc_iot_ota.h"
+
+static void on_receive_firmware_upgrade_notify(
+    const tc_iot_ota_firmware_info_t *firmware_info, void *user_data);
+static 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);
+static 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);
+
+tc_iot_ota_firmware_info_t firmware_info[] = {
+    {
+        .module_name = "mcu",
+        .module_version = "1.0.0",
+    },
+    {
+        .module_name = "wifi",
+        .module_version = "1.1.0",
+    }
+}; // 示例版本；实际接入时填写当前运行的固件版本。
+
+tc_iot_ota_config_t ota_config = {
+    .firmware_info = firmware_info,
+    .firmware_info_count = sizeof(firmware_info) / sizeof(firmware_info[0]),
+};
+
+tc_iot_ota_observer_t ota_observer;
+memset(&ota_observer, 0, sizeof(ota_observer));
+ota_observer.on_receive_firmware_upgrade_notify =
+    on_receive_firmware_upgrade_notify;
+ota_observer.on_download_firmware_progress = on_download_firmware_progress;
+ota_observer.on_download_firmware_result = on_download_firmware_result;
+
+tc_iot_error_e error = tc_iot_ota_init(&ota_config, &ota_observer, NULL);
+if (error != TC_IOT_ERR_SUCCESS) {
+    printf("tc_iot_ota_init failed: %d\n", error);
+}
+```
+
+`on_receive_firmware_upgrade_notify` 和 `on_download_firmware_result` 必须注册；不需要处理下载进度时，`on_download_firmware_progress` 可设为 `NULL`。
+
+> **注意：**
+> - 同一个 `module_name` 只能注册一次。
+> - `user_data` 为自定义回调上下文，其指向的对象须在 OTA 反初始化及相关回调完成前保持有效。
+
+### 步骤 2：处理升级通知，检查更新条件并发起下载
+
+有可用升级时，SDK 调用 `on_receive_firmware_upgrade_notify`，通知目标模块和目标版本。设备检查本地状态，确认满足更新条件后，调用 `tc_iot_ota_download_firmware` 发起下载。
+
+以下示例假设本地更新条件已满足，在回调中发起下载：
+``` c
+#define OTA_DOWNLOAD_DIRECTORY "./ota_firmware"
+
+static void on_receive_firmware_upgrade_notify(
+    const tc_iot_ota_firmware_info_t *firmware_info, void *user_data) {
+    (void)user_data;
+    printf("[ota] receive upgrade: module=%s, target_version=%s\n",
+           firmware_info->module_name, firmware_info->module_version);
+
+    tc_iot_error_e error =
+        tc_iot_ota_download_firmware(firmware_info, OTA_DOWNLOAD_DIRECTORY);
+    if (error != TC_IOT_ERR_SUCCESS) {
+        printf("[ota] submit download failed: %d\n", error);
+    }
+}
+```
+
+`download_directory` 指定固件保存目录。下载成功后，使用结果回调提供的 `file_path` 读取固件。
+
+> **注意：**
+> - `firmware_info` 的模块名称和目标版本须与本次升级通知一致；延后下载时须先复制该信息。
+> - SDK 同一时间只能处理一个 OTA 任务，下载进行中不得重复调用下载接口。
+> - OTA 回调中不得执行耗时或阻塞操作。
+
+### 步骤 3：处理固件下载进度（可选）
+
+下载期间，SDK 通过 `on_download_firmware_progress` 通知已下载字节数和固件总字节数。示例按字节数计算下载百分比：
+``` c
+static 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) {
+    (void)user_data;
+    uint32_t progress =
+        total_size == 0 ? 0 : (uint32_t)(((uint64_t)current_size * 100u) / total_size);
+    printf("[ota] downloading: module=%s, version=%s, progress=%u%% (%u/%u)\n",
+           firmware_info->module_name, firmware_info->module_version, progress,
+           current_size, total_size);
+}
+```
+
+`tc_iot_ota_report_upgrade_progress` 用于上报固件刷写进度。
+
+### 步骤 4：处理下载结果并执行固件刷写
+
+SDK 通过 `on_download_firmware_result` 通知下载结果。仅在 `error_code` 为 `TC_IOT_ERR_SUCCESS` 时执行固件刷写：
+
+|场景|`error_code`|`error_message`|`file_path`|
+|---------|---------|---------|---------|
+|下载并校验成功|`TC_IOT_ERR_SUCCESS`|`NULL`|固件文件路径|
+|下载或校验失败|非 `TC_IOT_ERR_SUCCESS`|失败原因|`NULL`|
+
+``` c
+static 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) {
+    ota_demo_context_t *context = (ota_demo_context_t *)user_data;
+
+    if (error_code != TC_IOT_ERR_SUCCESS) {
+        printf("[ota] download failed: module=%s, version=%s, error=%d, message=%s\n",
+               firmware_info->module_name, firmware_info->module_version, error_code,
+               error_message ? error_message : "");
+        return;
+    }
+
+    printf("[ota] firmware ready: module=%s, version=%s, path=%s\n",
+           firmware_info->module_name, firmware_info->module_version, file_path);
+
+    /* 复制回调参数并通知升级线程执行固件刷写，不能长期持有回调中的指针。 */
+    schedule_firmware_install(context, firmware_info, file_path);
+}
+```
+
+示例中的 `schedule_firmware_install` 由接入方实现，用于复制固件信息和文件路径，并通知**独立升级线程**执行固件刷写。
+
+> **注意：**
+> `firmware_info`、`error_message` 和 `file_path` 仅在回调期间有效，延后使用时必须复制内容。
+>
+
+### 步骤 5：上报固件刷写进度和结果
+
+设备在固件刷写过程中，按实际进度调用 `tc_iot_ota_report_upgrade_progress`。固件刷写失败，或成功后无需重启时，调用 `tc_iot_ota_report_upgrade_result` 上报结果。
+
+如果固件刷写成功后需要重启，设备在新固件启动并登录后，将实际运行的新版本填入 `tc_iot_ota_init` 配置。SDK 会上报新版本，后台据此确认升级完成。
+
+以下示例演示固件刷写函数返回后主动上报结果的用法：
+``` c
+static void install_firmware(const tc_iot_ota_firmware_info_t *firmware_info,
+                             const char *file_path) {
+    tc_iot_error_e error =
+        tc_iot_ota_report_upgrade_progress(firmware_info, 0);
+    if (error != TC_IOT_ERR_SUCCESS) {
+        printf("[ota] report upgrade progress failed: %d\n", error);
+    }
+
+    /* 平台固件刷写过程中，应继续按实际固件刷写进度调用进度上报接口。 */
+    bool install_success = platform_install_firmware(file_path);
+    if (install_success) {
+        error = tc_iot_ota_report_upgrade_progress(firmware_info, 100);
+        if (error != TC_IOT_ERR_SUCCESS) {
+            printf("[ota] report upgrade progress failed: %d\n", error);
+        }
+    }
+
+    int32_t result_code = install_success ? 0 : -1;
+    const char *description = install_success ? "upgrade_success" : "upgrade_failed";
+    error = tc_iot_ota_report_upgrade_result(
+        firmware_info, result_code, description);
+    if (error != TC_IOT_ERR_SUCCESS) {
+        printf("[ota] report upgrade result failed: %d\n", error);
+    }
+}
+```
+
+|接口|说明|
+|---------|---------|
+|`tc_iot_ota_report_upgrade_progress(firmware_info, progress)`|上报固件刷写进度，`progress` 取值范围为 0～100。|
+|`tc_iot_ota_report_upgrade_result(firmware_info, 0, description)`|上报升级成功。|
+|`tc_iot_ota_report_upgrade_result(firmware_info, -1, description)`|上报升级失败。|
+
+> **注意：**
+> - 下载成功后才能上报固件刷写进度或结果。
+> - 上报时使用下载成功回调中的目标模块和目标版本。
+
+### 步骤 6：反初始化 OTA
+
+设备退出登录或释放 SDK 前，调用 `tc_iot_ota_deinit` 停止下载并释放 OTA 资源：
+``` c
+tc_iot_error_e error = tc_iot_ota_deinit();
+if (error != TC_IOT_ERR_SUCCESS) {
+    printf("tc_iot_ota_deinit failed: %d\n", error);
+}
+
+tc_iot_logout();
+tc_iot_deinit();
+```
+
+## 常见问题
+
+|现象|排查建议|
+|---------|---------|
+|`tc_iot_ota_init` 返回 `TC_IOT_ERR_NOT_INITIALIZED`|先调用 `tc_iot_init` 初始化 SDK，并调用 `tc_iot_login` 登录。|
+|`tc_iot_ota_init` 返回 `TC_IOT_ERR_NOT_CONNECTED`|等待 `tc_iot_login` 回调通知登录成功后，再初始化 OTA。|
+|`tc_iot_ota_init` 返回 `TC_IOT_ERR_OTA_INIT_PARAM_INVALID`|检查 `firmware_info` 和 `firmware_info_count` 是否正确；模块名称不可重复，名称和版本字符串以 `\0` 结尾。|
+|`tc_iot_ota_init` 返回 `TC_IOT_ERR_OTA_INIT_OBSERVER_NULL`|需要传入合法的 observer，至少包含必填的 `on_receive_firmware_upgrade_notify` 和 `on_download_firmware_result`。|
+|`on_download_firmware_result` 回调中的 `error_code` 为 `TC_IOT_ERR_OTA_START_FAILED`|检查模块名称和目标版本是否与本次升级通知一致，以及是否重复调用下载接口。|
+|烧录完成重启后仍收到相同升级通知|确认新固件已生效，并在 `tc_iot_ota_init` 中使用实际运行的新版本初始化|
+