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": {}
}