Items commands
hub.items.list
Connection type: UI
Permissions: EZLO: READ/VIEW
Provides a list of registered items on the hub.
Note: this request doesn't take a device id, so it returns items for ALL devices.
request:
{
"method": "hub.items.list",
"id": "_ID_",
"params": {}
}
request with filter by deviceId:
{
"method": "hub.items.list",
"id": "_ID_",
"params": {
"deviceIds": [
"deviceId0",
"deviceId1"
]
}
}
Field | Type | Required | Description |
---|---|---|---|
deviceIds (optional) | string[] | - | Device ID array to filter device items list with. |
response:
Field | Type | Required | Description |
---|---|---|---|
_id | string | + | An id of the item |
deviceId | string | + | An id of a device this item belongs to |
deviceName | string | - | see device.name !!!MUST BE DROPPED!!! temporary add for house mode events |
deviceArmed | bool | - | see device.armed !!!MUST BE DROPPED!!! temporary add for house mode events |
enum | array | - | Finite array of possible token values |
hasGetter | bool | + | Whether the item provides an ability to get a value |
hasSetter | bool | + | whether the item provides an ability to set a value |
name | string | + | A name(type) of the item |
show | bool | + | Whether to show the item (on the UI) or not |
scale | string | - | A name of measurement units |
valueType | string | + | A type of an item's value |
valueFormatted | string | + | An item formatted value |
value | object | + | An item value |
minValue | number | - | Lower limit of item's value field, (for scalable values - only numeric part) |
maxValue | number | - | Upper limit of item's value field, (for scalable values - only numeric part) |
elementsMaxNumber | int | - | max allowed elements of a dictionary or an array value |
stringRestriction | string | - | Regexp restriction for a value in item of value type string |
userCodeRestriction | string | - | Regexp restriction for a field code in any value of userCode value type. E.g. it's used in item user_codes . |
userCodeModes | JsonArray | - | List of available pin code modes. It's used in user_codes item. |
elementsMaxNumberPerArray | int | - | max allowed elements of each array ( if array is subtype of dictionary or another array ) |
oneWeekDayCost | int | - | cost of one week day in item weekly_user_code_intervals . |
oneShiftedWeekDayCost | int | - | cost of one shifted (startTime > stopTime) week day in item weekly_user_code_intervals |
Note, each array in item weekly_user_code_intervals
can contain different amount of "weekly_interval". Calculate weekly_interval cost by following pseudo code:
oneWeekDayCost ?
( ( startTime > stopTime and oneShiftedWeekDayCost ) ? oneShiftedWeekDayCost : oneWeekDayCost ) *
weekly_interval.days.length :
1
Items list filtering
request.params.deviceIds | Result | Behavior | Description |
---|---|---|---|
undefined | No filtering will be performed | Default | result will contain the whole items list |
[] | No filtering will be performed | Custom | result will contain the whole items list |
[ deviceId ], [ deviceId0, deviceId1, ... ] | filtered result | Custom | resulting items list will contain only specific devices' items. If deviceId specified doesn't match any items, items array in response will be empty. |
Examples
Get information about registered items on the hub.
request:
{
"method": "hub.items.list",
"id": "_ID_",
"params": {}
}
response:
{
"api": "1.0",
"error": null,
"id": "_ID_",
"result": {
"items": [
{
"_id": "5cef9bf17f00007937ab8015",
"deviceId": "5cef9bf17f00007937ab8013",
"deviceName": "_DEVICE_NAME_",
"deviceArmed": false,
"enum": [
"idle",
"heating",
"cooling",
"fan_only",
"vent_economizer",
"aux_heating",
"2nd_stage_heating",
"2nd_stage_cooling"
],
"hasGetter": true,
"hasSetter": false,
"name": "thermostat_operating_state",
"show": true,
"type": "token",
"value": "idle",
"valueFormatted": "idle",
"elementsMaxNumber": 2,
"userCodeRestriction": "\d{4}"
}
]
}
}
Get information about registered items on the hub, filtered by specific device Id.
request:
{
"method": "hub.items.list",
"id": "_ID_",
"params": {
"deviceIds": [
"5e4e6e3f7f00007ff33c7591",
"5e4e6e3f7f00007ff33cffff"
]
}
}
response:
{
"api": "1.0",
"error": null,
"id": "_ID_",
"result": {
"items": [
{
"_id": "5e4e6e3f7f00007ff33c7599",
"deviceId": "5e4e6e3f7f00007ff33c7591",
"hasGetter": true,
"hasSetter": false,
"name": "electric_meter_watt",
"show": true,
"value": 0,
"valueFormatted": "0",
"valueType": "float"
},
...
{
"_id": "5e4e6e3f7f00007ff33c7aaa",
"deviceId": "5e4e6e3f7f00007ff33cffff",
"hasGetter": true,
"hasSetter": false,
"name": "electric_meter_watt",
"show": true,
"value": 0,
"valueFormatted": "0",
"valueType": "float"
},
...
]
}
}
hub.item.value.set
Connection type: UI
Permissions: EZLO: WRITE/EDIT
Set item value.
One of parameters "_id" or "ids" should be specified.
request:
Field | Type | Required | Description |
---|---|---|---|
_id | string | - | Item object id |
ids | array of strings | - | List of items to send multicast request |
value | depends on item type | + | New item value. |
scale | depends on item type | - | New item value scale. |
response:
empty result
broadcasts:
Broadcast | Description |
---|---|
hub.item.updated | Informs about item changed |
Examples
request:
{
"method": "hub.item.value.set",
"id": "<request_id>",
"params": {
"_id" : "5cf0dc8c7f000068d223e88a",
"value" : true
}
}
request_multicast:
{
"method": "hub.item.value.set",
"id": "<request_id>",
"params": {
"ids" : ["5cf0dc8c7f000068d223e88a", "5cf0dc8c7f000068d223e88b"],
"value" : true
}
}
request with scale:
{
"method": "hub.item.value.set",
"id": "<request_id>",
"params": {
"_id" : "5cf0dc8c7f000068d223e88a",
"value" : 36.6,
"scale": "celsius"
}
}
response:
{
"api": "1.0",
"error": null,
"id": "_ID_",
"result": {}
}
If the scale field is present, the firmware will work with the obtained value in accordance with
the specified scale.
If the scale field is NOT present, the firmware will work with the obtained value in accordance with the scale from:
* a hub configuration;
* an item.
Errors:
Situation | Error code | Description | Error code |
---|---|---|---|
Item scale cannot be converted to target scale | -32602 | The specified scale cannot be used | rpc.params.scale.invalid |
hub.item.value.percent.apply
Connection type: UI
Permissions: EZLO: WRITE/EDIT
This command sets current value between minimum and maximum in position specified by current level plus
percent
.
Positive percent increases value level and negative decreases.
Simplified formula:newValue
=currentValue
+percentFromRange
Implementation: newValue
= round( currentValue
+ ( maxValue
- minValue
) * percent
/ 100 )
newValue
always will be in range: [minValue
, maxValue
].
if( newValue > maxValue )
newValue = maxValue;
else if( newValue < minValue )
newValue = minValue;
request:
Field | Type | Required | Description |
---|---|---|---|
_id | string | + | Item object id |
percent | int | + | Value must belong to range from -100 to 100 |
response:
Field | Type | Required | Description |
---|---|---|---|
newValue | float | + | New value of an item. |
scale | string | - | Scale for temperature items, one of (celsius, fahrenheit) |
valueType | string | - | temperature for temperature items |
broadcasts:
Broadcast | Description |
---|---|
hub.item.updated | Informs about item changed |
errors:
Code | Message | Data | Reason |
---|---|---|---|
-32600 | Bad request, id is empty | rpc.params.empty._id |
|
-32602 | Value has invalid type | rpc.params.type.invalid |
|
-32602 | Currently only items with type int are supported |
rpc.params.type.invalid |
|
-32602 | Value is not in valid range | rpc.params.range.invalid |
|
-32500 | rpc.unknown.error |
Unknown error | Item associated with this id (_id ) has no minimal and maximal value fields |
-32500 | rpc.unknown.error |
Unknown error | Item not found by id: _id |
-32500 | rpc.unknown.error |
Unknown error | Value 'value_name ' has invalid type. Type 'unsupported_type_name ' is not supported. Item id: _id |
-32500 | rpc.unknown.error |
Unknown error | Value 'value_name ' is not in valid range. Valid range is: [min , max ]. Item id: _id |
Examples
request:
{
"method": "hub.item.value.percent.apply",
"id": "<request_id>",
"params": {
"_id" : "5cf0dc8c7f000068d223e88a",
"percent" : 40
}
}
Let's assume we have dimmer with minimal value 0
and maximal 99
.
Current value is 30
The percent
is 40
and new value will be 70
.
response:
{
"error": null,
"id": "_ID_",
"result": {
"newValue" : 70
}
}
In case of we have a thermostat with minimal value 0
and maximal 40
.
Current value is 30
The percent
is 10
and new value will be 34
.
response:
{
"error": null,
"id": "_ID_",
"result": {
"newValue" : 34,
"scale": "celsius",
"valueType": "temperature"
}
}
hub.item.dictionary.value.add
Connection type: UI
Permissions: DEVICES: WRITE/EDIT
Add element to the dictionary (key will be generated on firmware side)
Only applicable for items with value type dictionary
'addItemDictionaryValue' script from plugin config will be called in lua
request:
Field | Type | Description |
---|---|---|
_id | string | Item object id |
element.type | string | Valid value type. MUST be equal to dictionary element type |
element.value | depends on element.type | Element value |
response:
empty result
broadcasts:
Broadcast | Description |
---|---|
hub.item.updated | Informs about item changed |
Examples
request:
{
"method": "hub.item.dictionary.value.add",
"id": "<request_id>",
"params": {
"_id" : "5cf0dc8c7f000068d223e88a",
"element": {
"type": "string",
"value": "some_string_value"
}
}
}
response:
{
"api": "1.0",
"error": null,
"id": "_ID_",
"result": {}
}
hub.item.dictionary.value.set
Connection type: UI
Permissions: DEVICES: WRITE/EDIT
Set new value for element in the dictionary
Only applicable for items with value type dictionary
'setItemDictionaryValue' script from plugin config will be called in lua
request:
Field | Type | Description |
---|---|---|
_id | string | Item object id |
key | string | Valid element key |
element.type | string | Valid value type. MUST be equal to dictionary element type |
element.value | depends on element.type | Element value |
response:
empty result
broadcasts:
Broadcast | Description |
---|---|
hub.item.updated | Informs about item changed |
Examples
request:
{
"method": "hub.item.dictionary.value.set",
"id": "<request_id>",
"params": {
"_id" : "5cf0dc8c7f000068d223e88a",
"key" : "some_key",
"element": {
"type": "string",
"value": "some_new_string_value"
}
}
}
response:
{
"api": "1.0",
"error": null,
"id": "_ID_",
"result": {}
}
hub.item.dictionary.value.remove
Connection type: UI
Permissions: DEVICES: WRITE/EDIT
Remove element from the dictionary
Only applicable for items with value type dictionary
'removeItemDictionaryValue' script from plugin config will be called in lua
request:
Field | Type | Description |
---|---|---|
_id | string | Item object id |
key | string | Valid element key |
response:
empty result
broadcasts:
Broadcast | Description |
---|---|
hub.item.updated | Informs about item changed |
Examples
request:
{
"method": "hub.item.dictionary.value.remove",
"id": "<request_id>",
"params": {
"_id" : "5cf0dc8c7f000068d223e88a",
"key" : "some_key"
}
}
response:
{
"api": "1.0",
"error": null,
"id": "_ID_",
"result": {}
}