Руководство для разработчиков и 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 Категория отображения устройства и возможности

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

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

  • 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 Extended Format): 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. Токен доступа

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

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

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

:::tips

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

• Метод：GET

• Заголовок：

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

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

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

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

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

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

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

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

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

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

• 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	Единица измерения температуры CPU:
Необязательный
values:'c', 'f'
sd_card_used	int	Y	Использование SD-карты (в процентах):
Диапазон:[0-100] с точностью до одного знака после запятой
*Примечание: если SD-карта не вставлена или не отформатирована, значение пустое.

:::tips Условия: Параметры запроса корректны, и проверка идентичности пользователя пройдена. **Код состояния: **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. Настройка шлюза

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

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

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

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

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

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

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

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

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

• 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	Название устройства

Успешный ответ с данными: пустой объект {} :::tips Условия: Нет **Код состояния: **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)

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

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

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

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

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

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

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

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

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

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

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

g. Отмена тревоги на шлюзе

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

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

• Метод：PUT

• Заголовок：

  • Content-Type: application/json

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

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

3.2 Аппаратные функции

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

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

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

• Метод：POST

• Заголовок：

  • Content-Type: application/json

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

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

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

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

• 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]

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

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

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

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

Тип устройства	Значение	Версия iHost
Розетка (Plug)	plug	≥ 2.1.0
Выключатель (Switch)	switch	≥ 2.1.0
Свет (Light)	light	≥ 2.1.0
Штора (Curtain)	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)	fanLight	≥ 2.1.0
Кондиционер (AirConditioner)	airConditioner	≥ 2.1.0
Вентилятор (Fan)	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, // Включена ли функция inching. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка инерционного переключателя. **Тип:** String. Обязательно. "off" (питание выкл), "on" (питание вкл)
              "delay": 1000, // Время задержки inching в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            },
            "2": { // Название компонента
              "enable": true, // Включена ли функция inching. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка инерционного переключателя. **Тип:** String. Обязательно. "off" (питание выкл), "on" (питание вкл)
              "delay": 1000, // Время задержки inching в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            },
            "3": { // Название компонента
              "enable": true, // Включена ли функция inching. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка инерционного переключателя. **Тип:** String. Обязательно. "off" (питание выкл), "on" (питание вкл)
              "delay": 1000, // Время задержки inching в миллисекундах. **Тип:** Integer. Обязательно.
              "min_delay": 500, // Минимальное время задержки
              "max_delay": 100000 // Максимальное время задержки
            },
            "4": { // Название компонента
              "enable": true, // Включена ли функция inching. **Тип:** Boolean. Обязательно.
              "inchingSwitch": "off", // Настройка инерционного переключателя. **Тип:** String. Обязательно. "off" (питание выкл), "on" (питание вкл)
              "delay": 1000, // Время задержки inching в миллисекундах. **Тип:** 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 name] :{
            "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": { // Настройка включения функции inч
      "permission": "11",
      "type": "boolean",
      "value": false
    },
    "inchingSwitch": { // Настройка действия inch
      "type": "enum",
      "permission": "11",
      "value": "on",
      "values": ["on", "off"]
    },
    "inchingDelay": { // Настройка времени inch
      "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 // Концентрация углекислого газа. **Тип:** 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 // Результат обнаружения. **Тип:** Булево. `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 // Результат обнаружения. **Тип:** Булево. `true` означает обнаружение, `false` — отсутствие обнаружения.
}

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

Блокировка от детей (child-lock)

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

Режим ECO (eco)

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

{
  "startup": "on" // **Тип:** Строка. Варианты: `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` указывает состояние удержания обнаружения. **Тип:** Строка. `on` означает активное удержание обнаружения, `off` — неактивное.
}

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

Обнаружение тока подкомпонента (toggle-electric-current)

Пример декларации возможности:

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

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

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

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

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

Обнаружение мощности подкомпонента (toggle-electric-power)

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

[
  {
    "capability": "toggle-power-consumption",
    "permission": "1101",
    "name": "1", // Имя компонента. **Тип:** Строка. Необязательные значения: "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, // Запуск или остановка статистики в реальном времени. **Тип:** Булево. Обязательно.
  "timeRange": { // Временной диапазон для сводки. Обязательно.
    "start": "2020-07-05T08:00:00Z", // Время начала учета потребления мощности. **Тип:** Строка. Обязательно.
    "end": "2020-07-05T09:00:00Z" // Время окончания учета потребления мощности. **Тип:** Строка. Обязательно.
  }
}

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

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

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

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

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

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

{
  "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` представляет индикатор качества связи. **Тип:** Число. Диапазон значений: 0–255.
}

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

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

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

Пример декларации возможности:

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

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

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

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

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

Система (system)

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

Осадки (rainfall)

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

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

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

Пример декларации возможности:

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

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

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

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

{
  "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, // Текущий объем орошения. **Тип:** Число. Необязательно. **Единица:** L.
  "start": "2020-07-05T08:00:00Z", // Время начала орошения. **Тип:** Дата. Необязательно.
  "end": "2020-07-05T09:00:00Z", // Время окончания орошения. **Тип:** Дата. Необязательно.
  "dailyVolume": 20 // Суточный объем орошения. **Тип:** Число. Необязательно. **Единица:** L.
}

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

Отчет о состоянии работы:

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

Запрос состояния работы:

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

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

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

Режим работы орошения (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" // Режим работы орошения. **Тип:** Строка. Необязательно. Значения должны быть из `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", // Режим полива. **Тип:** Строка. Обязательно. Варианты: "volume", "time".
  "action": {
    "perDuration": 60, // Продолжительность каждого цикла полива. **Тип:** Число. Обязательно.
    "intervalDuration": 20, // Интервал между циклами полива. **Тип:** Число. Обязательно.
    "count": 3 // Количество циклов полива. **Тип:** Число. Обязательно.
  }
}

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

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

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

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

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

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

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

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

**Имена режимов **	**Необязательные значения **
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": {
        '1': 'Chanel1',
        '2': 'Chanel2',
        '3': 'Chanel3',
        '4': 'Chanel4',
    },
}

• Специальный ключ 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

Успешный ответ с данными: пустой объект {} :::tips Условия: Параметры запроса корректны, и проверка идентичности пользователя пройдена. **Код состояния: ** 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 включают только возможности потока камеры.
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	Уникальный серийный номер устройства

:::tips Условия: Параметры запроса корректны, и проверка идентичности пользователя пройдена. **Код состояния: **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": "camera ip access failed" 
}

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 💡Примечание: Пожалуйста, проверьте примеры поддерживаемых возможностей устройства в разделе [Supported Device Capabilities].

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

