Smart App SDK智能生活 App SDKiOS 开发指南业务拓展 SDK场景创建

场景创建

更新时间：2023-10-31 03:15:38下载pdf

场景基座主要介绍场景条件、场景条件表达式、场景动作和场景生效时间段的各类型创建方法。

主要类和类功能介绍：

类名	说明
ThingSmartSceneConditionFactory	提供快捷创建场景条件方法的工具类
ThingSmartSceneConditionExprBuilder	提供快捷创建场景条件表达式方法的工具类
ThingSmartSceneActionFactory	提供快捷创建场景动作方法的工具类
ThingSmartScenePreConditionFactory	提供快捷创建自动化生效条件方法的工具类

场景条件创建

场景条件对应 ThingSmartSceneConditionModel 类，涂鸦支持以下条件类型：

气象条件：包括温度、湿度、天气、PM2.5、空气质量、日落日出。用户选择气象条件时，可以选择当前城市。
设备条件：指用户可预先选择一个设备的功能状态，当该设备达到该状态时，会触发当前场景里的任务。但同一设备不能同时作为条件和任务，避免操作冲突。
定时条件：指可以按照指定的时间去执行预定的任务。
传感类 PIR 条件：设备条件衍生的一种条件类型，主要针对传感类设备。例如，人体传感器监测 2 分钟无人移动。
地理围栏条件：当进入或离开设定的地理围栏区域，触发场景动作任务。
家人回家条件：当某个家庭成员回家时，自动触发场景动作，主要针对门锁设备。
计算型条件：设备条件衍生的一种条件类型，设备某个功能点加上持续时间。例如，红外移动传感器检测到没有人移动，持续 10 分钟。
日落日出前后几分钟条件：天气中日落日出衍生出的一类条件类型，可以在日落日出的前后某段时长内判断条件是否触发。

条件模型

ThingSmartSceneConditionModel 字段说明

参数	类型	是否必须	说明
conditionId	string	否	条件 ID
entityId	string	是	条件实体 ID
entityType	ThingConditionAutoType	是	条件类型
entitySubIds	string	是	条件实体子 ID，可能包含多个值，中间以逗号隔开
expr	array	是	条件表达式
extraInfo	dictionary	否	条件扩展参数
iconUrl	string	否	条件图标地址
condType	ThingSConditionExpressionType	是	条件表达式类型，分为简单匹配和精准匹配

ThingConditionAutoType 枚举

枚举类型	枚举值	说明
AutoTypeDevice	1	设备类型
AutoTypeWhether	3	天气类型
AutoTypeTimer	6	定时类型
AutoTypePir	7	PIR 类型
AutoTypeGeofence	10	地理围栏类型
AutoTypeLockMemberGoHome	11	家人回家类型
AutoTypeConditionCalculate	13	设备持续时间类型
AutoTypeSunsetriseTimer	16	日落日出前后几分钟
AutoTypeManual	99	一键执行类型，占位使用无业务意义

ThingSConditionExpressionType 枚举

枚举类型	枚举值	说明
ThingSConditionExpressionTypePrecise	1	表达式精准匹配
ThingSConditionExpressionTypeSimple	2	表达式简单匹配，当 DP 类型为 string 或 raw 时，才使用该枚举

条件 DP 模型

获取天气条件的 DP 数据调用 getAllConditionListWithFahrenheit:windSpeedUnit:homeId:success:failure 或 getConditionCategoryListWihtHomeId:conditionCategoryParams:success:failure。
获取设备条件的 DP 数据调用 getCondicationDeviceDPListWithDevId:success:failure。
场景条件设备和天气的 DP 对象模型对应 ThingSmartSceneDPModel。

ThingSmartSceneDPModel 字段说明

参数	类型	是否必须	说明
entityId	string	是	产品 ID。设备 DP 有值，天气无值。
entitySubId	string	是	DP ID。天气 DP ID： `temp`：温度 `humidity`：湿度 `condition`：天气 `pm25`：PM2.5 `aqi`：空气质量指数 `windSpeed`：风速 `sunsetrise`：日出日落
entityName	string	是	DP 名称。
entityType	int	是	DP 对应可创建的条件类型。例如： `1`：表示可建设备条件 `3`：表示可建天气条件 `7`：表示可建设备传感 PIR 条件
valueRangeJson	array	否	DP 取值范围。天气和设备 DP 类型为 enum 有值。
dpModel	ThingSmartSchemaModel	是	DP 详细信息模型。
operators	string	否	操作符字符串。例如 `"[\"==\"]"`。

ThingSmartSchemaModel 字段说明

参数	类型	是否必须	说明
dpId	string	是	DP ID
code	string	是	DP 功能标识符，又称 DP code
name	string	是	DP 功能名称
mode	string	是	DP 数据传输模式 `rw`：可下发可上报 `ro`：只上报 `wr`：只下发
property	ThingSmartSchemaPropertyModel	是	DP 功能属性信息模型

ThingSmartSchemaPropertyModel 字段说明

参数	类型	是否必须	说明
type	string	是	DP 类型，bool、enum、value、string、raw
unit	string	否	DP 单位，例如温度单位 ℃ 和 ℉
min	double	否	DP 最小值
max	double	否	DP 最大值
step	double	否	DP 步进值
scale	int	否	DP 倍数
range	array	否	DP 取值范围

创建设备条件

接口说明

+ (ThingSmartSceneConditionModel *)createDeviceConditionWithDevice:(ThingSmartDeviceModel *)device
                                                           dpModel:(ThingSmartSceneDPModel *)dpModel
                                                         exprModel:(ThingSmartSceneExprModel *)exprModel

