Create Scene

Last Updated on : 2024-01-09 05:43:05download

The topic describes how to build scene models that consist of conditions and actions.

Feature description

Condition builder

Class	Feature description
`GeofenceConditionBuilder`	Create a condition of when location changes.
`WeatherConditionBuilder`	Create a condition of when weather changes.
`SunRiseSetConditionBuilder`	Create a condition of when weather changes – a time before or after sunset/sunrise.
`TimingConditionBuilder`	Create a condition of schedule.
`DeviceConditionBuilder`	Create a condition of when device status changes or when home members come home.

Action builder

Class	Feature description
`DelayActionBuilder`	Create delay the action.
`NotifyActionBuilder`	Create the action of send notification.
`LinkageRuleActionBuilder`	Create the action of select smart scenes.
`DeviceActionBuilder`	Create the action of control single device.

Data model

ConditionBase

Property	Type	Description
id	String?	The condition ID.
condType	Int?	The match type of conditional expression. See CondType.type for details.
entityType	Int	The condition type. See ConditionEntityType.type for details.
entityId	String?	The ID of the condition content. When the condition is weather, the value is the city ID. When the condition is a device, the value is the device ID. When the condition is a schedule, the value is fixed as `"timer"`. When the condition is a time before or after sunrise/sunset, the value is fixed as `"sunsetriseTimer"`.
entitySubIds	String?	The ID of the condition-specific feature. When the condition is a device, the value is the ID of the selected DP. When the condition is weather, the value is a weather description, for example `"temp"`. When the condition is a schedule (`"timer"`), a time before or after sunrise/sunset (`"sunsetriseTimer"`), or a geofence (`"condition"`), the value is a fixed string.
expr	MutableList<Any? >?	The conditional expression.
extraInfo	MutableMap<String, Any? >?	The extended information about the condition.

CondType

Property	Type	Description
type	Int	The match type of conditional expression.

Enum instance	Instance property value	Description
EXPR_MATCH	1	Expression match.
SIMPLE_MATCH	2	Simple match. Note: When the DP is raw or string type, set `condType` to `2`.

ConditionEntityType

Property	Type	Description
type	Int	The condition type.

Enum instance	Instance property value (constant descriptor in parentheses)	Description
MANUAL	99 (`CONDITION_TYPE_MANUAL`)	Tap-to-Run
WEATHER	3 (`CONDITION_TYPE_WEATHER`)	Weather (excluding a time before or after sunrise/sunset)
SUN_RISE_SET	16 (`CONDITION_TYPE_WEATHER_SUN`)	Time before or after sunrise/sunset
TIMER	6 (`CONDITION_TYPE_TIMER`)	Schedule
DEVICE	1 (`CONDITION_TYPE_DEVICE`)	Device
PIR	7 (`CONDITION_TYPE_PIR`)	PIR device
CONDITION_CALCULATE	13 (`CONDITION_TYPE_WITH_TIME`)	Duration
LOCK_MEMBER_GO_HOME	11 (`CONDITION_TYPE_LOCK`)	Home members come home (detected by door lock)
GEOFENCE	10 (`CONDITION_TYPE_GEO_FENCING`)	Geofence
FACE_DETECT	9 (`CONDITION_TYPE_FACE_DETECT`)	Face recognition
KAFKA	23 (`CONDITION_TYPE_KAFKA`)	Kafka message trigger
ARMED_STATE	12 (`CLIENT_INTERNAL_CONDITION_TYPE_ARM_CLEAR_CLIENT_BIT`)	Smart protection

ActionBase

Property	Type	Description
id	String?	The action ID.
ruleId	String?	The ID of the associated linkage.
actionExecutor	String?	The actuator.
executorProperty	MutableMap<String, Any? >?	The action.
extraProperty	MutableMap<String, Any? >?	The additional information about the action.
entityId	String?	The action ID.

Create scene conditions

When location changes

Class

class GeofenceConditionBuilder(radius: Int, lat: Double, lng: Double, address: String, geofenceType: String)

Parameters

Property	Type	Description
raidus	Int	The radius of the geofence, in meters.
lat	Double	The latitude of the center coordinates of the geofence.
lng	Double	The longitude of the center coordinates of the geofence.
address	String	The description of the center coordinates of the geofence.
geofenceType	String	The type of the geofence. See GeofencingType.type.

Example in Kotlin

// You can retrieve the radius, lat, lon, and address from the geofence configuration.
val radius = 100
val lat: Double = 30.30288959184809
val lon: Double = 120.0640840491766
val address = "XX"
val geofenceType = GeofencingType.GEOFENCING_TYPE_ENTER.type
val geofenceConditionBuilder = GeofenceConditionBuilder(radius, lat, lon, address, geofenceType)
val conditionBase = geofenceConditionBuilder.build() as ConditionBase
val geoCondition = SceneCondition(conditionBase).apply {
     this.entityName = address
}

