Разработчикам и руководство по API

1. Начало использования

1.1 Подготовка

Шаг 1. Пожалуйста, убедитесь, что шлюз включен и работает правильно.

Шаг 2. Убедитесь, что шлюз и ПК подключены к одной локальной сети. Затем введите URL CUBE в вашем браузере.

Примечание: Если у вас несколько шлюзов, вы можете получить соответствующий IP-адрес для доступа к указанному шлюзу одним из двух способов ниже.

1. Войдите в настройки вашего беспроводного роутера и проверьте IP-адрес шлюза в DHCP.

2. CUBE поддерживает локальное обнаружение через mDNS.

1.2 Начало работы

• Вызовите интерфейс [Access Token] и получите ответ с ошибкой, предлагающий нажать <Готово>. Обратите внимание, что после нажатия доступ к интерфейсу действителен не более 5 минут.

// Запрос
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// Ответ
{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

• Нажмите <Готово> и вызовите интерфейс [Access Token] снова. Ответ успешный, и токен получен.

// Запрос
curl --location --request GET 'http://<ip address>/open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json'

// Ответ
{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

• Проверьте токен. Вызовите интерфейс [Get Device List]. Ответ успешный, и список устройств получен.

// Запрос
curl --location --request GET 'http://<ip address>/open-api/V2/rest/devices' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d'

// Ответ
{
  "error": 0,
  "data": {
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "device name",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  }
  "message": "success"
}

• Метод получения токена доступа CUBE: после вызова интерфейса [Access Token] на странице веб-консоли CUBE появляется глобальное всплывающее окно с просьбой пользователя подтвердить получение учетных данных для вызова интерфейса.

• Примечание: Если вы откроете более одной страницы веб-консоли CUBE, окно подтверждения появится одновременно на нескольких страницах веб-консоли, и окна на других страницах закроются после нажатия подтверждения на одной из страниц.

2. Основная концепция

2.1 Адрес интерфейса разработки

Веб-API интерфейс шлюза имеет два способа доступа (по IP или по доменному имени), обычно корневой путь /open-api/V2/rest/< specific function module >

// Доступ по IP http:///open-api/V2/rest/bridge

// Доступ по доменному имени http:///open-api/V2/rest/bridge

2.2 Категория отображения устройства и параметры (Capabilities)

• **Категория отображения устройства (DisplayCategory). **Категория отображения устройства используется для идентификации конкретных категорий устройства, таких как switch, plug, light и т.д. Эта информация определяет отображение устройства в пользовательском интерфейсе шлюза.

• **Возможности устройства (Device Capability). **Возможности устройства описывают конкретные подфункции устройства. Например, управление питанием, управление яркостью, управление цветовой температурой и т.д. Одно устройство может поддерживать 1 или более возможностей.

  • capability: Описывает имя возможности, которое должно быть глобально уникальным и строкового типа. Несколько английских слов следует разделять дефисом ("-"). Например: "thermostat-target-setpoint".

  • name: Описывает категорию внутри возможности, также строкового типа. Несколько английских слов следует разделять дефисом ("-"). Например: "auto-mode", "manual-mode".

  • permission: Описывает права, связанные с возможностью. Тип — строка, форматируется в виде кода 8421 в двоичном представлении. Примеры включают:

    • Управляемое устройство: "1000"

    • Конфигурируемое устройство: "0010"

    • Устройство, управляемое и конфигурируемое: "1010"

    • Устройство, управляемое и отчитывающееся: "1100"

Значение каждого бита, слева направо (с правого на левый), следующее: ⅰ. Бит 0: Разрешает опрос устройства ⅱ. Бит 1: Разрешает настройку устройства ⅲ. Бит 2: Разрешает устройству отправлять отчетные данные ⅳ. Бит 3: Разрешает управление устройством

const permission = {
  "update": "1000",
  "updated": "0100",
  "configure": "0010",
  "query": "0001",  
  "update-updated": "1100",
  "update-query": "1001",
  "update-updated-configure": "1110",
  "updated-configure":"0110",
  "update-updated-query":"1101"
}

settings: Описывает элементы конфигурации для возможности, которые имеют тип object и включают описание каждого элемента конфигурации. ⅰ. key: Описывает имя элемента конфигурации, которое является строкой. Несколько английских слов следует представлять в camelCase. Например: "temperatureUnit". ⅱ. value: Описывает содержимое элемента конфигурации. Конкретные спецификации детализированы в таблице ниже.

Атрибут	Тип	Необязательно	Описание
permission	string	N	Описывает права для элемента конфигурации.
Возможные значения:

• Разрешить изменение этого элемента конфигурации: "10"

• Разрешить просмотр этого элемента конфигурации: "01"

• Разрешить и изменение, и просмотр этого элемента конфигурации: "11"

Объяснение битов:

1. Бит 0: Разрешает просмотр этого элемента конфигурации

2. Бит 1: Разрешает изменение этого элемента конфигурации | | type | string | N | Описывает тип данных значения элемента конфигурации. Возможные значения:

• "enum"

• "numeric"

• "object"

• "boolean"

• "string"

Рекомендации, специфичные для типа:

1. Когда **type = enum**:

   • Поле value обязательное, если permission разрешает изменение ("10" или "11").

   • Поле default (описывающее значение по умолчанию элемента конфигурации) и values (описывающее доступные для выбора значения для элемента конфигурации) поля необязательны.

2. Когда **type = numeric**:

   • Поле value поле обязательно, если permission разрешает изменение ("10" или "11").

   • Следующие поля необязательны:

     • min (описывающее минимальное значение элемента конфигурации)

     • max (описывающее максимальное значение элемента конфигураии)

     • step (описывающее шаг значения для элемента конфигурации)

     • precision (описывающее точность)

     • unit (описывающее единицу измерения элемента конфигурации)

     • default (описывающее значение по умолчанию)

3. Когда **type = object**:

   • Поле value поле обязательно, если permission разрешает изменение ("10" или "11").

   • Поле default поле необязательно.

4. Когда **type = boolean**:

   • Поле value поле обязательно, если permission разрешает изменение ("10" или "11").

   • Поле default поле необязательно.

5. Когда **type = string**:

   • Поле value поле обязательно, если permission разрешает изменение ("10" или "11").

   • Поле default поле необязательно. |

// type = enum
{
  "settings":{
    "temperatureUnit": {
      "type": "enum",
      "permission": "11", 
      "values": ["c", "f"], 
      "default": "c",
      "value": "f"
    }
  }
}
// type = numeric
{
  "settings": {
    "setpointRange": {
      "type": "numeric", 
      "permission": "01", 
      "min": 4, 
      "max": 35,
      "default": 20,
      "step": 0.5,
      "precision": 0.01
      "unit": "c"
    }
  }
}

// type = object
{
  "settings":{
    "weeklySchedule":{
      "type": "object",
      "permission": "11", 
      "value": {
        "maxEntryPerDay": 2, 
        "Monday": [
          {
            "startTimeInMinutes": 440, 
            "upperSetpoint": 36.5 
          },
          {
            "startTimeInMinutes": 900,
            "upperSetpoint": 26.5 
          }
        ]，
        "Tuesday": [...],
        "Wednesday": [...],
        "Thursday": [...],
        "Friday": [...],
        "Saturday": [...],
        "Sunday": [...],
      }
    }
  }
}

3. Веб-API

Тип данных

Тип	Описание
string	Строковый тип данных. Кодировка UTF-8.
number	Числовой тип данных. двойная точность, 64-битный двоичный формат IEEE 754
int	Целочисленный тип данных.
object	Тип объекта. Объект, совместимый с JSON
string[]	Массив строк
int[]	Массив целых чисел
object[]	Массив объектов
bool	Логический тип
date	Строка времени. Строка в формате ISO (ISO 8601 расширенный формат): YYYY-MM-DDTHH:mm:ss.sssZ. Часовой пояс всегда UTC (координированное всемирное время), обозначается суффиксом "Z".

Общие результаты ответа

Атрибут	Тип	Необязательно	Описание
error	int	N	Код ошибки:
0: Успех
400: Ошибка параметра
401: Аутентификация не удалась
500: Исключение сервера
data	object	N	Тело данных ответа
message	string	N	Описание ответа:
Когда error равно 0, содержимое — success
Когда error не равно 0, это непустая строка, содержащая описание ошибки.

Пример ответа:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

{
  "error": 400,
  "data": {},
  "message": "invalid parameters"
}

Список ресурсов

Тип	Описание
Поддерживаемые звуки	- alert1 (Звук сигнала тревоги 1)

• alert2 (Звук сигнала тревоги 2)

• alert3 (Звук сигнала тревоги 3)

• alert4 (Звук сигнала тревоги 4)

• alert5 (Звук сигнала тревоги 5)

• doorbell1 (Звонок 1)

• doorbell2 (Звонок 2)

• doorbell3 (Звонок 3)

• doorbell4 (Звонок 4)

• doorbell5 (Звонок 5)

• alarm1 (Сигнал тревоги 1)

• alarm2 (Сигнал тревоги 2)

• alarm3 (Сигнал тревоги 3)

• alarm4 (Сигнал тревоги 4)

• alarm5 (Сигнал тревоги 5) | | Поддерживаемые deep | - bootComplete (Загрузка системы завершена)

• networkConnected (Сеть подключена)

• networkDisconnected (Сеть отключена)

• systemShutdown (Выключение системы) -deviceDiscovered (Обнаружено устройство)

• system Armed (Система поставлена на охрану)

• system Disarmed (Система снята с охраны)

• factoryReset (Сброс устройства до заводских настроек) |

3.1 Функции шлюза

a. Токен доступа

Позволяет пользователям получить токен доступа.

• Примечание: Токен будет очищен после сброса устройства.

• Примечание: После получения токена необходимо снова нажать кнопку, чтобы успешно получить новый токен.

:::советы

• URL：/open-api/V2/rest/bridge/access_token

• Метод：GET

• Заголовок：

  • Content-Type: application/json ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
app_name	string	Y	Описание названия приложения.

Успешный ответ с данными:

Атрибут	Тип	Необязательно	Описание
token	string	N	Токен доступа интерфейса. Он действителен длительное время, пожалуйста, сохраните его
app_name	string	Y	Описание названия приложения.

:::советы Условие: Пользователь активировал < command key > и обратился к этому интерфейсу в пределах допустимого времени. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {
    "token": "376310da-7adf-4521-b18c-5e0752cfff8d"
  },
  "message": "success"
}

Данные ответа при отказе：пустой объект :::советы Условия：Пользователь не активировал < command key >, или время действия истекло. **Код состояния: ** 200 OK ::: Пример ответа:

{
  "error": 401,
  "data": {},
  "message": "link button not pressed" 
}

b. Получение состояния шлюза

Позволяет авторизованным пользователям получить состояние шлюза через этот интерфейс :::советы

• URL：/open-api/V2/rest/bridge/runtime

• Метод：GET

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными:

Атрибут	Тип	Необязательно	Описание
ram_used	int	N	Процент использования оперативной памяти. [0-100]
cpu_used	int	N	Процент использования ЦП. [0-100]
power_up_time	date	N	Время последнего включения питания
cpu_temp	int	N	Температура ЦП:
Единица: Цельсий
cpu_temp_unit	string	N	Единица температуры ЦП:
Необязательно
значения:'c', 'f'
sd_card_used	int	Y	Использование SD-карты (в процентах):
Диапазон:[0-100] с точностью до одного знака после запятой
*Примечание: Если SD-карта не вставлена или не отформатирована, значение пусто.

:::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {
    "ram_used": 40,
    "cpu_used": 30,
    "power_up_time": "2022-10-12T02:58:09.989Z",
    "cpu_temp": 51,
    "cpu_temp_unit": "c",
    "sd_card_used" : "12"
  },
  "message": "success"
}

c. Настройка шлюза

Позволяет авторизованным пользователям настраивать шлюз через этот интерфейс :::советы

• URL：/open-api/V2/rest/bridge/config

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
volume	int	Y	Громкость системы. [0-100]

Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

d. Получение информации о шлюзе

Позволяет авторизованным пользователям получить информацию о шлюзе через этот интерфейс :::советы

• URL：/open-api/V2/rest/bridge

• Метод：GET

• Заголовок：

  • Content-Type: application/json ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
ip	string	N	IP-адрес
mac	string	N	MAC-адрес
domain	string	Y	Домен сервиса шлюза
fw_version	string	N	Версия прошивки
name	string	N	Название устройства

Успешный ответ с данными: пустой объект {} :::советы Условия: Нет **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {
    "ip": "192.168.31.25",
    "mac": "00:0A:02:0B:03:0C",
    "domain": "ihost.local",
    "fw_version": "1.9.0",
    "name": "iHost"
  },
  "message": "success"
}

e. Отключение звука у шлюза (Mute)

Позволяет авторизованным пользователям отключать звук на шлюзе через этот интерфейс. :::советы

• URL：/open-api/v2/rest/bridge/mute

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Включение звука у шлюза (Unmute)

Позволяет авторизованным пользователям включать звук на шлюзе через этот интерфейс. :::советы

• URL：/open-api/v2/rest/bridge/unmute

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

g. Отключение будильника шлюза

Позволяет авторизованным пользователям отключать состояние звуковой тревоги на шлюзе через этот интерфейс. :::советы

• URL：/open-api/v2/rest/bridge/cancel_alarm

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.2 Функции аппаратного обеспечения

a. Перезагрузка шлюза

Позволяет авторизованному пользователю перезагрузить шлюз через этот интерфейс :::советы

• URL：/open-api/V2/rest/hardware/reboot

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK :::

{
  "error": 0,
  "data": {},
  "message": "success"
}

b. Управление динамиком

Позволяет авторизованным пользователям управлять динамиком через этот интерфейс :::советы

• URL：/open-api/V2/rest/hardware/speaker

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
type	string	N	Необязательные параметры: 1.play_sound (воспроизвести звук) 2.play_beep (воспроизвести сигнал)
sound	SoundObject	Y (N, если type = play_sound.)	Звук.
beep	BeepObject	Y (N, если type = play_beep.)	Сигнал

SoundObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя звука. Поддерживаемые значения можно посмотреть в [Resource List - Supported sound]
volume	int	N	Громкость звука. [0-100]
countdown	int	N	Продолжительность воспроизведения звука динамиком; воспроизведение автоматически остановится по истечении времени. Единица: секунда. [0,1799]

BeepObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя deep. Поддерживаемые значения можно посмотреть в [Resource List - Supported deep]
volume	int	N	Громкость deep. [0-100]

Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: ** 200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.3 Функции управления устройствами

a. Поддерживаемые типы устройств

Тип устройства	Значение	Версия iHost
Розетка	plug	≥ 2.1.0
Выключатель	switch	≥ 2.1.0
Свет	light	≥ 2.1.0
Штора	curtain	≥ 2.1.0
Датчик двери/окна	contactSensor	≥ 2.1.0
Датчик движения	motionSensor	≥ 2.1.0
Датчик температуры	temperatureSensor	≥ 2.1.0
Датчик влажности	humiditySensor	≥ 2.1.0
Датчик температуры и влажности	temperatureAndHumiditySensor	≥ 2.1.0
Детектор протечки воды	waterLeakDetector	≥ 2.1.0
Детектор дыма	smokeDetector	≥ 2.1.0
Беспроводная кнопка	button	≥ 2.1.0
Камера	camera	≥ 2.1.0
Общий датчик	sensor	≥ 2.1.0
Общий датчик	sensor	≥ 2.1.0
Потолочный вентилятор со светом	fanLight	≥ 2.1.0
Кондиционер	airConditioner	≥ 2.1.0
Вентилятор	fan	≥ 2.1.0
Термостат	thermostat	≥ 2.1.0

b. Поддерживаемые возможности устройства

Выключатель питания (power):

Пример объявления возможности:

[
  {
    "capability": "power", // Название возможности
    "permission": "1100",  // ihost не поддерживает настройку мягкого запуска/остановки, поэтому поле configure отсутствует
  }
]

Атрибут состояния:

{
  "powerState": "on", // Поле powerState указывает состояние включения/выключения питания. Обязательно. **Тип:** string. "on" означает включено, "off" означает выключено, "toggle" означает переключение.
}