参数说明

参数	类型	说明
device	ThingSmartDeviceModel	设备模型
dpModel	ThingSmartSceneDPModel	DP 模型
exprModel	ThingSmartSceneExprModel	表达式模型

示例代码

Objective-C：

- (void)buildDeviceCondition {
    ThingSmartSceneExprModel *deviceValueExpr = [ThingSmartSceneConditionExprBuilder createValueExprWithType:@"1" operater:@"==" chooseValue:1000 exprType:kExprTypeDevice];
    ThingSmartSceneDPModel *dpModel = [[ThingSmartSceneDPModel alloc] init];
    ThingSmartDeviceModel *deviceModel = [[ThingSmartDeviceModel alloc] init];

    ThingSmartSceneConditionModel *conditionModel = [ThingSmartSceneConditionFactory createDeviceConditionWithDevice:deviceModel dpModel:dpModel exprModel:deviceValueExpr];
}

Swift：

func buildDeviceCondition() {
    let deviceValueExpr = ThingSmartSceneConditionExprBuilder.createValueExpr(withType: "1", operater: "==", chooseValue: 1000, exprType: .device)
    let dpModel = ThingSmartSceneDPModel()
    let deviceModel = ThingSmartDeviceModel()
    let conditionModel = ThingSmartSceneConditionFactory.createDeviceCondition(withDevice: deviceModel, dpModel: dpModel, exprModel: deviceValueExpr)
}

创建天气条件

天气条件需要城市信息，获取城市信息可以调用 getCityInfoWithLatitude:longitude:success:failure 或getCityInfoWithCityId:success:failure。

接口说明

+ (ThingSmartSceneConditionModel *)createWhetherConditionWithCity:(ThingSmartCityModel *)city
                                                          dpModel:(ThingSmartSceneDPModel *)dpModel
                                                        exprModel:(ThingSmartSceneExprModel *)exprModel;

参数说明

参数	类型	说明
city	ThingSmartCityModel	城市信息模型
dpModel	ThingSmartSceneDPModel	DP 模型
exprModel	ThingSmartSceneExprModel	表达式模型

示例代码

Objective-C：

- (void)buildWeatherCondition {
    ThingSmartSceneExprModel *weatherEnumExpr = [ThingSmartSceneConditionExprBuilder createEnumExprWithType:@"789" chooseValue:@"1000" exprType:kExprTypeWhether];
    ThingSmartCityModel *cityModel = [[ThingSmartCityModel alloc] init];
    ThingSmartSceneDPModel *dpModel = [[ThingSmartSceneDPModel alloc] init];

    ThingSmartSceneConditionModel *weatherCondition = [ThingSmartSceneConditionFactory createWhetherConditionWithCity:cityModel dpModel:dpModel exprModel:weatherEnumExpr];
}

Swift：

func buildWeatherCondition() {
    let weatherEnumExpr = ThingSmartSceneConditionExprBuilder.createEnumExpr(withType: "789", chooseValue: "1000", exprType: .whether)
    let cityModel = ThingSmartCityModel()
    let dpModel = ThingSmartSceneDPModel()
    let weatherCondition = ThingSmartSceneConditionFactory.createWhetherCondition(withCity: cityModel, dpModel: dpModel, exprModel: weatherEnumExpr)
}

创建定时条件

接口说明

+ (ThingSmartSceneConditionModel *)createTimerConditionWithExprModel:(ThingSmartSceneExprModel *)exprModel;

参数说明

参数	类型	说明
exprModel	ThingSmartSceneExprModel	表达式模型

示例代码

Objective-C：

- (void)buildTimerCondition {
    ThingSmartSceneExprModel *timeExpr = [ThingSmartSceneConditionExprBuilder createTimerExprWithTimeZoneId:[NSTimeZone defaultTimeZone].name loops:@"1111111" date:@"20231010" time:@"20:30"];

    ThingSmartSceneConditionModel *timerCondition = [ThingSmartSceneConditionFactory createTimerConditionWithExprModel:timeExpr];
}

Swift：

func buildTimerCondition() {
    let timeExpr = ThingSmartSceneConditionExprBuilder.createTimerExpr(withTimeZoneId: NSTimeZone.default.identifier, loops: "1111111", date: "20231010", time: "20:30")
    let timerCondition = ThingSmartSceneConditionFactory.createTimerCondition(with: timeExpr)
}

创建传感类 PIR 条件

传感类的条件可以判断 ThingSmartSceneDPModel 中的属性 entityType 为 AutoTypePir(7) 时，调用下面的接口创建传感类条件。

接口说明

+ (ThingSmartSceneConditionModel *)createPirConditionWithDevice:(ThingSmartDeviceModel *)device
                                                        dpModel:(ThingSmartSceneDPModel *)dpModel
                                                      exprModel:(ThingSmartSceneExprModel *)exprModel;

参数说明

参数	类型	说明
device	ThingSmartDeviceModel	设备模型
dpModel	ThingSmartSceneDPModel	DP 模型
exprModel	ThingSmartSceneExprModel	表达式模型

示例代码

Objective-C：

- (void)buildPirDeviceCondition {
    ThingSmartDeviceModel *deviceModel = [[ThingSmartDeviceModel alloc] init];
    ThingSmartSceneDPModel *dpModel = [[ThingSmartSceneDPModel alloc] init];
    ThingSmartSceneExprModel *enumExpr = [ThingSmartSceneConditionExprBuilder createEnumExprWithType:@"789" chooseValue:@"1000" exprType:kExprTypeDevice];

    ThingSmartSceneConditionModel *pirCondition = [ThingSmartSceneConditionFactory createPirConditionWithDevice:deviceModel dpModel:dpModel exprModel:enumExpr];
}