Data model

GeofencingType

Property	Type	Description
type	String	The type of the geofence.

Enum instance	Instance property value	Description
GEOFENCING_TYPE_ENTER	`"enter"`	When users arrive at a specific place, they enter the geofence.
GEOFENCING_TYPE_EXIT	`"exit"`	When users leave a specific place, they exit the geofence.
GEOFENCING_TYPE_INSIDE	`"inside"`	When users are in a specific place, they are in the geofence.
GEOFENCING_TYPE_OUTSIDE	`"outside"`	When users are not in a specific place, they are outside the geofence.

Register scene geofence

API description

This method is used to register a scene geofence. For example, it is invoked when the user saves and enables an added or edited scene that contains a geofence.

This method applies to all data centers except China Data Center. For more information about integrating with geofencing, see Create and Monitor Geofences for Android or Developing the Geofence Service for Huawei.

fun addGeofence(geofenceCondition: SceneCondition, listener: IResultCallback<Unit>? = null)

Parameter description

Parameters	Type	Description
geofenceCondition	SceneCondition	The scene condition.
listener	IResultCallback<Unit>?	The callback for the result of registration.

Example in Kotlin

ThingHomeSdk.getSceneServiceInstance().extService().addGeofence(geofenceCondition)

Bulk register scene geofences

API description

This method is used to reset and register multiple scene geofences in one go. For example, it is invoked when the list of automations is requested.

This method applies to all data centers except China Data Center.

fun resetGeofence()

Example in Kotlin

ThingHomeSdk.getSceneServiceInstance().extService().resetGeofence()

Remove a geofence

API description

This method is used to remove a registered geofence from the system. For example, it is invoked when the user saves and disables an added or edited scene that contains a geofence, or when the user deletes a scene that contains a geofence.

This method applies to all data centers except China Data Center.

fun removeGeofence(geofenceId: String, listener: IResultCallback<Unit>? = null)

Parameter description

Parameters	Type	Description
geofenceId	String	The ID of the geofence. Description: Get the `entityId` field of the conditional data model. The value of this field will be assigned after the scene model is successfully created on the cloud.
listener	IResultCallback<Unit>?	The callback for the result of removal.

Example in Kotlin

ThingHomeSdk.getSceneServiceInstance().extService().removeGeofence(geofenceId)

Remove all geofences

API description

This method is used to remove all the registered geofences. For example, it is invoked when the app is logged out.

This method applies to all data centers except China Data Center.

fun removeAllGeofence()

Example in Kotlin

ThingHomeSdk.getSceneServiceInstance().extService().removeAllGeofence()

When weather changes

Class

class WeatherConditionBuilder(
        cityId: String,
        cityName: String,
        entityType: Int,
        weatherType: WeatherType,
        operator: String? = "==",
        chooseValue: Any)

Parameters

Property	Type	Description
cityId	String	The city ID. Note: With the longitude and latitude of the location, you can get the value of `cityId` by calling the method of querying city information by longitude and latitude. Alternatively, query the list of cities and select a city to get the city ID.
cityName	String	The city name. Note: You can get the value of `city` using the same method as retrieving `cityId`.
entityType	Int	The condition type. When the condition is weather, the value is `3`. Note: You can retrieve the list of weather conditions (the field `envConds`) by querying the list of conditions in order to get the `entityType` of the corresponding weather variable.
weatherType	`WeatherType`	Weather variable. See WeatherType.
operator	String?	The operator, such as `"<"`, `"=="`, and `">"`. Note: For temperature and wind speed, the specified operator must be passed. For other weather variables, just pass `null` because an operator is taken as invalid.
chooseValue	Any	The selected value.

Optional parameters

Property	Type	Description
rule	`Rule`	The conditional expression. See Rule.
windSpeedUnit	String?	The unit of wind speed. For example, `"m/s"`.
originTempUnit	String?	The original temperature unit, either `"celsius"` or `"fahrenheit"`.
convertTemp	Map<String, Int>?	Temperature unit conversion. Note: This field only applies to the weather condition – temperature.
tempUnit	String?	The preferred temperature unit for display, either `"celsius"` or `"fahrenheit"`. Note: This field only applies to the weather condition – temperature. Typically, it is used to set the temperature unit on the mobile app.
dpScale	Int?	The conversion factor between Celsius (°C) and Fahrenheit (°F). Note: This field only applies to the weather condition – temperature.

Example in Kotlin

// Retrieve the cityId, cityName, and entityType as described in the above table.
// Pass in the specified weatherType, operator, and chooseValue.
// Retrieve windSpeedUnit from ConditionItemDetail.property?.property?.unit
val weatherConditionBuilder = WeatherConditionBuilder(
                                cityId = cityId,
                                cityName = cityName,
                                entityType = entityType,
                                weatherType = WEATHER_TYPE_WIND,
                                operator = "<",
                                chooseValue = chooseValue,
                            )
                                .setWindSpeedUnit(data.unit)