Протокол (запрос статуса и управляющие инструкции):

Включить:

{
  "power": {
    "powerState": "on"
  }
}

Выключить:

{
  "power": {
    "powerState": "off"
  }
}

Переключатель канала (toggle):

Пример объявления возможности:

Пример для одного компонента:

[
  {
    "capability": "toggle", // Название возможности
    "permission": "1100",  // Разрешение
    "name": "1", // Название компонента, **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4), или другие значения, содержащие заглавные и строчные буквы и цифры
  }
]

Пример для нескольких компонентов:

[
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "1"
  },
  {
    "capability": "toggle",
    "permission": "1100",
    "name": "2"
  }
]

Атрибут состояния:

{
  "toggleState": "on", // Поле toggleState указывает состояние переключателя {device_id} для атрибута {name}. Обязательно. **Тип:** String. "on" означает включено, "off" означает выключено, "toggle" означает переключить.
}

Протокол (запрос статуса и управляющие инструкции):

Формат переключения:

{
  [capability]: {
    [toggle-name]: {
      [toggleState]: [value]
    }
  }
}
Компонент 1 Включен, Компонент 2 Выключен:
{
  "toggle": {
    "1": {
      "toggleState": "on"
    },
    "2": {
      "toggleState": "off"
    }
  }
}

Импульсное включение канала (toggle-inching):

Пример объявления возможности:

[
  {
    "capability": "toggle-inching", // Название возможности
    "permission": "0010",  // Разрешение
    "settings": {
      "toggleInchingSetting": {
        "permission": "11",
        "type": "object",
        "value": {
          "supported": {
            "1": { // Название компонента
              "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено)
              "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            },
            "2": { // Название компонента
              "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено)
              "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            },
            "3": { // Название компонента
              "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено)
              "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            },
            "4": { // Название компонента
              "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено)
              "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            }
          }
        }
      }
    }
  }
]

Атрибут состояния

Нет

Протокол (запрос статуса и управляющие инструкции)

Нет

Регулировка яркости (brightness):

Пример объявления возможности:

{
  "capability": "brightness", // Название возможности
  "permission": "1100"  // Разрешение
}

Атрибут состояния:

{
  "brightness": 100, // Поле brightness указывает процент яркости. Выберите brightness или brightnessDelta. **Тип:** Number. Диапазон: 0-100.
}

Протокол (запрос статуса и управляющие инструкции):

Установить яркость на 80%. (0 — темнее, 100 — светлее.)

json
Копировать код
{
  "brightness": {
    "brightness": 80
  }
}

Регулировка цветовой температуры (color-temperature):

Пример объявления возможности:

{
  "capability": "color-temperature", // Название возможности
  "permission": "1100"  // Разрешение
}

Атрибут состояния:

{
  "colorTemperature": 100, // Поле colorTemperature указывает процент цветовой температуры. Выберите colorTemperature или colorTemperatureDelta. **Тип:** Number. Диапазон: 0-100. 0 означает теплый свет, 50 — нейтральный, 100 — холодный.
}

Протокол (запрос статуса и управляющие инструкции):

Отрегулировать цветовую температуру до 50%:

json
 
{
  "color-temperature": {
    "colorTemperature": 50
  }
}

Регулировка цвета (color-rgb):

Пример объявления возможности:

{
  "capability": "color-rgb", // Название возможности
  "permission": "1100"  // Разрешение
}

Атрибут состояния:

{
  "red": 255, // Поле red представляет красный компонент в RGB. Обязательно. **Тип:** Number. Диапазон: 0-255.
  "green": 0, // Поле green представляет зеленый компонент в RGB. Обязательно. **Тип:** Number. Диапазон: 0-255.
  "blue": 255 // Поле blue представляет синий компонент в RGB. Обязательно. **Тип:** Number. Диапазон: 0-255.
}

Протокол (запрос статуса и управляющие инструкции):

Установить цвет на фиолетовый:

{
  "color-rgb": {
    "red": 255,
    "green": 0,
    "blue": 255
  }
}

Регулировка в процентах (percentage):

Пример объявления возможности:

{
  "capability": "percentage",
  "permission": "1100",
  "settings": { // Необязательно
    "percentageRange": {
      "permission": "01",
      "type": "numeric",
      "min": 0,
      "max": 100,
      "step": 5
    }
  }
}

Атрибут состояния:

{
  "percentage": 100, // Поле percentage указывает процентное значение. Выберите percentage или percentageDelta. **Тип:** Number. Диапазон: 0-100.
}

Протокол (запрос статуса и управляющие инструкции):

Отрегулировать до 40%:

{
  "percentage": {
    "percentage": 40
  }
}

Управление мотором (motor-control):

Пример объявления возможности:

{
  "capability": "motor-control",
  "permission": "1100"
}

Атрибут состояния:

json
 
{
  "motorControl": "stop", // Поле motorControl указывает состояние мотора. Обязательно. **Тип:** String. Возможные значения: "open" (открыть), "close" (закрыть), "stop" (остановить), "lock" (заблокировать).
}

Протокол (запрос статуса и управляющие инструкции):

Открыть мотор:

{
  "motor-control": {
    "motorControl": "open"
  }
}

Реверс мотора (motor-reverse):

Пример объявления возможности:

{
  "capability": "motor-reverse",
  "permission": "1100"
}

Атрибут состояния:

{
  "motorReverse": true, // Поле motorReverse указывает направление мотора. Обязательно. **Тип:** Boolean. true означает вперед, false означает назад.
}

Протокол (запрос статуса и управляющие инструкции):

Установить мотор на движение вперед:

{
  "motor-reverse": {
    "motorReverse": true
  }
}

Калибровка мотора (motor-clb)

Пример объявления возможности:

{
  "capability": "motor-clb",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "motorClb": "calibration" // Поле motorClb указывает статус калибровки мотора. Обязательно. **Тип:** String. "normal" означает нормальный режим (откалиброван), "calibration" означает выполняющуюся калибровку.
}

Протокол (отчет о состоянии):

Отчет: мотор проходит калибровку:

{
  "motor-clb": {
    "motorClb": "calibration"
  }
}

Состояние при включении питания (startup)

Пример объявления возможности:

{
  "capability": "startup",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "startup": "on" // Состояние питания при старте. **Тип:** String. Обязательно. Допустимые значения: "on" (включено), "stay" (сохранить состояние), "off" (выключено), "toggle" (инвертировать состояние).
}

Протокол (запрос статуса и управляющие инструкции):

Установить состояние питания: всегда включено:

{
  "startup": {
    "startup": "on"
  }
}

---

Активация при пробуждении (identify)

Пример объявления возможности:

{
  "capability": "identify",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "identify": true // Указывает, активно ли устройство сообщает результаты распознавания или активировано.
}

Протокол (отчет о состоянии и управляющие инструкции):

Установить время активации при пробуждении:

{
  "identify": {
    "countdown": 180 // Поле countdown указывает время обратного отсчета. Обязательно. **Тип:** Number. Единица: секунды.
  }
}

Отчет о статусе активации:

{
  "identify": {
    "identify": true // Указывает, активно ли устройство сообщает результаты распознавания или активировано.
  }
}

Переключатель статистики реального потребления энергии (power-consumption)

Пример объявления возможности:

{
  "capability": "power-consumption",
  "permission": "1101",
  "settings": {
    "resolution": {
      "permission": "01",
      "type": "numeric",
      "value": 3600
    },
    "timeZoneOffset": {
      "permission": "01",
      "type": "numeric",
      "min": -12,
      "max": 14,
      "value": 0
    }
  }
}

Атрибуты (Состояние):

Запустить/Остановить статистику в реальном времени:

{
  "rlSummarize": true, // Запуск/остановка статистики в реальном времени. **Тип:** Boolean. Обязательно.
  "timeRange": { // Диапазон времени для суммирования. Обязательно.
    "start": "2020-07-05T08:00:00Z", // Время начала статистики потребления энергии. **Тип:** String. Обязательно.
    "end": "2020-07-05T09:00:00Z" // Время окончания статистики потребления энергии. **Тип:** String. Обязательно.
  }
}

Запросить потребление энергии за диапазон времени:

{
  "type": "summarize", // Тип статистики. **Тип:** String. Обязательно. Допустимые значения: "rlSummarize" (реальное время), "summarize" (текущий итог).
  "timeRange": { // Диапазон времени для суммирования. Обязательно, если type = "summarize".
    "start": "2020-07-05T08:00:00Z", // Время начала статистики потребления энергии. **Тип:** String. Обязательно.
    "end": "2020-07-05T09:00:00Z" // Время окончания статистики потребления энергии. **Тип:** String. Необязательно. Если пропущено, означает текущее время.
  }
}

Ответ со статистикой за диапазон времени:

json
 
{
  "type": "summarize", // Тип статистики. **Тип:** String. Обязательно. Допустимые значения: "rlSummarize" (реальное время), "summarize" (текущий итог).
  "rlSummarize": 50.0, // Общее потребление энергии. **Тип:** Number. Единица: 0.01 kWh. Необязательно.
  "electricityIntervals": [ // Несколько записей статистики, разделенные в соответствии с configuration.resolution. Необязательно. Отсутствует, когда type = "rlSummarize".
    {
      "usage": 26.5, // Потребление энергии. **Тип:** Number. Единица: 0.01 kWh. Обязательно.
      "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** Date. Обязательно.
      "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** Date. Обязательно. Если интервал между end и start меньше resolution, все записанные записи считаются недействительными.
    },
    {
      "usage": 26.5, // Потребление энергии. **Тип:** Number. Единица: 0.01 kWh. Обязательно.
      "start": "2020-07-05T09:00:00Z", // Время начала. **Тип:** Date. Обязательно.
      "end": "2020-07-05T10:00:00Z" // Время окончания. **Тип:** Date. Обязательно. Если интервал между end и start меньше resolution, все записанные записи считаются недействительными.
    }
  ]
}

Протокол (отчет о состоянии и управляющие инструкции):

Запустить статистику в реальном времени:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}

Остановить статистику в реальном времени:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Получить историческое потребление энергии:

json
 
{
  "power-consumption": {
    "type": "summarize",
    "timeRange": {
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z"
    }
  }
}

Получить потребление энергии в реальном времени:

json
 
{
  "power-consumption": {
    "powerConsumption": {
      "type": "rlSummarize"
    }
  }
}

Обнаружение режима температуры и влажности (thermostat-mode-detect)

Пример объявления возможности:

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "temperature", // Тип обнаружения климат-контроля. **Тип:** String. Обязательно. Допустимые значения: "humidity" (влажность), "temperature" (температура).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Поддерживаемые настройки обнаружения. Обязательно.
          {
            "name": "lowerSetpoint", // Значение обнаружения должно быть выше этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint.
            "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия.
              "value": 68.0, // Значение температуры. **Тип:** Number. Обязательно.
              "scale": "f" // Единица температуры. Обязательно, когда name=temperature. Допустимые значения: "c" (Цельсий), "f" (Фаренгейт).
            }
          },
          {
            "name": "upperSetpoint", // Значение обнаружения должно быть ниже этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint.
            "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия.
              "value": 68.0, // Значение температуры. **Тип:** Number. Обязательно.
              "scale": "f" // Единица температуры. Обязательно, когда name=temperature. Допустимые значения: "c" (Цельсий), "f" (Фаренгейт).
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

{
  "capability": "thermostat-mode-detect",
  "permission": "0110",
  "name": "humidity", // Тип обнаружения климат-контроля. **Тип:** String. Обязательно. Допустимые значения: "humidity" (влажность), "temperature" (температура).
  "settings": {
    "setpointRange": {
      "permission": "11",
      "type": "object",
      "value": {
        "supported": [ // Поддерживаемые настройки обнаружения. Обязательно.
          {
            "name": "lowerSetpoint", // Значение обнаружения должно быть выше этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint.
            "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия.
              "value": 68.0, // Значение влажности. **Тип:** Number. Обязательно
            }
          },
          {
            "name": "upperSetpoint", // Значение обнаружения должно быть ниже этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint.
            "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия.
              "value": 68.0, // Значение влажности. **Тип:** Number. Обязательно
            }
          }
        ]
      }
    },
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "COMFORT",
        "COLD",
        "HOT"
      ]
    }
  }
}

Атрибуты (Состояние):

{
  "mode": "COMFORT" // Идентификатор режима. Необязательно. Поддерживаемые значения: "COMFORT" (Комфорт), "COLD" (Холод), "HOT" (Жарко), "DRY" (Сухо), "WET" (Влажно).
}

Протокол (запрос статуса и управляющие инструкции):

Формат:

{
    [capability] :{
        [имя режима] :{
            "mode": [value]
        }
    }
}

Пример:

{
  "thermostat-mode-detect": {
    "humidity": {
      "mode": "COMFORT"
    }
  }
}

Режим термостата (thermostat-mode)

Пример объявления возможности:

{
  "capability": "thermostat",
  "permission": "1100",
  "name": "thermostat-mode",
  "settings": {
    "supportedModes": {
      "type": "enum",
      "permission": "01",
      "values": [
        "MANUAL",
        "AUTO",
        "ECO"
      ]
    }
  }
}

Атрибуты (Состояние):

{
  "thermostatMode": "MANUAL" // Режим работы термостата. **Тип:** String. Допустимые значения: "MANUAL", "AUTO", "ECO".
}

Протокол (запрос статуса и управляющие инструкции):

{
   "thermostat": {
    "thermostat-mode": {
      "thermostatMode": "MANUAL"
    }
  }
}

Статус адаптивного восстановления термостата (thermostat/adaptive-recovery-status)

Пример объявления возможности:

{
  "capability": "thermostat",
  "permission": "0100",
  "name": "adaptive-recovery-status" // Статус адаптивного восстановления термостата
}

Атрибуты (Состояние):

{
  "adaptiveRecoveryStatus": "HEATING" // Статус адаптивного восстановления термостата. **Тип:** String. Допустимые значения: "HEATING", "INACTIVE".
}

Протокол (запрос статуса и управляющие инструкции):

{
  "thermostat": {
    "adaptive-recovery-status": {
      "adaptiveRecoveryStatus": "HEATING"
    }
  }
}

Установка целевой температуры режима термостата (thermostat-target-setpoint)

Пример объявления возможности:

[[
  {
    "capability": "thermostat-target-setpoint",
    "name": "manual-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "eco-mode",
    "permission": "1110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      }
    }
  },
  {
    "capability": "thermostat-target-setpoint",
    "name": "auto-mode",
    "permission": "0110",
    "settings": {
      "temperatureUnit":{
        "type": "enum",
        "permission": "11",
        "value": "c",
        "values": [
          "c",
          "f"
        ]
      },
      "temperatureRange":{
        "type": "numeric",
        "permission": "01",
        "min": 4,
        "max": 35,
        "step": 0.5
      },
      "weeklySchedule":{
        "type": "object",
        "permission": "11",
        "value": {
          "maxEntryPerDay": 2,
          "Monday": [
          {
            "startTimeInMinutes": 440, // Время начала в минутах. **Тип:** int. Например, 7:20 = 440 минут.
            "upperSetpoint": 36.5, // Максимальная целевая температура. **Тип:** number.
            "lowerSetpoint": 20 // Минимальная целевая температура. **Тип:** number.
          },
          {
            "startTimeInMinutes": 900, // Время начала в минутах. Например, 15:00 = 900 минут.
            "upperSetpoint": 26.5, // Максимальная целевая температура. **Тип:** number.
            "lowerSetpoint": 21 // Минимальная целевая температура. **Тип:** number.
          }
        ],
          "Tuesday": [...
          ],
          "Wednesday": [...
          ],
          "Thursday": [...
          ],
          "Friday": [...
          ],
          "Saturday": [...
          ],
          "Sunday": [...
          ],
        }
      }
    }
  }
]

Атрибуты (Состояние):

{
  "targetSetpoint": 30 // Целевая температура для указанного режима. **Тип:** number, в единицах, заданных temperatureUnit.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "thermostat-target-setpoint": {
    "manual-mode": {
        "targetSetpoint": 30 
    },
    "auto-mode": {
        "targetSetpoint": 30 
    }
  }
}