Swift：

func buildPirDeviceCondition() {
    let deviceModel = ThingSmartDeviceModel()
    let dpModel = ThingSmartSceneDPModel()
    let enumExpr = ThingSmartSceneConditionExprBuilder.createEnumExpr(withType: "789", chooseValue: "1000", exprType: .device)
    let pirCondition = ThingSmartSceneConditionFactory.createPirCondition(withDevice: deviceModel, dpModel: dpModel, exprModel: enumExpr)
}

创建地理围栏条件

该功能依赖 Apple 系统能力，所以此类条件有如下限制：

App 地址位置权限必须申请，且选择始终打开。如果选择其他类型，会导致地理围栏条件无法触发。
系统定位服务总开关需要打开。
地理围栏半径最小设置 100m，也不能设置过大，否则会导致无法精准触发。
地理围栏个数限制 20 个，设置过多的地理围栏都会无效。

接口说明

+ (ThingSmartSceneConditionModel *)createGeoFenceConditionWithGeoType:(GeoFenceType)type
                                                              geoLati:(CGFloat)latitude
                                                             geoLonti:(CGFloat)longitude
                                                            geoRadius:(CGFloat)radius
                                                             geoTitle:(NSString *)geoTitle;

参数说明

参数	类型	说明
type	GeoFenceType	地理围栏类型，详细见 `GeoFenceType`
latitude	double	地理围栏中心点的纬度
longitude	double	地理围栏中心点的经度
radius	double	地理围栏的半径，单位：米。建议设置值为 100，设置过大会影响触发
geoTitle	string	地理围栏中心点的位置名称

GeoFenceType 枚举

枚举类型	枚举值	说明
kGeoFenceTypeReach	0	到达类型，表示到达某个地方
kGeoFenceTypeExit	1	离开类型，表示离开某个地方
kGeoFenceTypeNotSet	2	未知类型

示例代码

Objective-C：

- (void)buildGeofenceCondition {
    ThingSmartSceneConditionModel *geofenceCondition = [ThingSmartSceneConditionFactory createGeoFenceConditionWithGeoType:kGeoFenceTypeReach geoLati:30.30288959184809 geoLonti:120.0640840491766 geoRadius:100 geoTitle:@"XX 影视"];
}

Swift：

func buildGeofenceCondition() {
    let geofenceCondition = ThingSmartSceneConditionFactory.createGeoFenceCondition(withGeoType: .reach, geoLati: 30.30288959184809, geoLonti: 120.0640840491766, geoRadius: 100, geoTitle: "XX 影视")
}

创建家人回家条件

创建家人回家条件类型，需要如下几个步骤：

获取支持家人回家的设备列表，调用 getLockDeviceListWithHomeId:success:failure。
通过当前家庭 ID 获取成员列表，调用 ThingSmartDeviceKit SDK
中的 getHomeMemberListWithSuccess:failure。
调用以下接口，将选择的家庭成员 ID 和名称生成家人回家条件模型。
entitySubIds 字段的值使用 getAllConditionListWithFahrenheit:windSpeedUnit:homeId:success:failure 接口数据字段 devConds 内家人回家条件对应的 entitySubIds。

接口说明

+ (ThingSmartSceneConditionModel *)memberBackHomeConditionWithDevId:(NSString *)devId
                                                       entitySubIds:(NSString *)entitySubIds
                                                          memberIds:(NSString *)memberIds
                                                        memberNames:(NSString *)memberNames;

参数说明

参数	类型	说明
devId	string	设备 ID
entitySubIds	string	子类型 ID 数组
memberIds	string	选择的家庭成员 ID 数组，使用逗号隔开
memberNames	string	选择的家庭成员名称数组，使用逗号隔开

示例代码

Objective-C：

- (void)buildMemberGoingHomeCondition {
    ThingSmartSceneConditionModel *memberGoingHomeCondition = [ThingSmartSceneConditionFactory memberBackHomeConditionWithDevId:@"vdevo155919804483178" entitySubIds:@"1,2,3,4,5,6,7" memberIds:@"id1,id2,id3" memberNames:@"name1,name2,name3"];
}

Swift：

func buildMemberGoingHomeCondition() {
    let memberGoingHomeCondition = ThingSmartSceneConditionFactory.memberBackHomeCondition(withDevId: "vdevo155919804483178", entitySubIds: "1,2,3,4,5,6,7", memberIds: "id1,id2,id3", memberNames: "name1,name2,name3")
}

创建计算型条件

创建计算型条件，需要如下几个步骤：

判断 ThingSmartSceneDPModel 中 condCalExtraInfo 字典内 calType 的值为 duration。如果是，继续进行以下步骤。
condCalExtraInfo 字段内的 maxSeconds 要求您的持续时间不能超过该值。该值的单位为秒。
处理 ThingSmartSceneDPModel 中 valueRangeJson 数据，遍历 valueRangeJson 中的数据，给每条数据增加一个复制项，给该复制项加上一个标识，用于标识该选项支持增加时间属性。
选择持续时间后，将相关属性传入以下接口，生成计算型条件模型。

接口说明

+ (ThingSmartSceneConditionModel *)calculateConditionWithDeviceModel:(ThingSmartDeviceModel *)deviceModel
                                                             dpModel:(ThingSmartSceneDPModel *)dpModel
                                                           exprModel:(ThingSmartSceneExprModel *)exprModel
                                                        durationTime:(NSTimeInterval)durationTime;

