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

package/resource/knowledge/iot/device/login-and-register/android-smart-device.md

@@ -0,0 +1,131 @@
+---
+product: iot
+framework:
+  - android
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+本文将介绍如何快速完成腾讯云物联网（IoT）设备端 SDK 的接入，跑通登录功能。
+
+## 前提条件
+
+### 开通服务
+
+在使用 IoT 设备端 SDK 前，您需要前往控制台，创建产品并在产品下创建设备。具体步骤参见 [开通服务](https://cloud.tencent.com/document/product/1081/135239)。
+
+开通服务后，请记录以下设备三元组信息，在后续 登录 步骤中会用到：
+- **ProductId**（产品 ID）
+
+- **DeviceName**（设备名称）
+
+- **DeviceSecret**（设备密钥）
+
+   > **注意：**
+   >
+   > 设备三元组是设备登录平台的唯一身份凭证，请妥善保管 DeviceSecret，避免硬编码提交到公共代码仓库。
+   >
+
+### 环境准备
+- Android Studio 3.5 及以上版本。
+
+- 最低兼容 Android 5.0（SDK API Level 21）及以上。
+
+## 创建项目
+
+参考以下步骤创建一个新的 Android 项目。如果已有项目，可跳过本节。
+1. 打开 Android Studio，选择 New Project（新建项目）。
+
+2. 选择 **Empty Views Activity** 模板，单击 **Next**。
+
+3. 在 Configure your project 页面配置：
+
+   - Language 选择 Java。
+
+   - Minimum SDK 选择 Android 5.0（API 21）及以上。
+
+   - Build configuration language 选择 Groovy DSL (build.gradle)。
+
+## 集成 SDK
+1. 在 app/build.gradle（非根目录的 build.gradle）的 dependencies 中添加 TRTC SDK 以及 IoT SDK 依赖：
+
+   ``` java
+   dependencies {
+       //TRTC SDK
+       implementation 'com.tencent.liteav:LiteAVSDK_TRTC:latest.release'
+       // 物联网设备端 SDK
+       implementation 'com.tencent.liteav.iot:tx-iot-device:latest.release'
+   }
+   ```
+2. 完成配置后，在 Android Studio 工具栏单击 **Sync Now**，SDK 将自动下载并集成到工程中。出现 Build successful 即表示成功。
+
+## 接入步骤
+
+### 步骤 1：初始化 SDK
+
+调用 TXIoTDeviceEngine.getInstance 获取 SDK 实例，并通过 TXIoTDeviceEngine.initSDK 初始化，以及注册日志回调和设备状态推送监听。
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`storagePath`|`String`|本地持久化目录；可为 NULL；非空时长度须合法（实现侧上限约 256）。|
+|`logLevel`|`TXIoTDeviceEngine.LogLevel`|日志级别。|
+|`region`|`String`|地域。|
+
+``` java
+TXIoTDeviceEngine ioTDeviceEngine = TXIoTDeviceEngine.getInstance(getApplicationContext());
+ioTDeviceEngine.addListener(new TXIoTDeviceEngine.Listener() {
+    @Override
+    public void onLog(TXIoTDeviceEngine.LogLevel level, String log) {
+        Log.d(TAG, "onLog: level = " + level + ", log = " + log);
+    }
+
+    @Override
+    public void onDeviceStateChanged(TXIoTDeviceEngine.DeviceState oldState, TXIoTDeviceEngine.DeviceState newState) {
+        Log.d(TAG, "onDeviceStateChanged: oldState = " + oldState + ", newState = " + newState);
+    }
+});
+
+//初始化 SDK
+TXIoTDeviceEngine.Config config = new TXIoTDeviceEngine.Config();
+config.storagePath = "file_path";
+config.logLevel = TXIoTDeviceEngine.LogLevel.INFO;
+config.region = "china";//国内取值为china，国外取值为us-east、europe、ap-bangkok
+ioTDeviceEngine.initSDK(config);
+```
+
+### 步骤 2：登录
+
+调用 TXIoTDeviceEngine.login 完成鉴权并登录，并通过回调监听登录结果。
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`productId`|`String`|产品 ID。|
+|`deviceId`|`String`|设备名称，即 `DeviceName`。|
+|`deviceSecret`|`String`|设备密钥。|
+
+``` java
+TXIoTDeviceEngine.DeviceInfo deviceInfo = new TXIoTDeviceEngine.DeviceInfo();
+deviceInfo.productId = "PRODUCT_ID";
+deviceInfo.deviceId = "DEVICE_NAME";
+deviceInfo.deviceSecret = "DEVICE_SECRET";
+ioTDeviceEngine.login(deviceInfo, new TXIoTCallback() {
+    @Override
+    public void onSuccess() {
+        //登录成功
+    }
+
+    @Override
+    public void onError(int code, String desc) {
+        //登录失败
+    }
+});
+```
+
+## 常见问题
+
+|现象|排查建议|
+|---------|---------|
+|login 长时间无回调 / 超时|检查设备三元组是否正确、网络是否可达、本机系统时间是否准确。|
+

package/resource/knowledge/iot/device/login-and-register/linux-rtos-device.md

@@ -0,0 +1,291 @@
+---
+product: iot
+framework:
+  - linux
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+本文将介绍如何快速接入腾讯云物联网设备端 SDK，跑通**登录**功能。
+
+## 前提条件
+
+### 开通服务
+
+在使用 IoT 设备端 SDK 前，您需要前往控制台，创建产品并在产品下创建设备。具体步骤参见 开通服务。
+
+开通服务后，请记录以下设备三元组信息，在后续 登录 步骤中会用到：
+- **ProductId**（产品 ID）
+
+- **DeviceName**（设备名称）
+
+- **DeviceSecret**（设备密钥）
+
+   > **注意：**
+   >
+   > 设备三元组是设备登录平台的唯一身份凭证，请妥善保管 DeviceSecret，避免硬编码提交到公共代码仓库。
+   >
+
+### 环境准备
+
+请根据您实际对接的设备芯片平台，准备对应的编译环境。本文以 Linux 本机环境为例演示接入流程，帮助您快速跑通登录功能；正式对接您的设备时，替换为目标芯片平台的交叉编译工具链即可，示例代码无需改动。
+
+【Linux 本机（快速体验）】
+
+|环境项|要求|
+|---------|---------|
+|操作系统|x86_64 Linux（Ubuntu 18.04+ / CentOS 7+ 等主流发行版）。|
+|编译工具|CMake 3.10 及以上、GCC / Clang（支持 C99）。|
+|系统依赖库|`pthread`、`m`（数学库）、`dl`、`z`（zlib）。|
+
+【嵌入式设备（交叉编译）】
+
+|环境项|要求|
+|---------|---------|
+|交叉编译工具链|与目标芯片架构匹配的 GCC / Clang 交叉工具链（如 `arm-linux-gnueabihf-gcc`、`aarch64-none-linux-gnu-gcc` 等），具体工具链由芯片厂商 SDK 或 FAE 提供。|
+|编译工具|CMake 3.21 及以上（交叉编译需要通过 `-DCMAKE_TOOLCHAIN_FILE` 指定工具链配置文件）。|
+|sysroot|部分工具链已自带默认 sysroot，无需单独指定；如需自定义。|
+|系统依赖库|与目标架构匹配的 `pthread`、`m`、`dl`、`z` 等库版本，通常随交叉工具链一并提供。|
+
+> **说明：**
+> 不同芯片平台的交叉编译工具链配置差异较大，具体的工具链路径、`-DCMAKE_TOOLCHAIN_FILE` 配置方式请参考对应芯片平台 SDK 包内的 README 说明。
+>
+
+### 获取 SDK
+
+前往 SDK & Demo 页面下载 SDK 包并解压。解压后得到以下内容：
+```
+tc_iot_sdk/
+├── include/              # 全量 public API 头文件（tc_iot.h 等）
+└── lib/
+    └── libtc_iot_sdk.a    # SDK 静态库
+```
+
+## 创建项目
+1. 新建项目目录，并将上一步下载解压得到的 `tc_iot_sdk/` 目录拷贝到项目根目录下。
+
+   ``` bash
+   mkdir -p my_iot_project && cd my_iot_project
+   cp -r /path/to/tc_iot_sdk .
+   ```
+2. 项目目录结构如下：
+
+   ```
+   my_iot_project/
+   ├── CMakeLists.txt
+   ├── main.c
+   └── tc_iot_sdk/
+       ├── include/
+       └── lib/libtc_iot_sdk.a
+   ```
+
+## 集成并引入 SDK
+
+### 步骤 1：配置 CMakeLists.txt
+
+在项目根目录创建 `CMakeLists.txt`，添加头文件搜索路径与静态库链接：
+
+【CMakeLists.txt】
+``` cmake
+cmake_minimum_required(VERSION 3.10)
+project(iot_quickstart_demo C)
+
+set(CMAKE_C_STANDARD 99)
+
+set(SDK_DIR ${CMAKE_CURRENT_SOURCE_DIR}/tc_iot_sdk)
+
+add_executable(iot_quickstart_demo main.c)
+
+target_include_directories(iot_quickstart_demo PRIVATE
+    ${SDK_DIR}/include)
+
+target_link_libraries(iot_quickstart_demo PRIVATE
+    -Wl,--start-group ${SDK_DIR}/lib/libtc_iot_sdk.a -Wl,--end-group
+    pthread m dl z)
+```
+
+### 步骤 2：引入头文件
+
+在 `main.c` 中引入设备端登录相关头文件：
+``` c
+#include "tc_iot.h"      // 初始化 / 登录 / 登出
+```
+
+## 接入步骤
+
+本节介绍如何调用 SDK 完成**登录**。
+
+### 步骤 1：初始化 SDK
+
+调用 `tc_iot_init` 完成 SDK 全局初始化：
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| <code>storage_path</code> | <code>const char *</code> | 本地存储位置。 |
+| <code>log_level</code> | <code>tc_iot_log_level_e</code> | 日志级别。 |
+| <code>on_log</code> | <code>void (*)(tc_iot_log_level_e level,</code><br><code>const char *log)</code> | 日志回调。 |
+| <code>on_device_event</code> | <code>void (*)(tc_iot_device_event_type_e</code><br><code>event_type, const void *event_data)</code> | 事件回调（在线、离线、重连）。 |
+| <code>region</code> | <code>const char *</code> | - 国内站：<code>""</code><br>- 海外站：<code>"us-east"</code>/<code>"europe"</code>/<code>"ap-bangkok"</code> |
+
+``` c
+#include <string.h>
+#include "tc_iot.h"
+
+tc_iot_config_s config;
+memset(&config, 0, sizeof(config));
+config.storage_path = "./";
+config.log_level = TC_IOT_LOG_LEVEL_INFO;
+config.on_log = NULL;
+config.on_device_event = NULL;
+
+tc_iot_error_e rc = tc_iot_init(&config);
+if (rc != TC_IOT_ERR_SUCCESS) {
+    printf("tc_iot_init failed: %d\n", rc);
+    return -1;
+}
+```
+
+### 步骤 2：登录
+
+调用 `tc_iot_login` 使用设备三元组完成登录鉴权，登录结果通过回调异步返回：
+
+|参数|类型|说明|
+|---------|---------|---------|
+|`product_id`|`const char *`|产品 ID。|
+|`device_id`|`const char *`|设备名称。|
+|`device_secret`|`const char *`|设备密钥。|
+
+``` c
+static void on_login(tc_iot_error_e error_code, const char *error_message) {
+    if (error_code == TC_IOT_ERR_SUCCESS) {
+        printf("[demo] login success\n");
+    } else {
+        printf("[demo] login failed: %d, msg=%s\n", error_code,
+               error_message ? error_message : "");
+    }
+}
+
+tc_iot_device_info_s device_info;
+device_info.product_id = "YOUR_PRODUCT_ID";
+device_info.device_id = "YOUR_DEVICE_NAME";
+device_info.device_secret = "YOUR_DEVICE_SECRET";
+
+rc = tc_iot_login(&device_info, on_login);
+if (rc != TC_IOT_ERR_SUCCESS) {
+    printf("tc_iot_login call failed: %d\n", rc);
+}
+```
+
+## 完整示例代码
+``` c
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+#include "tc_iot.h"
+
+static volatile int s_login_done = 0;
+static tc_iot_error_e s_login_rc = TC_IOT_ERR_SUCCESS;
+
+static void on_login(tc_iot_error_e error_code, const char *error_message) {
+    s_login_rc = error_code;
+    s_login_done = 1;
+    if (error_code != TC_IOT_ERR_SUCCESS) {
+        printf("[demo] login failed: %d, msg=%s\n", error_code,
+               error_message ? error_message : "");
+    } else {
+        printf("[demo] login success\n");
+    }
+}
+
+int main(int argc, char **argv) {
+    if (argc < 7) {
+        printf("Usage: %s -p <product_id> -d <device_id> -s <device_secret>\n", argv[0]);
+        return 0;
+    }
+
+    const char *product_id = NULL;
+    const char *device_id = NULL;
+    const char *device_secret = NULL;
+    for (int i = 1; i < argc; i++) {
+        if (strcmp(argv[i], "-p") == 0 && i + 1 < argc) {
+            product_id = argv[++i];
+        } else if (strcmp(argv[i], "-d") == 0 && i + 1 < argc) {
+            device_id = argv[++i];
+        } else if (strcmp(argv[i], "-s") == 0 && i + 1 < argc) {
+            device_secret = argv[++i];
+        }
+    }
+    if (!product_id || !device_id || !device_secret) {
+        printf("device info error\n");
+        return 1;
+    }
+
+    // 1. 初始化 SDK
+    tc_iot_config_s config;
+    memset(&config, 0, sizeof(config));
+    config.storage_path = "./";
+    config.log_level = TC_IOT_LOG_LEVEL_INFO;
+
+    tc_iot_error_e rc = tc_iot_init(&config);
+    if (rc != TC_IOT_ERR_SUCCESS) {
+        printf("tc_iot_init failed: %d\n", rc);
+        return 1;
+    }
+
+    // 2. 登录
+    tc_iot_device_info_s device_info;
+    device_info.product_id = product_id;
+    device_info.device_id = device_id;
+    device_info.device_secret = device_secret;
+
+    rc = tc_iot_login(&device_info, on_login);
+    if (rc != TC_IOT_ERR_SUCCESS) {
+        printf("tc_iot_login call failed: %d\n", rc);
+        tc_iot_deinit();
+        return 1;
+    }
+
+    int waited_ms = 0;
+    while (!s_login_done && waited_ms < 5000) {
+        usleep(100 * 1000);
+        waited_ms += 100;
+    }
+    if (!s_login_done || s_login_rc != TC_IOT_ERR_SUCCESS) {
+        printf("login timeout or failed\n");
+        tc_iot_deinit();
+        return 1;
+    }
+
+    // 3. 释放资源
+    tc_iot_logout();
+    tc_iot_deinit();
+    printf("[demo] main exit\n");
+    return 0;
+}
+```
+
+## 编译并运行
+1. 在项目根目录执行 CMake 编译。
+
+   ``` bash
+   cmake -B build
+   cmake --build build -j
+   ```
+2. 运行可执行文件，传入设备三元组。
+
+   ``` bash
+   ./build/iot_quickstart_demo -p YOUR_PRODUCT_ID -d YOUR_DEVICE_NAME -s 'YOUR_DEVICE_SECRET'
+   ```
+3. 观察日志输出，出现以下内容代表登录成功。
+
+   您可以进入 [物联网开发平台控制台](https://console.cloud.tencent.com/iotexplorer)，在实例下的设备详情页面查看设备状态。
+
+## 常见问题
+
+|现象|排查建议|
+|---------|---------|
+|`tc_iot_login` 长时间无回调 / 超时|检查设备三元组是否正确、网络是否可达、本机系统时间是否准确。|
+|编译报错找不到头文件|确认 `CMakeLists.txt` 中 `target_include_directories` 正确指向 `tc_iot_sdk/include`。|
+|链接报错找不到符号|确认链接顺序使用了 `-Wl,--start-group ... -Wl,--end-group` 包裹静态库，且补齐了 `pthread m dl z` 系统库。|
+

package/resource/knowledge/iot/device/monitor-pushing/android-smart-device.md

@@ -0,0 +1,237 @@
+---
+product: iot
+framework:
+  - android
+types:
+  - feature
+retrievable_scope: always
+feature_domain: device
+---
+
+本文将介绍设备如何在 Android 平台实现响应 APP 发起的**监控请求**、**采集并推送音视频画面**、**切换清晰度**，帮助您快速了解实时监控的功能。
+
+## 前提条件
+
+在开始之前，请您先完成 登录与注册 文档中跑通 login 登录功能。如果您已经完成，可以跳过该操作。
+
+> **说明：**
+> 监控推流依赖摄像头与麦克风采集，请确保已在 `AndroidManifest.xml` 中声明 `android.permission.CAMERA`、`android.permission.RECORD_AUDIO` 权限，并在运行时向用户申请授权。
+>
+
+## 接入步骤
+
+### 步骤 1：注册监控事件回调
+
+登录成功后，通过 `TXIoTMonitorSession.getInstance().addListener` 注册 TXIoTMonitorSession.Listener，实时监控相关的回调如下：
+
+|回调|说明|
+|---------|---------|
+|`onMonitorBegin`|APP 发起监控查看请求时触发，携带 option（清晰度等）与 `customData`（自定义数据）。|
+|`onMonitorEnd`|对端结束监控查看时触发。|
+|`onMonitorSwitch`|APP 在监控查看期间切换清晰度时触发，携带切换后的 quality（可选实现。|
+|`onPTZCommandReceived`|APP 下发云台控制指令时触发，携带 `command`（方向/变焦等）与 `speed`（速度），仅支持云台的设备需实现。|
+
+``` java
+import com.tencent.liteav.iot.TXIoTMonitorSession;
+
+TXIoTMonitorSession monitorSession = TXIoTMonitorSession.getInstance();
+
+TXIoTMonitorSession.Listener listener = new TXIoTMonitorSession.Listener() {
+    @Override
+    public void onMonitorBegin(TXIoTMonitorSession.Option option, String customData) {
+        // APP 发起监控，开启摄像头/麦克风采集推流（详见步骤 2、步骤 3）
+    }
+
+    @Override
+    public void onMonitorEnd() {
+        // APP 结束监控，关闭采集推流（详见步骤 5）
+    }
+
+    @Override
+    public void onMonitorSwitch(TXIoTMonitorSession.VideoQuality quality) {
+        // APP 切换清晰度（详见步骤 4）
+    }
+
+    @Override
+    public void onPTZCommandReceived(TXIoTMonitorSession.PTZCommand command, int speed) {
+        // 云台控制指令（可选实现）
+    }
+};
+
+monitorSession.addListener(listener);
+```
+
+### 步骤 2：响应 onMonitorBegin，开启摄像头推流
+
+在 `onMonitorBegin` 回调中，**必须**调用 openCamera 开启摄像头采集并推流，只需传入 `Option` 与用于本地预览的 `TXCloudVideoView` 即可：
+
+|接口|说明|
+|---------|---------|
+|`openCamera(Option option, TXCloudVideoView view)`|开启摄像头采集并推流，`option` 指定视频清晰度（可复用回调传入的 `option`）；`view` 为本地预览渲染控件，若无需本地预览可传 `null，`返回 `0`（`TXIoTError.SUCCESS`）表示调用成功。|
+|`closeCamera`|关闭摄像头采集与推流（。|
+
+``` java
+private TXCloudVideoView mVideoView; // 在布局中放置 <com.tencent.rtmp.ui.TXCloudVideoView/> 并获取实例
+
+@Override
+public void onMonitorBegin(TXIoTMonitorSession.Option option, String customData) {
+    // 开启摄像头采集并推流，同时在 mVideoView 上本地预览
+    int ret = TXIoTMonitorSession.getInstance().openCamera(option, mVideoView);
+    if (ret != TXIoTError.SUCCESS) {
+        Log.e(TAG, "openCamera failed: " + ret);
+    }
+
+    // 若需要音频，继续开启麦克风推流（详见步骤 3）
+    TXIoTMonitorSession.getInstance().openMicrophone();
+}
+```
+
+### 步骤 3：开启麦克风推流
+
+若监控需要音频，调用 openMicrophone 开启麦克风就可实现音频采集并推流。
+
+|接口|说明|
+|---------|---------|
+|`openMicrophone()`|开启麦克风采集并推流。|
+|`closeMicrophone`|关闭麦克风采集与推流（。|
+
+> **注意：**
+> 开启摄像头与麦克风前，请确保已获得 `CAMERA` 与 `RECORD_AUDIO` 运行时权限，否则采集会失败导致对端无画面或无声音。
+>
+
+``` java
+int ret = TXIoTMonitorSession.getInstance().openMicrophone();
+if (ret != TXIoTError.SUCCESS) {
+    Log.e(TAG, "openMicrophone failed: " + ret);
+}
+```
+
+### 步骤 4：响应 onMonitorSwitch，切换视频清晰度（可选）
+
+APP 端在监控查看期间切换清晰度时，设备端会通过 `onMonitorSwitch` 回调收到通知，携带切换后的 `quality`，在 `onMonitorSwitch` 回调中调用 switchVideoQuality 传入新的清晰度即可完成清晰度切换。`quality` 的可选取值（`TXIoTMonitorSession.VideoQuality`）如下：
+
+|取值|说明|
+|---------|---------|
+|`VideoQuality.UNKNOWN`|未知/未设置。|
+|`VideoQuality.LD`|流畅（低清晰度）。|
+|`VideoQuality.SD`|标清。|
+|`VideoQuality.HD`|高清。|
+|`VideoQuality.FHD`|超清（全高清）。|
+
+``` java
+@Override
+public void onMonitorSwitch(TXIoTMonitorSession.VideoQuality quality) {
+    int ret = TXIoTMonitorSession.getInstance().switchVideoQuality(quality);
+    if (ret != TXIoTError.SUCCESS) {
+        Log.e(TAG, "switchVideoQuality failed: " + ret);
+    }
+}
+```
+
+### 步骤 5：响应 onMonitorEnd，关闭采集推流
+
+对端结束监控查看时触发 `onMonitorEnd`，此时应关闭摄像头与麦克风，停止采集推流：
+``` java
+@Override
+public void onMonitorEnd() {
+    TXIoTMonitorSession.getInstance().closeCamera();
+    TXIoTMonitorSession.getInstance().closeMicrophone();
+}
+```
+
+## 示例代码
+
+以下示例展示在一个 Activity 中完成监听注册与监控推流的完整流程，设备登录与初始化。
+``` java
+package com.example.iotdemo;
+
+import android.os.Bundle;
+import android.util.Log;
+import androidx.annotation.Nullable;
+import androidx.appcompat.app.AppCompatActivity;
+
+import com.tencent.liteav.iot.TXIoTError;
+import com.tencent.liteav.iot.TXIoTMonitorSession;
+import com.tencent.rtmp.ui.TXCloudVideoView;
+
+public class MonitorActivity extends AppCompatActivity {
+
+    private static final String TAG = "MonitorActivity";
+
+    private TXIoTMonitorSession mMonitorSession;
+    private TXCloudVideoView mVideoView;
+
+    private final TXIoTMonitorSession.Listener mListener = new TXIoTMonitorSession.Listener() {
+        @Override
+        public void onMonitorBegin(TXIoTMonitorSession.Option option, String customData) {
+            Log.i(TAG, "onMonitorBegin, customData=" + customData);
+            // 开启摄像头采集并推流，同时本地预览
+            int ret = mMonitorSession.openCamera(option, mVideoView);
+            if (ret != TXIoTError.SUCCESS) {
+                Log.e(TAG, "openCamera failed: " + ret);
+            }
+            // 开启麦克风采集并推流
+            ret = mMonitorSession.openMicrophone();
+            if (ret != TXIoTError.SUCCESS) {
+                Log.e(TAG, "openMicrophone failed: " + ret);
+            }
+        }
+
+        @Override
+        public void onMonitorSwitch(TXIoTMonitorSession.VideoQuality quality) {
+            Log.i(TAG, "onMonitorSwitch, quality=" + quality);
+            int ret = mMonitorSession.switchVideoQuality(quality);
+            if (ret != TXIoTError.SUCCESS) {
+                Log.e(TAG, "switchVideoQuality failed: " + ret);
+            }
+        }
+
+        @Override
+        public void onMonitorEnd() {
+            Log.i(TAG, "onMonitorEnd");
+            mMonitorSession.closeCamera();
+            mMonitorSession.closeMicrophone();
+        }
+
+        @Override
+        public void onPTZCommandReceived(TXIoTMonitorSession.PTZCommand command, int speed) {
+            Log.i(TAG, "onPTZCommandReceived, command=" + command + ", speed=" + speed);
+            // 仅支持云台的设备需实现，驱动云台电机执行对应动作
+        }
+    };
+
+    @Override
+    protected void onCreate(@Nullable Bundle savedInstanceState) {
+        super.onCreate(savedInstanceState);
+        setContentView(R.layout.activity_monitor);
+        mVideoView = findViewById(R.id.video_view);
+
+        // 前提：SDK 已完成初始化并登录成功（参见「登录与注册」）
+        mMonitorSession = TXIoTMonitorSession.getInstance();
+        mMonitorSession.addListener(mListener);
+
+        Log.i(TAG, "monitor session ready, waiting for monitor request from app...");
+    }
+
+    @Override
+    protected void onDestroy() {
+        // 释放资源
+        mMonitorSession.closeCamera();
+        mMonitorSession.closeMicrophone();
+        mMonitorSession.removeListener(mListener);
+        super.onDestroy();
+    }
+}
+```
+
+## 常见问题
+
+|现象|排查建议|
+|---------|---------|
+|发起监控查看后，设备端未收到 `onMonitorBegin`|确认设备已成功登录；确认已通过 `addListener` 注册监听器且未在收到回调前被 `removeListener` 移除。|
+|APP 端看不到监控画面|确认已在 `onMonitorBegin` 中调用 `openCamera` 且返回 `TXIoTError.SUCCESS`；确认已获得 `CAMERA` 运行时权限；确认摄像头未被其他应用占用。|
+|APP 端听不到声音|确认已调用 `openMicrophone` 且返回 `TXIoTError.SUCCESS`；确认已获得 `RECORD_AUDIO` 运行时权限。|
+|切换清晰度后，设备端未收到 `onMonitorSwitch`|确认设备已成功登录且监听器已注册；确认监控会话已建立（`onMonitorBegin` 已触发）。|
+|收到 `onMonitorSwitch` 回调但画面清晰度未变化|确认在回调中调用了 `switchVideoQuality` 且返回 `TXIoTError.SUCCESS`；确认传入的 `quality` 与回调携带的值一致。|
+|监控结束后摄像头/麦克风仍被占用|确认在 `onMonitorEnd` 回调及页面销毁（`onDestroy`）时调用了 `closeCamera` 与 `closeMicrophone` 释放采集资源。|
+