物联网开发平台远程控制

本文介绍腾讯云物联网（IoT）应用端 SDK 中设备管理（TXIoTDeviceManager）的远程控制能力：通过 sendCommand 向设备下发命令、通过 getProperties 查询设备当前属性。完成快速接入、登录 SDK 后，您需确保目标设备已完成 绑定与分享，取得 deviceId 后方可对其进行远程控制。
说明：
本文仅介绍设备远程控制（sendCommand / getProperties）相关能力，不包含 TXIoTMonitorSession 和 TXIoTCallSession 等音视频功能。Android 和 iOS 接口语义基本一致，下文以选项卡形式分别给出关键调用方式。
前提条件
在远程控制设备前，请确保已完成以下准备工作：
已开通腾讯云物联网相关服务，并在控制台完成实例、应用和设备准备。可参见 开通服务。
已在客户端工程中集成 IoT 应用端 SDK。
已通过业务后台生成登录签名，并调用 TXIoTEngine 完成登录。
设备已完成绑定或分享：仅当用户本人拥有该设备、或家庭成员拥有该设备、或用户被分享了该设备时，才具备远程控制的权限。若尚未完成设备绑定或分享，请先参考 绑定与分享。
如果尚未完成 SDK 集成与登录，请先参考 Android 快速接入 或 iOS 快速接入。
APP 操作过程
获取管理对象
设备管理能力通过 TXIoTEngine 获取。在 Android 和 iOS 上，登录成功后，均可通过 TXIoTEngine 单例实例调用 getDeviceManager() 获取设备管理对象。
说明：
如果获取到的 TXIoTDeviceManager 为 null（iOS 为 nil），通常是因为 SDK 尚未登录或登录已过期，请先完成登录后再使用相关能力。
下发命令和查询属性
设备命令和设备属性均使用 JSON 字符串。sendCommand 用于向设备下发命令，getProperties 用于查询设备当前属性。
注意：
jsonData 的字段需要与设备物模型或业务约定保持一致。设备离线、设备不存在或没有权限时，接口会通过 onError 返回错误码和错误信息。
方法
说明
sendCommand
向设备下发命令，参数 jsonData 为设备命令 JSON 字符串。
getProperties
查询设备当前属性，返回设备属性 JSON 字符串。
Android
iOS
String jsonData = "{\\"power_switch\\":1}";
deviceManager.sendCommand(deviceId, jsonData, new TXIoTEngineDef.TXIoTCallback<String>() {
    @Override
    public void onSuccess(String result) {
        // 命令下发成功，result 为服务端返回的 JSON 字符串。
    }
﻿
    @Override
    public void onError(TXIoTEngineDef.TXIoTErrorCode errorCode, String errorMessage) {
        // 命令下发失败，请根据错误码和错误信息处理。
    }
});
﻿
deviceManager.getProperties(deviceId, new TXIoTEngineDef.TXIoTCallback<String>() {
    @Override
    public void onSuccess(String result) {
        // 查询成功，result 为设备属性 JSON 字符串。
    }
﻿
    @Override
    public void onError(TXIoTEngineDef.TXIoTErrorCode errorCode, String errorMessage) {
        // 查询属性失败，请根据错误码和错误信息处理。
    }
});
NSString *jsonData = @"{\\"power_switch\\":1}";
TXIoTCallback<NSString *> *commandCallback = [TXIoTCallback new];
commandCallback.onSuccess = ^(NSString *result) {
    // 命令下发成功，result 为服务端返回的 JSON 字符串。
};
commandCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 命令下发失败，请根据错误码和错误信息处理。
};
[deviceManager sendCommand:deviceId jsonData:jsonData callback:commandCallback];
﻿
TXIoTCallback<NSString *> *propertyCallback = [TXIoTCallback new];
propertyCallback.onSuccess = ^(NSString *result) {
    // 查询成功，result 为设备属性 JSON 字符串。
};
propertyCallback.onError = ^(TXIoTErrorCode errorCode, NSString *errorMessage) {
    // 查询属性失败，请根据错误码和错误信息处理。
};
[deviceManager getProperties:deviceId callback:propertyCallback];
设备端接收远程控制
APP 发送远程控制命令，对应设备端接收属性变更、设备端接收行为调用并回复结果。本节仅作简要介绍，详情可参见 物模型通信。
步骤 1：设备初始化物模型模块
调用 tc_iot_data_model_init 设置回调。
static void on_receive_property_changed_cb(char *property_id,
                                           tc_iot_data_model_property_t *data_model_property);
﻿
static int  on_receive_new_action_cb(char *action_id,
                                      tc_iot_data_model_action_t *data_model_action);