参数说明

参数	类型	说明
deviceModel	ThingSmartDeviceModel	设备模型信息
dpModel	ThingSmartSceneDPModel	DP 模型
exprModel	ThingSmartSceneExprModel	表达式模型
durationTime	double	持续时间，单位秒

示例代码

Objective-C：

- (void)buildCalculateCondition {
    ThingSmartSceneExprModel *expr = [ThingSmartSceneConditionExprBuilder buildCalculateExprWithDpId:@"123" dpType:@"enum" selectedValue:@"123"];
    ThingSmartSceneDPModel *dpModel = [[ThingSmartSceneDPModel alloc] init];
    ThingSmartDeviceModel *deviceModel = [[ThingSmartDeviceModel alloc] init];

    ThingSmartSceneConditionModel *calcaulateCondition = [ThingSmartSceneConditionFactory calculateConditionWithDeviceModel:deviceModel dpModel:dpModel exprModel:expr durationTime:100];
}

Swift：

func buildCalculateCondition() {
    let expr = ThingSmartSceneConditionExprBuilder.buildCalculateExpr(withDpId: "123", dpType: "enum", selectedValue: "123")
    let dpModel = ThingSmartSceneDPModel()
    let deviceModel = ThingSmartDeviceModel()
    let calcaulateCondition = ThingSmartSceneConditionFactory.calculateCondition(with: deviceModel, dpModel: dpModel, exprModel: expr, durationTime: 100)
}

创建日落日出前后几分钟条件

条件需要城市信息，获取城市信息调用 getCityInfoWithLatitude:longitude:success:failure 或getCityInfoWithCityId:success:failure。
选择前后几分钟和类型，传递给 createSunsetriseTimerExprWithCity:type:deltaMinutes: 生成 expr 对象。
城市模型和 expr 模型生成日落日出前后几分钟条件模型。

接口说明

+ (ThingSmartSceneConditionModel *)createSunsetriseTimerConditionWithCity:(ThingSmartCityModel *)city
                                                                ExprModel:(ThingSmartSceneExprModel *)exprModel

参数说明

参数	类型	说明
city	ThingSmartCityModel	城市信息模型
exprModel	ThingSmartSceneExprModel	表达式模型

示例代码

Objective-C：

- (void)buildSunsetriseCondition {
    ThingSmartCityModel *cityModel = [[ThingSmartCityModel alloc] init];
    cityModel.cityId = 5621253;
    cityModel.city = @"杭州市";

    ThingSmartSceneExprModel *sunsetExpr = [ThingSmartSceneConditionExprBuilder createSunsetriseTimerExprWithCity:cityModel type:kSunTypeSet deltaMinutes:30];

    ThingSmartSceneConditionModel *sunsetriseCondition = [ThingSmartSceneConditionFactory createSunsetriseTimerConditionWithCity:cityModel ExprModel:sunsetExpr];
}

Swift：

func buildSunsetriseCondition() {
    let cityModel = ThingSmartCityModel()
    cityModel.cityId = 5621253
    cityModel.city = "杭州市"
    let sunsetriseExpr = ThingSmartSceneConditionExprBuilder.createSunsetriseTimerExpr(withCity: cityModel, type: .set, deltaMinutes: 30)
    let sunsetriseCondition = ThingSmartSceneConditionFactory.createSunsetriseTimerCondition(withCity: cityModel, exprModel: sunsetriseExpr)
}

场景条件表达式创建

创建表达式的主要类和说明：

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

使用 ThingSmartSceneConditionExprBuilder 创建一个 ThingSmartSceneExprModel 对象，生成创建条件所需的表达式 expr。expr 是一个数组（请注意，最外层一定是数组），数组中的每一个对象描述了一个条件，如 @[@"$temp",@"<",@15] 条件数组就描述了温度低于 15℃ 这个条件。

场景条件表达式对应 ThingSmartSceneExprModel 类。涂鸦支持以下几种表达式的创建。

设备表达式。设备的 DP 有 bool、enum、value、raw、string 类型。
天气表达式。天气的 DP 有 enum、value 类型。
定时表达式。
日落日出前后几分钟表达式。
地理围栏表达式。
计算型表达式。
家人回家表达式。

示例说明

气象条件 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]]，可以表示一个 电灯开 的条件。其中 dp1 是 ThingSmartSceneDPModel 中提供的 DP 的名称。
日落日出 expr 示例：

日落日出前后几分钟条件使用一个字典表示，例如 { "type":"sunrise", "cityId":"1442827101764976691", "sunrise":10}。type 表示日落还是日出，cityId 表示城市 ID，sunrise 是动态的，取的 type 的值，表示前后几分钟。
地理围栏 expr 示例：

地理围栏条件的 expr 是一个数组。例如 [[ "$action", "==", "exit"]]。表示是离开某个地理围栏的条件。如果要表示进入某个地理围栏，把最后一个值改为 enter。
计算型 expr 示例：

计算型 expr 是多维数组。例如：[[[["$dp1","==","nopir"],"condCalculate","$calObj"],"==",true]]。第一个 $dp1 表示 DP ID 是 1。nopir 表示用户选的枚举值，该值也可能是布尔型，具体看 DP 类型。其他的值都是固定的。
家人回家 expr 示例：

家人回家 expr 是多维数组，例如：[[["$devId","lockRecognition","$allData"],"inRange","41241544,37190406"]]。只有最后一个值是动态的，其他固定不变，最后一个值将家庭成员的 ID 以逗号隔开的方式生成字符串。