Обнаружение датчика (detect)

Пример объявления возможности:

{
  "capability": "detect",
  "permission": "0110",
  "settings": { // Необязательно
    "detectInterval": {
      "permission": "11",
      "type": "numeric",
      "value": 300
    },
    "detectSensitivity": {
      "permission": "11",
      "type": "numeric",
      "value": 1000
    }
  }
}

Атрибуты (Состояние):

{
  "detected": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено.
}

Протокол (запрос статуса и управляющие инструкции):

{
    "detect": {
        "detected": true
    }
}

Обнаружение температуры (temperature)

Пример объявления возможности:

{
  "capability": "temperature",
  "permission": "0110",
  "settings": { // Необязательно
    "temperatureCalibration": { // Необязательная калибровка температуры
      "type": "numeric",
      "permission": "11",
      "min": -7, // Минимальное значение
      "max": 7, // Максимальное значение
      "step": 0.2, // Шаг регулировки температуры, единица совпадает с temperatureUnit
      "value": 5.2 // Текущее значение калибровки температуры. **Тип:** number.
    },
    "temperatureUnit": { // Необязательная единица температуры
      "type": "enum",
      "permission": "11",
      "value": "c",
      "values": [
        "c",
        "f"
      ]
    },
    "temperatureRange": { // Необязательный диапазон обнаружения температуры
      "type": "numeric",
      "permission": "01",
      "min": -40,
      "max": 80
    }
  }
}

Атрибуты (Состояние):

json
Копировать код
{
  "temperature": 26.5 // Текущая температура. **Тип:** Number, в градусах Цельсия.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "temperature": {
    "temperature": 20
  }
}

Обнаружение влажности (humidity)

Пример объявления возможности:

{
  "capability": "humidity",
  "permission": "0100",
  "settings": { // Необязательный диапазон обнаружения влажности.
    "humidityRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 100
    }
  }
}

Атрибуты (Состояние):

{
  "humidity": 50 // Текущая относительная влажность (в процентах). **Тип:** Number, диапазон 0-100.
}

Протокол (запрос статуса и управляющие инструкции):

{
    "humidity": {
        "humidity": 20
    }
}

Обнаружение батареи (battery)

Пример объявления возможности:

{
  "capability": "battery",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "battery": 95 // Оставшийся заряд батареи в процентах. **Тип:** Number, диапазон -1 до 100. Примечание: -1 означает неизвестный уровень батареи.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "battery": {
    "battery": 40
  }
}

Обнаружение одиночной кнопки (press)

Пример объявления возможности:

{
  "capability": "press",
  "permission": "1100",
  "settings": { // Необязательно
    "actions": { // Действия кнопки, необязательно.
      "type": "enum",
      "permission": "01",
      "values": [ // Необязательные действия кнопки. Значения по умолчанию: "singlePress", "doublePress", "longPress". Настроенные действия заменяют значения по умолчанию.
      ]
    }
  }
}

Атрибуты (Состояние):

{
  "press": "singlePress" // Тип нажатия кнопки. **Тип:** String. Стандартные значения: "singlePress" (одиночное/короткое), "doublePress" (двойное), "longPress" (долгое).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "press": {
    "press": "singlePress"
  }
}

Обнаружение множественных нажатий (multi-press)

Пример объявления возможности:

{
  "capability": "multi-press",
  "permission": "0100",
  "name": "1", // Имя атрибута multi-press. **Тип:** String. Разрешены только буквенно-цифровые символы.
  "settings": { // Необязательно
    "actions": { // Действия кнопки, необязательно.
      "type": "enum",
      "permission": "01",
      "values": [ // Необязательные действия кнопки. Значения по умолчанию: "singlePress", "doublePress", "longPress". Настроенные действия заменяют значения по умолчанию.
      ]
    }
  }
}

Атрибуты (Состояние):

{
  "press": "singlePress" // Тип нажатия кнопки. **Тип:** String. Стандартные значения: "singlePress" (одиночное/короткое), "doublePress" (двойное), "longPress" (долгое).
}

Протокол (запрос статуса и управляющие инструкции):

{
    [capability] :{
        [multi-press-name]：{
            press:[value]
        }
    }
}

пример:
{
  "multi-press": {
    "1": {
      "press": "singlePress"
    },
    "2": {
      "press": "doublePress"
    }
  }
}

Обнаружение уровня сигнала (rssi)

Пример объявления возможности:

{
  "capability": "rssi",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "rssi": -65 // Уровень беспроводного сигнала (Received Signal Strength Indicator). **Тип:** Number, единица dBm, отрицательное целое значение.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "rssi": {
    "rssi": -65
  }
}

Обнаружение попытки вскрытия (tamper-alert)

Пример объявления возможности:

{
  "capability": "tamper-alert",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "tamper": "clear" // Статус вскрытия. **Тип:** String. Возможные значения: "clear" (не вскрыто), "detected" (вскрыто).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "tamper-alert": {
    "tamper": "clear" // Статус вскрытия. **Тип:** String. Возможные значения: "clear" (не вскрыто), "detected" (вскрыто).
  }
}

Обнаружение уровня освещенности (illumination-level)

Пример объявления возможности:

{
  "capability": "illumination-level",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "level": "brighter" // Уровень яркости. **Тип:** String. Возможные значения: "brighter" (ярче), "darker" (темнее).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "illumination-level": {
    "level": "brighter"
  }
}

Обнаружение напряжения (voltage)

Пример объявления возможности:

{
  "capability": "voltage",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "voltage": 50 // Текущее значение напряжения, в единицах 0.01V. **Тип:** Number, неотрицательное значение.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "voltage": {
    "voltage": 50
  }
}

Обнаружение электрического тока (electric-current)

Пример объявления возможности:

{
  "capability": "electric-current",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "electric-current": 50 // Текущее значение тока, в единицах 0.01A. **Тип:** Number, неотрицательное целое.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "electric-current": {
    "electric-current": 50
  }
}

Обнаружение электрической мощности (electric-power)

Пример объявления возможности:

{
  "capability": "electric-power",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "electric-power": 50 // Текущее значение мощности, в единицах 0.01W. **Тип:** Number, неотрицательное целое.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "electric-power": {
    "electric-power": 50
  }
}

Обнаружение неисправности (fault)

Пример объявления возможности:

{
  "capability": "fault",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "fault": "none" // Статус неисправности. **Тип:** String. Возможные значения: "none" (без неисправностей), "detected" (неисправность обнаружена).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "fault": {
    "fault": "none"
  }
}

Пороговый переключатель (threshold-breaker)

Пример объявления возможности:

{
  "capability": "threshold-breaker",
  "permission": "0010",
  "settings": {
    "supportedSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "supported": [
          {
            "name": "lowerPower", // Порог низкой мощности
            "value": {
              "value": 50, // Значение мощности для обнаружения, в единицах 0.01W. **Тип:** Integer. Диапазон: >=0.
              "min_range": 10, // Минимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0.
              "max_range": 3500 // Максимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0.
            }
          },
          {
            "name": "upperPower", // Порог высокой мощности
            "value": {
              "value": 50, // Значение мощности для обнаружения, в единицах 0.01W. **Тип:** Integer. Диапазон: >=0.
              "min_range": 10, // Минимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0.
              "max_range": 3500 // Максимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0.
            }
          },
          {
            "name": "lowerElectricCurrent", // Порог низкого тока
            "value": {
              "value": 50, // Значение тока для обнаружения, в единицах 0.01A. **Тип:** Integer. Диапазон: >=0.
              "min_range": 10, // Минимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0.
              "max_range": 1500 // Максимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0.
            }
          },
          {
            "name": "upperElectricCurrent", // Порог высокого тока
            "value": {
              "value": 50, // Значение тока для обнаружения, в единицах 0.01A. **Тип:** Integer. Диапазон: >=0.
              "min_range": 10, // Минимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0.
              "max_range": 1500 // Максимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0.
            }
          },
          {
            "name": "lowerVoltage", // Порог низкого напряжения
            "value": {
              "value": 50, // Значение напряжения для обнаружения, в единицах 0.01V. **Тип:** Integer. Диапазон: >=0.
              "min_range": 10, // Минимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0.
              "max_range": 24000 // Максимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0.
            }
          },
          {
            "name": "upperVoltage", // Порог высокого напряжения
            "value": {
              "value": 50, // Значение напряжения для обнаружения, в единицах 0.01V. **Тип:** Integer. Диапазон: >=0.
              "min_range": 10, // Минимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0.
              "max_range": 24000 // Максимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0.
            }
          }
        ]
      }
    }
  }
}

Атрибуты (Состояние)

• Нет

Протокол (запрос статуса и управляющие инструкции)

• Нет

Функция импульса (inching)

Пример объявления возможности:

{
  "capability": "inching",
  "permission": "0010",
  "settings": {
    "inchingEnable": { // Настройка включения функции импульса
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Настройка действия импульса
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Настройка времени импульса
      "type": "numeric",
      "permission": "11",
      "min": 500,
      "max": 100000,
      "value": 1000,
      "unit": "ms"
    }
  }
}

Атрибуты (Состояние):

• Нет

Протокол (запрос статуса и управляющие инструкции):

• Нет

Поток камеры (camera-stream)

Пример объявления возможности:

{
  "capability": "camera-stream",
  "permission": "0010",
  "settings": {
    "streamSetting": {
      "type": "object",
      "permission": "11",
      "value": {
        "username": "String", // Учетная запись доступа. **Тип:** String. Обязательно.
        "password": "String", // Пароль доступа. **Тип:** String. Обязательно.
        "streamUrl": "rtsp://<username>:<password>@<hostname>:<port>/streaming/channel01", // URL потока. **Тип:** String. Обязательно.
        "videoCodec": "", // Видео кодек. **Тип:** String. Обязательно. Дополнительные параметры должны быть определены.
        "resolution": { // Разрешение видео. Обязательно.
          "width": 1080, // Ширина. **Тип:** Number. Обязательно.
          "height": 720 // Высота. **Тип:** Number. Обязательно.
        },
        "keyFrameInterval": 5, // Интервал ключевых кадров. **Тип:** String. Обязательно.
        "audioCodec": "G711", // Аудио кодек. **Тип:** String. Обязательно. Дополнительные параметры должны быть определены.
        "samplingRate": 50, // Частота дискретизации аудио, в Гц. **Тип:** Number. Обязательно. Дополнительные параметры должны быть определены.
        "dataRate": 50 // Битрейт. **Тип:** Number. Обязательно. Единица: kb/s.
      }
    }
  }
}

Атрибуты (Состояние):

• Нет

Протокол (запрос статуса и управляющие инструкции):

• Нет

Управление режимом (mode)

Пример объявления возможности:

[
  {
    "capability": "mode",
    "name": "fanLevel",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["low", "medium", "high"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию.
      }
    }
  },
  {
    "capability": "mode",
    "name": "thermostatMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["auto", "manual"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию.
      }
    }
  },
  {
    "capability": "mode",
    "name": "airConditionerMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["cool", "heat", "auto", "fan", "dry"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию.
      }
    }
  },
  {
    "capability": "mode",
    "name": "fanMode",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["normal", "sleep", "child"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию.
      }
    }
  },
  {
    "capability": "mode",
    "name": "horizontalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию.
      }
    }
  },
  {
    "capability": "mode",
    "name": "verticalAngle",
    "permission": "1100",
    "settings": {
      "supportedValues": {
        "type": "enum",
        "permission": "01",
        "values": ["30", "60", "90", "120", "180", "360"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию.
      }
    }
  }
]

Атрибуты (Состояние):

{
  "modeValue": "low" // Значение режима. **Тип:** String. Обязательно. См. поддерживаемые предустановленные режимы.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "mode": {
    "fanLevel": {
      "modeValue": "low"
    }
  }
}

Обнаружение углекислого газа (co2)

Пример объявления возможности:

{
  "capability": "co2",
  "permission": "0100",
  "settings": {
    "co2Range": {
      "type": "numeric",
      "permission": "01",
      "min": 400,
      "max": 10000
    }
  }
}

Атрибуты (Состояние):

{
  "co2": 111 // Концентрация CO2. **Тип:** Integer. Единица: ppm.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "co2": {
    "co2": 500
  }
}

Обнаружение освещенности (illumination)

Пример объявления возможности:

{
  "capability": "illumination",
  "permission": "0100",
  "settings": {
    "illuminationRange": {
      "type": "numeric",
      "permission": "01",
      "min": 0,
      "max": 160000
    }
  }
}

Атрибуты (Состояние):

{
  "illumination": 11 // Уровень освещенности. **Тип:** Integer. Единица: люкс.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "illumination": {
    "illumination": 50
  }
}

Обнаружение дыма (smoke)

Пример объявления возможности:

{
  "capability": "smoke",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "smoke": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "smoke": {
    "smoke": true
  }
}

Обнаружение открытия/закрытия дверного магнита (контакт)

Пример объявления возможности:

{
  "capability": "contact",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "contact": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "contact": {
    "contact": true
  }
}

Обнаружение движения (motion)

Пример объявления возможности:

{
  "capability": "motion",
  "permission": "0110",
  "settings": {
    "motionInterval": {
      "type": "numeric",
      "permission": "11",
      "value": 300
    },
    "motionSensitivity": {
      "type": "numeric",
      "permission": "11",
      "value": 1000
    }
  }
}

Атрибуты (Состояние):

{
  "motion": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "motion": {
    "motion": true
  }
}

Обнаружение утечки воды (water-leak)

Пример объявления возможности:

{
  "capability": "water-leak",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "waterLeak": true // Поле `waterLeak` указывает текущий результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "water-leak": {
    "waterLeak": true
  }
}

Переключатель обнаружения окна (window-detection)

Пример объявления возможности:

{
  "capability": "window-detection",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "window-detection": {
    "powerState": "on"
  }
}

Защита от детей (child-lock)

Пример объявления возможности:

{
  "capability": "child-lock",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "child-lock": {
    "powerState": "on"
  }
}

Защита от прямого удара (anti-direct-blow)

Пример объявления возможности:

{
  "capability": "anti-direct-blow",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "anti-direct-blow": {
    "powerState": "on"
  }
}

Горизонтальный маятник (horizontal-swing)

Пример объявления возможности:

{
  "capability": "horizontal-swing",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "horizontal-swing": {
    "powerState": "on"
  }
}

Вертикальный маятник (vertical-swing)

Пример объявления возможности:

{
  "capability": "vertical-swing",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "vertical-swing": {
    "powerState": "on"
  }
}

Режим ECO (eco)

Пример объявления возможности:

{
  "capability": "eco",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "eco": {
    "powerState": "on"
  }
}

Переключатель запуска (toggle-startup)

Пример объявления возможности:

{
  "capability": "toggle-startup",
  "permission": "1100",
  "name": "1" // Поле `name` задает имя атрибута для `toggle-startup`. **Тип:** String. Допускаются только буквы и цифры.
}

Атрибуты (Состояние):

{
  "startup": "on" // **Тип:** String. Опции: `on` (включить питание), `stay` (удерживать питание), `off` (выключить питание).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "toggle-startup": {
    "1": {
      "startup": "on"
    },
    "2": {
      "startup": "off"
    }
  }
}

Задержка обнаружения (detect-hold)

Пример объявления возможности:

{
  "capability": "detect-hold",
  "permission": "0100",
  "settings": {
    "detectHoldEnable": { // Настройка включения задержки обнаружения
      "permission": "01",
      "type": "boolean",
      "value": false
    },
    "detectHoldSwitch": { // Настройка действия задержки обнаружения
      "type": "enum",
      "permission": "01",
      "value": "on",
      "values": ["on", "off"]
    },
    "detectHoldTime": { // Настройка времени задержки обнаружения
      "type": "numeric",
      "permission": "01",
      "min": 1,
      "max": 359,
      "value": 5,
      "unit": "minute"
    }
  }
}

Атрибуты (Состояние):

