Create Scene

Last Updated on : 2025-11-24 09:10:40download

This topic describes methods for scene conditions, conditional expressions, scene actions, and effective periods.

Classes and their functions:

Class name	Description
ThingSmartSceneConditionFactory	The utility class that provides methods to quickly create conditions for smart scenes.
ThingSmartSceneConditionExprBuilder	The utility class that provides methods to quickly create conditional expressions for smart scenes.
ThingSmartSceneActionFactory	The utility class that provides methods to quickly create actions for smart scenes.
ThingSmartScenePreConditionFactory	The utility class that provides methods to quickly create conditions for automations.

Scene v2.0 is a new method that maintains consistent core functions while optimizing return parameters. Benefiting from the lightweight design of the cloud-side return parameter processing logic, its API performance is better. You can choose to use it independently according to your own needs.

Create scene conditions

The ThingSmartSceneConditionModel class is used to create scene conditions, supporting the following condition types.

Weather conditions: Includes temperature, humidity, weather, PM2.5, air quality, sunrise, sunset, and more. When users select weather conditions, they can choose the current city.
Device conditions: Users can set the status of a device feature as a condition. When the condition is met, the action in the scene will be triggered. The same device cannot be used as a condition and an action at the same time. Otherwise, operation conflicts might occur.
Schedule: An action can be scheduled to run at a specific time.
PIR sensor-specific conditions: A condition type derived from device conditions. For example, no movement is detected within two minutes.
Geofence: Trigger an action when people enter or leave a geofence.
Home members come home: Trigger an action when a home member comes home, which is mostly used for door locks.
Calculation: A condition type derived from device conditions. Add a duration to a specific feature of the device. For example, a PIR sensor detects no movement for 10 minutes.
Time before or after sunrise/sunset: A condition type derived from the sunrise/sunset conditions. Trigger an action at a specified time before or after sunrise/sunset.

Condition model

Fields in ThingSmartSceneConditionModel

Parameters	Type	Required	Description
conditionId	string	No	The condition ID.
entityId	string	Yes	The ID of the condition entity.
entityType	ThingConditionAutoType	Yes	The condition type.
entitySubIds	string	Yes	The ID of the condition’s sub-entity. Multiple values are separated with commas (,).
expr	array	Yes	The conditional expression.
extraInfo	dictionary	No	The extended information about the condition.
iconUrl	string	No	The URL of the condition icon.
condType	ThingSConditionExpressionType	Yes	There are two types of conditional expressions: simple match and exact match.

ThingConditionAutoType enum

Enum type	Enum value	Description
AutoTypeDevice	1	Device status
AutoTypeWhether	3	Weather conditions
AutoTypeTimer	6	Schedule
AutoTypePir	7	PIR sensor
AutoTypeGeofence	10	Geofence
AutoTypeLockMemberGoHome	11	When home members come home
AutoTypeConditionCalculate	13	Duration
AutoTypeSunsetriseTimer	16	Time before or after sunrise/sunset
AutoTypeManual	99	Tap-to-Run, serving as a placeholder.

ThingSConditionExpressionType enum

Enum type	Enum value	Description
ThingSConditionExpressionTypePrecise	1	Exact match on the conditional expression.
ThingSConditionExpressionTypeSimple	2	Simple match on the conditional expression. When the DP type is string or raw, this enum is used.

Models for condition DPs

Call getAllConditionListWithFahrenheit:windSpeedUnit:homeId:success:failure or getConditionCategoryListWihtHomeId:conditionCategoryParams:success:failure to get the DP data for weather conditions.
Call getCondicationDeviceDPListWithDevId:success:failure to get the DP data for device conditions.
ThingSmartSceneDPModel is the DP object model for device and weather conditions.

Fields in ThingSmartSceneDPModel

Parameters	Type	Required	Description
entityId	string	Yes	The product ID (PID). If the condition is a device, a value is specified. If it is weather, no value is specified.
entitySubId	string	Yes	The DP ID. The ID of weather-specific DP: `temp`: Temperature `humidity`: Humidity `condition`: Weather conditions `pm25`: PM2.5 `aqi`: Air quality index `windSpeed`: Wind speed `sunsetrise`: Sunrise/sunset
entityName	string	Yes	The DP name.
entityType	int	Yes	The applicable condition type for the DP. Example: `1`: Device condition. `3`: Weather condition. `7`: PIR sensor condition.
valueRangeJson	array	No	The value range of the DP. For weather and device conditions, if the DP type is enum, values are specified.
dpModel	ThingSmartSchemaModel	Yes	The model for DP details.
operators	string	No	The string of the operator. For example, “[”==“]”