:::tips Условия: Параметры запроса корректны, и проверка идентичности пользователя пройдена. **Код состояния: **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	Объект состояния устройства. Для примеров состояний разных возможностей, пожалуйста, проверьте [Support Device Capabilities]
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

  • Авторизация: Bearer ::: Параметры запроса:

Атрибут	Тип	Необязательный	Описание
name	string	Y	Имя устройства.
теги	object	Y	Пары ключ-значение в формате JSON, используемые для хранения имён каналов устройства и другой информации о суб-устройствах.
state	object	Y	Изменить состояние устройства; для деталей протокола смотрите "Supported Device Capabilities."
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	Запрашивает состояние устройства; для деталей протокола смотрите "Supported Device Capabilities."

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 Отключено |

:::tips Условия: Параметры запроса корректны, и проверка идентичности пользователя пройдена. **Код состояния: **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.0.jpg

Доступ стороннего шлюза

2.0.jpg

Шаги доступа

1. Определите классификацию устройства в шлюзе. Подробности смотрите в [Supported Device Type].

2. Определите возможности, к которым устройство может получить доступ. Подробности смотрите в [Supported Device Capabilities].

3. Вызовите интерфейс [Discovery Request], чтобы добавить устройство в шлюз.

   1. Внимание: Вам необходимо предоставить адрес сервиса для получения инструкций, отправленных шлюзом, который используется для получения команд управления устройством, выданных шлюзом.

4. Если состояние стороннего устройства изменится, вам нужно вызвать интерфейс [Device States Change Report], чтобы отправить шлюзу последнее состояние.

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