{
  "detectHold": "on" // Поле `detectHold` указывает состояние удержания обнаружения. **Тип:** String. `on` означает, что удержание обнаружения активно, `off` означает, что удержание обнаружения не активно.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "detect-hold": {
    "detectHold": "on"
  }
}

Переключатель идентификации/активации (toggle-identify)

Пример объявления возможности:

{
  "capability": "toggle-identify",
  "permission": "1100", // Примечание: Эта возможность не используется для отчетности в текущей версии (V1.13.7) на ihost.
  "name": "1" // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4).
}

Атрибуты (Состояние):

{
  "identify": true, // Указывает, что устройство активно сообщило об идентификации или активации.
  "countdown": 180 // Поле `countdown` указывает длительность активации. **Тип:** Number. Единица: секунды.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "toggle-identify": {
    "1": {
      "countdown": 180 // Активировать устройство на 180 секунд.
    }
  }
}

// Устройство сообщает о самості активации
{
  "toggle-identify": {
    "1": {
      "identify": true
    }
  }
}

Переключатель измерения напряжения (toggle-voltage)

Пример объявления возможности:

{
  "capability": "toggle-voltage",
  "permission": "1100"
}

Атрибуты (Состояние):

{
  "voltage": 230 // Поле `voltage` указывает измеренное напряжение. **Тип:** Number. Единица: Вольт.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "toggle-voltage": {
    "voltage": 230
  }
}

Измерение электрического тока подкомпонента (toggle-electric-current)

Пример объявления возможности:

[
  {
    "capability": "toggle-electric-current",
    "permission": "0100",
    "name": "1" // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4).
  }
]

Атрибуты (Состояние):

{
  "electricCurrent": 50 // Поле `electricCurrent` представляет текущее значение тока. **Единица:** 0.01 A. **Тип:** Integer. Значение должно быть >= 0.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "toggle-electric-current": {
    "1": {
      "electricCurrent": 50
    }
  }
}

Измерение мощности подкомпонента (toggle-electric-power)

Пример объявления возможности:

[
  {
    "capability": "toggle-electric-power",
    "permission": "0100",
    "name": "1" // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4).
  }
]

Атрибуты (Состояние):

{
  "electricPower": 50, // Поле `electricPower` представляет текущее значение мощности. **Единица:** 0.01 W. **Тип:** Integer. Значение должно быть >= 0.
  "reactivePower": 50, // Поле `reactivePower` представляет текущее значение реактивной мощности. **Единица:** 0.01 W. **Тип:** Integer. Необязательно.
  "activePower": 50, // Поле `activePower` представляет текущее значение активной мощности. **Единица:** 0.01 W. **Тип:** Integer. Необязательно.
  "apparentPower": 50 // Поле `apparentPower` представляет текущее значение полной мощности. **Единица:** 0.01 W. **Тип:** Integer. Необязательно.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "toggle-electric-power": {
    "1": {
      "electricPower": 50,
      "reactivePower": 50,
      "activePower": 50,
      "apparentPower": 50
    }
  }
}

Статистика потребления энергии подкомпонента (toggle-power-consumption)

Пример объявления возможности:

[
  {
    "capability": "toggle-power-consumption",
    "permission": "1101",
    "name": "1", // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4).
    "settings": {
      "resolution": {
        "permission": "01",
        "type": "numeric",
        "value": 3600
      },
      "timeZoneOffset": {
        "permission": "01",
        "type": "numeric",
        "min": -12,
        "max": 14,
        "value": 0
      }
    }
  }
]

Атрибуты (Состояние):

Запустить/Остановить статистику в реальном времени:

{
  "rlSummarize": true, // Запуск или остановка статистики в реальном времени. **Тип:** Boolean. Обязательно.
  "timeRange": { // Интервал времени для сводки. Обязательно.
    "start": "2020-07-05T08:00:00Z", // Время начала учета потребления энергии. **Тип:** String. Обязательно.
    "end": "2020-07-05T09:00:00Z" // Время окончания учета потребления энергии. **Тип:** String. Обязательно.
  }
}

Запросить потребление энергии за диапазон времени:

{
  "type": "summarize", // Тип сводки. **Тип:** String. Обязательно. Опции: "rlSummarize" (сводка в реальном времени), "summarize" (текущая сводка).
  "timeRange": { // Интервал времени для сводки, обязателен, когда type равен "summarize".
    "start": "2020-07-05T08:00:00Z", // Время начала учета потребления энергии. **Тип:** String. Обязательно.
    "end": "2020-07-05T09:00:00Z" // Время окончания учета потребления энергии. **Тип:** String. Необязательно. Если не указано, по умолчанию используется текущее время.
  }
}

Ответ по потреблению энергии за указанный период:

{
  "type": "summarize", // Тип сводки. **Тип:** String. Обязательно.
  "rlSummarize": 50.0, // Общее потребление энергии. **Единица:** 0.01 kWh. **Тип:** Number. Необязательно.
  "electricityIntervals": [ // Разделено по `configuration.resolution` на несколько записей. Необязательно. Отсутствует, когда type = "rlSummarize".
    {
      "usage": 26.5, // Потребление энергии. **Единица:** 0.01 kWh. **Тип:** Number. Обязательно.
      "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** String. Обязательно.
      "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** String. Обязательно. Записи с интервалом меньше разрешения считаются недействительными.
    },
    {
      "usage": 26.5, // Потребление энергии. **Единица:** 0.01 kWh. **Тип:** Number. Обязательно.
      "start": "2020-07-05T09:00:00Z", // Время начала. **Тип:** String. Обязательно.
      "end": "2020-07-05T10:00:00Z" // Время окончания. **Тип:** String. Обязательно. Записи с интервалом меньше разрешения считаются недействительными.
    }
  ]
}

Протокол (запрос статуса и управляющие инструкции):

Запустить статистику в реальном времени:

{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": true,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": ""
      }
    }
  }
}

Остановить статистику в реальном времени:

{
  "toggle-power-consumption": {
    "1": {
      "rlSummarize": false,
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Получить историческое потребление энергии:

{
  "toggle-power-consumption": {
    "1": {
      "type": "summarize",
      "timeRange": {
        "start": "2020-07-05T08:00:00Z",
        "end": "2020-07-05T09:00:00Z"
      }
    }
  }
}

Получить потребление энергии в реальном времени:

{
  "toggle-power-consumption": {
    "1": {
      "type": "rlSummarize"
    }
  }
}

Индекс качества связи (lqi)

Пример объявления возможности:

{
  "capability": "lqi",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "lqi": 60 // Поле `lqi` представляет индекс качества связи. **Тип:** Number. Диапазон значений: 0–255.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "lqi": {
    "lqi": 60
  }
}

Функциональная конфигурация (configuration)

Пример объявления возможности:

[
  {
    "capability": "configuration",
    "permission": "1100"
  }
]

Атрибуты (Состояние):

{
  "deviceConfiguration": { // Функциональная конфигурация, связанная с устройством
    "defaultResolution": 300, // Разрешение по умолчанию для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно.
    "maxResolution": 86400, // Максимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно.
    "minResolution": 60 // Минимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно.
  }
}

Протокол (запрос статуса и управляющие инструкции):

{
  "configuration": {
    "deviceConfiguration": { // Функциональная конфигурация, связанная с устройством
      "defaultResolution": 300, // Разрешение по умолчанию для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно.
      "maxResolution": 86400, // Максимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно.
      "minResolution": 60 // Минимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно.
    }
  }
}

Система (system)

Пример объявления возможности:

[
  {
    "capability": "system",
    "permission": "1000"
  }
]

Атрибуты (Состояние):

{
  "restart": true // Команда перезапуска устройства. **Тип:** Boolean. Обязательно. Значение должно быть `true`.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "system": { // Конфигурация, связанная с возможностью. Необязательно.
    "restart": true
  }
}

Влажность (moisture)

Пример объявления возможности:

[
  {
    "capability": "moisture",
    "permission": "0100"
  }
]

Атрибуты (Состояние):

{
  "moisture": 55.5 // Поле `moisture` представляет процент насыщения влагой. **Тип:** Number. Обязательно. Диапазон: 0–100.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "moisture": {
    "moisture": 55.5
  }
}

Барометрическое давление (barometric-pressure)

Пример объявления возможности:

[
  {
    "capability": "barometric-pressure",
    "permission": "0100",
    "settings": {
      "barometricPressureRange": {
        "type": "numeric",
        "permission": "01",
        "min": 540, // Минимальное значение. **Тип:** Integer. Обязательно. Должно быть меньше `max`.
        "max": 1100 // Максимальное значение. **Тип:** Integer. Обязательно. Должно быть больше `min`.
      }
    }
  }
]

Атрибуты (Состояние):

{
  "barometricPressure": 50 // Значение барометрического давления. **Тип:** Integer. Обязательно. **Единица:** hPa.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "barometric-pressure": {
    "barometricPressure": 50
  }
}

Скорость ветра (wind-speed)

Пример объявления возможности:

