智能场景

更新时间:2024-08-22 08:33:39下载pdf

智能场景分为 一键执行场景自动化场景,本文分别简称为 场景自动化

  • 场景是用户添加动作,手动触发。
  • 自动化是由用户设定条件,当条件触发后自动执行设定的动作。

功能说明

涂鸦支持用户根据实际生活场景,通过设置气象或设备条件,当条件满足时,让一个或多个设备执行相应的任务。

类名 说明
ThingSmartScene 提供了单个场景的添加、修改、删除、执行四种操作,需要使用场景 ID 进行初始化,场景 ID 指的是 ThingSmartSceneModelsceneId 字段,可以从场景列表中查询。
ThingSmartSceneManager 主要提供了场景里条件、任务、设备、城市相关的所有数据,和场景列表数据查询。
ThingSmartScenePreConditionFactory 提供快捷创建自动化生效条件方法的工具类
ThingSmartSceneConditionFactory 提供快捷创建场景条件方法的工具类
ThingSmartSceneActionFactory 提供快捷创建场景动作方法的工具类
ThingSmartSceneConditionExprBuilder 提供快捷创建场景条件表达式方法的工具类

在使用智能场景相关的接口之前,您需要首先了解 场景条件场景任务 这两个概念。

场景条件

场景条件对应 ThingSmartSceneConditionModel 类,涂鸦支持以下条件类型:

  • 气象条件:包括温度、湿度、天气、PM2.5、空气质量、日落日出,用户选择气象条件时,可以选择当前城市。
  • 设备条件:指用户可预先选择一个设备的功能状态,当该设备达到该状态时,会触发当前场景里的任务,但同一设备不能同时作为条件和任务,避免操作冲突。
  • 定时条件:指可以按照指定的时间去执行预定的任务。

ThingSmartSceneConditionModel 对象

字段 类型 描述
defaultIconUrl String 条件默认图标
conditionId String 条件 ID
entityName String 条件名称
entityId String 条件为设备类型时,表示设备 ID
entityType Int 条件类型,例如:
  • 一键执行:99
  • 设备:1
  • 天气:3
  • 定时:6
  • Pir:7
  • 地理围栏:10
  • 家人回家:11
  • 安防:12
  • 持续时间计算:13
  • 日落日出:16
  • 能源:28
  • 结构体:30
entitySubIds String 除设备之外的其它条件标识,例如:
  • 温度:temp
  • 湿度:humidity
  • 天气:condition
  • PM 2.5:pm25
  • 空气质量:aqi
  • 日出日落:sunsetrise
  • 风速:windSpeed
condType Integer 条件匹配规则,例如:
  • 1:表达式匹配
  • 2:简单匹配
说明:该字段为了 Raw 类型数据而设置,Raw 类型 condType2
expr Array 条件 DP 表达式,例如:[["$temp","<",-40]]
iconUrl String 条件图标
exprDisplay String 副标题名称,例如 "温度 : 小于-40°F"
productId String 条件为设备类型时,表示设备产品 ID
productPic String 条件为设备类型时,表示设备产品图片
devDelMark Bool 条件为设备类型时,表示设备是否被移除
deleteDevIcon String 条件为设备类型时,表示设备被删除时的图标
extraInfo Dictionary 条件拓展属性

extraInfo 内部分属性定义如下:

字段 类型 描述
tempUnit String 当前温度单位
cityName String 城市名称
delayTime String 红外设备预置 持续时间 条件设定数值
percent Dictionary<String,String> 0%-100% 条件类型 DP 及对应百分值
percent1 Dictionary<String,String> 1%-100% 条件类型 DP 及对应百分值
members String 门锁条件家庭成员
timeWindow long 红外设备自定义 持续时间 的条件设定数值
calType String 红外设备自定义 持续时间 的条件类型标记
maxSeconds long 红外设备自定义 持续时间 的条件最大值
center Dictionary<String,Double> 地理围栏中心坐标
radius Int 地理围栏半径
geotitle String 地理围栏名称
windSpeedUnit String 风速单位
originTempUnit String 原始温度单位
dpScale Int 华氏度与摄氏度转换系数

场景任务

场景任务是指当该场景满足已经设定的气象或设备条件时,让一个或多个设备执行某种操作,对应 ThingSmartSceneActionModel 类。或者关闭、开启一个自动化。

新增场景时,场景条件和场景任务对象的创建,参考本文档末尾的示例。

ThingSmartSceneActionModel 对象

字段 类型 说明
actionId String 动作 ID
entityId String 设备 ID
entityName String 设备名称
actionDisplay String 动作展示信息
actionDisplayNew Dictionary 动作展示信息
actionExecutor String 动作类型。枚举:
  • ruleTrigger:触发场景
  • ruleEnable:启用场景
  • ruleDisable:禁用场景
  • appPushTrigger:推送消息
  • mobileVoiceSend:电话服务
  • smsSend:短信服务
  • deviceGroupDpIssue:执行群组
  • irIssue:执行红外设备
  • dpIssue:执行普通设备
  • delay:延时
  • irIssueVii:执行红外设备,执行参数为真实的红外控制码
  • toggle:执行切换开关动作
  • dpStep:执行步进动作
executorProperty Dictionary 动作执行信息
extraProperty Dictionary 动作额外信息

场景管理

查询简易场景列表

接口说明

接口会同时返回场景和自动化,您可以通过条件(conditions)字段是否为空数组来区分场景和自动化。该接口比 查询场景列表 数据更加轻量。