Fields in ThingSmartSchemaModel

Parameters	Type	Required	Description
dpId	string	Yes	The DP ID.
code	string	Yes	The identifier of the DP, also known as DP code.
name	string	Yes	The DP name.
mode	string	Yes	The DP data transfer type. `rw`: Send and report `ro`: Report only `wr`: Send only
property	ThingSmartSchemaPropertyModel	Yes	The model for DP property details.

Fields in ThingSmartSchemaPropertyModel

Parameters	Type	Required	Description
type	string	Yes	The data type of the DP. Valid values: Boolean, enum, value, string, and raw.
unit	string	No	The unit of the DP. For example, the temperature unit is °C or °F.
min	double	No	The minimum value of the DP.
max	double	No	The maximum value of the DP.
step	double	No	The step of the DP.
scale	int	No	The scale of the DP.
range	array	No	The value range of the DP.

Device conditions

API description

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

Parameter description

Parameters	Type	Description
device	ThingSmartDeviceModel	The device model.
dpModel	ThingSmartSceneDPModel	The DP model.
exprModel	ThingSmartSceneExprModel	The expression model.

Example

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)
}

Weather conditions

Call getCityInfoWithLatitude:longitude:success:failure or getCityInfoWithCityId:success:failure to get the city information that is required to create weather conditions.

API description

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

Parameter description

Parameters	Type	Description
city	ThingSmartCityModel	The city information model.
dpModel	ThingSmartSceneDPModel	The DP model.
exprModel	ThingSmartSceneExprModel	The expression model.

Example

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)
}

Schedule

API description

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

Parameter description

Parameters	Type	Description
exprModel	ThingSmartSceneExprModel	The expression model.

Example

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 sensor

If the entityType is AutoTypePir(7) in ThingSmartSceneDPModel, the condition type is for PIR sensors. Then, you can call the following method to create PIR sensor conditions.

API description

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

Parameter description

Parameters	Type	Description
device	ThingSmartDeviceModel	The device model.
dpModel	ThingSmartSceneDPModel	The DP model.
exprModel	ThingSmartSceneExprModel	The expression model.

Example

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)
}

Geofence

Geofencing depends on Apple-specific capabilities and is subject to the following limitations.

The app must be allowed to access the user’s location with the Always Allow permission. Otherwise, the geofence condition cannot be triggered.
The system location services must be always on.
The minimum radius of a geofence is 100 meters. If the radius is too large, the condition might not be triggered as expected.
Up to 20 geofences can be set. Any excess geofences are invalid.

API description

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

Parameter description

Parameters	Type	Description
type	GeoFenceType	The type of the geofence. See `GeoFenceType`.
latitude	double	The latitude of the center of the geofence.
longitude	double	The longitude of the center of the geofence.
radius	double	The radius of the geofence, in meters. 100 meters is recommended. A larger value might compromise the accuracy of the trigger.
geoTitle	string	The name of the center of the geofence.

GeoFenceType enum

Enum type	Enum value	Description
kGeoFenceTypeReach	0	The user arrives at a specific place.
kGeoFenceTypeExit	1	The user leaves a specific place.
kGeoFenceTypeNotSet	2	Unknown type

Example

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")
}

When home members come home

The steps to create a condition of when home members come home.

Call getLockDeviceListWithHomeId:success:failure to get the list of devices that support the condition of when home members come home.
Call getHomeMemberListWithSuccess:failure in the ThingSmartDeviceKit SDK to get the list of home members by home ID.
Call the following method to generate the condition model by using the ID and name of the selected home members.
The value of entitySubIds is the corresponding entitySubIds in devConds returned by getAllConditionListWithFahrenheit:windSpeedUnit:homeId:success:failure.

API description

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

Parameter description

Parameters	Type	Description
devId	string	The device ID.
entitySubIds	string	An array of IDs of subtypes.
memberIds	string	An array of IDs of the selected home members, separated with commas (,).
memberNames	string	An array of names of the selected home members, separated with commas (,).

Example

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")
}

Calculation

The steps to create a calculation condition.