val conditionBase = weatherConditionBuilder.build() as ConditionBase
val weatherCondition = SceneCondition(conditionBase).apply {
                    entityName = cityName
                    iconUrl = weatherData.icon // The icon of the selected weather type.
                    exprDisplay = exprDis // Visual presentation of conditional expressions.
                }

Data model

WeatherType

Property	Type	Description
type	String	Weather variable.

Enum instance	Instance property value	Description
WEATHER_TYPE_TEMP	`"temp"`	Temperature
WEATHER_TYPE_HUMIDITY	`"humidity"`	Humidity
WEATHER_TYPE_CONDITION	`"condition"`	Weather
WEATHER_TYPE_PM	`"pm25"`	PM2.5
WEATHER_TYPE_AQI	`"aqi"`	Air quality index
WEATHER_TYPE_SUN	`"sunsetrise"`	Sunrise/sunset
WEATHER_TYPE_WIND	`"windSpeed"`	Wind speed
WEATHER_TYPE_SUN_TIMER	`"sunsetriseTimer"`	Time before or after sunrise/sunset

Time before or after sunrise/sunset

Class

class SunRiseSetConditionBuilder(
              cityId: String,
              sunType: SunSetRiseRule.SunType,
              minutes: Int)

Parameters

Property	Type	Description
cityId	String	The city ID.
sunType	`SunSetRiseRule.SunType`	Sunrise or sunset. See SunSetRiseRule.SunType.
minutes	Int	The specified minutes.

Example in Kotlin

val conditionBase: ConditionBase = SunRiseSetConditionBuilder(
                                    cityId,
                                    SunSetRiseRule.SunType.SUNSET,
                                    20
                                ).build() as ConditionBase
val sunRiseSetCondition = SceneCondition(conditionBase).apply {
                    entityName = cityName
                    iconUrl = weatherData.icon // The icon of the selected weather type.
                    exprDisplay = exprDis // Visual presentation of conditional expressions.
                }

Data model

SunSetRiseRule.SunType

Property	Type	Description
sunType	String	Type

Enum instance	Instance property value	Description
SUNRISE	`"sunrise"`	Sunrise
SUNSET	`"sunset"`	Sunset

Schedule condition

Class

class TimingConditionBuilder(
              timeZoneId: String?,
              loops: String,
              time: String,
              date: String)

Parameters

Property	Type	Description
timeZoneId	String?	The time zone ID. Note: You can get the time zone through `Calendar.getInstance().timeZone.id`, `TimeZone.getDefault().id`, or other methods.
loops	String	The recurring pattern. 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. For example, `"0000000"`.
time	String	The time, in the format `%02d:%02d`. For example, `"08:00"`.
date	String	The date, in the format `yyyyMMdd`. For example, `"20230308"`.

Example in Kotlin

// Retrieve timeZoneId as described in the above table.
// Pass in the specified loops, time and date.
val conditionBase: ConditionBase = TimingConditionBuilder(
                    timeZoneId,
                    loops,
                    time,
                    date,
                ).build() as ConditionBase
val timerCondition = SceneCondition(conditionBase).apply {
                    entityName = "Schedule"
                        exprDisplay = time
                }

When device status changes or home members come home

Class

class DeviceConditionBuilder(
        deviceId: String,
        dpId: String,
        entityType: Int,
        deviceConditionData: DeviceConditionData? = null,
        chooseValue: Any? = null)

Parameters

Property	Type	Description
deviceId	String	The device ID.
dpId	String	The DP ID. Note: To create a condition of when home members come home, you can take the field `entitySubId` from ConditionItemDetail.
entityType	Int	The type of the condition entity. Valid values are `1`, `7`, `11`, and `13`. See ConditionEntityType.type.
deviceConditionData	`DeviceConditionData?`	The data model of the device condition. Note: See DeviceConditionData, which is converted from ConditionItemDetail used in the method for querying the list of DPs for device conditions. When a custom rule is set using the optional parameter `rule`, this parameter becomes invalid.
chooseValue	Any?	The selected value.

Optional parameters

Property	Type	Description
rule	`Rule`	The conditional expression. See Rule.
chooseValue	Any?	The selected value.
calType	String?	The type of the custom duration condition for infrared devices.
timeWindow	Long?	The set value of the custom duration condition for infrared devices.
maxSeconds	Long?	The maximum value of the custom duration condition for infrared devices.
delayTime	String?	The preset value of the custom duration condition for infrared devices.
convertTemp	Map<String, Int>?	Temperature unit conversion. Note: Two key-value pairs are included, one for the original temperature unit and its corresponding value, and another for the preferred temperature unit and its corresponding value.
tempUnit	String?	The preferred temperature unit for display, either `"celsius"` or `"fahrenheit"`. Note: Typically, this field is used to set the temperature unit on the mobile app.
originTempUnit	String?	The original temperature unit, either `"celsius"` or `"fahrenheit"`.
dpScale	Int?	The conversion factor between Celsius (°C) and Fahrenheit (°F).
windSpeedUnit	String?	The unit of wind speed, for example, `"m/s"`.
percent	Map<String, String>?	The DP that acts as a condition and its value that ranges from 0% to 100%.
percent1	Map<String, String>?	The DP that acts as a condition and its value that ranges from 1% to 100%.
members	String?	The list of home members that can be used for the condition of when home members come home, for example, `"Amy and Tom"`.