- (void)getSimpleSceneListWithHomeId:(long long)homeId
        success:(void(^)(NSArray<ThingSmartSceneModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)fetchSimpleSceneListDataWithHomeId:(long long)homeId {
    [[ThingSmartSceneManager sharedInstance] getSimpleSceneListWithHomeId:homeId success:^(NSArray<ThingSmartSceneModel *> *list) {
        NSLog(@"get simple scene list success = %@", list);
    } failure:^(NSError *error) {
        NSLog(@"get simple scene list error = %@", error);
    }];
}

Swift:

func getSimpleSceneList(homeId: Int64) {
   ThingSmartSceneManager.sharedInstance()?.getSimpleSceneList(withHomeId: homeId, success: { (sceneModelList) in
        if let sceneList = sceneModelList {
            print("get simple scene list success: \(sceneList)")
        }
   }, failure: { (error) in
        if let e = error {
            print("get simple scene list error: \(e)")
        }
   })
}

查询场景列表

接口说明

接口会同时返回场景和自动化,您可以通过条件(conditions)字段是否为空数组来区分场景和自动化。该接口不再更新,建议优先使用查询简易场景列表。

- (void)getSceneListWithHomeId:(long long)homeId
        success:(void(^)(NSArray<ThingSmartSceneModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

// 查询家庭下的场景列表
- (void)getSmartSceneList {
    [[ThingSmartSceneManager sharedInstance] getSceneListWithHomeId:homeId success:^(NSArray<ThingSmartSceneModel *> *list) {
        NSLog(@"get scene list success %@:", list);
    } failure:^(NSError *error) {
        NSLog(@"get scene list failure: %@", error);
    }];
}

Swift:

// 查询家庭下的场景列表
func getSmartSceneList() {
    ThingSmartSceneManager.sharedInstance()?.getSceneList(withHomeId: homeId, success: { (list) in
        print("get scene list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get scene list failure: \(e)")
        }
    })
}

查询场景详情

接口说明

- (void)fetchSceneDetailWithDetailParams:(TSceneDetailParams *)detailParams
                                 success:(ThingSceneGetModelCompletion)success
                                 failure:(ThingFailureError)failure;

参数说明

参数 说明
detailParams 请求详情参数对象
success 成功回调,返回 ThingSmartSceneModel 对象
failure 失败回调,返回错误信息

TSceneDetailParams 对象

参数 说明
sceneId 场景 ID
gid 家庭 ID
supportHome 是否支持家庭房间信息
  • 如果设置为 YES,会返回场景所在的房间
  • 如果设置为 NO,不会返回房间相关信息
ruleGenre 场景类型
  • 1:一键执行
  • 2:自动化

ThingSmartSceneModel 对象说明

字段 类型 描述
sceneId String 场景 ID
name String 场景名称
enabled Bool 自动化是否启用
stickyOnTop Bool 是否在首页显示
conditions Array 条件列表,ThingSmartSceneConditionModel 对象集合
statusConditions Array 状态条件列表,ThingSmartSceneConditionModel 对象集合
actions Array 动作列表,ThingSmartSceneActionModel 对象集合
preConditions Array 场景生效时间段,ThingSmartScenePreConditionModel 对象集合
coverIcon String 一键执行的图标
displayColor String 场景背景颜色
matchType ThingSmartConditionMatchType 条件匹配类型
  • ThingSmartConditionMatchAny: 匹配任一
  • ThingSmartConditionMatchAll: 匹配所有
subMatchType ThingSmartConditionSubMatchType 状态条件匹配类型
  • ThingSmartConditionSubMatchAny: 匹配任一
  • ThingSmartConditionSubMatchAll: 匹配所有
boundForPanel Bool 表示是否绑定面板,和 boundForWiFiPanel 有任一个属性为 true,就表示绑定面板
boundForWiFiPanel Bool 表示是否绑定面板,和 boundForPanel 有任一个属性为 true,就表示绑定面板
newLocalScene Bool 是否是同网关下的一键执行,已废弃
gwId String 接管场景的主网关设备 ID
panelType ThingSmartScenePanelType 面板支持选择设备类型
  • ThingSmartScenePanelTypeNonAllDevevice: 只能选择 Zigbee 子设备
  • ThingSmartScenePanelTypeAllDevices: 所有设备
localLinkage Bool 是否是同网关下的自动化
linkageType ThingLocalLinkageType 场景类型:
  • ThingLinkageTypeUnknow:云端
  • ThingLinkageTypeLocal:本地(单网关)
  • ThingLinkageTypeLan:局域网
arrowIconUrl String 场景箭头图标
outOfWork ThingSmartSceneWorkingStatus 场景状态:
  • ThingSmartSceneWorkingStatusFine:正常
  • ThingSmartSceneWorkingStatusInvalid:失效
  • ThingSmartSceneWorkingStatusException:异常
ruleGenre ThingSmartSceneRuleGenre 场景类型:
  • ThingSmartSceneRuleGenreManual:一键执行
  • ThingSmartSceneRuleGenreAuto:自动化

示例代码

Objc:

TSceneDetailParams *detailParams = [TSceneDetailParams new];
detailParams.sceneId = @"sceneID";
detailParams.gid = 123456;
detailParams.supportHome = NO;
detailParams.ruleGenre = ThingSmartSceneRuleGenreManual;

[[ThingSmartSceneManager sharedInstance] fetchSceneDetailWithDetailParams:detailParams success:^(ThingSmartSceneModel * _Nonnull scene) {
    
} failure:^(NSError *error) {
    
}];

Swift:

let detailParams = TSceneDetailParams.init();
detailParams.sceneId = "sceneID";
detailParams.gid = 123456;
detailParams.supportHome = false;
detailParams.ruleGenre = .manual;

ThingSmartSceneManager.sharedInstance().fetchSceneDetail(with: detailParams) { sceneModel in

} failure: { error in
    
}

查询条件列表

接口说明

查询的条件可以是温度、湿度、天气、PM2.5、日落日出等。

  • 设备也可作为条件。
  • 条件中的温度分为摄氏度和华氏度,根据需求传入需要的数据。
- (void)getConditionListWithFahrenheit:(BOOL)fahrenheit
        success:(void(^)(NSArray<ThingSmartSceneDPModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
fahrenheit
  • YES:使用华氏单位
  • NO:使用摄氏单位
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getConditionList {
    [[ThingSmartSceneManager sharedInstance] getConditionListWithFahrenheit:YES success:^(NSArray<ThingSmartSceneDPModel *> *list) {
        NSLog(@"get condition list success:%@", list);
    } failure:^(NSError *error) {
        NSLog(@"get condition list failure: %@", error);
    }];
}

Swift:

func getConditionList() {
    ThingSmartSceneManager.sharedInstance()?.getConditionList(withFahrenheit: true, success: { (list) in
        print("get condition list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get condition list failure: \(e)")
        }
    })
}

查询任务设备列表

接口说明

添加任务时,您需要查询任务的设备列表,用来选择执行相应的任务。

- (void)getActionDeviceListWithHomeId:(long long)homeId
        success:(void(^)(NSArray<ThingSmartDeviceModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getActionDeviceList {
    [[ThingSmartSceneManager sharedInstance] getActionDeviceListWithHomeId:homeId success:^(NSArray<ThingSmartDeviceModel *> *list) {
        NSLog(@"get action device list success:%@", list);
    } failure:^(NSError *error) {
        NSLog(@"get action device list failure: %@", error);
    }];
}

Swift:

func getActionDeviceList() {
    ThingSmartSceneManager.sharedInstance()?.getActionDeviceList(withHomeId: homeId, success: { (list) in
        print("get action device list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get action device list failure: \(e)")
        }
    })
}

查询条件设备列表

接口说明

添加条件时,除了温度、湿度、天气等这些气象条件可以作为任务执行条件外,设备也可以作为条件。即查询条件设备列表,然后选择一个设备执行相应的任务作为条件。

- (void)getConditionDeviceListWithHomeId:(long long)homeId
        success:(void(^)(NSArray<ThingSmartDeviceModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getConditionDeviceList {
    [[ThingSmartSceneManager sharedInstance] getConditionDeviceListWithHomeId:homeId success:^(NSArray<ThingSmartDeviceModel *> *list) {
        NSLog(@"get condition device list success:%@", list);
    } failure:^(NSError *error) {
        NSLog(@"get condition device list failure: %@", error);
    }];
}

Swift:

func getConditionDeviceList() {
    ThingSmartSceneManager.sharedInstance()?.getConditionDeviceList(withHomeId: homeId, success: { (list) in
        print("get condition device list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get condition device list failure: \(e)")
        }
    })
}

查询任务设备的 DP 列表

接口说明

添加或修改场景任务时,选择设备后,需要根据选择设备的 deviceId 查询设备 DP 列表,进而选择某一个 DP,即指定该设备执行该项任务。

- (void)getNewActionDeviceDPListWithDevId:(NSString *)devId
        success:(void(^)(NSArray<ThingSmartSceneCoreFeatureModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
devId 设备 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getActionDeviceDPList {
    [[ThingSmartSceneManager sharedInstance] getNewActionDeviceDPListWithDevId:@"your_device_id" success:^(NSArray<ThingSmartSceneCoreFeatureModel *> *list) {
        NSLog(@"get action device DP list success:%@", list);
    } failure:^(NSError *error) {
        NSLog(@"get action device DP list failure: %@", error);
    }];
}

Swift:

func getActionDeviceDPList() {
    ThingSmartSceneManager.sharedInstance()?.getNewActionDeviceDPListWithDevId(withDevId: "your_device_id", success: { (list) in
        print("get action device DP list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get action device DP list failure: \(e)")
        }
    })
}

查询条件设备的 DP 列表

接口说明

选择场景条件时,选择了设备,需要根据选择设备的 deviceId 查询设备 DP 列表,进而选择某一个 DP,即指定该设备执行该 DP 功能作为该场景的执行条件。


- (void)getCondicationDeviceDPListWithDevId:(NSString *)devId
        success:(void(^)(NSArray<ThingSmartSceneDPModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
devId 设备 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getCondicationDeviceDPList {
    [[ThingSmartSceneManager sharedInstance] getCondicationDeviceDPList:@"your_device_id" success:^(NSArray<ThingSmartSceneDPModel *> *list) {
        NSLog(@"get condition device DP list success:%@", list);
    } failure:^(NSError *error) {
        NSLog(@"get condition device DP list failure: %@", error);
    }];
}

Swift:

func getCondicationDeviceDPList() {
    ThingSmartSceneManager.sharedInstance()?.getCondicationDeviceDPList(withDevId: "your_device_id", success: { (list) in
        print("get condition device DP list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get condition device DP list failure: \(e)")
        }
    })
}

场景排序

接口说明

对已经存在的场景进行排序。

- (void)sortSceneWithHomeId:(long long)homeId
        sceneIdList:(NSArray<NSString *> *)sceneIdList
        success:(TYSuccessHandler)success
        failure:(TYFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
sceneIdList 排序后的场景 ID 数组
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void) sortScene {
    [[ThingSmartSceneManager sharedInstance] sortSceneWithHomeId:homeId sceneIdList:(NSArray<NSString *> *) success:^{
        NSLog(@"sort scene success");
    } failure:^(NSError *error) {
        NSLog(@"sort scene failure:%@", error);
    }];
}

Swift:

func sortScene() {
    ThingSmartSceneManager.sharedInstance()?.sortScene(withHomeId: homeId, sceneIdList: ["sceneId list"], success: {
        print("sort scene success")
    }, failure: { (error) in
        if let e = error {
            print("sort scene failure: \(e)")
        }
    })
}

查询场景背景图片列表

接口说明

查询场景支持的背景图片 URL 列表。

- (void)getSmartSceneBackgroundCoverWithsuccess:(TYSuccessList)success
        failure:(TYFailureError)failure;

参数说明

参数 说明
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getDefaultSceneCover {
    [[ThingSmartSceneManager sharedInstance] getSmartSceneBackgroundCoverWithsuccess:^(NSArray *list) {

    } failure:^(NSError *error) {

    }];
}

Swift:

func getDefaultSceneCover() {
    ThingSmartSceneManager.sharedInstance()?.getSmartSceneBackgroundCover(withsuccess: {(list) in

    }, failure: { (error) in

    })
}

查询场景城市信息

查询城市列表

接口说明

选择场景气象条件时,根据国家码查询城市列表,用户可以选择当前城市。countryCode 使用 isoCountryCode,例如 cn 代表中国。

如果用户来自非中国大陆地区的城市,建议根据经纬度查询城市信息,因为列表可能暂时不全。

- (void)getCityListWithCountryCode:(NSString *)countryCode
        success:(void(^)(NSArray<ThingSmartCityModel *> *list))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
countryCode 国家码,使用 isoCountryCode,例如 cn 代表中国
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getCityList {
    [[ThingSmartSceneManager sharedInstance] getCityListWithCountryCode:@"your_country_code" success:^(NSArray<ThingSmartCityModel *> *list) {
        NSLog(@"get city list success:%@", list);
    } failure:^(NSError *error) {
           NSLog(@"get city list failure: %@", error);
    }];
}

Swift:

func getCityList() {
    ThingSmartSceneManager.sharedInstance()?.getCityList(withCountryCode: "your_country_code", success: { (list) in
        print("get city list success: \(list)")
    }, failure: { (error) in
        if let e = error {
            print("get city list failure: \(e)")
        }
    })
}

根据经纬度查询城市信息

接口说明

- (void)getCityInfoWithLatitude:(NSString *)latitude
            longitude:(NSString *)longitude
            success:(void(^)(ThingSmartCityModel *model))success
            failure:(TYFailureError)failure;

参数说明

参数 说明
latitude 纬度
longitude 经度
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)getCityInfo {
    [[ThingSmartSceneManager sharedInstance] getCityInfoWithLatitude:@"your_location_latitude" longitude:@"your_location_longitude" success:^(ThingSmartCityModel *city) {
        NSLog(@"get city info success:%@", city);
    } failure:^(NSError *error) {
        NSLog(@"get city info failure:%@", error);
    }];
}

Swift:

func getCityInfo() {
    ThingSmartSceneManager.sharedInstance()?.getCityInfo(withLatitude: "your_location_latitude", longitude: "your_location_longitude", success: { (city) in
        print("get city info success: \(city)")
    }, failure: { (error) in
        if let e = error {
            print("get city info failure: \(e)")
        }
    })
}

根据城市 ID 查询城市信息

接口说明

根据城市 ID 查询城市信息,城市 ID 可以从城市列表查询。

- (void)getCityInfoWithCityId:(NSString *)cityId
        success:(void(^)(ThingSmartCityModel *model))success
        failure:(TYFailureError)failure;

参数说明

参数 说明
cityId 城市 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void) getCityInfo {
    [[ThingSmartSceneManager sharedInstance] getCityInfoWithCityId:@"your_city_id" success:^(ThingSmartCityModel *city) {
        NSLog(@"get city info success:%@", city);
    } failure:^(NSError *error) {
        NSLog(@"get city info failure:%@", error);
    }];
}

Swift:

func getCityInfo() {
    ThingSmartSceneManager.sharedInstance()?.getCityInfo(withCityId: "your_city_id", success: { (city) in
        print("get city info success: \(city)")
    }, failure: { (error) in
        if let e = error {
            print("get city info failure: \(e)")
        }
    })
}

场景操作

ThingSmartScene 提供了单个场景的添加、修改、删除、执行四种操作,您需要使用场景 ID 进行初始化。场景 ID 指的是 ThingSmartSceneModelsceneId 字段,您可以从场景列表中查询。

添加场景

接口说明

添加场景需要传入场景名称、家庭 ID、背景图片的 URL、决定是否显示在首页、相关的前置条件列表(生效时间段)、条件列表、任务列表(至少一个任务)、满足任一条件还是满足所有条件时执行等。

您也可以只设置名称、任务、背景图片,但不设置条件,这就需要用户手动执行场景。

+ (void)addNewSceneWithName:(NSString *)name
                    homeId:(long long)homeId
                background:(NSString *)background
            showFirstPage:(BOOL)showFirstPage
        preConditionList:(NSArray<ThingSmartScenePreConditionModel*> *)preConditionList
            conditionList:(NSArray<ThingSmartSceneConditionModel*> *)conditionList
                actionList:(NSArray<ThingSmartSceneActionModel*> *)actionList
                matchType:(ThingSmartConditionMatchType)matchType
                    success:(void (^)(ThingSmartSceneModel *sceneModel))success
                    failure:(TYFailureError)failure;

参数说明

参数 说明
name 场景名
homeId 家庭 ID
background 背景图 URL,只能使用 查询场景背景图片列表 接口中提供的背景图
showFirstPage 是否显示在首页标识
preConditionList 生效时间段,以前置条件数组的形式传入
conditionList 条件数组
actionList 动作数组
matchType 条件的匹配逻辑,可以是 或者
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)addSmartScene {

    [ThingSmartScene addNewSceneWithName:@"your_scene_name" homeId:homeId background:@"background_url" showFirstPage:YES conditionList:(NSArray<ThingSmartSceneConditionModel *> *) actionList:(NSArray<ThingSmartSceneActionModel *> *) matchType:ThingSmartConditionMatchAny success:^(ThingSmartSceneModel *sceneModel) {
        NSLog(@"add scene success %@:", sceneModel);
    } failure:^(NSError *error) {
        NSLog(@"add scene failure: %@", error);
    }];
}

Swift:

func addSmartScene() {
    ThingSmartScene.addNewScene(withName: "your_scene_name", homeId: homeId, background: "background_url", showFirstPage: true, conditionList: [ThingSmartSceneConditionModel]!, actionList: [ThingSmartSceneActionModel]!, matchType: ThingSmartConditionMatchAny, success: { (sceneModel) in
        print("add scene success :\(sceneModel)")
    }) { (error) in
        if let e = error {
            print("add scene failure: \(e)")
        }
    }
}

修改场景

接口说明

修改场景的名称、背景图、前置条件(生效时间段)、条件列表、任务列表、满足任一条件还是满足所有条件时执行。

- (void)modifySceneWithName:(NSString *)name
                background:(NSString *)background
            showFirstPage:(BOOL)showFirstPage
        preConditionList:(NSArray<ThingSmartScenePreConditionModel*> *)preConditionList
            conditionList:(NSArray<ThingSmartSceneConditionModel*> *)conditionList
                actionList:(NSArray<ThingSmartSceneActionModel*> *)actionList
                matchType:(ThingSmartConditionMatchType)matchType
                    success:(TYSuccessHandler)success
                    failure:(TYFailureError)failure;

参数说明

参数 说明
name 场景名
background 背景图 URL,只能使用 查询场景背景图片列表 接口中提供的背景图
showFirstPage 是否显示在首页标识
preConditionList 生效时间段,以前置条件数组的形式传入
conditionList 条件数组
actionList 动作数组
matchType 条件的匹配逻辑,可以是 AND)或者 OR
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)modifySmartScene {
//    self.smartScene = [ThingSmartScene sceneWithSceneId:@"your_scene_id"];
    [self.smartScene modifySceneWithName:name background:@"background_url" showFirstPage:YES condition:(NSArray<ThingSmartSceneConditionModel *> *) actionList:(NSArray<ThingSmartSceneActionModel *> *) matchType:ThingSmartConditionMatchAny success:^{
        NSLog(@"modify scene success");
    } failure:^(NSError *error) {
        NSLog(@"modify scene failure: %@", error);
    }];
}

Swift:

func modifySmartScene() {
    smartScene?.modifyScene(withName: "name", background: "background_url", showFirstPage: true, conditionList: [ThingSmartSceneConditionModel]!, actionList: [ThingSmartSceneActionModel]!, matchType: ThingSmartConditionMatchAny, success: {
        print("modify scene success")
    }, failure: { (error) in
        if let e = error {
            print("modify scene failure: \(e)")
        }
    })
}

删除场景

接口说明

- (void)deleteSceneWithHomeId:(long long)homeId
                      success:(TYSuccessBOOL)success
                      failure:(TYFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)deleteSmartScene {
//    self.smartScene = [ThingSmartScene sceneWithSceneId:@"your_scene_id"];
    long long homeId = your home id;
    [self.smartScene deleteSceneWithHomeId:homeId success:^{
        NSLog(@"delete scene success");
    } failure:^(NSError *error) {
        NSLog(@"delete scene failure: %@", error);
    }];
}

Swift:

func deleteSmartScene() {
    var homeId = your home id
    smartScene?.delete(homeId:homeId, success: {
        print("delete scene success")
    }, failure: { (error) in
        if let e = error {
            print("delete scene failure: \(e)")
        }
    })
}

执行场景

接口说明

该接口只负责发送指令到云端执行场景,具体设备执行成功与否可以参考 设备代理监听 来监听设备的 DP 变化。

- (void)executeSceneWithSuccess:(TYSuccessHandler)success
        failure:(TYFailureError)failure;

参数说明

参数 说明
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)executeSmartScene {
//    self.smartScene = [ThingSmartScene sceneWithSceneId:@"your_scene_id"];
    [self.smartScene executeSceneWithSuccess:^{
           NSLog(@"execute scene success");
    } failure:^(NSError *error) {
        NSLog(@"execute scene failure: %@", error);
    }];
}

Swift:

func executeSmartScene() {
    smartScene?.execute(success: {
        print("execute scene success")
    }, failure: { (error) in
        if let e = error {
            print("execute scene failure: \(e)")
        }
    })
}

开启自动化场景

只有自动化场景才可以开启和失效。

接口说明

- (void)enableSceneWithSuccess:(TYSuccessHandler)success
        failure:(TYFailureError)failure;

参数说明

参数 说明
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)enableSmartScene {
//    self.smartScene = [ThingSmartScene sceneWithSceneId:@"your_scene_id"];
    [self.smartScene enableSceneWithSuccess:^{
           NSLog(@"enable scene success");
    } failure:^(NSError *error) {
        NSLog(@"enable scene failure: %@", error);
    }];
}