Determine if condCalExtraInfo in ThingSmartSceneDPModel calType is duration. If it is, proceed with the following steps. maxSeconds in condCalExtraInfo specifies the maximum duration. The unit is in seconds.
Process valueRangeJson in ThingSmartSceneDPModel. Traverse the data in valueRangeJson and duplicate each piece of data. Add a flag to the duplicate to indicate its support for adding a time property.
After the duration is selected, pass the required properties to the following method to generate a condition model.

API description

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

Parameter description

Parameters	Type	Description
deviceModel	ThingSmartDeviceModel	The device model.
dpModel	ThingSmartSceneDPModel	The DP model.
exprModel	ThingSmartSceneExprModel	The expression model.
durationTime	double	The duration, in seconds.

Example

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)
}

Time before or after sunrise/sunset

Call getCityInfoWithLatitude:longitude:success:failure or getCityInfoWithCityId:success:failure to get the city information that is required to create a condition.
Specify the time before or after sunrise/sunset and pass it to createSunsetriseTimerExprWithCity:type:deltaMinutes: to generate the expression object.
Use the city information model and expression model to generate the condition model.

API description

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

Parameter description

Parameters	Type	Description
city	ThingSmartCityModel	The city information model.
exprModel	ThingSmartSceneExprModel	The expression model.

Example

Objective-C:

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

    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 = "Hangzhou"
    let sunsetriseExpr = ThingSmartSceneConditionExprBuilder.createSunsetriseTimerExpr(withCity: cityModel, type: .set, deltaMinutes: 30)
    let sunsetriseCondition = ThingSmartSceneConditionFactory.createSunsetriseTimerCondition(withCity: cityModel, exprModel: sunsetriseExpr)
}

Create conditional expressions

Classes and their functions:

Class name	Description
ThingSmartSceneExprModel	Store the `expr` for scene conditions.
ThingSmartSceneConditionExprBuilder	The utility class that generates conditional expressions for automation scenes.

Use ThingSmartSceneConditionExprBuilder to create a ThingSmartSceneExprModel object and generate the required conditional expr. expr is an array and its outermost layer must be an array. Each object in the array represents a condition. For example, @[@"$temp",@"<",@15] indicates the condition where the temperature is lower than 15°C.

The ThingSmartSceneExprModel class is used for conditional expressions. The conditional expression supports the following types of conditions.

Device conditions. The data type of the DP can be Boolean, enum, value, string, or raw.
Weather conditions. The data type of the DP can be enum and value.
Schedule condition.
Time before or after sunrise/sunset.
Geofence.
Calculation.
When home members come home.

Example

Examples of expr for weather conditions:
- Temperature: @[@[@“$temp”,@“<”,@15]]
- Humidity: @[@[@“$humidity”,@“==”,@“comfort”]]
- Weather: @[@[@“$condition”,@“==”,@“snowy”]]
- PM2.5: @[@[@“$pm25”,@“==”,@“fine”]]
- Air quality: @[@[@“$aqi”,@“==”,@“fine”]]
- Sunrise and sunset: @[@[@“$sunsetrise”,@“==”,@“sunrise”]]
Examples of expr for schedule conditions:

A schedule condition is specified with a dictionary, for example, {timeZoneId = "Asia/Shanghai",loops = "0000000",time = "08:00",date = "20180308"}. Each bit of loops represents the day of the week, Sunday through Saturday. 1 indicates the schedule is on, while 0 indicates the schedule is off. expr is an array, so the dictionary for schedule conditions must also be enclosed in an array.
Examples of expr for device conditions:

A device condition is specified with an array to represent a specific condition value. The concatenated expr for the selected condition can be @[@[@“$dp1”,@“==”,@YES]], indicating the light is turned on. dp1 is the name of the DP provided by ThingSmartSceneDPModel.
Examples of expr for sunrise/sunset conditions:

The time before or after sunrise/sunset is specified with a dictionary, for example { "type":"sunrise", "cityId":"1442827101764976691", "sunrise":10}. type indicates sunset or sunrise. cityId indicates the city ID. sunrise is dynamic, with the value taken from the type, indicating the specific time before or after sunrise/sunset.
Examples of expr for geofence conditions:

The expr of a geofence condition is an array. For example, [[“$action”, “==”, “exit”]]. It indicates the condition when the user leaves a geofence. You can change the last value to enter to indicate the condition when the user enters a geofence.
Examples of expr for calculation conditions:

The expr for calculation conditions is a multidimensional array. For example, [[[["$dp1","==","nopir"],"condCalculate","$calObj"],"==",true]]. The first $dp1 indicates the DP ID is 1. nopir indicates the enum value selected by the user. This value might be a boolean, depending on the DP type. Other values are fixed.
Examples of expr for conditions of when home members come home:

The expr is a multidimensional array, for example, [[[“$devId”,“lockRecognition”,“$allData”],“inRange”,“41241544,37190406”]]. The last element is dynamic, which is a string of home member IDs separated by commas, while the others are fixed.

The expressions for device and weather conditions are created by DP. ExprType distinguishes between the device condition and the weather condition.

ExprType type

Enum type	Enum value	Description
kExprTypeWhether	0	Weather condition
kExprTypeDevice	1	Device condition

Boolean DP

API description

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

Parameter description

Parameters	Type	Description
type	string	The DP ID.
isTrue	bool	The Boolean value, either yes or no.
exprType	ExprType	The expression type, distinguishing between the device condition and the weather condition. See `ExprType`.

Example

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)
}

Enum DP

API description

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

Parameter description

Parameters	Type	Description
type	string	The selected DP ID, for example, 24, PM2.5.
chooseValue	string	The selected DP value, for example, white.
exprType	ExprType	The expression type, distinguishing between the device condition and the weather condition. See `ExprType`.

Example

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)
}

Value DP

API description

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

Parameter description

Parameters	Type	Description
type	string	The selected DP ID, for example, 24, PM2.5.
operateString	string	The operator string. Valid values: ==, >, and <.
value	long	The selected DP value, for example, 250.
exprType	ExprType	The expression type, distinguishing between the device condition and the weather condition. See ExprType.

Example

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)
}

Raw DP

When the DP type is string or raw, call this method to generate an expression object.

API description

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

Parameter description

Parameters	Type	Description
type	string	The selected DP ID, for example, 24, PM2.5.
exprType	ExprType	The expression type, distinguishing between the device condition and the weather condition. See `ExprType`.

Example

Objective-C:

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

    // No raw or string DPs exist for weather.
    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)

    // No raw or string DPs exist for weather.
    let weatherType: ExprType = .whether
    let weatherRawExpr = ThingSmartSceneConditionExprBuilder.createRawExpr(withType: "456", exprType: weatherType)
}

Schedule

API description

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

Parameter description

Parameters	Type	Description
timeZoneId	string	The time zone of the device, for example, Asia/Shanghai.
loops	string	The recurring pattern. For example, `1111111` indicates the schedule repeats every day, Sunday through Saturday.
date	string	The schedule date, for example, 20220517.
time	string	The schedule time, for example, 17:26.

Example

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")
}

Time before or after sunrise/sunset

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

Parameter description

Parameters	Type	Description
city	ThingSmartCityModel	The city information model.
SunType	SunType	The sunrise/sunset type. See `SunType`.
minutes	long	The time before or after sunrise/sunset, in minutes.

SunType enum

Enum type	Enum value	Description
kSunTypeNotDetermin	0	Unknown type
kSunTypeRise	1	Sunrise
kSunTypeSet	2	Sunset

Example

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)
}

Geofence

API description

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

Parameter description

Parameters	Type	Description
type	GeoFenceType	The type of the geofence. See `GeoFenceType`.

GeoFenceType enum

Enum type	Enum value	Description
kGeoFenceTypeReach	0	The user arrives at a specific place.
kGeoFenceTypeExit	1	The user leaves a specific place.
kGeoFenceTypeNotSet	2	Unknown type

Example

Objective-C:

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

Swift:

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

Calculation

API description

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

Parameter description

Parameters	Type	Description
dpId	string	The selected DP ID.
dpType	string	The selected DP type. Only enum and Boolean are applicable.
selectedValue	id	The selected DP value. The type can be NSString and NSNumber. For example, 200, YES.

Example

Objective-C:

- (void)buildCalculateExpr {
    // dpType only supports enum and bool.
    ThingSmartSceneExprModel *expr = [ThingSmartSceneConditionExprBuilder buildCalculateExprWithDpId:@"123" dpType:@"enum" selectedValue:@"123"];
}

Swift:

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

When home members come home

API description

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

Parameter description

