Устройство пользователя (device)

Обновлено 13 апреля 2025

Структура описывает характеристики и функции конкретного устройства, например лампы или розетки пользователя.

Структура используется:

• Когда вендор отправляет умному дому информацию об устройствах пользователя:

  • при ответе вебхука на запрос Запрос всех устройств пользователя и их функций (get devices);
  • при отправке запроса Добавление устройств пользователя (post devices);
  • при отправке запроса Обновление устройств пользователя (put devices).

• Когда умный дом отправляет вендору ответ на запрос Получение списка устройств пользователя (get devices).

Поле	Тип	Обязательное?	Описание
id	string	✔︎	Идентификатор устройства в системе вендора
parent_id	string		ID родительского устройства (например, хаба)
name	string	✔︎	Название, которое пользователь дал устройству
default_name	string	✔︎	Название устройства от производителя
nicknames	list<string>		Альтернативные названия устройства
home	string		Название группы помещений, в которой расположено устройство
room	string		Название помещения, в котором расположено устройство
groups	list<string>		Названия групп, в которые входит устройство. В группу могут входить только устройства одного типа
model_id	string	✔︎	ID модели устройства
model	<object>	✔︎	Описание модели устройства (указывается, только если не задан model_id). Структуру описания модели см. в разделе Модель устройства (model)
hw_version	string		Версия оборудования
sw_version	string		Версия прошивки
partner_meta	<object>		Произвольная информация об устройстве. Содержит неограниченное количество пар ключ–значение, где ключ всегда имеет тип string, а значение может принимать любой тип данных (в том числе другой объект, вложенность не ограничена). Максимально допустимое количество символов в JSON-представлении объекта partner_meta — 1024. Вендор может передать в partner_meta любую нужную информацию, умный дом будет хранить ее и возвращать в ответ на запросы получения списка устройств

{
    "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,
        // ...
    },
}

Пример описания устройства пользователя

В примере описана умная лампа. Для лампы не приведено описание модели — считаем, что модели устройств описаны отдельно, поэтому достаточно указать только ID модели (здесь — QWERTY123).

{
    "id": "ABCD_003",
    "name": "Моя лампа",
    "default_name": "Умная лампа",
    "nicknames": [
        "Светодиодная лампа",
        "Смарт-лампа"
    ],
    "home": "Мой дом",
    "room": "Гостиная",
    "groups": [
      "Верхний свет",
      "Ниша"
    ],
    "model_id": "QWERTY123",
    "hw_version": "3.2",
    "sw_version": "5.7",
    "partner_meta": {
        "internal-id": 1234,
        "specificity": "microchip 2A"
    },
}