Example in Kotlin

// deviceId is the currently selected device.
// Retrieve the dpId, entityType, and deviceConditionData as described in the above table.
// Pass in the specified chooseValue.
val builder = DeviceConditionBuilder(
                        deviceId = conditionData.deviceId,
                        dpId = conditionData.datapointId.toString(),
                        entityType = conditionData.entityType ?: CONDITION_TYPE_DEVICE,
                        deviceConditionData = conditionData,
                        chooseValue = chooseValue
                    )
val conditionBase = builder.build() as ConditionBase
val deviceCondition = SceneCondition(conditionBase).apply {
                        entityName = deviceBean.name // Device name
                        entitySubIds = conditionData.datapointId.toString() // DP ID
                        iconUrl = deviceBean.getIconUrl()// Device icon
                        exprDisplay = displayString // Visual presentation of the conditional expression for device conditions.
                    }

Data model

DeviceConditionData

Property	Type	Description
deviceId	String	The device ID.
datapointType	`DatapointType`	The DP type. See DatapointType.
datapointId	Long	The DP ID.
datapointName	String	The DP name.
deviceIcon	String	The icon of the device.
valueTypeData	`ValueTypeData?`	The property of the value-type DP. See ValueTypeData.
otherTypeData	List<OtherTypeData>?	The property of the DP of other types. See OtherTypeData.
entityType	Int?	The condition type.
extraInfo	`ConditionExtraInfo?`	The additional information about the condition. See ConditionExtraInfo.
mcGroups	List<NewMCGroup>?	Multi-control group. See NewMCGroup.

DatapointType

Property	Type	Description
type	String	The DP type.

Enum instance	Instance property value	Description
DATAPOINT_TYPE_VALUE	`"value"`	Value type
DATAPOINT_TYPE_BOOLEAN	`"bool"`	Boolean type
DATAPOINT_TYPE_ENUM	`"enum"`	Enum instance
DATAPOINT_TYPE_RAW	`"raw"`	Raw type
DATAPOINT_TYPE_STRING	`"string"`	String type

ValueTypeData

The property of value-type DP

Property	Type	Description
value	Int	The current value, which usually takes the value of `min`.
operators	List<Pair<String, Boolean>>	The operator. Note: The first operator is selected by default, meaning that the `second` property of the first `pair` is flagged as `true`.
unit	String	The unit.
min	Int	The minimum value.
max	Int	The maximum value.
scale	Int	The number of decimal places. Note: `0` for zero decimal places. `1` for one decimal place. `2` for two decimal places.
step	Int	The step. Note: If the maximum value is 100 and the step is 10, the valid values can be `min`, `min+10`, `min+20`, and more.

OtherTypeData

Property	Type	Description
datapointKey	String	For DPs of `raw` or `string` type, the value is the DP ID. For DPs of other types, the value is the DP value.
datapointOption	String	For DPs of `raw` or `string` type, the value is the condition name. For DPs of other types, the value is the readable description of the DP ID.
checked	Boolean	The selected state.
virtualItem	Boolean?	Indicates whether a node is virtual, applying to PIR sensors only.
durationTime	String?	The duration, applying to PIR sensors only.

NewMCGroup

Property	Type	Description
id	int	The ID of the multi-control group.
groupName	String	The name of the multi-control group.

Create conditional expressions

Rule

The base class of conditional expressions.

Property	Type	Description
expr	MutableList<Any? >	The conditional expression, described in array.

Data model

ExprType

The expression type. The expression format varies by condition type.

Enum instance	Instance property value	Description
DEVICE	/	Device
WEATHER	/	Weather

BoolRule

Boolean type. An example of a complete conditional expression: [["$dp2";"=="; true]]

API description

Create a conditional expression for Boolean type.

fun newInstance(key: String, isTrue: Boolean, exprType: ExprType = ExprType.WEATHER): BoolRule

Parameter description

Parameters Type Description

key

String

Parameters	Type	Description
key	String	When `exprType` is `DEVICE`, the value is DP ID. When `exprType` is `WEATHER`, the value is `WeatherType.type`. Note: Currently, only the `DEVICE` type is available.
isTrue	Boolean	Enable or disable, corresponding to `true` or `false`.
exprType	ExprType	The expression type. See ExprType.

When exprType is DEVICE, the value is DP ID.
When exprType is WEATHER, the value is WeatherType.type.