Swift:

func enableSmartScene() {
    smartScene?.enable(success: {
        print("enable scene success")
    }, failure: { (error) in
        if let e = error {
            print("enable scene failure: \(e)")
        }
    })
}

失效自动化场景

接口说明

使一个自动化场景失效,不再自动执行。

- (void)disableSceneWithSuccess:(TYSuccessHandler)success
        failure:(TYFailureError)failure;

参数说明

参数 说明
success 接口发送成功回调
failure 接口发送失败回调,error 表示失败原因

示例代码

Objc:

- (void)disableSmartScene {
//    self.smartScene = [ThingSmartScene sceneWithSceneId:@"your_scene_id"];
    [self.smartScene disableSceneWithSuccess:^{
           NSLog(@"disable scene success");
    } failure:^(NSError *error) {
        NSLog(@"disable scene failure: %@", error);
    }];
}

Swift:

func disableSmartScene() {
    smartScene?.disableScene(success: {
        print("disable scene success")
    }, failure: { (error) in
        if let e = error {
            print("disable scene failure: \(e)")
        }
    })
}

监听场景信息变更

接口说明

添加、修改、删除、执行、开启、失效场景操作的监听回调方法。

- (void)sceneManager:(ThingSmartSceneManager *)manager state:(NSString *)state sceneId:(NSString *)sceneId;

