Common commands

hub.info.get

Version: 1.0

Classes: UI

Title: Hub info

Description: Return hub info (mode, firmware, hardware, ...)

parameters:

No parameters required.

return result fields:

Field Type Required Description
model string + Production name
architecture string + SOC architecture
firmware string + Firmware version
kernel string + Kernel version (for atom32 ESP-SDK version used)
hardware string + Hardware version
serial string + Serial number
location JsonObj + Location information
location.latitude float32 + Latitude value
location.longitude float32 + Longitude value
location.timezone string + Time zone name. Can be empty on internal error. Check logs on the hub for the error message (/var/log/firmware/ha-uid.log for H2)
location.state string + Can contain one of possible values: default, customAll, customTimezone, customCoordinates
build JsonObj + Build info
build.time string + Time and date when the build was made (ISO 8601: YYYY-MM-DDThh:mm:ss±hhmm)
build.builder string + Where the firmware was builded (user@host)
build.branch string + Branch name
build.commit string + Commit hash
battery object - If controller have no battery support whole section is not returned
battery.status enum - initializing, missing, charging, full, discharging
battery.stateOfCharge int - Percent of available battery capacity
battery.remainingTime int - Remaining time in minutes to empty if discharging, or to full if charging
battery.health int - Percent of current full capacity relative to original full capacity
uptime string + Hub uptime
localtime string + Current time on hub (ISO 8601: YYYY-MM-DDThh:mm:ss±hhmm)

Atom32: Kernel version get by call git describe --first-parent --always on ESP-SDK Firmware version .. major + minor parts is manually set

Firmware file name format --.bin esp32-rev1-0.9.2.bin

Here is it an example of usage:

call:

{
    "method": "hub.info.get",
    "id": "_ID_",
    "params": {}
}

reply:

{
    "error": null,
    "id": "_ID_",
    "result": {
        "model": "ATOM32",
        "architecture": "esp32",
        "firmware": "0.9.2",
        "kernel": "v3.3-dev-239-g18118a6d5",
        "hardware": "rev1",
        "serial": "7000183",
        "location": {
            "latitude": 46.4828401,
            "longitude": 30.7595042,
            "timezone": "Europe/Kiev",
            "state": "custom"
        },
        "build": {
            "time": "2004-05-23T14:25:10+0200",
            "builder": "jenkins@builder1",
            "branch": "qa",
            "commit": "cc2b9921c8572147d762674eacb9b02974ece302"
        },
        "battery": {
            "stateOfCharge": 87,
            "remainingTime": 236,
            "status": "discharging",
            "health": 91
        },
        "uptime": "5d 22h 18m 11s",
        "localtime": "2004-05-23T14:25:10+0200"
    }
}

hub.reboot

Starts hub to reboot

call:

{
    "api" : "1.0"
    "id": "_ID_",
    "method": "hub.reboot",
    "params": {}
}

reply: Reply by json-RPC protocol means that command successfully received by hub

{
    "error": null,
    "id": "_ID_",
    "result": {}
}

hub.data.list

Version: 1.0

Classes: UI

Title: Hub data list

The command allows to request data from multiple collections from a hub in one request, allows data filtering by id and field names.

Request

Default request:

{
    "api": "1.0",
    "method": "hub.data.list",
    "id": "<REQUEST_ID>",
    "params": {
        "devices":null,
        "items":null,
        "rooms": null,
        "scenes":null
    }
}

Default request, with all fields filled:

{
    "api": "1.0",
    "method": "hub.data.list",
    "id": "<REQUEST_ID>",
    "params": {
        "devices":{ 
            "ids":[], "fields": { "include":[] }
         },
        "items":{ 
            "ids":[], "fields": { "include":[] }
         },
        "rooms":{ 
            "ids":[], "fields": { "include":[] }
         },
        "scenes":{ 
            "ids":[], "fields": { "include":[] }
         }
    }
}

Parameters:

devices, items, rooms, scenes