Note: Currently, only the DEVICE type is available.

isTrue Boolean Enable or disable, corresponding to true or false.

exprType ExprType The expression type. See ExprType.

Example in Kotlin

val datapointId = "2"
val expr = mutableListOf(BoolRule.newInstance(datapointId, true, ExprType.DEVICE).expr)

EnumRule

Enum type. An example of a complete conditional expression: [["$dp21";"==";"colour"]]

API description

Create a conditional expression for enum type.

fun newInstance(key: String, chooseValue: String, exprType: ExprType = ExprType.WEATHER): EnumRule

Parameter description

Parameters	Type	Description
key	String	When `exprType` is `DEVICE`, the value is DP ID. When `exprType` is `WEATHER`, the value is `WeatherType.type`.
chooseValue	String	The selected enum values.
exprType	ExprType	The expression type. See ExprType.

Example in Kotlin

val datapointId = "21"
val chooseValue = "colour"
val expr = mutableListOf(EnumRule.newInstance(datapointId, chooseValue, ExprType.DEVICE).expr)

ValueRule

Value type. An example of a complete conditional expression: [["$dp3";"<";149]]

API description

Create a conditional expression for value type.

fun newInstance(key: String, operator: String, value: Int, exprType: ExprType = ExprType.WEATHER): ValueRule

Parameter description

Parameters	Type	Description
key	String	When `exprType` is `DEVICE`, the value is DP ID. When `exprType` is `WEATHER`, the value is `WeatherType.type`.
operator	String	The selected operator.
value	Int	The selected value.
exprType	ExprType	The expression type. See ExprType.

Example in Kotlin

val datapointId = "3"
val operator = "<"
val expr = mutableListOf(ValueRule.newInstance(datapointId, operator, 149, ExprType.DEVICE).expr)

RawRule

Raw and string type. An example of a complete conditional expression: [["$dp20"]]

API description

Create a conditional expression for raw or string type.

fun newInstance(key: String, exprType: ExprType = ExprType.WEATHER): RawRule

Parameter description

Parameters Type Description

key

String

Parameters	Type	Description
key	String	When `exprType` is `DEVICE`, the value is DP ID. When `exprType` is `WEATHER`, the value is `WeatherType.type`. Note: Currently, only the `DEVICE` type is available.
exprType	ExprType	The expression type. See ExprType.

When exprType is DEVICE, the value is DP ID.
When exprType is WEATHER, the value is WeatherType.type.

Note: Currently, only the DEVICE type is available.

exprType ExprType The expression type. See ExprType.

Example in Kotlin

val datapointId = "20"
val expr = mutableListOf(RawRule.newInstance(datapointId, ExprType.DEVICE).expr)

SunSetRiseRule

Time before or after sunrise/sunset. An example of a complete conditional expression: [{"type":"sunrise","cityId":"1442827101764976691","sunrise":10}]

API description

Create a conditional expression for a time before or after sunrise/sunset.

fun newInstance(cityId: String, type: SunType, minutes: Int): SunSetRiseRule

Parameter description

Parameters	Type	Description
cityId	String	The city ID. Note: With the longitude and latitude of the location, you can get the value of `cityId` by calling the method of querying city information by longitude and latitude. Alternatively, query the list of cities and select a city to get the city ID.
type	SunType	The expression type. See SunSetRiseRule.SunType.
minutes	Int	Minutes.

Example in Kotlin

// Retrieve the cityId as described in the above table.
// Pass in the specified type and minutes.
val type = SUNRISE
val minutes = 10
val expr = SunSetRiseRule.newInstance(cityId, type, minutes).expr

TimerRule

Schedule type. An example of a complete conditional expression: [{timeZoneId = "Asia/Shanghai";loops = "0000000";time = "17:26";date = "20220517"}]

API description

Create a conditional expression for schedule type.

fun newInstance(timeZoneId: String?, loops: String, time: String, date: String): TimerRule

Parameter description

Property	Type	Description
timeZoneId	String?	The time zone ID. Note: You can get the time zone through `Calendar.getInstance().timeZone.id`, `TimeZone.getDefault().id`, or other methods.
loops	String	The recurring pattern. 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. For example, `"0000000"`.
time	String	The time, in the format `%02d:%02d`. For example, `"08:00"`.
date	String	The date, in the format `yyyyMMdd`. For example, `"20230308"`.

Example in Kotlin

// Retrieve the timeZoneId as described in the above table.
// Pass in the specified loops, time, and date.
val expr = TimerRule.newInstance(timeZoneId, loops, time, date).expr

CalculateRule

Device derivative calculation. An example of a complete conditional expression: [[[["$dp1";"==";"nopir"];"condCalculate";"$calObj"];"==";true]]

API description

Create a conditional expression for the calculation type.

fun newInstance(key: String, chooseValue: Any): CalculateRule

Parameter description

Property	Type	Description
key	String	The DP ID.
chooseValue	Any	The selected enum values.

