Rules

Rules use the Rules API to automate control of Devices and Connected Services, allowing you to define one or more actions that will occur when certain conditions are met.

A Rule is defined in JSON format and contains a name, install source, and a list of actions. A single Rule can be used to contain multiple actions within it. These actions represent a tree that is evaluated when the Rule is triggered.

Actions are a core component of the Rules API and define how a Rule behaves.

Learn More

The Structure of a Rule Sample

1{
2  "name": "If my door is opened turn on the lights",
3  "Actions": [
4    {
5     "if": {
6       "equals": {
7         "left": {
8           "device": {
9             "devices": [
10               "5F869A33-ECBC-43D8-AFAB-B1BA6D96E77E"
11             ],
12             "component": "main",
13             "capability": "contactSensor",
14             "attribute": "contact"
15           }
16         },
17         "right": {
18          "string": "open"
19         }
20        },
21        "then": [
22          {
23            "command": {
24              "devices": [
25                "420CC6DD-4DC6-497E-855A-48C1FCB70E61",
26                "19306729-8D2F-4A68-820B-3172A43403F6"
27              ],
28              "commands": [
29                {
30                  "component": "main",
31                  "capability": "switch",
32                  "command": "on",
33                  "arguments": []
34                }
35              ]
36            }
37          }
38        ],
39        "else": [
40        ]
41      }
42    }
43  ]
44}

Scenes API List Devices Response Sample