All of them are optional, but at least on is required.

Name Required Description
devices - If this field is present: a response with the devices will be sent anyway. If it has null value than all devices will be sent.
devices.ids - Array of IDs of requested devices. Only requested devices will be in the answer. If the controller doesn't have requested device then null will be send instead of device data.
devices.fields - Description of fields filtering. If this field is missed than all fields will be present in answer.
devices.fields.include - Name of fields which should be in answer. Possible values: parentDeviceId, category, subcategory, deviceTypeId, gatewayId, name, type, batteryPowered, reachable, armed, roomId, persistent, info, serviceNotification, security, ready, status
items - If this field is present: a response with the items will be sent anyway. If it has null value than all items will be sent.
items.ids - Array of IDs of requested items. Only requested items will be in the answer. If the controller doesn't have requested item then null will be send instead of item data.
items.fields - Description of fields filtering. If this field is missed than all fields will be present in answer.
items.fields.include - Name of fields which should be in answer. Possible values: deviceId, enum, hasGetter, hasSetter, name, show, scale, valueType, valueFormatted, value, minValue, maxValue, elementsMaxNumber, userCodeRestriction, elementsMaxNumberPerArray, oneWeekDayCost, oneShiftedWeekDayCost
rooms - If this field is present: a response with the rooms will be sent anyway. If it has null value than all rooms will be sent.
rooms.ids - Array of IDs of requested rooms. Only requested rooms will be in the answer. If the controller doesn't have requested room then null will be send instead of room data.
rooms.fields - Description of fields filtering. If this field is missed than all fields will be present in answer.
rooms.fields.include - Name of fields which should be in answer. Possible values: enabled, group_id, is_group, name, parent_id, then, when
scenes - If this field is present: a response with the scenes will be sent anyway. If it has null value than all scenes will be sent.
scenes.ids - Array of IDs of requested scenes. Only requested scenes will be in the answer. If the controller doesn't have requested room then null will be send instead of room data.
scenes.fields - Description of fields filtering. If this field is missed than all fields will be present in answer.
scenes.fields.include - Name of fields which should be in answer. Possible values: enabled, group_id, is_group, name, parent_id, then, when

Errors:

Type of error Error code Reason Data Field
Invalid parameters -32602 Empty params rpc.params.invalid
Wrong format of request fields -32602 Wrong params rpc.params.invalid.[NAME]

Answers: Request will send a few answers with same request and sender info in each answer. Each type of controller sends in a separate answer.

{
    "api": "1.0",
    "error": null,
    "method": "hub.data.list",
    "id": "<REQUEST_ID>",
    "result": {
        "devices": {
            "5e6b361746abd40dfb1494c1":{
                "name": "Smart Plug",
                "reachable": true,
                "armed": false,
                "serviceNotification": false,
                "roomId": "",
                "status": "idle"
            }
        }
    }
}
{
    "api": "1.0",
    "error": null,
    "method": "hub.data.list",
    "id": "<REQUEST_ID>",
    "result": {
        "items": {
            "5e6b361746abd40dfb1494c2":{
                "value": "idle"
            },
            "5e6b361746abd40dfb1494c3":null
        }
    }
}
{
    "api": "1.0",
    "error": null,
    "method": "hub.data.list",
    "id": "<REQUEST_ID>",
    "result": {
        "rooms": {
            "8e6b361746abd40dfb1494c4":{
                "name": "Living Room"
            },
            "8e6b361746abd40dfb149417":{
                "name": "Hall"
            }
        }
    }
}
{
    "api": "1.0",
    "error": null,
    "method": "hub.data.list",
    "id": "<REQUEST_ID>",
    "result": {
        "scenes": {
            "5c7ff48b7f00002a07a408e3":{
                "name": "Scene1"
            },
            "5c6ec961cc01eb07f86f9dd9":{
                "name": "Test Scene"
            }
        }
    }
}

The order of requests to be sent is always the same: devices, items, rooms, scenes.