因为设备和天气的很多类型类似，所以设备和天气的表达式都是以 DP 类型来创建。为了区分设备和天气，会有 ExprType 枚举类型。

ExprType 类型

枚举类型	枚举值	说明
kExprTypeWhether	0	天气类型
kExprTypeDevice	1	设备类型

创建布尔型表达式

接口说明

+ (ThingSmartSceneExprModel *)createBoolExprWithType:(NSString *)type
                                              isTrue:(BOOL)isTrue
                                            exprType:(ExprType)exprType;

参数说明

参数	类型	说明
type	string	DP ID
isTrue	bool	布尔值，yes 或 no
exprType	ExprType	表达式类型，区分是设备或天气，详细见 `ExprType` 类型说明

示例代码

Objective-C：

- (void)buildBOOLExpr {
    // device
    ExprType deviceType = kExprTypeDevice;
    ThingSmartSceneExprModel *deviceBoolExpr = [ThingSmartSceneConditionExprBuilder createBoolExprWithType:@"123" isTrue:YES exprType:deviceType];

    // weather
    ExprType weatherType = kExprTypeWhether;
    ThingSmartSceneExprModel *weatherBoolExpr = [ThingSmartSceneConditionExprBuilder createBoolExprWithType:@"123" isTrue:YES exprType:weatherType];
}

Swift：

func buildBOOLExpr() {
    // device
    let deviceType: ExprType = .device
    let deviceBoolExpr = ThingSmartSceneConditionExprBuilder.createBoolExpr(withType: "123", isTrue: true, exprType: deviceType)

    // weather
    let weatherType: ExprType = .whether
    let weatherBoolExpr = ThingSmartSceneConditionExprBuilder.createBoolExpr(withType: "123", isTrue: true, exprType: weatherType)
}

创建枚举型表达式

接口说明

+ (ThingSmartSceneExprModel *)createEnumExprWithType:(NSString *)type
                                         chooseValue:(NSString *)chooseValue
                                            exprType:(ExprType)exprType

参数说明

参数	类型	说明
type	string	选择的 DP ID，例如 24，pm2.5
chooseValue	string	选择的 DP 值，例如 white
exprType	ExprType	表达式类型，区分是设备或天气，详细见 `ExprType` 类型说明

示例代码

Objective-C：

- (void)buildEnumExpr {
    // device
    ExprType deviceType = kExprTypeDevice;
    ThingSmartSceneExprModel *deviceEnumExpr = [ThingSmartSceneConditionExprBuilder createEnumExprWithType:@"789" chooseValue:@"1000" exprType:deviceType];

    // weather
    ExprType weatherType = kExprTypeWhether;
    ThingSmartSceneExprModel *weatherEnumExpr = [ThingSmartSceneConditionExprBuilder createEnumExprWithType:@"789" chooseValue:@"1000" exprType:weatherType];
}

Swift：

func buildEnumExpr() {
    // device
    let deviceType: ExprType = .device
    let deviceEnumExpr = ThingSmartSceneConditionExprBuilder.createEnumExpr(withType: "789", chooseValue: "1000", exprType: deviceType)

    // weather
    let weatherType: ExprType = .whether
    let weatherEnumExpr = ThingSmartSceneConditionExprBuilder.createEnumExpr(withType: "789", chooseValue: "1000", exprType: weatherType)
}

创建数值型表达式

接口说明

+ (ThingSmartSceneExprModel *)createValueExprWithType:(NSString *)type
                                             operater:(NSString *)operateString
                                          chooseValue:(NSInteger)value
                                             exprType:(ExprType)exprType

参数说明

参数	类型	说明
type	string	选择的 DP ID，例如 24，pm2.5
operateString	string	操作符字符串，可传 “==”，“>”，“<”
value	long	选择的 DP 值，例如 250
exprType	ExprType	表达式类型，区分是设备或天气，详细见 `ExprType` 类型说明

示例代码

Objective-C：

- (void)buildValueExpr {
    // device
    ExprType deviceType = kExprTypeDevice;
    ThingSmartSceneExprModel *deviceValueExpr = [ThingSmartSceneConditionExprBuilder createValueExprWithType:@"1" operater:@"==" chooseValue:1000 exprType:deviceType];

    // weather
    ExprType weatherType = kExprTypeWhether;
    ThingSmartSceneExprModel *weatherValueExpr = [ThingSmartSceneConditionExprBuilder createValueExprWithType:@"1" operater:@"==" chooseValue:1000 exprType:weatherType];
}

Swift：

func buildValueExpr() {
    // device
    let deviceType: ExprType = .device
    let deviceValueExpr = ThingSmartSceneConditionExprBuilder.createValueExpr(withType: "1", operater: "==", chooseValue: 1000, exprType: deviceType)

    // weather
    let weatherType: ExprType = .whether
    let weatherValueExpr = ThingSmartSceneConditionExprBuilder.createValueExpr(withType: "1", operater: "==", chooseValue: 1000, exprType: weatherType)
}

创建透传型表达式

当判断设备 DP 类型为 string 或 raw 时，可调用该接口生成表达式对象。

接口说明

+ (ThingSmartSceneExprModel *)createRawExprWithType:(NSString *)type
                                           exprType:(ExprType)exprType;

参数说明

参数	类型	说明
type	string	选择的 DP ID，例如：24，pm2.5
exprType	ExprType	表达式类型，区分是设备或天气，详细见 `ExprType` 类型说明

示例代码

Objective-C：