Parameters	Type	Description
memberIds	string	An array of IDs of the selected home members, separated with commas (,). For example, “123,456,789”.

Example

Objective-C:

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

Swift:

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

Create scene actions

The scene action class is ThingSmartSceneActionModel and the actionExecutor property represents the type of scene action. The following action types are supported:

dpIssue: Device
deviceGroupDpIssue: Group
ruleTrigger: Trigger a scene
ruleEnable: Enable automation
ruleDisable: Disable automation
delay: Delay the action
appPushTrigger: Message center notification
mobileVoiceSend: Phone call notification
smsSend: SMS notification

After you create the ThingSmartSceneActionModel object, set its properties, especially entityId, actionExecutor, and executorProperty. These three properties describe the object, type, and specific content of an action.

Action type	Description
Device	Set `entityId` to the value of `devId`. Set `actionExecutor` to `dpIssue`. `executorProperty` is a dictionary. For example, `{"1":YES}` specifies an action of setting DP 1 to `YES`, applying to Boolean DPs, such as the light on/off status. You can call the method of getting the list of DPs for device tasks to get the DP ID and its valid values.
Group	Set `entityId` to the value of `groupId`. Set `actionExecutor` to `deviceGroupDpIssue`. Other properties are the same as those of device actions.
Trigger a scene	Set `entityId` to the value of `sceneId`. Set `actionExecutor` to `ruleTrigger`. `executorProperty` is not required.
Enable automation	Set `entityId` to the value of `sceneId`. Set `actionExecutor` to `ruleEnable`. `executorProperty` is not required.
Disable automation	Set `entityId` to the value of `sceneId`. Set `actionExecutor` to `ruleDisable`. `executorProperty` is not required.
Delay the action	Set `entityId` to `delay`. Set `actionExecutor` to `delay`. `executorProperty` specifies a delay expressed with a dictionary. For example, `{@"minutes":@"1",@"seconds":@"30"}` specifies a delay of 1 minute and 30 seconds. Currently, the delay can be up to five hours or 300 minutes.
Message center notification	`entityId` is not required. Set `actionExecutor` to `appPushTrigger`. `executorProperty` is not required.
Phone call notification	`entityId` is not required. Set `actionExecutor` to `mobileVoiceSend`. `executorProperty` is not required.
SMS notification	`entityId` is not required. Set `actionExecutor` to `smsSend`. `executorProperty` is not required.

Device action

API description

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

Parameter description

Parameters	Type	Description
feature	ThingSmartSceneCoreFeatureModel	The feature model of the device.
devId	string	The device ID.
deviceName	string	The name of the device.

Example

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)
}

Group action

API description

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

Parameter description

Parameters	Type	Description
feature	ThingSmartSceneCoreFeatureModel	The feature model of the group.
groupId	string	The group ID.
groupName	string	The name of the group.

Example

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)
}

Tap-to-Run action

API description

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

Parameter description

Parameters	Type	Description
sceneId	string	The scene ID.
sceneName	string	The scene name.

Example

Objective-C:

- (void)buildSelectTapToRunAction {
    ThingSmartSceneActionModel *selectTapToRunAction = [ThingSmartSceneActionFactory createTriggerSceneActionWithSceneId:@"Test scene ID" sceneName:@"Test scene name"];
}

Swift:

func buildSelectTapToRunAction() {
    let selectTapToRunAction = ThingSmartSceneActionFactory.createTriggerSceneAction(withSceneId: "Test scene ID", sceneName: "Test scene name")
}

Automation action

API description

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

Parameter description

Parameters	Type	Description
sceneId	string	The scene ID.
sceneName	string	The scene name.
type	AutoSwitchType	The type of automation operation. See `AutoSwitchType`.

AutoSwitchType enum

Enum type	Enum value	Description
kAutoSwitchTypeEnable	0	Enable automation.
kAutoSwitchTypeDisable	1	Disable automation.

Example

Objective-C:

- (void)buildSelectAutomationAction {
    ThingSmartSceneActionModel *automationAction = [ThingSmartSceneActionFactory createSwitchAutoActionWithSceneId:@"Test scene ID" sceneName:@"Test scene name" type:kAutoSwitchTypeEnable];
}

Swift:

func buildSelectAutomationAction() {
    let automationAction = ThingSmartSceneActionFactory.createSwitchAutoAction(withSceneId: "Test scene ID", sceneName: "Test scene name", type: AutoSwitchType(rawValue: 0)!)
}