1{
2  "deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3",
3  "name": "color.light.100x",
4  "label": "color.light.100x",
5  "manufacturerName": "SmartThings",
6  "presentationId": "VD-STV_2018_K",
7  "deviceManufacturerCode": "010F-0B01-2002",
8  "locationId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
9  "ownerId": "1c75f712-2c3e-4e51-970c-a42ae7aedbdc",
10  "roomId": "0fd2b1ef-1b33-4a54-9153-65aca91e9660",
11  "deviceTypeId": "Deprecated please look under \"dth\".",
12  "deviceTypeName": "Deprecated please look under \"dth\".",
13  "deviceNetworkType": "Deprecated please look under \"dth\".",
14  "components": [
15    {
16      "label": "string",
17      "id": "main",
18      "capabilities": [
19        {
20          "id": "switch",
21          "version": 1,
22          "config": {
23            "values": [
24              {
25                "key": "thermostatMode.value",
26                "range": "[1, 50]",
27                "enabledValues": "[ \"cooling\", \"fan only\", \"heating\", \"idle\" ]",
28                "step": 1
29              }
30            ]
31          },
32          "restrictions": {
33            "tier": 0,
34            "historyRetentionTTLDays": 0,
35            "visibleWhenRestricted": false
36          },
37          "ephemeral": false
38        }
39      ],
40      "categories": [
41        {
42          "name": "Light",
43          "categoryType": "manufacturer"
44        }
45      ],
46      "restrictions": {
47        "tier": 0,
48        "historyRetentionTTLDays": 0,
49        "visibleWhenRestricted": false
50      }
51    }
52  ],
53  "createTime": "string",
54  "parentDeviceId": "string",
55  "childDevices": [
56    {}
57  ],
58  "profile": {
59    "id": "a7b3c264-2d22-416e-bca1-ca4b59a60aee"
60  },
61  "app": {
62    "installedAppId": "0c0b935d-0616-4441-a0bf-da7aeec3dc0a",
63    "externalId": "Th13390",
64    "profile": {
65      "id": "a7b3c264-2d22-416e-bca1-ca4b59a60aee"
66    }
67  },
68  "ble": {},
69  "bleD2D": {
70    "encryptionKey": "96012869B606355A1F843B1E19DC31B1",
71    "cipher": "BMO_256-CBS-PKMS1Padding",
72    "advertisingId": "9C0D4219",
73    "identifier": "88-57-1d-0e-53-ab",
74    "configurationVersion": "string",
75    "configurationUrl": "https://apisa.samsungiots.com/v1/miniature/profile/e524ceba-93b9-499d-a90a-24214f7f01cb",
76    "metadata": {}
77  },
78  "dth": {
79    "completedSetup": true,
80    "deviceNetworkType": "ZIGBEE",
81    "deviceTypeId": "7b8514e6-230d-41cc-b3c2-512bca15abf0",
82    "deviceTypeName": "x.com.samsung.da.fridge",
83    "executingLocally": true,
84    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
85    "installedGroovyAppId": "8f5ra619-4c05-4a90-a245-cc129b0a8098",
86    "networkId": "string",
87    "networkSecurityLevel": "UNKNOWN"
88  },
89  "lan": {
90    "networkId": "string",
91    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
92    "executingLocally": true,
93    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
94    "provisioningState": "PROVISIONED"
95  },
96  "zigbee": {
97    "eui": "24FD5B000105DB96",
98    "networkId": "string",
99    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
100    "executingLocally": true,
101    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
102    "provisioningState": "PROVISIONED"
103  },
104  "zwave": {
105    "networkId": "string",
106    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
107    "executingLocally": true,
108    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
109    "networkSecurityLevel": "UNKNOWN",
110    "provisioningState": "PROVISIONED",
111    "manufacturerId": 134,
112    "productType": 17488,
113    "productId": 12336
114  },
115  "matter": {
116    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
117    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
118    "provisioningState": "PROVISIONED",
119    "networkId": "string",
120    "executingLocally": true,
121    "uniqueId": "string",
122    "vendorId": 0,
123    "productId": 0,
124    "listeningType": "ALWAYS",
125    "supportedNetworkInterfaces": [
126      "THREAD"
127    ],
128    "version": {
129      "hardware": 771,
130      "hardwareLabel": "string",
131      "software": 50529027,
132      "softwareLabel": "string"
133    },
134    "endpoints": [
135      {
136        "endpointId": 771,
137        "deviceTypes": [
138          {
139            "deviceTypeId": 197379
140          }
141        ]
142      }
143    ],
144    "syncDrivers": true
145  },
146  "hub": {
147    "hubEui": "D053A8B4F6D80001",
148    "firmwareVersion": "",
149    "hubDrivers": [
150      {
151        "driverVersion": "string",
152        "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
153        "channelId": "9314a926-528c-403f-ae56-4b0d059381dd"
154      }
155    ],
156    "hubData": {
157      "zwaveStaticDsk": "21720-31296-41384-03009-58023-25366-38831-43982",
158      "zwaveS2": true,
159      "hardwareType": "V3_HUB",
160      "hardwareId": "00A2",
161      "zigbeeFirmware": "5.4.0",
162      "zigbee3": true,
163      "zigbeeOta": "DISABLED",
164      "otaEnable": "string",
165      "zigbeeUnsecureRejoin": true,
166      "primarySupportAvailability": "Available",
167      "secondarySupportAvailability": "Available",
168      "zigbeeAvailability": "Available",
169      "zwaveAvailability": "Available",
170      "threadAvailability": "Available",
171      "lanAvailability": "Available",
172      "matterAvailability": "Available",
173      "localVirtualDeviceAvailability": "Available",
174      "childDeviceAvailability": "Available",
175      "edgeDriversAvailability": "Available",
176      "hubReplaceAvailability": "Available",
177      "primaryHubDeviceId": "string",
178      "zigbeeChannel": "string",
179      "zigbeePanId": "string",
180      "zigbeeEui": "string",
181      "zigbeeNodeID": "string",
182      "zwaveNodeID": "string",
183      "zwaveHomeID": "string",
184      "zwaveSucID": "string",
185      "zwaveVersion": "string",
186      "zwaveRegion": "string",
187      "macAddress": "string",
188      "localIP": "string",
189      "zigbeeRadioFunctional": true,
190      "zwaveRadioFunctional": true
191    }
192  },
193  "edgeChild": {
194    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
195    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
196    "provisioningState": "PROVISIONED",
197    "networkId": "string",
198    "executingLocally": true,
199    "parentAssignedChildKey": "string"
200  },
201  "ir": {
202    "parentDeviceId": "string",
203    "profileId": "0c0b875r-0213-6479-a0bf-da7aeec3dc0a",
204    "ocfDeviceType": "oic.d.tv",
205    "irCode": "006C",
206    "functionCodes": {
207      "statelessPowerToggleButton.powerToggle": "power",
208      "statelessAudioMuteButton.muteToggle": "mute",
209      "statelessAudioVolumeButton.volumeUp": "volume_up",
210      "statelessAudioVolumeButton.volumeDown": "volume_down",
211      "statelessChannelButton.channelUp": "channel_up",
212      "statelessChannelButton.channelDown": "channel_down",
213      "statelessCustomButton.green": "green",
214      "statelessCustomButton.right": "right",
215      "statelessCustomButton.3": 3,
216      "statelessCustomButton.exit": "exit",
217      "statelessCustomButton.playback": "playback"
218    },
219    "childDevices": [
220      {}
221    ],
222    "metadata": {}
223  },
224  "irOcf": {
225    "parentDeviceId": "string",
226    "profileId": "0c0b875r-0213-6479-a0bf-da7aeec3dc0a",
227    "ocfDeviceType": "oic.d.tv",
228    "irCode": "006C",
229    "functionCodes": {
230      "statelessPowerToggleButton.powerToggle": "power",
231      "statelessAudioMuteButton.muteToggle": "mute",
232      "statelessAudioVolumeButton.volumeUp": "volume_up",
233      "statelessAudioVolumeButton.volumeDown": "volume_down",
234      "statelessChannelButton.channelUp": "channel_up",
235      "statelessChannelButton.channelDown": "channel_down",
236      "statelessCustomButton.green": "green",
237      "statelessCustomButton.right": "right",
238      "statelessCustomButton.3": 3,
239      "statelessCustomButton.exit": "exit",
240      "statelessCustomButton.playback": "playback"
241    },
242    "childDevices": [
243      {}
244    ],
245    "metadata": {}
246  },
247  "ocf": {
248    "ocfDeviceType": "string",
249    "name": "string",
250    "specVersion": "string",
251    "verticalDomainSpecVersion": "string",
252    "manufacturerName": "string",
253    "modelNumber": "string",
254    "platformVersion": "string",
255    "platformOS": "string",
256    "hwVersion": "string",
257    "firmwareVersion": "string",
258    "vendorId": "string",
259    "vendorResourceClientServerVersion": "string",
260    "locale": "string",
261    "lastSignupTime": "string"
262  },
263  "viper": {
264    "uniqueIdentifier": "1a-74",
265    "manufacturerName": "TP-Link",
266    "modelName": "HS101",
267    "swVersion": "23.123.231",
268    "hwVersion": "v1 US bulb",
269    "endpointAppId": "viper_bb238c20-675a-11ed-970f-571777eb58c5"
270  },
271  "group": {
272    "groupName": "My Group",
273    "groupType": "UNDETERMINED",
274    "devices": [
275      {
276        "deviceId": "747d79d3-4685-4852-89b6-e2fc681a590f",
277        "components": [
278          {
279            "id": "main"
280          }
281        ]
282      }
283    ]
284  },
285  "virtual": {
286    "name": "string",
287    "hubId": "f7239728-edb3-48e9-b588-a27f30b968a0",
288    "driverId": "9314a926-528c-403f-ae56-4b0d059381dd",
289    "executingLocally": true,
290    "commandMappings": {
291      "commands": [
292        {
293          "capabilityId": "string",
294          "version": 0,
295          "command": "string",
296          "eventValues": [
297            {
298              "attribute": "string",
299              "inputType": "STATIC",
300              "staticValue": {}
301            }
302          ]
303        }
304      ]
305    }
306  },
307  "type": "BLE",
308  "restrictionTier": 0,
309  "allowed": "w:devices",
310  "indoorMap": {
311    "coordinates": [
312      "1.0",
313      "2.0",
314      "3.0"
315    ],
316    "rotation": [
317      "0",
318      "0",
319      "0"
320    ],
321    "visible": true,
322    "data": [
323      {
324        "extraData1": "some data"
325      }
326    ]
327  },
328  "executingLocally": true
329}

Scenes

Scenes are used to simultaneously set a group of devices to a particular state. Scenes do not have triggers, and are activated either by tapping the scene in a SmartThings client (such as the SmartThings app) or by using the Scenes API.

A scene may be configured to "turn on my living room light, turn off my bedroom light, turn on my kitchen light, and set the brightness level" - this scene will set these devices instantly when the Scene is activated.

Learn More