Rules¶
Rules provide the ability to trigger actions of lights or groups when a specific sensor condition is met.
Create rule ¶
POST /api/<apikey>/rules
Creates a new rule.
Parameters¶
| Field | Type | Description | Required |
|---|---|---|---|
| actions | Array (1–8) | An array of actions that will happen when the rule triggers. | required |
| action.address | String | path to a light, group or scene resource | required |
| action.body | Object | Parameters that will be send to the resource formated as JSON. | required |
| action.method | String | Can be PUT, POST or DELETE. | required |
| conditions | Array(condition) (1–8) | The conditions that must be met to trigger a rule. | required |
| condition.address | String | path to a sensor resource and the related state | required |
| condition.operator | String | eq, gt, lt, dx (equals, greater than, lower than, on change). | required |
| condition.value | String | The value the operator is compared with. Will be casted automatically to the corresponding data type. | required |
| name | String | The name of the rule. | required |
| periodic | Number | Specifies if the rule should trigger periodically. 0 = trigger on event; >0 = time in ms the rule will be triggered periodically. Default is 0. | optional |
| status | String | The status of the rule, either "enabled" or "disabled". Default is "enabled". | optional |
Example request data¶
{
"actions": [
{
"address": "/groups/0/action",
"body": {
"on": true
},
"method": "BIND"
}
],
"conditions": [
{
"address": "/sensors/1/state/buttonevent",
"operator": "eq",
"value": "1"
}
],
"name": "Switch button 1 all lights On/Off"
}
This will create a binding between a switch and the On/Off Cluster of all Lights of the group 0.
Response¶
HTTP/1.1 200 OK
[ { "success": { "id": "1" } } ]
Response fields¶
| Field | Type | Description |
|---|---|---|
| id | String | The unique identifier of the new rule. |
Possible errors¶
Get all Rules ¶
GET /api/<apikey>/rules
Returns a list of all rules. If there are no rules in the system then an empty object {} will be returned.
Parameters¶
None
Response¶
HTTP/1.1 200 OK
{
"1": {
"actions": [
{
"address": "/lights/1/state",
"body": {
"on": true
},
"method": "BIND"
}
],
"conditions": [
{
"address": "/sensors/2/state/buttonevent",
"operator": "eq",
"value": "4"
}
],
"created": "2016-07-04T14:17:12",
"etag": "9bd1fcc627001458ea88c8742e61c692",
"lasttriggered": "none",
"name": "Sensor: 2 EP:4 On/Off",
"owner": "AD4F14F244",
"periodic": 0,
"status": "enabled",
"timestriggered": 0
},
"2": {
"actions": [
{
"address": "/groups/0/action",
"body": {
"on": false
},
"method": "PUT"
}
],
"conditions": [
{
"address": "/sensors/5/state/buttonevent",
"operator": "eq",
"value": "34"
},
{
"address": "/sensors/5/state/lastupdated",
"operator": "dx"
}
],
"created": "2016-07-05T13:36:52",
"etag": "0fb118418fa77116052f74fb129a648b",
"lasttriggered": "none",
"name": "0x0000000000402483[Rule1]",
"owner": "AD4F14F244",
"periodic": 0,
"status": "enabled",
"timestriggered": 0
}
}
Response fields¶
The whole rule object as descripted in Get rule.
Possible errors¶
Get rule ¶
GET /api/<apikey>/rules/<id>
Returns the rule with the specified id.
Parameters¶
None
Response¶
HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"
{
"actions": [
{
"address": "/lights/1/state",
"body": {
"on": true
},
"method": "BIND"
}
],
"conditions": [
{
"address": "/sensors/2/state/buttonevent",
"operator": "eq",
"value": "4"
}
],
"created": "2016-07-04T14:17:12",
"etag": "9bd1fcc627001458ea88c8742e61c692",
"lasttriggered": "none",
"name": "Sensor: 2 EP:4 On/Off",
"owner": "AD4F14F244",
"periodic": 0,
"status": "enabled",
"timestriggered": 0
}
Response fields¶
| Field | Type | Description |
|---|---|---|
| actions | Array | An array of actions that will happen when the rule triggers. |
| action.address | String | path to a light, group or scene resource |
| action.body | Object | Parameters that will be send to the resource formated as JSON. |
| action.method | String | Can be PUT, POST or DELETE. |
| conditions | Array | The conditions that must be met to trigger a rule. |
| condition.address | String | path to a sensor resource |
| condition.operator | String | eq, gt, lt, dx (equals, greater than, lower than, on change). |
| condition.value | String | The value the operator is compared with. Will be casted automatically to the corresponding data type. |
| created | String | Timestamp when the rule was created. |
| etag | String | HTTP etag which changes whenever the rule is changed. |
| lasttriggered | String | Timestamp when the rule was last triggered. |
| name | String | The name of the rule. |
| owner | String | The owner of the rule. |
| periodic | Number | Specifies if the rule should trigger periodically. 0 = trigger on event; >0 = time in ms the rule will be triggered periodically. |
| status | String | The status of the rule, either "enabled" or "disabled". |
| timestriggered | Number | Times the rule was triggered. |
Possible errors¶
Update rule ¶
PUT /api/<apikey>/rules/<id>/
Update a rule with the specified parameters.
Parameters¶
| Field | Type | Description | Required |
|---|---|---|---|
| actions | Array (1–8) | An array of actions that will happen when the rule triggers. | optional |
| conditions | Array (1–8) | The conditions that must be met to trigger a rule. | optional |
| name | String | The name of the rule. | optional |
| periodic | Number | Specifies if the rule should trigger periodically. 0 = trigger on event; >0 = time in ms the rule will be triggered periodically. Default is 0. | optional |
| status | String | The status of the rule, either "enabled" or "disabled", the default is "enabled". | optional |
Example request data¶
{
"actions": [
{
"address": "/lights/1/state",
"body": {
"bri": 1
},
"method": "BIND"
}
]
}
Response¶
HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"
[
{
"success": { "/rules/1/actions":
{
"address": "/lights/1/state",
"body": {
"bri": 1
},
"method": "BIND"
}
}
}
]
Possible errors¶
Delete rule ¶
DELETE /api/<apikey>/rules/<id>
Delete a rule.
Parameters¶
None
Response¶
HTTP/1.1 200 OK
ETag: "030cf8c1c0025420f3a0659afab251f5"
[{ "success": "1"}]