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
| Name | Type | Description | Required |
|---|---|---|---|
| name | String | Name of the rule | Required |
| actions | Array 1–8 | Actions the rule should execute | Required |
| conditions | Array 1–8 | Conditions to trigger the actions | Required |
| status | String | “enabled” or “disabled” | Optional |
actions object
| Name | Type | Description | Required |
|---|---|---|---|
| address | String | Path to a light, group, sensor or scene resource | Required |
| body | Object | Parameters that will be send to the resource | Required |
| method | String | Method like PUT, POST or DELETE | Required |
conditions object
| Name | Type | Description | Required |
|---|---|---|---|
| address | String | Path to a resource and given attribute | Required |
| operator | Object | eq, gt, lt, dx, ddx, stable, in, not in | Required |
| value | String | Value the resource attribute is testet against via operator. Will be casted automatically to the corresponding data type. | Required |
| Field | Type | Description | Required |
|---|---|---|---|
| actions | Array(action) (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, 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, ddx, stable, in, not in (see conditions). | 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 |
| status | String (“enabled”|“disabled”) | The status of the rule. Default is enabled. | optional |
Conditions
Following operators are allowed in a condition.
| Condition | Description | Explanation |
|---|---|---|
| eq | equals | Used for bool and int. |
| gt | greater than | Allowed on int values. |
| lt | lower than | Allowed on int values. |
| dx, ddx | on change, delayed on change | Time (timestamps) int and bool values. Only dx or ddx is allowed, but not both. Triggers when value of button event is changed or change of presence is detected. |
| stable | stable for a given time | Time (timestamps) int and bool values. An attribute has changed for a given time. Does not trigger a rule change. Not allowed on /config/utc and /config/localtime |
| in | Current time is in given time interval (only for /config/localtime, not UTC) | “in” rule will be triggered on starttime. Only one “in” operator is allowed in a rule. Not allowed to be combined with “not in”. |
| not in | Current time is not in given time interval (only for /config/localtime, not UTC) | “not in” rule will be triggered on endtime. Multiple “not in” operators are allowed in a rule. Not allowed to be combined with “in”. |
Example request data
{
"actions": [
{
"address": "/groups/0/action",
"body": {
"on": true
},
"method": "PUT"
}
],
"conditions": [
{
"address": "/sensors/1/state/buttonevent",
"operator": "eq",
"value": "1000"
}
],
"name": "Switch button 1 all lights On/Off"
}This will put all Lights of the group 0 to on when a button on a switch is pressed.
Response
[ { "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
{
"1": {
"actions": [
{
"address": "/lights/1/state",
"body": {
"on": true
},
"method": "PUT"
}
],
"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 for the specified id.
Parameters
None
Response
{
"actions": [
{
"address": "/lights/1/state",
"body": {
"on": true
},
"method": "PUT"
}
],
"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(action) | 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, DELETE |
| conditions | Array(condition) | 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, ddx, stable, in, not in (see conditions). |
| 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. |
| status | String (“enabled”|“disabled”) | The status of the rule. |
| 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(action) (1..8) | An array of actions that will happen when the rule triggers. | optional |
| conditions | Array(condition) (1..8) | The conditions that must be met to trigger a rule. | optional |
| name | String | The name of the rule. | optional |
| status | String (“enabled”|“disabled”) | The status of the rule. Default is enabled. | optional |
For information about conditions see conditions.
Example request data
{
"actions": [
{
"address": "/lights/1/state",
"body": {
"bri": 10
},
"method": "PUT"
}
]
}Response
[
{
"success": { "/rules/1/actions":
{
"address": "/lights/1/state",
"body": {
"bri": 10
},
"method": "PUT"
}
}
}
]Possible errors
Delete rule
DELETE /api/<apikey>/rules/<id>
Delete a rule.
Parameters
None
Response
[{ "success": "1"}]