- (void)buildRawExpr {
    // device
    ExprType deviceType = kExprTypeDevice;
    ThingSmartSceneExprModel *deviceRawExpr = [ThingSmartSceneConditionExprBuilder createRawExprWithType:@"456" exprType:deviceType];

    // 天气不存在 raw 或 string 类型的 DP
    ExprType weatherType = kExprTypeWhether;
    ThingSmartSceneExprModel *weatherRawExpr = [ThingSmartSceneConditionExprBuilder createRawExprWithType:@"456" exprType:weatherType];
}

Swift：

func buildRawExpr() {
    // device
    let deviceType: ExprType = .device
    let deviceRawExpr = ThingSmartSceneConditionExprBuilder.createRawExpr(withType: "456", exprType: deviceType)

    // 天气不存在 raw 或 string 类型的 DP
    let weatherType: ExprType = .whether
    let weatherRawExpr = ThingSmartSceneConditionExprBuilder.createRawExpr(withType: "456", exprType: weatherType)
}

创建定时表达式

接口说明

+ (ThingSmartSceneExprModel *)createTimerExprWithTimeZoneId:(NSString *)timeZoneId
                                                      loops:(NSString *)loops
                                                       date:(NSString *)date
                                                       time:(NSString *)time;

参数说明

参数	类型	说明
timeZoneId	string	当前设备所在时区，例如 Asia/Shanghai
loops	string	循环次数，例如 `1111111`，表示从星期天至星期六每天都执行
date	string	定时日期，例如 `20220517`
time	string	定时时间，例如 `17:26`

示例代码

Objective-C：

- (void)buildTimerExpr {
    ThingSmartSceneExprModel *timeExpr = [ThingSmartSceneConditionExprBuilder createTimerExprWithTimeZoneId:[NSTimeZone defaultTimeZone].name loops:@"1111111" date:@"20231010" time:@"20:30"];
}

Swift：

func buildTimerExpr() {
    let timeExpr = ThingSmartSceneConditionExprBuilder.createTimerExpr(withTimeZoneId: NSTimeZone.default.identifier, loops: "1111111", date: "20231010", time: "20:30")
}

创建日落日出前后几分钟表达式

+ (ThingSmartSceneExprModel *)createSunsetriseTimerExprWithCity:(ThingSmartCityModel *)city
                                                           type:(SunType)type
                                                   deltaMinutes:(NSInteger)minutes;

参数说明

参数	类型	说明
city	ThingSmartCityModel	城市模型
SunType	SunType	日落日出类型，详细见 `SunType`
minutes	long	前后几分钟，以分为单位

SunType 枚举

枚举类型	枚举值	说明
kSunTypeNotDetermin	0	未知类型
kSunTypeRise	1	日出类型
kSunTypeSet	2	日落类型

示例代码

Objective-C：

- (void)buildSunsetriseTimerExpr {
    ThingSmartCityModel *cityModel = [ThingSmartCityModel new];
    cityModel.cityId = 23;
    cityModel.city = @"Shanghai";
    ThingSmartSceneExprModel *sunsrise = [ThingSmartSceneConditionExprBuilder createSunsetriseTimerExprWithCity:cityModel type:kSunTypeRise deltaMinutes:100];
}

Swift：

func buildSunsetriseTimerExpr() {
    let cityModel = ThingSmartCityModel()
    cityModel.cityId = 23
    cityModel.city = "Shanghai"
    let sunserrise = ThingSmartSceneConditionExprBuilder.createSunsetriseTimerExpr(withCity: cityModel, type: .rise, deltaMinutes: 100)
}

创建地理围栏表达式

接口说明

+ (ThingSmartSceneExprModel *)buildGeofenceExprWithType:(GeoFenceType)type;

参数说明

参数	类型	说明
type	GeoFenceType	地理围栏枚举，详细见 `GeoFenceType`

GeoFenceType 枚举

枚举类型	枚举值	说明
kGeoFenceTypeReach	0	到达类型，表示到达某个地方
kGeoFenceTypeExit	1	离开类型，表示离开某个地方
kGeoFenceTypeNotSet	2	未知类型

示例代码

Objective-C：

- (void)buildGeofenceExpr {
    ThingSmartSceneExprModel *reachExpr = [ThingSmartSceneConditionExprBuilder buildGeofenceExprWithType:kGeoFenceTypeReach];
}

Swift：

func buildGeofenceExpr() {
    let reachExpr = ThingSmartSceneConditionExprBuilder.buildGeofenceExpr(with: .reach)
}

创建计算型表达式

接口说明

+ (ThingSmartSceneExprModel *)buildCalculateExprWithDpId:(NSString *)dpId dpType:(NSString *)dpType selectedValue:(id)selectedValue;

参数说明

参数	类型	说明
dpId	string	选择的 DP ID
dpType	string	选择的 DP 类型，只支持 enum 和 bool
selectedValue	id	选择的 DP 值，类型可以是 NSString、NSNumber 等。例如 200，YES

示例代码

Objective-C：

- (void)buildCalculateExpr {
    // dpType 只支持 enum 和 bool
    ThingSmartSceneExprModel *expr = [ThingSmartSceneConditionExprBuilder buildCalculateExprWithDpId:@"123" dpType:@"enum" selectedValue:@"123"];
}

Swift：

func buildCalculateExpr() {
    let expr = ThingSmartSceneConditionExprBuilder.buildCalculateExpr(withDpId: "123", dpType: "enum", selectedValue: "123")
}

创建家人回家表达式

接口说明

