User device (device)

Last updated on May 25, 2023

The structure describes specifications and functions of the model of a device, such as a lamp or a socket.

The structure is used:

• When the vendor sends information about the user's devices to the Sber Smart Home:

  • when the webhook responds to a request Request for all the user's devices and their functions (get devices);
  • when sending a request Add user's devices (post devices);
  • when sending a request Update user's devices (put devices).

• When the Sber Smart Home sends a response to the vendor's request Get the user’s device list (get devices).

Field	Type	Mandatory?	Description
id	string	✔︎	Device ID in the vendor's system
parent_id	string		ID of parent device (e.g. hub)
name	string	✔︎	Device name given by the user
default_name	string	✔︎	Device name from the manufacturer
nicknames	list<string>		Alternative device names
home	string		Name of the room group in which the device is located
room	string		Name of the room in which the device is located
groups	list<string>		Names of the groups the device belongs to. A group can only include devices of the same type
model_id	string	✔︎*	Device model ID (*only specified if model is not specified)
model	<object>	✔︎*	Device model description (*only specified if model_id is not specified). For the structure of the model description, see Device model (model)
hw_version	string		Equipment version
sw_version	string		Firmware version
partner_meta	<object>		Arbitrary information about the device. Contains an unlimited number of key–value pairs, where the key is always of type string, and the value can take any data type (including another object, nesting is not limited). The maximum allowed number of characters in the JSON representation of the partner_meta object is 1024. The vendor can send any necessary information to partner_meta, the Sber Smart Home will store it and return it in response to requests to get a list of devices

{
    "id": string,
    "parent_id": string,
    "name": string,
    "default_name": string,
    "nicknames": [
        string,
        string
        // ...
    ],
    "home": string,
    "room": string,
    "groups": [
        string,
        string
        // ...
    ],
    "model_id": string,
    "hw_version": string,
    "sw_version": string,
    "partner_meta": {
        "key": value,
        "key": value,
        // ...
    },
}

User's device description example

The example describes a smart lamp. There is no lamp model description as we believe that models are described independently and the model ID will be enough (in this case, QWERTY124).

{
    "id": "ABCD_003",
    "name": "My lamp",
    "default_name": "Smart lamp",
    "nicknames": [
        "LED lamp",
        "Smart lamp"
    ],
    "home": "My home",
    "room": "Living room",
    "groups": [
        "Overhead light",
        "Alcove"
    ],
    "model_id": "QWERTY123",
    "hw_version": "3.2",
    "sw_version": "5.7",
    "partner_meta": {
        "internal-id": 1234,
        "specificity": "microchip 2A"
    },
},