[
  {
    "capability": "wind-speed",
    "permission": "0100",
    "settings": {
      "windSpeedRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`.
        "max": 50 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`.
      }
    }
  }
]

Атрибуты (Состояние):

{
  "windSpeed": 50 // Значение скорости ветра. **Тип:** Number. Обязательно. **Единица:** м/с (метры в секунду).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "wind-speed": {
    "windSpeed": 50
  }
}

Направление ветра (wind-direction)

Пример объявления возможности:

[
  {
    "capability": "wind-direction",
    "permission": "0100"
  }
]

Атрибуты (Состояние):

{
  "windDirection": 10 // Направление ветра. **Тип:** Integer. Обязательно. **Единица:** градусы. Диапазон: 0–360 градусов (по часовой стрелке).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "wind-direction": {
    "windDirection": 10
  }
}

Осадки (rainfall)

Пример объявления возможности:

[
  {
    "capability": "rainfall",
    "permission": "0100",
    "settings": {
      "rainfallRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`.
        "max": 450 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`.
      }
    }
  }
]

Атрибуты (Состояние):

{
  "rainfall": 11.11 // Значение осадков. **Тип:** Number. Обязательно. **Единица:** мм/ч (миллиметры в час).
}

Протокол (запрос статуса и управляющие инструкции):

{
  "rainfall": {
    "rainfall": 11.11
  }
}

Ультрафиолетовый индекс (ultraviolet-index)

Пример объявления возможности:

[
  {
    "capability": "ultraviolet-index",
    "permission": "0100",
    "settings": {
      "ultravioletIndexRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`.
        "max": 16 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`.
      }
    }
  }
]

Атрибуты (Состояние):

{
  "ultravioletIndex": 11.1 // Ультрафиолетовый индекс. **Тип:** Number. Обязательно.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "ultraviolet-index": {
    "ultravioletIndex": 11.1
  }
}

Электропроводимость (electrical-conductivity)

Пример объявления возможности:

[
  {
    "capability": "electrical-conductivity",
    "permission": "0100",
    "settings": {
      "electricalConductivityRange": {
        "type": "numeric",
        "permission": "01",
        "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`.
        "max": 23 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`.
      }
    }
  }
]

Атрибуты (Состояние):

{
  "electricalConductivity": 11.11 // Значение электропроводимости. **Тип:** Number. Обязательно. **Единица:** dS/m.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "electrical-conductivity": {
    "electricalConductivity": 11.11
  }
}

Мощность передачи (transmit-power)

Пример объявления возможности:

[
  {
    "capability": "transmit-power",
    "permission": "1100"
  }
]

Атрибуты (Состояние):

{
  "transmitPower": 9 // Значение мощности передачи устройства. **Тип:** Integer. Обязательно. **Единица:** dBm.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "transmit-power": {
    "transmitPower": 9
  }
}

Обнаружение PM2.5 (pm25)

Пример объявления возможности:

[
  {
    "capability": "pm25",
    "permission": "0100"
  }
]

Атрибуты (Состояние):

{
  "pm25": 10 // Концентрация PM2.5 в воздухе. **Тип:** Number. Обязательно. **Единица:** µg/m³.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "pm25": {
    "pm25": 10
  }
}

Индекс VOC (voc-index)

Пример объявления возможности:

{
  "capability": "voc-index",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "vocIndex": 10 // Индекс VOC, отражающий уровень загрязнения вредными газами. **Тип:** Number. Обязательно. **Единица:** µg/m³.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "voc-index": {
    "vocIndex": 10
  }
}

Обнаружение природного газа (gas)

Пример объявления возможности:

{
  "capability": "gas",
  "permission": "0100"
}

Атрибуты (Состояние):

{
  "gas": true // Указывает, обнаружена ли утечка природного газа. **Тип:** Boolean. Обязательно.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "gas": {
    "gas": true
  }
}

Статус работы орошения (irrigation/work-status)

Пример объявления возможности:

[
  {
    "capability": "irrigation",
    "permission": "0101",
    "name": "work-status",
    "settings": {
      "volumeUnit": {
        "type": "enum",
        "permission": "01",
        "values": ["L"],
        "value": "L"
      }
    }
  }
]

Атрибуты (Состояние):

{
  "realTimeVolume": 20, // Текущий объем орошения. **Тип:** Number. Необязательно. **Единица:** L.
  "start": "2020-07-05T08:00:00Z", // Время начала орошения. **Тип:** Date. Необязательно.
  "end": "2020-07-05T09:00:00Z", // Время окончания орошения. **Тип:** Date. Необязательно.
  "dailyVolume": 20 // Суточный объем орошения. **Тип:** Number. Необязательно. **Единица:** L.
}

Протокол (запрос статуса и управляющие инструкции):

Отчет о статусе работы:

{
  "irrigation": {
    "work-status": {
      "realTimeVolume": 20,
      "start": "2020-07-05T08:00:00Z",
      "end": "2020-07-05T09:00:00Z",
      "dailyVolume": 20
    }  
  }
}

Запрос статуса работы:

{
  "irrigation": {
    "type": "oneDay", // Тип агрегации. **Тип:** String. Обязательно. Опции: "oneDay", "30Days", "180Days".
    "timeRange": { // Интервал времени для агрегации. **Тип:** Object. Обязательно.
      "start": "2020-07-05T08:00:00Z", // Время начала агрегации данных о поливе. **Тип:** String. Обязательно.
      "end": "2020-07-05T09:00:00Z" // Время окончания агрегации данных о поливе. **Тип:** String. Необязательно. Если опущено, используется текущее время.
    }
  }
}

Результат запроса статуса работы:

{
  "irrigation": {
    "type": "oneDay", // Тип агрегации. **Тип:** String. Обязательно.
    "irrigationIntervals": [
      {
        "volume": 6500, // Объем орошения. **Тип:** Number. Обязательно. **Единица:** L.
        "duration": 30, // Длительность орошения. **Тип:** Number. Обязательно. **Единица:** минуты.
        "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** String. Обязательно.
        "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** String. Обязательно.
      },
      {
        "volume": 6500, // Объем орошения. **Тип:** Number. Обязательно. **Единица:** L.
        "duration": 30, // Длительность орошения. **Тип:** Number. Обязательно. **Единица:** минуты.
        "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** String. Обязательно.
        "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** String. Обязательно.
      }
    ]
  }
}

Режим работы орошения (irrigation/work-mode)

Пример объявления возможности:

[
  {
    "capability": "irrigation",
    "permission": "0100",
    "name": "work-mode",
    "settings": {
      "supportedModes": {
        "type": "enum",
        "permission": "01",
        "values": [
          "MANUAL", // Ручной режим
          "TIMER", // Одноразовое планирование
          "CYCLE-TIMER", // Повторяющееся планирование
          "VOLUME", // Одноразовый объем
          "CYCLE-VOLUME" // Повторяющийся объем
        ]
      }
    }
  }
]

Атрибуты (Состояние):

{
  "workMode": "MANUAL" // Режим работы орошения. **Тип:** String. Необязательно. Значения должны быть из `settings.supportedModes`.
}

Протокол (запрос статуса и управляющие инструкции):

{
  "irrigation": {
    "work-mode": "MANUAL"
  }
}

Автоматический контроллер орошения (irrigation/auto-controller)

Пример объявления возможности:

[
  {
    "capability": "irrigation",
    "permission": "1100",
    "name": "auto-controller",
    "settings": {
      "volumeRange": { // Диапазон объема
        "type": "enum",
        "permission": "01",
        "min": 0,
        "max": 6500,
        "unit": "L"
      },
      "timeRange": { // Диапазон времени
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 86400,
        "unit": "second"
      },
      "cycleCountRange": { // Диапазон количества циклов
        "type": "enum",
        "permission": "01",
        "min": 1,
        "max": 100,
        "step": 1
      }
    }
  }
]

Атрибуты (Состояние):

Одноразовое или повторяющееся планирование:

{
  "type": "time", // Режим полива. **Тип:** String. Обязательно. Опции: "volume", "time".
  "action": {
    "perDuration": 60, // Длительность одного цикла полива. **Тип:** Number. Обязательно.
    "intervalDuration": 20, // Интервал между циклами полива. **Тип:** Number. Обязательно.
    "count": 3 // Количество циклов полива. **Тип:** Number. Обязательно.
  }
}

Одноразовый или повторяющийся по объему:

{
  "type": "volume", // Режим полива. **Тип:** String. Обязательно. Опции: "volume", "time".
  "action": {
    "perConsumedVolume": 60, // Объем, расходуемый за один цикл полива. **Тип:** Number. Обязательно.
    "intervalDuration": 20, // Интервал между циклами полива. **Тип:** Number. Обязательно.
    "count": 3 // Количество циклов полива. **Тип:** Number. Обязательно.
  }
}

Протокол (запрос статуса и управляющие инструкции):

Одноразовое или повторяющееся планирование:

{
  "irrigation": {
    "auto-controller": {
      "type": "time", // Режим полива. **Тип:** String. Обязательно.
      "action": {
        "perDuration": 60, // Длительность одного цикла полива. **Тип:** Number. Обязательно.
        "intervalDuration": 20, // Интервал между циклами. **Тип:** Number. Обязательно.
        "count": 3 // Количество циклов. **Тип:** Number. Обязательно.
      }
    }
  }
}

Одноразовый или повторяющийся по объему:

{
  "irrigation": {
    "auto-controller": {
      "type": "volume", // Режим полива. **Тип:** String. Обязательно.
      "action": {
        "perConsumedVolume": 60, // Объем, расходуемый за цикл. **Тип:** Number. Обязательно.
        "intervalDuration": 20, // Интервал между циклами. **Тип:** Number. Обязательно.
        "count": 3 // Количество циклов. **Тип:** Number. Обязательно.
      }
    }
  }
}

Поддерживаемые предустановленные режимы

**Имена режимов **	**Дополнительные значения **
fanLevel (уровень вентилятора)	"low"
"medium"
"high"
thermostatMode (режим термостата)	"auto"
"manual"
airConditionerMode >= 1.11.0 (режим кондиционера)	"cool"
"heat"
"auto"
"fan"
"dry"
fanMode >= 1.11.0 (режим вентилятора)	"normal"
"sleep"
"child"
horizontalAngle >= 1.11.0 (горизонтальный угол)	"30"
"60"
"90"
"120"
"180"
"360"
verticalAngle >= 1.11.0 (вертикальный угол)	"30"
"60"
"90"
"120"
"180"
"360"

c. Описание тегов

• Специальный ключ toggle используется для установки имени подкомпонента toggle.

{
    "toggle": {
        '1': 'Канал1',
        '2': 'Канал2',
        '3': 'Канал3',
        '4': 'Канал4',
    },
}

• Специальный ключ temperature_unit используется для установки единицы температуры.

{
    "temperature_unit":'c' // c — Цельсий; f — Фаренгейт
}

d. Специальные коды ошибок и описание

Код ошибки	Описание	Версия iHost
110000	Под-устройство/группа, соответствующая id, не существует	≥2.1.0
110001	Шлюз находится в состоянии поиска zigbee-устройств	≥2.1.0
110002	Устройства в группе не имеют общей возможности	≥2.1.0
110003	Неверное количество устройств	≥2.1.0
110004	Неверное количество групп	≥2.1.0
110005	Устройство офлайн	≥2.1.0
110006	Не удалось обновить статус устройства	≥2.1.0
110007	Не удалось обновить статус группы	≥2.1.0
110008	Достигнуто максимальное количество групп. Создайте до 50 групп	≥2.1.0
110009	IP-адрес камерного устройства неверен	≥2.1.0
110010	Ошибка авторизации доступа к камере	≥2.1.0
110011	Ошибка адреса потока камерного устройства	≥2.1.0
110012	Кодирование видео камерой не поддерживается	≥2.1.0
110013	Устройство уже существует	≥2.1.0
110014	Камера не поддерживает офлайн-режим	≥2.1.0
110015	Пароль учетной записи не совпадает с паролем в адресе RTSP-потока	≥2.1.0
110016	Шлюз находится в состоянии поиска onvif-камер	≥2.1.0
110017	Превышено максимальное количество добавленных камер	≥2.1.0
110018	Путь ESP-камеры указан неверно	≥2.1.0
110019	Не удалось получить доступ к адресу сервиса стороннего устройства	≥2.1.0

e. Поиск под-устройства

Разрешить авторизованным пользователям включать или отключать поиск шлюзом под-устройств через этот интерфейс

• 💡Примечание: В настоящее время поддерживается только поиск Zigbee-под-устройств.

• 💡Примечание: Zigbee-под-устройства будут добавлены автоматически после поиска. Не нужно использовать интерфейс "Ручное добавление под-устройств" :::tips

• URL：/open-api/V2/rest/devices/discovery

• Метод: PUT

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
enable	boolean	N	true (Начать сопряжение); false (Приостановить сопряжение)
type	string	N	Тип поиска: Zigbee

Успешный ответ с данными: пустой объект {} :::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: ** 200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

f. Ручное добавление под-устройства

Разрешить авторизованным пользователям добавить одно под-устройство через этот интерфейс.

• Примечание: В настоящее время поддерживаются только RTSP-камера и ESP32-камера :::tips

• URL：/open-api/V2/rest/devices

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
name	string	N	Название под-устройства
display_category	string	N	Тип устройства. Поддерживается только камера.
capabilities	CapabilityObject[]	N	Список возможностей. Когда display_category = camera, capabilities включает только возможности camera-stream.
protocal	string	N	Протокол устройства. RTSP; ESP32-CAM
manufacturer	string	N	Производитель.
model	string	N	Модель устройства
firmware_version	string	N	Версия прошивки устройства

CapabilityObject

Атрибут	Тип	Необязательно	Описание
capability	string	N	Имя возможности. Поддерживается только "camera-stream"
permission	string	N	Разрешение устройства. Поддерживается только чтение.
configuration	CameraStreamConfigurationObject	Y	Конфигурация потокового видео камеры.

SettingsObject

Атрибут	Тип	Необязательно	Описание
streamSetting	StreamSettingObject	N	Конфигурация потокового сервиса

StreamSettingObject

Атрибут	Тип	Необязательно	Описание
type	string	N	Конфигурация потокового сервиса
permission	string	N	Разрешение возможности. Поддерживает только "11" (изменяемое).
value	StreamSettingValueObject	N	Конкретные значения конфигурации

StreamSettingValueObject

Атрибут	Тип	Необязательно	Описание
stream_url	string	N	Формат URL потока
Формат:<schema>://<hostname>:<port>/<username>:<password>@<service_path>
Пример:rtsp://admin:[email protected]:554/streaming/channel01
Варианты схемы:
rtsp (Протокол потоковой передачи в реальном времени)
http (Протокол гипертекста) — для устройств ESP32-CAM
*Примечание: Некоторые камеры могут не требовать имени пользователя или пароля. В таких случаях вы можете опустить <username> и <password> поля из URL.

Успешный ответ с данными:

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства

:::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {
    "serial_number": "serial_number"
  },
  "message": "success"
}

Данные об ошибке при неудаче: пустой объект :::tips Условие：

1. Ошибка доступа к адресу потока камеры (ошибка формата, ошибка авторизации, сетевые исключения и т.д.)

2. Устройство уже существует

3. Если добавление одного устройства не удалось, возвращается ошибка для всех устройств.

Код состояния: 200 OK Код ошибки： ● 110009 Ошибка IP-адреса камеры ● 110010 Ошибка авторизации доступа к камере ● 110011 Ошибка адреса потока камеры ● 110012 Видео кодирование камеры не поддерживается ● 110013 Устройство уже существует ::: Пример ответа:

{
  "error": 110009,
  "data": {},
  "message": "не удалось получить доступ к IP камеры" 
}

g. Получить список под-устройств

Разрешить авторизованным пользователям получить список под-устройств шлюза через этот интерфейс. :::tips

• URL：/open-api/V2/rest/devices

• Метод: GET

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными:

Атрибут	Тип	Необязательно	Описание
device_list	ResponseDeviceObject[]	N	Список устройств

ResponseDeviceObject

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	"N" когда подключено стороннее устройство, иначе "Y"	Уникальный серийный номер стороннего устройства
service_address	string	"N" когда подключено стороннее устройство, иначе "Y"	Адрес сервиса стороннего устройства
name	string	N	Название устройства; если оно не переименовано, будет отображаться на фронтенде по правилам отображения по умолчанию.
manufacturer	string	N	Производитель
model	string	N	Модель устройства
firmware_version	string	N	Версия прошивки. Может быть пустой строкой.
hostname	string	Y	Имя хоста устройства
mac_address	string	Y	MAC-адрес устройства
app_name	string	Y	Название приложения, к которому оно принадлежит. Если app_name был заполнен при получении сертификата открытого интерфейса, тогда все последующие устройства, подключенные через этот сертификат, будут записаны в это поле.
display_category	string	N	Категория устройства
capabilities	CapabilityObject[]	N	Возможности устройства
protocol	string	"N" когда подключено стороннее устройство, иначе "Y"	Протокол устройства: zigbee, onvif, rtsp, esp32-cam
state	object	Y	Объект состояния устройства. Для примеров состояний различных возможностей, пожалуйста, проверьте 【Поддерживаемые возможности устройства】
теги	object	Y	JSON-формат ключ-значение, пользовательская информация об устройстве. Функция следующая: - Используется для хранения каналов устройства - Используется для хранения единиц температуры - Пользовательская информация для других сторонних устройств
в сети	boolean	N	Статус онлайн: True — в сети False — не в сети
подсеть	boolean	Y	Находится ли в той же подсети, что и шлюз

CapabilityObject 💡Примечание: Пожалуйста, проверьте Примеры поддерживаемых возможностей устройства в разделе [Поддерживаемые возможности устройства].

Атрибут	Тип	Необязательно	Описание
capability	string	N	Название возможности. Подробности смотрите в [Поддерживаемые возможности устройства]
permission	string	N	Разрешение возможности. Возможные значения: "read" (чтение), "write" (запись), "readWrite" (чтение и запись).
configuration	object	Y	Информация о конфигурации возможности. В настоящее время используется camera-stream, см. [Поддерживаемые возможности устройства]
name	string	Y	Поле name в toggle. Номер подканала, используемый для идентификации многоканальных устройств. Например, если name равен 1, это означает канал 1.

:::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data":{
    "device_list":  [
      {
        "serial_number": "ABCDEFGHIJK",
        "name": "Мое устройство",
        "manufacturer": "SONOFF",
        "model": "BASICZBR3",
        "firmware_version": "1.1.0",
        "display_category": "switch",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          },
          {
            "capability": "rssi",
            "permission": "read"
          }
        ],
        "protocal": "zigbee",
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ],
  }
  "message": "success"
}

h. Обновить указанную информацию или состояние устройства

Разрешить авторизованным пользователям изменять базовую информацию суб-устройства и отправлять команды управления через этот интерфейс. :::tips

• URL：/open-api/V2/rest/devices/{serial_number}

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
name	string	Y	Название устройства
теги	object	Y	JSON-формат ключ-значение, пользовательская информация об устройстве.
state	object	Y	Объект состояния устройства. Для примеров состояний различных возможностей, пожалуйста, проверьте [Поддерживаемые возможности устройства]
configuration	object	Y	Информация о конфигурации возможности, в настоящее время только возможность camera_stream поддерживает изменение.

Успешный ответ с данными: :::tips Условия: Параметры запроса корректны и проверка подлинности пользователя пройдена. **Код состояния: **200 OK Код ошибки:

• 110000 Соответствующее id суб-устройства/группы не существует ::: Пример ответа:

{
  "error": 0,
  "data":{
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "我的设备",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  },
  "message": "success"
}

i. Удалить суб-устройство

Разрешить авторизованным пользователям удалять суб-устройства через этот интерфейс. :::tips

• URL：/open-api/V2/rest/devices/{serial_number}

• Метод：DELETE

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
name	string	Y	Имя устройства.
теги	object	Y	Пары ключ-значение в формате JSON, используемые для хранения имен каналов устройства и другой информации о суб-устройствах.
state	object	Y	Изменить состояние устройства; для подробностей протокола см. "Поддерживаемые возможности устройства."
capabilities	CapabilityObject []	Y	Информация о конфигурации возможности; все возможности, поддерживающие установку конфигураций, могут быть изменены. Обратите внимание, что разрешения нельзя менять.

Успешный ответ с данными: :::tips Условия: Параметры запроса корректны и проверка подлинности пользователя пройдена. **Код состояния: **200 OK Коды ошибок:

• 110000: Соответствующее ID суб-устройства/группы не существует.

• 110006: Не удалось обновить состояние устройства.

• 110019: Не удалось обратиться к сервисному адресу третьей стороны.

• 110024: Не удалось обновить конфигурацию устройства. ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // включить устройство
  await axios({
    url: `http://<domain name or ip address>/open-api/v2/rest/devices/${serial_number}`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      state: {
        power: {
          powerState: 'on'
        }
      }
    }
  });
})()

j. Удалить суб-устройство

Позволяет авторизованным пользователям удалять суб-устройства через этот интерфейс. :::tips

• URL：/open-api/v2/rest/devices/{serial_number}

• Метод：DELETE

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: :::tips Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

k. Запросить состояние устройства

Позволяет авторизованным пользователям запрашивать состояние устройства через этот интерфейс. :::tips

• URL：/open-api/v2/rest/devices/:serial_number/query-state/{capability}

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
query_state	object	N	Запросить состояние устройства; для подробностей протокола см. "Поддерживаемые возможности устройства."

import axios from 'axios';

const serial_number = 'serial_number';
const access_token = 'access_token';