参数说明

参数 说明
ThingSmartSceneManager 场景数据管理类,可以使用该类查询场景列表数据
state 状态变化字符串,例如:
  • update:更新
  • disable:关闭自动化
sceneId 场景 ID

示例代码

Objc:

- (void)sceneManager:(ThingSmartSceneManager *)manager state:(NSString *)state sceneId:(NSString *)sceneId {
    if ([state isEqualToString:@"update"]) {
        NSLog(@"update scene list");
    }
}

Swift:

func sceneManager(_ manager: ThingSmartSceneManager!, state: String!, sceneId: String!) {
    if state == "update" {
        print("reload scene list")
    }
}

场景日志

查询家庭下是否有新产生的场景执行日志

接口说明

检查用户在当前家庭下是否产生新的场景日志。

- (void)hasNewLogsWithHomeId:(long long)homeId success:(nullable ThingSuccessBOOL)success failure:(nullable ThingFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
success 成功回调,如果有新日志产生返回 YES,否则返回 NO
failure 失败回调

查询场景日志列表

接口说明

获取所有场景联动日志,包括场景执行成功或失败的提醒,推送信息等。

- (void)getSmartSceneLogWithHomeId:(long long)homeId
                         startTime:(long long)startTime
                           endTime:(long long)endTime
                              size:(NSInteger)size
                            lastId:(NSString *)lastId
                    lastRecordTime:(long long)lastRecordTime
                           success:(ThingSceneLogCompletion)success
                           failure:(ThingFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
startTime 日志记录的开始时间
endTime 日志记录的截止时间
size 分页获取的数据条数
lastId 上一次获取日志的最后一条数据的 eventId,用于分页加载更多数据
lastRecordTime 上一次获取日志的最后一条数据的 execTime,用于分页加载更多数据
success 成功回调,返回 ThingSmartSceneLogModel 对象
failure 失败回调,返回失败结果

返回参数说明

ThingSmartSceneLogModel 对象

参数 说明
datas ThingSmartSceneLogData 对象数组
totalCount 数组总条数

ThingSmartSceneLogData 对象

字段 类型 描述
eventId String 日志 ID
ownerId String 场景所在的家庭 ID
ruleId String 场景 ID
ruleName String 场景名称
runMode string 场景执行模式。
  • local:表示场景本地执行
  • cloud:表示场景云端执行
sceneType int 场景类型
  • 1:一键执行
  • 2:自动化
uid String 用户 ID
execTime long 执行时间
detailTime String 执行信息
execResult int 执行结果码
  • 0:执行失败
  • 1:执行成功
  • 2:部分成功
  • 3:正在执行中
execResultMsg String 执行结果信息
failureCode int 错误码
failureCause String 错误信息

查询设备相关场景日志

接口说明

获取设备相关的场景日志列表。

- (void)getSmartSceneLogOfDeviceWithDevId:(NSString *)devId
                                   homeId:(long long)homeId
                                startTime:(long long)startTime
                                  endTime:(long long)endTime
                                     size:(NSInteger)size
                                   lastId:(NSString *)lastId
                           lastRecordTime:(long long)lastRecordTime
                                  success:(ThingSceneLogCompletion)success
                                  failure:(ThingFailureError)failure;

参数说明

参数 说明
devId 设备 ID
homeId 家庭 ID
startTime 日志记录的开始时间
endTime 日志记录的截止时间
size 分页获取的数据条数
lastId 上一次获取日志的最后一条数据的 eventId,用于分页加载更多数据
lastRecordTime 上一次获取日志的最后一条数据的 execTime,用于分页加载更多数据
success 成功回调,返回 ThingSmartSceneLogModel 对象
failure 失败回调,返回失败结果

查询日志详情

接口说明

- (void)getSmartSceneLogDetailWithHomeId:(long long)homeId
                                 eventId:(NSString *)eventId
                               startTime:(long long)startTime
                                 endTime:(long long)endTime
                              returnType:(long long)returnType
                                 success:(ThingSceneLogDetailListCompletion)success
                                 failure:(ThingFailureError)failure;

参数说明

参数 说明
homeId 家庭 ID
eventId 日志 ID
startTime 日志记录的开始时间
endTime 日志记录的截止时间
returnType
  • 1:获取所有日志信息
  • 0:只返回错误的日志信息
success 成功回调,返回 ThingSmartSceneLogDetailModel 对象数组
failure 失败回调,返回失败结果

返回参数说明

ThingSmartSceneLogDetailModel 对象

参数 说明
actionEntityId 执行动作的实体 ID,例如,设备 ID
actionEntityName 执行动作的名称
actionEntityUrl 执行动作的图标
actionExecutor 动作执行器描述
actionId 动作 ID
errorCode 错误码
errorMsg 错误信息描述
execStatus 执行状态
executeTime 日志执行时间

创建示例

  • 如果您使用的是 3.14.0 以前的版本,请参照以下示例创建条件和动作。

  • 如果您使用的是 3.14.0 及以上版本,推荐使用 ThingSmartSceneDataFactory 提供的工具类创建条件和动作。智能生活 App SDK 在 3.14.0 及以上版本加入了 ThingSmartSceneDataFactory 这个工具类集合,用于便捷的创建场景的条件、动作、生效时间段条件。

创建场景条件对象

场景条件对象为:ThingSmartSceneConditionModel

  • 气象条件包括温度、湿度、天气、PM2.5、空气质量、日落日出,这里以设置温度条件为例创建气象条件对象。
  • 场景条件也可以设置定时条件和设备条件。

查询条件列表 接口可以查询到所有气象条件的 ThingSmartSceneDPModel 对象列表。可以根据 ThingSmartSceneDPModel 对象的 entityNameentityId 区分不同的气象条件。从查询城市信息相关的接口,查询到 ThingSmartCityModel 对象,使用其中的 cityId 值作为定位信息。

选择完具体的条件值之后,如果将界面选择的温度、城市等信息保存在了 ThingSmartSceneDPModel 对象中,或者您设置的对象中。您可以通过一个 ThingSmartSceneDPModel 对象初始化一个 ThingSmartSceneConditionModel 条件对象,示例方法如下,这里使用了 ThingSmartSceneConditionModel 增加了一个分类方法:

//新增初始化方法
- (instancetype)initWithSmartSceneDPModel:(ThingSmartSceneDPModel *)dpModel {

    if (self = [super init]) {
        self.entityType = dpModel.entityType;
        self.iconUrl = dpModel.iconUrl;
        if (dpModel.entityType == 3) {
            //气象条件
            self.entityId = dpModel.cityId;
            self.entityName = dpModel.cityName;
            self.entitySubIds = dpModel.entitySubId;
            self.cityName = dpModel.cityName;
            self.cityLatitude = dpModel.cityLatitude;
            self.cityLongitude = dpModel.cityLongitude;
        } else if (dpModel.entityType == 7) {
            //定时条件
            NSString *value = dpModel.valueRangeJson[dpModel.selectedRow][0];
            self.extraInfo = @{@"delayTime" : value};
        } else {
            //设备条件
            self.entityId = dpModel.devId;
            ThingSmartDevice *device = [ThingSmartDevice deviceWithDeviceId:dpModel.devId];
            self.entityName = device.deviceModel.name;
            self.entitySubIds = [NSString stringWithFormat:@"%ld", (long)dpModel.dpId];
        }
        //expr 数组的组装见下文
        self.expr = dpModel.expr;
    }
    return self;
}

组装场景条件对象 expr 表达式

ThingSmartSceneConditionModel 的 expr 属性描述了条件的表达式,如 温度低于 15℃ 这样的一个条件,就可以用 expr 来描述。

expr 是一个数组(请注意,最外层一定是数组),数组中的每一个对象描述了一个条件,如 @[@"$temp",@"<",@15] 这个条件数组就描述了温度低于 15℃ 这个条件。

每个气象条件都应该对应一个 ThingSmartSceneConditionModel,所以 expr 数组中只包含一个条件数组。

  • 气象条件 expr 示例:

    • 温度 @[@[@"$temp",@"<",@15]]
    • 湿度 @[@[@"$humidity",@"==",@"comfort"]]
    • 天气 @[@[@"$condition",@"==",@"snowy"]]
    • PM2.5 @[@[@"$pm25",@"==",@"fine"]]
    • 空气质量 @[@[@"$aqi",@"==",@"fine"]]
    • 日出日落 @[@[@"$sunsetrise",@"==",@"sunrise"]]
  • 定时条件 expr 示例:

    定时条件使用一个字典表示,例如 {timeZoneId = "Asia/Shanghai",loops = "0000000",time = "08:00",date = "20180308"}。其中 loops 中的每一位分别表示周日到周六的每一天,1 表示生效,0 表示不生效。注意这个表示定时的字典也需要使用数组包起来,因为 expr 是个数组。

  • 设备条件 expr 示例:

    设备条件使用一个数组表示选定的条件值。选择的条件组装的 expr 可以表示为 @[@[@"$dp1",@"==",@YES]] ,这里可以表示一个“电灯开”的条件。其中 dp1ThingSmartSceneDPModel 中提供的 DP 的名称。

场景动作

场景动作类是 ThingSmartSceneActionModel,其中的 actionExecutor 属性即表示场景动作类型。场景动作类型包括:

  • dpIssue:设备
  • deviceGroupDpIssue:群组
  • ruleTrigger:触发场景
  • ruleEnable:启动自动化
  • ruleDisable:禁用自动化
  • delay:延时动作

新建完 ThingSmartSceneActionModel 的对象后,分别设置对应的属性,重点关注三个属性 entityIdactionExecutorexecutorProperty,这三个属性描述了哪个对象要做动作,做什么类型的动作,具体做什么动作。

场景动作类型 说明
设备
  • entityId 属性对应设备的 devId
  • actionExecutor 是 dpIssue
  • executorProperty 是一个字典,比如 {“1”:YES} ,表示 DP “1”,执行的动作是 YES,这个可以表示灯打开等布尔类型的 DP。DP 的 ID 和 DP 可取的值可以通过“查询任务设备的 DP 列表”接口查询到。
群组
  • entityId 属性对应群组的 groupId
  • actionExecutor 是 deviceGroupDpIssue
  • 其他的属性和设备动作相同
触发场景
  • entityId 是场景 sceneId
  • actionExecutor 是 ruleTrigger
  • executorProperty 不需要
启动自动化
  • entityId 是自动化 sceneId
  • actionExecutor 是 ruleEnable
  • executorProperty 不需要
禁用自动化
  • entityId 是自动化 sceneId
  • actionExecutor 是 ruleDisable
  • executorProperty 不需要
延时动作
  • entityId 是 delay
  • actionExecutor 是 delay
  • executorProperty 是延时的时间,用一个字典表示,形式和 key 为 {@"minutes":@"1",@"seconds":@"30"} ,表示 1 分 30 秒。目前最大支持 5 小时,即 300 分钟。

ThingSmartSceneDataFactory 工具类集合

ThingSmartSceneDataFactory 中包涵以下创建工具类:

类名 说明
ThingSmartScenePreConditionFactory 用于创建自动化场景的前置条件,如生效时间段。
ThingSmartSceneConditionFactory 用于创建自动化场景的条件,如天气条件、设备条件。
ThingSmartSceneActionFactory 用于创建场景动作,如设备动作。

以及两个辅助类:

类名 说明
ThingSmartSceneExprModel 用于储存场景条件中的 expr 表达式。
ThingSmartSceneConditionExprBuilder 自动化场景中条件表达式的生成工具类。

生效时间段、条件、动作的创建,所有支持的类型可以参照 SDK 头文件中的注释使用。注意:因为要适配多语言,条件和动作中,未生成用来显示条件和动作的详情的 exprDisplayactionDisplayNew,需要开发者根据条件中的表达式 expr 和动作中的执行参数 executorProperty 手动拼接生成。

使用示例

以创建一个开关类型的设备条件为例,使用顺序如下:

  1. 使用 ThingSmartSceneConditionExprBuilder 创建一个 ThingSmartSceneExprModel 对象,生成创建条件所需的表达式expr
  2. 使用 ThingSmartSceneConditionFactory 中的 API,传入第一步中生成的 ThingSmartSceneExprModel 对象以及其他必需参数,生成条件对象。

接口说明

//创建 exprModel
+ (ThingSmartSceneExprModel *)createBoolExprWithType:(NSString *)type
        isTrue:(BOOL)isTrue
        exprType:(ExprType)exprType;

参数说明

参数 说明
type 天气类型或者设备 DP ID
isTrue 布尔值参数
exprType 区分创建的是天气类型还是设备类型的枚举值

接口说明

//创建一个设备条件。
+ (ThingSmartSceneConditionModel *)createDeviceConditionWithDevice:(ThingSmartDeviceModel *)device
        dpModel:(ThingSmartSceneDPModel *)dpModel
        exprModel:(ThingSmartSceneExprModel *)exprModel;

参数说明

参数 说明
device 设备模型
dpModel 要创建的设备条件的 dpModel,如设备下开关这个 DP 的 dpModel
exprModel 使用 ThingSmartSceneConditionExprBuilder 创建的 model 对象

示例代码

ThingSmartSceneExprModel *exprModel = [ThingSmartSceneConditionExprBuilder createBoolExprWithType:dpModel.entitySubId
        isTrue:YES
        exprType:exprType];
ThingSmartSceneConditionModel *conditionModel = [ThingSmartSceneConditionFactory createDeviceConditionWithDevice:deviceModel
        dpModel:self.model
        exprModel:exprModel];

生成前置条件和动作直接使用 ThingSmartScenePreConditionFactoryThingSmartSceneActionFactory 中提供的 API 即可。