Delay the action

API description

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

Parameter description

Parameters	Type	Description
hours	string	Hour(s)
minutes	string	Minute(s)
seconds	string	Second(s)

Example

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")
}

Message center notification

API description

+ (ThingSmartSceneActionModel *)createSendNotificationAction;

Example

Objective-C:

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

Swift:

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

SMS notification

API description

+ (ThingSmartSceneActionModel *)createSmsAction;

Example

Objective-C:

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

Swift:

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

Phone call notification

API description

+ (ThingSmartSceneActionModel *)createCallAction;

Example

Objective-C:

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

Swift:

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

Create effective period

The effective period only works for automation scenes, without applying to tap-to-run. The ThingSmartScenePreConditionModel class is used to create the effective period, supporting the following types.

All day
Daytime
Nighttime
Custom. The user specifies the start and end times.

Condition model

Fields in ThingSmartScenePreConditionModel

Parameters	Type	Required	Description
scenarioId	string	No	The scene ID.
conditionId	string	No	The condition ID.
condType	string	Yes	The type of effective period. Valid values: `allDay`, `daytime`, `night`, and `custom`.
expr	dictionary	Yes	The expression for the effective period.

Method

This API will generate a ThingSmartScenePreConditionModel object from the passed preconditionParam, and internally assemble the expr property of the ThingSmartScenePreConditionModel object.

API description

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

Parameter description

Fields in TSmartScenePreconditionParam

Parameters	Type	Description
sceneID	string	The scene ID. It has a value when a scene is edited, while it has no value when a scene is created.
conditionID	string	The condition ID. It has a value when a scene is edited, while it has no value when a scene is created.
preconditionType	TSmartScenePreconditionType	The type of the effective period. See `TSmartScenePreconditionType`.
beginDate	string	The start time. It applies to a custom effective period and defaults to 00:00 for other types.
endDate	string	The end time. It applies to a custom effective period and defaults to 23:59 for other types.
loops	string	The recurring pattern. For example, `1111111`, the digits from left to right represent Sunday through Saturday. `1111111` indicates the schedule repeats every day. `0111111` indicates the schedule repeats every week Monday through Saturday.
cityId	string	The city ID.
cityName	string	The city name.
timeZoneId	string	The time zone.

TSmartScenePreconditionType enum

Enum type	Enum value	Description
TSmartScenePreconditionTypeUnknow	-1	Unknown
TSmartScenePreconditionTypeAllDay	0	All day
TSmartScenePreconditionTypeDaytime	1	Daytime
TSmartScenePreconditionTypeNight	2	Nighttime
TSmartScenePreconditionTypeCustom	3	Custom

Custom assembly of effective status object

This method mainly involves assembling the ThingSmartScenePreConditionModel object by yourself, with the key focus on the construction of expr. The field parsing within expr is as follows:

Field	Type	Description
loops	String	Configuration value for weekly repetition of the effective time period in scene v2.0, marked from left to right according to Sunday-Saturday; Examples: `1111111` means every day, `1000001` means weekends, `0111110` means Monday to Friday.
start	String	Custom effective start time, e.g., `00:00`.
end	String	Custom effective end time, e.g., `23:59`.
timeInterval	String	Effective time period, e.g.: `custom`: Custom time `daytime`: Daytime `night`: Nighttime `allDay`: All day
cityId	String	The city ID.
timeZoneId	String	The time zone ID.
cityName	String	The city name.
monthLoops	String	Configuration value for monthly repetition of the effective time period in scene v2.0, marked from left to right according to months 1-12; Example: `"100001000001"`.
dayLoops	String	Configuration value for daily repetition of the effective time period in scene v2.0, marked from left to right according to days 1-31, and the value content is converted to decimal for display; Example: `"2147483647"`.
repeatType	String	Repetition type of the effective time period in scene v2.0, e.g.: `onlyOnce`: Only once `everyDay`: Repeat daily `weekly`: Repeat weekly `legalWorkingDay`: Legal working days `legalHolidays`: Legal holidays `custom`: Custom
regionCode	String	Country code for the effective time period in scene v2.0; Required when `RepeatType` is `"legalHolidays"`, and only China (“CHN”) is supported for the time being.

Example

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)
}

Prev DocScene Creation

Next DocScene Recommendation