物模型功能

更新时间：2025-05-30 13:19:33

物模型SDK提供了App端的物模型（属性、事件、服务），用来开发设备界面，实现手机对设备的查看和控制。

// 导入物模型SDK头文件
#import <RTCXThingCapability/RTCXThingCapability.h>

初始化物对象

• 初始化方法如下：

@interface RTCXThingManager : NSObject
/**
 返回单例

 @return 单例
 */
+ (instancetype)sharedManager;


/**
 创建 Thing 对象，该对象会被加入管理者维护的物的队列中

 @param iotId 物的唯一标识符， 该 id 是物在注册绑定时由云端颁发
 @return 返回 Thing 对象
- (RTCXThing *)buildThing:(NSString *)iotId  DEPRECATED_API;
*/


/**
 销毁 Thing 对象，在 Thing 不再需要时调用此方法
可以将其从 管理者维护的物的队列中删除
 @param hing Thing 的对象
 */
- (void)destroyThing:(RTCXThing *)thing;



/**
 创建 Thing 对象，该对象会被加入管理者维护的物的队列中
 
 @param productKey 物在iot平台注册的产品型号
 @param deviceName 物的deviceName
 @param iotId 物的iotId
 @return 返回 Thing 对象
 */
- (RTCXThing*)buildThing:(NSString *)productKey
             deviceName:(NSString *)deviceName
                  iotId:(NSString *)iotId;

@end

• 状态回调代理方法如下：

/**
 物的状态变更、属性变更、事件触发的观察者类
 */
@protocol RTCXThingObserver <NSObject>

@optional
/**
 物的状态变更回调，如上线，离线等
 @param iotId 物的 iotId
 @param params 描述具体状态
 */
- (void)onStatusChange:(NSString *)iotId params:(NSDictionary *)params;
/**
物的属性发生变化

 @param iotId 物的 iotId
 @param params 描述属性内容
 */
- (void)onPropertyChange:(NSString *)iotId params:(NSDictionary *)params;

/**
设备被解绑通知
 @param iotId 物的 iotId
 @param params 描述属性内容
 */
- (void)onDeviceUnbind:(NSString *)iotId params:(NSDictionary *)params;

/**
物的 tsl 模板解析完毕，后续可以用 [self getThingProfile] 拿到详细的 tsl 模型数据
 */
- (void)didThingTslLoad:(NSString *)iotId;

@end

使用 RTCXThingManager 宏定义调用示例如下:

• 物模型对象初始化

// 初始化物模型
    RTCXThing *things = [kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId];
    self.things = things;
    // 注册监听
    [self.things registerThingObserver:self];

• 监听获取设备物模型、上下线消息、属性变化消息、解绑消息

#pragma mark -- RTCXThingObserver --
- (void)didThingTslLoad:(NSString *)iotId {
// 当 RTCXThingObserver  didThingTslLoad 方法被回调时，可以获得解析完成的物的模型。
    COMMON_PRINTF(@"物的 tsl 模板解析完毕，后续可以用 [self getThingProfile] 拿到详细的 tsl 模型数据");
}

- (void)onStatusChange:(NSString *)iotId params:(NSDictionary *)params {
    COMMON_PRINTF(@"[deviceList]:deviceStatusChanged-iotId: %@, params: %@",iotId,params);
    [self loadNewData];
}

- (void)onPropertyChange:(NSString *)iotId params:(NSDictionary *)params {
    COMMON_PRINTF(@"[deviceList]:devicePropertyChanged-iotId: %@, params: %@",iotId,params);
}

- (void)onDeviceUnbind:(NSString *)iotId params:(NSDictionary *)params {
    COMMON_PRINTF(@"[deviceList]:deviceUnbind-iotId: %@, params: %@",iotId,params);
    [self loadNewData];
}

• 获取物的属性，事件，服务

RTCXThing *things = [kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId];
RTCXThingProfile * Profile = [things getThingProfile];
//其中物的三要素，保存在 RTCXThingProfile 中。
NSArray<RTCXThingTslProperty*> *properties = [[things getThingProfile] allPropertiesOfModel];
NSArray<RTCXThingTslEvents*> *events =  [[things getThingProfile] allEventsOfModel];
NSArray<RTCXThingTslService*> *services =  [[things getThingProfile] allServicesOfModel];
// 注意，此处拿到的 properties，events，services 是物的模型中的物的三要素。

获取设备状态

@protocol RTCXThingActions <NSObject>
/**
 获取物的生命周期
 说明：status表示设备生命周期，目前有以下几个状态，0:未激活；1：上线；3：离线；8：禁用；
 @param **handler 结果回调函数
 */