+ (ThingSmartSceneExprModel *)buildMemberBackHomeExprWithMemberIds:(NSString *)memberIds;

参数说明

参数	类型	说明
memberIds	string	选择的家庭成员 ID 数组，使用逗号隔开。例如 `"123,456,789"`

示例代码

Objective-C：

- (void)buildMemberGoingHomeExpr {
    ThingSmartSceneExprModel *memberGoingHomeExpr = [ThingSmartSceneConditionExprBuilder buildMemberBackHomeExprWithMemberIds:@"123,456,789"];
}

Swift：

func buildMemberGoingHomeExpr() {
    let memberGoingHomeExpr = ThingSmartSceneConditionExprBuilder.buildMemberBackHomeExpr(withMemberIds: "123,456,789")
}

场景动作创建

场景动作类是 ThingSmartSceneActionModel，其中的 actionExecutor 属性即表示场景动作类型。涂鸦支持以下动作类型：

dpIssue：设备
deviceGroupDpIssue：群组
ruleTrigger：触发场景
ruleEnable：启动自动化
ruleDisable：禁用自动化
delay：延时动作
appPushTrigger：消息推送
mobileVoiceSend：电话通知
smsSend：短信通知

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

场景动作类型	说明
设备	`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 分钟。
消息推送	`entityId` 不需要。 `actionExecutor` 设置为 `appPushTrigger`。 `executorProperty` 不需要。
电话通知	`entityId` 不需要。 `actionExecutor` 设置为 `mobileVoiceSend`。 `executorProperty` 不需要。
短信通知	`entityId` 不需要。 `actionExecutor` 设置为 `smsSend`。 `executorProperty` 不需要。

创建设备动作

接口说明

+ (ThingSmartSceneActionModel *)deviceActionWithFeature:(ThingSmartSceneCoreFeatureModel *)feature
                                                  devId:(NSString *)devId
                                             deviceName:(NSString *)deviceName;

参数说明

参数	类型	说明
feature	ThingSmartSceneCoreFeatureModel	设备的功能模型
devId	string	设备 ID
deviceName	string	设备名称

示例代码

Objective-C：

- (void)buildDeviceAction{
    ThingSmartDeviceModel *deviceModel = [ThingSmartDevice deviceWithDeviceId:@"vdevo157381285723945"].deviceModel;
    ThingSmartSceneCoreFeatureModel *featureModel = nil;
    ThingSmartSceneActionModel *deviceAction = [ThingSmartSceneActionFactory deviceActionWithFeature:featureModel devId:deviceModel.devId deviceName:deviceModel.name];
}

Swift：

func buildDeviceAction() {
    let deviceModel = ThingSmartDevice.init(deviceId: "vdevo157381285723945")!.deviceModel
    var featureModel: ThingSmartSceneCoreFeatureModel!
    let deviceAction = ThingSmartSceneActionFactory.deviceAction(withFeature: featureModel, devId: deviceModel.devId, deviceName: deviceModel.name)
}

创建群组动作

接口说明

+ (ThingSmartSceneActionModel *)groupActionWithFeature:(ThingSmartSceneCoreFeatureModel *)feature
                                               groupId:(NSString *)groupId
                                             groupName:(NSString *)groupName;

参数说明

参数	类型	说明
feature	ThingSmartSceneCoreFeatureModel	群组的功能模型
groupId	string	群组 ID
groupName	string	群组名称

示例代码

Objective-C：

- (void)buildGroupAction {
    ThingSmartGroupModel *groupModel = [ThingSmartGroup groupWithGroupId:@""].groupModel;
    ThingSmartSceneCoreFeatureModel *featureModel = nil;
    ThingSmartSceneActionModel *groupAction = [ThingSmartSceneActionFactory groupActionWithFeature:featureModel groupId:groupModel.groupId groupName:groupModel.name];
}

Swift：

func buildGroupAction() {
    let groupModel = ThingSmartGroup.init(groupId: "")!.groupModel
    var featureModel: ThingSmartSceneCoreFeatureModel!
    let groupAction = ThingSmartSceneActionFactory.groupAction(withFeature: featureModel, groupId: groupModel.groupId, groupName: groupModel.name)
}

创建选择一键执行动作

接口说明

+ (ThingSmartSceneActionModel *)createTriggerSceneActionWithSceneId:(NSString *)sceneId sceneName:(NSString *)sceneName;

参数说明

参数	类型	说明
sceneId	string	场景 ID
sceneName	string	场景名称

示例代码

Objective-C：

- (void)buildSelectTapToRunAction {
    ThingSmartSceneActionModel *selectTapToRunAction = [ThingSmartSceneActionFactory createTriggerSceneActionWithSceneId:@"测试场景 ID" sceneName:@"测试场景名称"];
}

Swift：

func buildSelectTapToRunAction() {
    let selectTapToRunAction = ThingSmartSceneActionFactory.createTriggerSceneAction(withSceneId: "测试场景 ID", sceneName: "测试场景名称")
}

创建选择自动化动作

接口说明

+ (ThingSmartSceneActionModel *)createSwitchAutoActionWithSceneId:(NSString *)sceneId sceneName:(NSString *)sceneName type:(AutoSwitchType)type;

参数说明

参数	类型	说明
sceneId	string	场景 ID
sceneName	string	场景名称
type	AutoSwitchType	自动化操作类型，开启或关闭，详情见 `AutoSwitchType`

AutoSwitchType 枚举

枚举类型	枚举值	说明
kAutoSwitchTypeEnable	0	开启自动化
kAutoSwitchTypeDisable	1	关闭自动化

示例代码

Objective-C：

- (void)buildSelectAutomationAction {
    ThingSmartSceneActionModel *automationAction = [ThingSmartSceneActionFactory createSwitchAutoActionWithSceneId:@"测试场景 ID" sceneName:@"测试场景名称" type:kAutoSwitchTypeEnable];
}

Swift：

func buildSelectAutomationAction() {
    let automationAction = ThingSmartSceneActionFactory.createSwitchAutoAction(withSceneId: "测试场景 ID", sceneName: "测试场景名称", type: AutoSwitchType(rawValue: 0)!)
}

创建延时动作

接口说明

+ (ThingSmartSceneActionModel *)createDelayActionWithHours:(NSString *)hours minutes:(NSString *)minutes seconds:(NSString *)seconds;

参数说明

参数	类型	说明
hours	string	小时
minutes	string	分钟
seconds	string	秒

示例代码

Objective-C：

- (void)buildDelayAction {
    ThingSmartSceneActionModel *delayAction = [ThingSmartSceneActionFactory createDelayActionWithHours:@"0" minutes:@"0" seconds:@"60"];
}

Swift：

func buildDelayAction() {
    let delayAction = ThingSmartSceneActionFactory.createDelayAction(withHours: "0", minutes: "0", seconds: "60")
}

创建消息通知动作

接口说明

+ (ThingSmartSceneActionModel *)createSendNotificationAction;

示例代码

Objective-C：

- (void)buildNotificationAction {
    ThingSmartSceneActionModel *notificaitonAction = [ThingSmartSceneActionFactory createSendNotificationAction];
}

Swift：

func buildNotificationAction() {
    let notificaitonAction = ThingSmartSceneActionFactory.createSendNotificationAction()
}

创建短信通知动作

接口说明

+ (ThingSmartSceneActionModel *)createSmsAction;

示例代码

Objective-C：

- (void)buildSendSMSAction {
    ThingSmartSceneActionModel *sendSMSAction = [ThingSmartSceneActionFactory createSmsAction];
}

Swift：

func buildSendSMSAction() {
    let sendSMSAction = ThingSmartSceneActionFactory.createSmsAction()
}

创建电话通知动作

接口说明

+ (ThingSmartSceneActionModel *)createCallAction;

示例代码

Objective-C：

- (void)buildSendCallAction {
    ThingSmartSceneActionModel *sendCallAction = [ThingSmartSceneActionFactory createCallAction];
}

Swift：

func buildSendCallAction() {
    let sendCallAction = ThingSmartSceneActionFactory.createCallAction()
}

场景生效时间段创建

生效时间段只支持自动化场景，不支持一键执行场景，生效时间段对应 ThingSmartScenePreConditionModel 类，涂鸦支持以下时间段类型：

全天。
白天。
黑夜。
自定义。支持设置起始时间。

条件模型

ThingSmartScenePreConditionModel 字段说明

参数	类型	是否必须	说明
scenarioId	string	否	场景 ID
conditionId	string	否	场景条件 ID
condType	string	是	生效时间段类型，`allDay`，`daytime`，`night` 和 `custom`
expr	dictionary	是	生效时间段表达式

创建生效时间段通用接口

接口说明

+ (ThingSmartScenePreConditionModel *)scenePreconditionWithParam:(TSmartScenePreconditionParam *)preconditionParam;

参数说明

TSmartScenePreconditionParam 字段说明

参数	类型	说明
sceneID	string	场景 ID，编辑时有值，创建时无值
conditionID	string	场景条件 ID，编辑时有值，创建时无值
preconditionType	TSmartScenePreconditionType	场景生效时间段枚举值，详情见 `TSmartScenePreconditionType`
beginDate	string	生效时间段开始时间，自定义类型可以设置，其他类型默认 00:00
endDate	string	生效时间段结束时间，自定义类型可以设置，其他类型默认 23:59
loops	string	生效时间段重复天数，`1111111` 第一位至最后一位表示周日至周六。`1111111` 表示每天重复，`0111111` 表示周一至周六重复。
cityId	string	城市 ID
cityName	string	城市名称
timeZoneId	string	时区

TSmartScenePreconditionType 枚举

枚举类型	枚举值	说明
TSmartScenePreconditionTypeUnknow	-1	未知
TSmartScenePreconditionTypeAllDay	0	全天
TSmartScenePreconditionTypeDaytime	1	白天
TSmartScenePreconditionTypeNight	2	黑夜
TSmartScenePreconditionTypeCustom	3	自定义

示例说明

Objective-C：

- (void)buildPrecondition {
    TSmartScenePreconditionParam *precondParam = [[TSmartScenePreconditionParam alloc] init];
    precondParam.preconditionType = TSmartScenePreconditionTypeAllDay;
    precondParam.sceneID = @"1001";
    precondParam.conditionID = @"100001";
    precondParam.loops = @"1000111";
    precondParam.timeZoneId = [NSTimeZone defaultTimeZone].name;

    ThingSmartScenePreConditionModel *precondition = [ThingSmartScenePreConditionFactory scenePreconditionWithParam:precondParam];
}

Swift：

func buildPrecondition() {
    let precondParam = TSmartScenePreconditionParam()
    precondParam.preconditionType = .allDay
    precondParam.sceneID = "1001"
    precondParam.conditionID = "100001"
    precondParam.loops = "1000111"
    precondParam.timeZoneId = TimeZone.current.identifier

    let precondition = ThingSmartScenePreConditionFactory.scenePrecondition(with: precondParam)
}

上一篇群组管理

下一篇常见问题