物模型功能
更新时间：2025-01-09 11:06:01
物模型SDK提供了App端的物模型（属性、事件、服务），用来开发设备界面，实现手机对设备的查看和控制。
// 导入物模型SDK头文件
#import <RTCXThingCapability/RTCXThingCapability.h>
初始化物对象
- 初始化方法如下：
@interface RTCXThingManager : NSObject
/**
返回单例
@return 单例
*/
+ (instancetype)sharedManager;
/**
创建 Thing 对象，该对象会被加入管理者维护的物的队列中
@param iotId 物的唯一标识符， 该 id 是物在注册绑定时由云端颁发
@return 返回 Thing 对象
*/
- (RTCXThing *)buildThing:(NSString *)iotId;
/**
销毁 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];
// 获取物模型
RTCXThing *things = [kRTCXThingManager buildThing: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.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.iotId] getThingActions] getStatus:^(RTCXThingActionsResponse * _Nullable response) {
}];
获取物的模型
@protocol RTCXThingActions <NSObject>
/**
获取物的模型
@param handler 结果回调函数
*/
- (void)getTsl:(RTCXThingActionsResponseHandler)handler;
@end
调用示例如下：
[[[kRTCXThingManager buildThing: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.device.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) {
if ([[kRTCXThingManager buildThing:iotId] getThingProfile]) {
[[[kRTCXThingManager buildThing: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:obj.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:obj.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:@"设置云录像计划失败"];
}
}];