- (void)getStatus:(RTCXThingActionsResponseHandler)handler;
@end

调用示例如下：

[[[kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId] getThingActions] getStatus:^(RTCXThingActionsResponse * _Nullable response) {
            
 }];

获取物的模型

@protocol RTCXThingActions <NSObject>
/**
 获取物的模型
 @param handler 结果回调函数
 */
- (void)getTsl:(RTCXThingActionsResponseHandler)handler;
@end

调用示例如下：

[[[kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId] getThingActions] getTsl:^(RTCXThingActionsResponse * _Nullable response) {
            
 }];

设备属性

@protocol RTCXThingActions <NSObject>
/**
 获取物的所有属性的当前值

 @param handler 结果回调函数，请参考 `RTCXThingActionsResponseHandler`
 */
- (void)getPropertiesFull:(RTCXThingActionsResponseHandler)handler;
/**
 获取物的所有属性的当前值
 @param extraData 附加控制属性  key:@"IotPerformanceId" 性能测试
 key:@"Channel", value: ChannelPolicyCloud ChannelPolicyLocal   ChannelPolicyLocalPrefer
 @param handler 结果回调函数，请参考 `RTCXThingActionsResponseHandler`
 */
- (void)getPropertiesV1:(NSDictionary* _Nullable)extraData
        responseHandler:(RTCXThingActionsResponseHandler _Nullable)handler;
/**
 设置物的属性值，可以同时设置一个或者多个属性
 
 @param params 属性 key-value 对， 格式如{"items":{"power":"on", temperature:30}}
 @param extraData 附加控制属性  key:@"IotPerformanceId" 性能测试
                            key:@"Channel", value: ChannelPolicyCloud ChannelPolicyLocal   ChannelPolicyLocalPrefer
                            key:@"QosLevel", value: Qos_CON Qos_NON
                            key:@"NeedRsp", value:TRUE FALSE
                            key:@"Flag", 用于commonservice flag参数
 @param handler 结果回调函数，请参考 `RTCXThingActionsResponseHandler
 */
- (void)setPropertiesV1:(NSDictionary * _Nonnull)params
              extraData:(NSDictionary* _Nullable)extraData
        responseHandler:(RTCXThingActionsResponseHandler _Nullable)handler;
@end

调用示例如下：

• 获取物的属性

[[self.things getThingActions] getPropertiesFull:^(RTCXThingActionsResponse * _Nullable response) {
        COMMON_PRINTF(@"");
    }];

• 设置物的属性

[[[kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId] getThingActions] setPropertiesV1:@{@"MotionDetectSensitivity":@(index)} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
            if (response.success) {
                [self showToast:@"设置灵敏度成功"];
            } else {
                [self showToast:@"设置灵敏度失败"];
            }
        }];

设备服务

@protocol RTCXThingActions <NSObject>
/**
 调用物提供的服务

 @param serviceIdentifier 服务的唯一标识符
 @param params 调用服务的入参，请参考物的模型 tsl，形如 {"arg1":"val1", "arg2":"val2"}
 @param handler 结果回调函数
 */
- (void)invokeService:(NSString * _Nonnull)serviceIdentifier
               params:(NSDictionary* _Nullable)params
      responseHandler:(RTCXThingActionsResponseHandler)handler;

/**
 调用物提供的服务
 
 @param serviceIdentifier 服务的唯一标识符
 @param params 调用服务的入参，请参考物的模型 tsl，形如 {"arg1":"val1", "arg2":"val2"}
 @param extraData 附加控制属性
     key:@"IotPerformanceId" 性能测试
     key:@"callType" "async":异步， "sync"同步调用
     key:@"Channel", value: ChannelPolicyCloud ChannelPolicyLocal   ChannelPolicyLocalPrefer
     key:@"QosLevel", value: Qos_CON Qos_NON
     key:@"NeedRsp", value: value:TRUE FALSE

 @param handler 结果回调函数
 */
- (void)invokeServiceV1:(NSString * _Nonnull)serviceIdentifier
                 params:(NSDictionary* _Nullable)params
              extraData:(NSDictionary* _Nullable)extraData
        responseHandler:(RTCXThingActionsResponseHandler _Nullable)handler;
@end

调用示例如下：

• PTZ 云台控制

