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
Firmware file name format
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.