帮你快速理解、总结文档立即下载
文档中心>物联网开发平台>实时监控>云台控制

云台控制

最近更新时间：2026-07-30 12:00:37

我的收藏

本页目录：

本文将介绍设备如何实现实时监控场景下云台控制功能。

应用端接入

对于支持云台（PTZ）的设备，应用端在查看监控期间可通过 sendPTZCommand 控制镜头方向、变焦与停止控制。指令下发后，设备端会收到 on_ptz_command_received 回调并驱动云台硬件（见下文 设备端接入）。指令类型见枚举类型 TXIoTPTZCommand，速度 speed 由设备能力决定（通常取值 1 ~ 10）。
注意：
方向类操作通常为 “按住转动、松开停止”，按下时下发方向指令（如 LEFT），松开时必须下发 STOP，否则云台会持续转动无法停止。

接口说明

方法
说明
向 channelId 通道发送云台指令，command 为指令类型（TXIoTPTZCommand），speed 为速度。

调用示例

Android
iOS
// 控制云台向左转动，速度 5
session.sendPTZCommand(0,                         // 通道 ID，如果仅有一个通道，则传 0
        TXIoTMonitorSession.TXIoTPTZCommand.LEFT, // 云台指令，例如：向左转动
        5);                                       // 转动速度

// 松开时停止云台转动
session.sendPTZCommand(0,
        TXIoTMonitorSession.TXIoTPTZCommand.STOP,
        0);
// 控制云台向左转动，速度 5
[session sendPTZCommand:0                  // 通道 ID，如果仅有一个通道，则传 0
               command:TXIoTPTZCommandLeft // 云台指令，例如：向左转动
                  speed:5];                // 转动速度

// 松开时停止云台转动
[session sendPTZCommand:0
               command:TXIoTPTZCommandStop
                  speed:0];

设备端接入

接入步骤

步骤 1：注册 on_ptz_command_received 回调

调用 tc_iot_av_init 注册 tc_iot_av_observer_s 时，为 on_ptz_command_received 赋值。APP 端在查看监控期间发起云台操作时，设备端会通过该回调收到通知，携带 channel_id（对应的监控通道）、ptz_command（云台指令）与 speed（转动速度）：
#include "tc_iot_av.h"

static void on_ptz_command_received(int channel_id, ptz_command_e ptz_command, int speed);

tc_iot_av_observer_s observer;
memset(&observer, 0, sizeof(observer));
observer.on_ptz_command_received = on_ptz_command_received;

tc_iot_error_e av_rc = tc_iot_av_init(&observer);
if (av_rc != TC_IOT_ERR_SUCCESS) {
    printf("tc_iot_av_init failed: %d\\n", av_rc);
}
ptz_command 的可选取值（ptz_command_e）如下：
取值
说明
PTZ_CMD_UP
向上转动。
PTZ_CMD_DOWN
向下转动。
PTZ_CMD_LEFT
向左转动。
PTZ_CMD_RIGHT
向右转动。
PTZ_CMD_ZOOM_IN
镜头放大（拉近）。
PTZ_CMD_ZOOM_OUT
镜头缩小（拉远）。
PTZ_CMD_STOP
停止转动。

步骤 2：响应回调，驱动云台硬件

在回调中根据 ptz_command 调用对应的云台硬件驱动接口完成转动，speed 用于控制转动速度。云台驱动接口由具体硬件平台提供，以下以自定义 ptz_motor_move / ptz_motor_zoom / ptz_motor_stop 函数表示，请替换为您设备实际的云台驱动接口：
// 以下函数由业务自行实现，对接具体硬件平台的云台驱动接口
extern void ptz_motor_move(int direction, int speed);  // direction: 0=上 1=下 2=左 3=右
extern void ptz_motor_zoom(bool zoom_in, int speed);
extern void ptz_motor_stop(void);

static void on_ptz_command_received(int channel_id, ptz_command_e ptz_command, int speed) {
    printf("[demo] on_ptz_command_received channel_id=%d cmd=%d speed=%d\\n",
           channel_id, ptz_command, speed);

    switch (ptz_command) {
        case PTZ_CMD_UP:
            ptz_motor_move(0, speed);
            break;
        case PTZ_CMD_DOWN:
            ptz_motor_move(1, speed);
            break;
        case PTZ_CMD_LEFT:
            ptz_motor_move(2, speed);
            break;
        case PTZ_CMD_RIGHT:
            ptz_motor_move(3, speed);
            break;
        case PTZ_CMD_ZOOM_IN:
            ptz_motor_zoom(true, speed);
            break;
        case PTZ_CMD_ZOOM_OUT:
            ptz_motor_zoom(false, speed);
            break;
        case PTZ_CMD_STOP:
            ptz_motor_stop();
            break;
        default:
            break;
    }
}
注意：
APP 端云台方向操作通常是"按住转动、松开发送 PTZ_CMD_STOP"，请务必正确处理 PTZ_CMD_STOP，否则云台会持续转动无法停止。

常见问题

现象
排查建议
发起云台操作后，设备端未收到 on_ptz_command_received。
确认设备已成功登录且 tc_iot_av_init 调用成功；确认 on_ptz_command_received 已正确赋值（未被 memset 清零覆盖）；确认监控会话已建立（on_monitor_begin 已触发）。
收到回调但云台无转动。
确认已正确对接云台硬件驱动接口；确认 switch 分支覆盖了实际下发的 ptz_command 取值。
云台持续转动不停止。
检查是否正确处理了 PTZ_CMD_STOP 分支并调用了停止接口。
中国站