Example in Kotlin

val datapointId = "1"
val chooseValue = "nopir"
val expr = mutableListOf(CalculateRule.newInstance(datapointId, chooseValue).expr)

LockMemberRule

When home members come home. An example of a complete conditional expression: [[["$devId";"lockRecognition";"$allData"];"inRange";"1223421,1273723"]]

API description

Create a conditional expression for when home members come home.

fun newInstance(memberIds: String): LockMemberRule

Parameter description

Property	Type	Description
memberIds	String	A list of IDs of the selected home members, separated with commas (,). For example, `"1223421,1273723"`

Example in Kotlin

val memberIds = "1223421,1273723"
val expr = mutableListOf(LockMemberRule.newInstance(memberIds).expr)

GeofenceRule

Geofence type. An example of a complete conditional expression: [["$action";"==";"exit"]]

API description

Create a conditional expression for geofence type.

fun newInstance(type: String): GeofenceRule

Parameter description

Property	Type	Description
type	String	The type of the geofence. See GeofencingType.type.

Example in Kotlin

val geofenceType = "exit"
val expr = mutableListOf(GeofenceRule.newInstance(geofenceType).expr)

Create scene actions

Delay the action

Class

class DelayActionBuilder(minutes: Int, seconds: Int)

Parameters

Property	Type	Description
minutes	Int	Minutes delay.
seconds	Int	Seconds delay.

Example in Kotlin

val actionBase: ActionBase = DelayActionBuilder(62, 20).build() as ActionBase
val delayAction = SceneAction(actionBase).apply {
                    entityName = "Delay the action"
                }

Send notification

Class

class NotifyActionBuilder(notifyType: String)

Parameters

Property	Type	Description
notifyType	String	The notification type, including `"appPushTrigger"`, `"smsSend"`, and `"mobileVoiceSend"`.

Example in Kotlin

val unableTip = "Phone call notification expired"
val actionBase: ActionBase = NotifyActionBuilder("mobileVoiceSend").build() as ActionBase
val notifyAction = SceneAction(actionBase).apply {
        entityName = "Phone call notification"
    if (it.pushType != PushType.PUSH_TYPE_MESSAGE && !it.unableTip.isNullOrEmpty()) {
        actionDisplayNew = mutableMapOf(
                               "voice_package_has_expired" to listOf(it.unableTip),
                               "package_has_expired" to listOf(it.unableTip)
                           )
     }
}

Data model

PushType

Property	Type	Description
type	String	The notification type.

Enum instance	Instance property value	Description
PUSH_TYPE_MESSAGE	`"personal_push_message_service"`	Message center
PUSH_TYPE_MOBILE	`"personal_push_call_service"`	Phone call
PUSH_TYPE_SMS	`"personal_push_sms_service"`	SMS message

Select smart scenes

Class

class LinkageRuleActionBuilder(linkageRuleId: String, linkageOperator: String)

Parameters

Property	Type	Description
linkageRuleId	String	The linkage ID.
linkageOperator	String	The linkage type, including `"ruleTrigger"`, `"ruleEnable"`, and `"ruleDisable"`.

Example in Kotlin

val actionBase: ActionBase = LinkageRuleActionBuilder(linkageData.linkageId, "ruleTrigger").build() as ActionBase
val linkageAction = SceneAction(actionBase).apply {
         entityName = linkageData.linkageName // Linkage name
}

Control single device

Class

class DeviceActionBuilder(
              devId: String,
              deviceActionDetailData: DeviceActionDetailBean,
              selDpValue: Any?,
              selDpDisplayValue: Any,
              isStep: Boolean = false)

Parameters

Property	Type	Description
devId	String	The device ID or group ID.
deviceActionDetailData	`DeviceActionDetailBean`	The data model of the device action. Note: See DeviceActionDetailBean, which is converted from ActionDeviceDataPointList used in the method for querying the list of DPs for action device.
selDpValue	Any?	The selected value.
selDpDisplayValue	Any	Display the selected value.
isStep	Boolean	Specifies whether a step applies.

Optional parameters

Property	Type	Description
originTempUnit	String?	The original temperature unit, either `"celsius"` or `"fahrenheit"`.
dpScale	Int?	The conversion factor between Celsius (°C) and Fahrenheit (°F).
convertTemp	MutableMap<String, Int>?	Temperature unit conversion. Note: Two key-value pairs are included, one for the original temperature unit and its corresponding value, and another for the preferred temperature unit and its corresponding value.
type	DeviceStepType?	The step type. See DeviceStepType.

Example in Kotlin

// Pass in the specified deviceId and selDpValue.
// Retrieve the deviceActionDetailData as described in the above table.
// selDpDisplayValue  Perform visual DP conversion according to user selection.
val builder = DeviceActionBuilder(deviceId, deviceActionDetailData, selDpValue, selDpDisplayValue ?: "")
                .apply {
                    originTempUnit?.let {
                        this.setOriginTempUnit(it)
                    }
                    dpScale?.let {
                        this.setDpScale(it)
                    }
                    convertTemp?.let {
                        this.setConvertTemp(it)
                    }
                }