// 获取物模型services中ptz参数配置
[[weakSelf.things getThingProfile].services enumerateObjectsUsingBlock:^(RTCXThingTslService * _Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
      if ([obj.identifier isEqualToString:@"StartPTZAction"]) {
           COMMON_PRINTF(@"PTZ控制物模型: %@",obj.inputData);
       }
 }];
 // PTZ步进转动 方向：0:"左", 1:"右", 2:"上", 3:"下",
 [[weakSelf.things getThingActions] invokeServiceV1:@"PTZActionControl" params:@{@"ActionType":@(),@"Step":@(10)} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
     COMMON_PRINTF(response.success?@"PTZ步进转动成功":@"PTZ步进转动失败");
 }];
// PTZ连续转动控制，调用服务时的入参，请参见物的模型 TSL 中 Service 的 inputData
[[weakSelf.things getThingActions] invokeServiceV1:@"StartPTZAction" params:@{@"ActionType":@(0),@"Speed":@(1)} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
      COMMON_PRINTF(response.success?@"PTZ控制成功":@"PTZ控制失败");
 }];
 // PTZ停止转动控制
 [[weakSelf.things getThingActions] invokeServiceV1:@"StopPTZAction" params:@{} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
      COMMON_PRINTF(response.success?@"停止PTZ成功":@"停止PTZ失败");
 }];

• 设备缩略图

- (NSString *)queryThumnail:(NSString *)iotId {
    NSString *picUrl = [self.thumnailDic valueForKey:iotId];
//    if (!picUrl) {
            [[[kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId] getThingActions] invokeServiceV1:@"GetDevPicture" params:@{@"definition":@(1),@"picType":@"jpg"} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
        if (response.success) {
            NSString *picUrl = [response.dataObject valueForKey:@"downloadUrl"];
            [self.thumnailDic setObject:picUrl forKey:iotId];
            
            __block NSUInteger index = 0;
            [self.devicelist enumerateObjectsUsingBlock:^(RTCXDeviceInfo  *_Nonnull obj, NSUInteger idx, BOOL * _Nonnull stop) {
                if ([obj.iotId isEqualToString:iotId]) {
                    index = idx;
                    *stop = YES;
                }
            }];
            dispatch_async(dispatch_get_main_queue(), ^{
                [self.tableView beginUpdates];
                [self.tableView reloadRowsAtIndexPaths:@[[NSIndexPath indexPathForRow:index inSection:0]] withRowAnimation:UITableViewRowAnimationFade];
                [self.tableView endUpdates];
            });
        } else {
            NSString *errorMsg = response.responseError.userInfo[NSLocalizedFailureReasonErrorKey];
//                    [self showToast:errorMsg];
        }
    }];
//    }
    return picUrl;
}

• 直播预连接

[[[kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId] getThingActions] invokeServiceV1:@"PreConnect" params:@{@"Stream":obj.deviceName,@"Channel":@(0),@"Protocol":@"rtc",@"App":obj.productKey} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
    if (response.success) {
        NSLog(@"PreConnect succeed -- %@",obj.nickName?:obj.deviceName);
    } else {
        NSString *errorMsg = response.responseError.userInfo[NSLocalizedFailureReasonErrorKey];
        [self showToast:errorMsg];
    }
 }];

• 双目联动

app选择广角镜头区域，控制云台镜头转向指定位置

//坐标系：左上角(0,0) 右向X正轴 向下Y正轴, X、Y范围0~10000
[[[kRTCXThingManager buildThing:self.curDevice.productKey deviceName:self.curDevice.deviceName iotId:self.curDevice.iotId] getThingActions] invokeServiceV1:@"PTZUnitedMove" params:@{@{@"X":@(lround(X)),@"Y":@(lround(Y)),@"ID":@(0)}} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
    COMMON_PRINTF(response.success?@"联动成功":@"联动失败");
}];

• 云录制计划

// BeginTime: 开始时间0~86399，EndTime：结束时间0~86399，DayOfWeek：重复周期（0：周日，1~6：周一~周六）
[[[kRTCXThingManager buildThing:self.device.productKey deviceName:self.device.deviceName iotId:self.device.iotId] getThingActions] setPropertiesV1:@{@"CloudRecordPlan":@[@{@"BeginTime":@(1),@"EndTime":@(123),@"DayOfWeek":@(1)}]} extraData:@{} responseHandler:^(RTCXThingActionsResponse * _Nullable response) {
 if (response.success) {
     [self showToast:@"设置云录像计划成功"];
     dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
         [weakSelf.navigationController popViewControllerAnimated:YES];
     });
 } else {
     [self showToast:@"设置云录像计划失败"];
 }
}];