﻿
﻿
tc_iot_data_model_callback_t callback;
memset(&callback, 0, sizeof(callback));
callback.on_receive_property_changed_cb = on_receive_property_changed_cb;
callback.on_receive_new_action_cb       = on_receive_new_action_cb;
﻿
tc_iot_error_e dm_rc = tc_iot_data_model_init(callback);
if (dm_rc != TC_IOT_ERR_SUCCESS) {
    printf("tc_iot_data_model_init failed: %d\\n", dm_rc);
}
步骤 2：设备接收属性变更
当 APP 发送控制命令修改了设备的某个属性时，SDK 会通过 on_receive_property_changed_cb 回调通知用户层。
根据回调参数 tc_iot_data_model_property_t 确定属性名称，属性数据类型，属性数据值。
static void on_receive_property_changed_cb(char *property_id,
                                            tc_iot_data_model_property_t *data_model_property) {
    if (property_id == NULL || data_model_property == NULL) {
        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);
﻿
    switch (item->data_type) {
        case DATA_MODEL_DATA_TYPE_BOOL:
            // 根据 item->data_value.value_bool 调整设备状态
            break;
        case DATA_MODEL_DATA_TYPE_INT:
            // 根据 item->data_value.value_int 调整设备状态
            break;
        case DATA_MODEL_DATA_TYPE_FLOAT:
            // 根据 item->data_value.value_float 调整设备状态
            break;
        case DATA_MODEL_DATA_TYPE_STRING:
            // 根据 item->data_value.value_string 调整设备状态
            break;
        case DATA_MODEL_DATA_TYPE_ENUM:
            // 根据 item->data_value.value_enum 调整设备状态
            break;
        case DATA_MODEL_DATA_TYPE_TIME:
            // 根据 item->data_value.value_time 调整设备状态
            break;
        default:
            break;
    }
}
﻿
说明：
on_receive_property_changed_cb 触发后，设备如果修改了属性值，可以调用 tc_iot_data_model_report_property 将最新的属性值上报云端。
步骤 3：设备接收行为调用
当 APP 发送控制命令调用设备的行为时，SDK 会通过 on_receive_new_action_cb 回调通知用户层。
回调返回值为 int：0 表示执行成功，非0表示执行失败。
如果控制台物模型行为定义了输出参数，回调中给 action_output_data_list / action_output_data_num 赋值，SDK 会把结果回传给云端。
static int on_receive_new_action_cb(char *action_id, tc_iot_data_model_action_t *data_model_action) {
    if (action_id == NULL || data_model_action == NULL) {
        return -1;
    }
﻿
    printf("[demo] receive new action: id=%s, token=%s, timestamp=%u, input_num=%d\\n",
           action_id,
           data_model_action->token ? data_model_action->token : "",
           (unsigned)data_model_action->timestamp,
           data_model_action->action_input_data_num);
﻿
    // 1. 解析输入参数
    for (int i = 0; i < data_model_action->action_input_data_num; i++) {
        data_model_data_item_t *input = &data_model_action->action_input_data_list[i];
        printf("    input[%d]: id=%s, type=%d\\n", i, input->data_id, (int)input->data_type);
        // 根据业务需要读取 input->data_value ...
    }
﻿
    // 2. 执行行为逻辑（同步执行，避免在回调里做长时间阻塞）
﻿
    // 3. 填充输出参数（按云端定义的输出参数顺序和类型）
    int output_num = data_model_action->action_input_data_num;  // 示例：与输入参数个数保持一致
    data_model_action->action_output_data_num = output_num;
    data_model_action->action_output_data_list = NULL;
    if (output_num > 0) {
        data_model_action->action_output_data_list =
            (data_model_data_item_t *)calloc(output_num, sizeof(data_model_data_item_t));
        if (data_model_action->action_output_data_list == NULL) {
            return -2;  // 内存不足，回复云端失败
        }
        for (int i = 0; i < output_num; i++) {
            data_model_data_item_t *input  = &data_model_action->action_input_data_list[i];
            data_model_data_item_t *output = &data_model_action->action_output_data_list[i];
﻿
            output->data_id = input->data_id;       // 与云端约定好的输出参数标识
            output->data_type = input->data_type;   // 与云端约定好的输出参数类型
            if (input->data_type == DATA_MODEL_DATA_TYPE_INT) {
                output->data_value.value_int = input->data_value.value_int + 1;
            } else {
                output->data_value = input->data_value;
            }
        }
    }
﻿
    // 4. 返回 0：执行成功；返回非 0：执行失败，云端会收到对应错误码
    return 0;
}
﻿
说明：
如果行为没有输出参数，把 action_output_data_num 设置为 0、action_output_data_list 设置为 NULL 即可。
返回0表示执行成功，云端收到的 action_reply 消息中 code=0、status=success；返回非0时 code=返回值、status=action execution failed。
方法	说明
`sendCommand`	向设备下发命令，参数 `jsonData` 为设备命令 JSON 字符串。
`getProperties`	查询设备当前属性，返回设备属性 JSON 字符串。
远程控制

本页目录：

前提条件

APP 操作过程

获取管理对象

下发命令和查询属性

设备端接收远程控制

步骤 1：设备初始化物模型模块

步骤 2：设备接收属性变更

步骤 3：设备接收行为调用