val actionBase: ActionBase = builder.build() as ActionBase
SceneAction(actionBase).apply {
            actionDisplayNew = actionDisplayMap // Visual presentation of the selected DP.
            this.actionExecutor = ACTION_TYPE_DEVICE_GROUP // Group action executor
                      // The following are the icon, online status, and name of the group.
            DeviceUtil.getGroupDevice(dpDialogBean.deviceActionDetailBean.deviceId.toLong())?.let {
                  this.devIcon = it.iconUrl
                  this.isDevOnline = it.isOnline
                  this.entityName = it.name
}

Data model

DeviceActionDetailBean

Property	Type	Description
itemIndex	int	The sequence number of the feature.
hasEdit	boolean	Indicates whether the feature is in the edit state.
functionId	Long	The ID of the device feature.
functionName	String	The name of the device feature.
functionType	int	The type of the device feature. `0`: a common DP. `1`: a combined DP.
currentValue	Object	The current value.
entityId	String	The ID of the action entity, which is device ID or group ID.
deviceActionDataList	List<DeviceActionData>	A list of device DPs. See DeviceActionData.
hasChoose	boolean	Indicates whether the DP is selected. Note: In Zigbee standard local scenes, a DP of one device can be selected only once.
deviceId	String	The device ID or group ID.
deviceType	DeviceType	The type, either device or group.

DeviceActionData

Property	Type	Description
id	long	The unique ID of the DP. Note: Currently, only the combined DP has a valid ID property.
dpName	String	The name of the device DP.
dpId	int	The ID of the device DP.
isEditable	Boolean	Indicates whether the DP can be edited.
stepHighDpProperty	`StepDpProperty`	The valid step values for increment. See StepDpProperty.
stepLowDpProperty	`StepDpProperty`	The valid step values for decrement. See StepDpProperty.
step	int	The step value.
type	String	The step type. See DeviceStepType.type.
datapointType	`DatapointType`	The DP type. See DatapointType.
lightType	`LightType`	The light type, corresponding to the value of `valueType` in ActionDeviceDataPointDetail. See LightType.
dpValueType	`DeviceDpValueType`	The display type for value-type DPs. See DeviceDpValueType.
dpValueTypeData	`DpValueTypeData`	The property of the value-type DP. See DpValueTypeData.
dpEnumTypeData	`DpEnumTypeData`	The property of the enum-type DP. See DpEnumTypeData.

StepDpProperty

Property	Type	Description
value	List<Integer>	A list of step values.

LightType

Property	Type	Description
type	String	`valueType` enum.

Enum instance	Instance property value	Description
LIGHT_TYPE_COLOR_NEW	`"color2"`	New colored light.
LIGHT_TYPE_COLOR_OLD	`"color1"`	Legacy colored light.
LIGHT_TYPE_COLOR_LEGACY	`"color"`	Legacy colored light is reserved for backward compatibility.
LIGHT_TYPE_BRIGHT	`"bright"`	Brightness of the white light.
LIGHT_TYPE_TEMP	`"light_temp"`	Temperature of the white light.
LIGHT_TYPE_NULL	`""`	Empty string.

DeviceDpValueType

Property	Type	Description
type	String	The display type for value-type DPs.

Enum instance	Instance property value	Description
DP_VALUE_TYPE_COUNTDOWN	`"countdown"`	Hour:Minute:Second format.
DP_VALUE_TYPE_COUNTDOWN_1	`"countdown1"`	Hour:Minute format.
DP_VALUE_TYPE_PERCENT	`"percent"`	Percentage format, ranging from 0% to 100%.
DP_VALUE_TYPE_PERCENT_1	`"percent1"`	Percentage format, ranging from 1% to 100%.
DP_VALUE_TYPE_NORMAL	`"normal"`	Common format.

DpValueTypeData

Property	Type	Description
currentValueKey	Object	The selected value.
unit	String	The unit.
min	int	The minimum value.
max	int	The maximum value.
scale	int	The number of decimal places. Note: `0` for zero decimal places. `1` for one decimal place. `2` for two decimal places.
step	int	The step. Note: If the maximum value is 100 and the step is 10, the valid values can be `min`, `min+10`, `min+20`, and more.

DpEnumTypeData

Property	Type	Description
value	List<String>	The display value of the enum list.
valueKey	List<Object>	The key of the enum list.
currentIndex	int	The index of the enum value.

DeviceStepType

Property	Type	Description
type	String	The step type.

Enum instance	Instance property value	Description
LOW	`"low"`	Decrease
HIGH	`"high"`	Increase

DeviceType

Enum instance	Instance property value	Description
COMMON_DEVICE	/	Device
GROUP_DEVICE	/	Group

Create effective period

Class and property

See PreCondition and PreConditionExpr.

Example in Kotlin

Call the method of querying city information by longitude and latitude and get the cityId for city ID and the city for city name. Alternatively, query the list of cities and select a city to get the city ID. Other information is populated with the user’s selection.

PreCondition().apply {
        val expr = PreConditionExpr()
        expr.cityName = "Hangzhou"
        expr.cityId = "1442827101764976691"
        expr.start = "00:00"
        expr.end = "23:59"
        expr.loops = "1111111"
        expr.timeInterval = TimeInterval.TIME_INTERVAL_ALL_DAY.value
        expr.timeZoneId = TimeZone.getDefault().id
        this.expr = expr
        condType = PreCondition.TYPE_TIME_CHECK
    }

Data model

TimeInterval

Property	Type	Description
value	String	The type of the effective period.

Enum instance	Instance property value	Description
TIME_INTERVAL_CUSTOM	`"custom"`	Custom time
TIME_INTERVAL_DAY	`"daytime"`	Daytime
TIME_INTERVAL_NIGHT	`"night"`	Nighttime
TIME_INTERVAL_ALL_DAY	`"allDay"`	All day

Data transfer object (DTO) model conversion

Convert condition device DP model to DTO model

API description

Convert the ConditionItemDetail returned by querying the list of DPs for condition device into DeviceConditionData.

fun ConditionItemDetail.mapToDeviceConditionData(devId: String): DeviceConditionData

Parameter description

Parameters	Type	Description
devId	String	The device ID.

Example in Kotlin

// deviceRepository defines the following suspend methods. You can get the list of DPs of the condition devices from the scene SDK.
suspend fun getConditionDeviceDpAll(deviceId: String): List<ConditionItemDetail> =
        suspendCoroutine {
            val callback = object : IResultCallback<List<ConditionItemDetail>?> {
                override fun onSuccess(result: List<ConditionItemDetail>?) {
                    it.resume(result ?: emptyList())
                }

                override fun onError(errorCode: String?, errorMessage: String?) {
                    it.resumeWithException(Exception(errorMessage))
                }
            }

            sceneService.deviceService().getConditionDeviceDpAll(deviceId, callback)
        }

// After calling the above method to get conditionItemDetailList, perform model conversion.
val conditionItemDetailList: List<ConditionItemDetail> = deviceRepository.getConditionDeviceDpAll(deviceId)
conditionItemDetailList.map { conditionItemDetail ->
                conditionItemDetail.mapToDeviceConditionData(deviceId)
}

Convert action device DP model to DTO model

API description

Convert the ActionDeviceDataPointList returned by querying the list of DPs for action device into DeviceActionDetailBean.

fun ActionDeviceDataPointList.mapToDeviceActionData(
    entityId: String,
    deviceId: String,
    deviceType: DeviceType,
    sceneAction: SceneAction? = null,
    togglePreFilter: () -> Boolean = { false }
): DeviceActionDetailBean?

Parameter description

Parameters	Type	Description
entityId	String	When the entity is a device, the value is the device ID. When the entity is a group, the following rules apply: Note: Preference is given to the ID of the device whose PID matches both the PID of the group and the PID of the first sub-device. If such a device does not exist, the ID of the first sub-device in the group is used. If the group is empty, use the group ID.
deviceId	String	The device ID or group ID.
deviceType	DeviceType	The type, either device or group.
sceneAction	SceneAction?	The scene action that is being edited.
togglePreFilter	() -> Boolean	The filter logic for one-tap toggle when users edit a scene. Note: Currently, the one-tap toggle option for Boolean DP is filtered out when users edit Zigbee standard local scenes.

Example in Kotlin

// deviceRepository defines the following suspend methods. You can get the list of DPs of the action devices (including groups) from the scene SDK.
suspend fun getActionDeviceDpAll(deviceId: String): List<ActionDeviceDataPointList> =
        suspendCoroutine {
            val callback = object : IResultCallback<List<ActionDeviceDataPointList>?> {
                override fun onSuccess(result: List<ActionDeviceDataPointList>?) {
                    it.resume(result ?: emptyList())
                }

                override fun onError(errorCode: String?, errorMessage: String?) {
                    it.resumeWithException(Exception("getActionDeviceDpAll onError, errorCode: $errorCode, errorMsg: $errorMessage"))
                }
            }

            sceneService.deviceService().getActionDeviceDpAll(deviceId, callback)
        }

// Call the above method to get fusedFunctions and then perform model conversion.
fusedFunctions.forEachIndexed { _, function ->
    function.mapToDeviceActionData(deviceId, deviceId, deviceType, sceneAction) { isBoundForPanel && !isAllDevice }
        ?.let { deviceActionDetailBean ->
            deviceActionDetailList.add(deviceActionDetailBean)
        }
}

Prev DocGroup Management

Next DocFAQs