(async function main() {
  // включить устройство
  await axios({
    url: `http://<domain name or ip address>/open-api/v2/rest/devices/${serial_number}/query-state/power-consumption`,
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${access_token}`
    },
    data: {
      "query_state":{
        "power-consumption":{
          "type": "summarize", // Тип статистики, обязателен
          "timeRange": { // Временной диапазон для суммирования, обязателен, когда type="summarize"
            "start": "2020-07-05T08:00:00Z", // Время начала статистики потребления энергии
            "end": "2020-07-05T09:00:00Z" // Время окончания статистики потребления энергии; если опущено, по умолчанию текущее время
          }
        }
      }
    });
})()

Успешный ответ с данными: :::tips Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

3.4 Управление безопасностью

a. Получить список безопасности

Позволяет авторизованным пользователям изменять настройки шлюза через этот интерфейс. :::tips

• URL：/open-api/v2/rest/security

• Метод：GET

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными:

Атрибут	Тип	Необязательно	Описание
security_list	ResponseSecurityObject[]	N	список устройств в ответе

ResponseDeviceObject

Атрибут	Тип	Необязательно	Описание
sid	int	N	ID охраны
name	string	N	Название охраны
enable	bool	N	Включено ли

• true Включено

• false Выключено |

:::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {
    "security_list":[
      {
        "sid": 1,
        "name": "Home Mode",
        "enable": true
      }
    ]
  },
  "message": "success"
}

b. Включить указанную режим охраны

Позволяет авторизованным пользователям включить указанный режим охраны через этот интерфейс. :::tips

• URL：/open-api/v2/rest/security/{security_id}/enable

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: пустой объект {} :::tips Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

c. Отключить указанную режим охраны

Позволяет авторизованным пользователям отключить указанный режим охраны через этот интерфейс. :::tips

• URL：/open-api/v2/rest/security/{security_id}/disable

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: пустой объект {} :::tips Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

d. Однокнопочная настройка охраны

Позволяет авторизованным пользователям включить режим однокнопочной настройки охраны через этот интерфейс. :::tips

• URL：/open-api/v2/rest/security/enable

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: пустой объект {} :::tips Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

e. Отключить охрану

Позволяет авторизованным пользователям отключить охрану через этот интерфейс. :::tips

• URL：/open-api/v2/rest/security/disable

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: пустой объект {} :::tips Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: **200 OK ::: Пример ответа:

{
  "error": 0,
  "data": {},
  "message": "success"
}

4. Доступ третьих сторон к устройствам

4.1 Инструкция по доступу

Доступ устройства

Доступ стороннего шлюза

Шаги доступа

1. Определите классификацию устройства в шлюзе. Подробности см. [Поддерживаемые типы устройств].

2. Определите возможности, к которым устройство может получить доступ. Подробности см. [Поддерживаемые возможности устройства].

3. Вызовите интерфейс [Discovery Request], чтобы добавить устройство в шлюз.

   1. Внимание: Вам необходимо предоставить адрес сервиса для получения инструкций, выданных шлюзом, который используется для получения команд управления устройством, выданных шлюзом.

4. Если статус стороннего устройства изменился, вам нужно вызвать интерфейс [Device States Change Report], чтобы отправить последнее состояние обратно в шлюз.

5. После добавления стороннее устройство появится в Списке устройств, с большинством функций шлюза (в отличие от других не-сторонних устройств). Общие открытые интерфейсы, связанные с устройством, смогут использоваться в обычном режиме.

• Выберите соответствующую категорию устройства. Классификация повлияет на конечное отображение в пользовательском интерфейсе после подключения устройства к шлюзу.

• Выберите правильную способность устройства. Список возможностей определит протокол состояния устройства.

Процесс программирования

a. Доступ устройства

b. Доступ стороннего шлюза

4.2 Пример доступа

Переключатель, Розетка

Синхронизировать сторонние устройства

// Запрос
URL：/open-api/v2/rest/thirdparty/event
Метод：POST
Заголовок：
  Content-Type: application/json
  Autorization: Bearer  <token>
Тело:
{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission": "1100"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "версия прошивки",
          "service_address": "http://192.168.31.14/webhook"
      	}
      ]
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "third_serial_number": "third_serial_number",
        "serial_number": "серийный номер"
      }
    ]
  }
}

Сообщить состояние устройства

URL：/open-api/V2/rest/thirdparty/event
Метод：POST
Заголовок：
  Content-Type: application/json
  Autorization: Bearer  <token>
Тело:

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {}
}

Сообщить офлайн/онлайн

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {}
}

Получать инструкции о том, как шлюз управляет устройством

URL：<service address>
Метод：POST
Заголовок：
  Content-Type: application/json
B

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "endpoint": {
      "third_serial_number": "third_serial_number",
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {}
}

Запросить устройство

URL：/open-api/V2/rest/devices
Метод：GET
Заголовок：
  Content-Type: application/json
  Autorization: Bearer  <token>
Тело: Нет

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "серийный номер",
        "third_serial_number": "third_serial_number",
        "name": "my plug",
        "manufacturer": "manufacturer name",
        "model": "model name",
        "firmware_version": "версия прошивки",
        "display_category": "plug",
        "capabilities": [
          {
            "capability": "power",
            "permission": "readWrite"
          }
        ],
        "state": {
          "power": {
            "powerState": "on"
          }
        },
        "tags": {
          "key": "value"
        },
        "online": true
      }
    ]
  },
  "message": "success"
}

4.3 Веб-API

Интерфейс запроса третьей стороны к шлюзу

Формат запроса

Разрешает авторизованным пользователям отправлять события в шлюз через этот интерфейс. :::tips

• URL：/open-api/V2/rest/thirdparty/event

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Autorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
event	EventObject	N	Структура объекта события запроса

EventObject

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
endpoint	EndpointObject	Y	Структура endpoint в запросе Примечание: Это поле пустое при синхронизации нового списка устройств.
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя запроса. необязательный параметр: DiscoveryRequest: Синхронизировать новые устройства DeviceStatesChangeReport: Отчет об обновлении состояния устройства DeviceOnlineChangeReport: Отчет о статусе онлайн устройства
message_id	string	N	ID сообщения запроса, UUID_V4
version	string	N	Номер версии протокола запроса. В настоящее время фиксирован на 1

EndpointObject

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	N	Уникальный серийный номер стороннего устройства
теги	object	Y	JSON-формат ключ-значение, пользовательская информация об устройстве. [Функция управления устройством] - [Описание тегов]

PayloadObject В зависимости от header.name различается структура запроса.

Формат ответа

:::tips **Код состояния: **200 OK Параметры ответа: :::

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка ответа
payload	PayloadObject	N	Структура payload ответа

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя заголовка ответа. необязательные параметры: Response: Успешный ответ ErrorResponse: Ответ с ошибкой
message_id	string	N	ID сообщения заголовка ответа, UUID_V4. Передайте сюда message_id из заголовка запроса *Если входной параметр запроса не содержит message_id, это поле будет пустой строкой в ответе.
version	string	N	- Номер версии протокола запроса. В настоящее время фиксирован на 1.

Успешный ответ--PayloadObject ：

В зависимости от типа запроса структура ответа различается. Для подробностей см. документ конкретного запроса.

Ответ при ошибке--PayloadObject：

Атрибут	Тип	Необязательно	Описание
type	string	N	Типы ошибок:

• INVALID_PARAMETERS: Ошибка параметров

• AUTH_FAILURE: Ошибка авторизации

• INTERNAL_ERROR: Внутренняя ошибка сервиса | | description | string | N | Описание ошибки |

DiscoveryRequest Синхронизировать новый список устройств

• Примечание: После синхронизации устройства в шлюз оно по умолчанию в сети, то есть online=true. Последующие изменения online полностью зависят от синхронизации с третьей стороной через интерфейс DeviceOnlineChangeReport.

Параметры запроса: EndpointObject**：**Нет PayloadObject：

Атрибут	Тип	Необязательно	Описание
endpoints	EndpointObject[]	N	Список устройств

EndpointObject:

Атрибут	Тип	Необязательно	Описание
third_serial_number	string	N	Уникальный серийный номер стороннего устройства
name	string	N	Название устройства
display_category	string	N	Категория устройства. Подробности см. в [Поддерживаемые типы устройств]. *Сторонние устройства сейчас не поддерживают добавление камер.
capabilities	CapabilityObject[]	N	Список возможностей
state	object	N	Начальная информация о состоянии
manufacturer	string	N	Производитель
model	string	N	Модель устройства
теги	object	Y	JSON-формат ключ-значение, пользовательская информация об устройстве: Используется для хранения каналов устройства Используется для хранения единиц температуры Другие пользовательские данные третьих сторон
firmware_version	string	N	Версия прошивки
service_address	string	N	Адрес сервиса. Например http://192.168.31.14/service_address

Пример запроса :

{
  "event": {
    "header": {
      "name": "DiscoveryRequest",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
      "endpoints": [
        {
          "third_serial_number": "third_serial_number_1",
          "name": "my plug",
          "display_category": "plug",
          "capabilities": [
            {
              "capability": "power",
              "permission" "readWrite"
            }
          ],
          "state": {
            "power": {
              "powerState": "on"
            }
          },
          "tags": {
            "key": "value"
          },
          "manufacturer": "manufacturer name",
          "model": "model name",
          "firmware_version": "версия прошивки",
          "service_address": "http://192.168.31.14/service_address"
        }
      ]
    }
  }
}

Параметры ответа: PayloadObject：

Атрибут	Тип	Необязательно	Описание
endpoints	EndpointObject[]	N	Список устройств

EndpointObject:

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	N	Уникальный серийный номер стороннего устройства

Пример корректного ответа:

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {
    "endpoints": [
      {
        "serial_number": "серийный номер",
        "third_serial_number": "third_serial_number"
      }
    ]
  }
}

Пример ответа с ошибкой:

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "webhook не может быть пустым" 
  }
}

DeviceStatesChangeReport Отчет об изменении состояния устройства

• Примечание: Повторяющиеся отчеты о состоянии могут неправильно сработать связанные сцены.

Параметры запроса: PayloadObject：

Атрибут	Тип	Необязательно	Описание
state	object	N	Состояние устройства, см. подробности в [Поддерживаемые возможности устройства]

Пример запроса :

{
  "event": {
    "header": {
      "name": "DeviceStatesChangeReport",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
    },
    "payload": {
       "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Параметры ответа: PayloadObject: Пустой объект Пример успешного ответа:

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {}
}

DeviceOnlineChangeReport Отчет о статусе онлайн устройства

• Примечание: Повторяющиеся отчеты о состоянии могут неправильно сработать связанные сцены.

Параметры запроса: PayloadObject：

Атрибут	Тип	Необязательно	Описание
в сети	boolean	N	Статус онлайн устройства true: В сети
false: Не в сети

Пример запроса :

{
  "event": {
    "header": {
      "name": "DeviceOnlineChangeReport",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
       "online": true
    }
  }
}

Параметры ответа: PayloadObject: Пустой объект Пример успешного ответа:

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {}
}

DeviceInformationUpdatedReport Отчет об обновлении информации об устройстве

• Примечание: Обновление может повлиять на существующие сцены или функции безопасности.

Параметры запроса: PayloadObject：

Атрибут	Тип	Необязательно	Описание
capabilities

| CapabilityObject[]

| N

| Список возможностей. Подробности можно найти в разделе поддерживаемых возможностей устройства. **Примечание: **Этот параметр обновит только value из настройки ключ внутри CapabilityObject, и обновления разрешены только если permission для настройки ключа является 11 или 01. Для конкретного определения структуры настройки в CapabilityObjectсмотрите подробное описание в разделе 2.3 Категории отображения устройств и возможности устройства. | | tags

| объект

| Y

| JSON-формат ключ-значение, пользовательская информация об устройстве.

• Может быть использовано для хранения каналов устройства

• Может быть использовано для хранения единиц температуры

• Другие пользовательские данные третьих сторон |

Пример запроса :

{
  "event": {
    "header": {
      "name": "DeviceInformationUpdatedReport",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "detect",
          "permission": "0110",
          "settings":{
            "detectInterval":{
              "permission": "11",
              "type": "numeric",
              "value": 300,
            },
            "detectSensitivity":{
              "permission": "11",
              "type": "numeric",
              "value": 1000,
            }
          }
        }
      ]
    }
  }
}

параметры ответа: PayloadObject: Пустой объект Пример успешного ответа:

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "2"
  },
  "payload": {}
}

Шлюз отправляет интерфейс инструкции через адрес сервиса устройства

• Примечание:

1. Сторонние должны ответить на запрос шлюза в течение 3 секунд. В противном случае шлюз сочтет выполнение команды вышедшим по таймауту.

2. Если сервис третьей стороны оффлайн, шлюз установит устройство в состояние оффлайн, и стороннему сервису потребуется сообщить состояние устройства (DeviceStatesChangeReport) или онлайн-состояние (DeviceOnlineChangeReport), прежде чем вернуться в онлайн.

Формат запроса

Шлюз отправляет инструкции третьей стороне через интерфейс адреса сервиса устройства. :::tips

• URL：

• Метод：POST

• Заголовок：

  • Content-Type: application/json ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
directive	DirectiveObject	N	Информация о структуре объекта директивы

DirectiveObject

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
endpoint	EndpointObject	N	Структура endpoint в запросе
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя запроса. Необязательные параметры: UpdateDeviceStates: Обновить состояния устройства
message_id	string	N	ID сообщения запроса, UUID_V4
version	string	N	Номер версии протокола запроса. В настоящее время фиксирован на 1.

EndpointObject

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	N	Уникальный серийный номер стороннего устройства
теги	object	N	JSON-формат ключ-значение, пользовательская информация об устройстве. [Функция управления устройством] - [Описание тегов]

PayloadObject: В зависимости от различных header.name, для каждого имеется конкретная структура запроса.

Пример запроса :

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number",
      "tags": {}
    },
    "payload": {
      "state": {
        "power": {
          "powerState": "on"
        }
      }
    }
  }
}

Формат ответа

:::tips **HTTP Код состояния: **200 OK Атрибуты HTTP-ответа： :::

Атрибут	Тип	Необязательно	Описание
event	EventObject	N	Структура события ответа

EventObject

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя заголовка ответа. Необязательный параметр: UpdateDeviceStatesResponse: Ответ на обновление состояний устройства ErrorResponse: Ответ с ошибкой
message_id	string	N	ID сообщения заголовка ответа, UUID_V4. Передайте сюда message_id из заголовка запроса
version	string	N	Номер версии протокола запроса. В настоящее время фиксирован на 1.

Успешный ответ--PayloadObject：

В зависимости от типа запроса структура ответа различается. Для подробностей см. документ конкретного запроса.

Ответ при ошибке--PayloadObject：

Атрибут	Тип	Необязательно	Описание
type	string	N	Типы ошибок:

• ENDPOINT_UNREACHABLE: Устройство недоступно или оффлайн

• ENDPOINT_LOW_POWER: Устройство в режиме низкого энергопотребления и не может быть управляемо

• INVALID_DIRECTIVE: Аномальная директива от шлюза

• NO_SUCH_ENDPOINT: Устройство не существует

• NOT_SUPPORTED_IN_CURRENT_MODE: Текущий режим не поддерживает операцию

• INTERNAL_ERROR: Внутренняя ошибка сервиса

• REMOTE_KEY_CODE_NOT_LEARNED: Код клавиши пульта дистанционного управления не выучен |

:::советы Условия: Параметры запроса корректны. **Код состояния: **200 OK Параметры ответа: :::

{
  "event": {
    "header": {
      "name": "UpdateDeviceStatesResponse",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {}
  }
}

{
  "event": {
    "header": {
      "name": "ErrorResponse",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
      "type": "ENDPOINT_UNREACHABLE"
    }
  }
}

UpdateDeviceStates

Параметры запроса: PayloadObject：

Атрибут	Тип	Необязательно	Описание
state	object	N	Состояние устройства, см. подробности в [Поддерживаемые возможности устройства].

Пример запроса :

{
  "directive": {
    "header": {
      "name": "UpdateDeviceStates",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
       "state": : {
         "power": {
           "powerState": "on"
         }
       }
    }
  }
}

Параметры ответа: PayloadObject：пустой объект Пример успешного ответа

{
  "header": {
    "name": "Response",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {}
}

QueryDeviceStates

Параметры запроса: PayloadObject：

Атрибут	Тип	Необязательно	Описание
state	object	N	Состояние устройства, см. подробности в [Поддерживаемые возможности устройства].

Пример запроса :

{
  "directive": {
    "header": {
      "name": "QueryDeviceStates",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number",
      "third_serial_number": "third_serial_number"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "timeRange": {
            "start": "2020-07-05T08:00:00Z", // Время начала статистики потребления энергии, обязательно.
            "end": "2020-07-05T09:00:00Z"   // Время окончания статистики потребления энергии, обязательно.
          }
        }
      }
    }
  }
}

Параметры ответа: PayloadObject：

Атрибут	Тип	Необязательно	Описание
state	object	N	Состояние устройства, см. подробности в [Поддерживаемые возможности устройства].

Пример ответа:

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "payload": {
      "state": {
        "power-consumption": {
          "electricityIntervals": [ // Разделено на несколько записей в зависимости от configuration.resolution
            {
              "usage": 26.5, // Значение потребления энергии, обязательно. Тип: number.
              "start": "2020-07-05T08:00:00Z", // Время начала, обязательно. Тип: date.
              "end": "2020-07-05T09:00:00Z"    // Время окончания, обязательно. Тип: date. Если интервал между end и start меньше resolution, все отчетные записи считаются недействительными.
            },
            {
              "usage": 26.5, // Значение потребления энергии, обязательно. Тип: number.
              "start": "2020-07-05T09:00:00Z", // Время начала, обязательно. Тип: date.
              "end": "2020-07-05T10:00:00Z"    // Время окончания, обязательно. Тип: date. Если интервал между end и start меньше resolution, все отчетные записи считаются недействительными.
            }
          ]
        }
      }
    }
  }
}

ConfigureDeviceCapabilities

Параметры запроса: PayloadObject：

Атрибут	Тип	Необязательно	Описание
capabilities	CapabilityObject[]	N	Список возможностей. Подробности можно посмотреть в разделе поддерживаемых возможностей устройства. Обратите внимание, поле permission нельзя изменить, при передаче синхронизации указывайте то же значение.

Пример запроса :

{
  "directive": {
    "header": {
      "name": "ConfigureDeviceCapabilities",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "endpoint": {
      "serial_number": "serial_number"
    },
    "payload": {
      "capabilities": [
        {
          "capability": "thermostat-mode-detect",
          "permission": "0110",
          "name": "temperature", // Тип детекции температуры, обязателен. Допустимые значения: humidity (влажность), temperature (температура)
          "settings": {
            "setpointRange": {
              "permission": "11",
              "type": "object",
              "value": {
                "supported": [ // Поддерживаемые настройки детекции, обязательно.
                  {
                    "name": "lowerSetpoint", // Минимальное значение, которое должна поддерживать детекция. Необходимо указать либо lowerSetpoint, либо upperSetpoint.
                    "value": { // Диапазон детекции, необязательно. Заполните, если заданы предустановленные условия.
                      "value": 68.0, // Значение температуры или влажности, обязательно.
                      "scale": "f" // Единица температуры, обязателен, если name=temperature. Варианты: c (Цельсий), f (Фаренгейт)
                    }
                  },
                  {
                    "name": "upperSetpoint", // Максимальное значение, которое должна поддерживать детекция. Необходимо указать либо lowerSetpoint, либо upperSetpoint.
                    "value": { // Диапазон детекции, необязательно. Заполните, если заданы предустановленные условия.
                      "value": 68.0, // Значение температуры или влажности, обязательно.
                      "scale": "f" // Единица температуры, обязателен, если name=temperature. Варианты: c (Цельсий), f (Фаренгейт)
                    }
                  }
                ]
              }
            },
            "supportedModes": {
              "type": "enum",
              "permission": "01",
              "values": [
                "COMFORT",
                "COLD",
                "HOT"
              ]
            }
          }
        }
      ]
    }
  }
}

Параметры ответа: PayloadObject：пустой объект Пример успешного ответа

{
  "event": {
    "header": {
      "name": "Response",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "2"
    },
    "payload": {}
  }
}

5. События, отправляемые сервером

Описание интерфейса MDN EventSource：https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events

5.1 Инструкция

Шлюз поддерживает отправку сообщений клиенту с помощью SSE (Server-sent events). Клиент может мониторить сообщения SSE после получения учетных данных доступа и разбирать содержимое push-сообщений в соответствии с протоколом уведомлений о событиях интерфейса разработки после получения сообщений, отправленных шлюзом. Следует отметить, что шлюз в настоящее время использует протокол HTTP1.1, поэтому в браузере для SSE существует ограничение максимум не более 6 соединений (Подробные инструкции см. в описании интерфейса MDN EventSource.)

5.2 Общий формат

:::советы

• URL：/open-api/V2/sse/bridge

• Метод：GET ::: Параметры запроса:

Имя	Тип	Необязательно	Описание
access_token	string	N	Токен доступа

Примечание: При запросе соединения SSE шлюз проверяет access_token, и при недействительном токене вернет ошибку аутентификации. { "error": 401, "data": {}, "message": "invalid access_token"}

## Например: Имя модуля: device Версия: 1,v2,v3 Тип сообщения: addDevice

Пример:

const evtSource = new EventSource("http://<domain name or ip address>/open-api/v2/sse/bridge?access_token=xxxxxx");

evtSource.addEventListener('device#v2#addDevice',function (event) {
  try {
    const data = JSON.parse(event.data);
    console.log('data', data);
  } catch (error) {
    console.error(`parse error`,error);
  }
}

5.3 Модуль устройства

a. Событие добавления устройства

:::tips Имя модуля：device Версия：v2 Тип сообщения：addDevice event.data параметры： :::

Имя	Тип	Необязательно	Описание
payload	ResponseDeviceObjectObject - Интерфейс такой же, как при получении списка устройств	N	Информация об устройстве

Пример:

// event.data
{
  "payload": {
    "serial_number": "ABCDEFGHIJK",
    "third_serial_number": "third_serial_number",
    "name": "Mydevice",
    "manufacturer": "SONOFF",
    "model": "BASICZBR3",
    "firmware_version": "1.1.0",
    "display_category": "switch",
    "capabilities": [
      {
        "capability": "power",
        "permission": "1100"
      },
      {
        "capability": "rssi",
        "permission": "0100"
      }
    ],
    "protocal": "zigbee",
    "state": {
      "power": {
        "powerState": "on"
      }
    },
    "tags": {
      "key": "value"
    },
    "online": true
  }
}

b. Событие обновления состояния устройства

:::tips Имя модуля：device Версия：v2 Тип сообщения：updateDeviceState event.data параметры： :::

Имя	Тип	Необязательно	Описание
endpoint	EndpointObject	N	Информация об устройстве
payload	object。 Структура такая же, как состояние устройства	N	Данные состояния устройства

EndpointObject:

Параметр	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	Y	Уникальный серийный номер стороннего устройства. Для устройств, подключенных через открытые интерфейсы, это поле обязательно.

Пример:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "power": {
      "powerState": "on"
    },
    "brightness": {
      "brightness": 100
    }
  }
}

c. Событие обновления информации об устройстве

:::tips Имя модуля：device Версия：v2 Тип сообщения：updateDeviceInfo event.data параметры： :::

Имя	Тип	Необязательно	Описание
endpoint	EndpointObject	N	Информация об устройстве
payload	DeviceChangeObject	N	Данные изменения устройства

EndpointObject:

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	Y	Уникальный серийный номер стороннего устройства. Для устройств, подключенных через открытые интерфейсы, это поле обязательно.

DeviceChangeObject

Имя	Тип	Необязательно	Описание
name	string	N	Имя устройства
capabilities	CapabilityObject []	Y	Список возможностей устройства.
теги	object	Y	тегиobject | Nullable | JSON-формат ключ-значение для пользовательской информации об устройстве.

• Может быть использовано для хранения каналов устройства.

• Может быть использовано для хранения единиц температуры.

• Для других пользовательских данных третьих сторон. |

Пример:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "name": "device name",
    "capabilities": [
      {
        "capability": "thermostat-mode-detect",
        "permission": "0110",
        "name": "temperature", // Тип детекции температуры, обязателен. Допустимые значения: humidity (влажность), temperature (температура)
        "settings": {
          "setpointRange": {
            "permission": "11",
            "type": "object",
            "value": {
              "supported": [ // Поддерживаемые настройки детекции, обязательно.
                {
                  "name": "lowerSetpoint", // Минимальное значение, которое должна поддерживать детекция. Необходимо указать либо lowerSetpoint, либо upperSetpoint.
                  "value": { // Диапазон детекции, необязательно. Заполните, если заданы предустановленные условия.
                    "value": 68.0, // Значение температуры или влажности, обязательно.
                    "scale": "f" // Единица температуры, обязателен, если name=temperature. Варианты: c (Цельсий), f (Фаренгейт)
                  }
                },
                {
                  "name": "upperSetpoint", // Максимальное значение, которое должна поддерживать детекция. Необходимо указать либо lowerSetpoint, либо upperSetpoint.
                  "value": { // Диапазон детекции, необязательно. Заполните, если заданы предустановленные условия.
                    "value": 68.0, // Значение температуры или влажности, обязательно.
                    "scale": "f" // Единица температуры, обязателен, если name=temperature. Варианты: c (Цельсий), f (Фаренгейт)
                  }
                }
              ]
            }
          },
          "supportedModes": {
            "type": "enum",
            "permission": "01",
            "values": [
              "COMFORT",
              "COLD",
              "HOT"
            ]
          }
        }
      }
    ]
  }
}

d. Событие удаления устройства

:::tips Имя модуля：device Версия：v2 Тип сообщения：deleteDevice event.data параметры： :::

** Имя **	** Тип **	** Необязательно**	** Описание **
endpoint	EndpointObject	N	Информация об устройстве

EndpointObject:

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	Y	Уникальный серийный номер стороннего устройства. Для устройств, подключенных через открытые интерфейсы, это поле обязательно.

Пример:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  }
}

e. Событие обновления онлайн-статуса устройства

:::tips Имя модуля：device Версия：v2 Тип сообщения：updateDeviceOnline event.data параметры： :::

Имя	Тип	Необязательно	Описание
endpoint	EndpointObject	N	Информация об устройстве
payload	DeviceChangeObject	N	Данные изменения устройства

EndpointObject:

Атрибут	Тип	Необязательно	Описание
serial_number	string	N	Уникальный серийный номер устройства
third_serial_number	string	Y	Уникальный серийный номер стороннего устройства. Для устройств, подключенных через открытые интерфейсы, это поле обязательно.

DeviceChangeObject

Имя	Тип	Необязательно	Описание
в сети	boolean	N	Статус онлайн устройства

Пример:

// event.data
{
  "endpoint": {
    "serial_number": "serial_number",
    "third_serial_number": "third_serial_number"
  },
  "payload": {
    "online": false
  }
}

5.4 Модуль шлюза

a. Событие обновления состояния безопасности

:::tips Имя модуля：device Версия：v2 Тип сообщения：updateDeviceOnline event.data параметры： :::

Атрибут	Тип	Необязательно	Описание
payload	SecurityStateObject	N	Информация об устройстве

SecurityStateObject

Атрибут	Тип	Необязательно	Описание
alarm_state	string	N

• arming | Включено

• disarming | Выключено |

Пример:

// event.data
{
  "payload": {
    "alarm_state": "alarming"
  }
}

5.5 Модуль безопасности

a. Событие обновления состояния постановки на охрану

:::tips Имя модуля：device Версия：v2 Тип сообщения：updateDeviceOnline event.data параметры： :::

Атрибут	Тип	Необязательно	Описание
payload	ArmStateObject	N	информация о постановке и снятии с охраны

ArmStateObject：

Атрибут	Тип	Необязательно	Описание
arm_state	string	N

• arming | Включено

• disarming | Выключено | | detail | DetailObject | N | Подробности постановки/снятия с охраны |

DetailObject：

Атрибут	Тип	Необязательно	Описание
sid	int	N	ID режима охраны
name	string	N	Название охраны

Пример

// event.data
{
  "payload": {
    "arm_state": "arming",
    "detail": {
      "sid": 1,
      "name": "Home Mode"
    }
  }
}

6. TTS (Функция движка синтеза речи (Text-to-Speech)

6.1 Инструкция

Ключевая роль

• Поставщик TTS-сервиса: поставщик сервиса движка TTS отвечает за регистрацию TTS-движка на шлюзе и предоставление TTS-услуг

• Сервер шлюза：iHost

• Клиент Gateway Open API

6.1.1 Регистрация сервиса движка TTS

1. 【Поставщик TTS-сервиса】Вызывает интерфейс для регистрации TTS-движка на шлюзе.

2. 【Сервер шлюза】После успешной регистрации шлюз сохранит базовую информацию о TTS-движке (включая адрес сервиса server_address, и последующая связь между шлюзом и поставщиком TTS-сервиса будет происходить через адрес server_address), а также выделит идентификатор сервиса TTS в пределах шлюза.

6.1.2 Получение списка синтезированных аудиофайлов

1. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка зарегистрированных TTS-сервисов. Вы можете получить текущий список зарегистрированных TTS-движков (включая идентификатор TTS-движка, выделенный шлюзом).

2. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка аудиофайлов указанного TTS-движка. Шлюз отправит синхронную команду списка аудио указанному поставщику TTS-сервиса и вернёт результат.

6.1.3 Синтез речи с указанием движка синтеза

1. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка зарегистрированных TTS-сервисов. Вы можете получить текущий список зарегистрированных TTS-движков (включая идентификатор TTS-движка, выделенный шлюзом).

2. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка аудиофайлов указанного TTS-движка. Шлюз отправит синхронную команду списка аудио указанному поставщику TTS-сервиса и вернёт результат.

6.1.4 Синтез аудио и воспроизведение TTS-речи.

1. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка зарегистрированных TTS-сервисов. Вы можете получить текущий список зарегистрированных TTS-движков (включая идентификатор TTS-движка, выделенный шлюзом).

2. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка аудиофайлов указанного TTS-движка. Шлюз отправит синхронную команду списка аудио указанному поставщику TTS-сервиса и вернёт результат. (включая адрес файла TTS-аудио)

3. 【Клиент Gateway Open API】Фиксирует адрес TTS-аудиофайла из результата, возвращённого на предыдущем шаге, вызывает интерфейс воспроизведения аудиофайла и воспроизводит его через шлюз.

6.2 Модуль TTS-движка

6.2.1 Открытые возможности шлюза

a. Получить список зарегистрированных TTS-сервисов

:::советы

• URL：/open-api/V2/rest/tts/engines

• Метод：GET

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: отсутствуют Корректный ответ с данными:

Атрибут	Тип	Необязательно	Описание
engines	EngineObject []	N	Список зарегистрированных TTS-движков

Структура EngineObject

Атрибут	Тип	Необязательно	Описание
id	string	N	Идентификатор движка, назначенный шлюзом
name	string	N	Название сервиса TS-движка

:::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK Пример ответа:： :::

{
  "error": 0,
  "data": {
    "engines": [
      {
        "id": "engine id",
        "name": "engine name"
      }
    ]
  },
  "message": "success"
}

b. Получить список аудио указанного TTS-движка

:::советы

• URL：/open-api/V2/rest/tts/engine/{id}/audio-list

• Метод：GET

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: отсутствуют Корректный ответ с данными:

Атрибут	Тип	Необязательно	Описание
audio_list	AudioObject []	N	Список аудио

Структура AudioObject

Атрибут	Тип	Необязательно	Описание
url	string	N	URL аудиофайла, например:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Метка аудиофайла

:::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK **Код ошибки: **

• 190000 Движок работает с ошибкой

Пример ответа:： :::

{
  "error": 0,
  "data": {
    "audio_list": [
      {
        "url": "адрес tts-аудио", // например: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "метка tts-аудио"
      }
    ]
  },
  "message": "success"
}

c. Выполнение синтеза речи с использованием указанного TTS-движка

:::советы

• URL：/open-api/V2/rest/tts/engine/{id}/synthesize

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
text	string	N	Текст, используемый для синтеза аудио
label	string	Y	Метка аудиофайла
language	string	Y	Прозрачное поле. Необязательный код языка для запроса синтеза речи. Конкретный список поддерживаемых кодов языков предоставляется сервисом TTS-движка. Обратите внимание, что сервис TTS-движка должен поддерживать язык по умолчанию для синтеза, что означает, что если язык не передан, будет использован язык по умолчанию движка для синтеза.
options	object	Y	Прозрачное поле. Используется для передачи конфигурационных параметров, требуемых для синтеза, сервису TTS-движка.

Корректный ответ с данными:

Атрибут	Тип	Необязательно	Описание
audio	AudioObject	N	Список аудио

Структура AudioObject

Атрибут	Тип	Необязательно	Описание
url	string	N	URL аудиофайла, например:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Метка аудиофайла

:::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK **Код ошибки: **

• 190000 Движок работает с ошибкой

Пример ответа:： :::

{
  "error": 0,
  "data": {
    "audio": {
        "url": "адрес tts-аудио" // например, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
        "label": "метка tts-аудио"
    }
  },
  "message": "success"
}

6.2.2 Взаимодействие между шлюзом и TTS-сервисом

a. Регистрация сервиса TTS-движка

Отправка запроса на шлюз от поставщика TTS-сервиса

:::советы

• URL：/open-api/V2/rest/thirdparty/event

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
event	EventObject	N	Структура объекта события запроса Информация

EventObject

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя запроса. Необязательный параметр.

• RegisterTTSEngine | | message_id | string | N | Идентификатор сообщения запроса, UUID_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

PayloadObject

Атрибут	Тип	Необязательно	Описание
service_address	string	N	Адрес сервиса. Например, http:///
name	string	N	Название сервиса

Пример запроса:

{
  "event": {
    "header": {
      "name": "RegisterTTSEngine",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
        "service_address": "service_address",
        "name": "название tts-сервиса"
    }
  }
}

**Корректные параметры ответа: **

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя заголовка ответа. Необязательный параметр:

• Ответ (Успешный ответ)

• ErrorResponse (Ошибка ответа) | | message_id | string | N | Идентификатор сообщения заголовка ответа, UUID_V4. Входящее здесь сообщение запроса: header.message_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

PayloadObject

Атрибут	Тип	Необязательно	Описание
engine_id	string	N	Идентификатор движка, назначенный шлюзом

:::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK Пример ответа:： ::: Пример корректного ответа:：

{
    "header": {
      "name": "Response",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
      "engine_id": "идентификатор движка"
    }
  }

**Параметры ненормального ответа: **

Атрибут	Тип	Необязательно	Описание
type	string	N	Тип ошибки

• INVALID_PARAMETERS (Ошибка параметров)

• AUTH_FAILURE (Ошибка аутентификации)

• INTERNAL_ERROR (Внутренняя ошибка сервиса) | | description | string | N | Описание ошибки |

Пример ответа с ошибкой:：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address не может быть пустым" 
  }
}

b. Команда синхронизации списка аудио

Отправка команды поставщику TTS-сервиса от шлюза.

:::советы

• URL：<service address>

• Метод：POST

• Заголовок：

  • Content-Type: application/json ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
directive	DirectiveObject	N	Информация о структуре объекта инструкции

DirectiveObject

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя запроса. Необязательный параметр:

• SyncTTSAudioList | | message_id | string | N | Идентификатор сообщения запроса, UUID_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

Пример запроса:

{
  "directive": {
    "header": {
      "name": "SyncTTSAudioList",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {}
  }
}

**Корректные параметры ответа: **

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя заголовка ответа. Необязательный параметр:

• Ответ (Успешный ответ)

• ErrorResponse (Ошибка ответа) | | message_id | string | N | Идентификатор сообщения заголовка ответа, UUID_V4. Входящее здесь сообщение запроса: header.message_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

PayloadObject:

Атрибут	Тип	Необязательно	Описание
audio_list	AudioObject []	N	Список TTS-аудио

Структура AudioObject

Атрибут	Тип	Необязательно	Описание
url	string	N	URL аудиофайла, например:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Метка аудиофайла

:::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK Пример ответа:： ::: Пример корректного ответа:：

{
    "header": {
      "name": "Response",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
      "audio_list": [
        {
            "url": "url tts-аудио",
            "label": "метка tts-аудио"
        }
      ]
    }
}

**Параметры ненормального ответа: **

Атрибут	Тип	Необязательно	Описание
type	string	N	Тип ошибки

• INVALID_PARAMETERS (Ошибка параметров)

• AUTH_FAILURE (Ошибка аутентификации)

• INTERNAL_ERROR (Внутренняя ошибка сервиса) | | description | string | N | Описание ошибки |

Пример ответа с ошибкой:：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address не может быть пустым" 
  }
}

c. Команда синтеза речи

Отправка команды поставщику TTS-сервиса от шлюза.

:::советы

• URL：<service address>

• Метод：POST

• Заголовок：

  • Content-Type: application/json ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
directive	DirectiveObject	N	Информация о структуре объекта инструкции

DirectiveObject

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя запроса. Необязательный параметр:

• SynthesizeSpeech | | message_id | string | N | Идентификатор сообщения запроса: UUID_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

PayloadObject

Атрибут	Тип	Необязательно	Описание
text	string	N	Текст, используемый для синтеза аудио
label	string	Y	Метка аудиофайла
language	string	Y	Прозрачное поле. Необязательный код языка для запроса синтеза речи. Конкретный список поддерживаемых кодов языков предоставляется сервисом TTS-движка. Обратите внимание, что сервис TTS-движка должен поддерживать язык по умолчанию для синтеза, что означает, что если язык не передан, будет использован язык по умолчанию движка для синтеза.
options	object	Y	Прозрачное поле. Используется для передачи конфигурационных параметров, требуемых для синтеза, сервису TTS-движка.

Пример запроса:

{
    "directive": {
        "header": {
            "name": "SynthesizeSpeech",
            "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
            "version": "1"
        },
        "payload": {
            "text": "Входной текст для синтеза.",
            "label": "метка tts-аудио"
        }
    }
}

**Корректные параметры ответа: **

Атрибут	Тип	Необязательно	Описание
header	HeaderObject	N	Структура заголовка запроса
payload	PayloadObject	N	Структура payload в запросе

HeaderObject

Атрибут	Тип	Необязательно	Описание
name	string	N	Имя заголовка ответа. Необязательный параметр:

• Ответ (Успешный ответ)

• ErrorResponse (Ошибка ответа) | | message_id | string | N | Идентификатор сообщения заголовка ответа, UUID_V4. Входящее здесь сообщение запроса: header.message_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

PayloadObject

Атрибут	Тип	Необязательно	Описание
audio	AudioObject	N	TTS-аудио

Структура AudioObject

Атрибут	Тип	Необязательно	Описание
url	string	N	URL аудиофайла, например:
https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3
label	string	Y	Метка аудиофайла

:::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK Пример ответа:： ::: Пример корректного ответа:：

{
    "header": {
      "name": "Response",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
      "audio": {
        "url": "url tts-аудио",
        "label": "метка tts-аудио"
      }
    }
}

**Параметры ненормального ответа: **

Атрибут	Тип	Необязательно	Описание
type	string	N	Тип ошибки

• INVALID_PARAMETERS (Ошибка параметров)

• AUTH_FAILURE (Ошибка аутентификации)

• INTERNAL_ERROR (Внутренняя ошибка сервиса) | | description | string | N | Описание ошибки |

Пример ответа с ошибкой:：

{
  "header": {
    "name": "ErrorResponse",
    "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
    "version": "1"
  },
  "payload": {
    "type": "INVALID_PARAMETERS",
    "description": "service_address не может быть пустым" 
  }
}

7. Модуль мультимедиа

7.1 Воспроизведение аудиофайла

:::советы

• URL：/open-api/V2/rest/media/audio-player

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
audio_url	string	N	Адрес URL аудио

Корректный ответ с данными: :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. **Код состояния: **200 OK Пример ответа:： :::

{
  "error": 0,
  "data": {},
  "message": "success"
}

8. Пользовательская UI-карта

Пользовательские UI-карты позволяют отображать любое содержимое внутри карты. Это содержимое может быть веб-страницей, изображением или любым сервисом с пользовательским интерфейсом. Вам нужно лишь предоставить URL содержимого, которое вы хотите отобразить. UI-карта автоматически подстроит ширину и высоту, а содержимое будет отображаться с помощью iFrame.

8.1 Инструкция

Ключевая роль

• Поставщик UI-сервиса: Поставщик, отвечающий за создание пользовательских UI-карт на шлюзе.

• Сервер шлюза: Сервер шлюза (iHost).

• Клиент Gateway Open API: Клиент Open API для шлюза.

8.1.1 Создание пользовательской UI-карты

• [Поставщик UI-сервиса]: Вызывает API для создания пользовательской UI-карты на шлюзе.

• [Сервер шлюза]: После успешной регистрации шлюз сохраняет базовую информацию о UI-карте (включая конфигурацию размера и URL ресурса карты) и присваивает внутренний идентификатор UI-карты в пределах шлюза.

8.1.2 Получение списка UI-карт

• [Поставщик UI-сервиса]: Вызывает API для получения списка UI-карт.

• [Сервер шлюза]: Возвращает список UI-карт, сохранённых на шлюзе, включая пользовательские UI-карты, не созданные вызывающей стороной.

8.1.3 Изменение конфигурации указанной UI-карты

• [Поставщик UI-сервиса]: Вызывает API для изменения конфигурации указанной UI-карты, например конфигурации размера и URL ресурса.

• [Сервер шлюза]: После успешного изменения шлюз сохраняет обновлённую информацию о UI-карте, включая новую конфигурацию размера и URL ресурса.

8.1.4 Удаление пользовательской UI-карты

1. [Поставщик UI-сервиса]: Вызывает API для удаления указанной пользовательской UI-карты.

2. [Сервер шлюза]: Шлюз удалит всю информацию, связанную с указанной UI-картой.

8.2 Модуль пользовательских UI-карт

8.2.1 Создание пользовательской UI-карты

Поставщик UI-сервиса отправляет запрос на шлюз для создания пользовательской UI-карты.

:::советы

• URL：/open-api/v2/rest/ui/cards

• Метод：POST

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
label	string	Y	Метка карты: используется для описания карты. Это псевдоним карты.
cast_settings	CastSettingsObject	Y	Настройки Cast-карты: конфигурационные параметры для cast-карт.
web_settings	WebSettingsObject	N	Настройки Web-карты: конфигурационные параметры для web-карт.

CastSettingsObject:

Атрибут	Тип	Необязательно	Описание
dimensions	DimensionObject []	N	Конфигурация размеров: должна включать по крайней мере одну конфигурацию.
default	string	N	Спецификация по умолчанию: используется стандартная конфигурация размера, необязательные параметры: 2x2

WebSettingsObject:

Атрибут	Тип	Необязательно	Описание
dimensions	DimensionObject []	N	Конфигурация размеров: должна включать по крайней мере одну конфигурацию.
drawer_component	DrawerObject	Y	Настройки отображения компонента drawer.
default	string	N	Спецификация по умолчанию:

• 1x1

• 2x1 |

DimensionObject:

Атрибут	Тип	Необязательно	Описание
src	string	N	URL ресурса: например: http://example.html
size	string	N	Спецификации размера:
Необязательные параметры CastSettingsObject:

• 2×2

Необязательные параметры WebSettingsObject:

• 1x1

• 2x1 |

DrawerObject:

Атрибут	Тип	Необязательно	Описание
src	string	N	URL ресурса: например: http://example.html

Успешный ответ с данными:

Атрибут	Тип	Необязательно	Описание
id	string	N	Уникальный идентификатор UI-карты

:::советы Условия: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. **Код состояния: ** 200 OK ::: Пример запроса：

{
  "label": "ewelink cube card",
  "cast_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×2"
      }
    ],
    "default": "2×2"
  },
  "web_settings": {
    "dimensions": [
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "2×1"
      },
      {
        "src": "https://ewelink.cc/ewelink-cube/",
        "size": "1×1"
      }
    ],
    "drawer_component": {
      "src": "https://ewelink.cc/ewelink-cube/"
    },
    "default": "2×1"
  }
}

Пример ответа:

{
  "error": 0,
  "data": {
    "id": "72cc5a4a-f486-4287-857f-b482d7818b16"
  },
  "message": "success"
}

8.2.2 Получение списка UI-карт

:::советы

• URL：/open-api/v2/rest/ui/cards

• Метод：GET

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: отсутствуют Параметры ответа:

Атрибут	Тип	Необязательно	Описание
data	CardObject[]	N	Список UI-карт

Объект CardObjec:

Атрибут	Тип	Необязательно	Описание
id	string	N	ID карты: уникальный идентификатор карты.
label	string	Y	Метка карты: используется для описания карты. Служит псевдонимом или названием карты.
cast_settings	CastSettingsObject	Y	Метка карты: используется для описания карты. Это псевдоним карты.
web_settings	WebSettingsObject	N	Настройки Cast-карты: конфигурационные параметры для cast-карт.
app_name	string	Y	Настройки Web-карты: конфигурационные параметры для web-карт.

CastSettingsObject:

Атрибут	Тип	Необязательно	Описание
dimensions	DimensionObject []	N	Конфигурация размеров: должна включать по крайней мере одну конфигурацию.
default	string	N	Спецификация по умолчанию:
Необязательный параметр: 2x2
used	string	N	Текущая спецификация:
Необязательный параметр: 2x2

WebSettingsObject:

Атрибут	Тип	Необязательно	Описание
dimensions	DimensionObject []	N	Конфигурация размеров: должна включать по крайней мере одну конфигурацию.
drawer_component	DrawerObject	Y	Настройки отображения компонента drawer.
default	string	N	Спецификация по умолчанию:
Необязательный параметр:

• 1x1

• 2x1 | | used | string | N | Текущая спецификация: Необязательный параметр:

• 1x1

• 2x1 |

DimensionObject:

Атрибут	Тип	Необязательно	Описание
src	string	N	URL ресурса: например: http://example.html
size	string	N	Спецификации размера:
Необязательный параметр:

• 1x1

• 2x1

Примечание: В настоящее время cast-карты поддерживают только спецификацию 2x2. Спецификация 2x2 не будет действовать. |

DrawerObject:

Атрибут	Тип	Необязательно	Описание
src	string	N	URL ресурса: например: http://example.html

Пример ответа:

{
  "error": 0,
  "data": [
    {
      "id": "72cc5a4a-f486-4287-857f-b482d7818b16",
      "label": "ewelink cube card",
      "cast_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×2"
          }
        ],
        "default": "2×2",
        "used": "2×2"
      },
      "web_settings": {
        "dimensions": [
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "2×1"
          },
          {
            "src": "https://ewelink.cc/ewelink-cube/",
            "size": "1×1"
          }
        ],
        "drawer_component": {
          "src": "https://ewelink.cc/ewelink-cube/"
        },
        "default": "2×1",
        "used": "2×1"
      },
      "appName": "ewelink-cube"
    }
  ],
  "message": "success"
}

8.2.3 Изменение конфигурации указанной UI-карты

Авторизованные пользователи могут изменить конфигурацию существующей UI-карты через этот интерфейс. Поставщики сервисов пользовательских карт могут изменять только UI-карты, которые они создали.

:::советы

• URL：/open-api/v2/rest/ui/cards/{id}

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательно	Описание
label	string	Y	Используется для описания карты. Это псевдоним карты.
cast_settings	CastSettingsObject	Y	Настройки Cast-карты
web_settings	WebSettingsObject	Y	Настройки Web-карты

CastSettingsObject:

Атрибут	Тип	Необязательно	Описание
used	string	Y, Либо used или src должен быть предоставлен, но требуется как минимум один из этих параметров.	Текущая спецификация:
Необязательный параметр:

• 2x2

| | src | string | Y, Либо used или src должен быть предоставлен, но требуется как минимум один из этих параметров. | URL ресурса: http://example.html |

WebSettingsObject:

Атрибут	Тип	Необязательно	Описание
used	string	Y, Либо used или src должен быть предоставлен, но требуется как минимум один из этих параметров.	Текущая спецификация:
Необязательный параметр:

• 1x1

• 2x1 | | src | string | Y, Либо used или src должен быть предоставлен, но требуется как минимум один из этих параметров. | URL ресурса: http://example.html |

Успешный ответ с данными: :::tips Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. UI-карта, которую изменяют, должна быть создана поставщиком пользовательских UI-карт, вызывающим интерфейс. **Код состояния: ** 200 OK Код ошибки:

• 406: Нет разрешения на доступ к этому ресурсу ::: **Пример ответа: **

{
  "error": 0,
  "data": {},
  "message": "success"
}

**Пример запроса: **

{
  "cast_settings": {
    "used": "2×2"
  },
  "web_settings": {
    "used": "1×1"
  }
}

8.2.4 Удаление пользовательской UI-карты

Авторизованные пользователи имеют право удалять существующую UI-карту с помощью этого интерфейса. Поставщики пользовательских карт могут удалять только UI-карты, которые они создали.

:::советы

• URL：/open-api/v2/rest/ui/cards/{id}

• Метод：DELETE

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: отсутствуют Успешный ответ с данными: :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. UI-карта, которую изменяют, должна быть создана поставщиком пользовательских UI-карт, вызывающим интерфейс. **Код состояния: ** 200 OK Код ошибки:

• 406: Нет разрешения на доступ к этому ресурсу. ::: **Пример ответа: **

{
  "error": 0,
  "data": {},
  "message": "success"
}