• Выберите соответствующую категорию устройства. Классификация повлияет на итоговое отображение в интерфейсе после подключения устройства к шлюзу.

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

Процесс программирования

a. Доступ устройства

3.0.jpg

b. Доступ стороннего шлюза

4.0.jpg

4.2 Пример доступа

Выключатель, розетка

Синхронизировать сторонние устройства

// Запрос
URL：/open-api/v2/rest/thirdparty/event
Метод：POST
Заголовок：
  Content-Type: application/json
  Авторизация: 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": "serial number"
      }
    ]
  }
}

Отчёт о состоянии устройства

URL：/open-api/V2/rest/thirdparty/event
Метод：POST
Заголовок：
  Content-Type: application/json
  Авторизация: 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
  Авторизация: Bearer  <token>
Тело: нет

{
  "error": 0,
  "data": {
    "device_list": [
      {
        "serial_number": "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. Последующие изменения онлайн полностью зависят от синхронизации со сторонним сервисом через интерфейс DeviceOnlineChangeReport.

Параметры запроса: EndpointObject**：**Нет PayloadObject：

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

EndpointObject:

Атрибут	Тип	Необязательный	Описание
third_serial_number	string	N	Уникальный серийный номер стороннего устройства
name	string	N	Название устройства
display_category	string	N	Категория устройства. Подробности см. в [Supported Device Type]. *Сторонние устройства пока не поддерживают добавление камер.
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": "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	Состояние устройства, подробности см. в [Supported device cabilities]

Пример запроса :

{
  "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

| object

| 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: Код клавиши пульта не обучен |

:::tips Условия: Параметры запроса корректны. **Код состояния: **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	Состояние устройства, подробности см. в [Supported device cabilities].

Пример запроса :

{
  "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	Состояние устройства, подробности см. в [Supported device cabilities].

Пример запроса :

{
  "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	Состояние устройства, подробности см. в [Supported device cabilities].

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

{
  "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 Общий формат

:::tips

• 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 - Интерфейс такой же, как у Get Device List	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), и выделит ID сервиса движка TTS внутри шлюза.

image.png

6.1.2 Получение списка синтезированных аудиофайлов

1. 【Клиент Gateway Open API】Вызвать интерфейс для получения списка зарегистрированных сервисов движков TTS. Можно получить текущий список зарегистрированных движков TTS (включая ID движка TTS, выделенный шлюзом).

2. 【Клиент Gateway Open API】Вызвать интерфейс для получения списка аудио у указанного движка TTS. Шлюз отправит синхронную команду получения списка аудио указанному поставщику TTS и вернёт результат.

image.png

6.1.3 Синтез речи с указанием движка синтеза

1. 【Клиент Gateway Open API】Вызвать интерфейс для получения списка зарегистрированных сервисов движков TTS. Можно получить текущий список зарегистрированных движков TTS (включая ID движка TTS, выделенный шлюзом).

2. 【Клиент Gateway Open API】Вызвать интерфейс для получения списка аудио у указанного движка TTS. Шлюз отправит синхронную команду получения списка аудио указанному поставщику TTS и вернёт результат.

image.png

6.1.4 Синтезировать аудио и воспроизвести TTS-говорение.

1. 【Клиент Gateway Open API】Вызвать интерфейс для получения списка зарегистрированных сервисов движков TTS. Можно получить текущий список зарегистрированных движков TTS (включая ID движка TTS, выделенный шлюзом).

2. 【Клиент Gateway Open API】Вызвать интерфейс для получения списка аудио указанного движка TTS. Шлюз отправит синхронную команду получения списка аудио указанному поставщику TTS и вернёт результат. (включая адрес TTS-аудиофайла)

3. 【Клиент Gateway Open API】Сохранить адрес TTS-аудиофайла из результата, возвращённого на предыдущем шаге, вызвать интерфейс воспроизведения аудиофайла и воспроизвести его через шлюз.

6.2 Модуль движка TTS

6.2.1 Открытые возможности шлюза

a. Получить список зарегистрированных сервисов движков TTS

:::tips

• URL：/open-api/V2/rest/tts/engines

• Метод：GET

• Заголовок：

  • Content-Type: application/json

  • Authorization: Bearer ::: Параметры запроса: отсутствуют Корректный ответ с данными:

Атрибут	Тип	Необязательный	Описание
engines	EngineObject []	N	Список зарегистрированных движков TTS

Структура EngineObject

Атрибут	Тип	Необязательный	Описание
id	string	N	ID движка, назначенный шлюзом
name	string	N	Название сервиса движка TTS

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

{
  "error": 0,
  "data": {
    "engines": [
      {
        "id": "id движка",
        "name": "название движка"
      }
    ]
  },
  "message": "success"
}

b. Получить список аудио указанного движка TTS

:::tips

• 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

:::tips

• 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-сервиса

:::tips

• 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 | ID сообщения запроса, 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 | ID сообщения заголовка ответа, UUID_V4. Входящий здесь ID запроса: header.message_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 |

PayloadObject

Атрибут	Тип	Необязательный	Описание
engine_id	string	N	ID движка, назначенный шлюзом

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

{
    "header": {
      "name": "Response",
      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",
      "version": "1"
    },
    "payload": {
      "engine_id": "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-сервиса от шлюза.

:::tips

• URL：<адрес сервиса>

• Метод：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 | ID сообщения запроса, 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 | ID сообщения заголовка ответа, UUID_V4. Входящий здесь ID запроса: 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-сервиса от шлюза.

:::tips

• URL：<адрес сервиса>

• Метод：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 | ID сообщения запроса: 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 | ID сообщения заголовка ответа, UUID_V4. Входящий здесь ID запроса: 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 Воспроизведение аудиофайла

:::tips

• 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-карты позволяют отображать внутри карты любое содержимое. Это содержимое может быть веб-страницей, изображением или любым сервисом с UI. Вам нужно предоставить URL содержимого, которое вы хотите отобразить. UI-карта автоматически адаптирует свою ширину и высоту, а содержимое будет отображаться с помощью iFrame.

8.1 Инструкция

Ключевая роль

• Поставщик UI-сервиса: Провайдер, ответственный за создание пользовательских UI-карт на шлюзе.

• Сервер шлюза: Сервер шлюза (iHost).

• Клиент Gateway Open API: Клиент Open API для шлюза.

8.1.1 Создание пользовательской UI-карты

• [Поставщик UI-сервиса]: Вызывает API для создания пользовательской UI-карты на шлюзе.

• [Сервер шлюза]: После успешной регистрации шлюз сохраняет базовую информацию UI-карты (включая конфигурацию размера и URL ресурса карты) и назначает внутренний ID UI-карты внутри шлюза.

image.png

8.1.2 Получение списка UI-карт

• [Поставщик UI-сервиса]: Вызывает API для получения списка UI-карт.

• [Сервер шлюза]: Возвращает список UI-карт, сохранённых на шлюзе, включая пользовательские UI-карты, не созданные вызывающей стороной.

image.png

8.1.3 Изменение конфигурации указанной UI-карты

• [Поставщик UI-сервиса]: Вызывает API для изменения конфигурации указанной UI-карты, такой как конфигурация размеров и URL ресурса.

• [Сервер шлюза]: После успешного изменения шлюз сохраняет обновлённую информацию UI-карты, включая новую конфигурацию размеров и URL ресурса.

image.png

8.1.4 Удаление пользовательской UI-карты

1. [Поставщик UI-сервиса]: Вызывает API для удаления указанной пользовательской UI-карты.

2. [Сервер шлюза]: Шлюз удалит всю информацию, связанную с указанной UI-картой.

image.png

8.2 Модуль пользовательских UI-карт

8.2.1 Создание пользовательской UI-карты

Поставщик UI-сервиса отправляет запрос на шлюз для создания пользовательской UI-карты.

:::tips

• 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	Уникальный ID UI-карты

:::tips Условия: Параметры запроса корректны, и проверка идентичности пользователя пройдена. **Код состояния: ** 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-карт

:::tips

• 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-карты, которые они создали.

:::tips

• 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-карты, которые они создали.

:::tips

• 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"
}