# Разработчикам и руководство по API ## 1. Начало использования ### 1.1 Подготовка Шаг 1. Пожалуйста, убедитесь, что шлюз включен и работает правильно. Шаг 2. Убедитесь, что шлюз и ПК подключены к одной локальной сети. Затем введите URL CUBE в вашем браузере. Примечание: Если у вас несколько шлюзов, вы можете получить соответствующий IP-адрес для доступа к указанному шлюзу одним из двух способов ниже. 1. Войдите в настройки вашего беспроводного роутера и проверьте IP-адрес шлюза в DHCP. 2. CUBE поддерживает локальное обнаружение через mDNS. ### 1.2 Начало работы * Вызовите интерфейс \[Access Token] и получите ответ с ошибкой, предлагающий нажать <**Готово**>. Обратите внимание, что после нажатия доступ к интерфейсу действителен не более 5 минут. ```json // Запрос curl --location --request GET 'http:///open-api/V2/rest/bridge/access_token' --header 'Content-Type: application/json' // Ответ { "error": 401, "data": {}, "message": "link button not pressed" } ``` * Нажмите <**Готово**> и вызовите интерфейс \[Access Token] снова. Ответ успешный, и токен получен. ```json // Запрос curl --location --request GET 'http:///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]. Ответ успешный, и список устройств получен. ```json // Запрос curl --location --request GET 'http:///open-api/V2/rest/devices' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer 376310da-7adf-4521-b18c-5e0752cfff8d' // Ответ { "error": 0, "data": { "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "device name", "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] } "message": "success" } ``` * Метод получения токена доступа CUBE: после вызова интерфейса \[Access Token] на странице веб-консоли CUBE появляется глобальное всплывающее окно с просьбой пользователя подтвердить получение учетных данных для вызова интерфейса. * Примечание: Если вы откроете более одной страницы веб-консоли CUBE, окно подтверждения появится одновременно на нескольких страницах веб-консоли, и окна на других страницах закроются после нажатия подтверждения на одной из страниц. ## 2. Основная концепция ### 2.1 Адрес интерфейса разработки Веб-API интерфейс шлюза имеет два способа доступа (по IP или по доменному имени), обычно корневой путь /open-api/V2/rest/< specific function module > // Доступ по IP http\:///open-api/V2/rest/bridge // Доступ по доменному имени http\:///open-api/V2/rest/bridge ### 2.2 Категория отображения устройства и параметры (Capabilities) * \*\*Категория отображения устройства (DisplayCategory). \*\*Категория отображения устройства используется для идентификации конкретных категорий устройства, таких как switch, plug, light и т.д. **Эта информация определяет отображение устройства в пользовательском интерфейсе шлюза**. * \*\*Возможности устройства (Device Capability). \*\*Возможности устройства описывают конкретные подфункции устройства. Например, управление питанием, управление яркостью, управление цветовой температурой и т.д. **Одно устройство может поддерживать 1 или более возможностей**. * **capability:** Описывает имя возможности, которое должно быть глобально уникальным и строкового типа. Несколько английских слов следует разделять дефисом ("-"). Например: `"thermostat-target-setpoint"`. * **name:** Описывает категорию внутри возможности, также строкового типа. Несколько английских слов следует разделять дефисом ("-"). Например: `"auto-mode"`, `"manual-mode"`. * **permission:** Описывает права, связанные с возможностью. Тип — строка, форматируется в виде кода 8421 в двоичном представлении. Примеры включают: * Управляемое устройство: `"1000"` * Конфигурируемое устройство: `"0010"` * Устройство, управляемое и конфигурируемое: `"1010"` * Устройство, управляемое и отчитывающееся: `"1100"` Значение каждого бита, слева направо (с правого на левый), следующее: ⅰ. Бит 0: Разрешает опрос устройства ⅱ. Бит 1: Разрешает настройку устройства ⅲ. Бит 2: Разрешает устройству отправлять отчетные данные ⅳ. Бит 3: Разрешает управление устройством ```javascript 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` поле необязательно. | ```javascript // 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](https://en.wikipedia.org/wiki/Double-precision_floating-point_format) | | int | Целочисленный тип данных. | | object | Тип объекта. Объект, совместимый с JSON | | string\[] | Массив строк | | int\[] | Массив целых чисел | | object\[] | Массив объектов | | bool | Логический тип | | date | Строка времени. Строка в формате ISO (ISO 8601 расширенный формат): YYYY-MM-DDTHH:mm:ss.sssZ. Часовой пояс всегда UTC (координированное всемирное время), обозначается суффиксом "Z". | ### Общие результаты ответа | Атрибут | Тип | Необязательно | Описание | | ------------------------------------------------------------------------ | ------ | ------------- | ------------------ | | error | int | N | Код ошибки: | | 0: Успех | | | | | 400: Ошибка параметра | | | | | 401: Аутентификация не удалась | | | | | 500: Исключение сервера | | | | | data | object | N | Тело данных ответа | | message | string | N | Описание ответа: | | Когда error равно 0, содержимое — success | | | | | Когда error не равно 0, это непустая строка, содержащая описание ошибки. | | | | **Пример ответа**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` ```json { "error": 400, "data": {}, "message": "invalid parameters" } ``` ### Список ресурсов | Тип | Описание | | -------------------- | --------------------------------- | | Поддерживаемые звуки | - alert1 (Звук сигнала тревоги 1) | * alert2 (Звук сигнала тревоги 2) * alert3 (Звук сигнала тревоги 3) * alert4 (Звук сигнала тревоги 4) * alert5 (Звук сигнала тревоги 5) * doorbell1 (Звонок 1) * doorbell2 (Звонок 2) * doorbell3 (Звонок 3) * doorbell4 (Звонок 4) * doorbell5 (Звонок 5) * alarm1 (Сигнал тревоги 1) * alarm2 (Сигнал тревоги 2) * alarm3 (Сигнал тревоги 3) * alarm4 (Сигнал тревоги 4) * alarm5 (Сигнал тревоги 5) | | Поддерживаемые deep | - bootComplete (Загрузка системы завершена) * networkConnected (Сеть подключена) * networkDisconnected (Сеть отключена) * systemShutdown (Выключение системы) -deviceDiscovered (Обнаружено устройство) * system Armed (Система поставлена на охрану) * system Disarmed (Система снята с охраны) * factoryReset (Сброс устройства до заводских настроек) | ### 3.1 Функции шлюза #### a. Токен доступа Позволяет пользователям получить токен доступа. * Примечание: Токен будет очищен после сброса устройства. * Примечание: После получения токена необходимо снова нажать кнопку, чтобы успешно получить новый токен. :::советы * **URL**：`/open-api/V2/rest/bridge/access_token` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ----------------------------- | | app\_name | string | Y | Описание названия приложения. | Успешный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ------------------------------------------------------------------------------------- | | token | string | N | Токен доступа интерфейса. Он действителен длительное время, пожалуйста, сохраните его | | app\_name | string | Y | Описание названия приложения. | :::советы **Условие**: Пользователь активировал < command key > и обратился к этому интерфейсу в пределах допустимого времени. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": { "token": "376310da-7adf-4521-b18c-5e0752cfff8d" }, "message": "success" } ``` Данные ответа при отказе：пустой объект :::советы **Условия**：Пользователь не активировал < command key >, или время действия истекло. \*\*Код состояния: \*\* `200 OK` ::: **Пример ответа**: ```json { "error": 401, "data": {}, "message": "link button not pressed" } ``` #### b. Получение состояния шлюза Позволяет авторизованным пользователям получить состояние шлюза через этот интерфейс :::советы * **URL**：`/open-api/V2/rest/bridge/runtime` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------------------------------------------------------------------------- | ------- | ----------------- | -------------------------------------------------- | | ram\_used | int | N | Процент использования оперативной памяти. \[0-100] | | cpu\_used | int | N | Процент использования ЦП. \[0-100] | | power\_up\_time | date | N | Время последнего включения питания | | cpu\_temp | int | N | Температура ЦП: | | Единица: Цельсий | | | | | cpu\_temp\_unit | string | N | Единица температуры ЦП: | | Необязательно | | | | | значения:`'c'`, `'f'` | | | | | sd\_card\_used | int | Y | Использование SD-карты (в процентах): | | Диапазон:`[0-100]` с точностью до одного знака после запятой | | | | | \*Примечание: Если SD-карта не вставлена или не отформатирована, значение пусто. | | | | :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": { "ram_used": 40, "cpu_used": 30, "power_up_time": "2022-10-12T02:58:09.989Z", "cpu_temp": 51, "cpu_temp_unit": "c", "sd_card_used" : "12" }, "message": "success" } ``` #### c. Настройка шлюза Позволяет авторизованным пользователям настраивать шлюз через этот интерфейс :::советы * **URL**：`/open-api/V2/rest/bridge/config` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | --------------------------- | | volume | int | Y | Громкость системы. \[0-100] | Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Получение информации о шлюзе Позволяет авторизованным пользователям получить информацию о шлюзе через этот интерфейс :::советы * **URL**：`/open-api/V2/rest/bridge` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ------------------- | | ip | string | N | IP-адрес | | mac | string | N | MAC-адрес | | domain | string | Y | Домен сервиса шлюза | | fw\_version | string | N | Версия прошивки | | name | string | N | Название устройства | Успешный ответ с данными: пустой объект {} :::советы **Условия**: Нет \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": { "ip": "192.168.31.25", "mac": "00:0A:02:0B:03:0C", "domain": "ihost.local", "fw_version": "1.9.0", "name": "iHost" }, "message": "success" } ``` #### e. Отключение звука у шлюза (Mute) Позволяет авторизованным пользователям отключать звук на шлюзе через этот интерфейс. :::советы * **URL**：`/open-api/v2/rest/bridge/mute` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### f. Включение звука у шлюза (Unmute) Позволяет авторизованным пользователям включать звук на шлюзе через этот интерфейс.\ :::советы * **URL**：`/open-api/v2/rest/bridge/unmute` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### g. Отключение будильника шлюза Позволяет авторизованным пользователям отключать состояние звуковой тревоги на шлюзе через этот интерфейс. :::советы * **URL**：`/open-api/v2/rest/bridge/cancel_alarm` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.2 Функции аппаратного обеспечения #### a. Перезагрузка шлюза Позволяет авторизованному пользователю перезагрузить шлюз через этот интерфейс :::советы * **URL**：`/open-api/V2/rest/hardware/reboot` * **Метод**：`POST` * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: ```json { "error": 0, "data": {}, "message": "success" } ``` #### b. Управление динамиком Позволяет авторизованным пользователям управлять динамиком через этот интерфейс :::советы * **URL**：`/open-api/V2/rest/hardware/speaker` * **Метод**：`POST` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------- | ------------------------------- | ------------------------------------------------------------------------------------------------ | | type | string | N | Необязательные параметры: 1.play\_sound (воспроизвести звук) 2.play\_beep (воспроизвести сигнал) | | sound | SoundObject | Y (N, если type = play\_sound.) | Звук. | | beep | BeepObject | Y (N, если type = play\_beep.) | Сигнал | SoundObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Имя звука. Поддерживаемые значения можно посмотреть в \[Resource List - Supported sound] | | volume | int | N | Громкость звука. \[0-100] | | countdown | int | N | Продолжительность воспроизведения звука динамиком; воспроизведение автоматически остановится по истечении времени. Единица: секунда. \[0,1799] | BeepObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------------------------------------------------- | | name | string | N | Имя deep. Поддерживаемые значения можно посмотреть в \[Resource List - Supported deep] | | volume | int | N | Громкость deep. \[0-100] | Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\* `200 OK` ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.3 Функции управления устройствами #### a. Поддерживаемые типы устройств | **Тип устройства** | **Значение** | Версия iHost | | ------------------------------- | ---------------------------- | ------------ | | Розетка | plug | ≥ 2.1.0 | | Выключатель | switch | ≥ 2.1.0 | | Свет | light | ≥ 2.1.0 | | Штора | curtain | ≥ 2.1.0 | | Датчик двери/окна | contactSensor | ≥ 2.1.0 | | Датчик движения | motionSensor | ≥ 2.1.0 | | Датчик температуры | temperatureSensor | ≥ 2.1.0 | | Датчик влажности | humiditySensor | ≥ 2.1.0 | | Датчик температуры и влажности | temperatureAndHumiditySensor | ≥ 2.1.0 | | Детектор протечки воды | waterLeakDetector | ≥ 2.1.0 | | Детектор дыма | smokeDetector | ≥ 2.1.0 | | Беспроводная кнопка | button | ≥ 2.1.0 | | Камера | camera | ≥ 2.1.0 | | Общий датчик | sensor | ≥ 2.1.0 | | Общий датчик | sensor | ≥ 2.1.0 | | Потолочный вентилятор со светом | fanLight | ≥ 2.1.0 | | Кондиционер | airConditioner | ≥ 2.1.0 | | Вентилятор | fan | ≥ 2.1.0 | | Термостат | thermostat | ≥ 2.1.0 | #### b. Поддерживаемые возможности устройства **Выключатель питания (power):** **Пример объявления возможности:** ``` [ { "capability": "power", // Название возможности "permission": "1100", // ihost не поддерживает настройку мягкого запуска/остановки, поэтому поле configure отсутствует } ] ``` **Атрибут состояния:** ``` { "powerState": "on", // Поле powerState указывает состояние включения/выключения питания. Обязательно. **Тип:** string. "on" означает включено, "off" означает выключено, "toggle" означает переключение. } ``` **Протокол (запрос статуса и управляющие инструкции):** **Включить:** ``` { "power": { "powerState": "on" } } ``` **Выключить:** ``` { "power": { "powerState": "off" } } ``` **Переключатель канала (toggle):** **Пример объявления возможности:** Пример для одного компонента: ``` [ { "capability": "toggle", // Название возможности "permission": "1100", // Разрешение "name": "1", // Название компонента, **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4), или другие значения, содержащие заглавные и строчные буквы и цифры } ] ``` Пример для нескольких компонентов: ``` [ { "capability": "toggle", "permission": "1100", "name": "1" }, { "capability": "toggle", "permission": "1100", "name": "2" } ] ``` **Атрибут состояния:** ``` { "toggleState": "on", // Поле toggleState указывает состояние переключателя {device_id} для атрибута {name}. Обязательно. **Тип:** String. "on" означает включено, "off" означает выключено, "toggle" означает переключить. } ``` **Протокол (запрос статуса и управляющие инструкции):** Формат переключения: ``` { [capability]: { [toggle-name]: { [toggleState]: [value] } } } Компонент 1 Включен, Компонент 2 Выключен: { "toggle": { "1": { "toggleState": "on" }, "2": { "toggleState": "off" } } } ``` **Импульсное включение канала (toggle-inching):** **Пример объявления возможности:** ``` [ { "capability": "toggle-inching", // Название возможности "permission": "0010", // Разрешение "settings": { "toggleInchingSetting": { "permission": "11", "type": "object", "value": { "supported": { "1": { // Название компонента "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно. "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено) "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно. "min_delay": 500, // Минимальное время задержки "max_delay": 100000 // Максимальное время задержки }, "2": { // Название компонента "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно. "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено) "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно. "min_delay": 500, // Минимальное время задержки "max_delay": 100000 // Максимальное время задержки }, "3": { // Название компонента "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно. "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено) "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно. "min_delay": 500, // Минимальное время задержки "max_delay": 100000 // Максимальное время задержки }, "4": { // Название компонента "enable": true, // Включена ли функция импульса. **Тип:** Boolean. Обязательно. "inchingSwitch": "off", // Настройка импульсного переключателя. **Тип:** String. Обязательно. "off" (выключено), "on" (включено) "delay": 1000, // Время задержки импульса в миллисекундах. **Тип:** Integer. Обязательно. "min_delay": 500, // Минимальное время задержки "max_delay": 100000 // Максимальное время задержки } } } } } } ] ``` **Атрибут состояния** Нет **Протокол (запрос статуса и управляющие инструкции)** Нет **Регулировка яркости (brightness):** **Пример объявления возможности:** ``` { "capability": "brightness", // Название возможности "permission": "1100" // Разрешение } ``` **Атрибут состояния:** ``` { "brightness": 100, // Поле brightness указывает процент яркости. Выберите brightness или brightnessDelta. **Тип:** Number. Диапазон: 0-100. } ``` **Протокол (запрос статуса и управляющие инструкции):** Установить яркость на 80%. (0 — темнее, 100 — светлее.) ``` json Копировать код { "brightness": { "brightness": 80 } } ``` **Регулировка цветовой температуры (color-temperature):** **Пример объявления возможности:** ``` { "capability": "color-temperature", // Название возможности "permission": "1100" // Разрешение } ``` **Атрибут состояния:** ``` { "colorTemperature": 100, // Поле colorTemperature указывает процент цветовой температуры. Выберите colorTemperature или colorTemperatureDelta. **Тип:** Number. Диапазон: 0-100. 0 означает теплый свет, 50 — нейтральный, 100 — холодный. } ``` **Протокол (запрос статуса и управляющие инструкции):** Отрегулировать цветовую температуру до 50%: ``` json { "color-temperature": { "colorTemperature": 50 } } ``` **Регулировка цвета (color-rgb):** **Пример объявления возможности:** ``` { "capability": "color-rgb", // Название возможности "permission": "1100" // Разрешение } ``` **Атрибут состояния:** ``` { "red": 255, // Поле red представляет красный компонент в RGB. Обязательно. **Тип:** Number. Диапазон: 0-255. "green": 0, // Поле green представляет зеленый компонент в RGB. Обязательно. **Тип:** Number. Диапазон: 0-255. "blue": 255 // Поле blue представляет синий компонент в RGB. Обязательно. **Тип:** Number. Диапазон: 0-255. } ``` **Протокол (запрос статуса и управляющие инструкции):** Установить цвет на фиолетовый: ``` { "color-rgb": { "red": 255, "green": 0, "blue": 255 } } ``` **Регулировка в процентах (percentage):** **Пример объявления возможности:** ``` { "capability": "percentage", "permission": "1100", "settings": { // Необязательно "percentageRange": { "permission": "01", "type": "numeric", "min": 0, "max": 100, "step": 5 } } } ``` **Атрибут состояния:** ``` { "percentage": 100, // Поле percentage указывает процентное значение. Выберите percentage или percentageDelta. **Тип:** Number. Диапазон: 0-100. } ``` **Протокол (запрос статуса и управляющие инструкции):** Отрегулировать до 40%: ``` { "percentage": { "percentage": 40 } } ``` **Управление мотором (motor-control):** **Пример объявления возможности:** ``` { "capability": "motor-control", "permission": "1100" } ``` **Атрибут состояния:** ``` json { "motorControl": "stop", // Поле motorControl указывает состояние мотора. Обязательно. **Тип:** String. Возможные значения: "open" (открыть), "close" (закрыть), "stop" (остановить), "lock" (заблокировать). } ``` **Протокол (запрос статуса и управляющие инструкции):** Открыть мотор: ``` { "motor-control": { "motorControl": "open" } } ``` **Реверс мотора (motor-reverse):** **Пример объявления возможности:** ``` { "capability": "motor-reverse", "permission": "1100" } ``` **Атрибут состояния:** ``` { "motorReverse": true, // Поле motorReverse указывает направление мотора. Обязательно. **Тип:** Boolean. true означает вперед, false означает назад. } ``` **Протокол (запрос статуса и управляющие инструкции):** Установить мотор на движение вперед: ``` { "motor-reverse": { "motorReverse": true } } ``` **Калибровка мотора (motor-clb)** **Пример объявления возможности:** ``` { "capability": "motor-clb", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "motorClb": "calibration" // Поле motorClb указывает статус калибровки мотора. Обязательно. **Тип:** String. "normal" означает нормальный режим (откалиброван), "calibration" означает выполняющуюся калибровку. } ``` **Протокол (отчет о состоянии):** Отчет: мотор проходит калибровку: ``` { "motor-clb": { "motorClb": "calibration" } } ``` **Состояние при включении питания (startup)** **Пример объявления возможности:** ``` { "capability": "startup", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "startup": "on" // Состояние питания при старте. **Тип:** String. Обязательно. Допустимые значения: "on" (включено), "stay" (сохранить состояние), "off" (выключено), "toggle" (инвертировать состояние). } ``` **Протокол (запрос статуса и управляющие инструкции):** Установить состояние питания: всегда включено: ``` { "startup": { "startup": "on" } } ``` *** **Активация при пробуждении (identify)** **Пример объявления возможности:** ``` { "capability": "identify", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "identify": true // Указывает, активно ли устройство сообщает результаты распознавания или активировано. } ``` **Протокол (отчет о состоянии и управляющие инструкции):** Установить время активации при пробуждении: ``` { "identify": { "countdown": 180 // Поле countdown указывает время обратного отсчета. Обязательно. **Тип:** Number. Единица: секунды. } } ``` Отчет о статусе активации: ``` { "identify": { "identify": true // Указывает, активно ли устройство сообщает результаты распознавания или активировано. } } ``` **Переключатель статистики реального потребления энергии (power-consumption)** **Пример объявления возможности:** ``` { "capability": "power-consumption", "permission": "1101", "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ``` **Атрибуты (Состояние):** Запустить/Остановить статистику в реальном времени: ``` { "rlSummarize": true, // Запуск/остановка статистики в реальном времени. **Тип:** Boolean. Обязательно. "timeRange": { // Диапазон времени для суммирования. Обязательно. "start": "2020-07-05T08:00:00Z", // Время начала статистики потребления энергии. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания статистики потребления энергии. **Тип:** String. Обязательно. } } ``` Запросить потребление энергии за диапазон времени: ``` { "type": "summarize", // Тип статистики. **Тип:** String. Обязательно. Допустимые значения: "rlSummarize" (реальное время), "summarize" (текущий итог). "timeRange": { // Диапазон времени для суммирования. Обязательно, если type = "summarize". "start": "2020-07-05T08:00:00Z", // Время начала статистики потребления энергии. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания статистики потребления энергии. **Тип:** String. Необязательно. Если пропущено, означает текущее время. } } ``` Ответ со статистикой за диапазон времени: ``` json { "type": "summarize", // Тип статистики. **Тип:** String. Обязательно. Допустимые значения: "rlSummarize" (реальное время), "summarize" (текущий итог). "rlSummarize": 50.0, // Общее потребление энергии. **Тип:** Number. Единица: 0.01 kWh. Необязательно. "electricityIntervals": [ // Несколько записей статистики, разделенные в соответствии с configuration.resolution. Необязательно. Отсутствует, когда type = "rlSummarize". { "usage": 26.5, // Потребление энергии. **Тип:** Number. Единица: 0.01 kWh. Обязательно. "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** Date. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** Date. Обязательно. Если интервал между end и start меньше resolution, все записанные записи считаются недействительными. }, { "usage": 26.5, // Потребление энергии. **Тип:** Number. Единица: 0.01 kWh. Обязательно. "start": "2020-07-05T09:00:00Z", // Время начала. **Тип:** Date. Обязательно. "end": "2020-07-05T10:00:00Z" // Время окончания. **Тип:** Date. Обязательно. Если интервал между end и start меньше resolution, все записанные записи считаются недействительными. } ] } ``` **Протокол (отчет о состоянии и управляющие инструкции):** Запустить статистику в реальном времени: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Остановить статистику в реальном времени: ``` json { "power-consumption": { "powerConsumption": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Получить историческое потребление энергии: ``` json { "power-consumption": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } ``` Получить потребление энергии в реальном времени: ``` json { "power-consumption": { "powerConsumption": { "type": "rlSummarize" } } } ``` **Обнаружение режима температуры и влажности (thermostat-mode-detect)** **Пример объявления возможности:** ``` { "capability": "thermostat-mode-detect", "permission": "0110", "name": "temperature", // Тип обнаружения климат-контроля. **Тип:** String. Обязательно. Допустимые значения: "humidity" (влажность), "temperature" (температура). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Поддерживаемые настройки обнаружения. Обязательно. { "name": "lowerSetpoint", // Значение обнаружения должно быть выше этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint. "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия. "value": 68.0, // Значение температуры. **Тип:** Number. Обязательно. "scale": "f" // Единица температуры. Обязательно, когда name=temperature. Допустимые значения: "c" (Цельсий), "f" (Фаренгейт). } }, { "name": "upperSetpoint", // Значение обнаружения должно быть ниже этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint. "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия. "value": 68.0, // Значение температуры. **Тип:** Number. Обязательно. "scale": "f" // Единица температуры. Обязательно, когда name=temperature. Допустимые значения: "c" (Цельсий), "f" (Фаренгейт). } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } { "capability": "thermostat-mode-detect", "permission": "0110", "name": "humidity", // Тип обнаружения климат-контроля. **Тип:** String. Обязательно. Допустимые значения: "humidity" (влажность), "temperature" (температура). "settings": { "setpointRange": { "permission": "11", "type": "object", "value": { "supported": [ // Поддерживаемые настройки обнаружения. Обязательно. { "name": "lowerSetpoint", // Значение обнаружения должно быть выше этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint. "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия. "value": 68.0, // Значение влажности. **Тип:** Number. Обязательно } }, { "name": "upperSetpoint", // Значение обнаружения должно быть ниже этой уставки. Требуется как минимум lowerSetpoint или upperSetpoint. "value": { // Диапазон обнаружения. Необязательно. Укажите, если есть предустановленные условия. "value": 68.0, // Значение влажности. **Тип:** Number. Обязательно } } ] } }, "supportedModes": { "type": "enum", "permission": "01", "values": [ "COMFORT", "COLD", "HOT" ] } } } ``` **Атрибуты (Состояние):** ``` { "mode": "COMFORT" // Идентификатор режима. Необязательно. Поддерживаемые значения: "COMFORT" (Комфорт), "COLD" (Холод), "HOT" (Жарко), "DRY" (Сухо), "WET" (Влажно). } ``` **Протокол (запрос статуса и управляющие инструкции):** Формат: ``` { [capability] :{ [имя режима] :{ "mode": [value] } } } ``` Пример: ``` { "thermostat-mode-detect": { "humidity": { "mode": "COMFORT" } } } ``` **Режим термостата (thermostat-mode)** **Пример объявления возможности:** ``` { "capability": "thermostat", "permission": "1100", "name": "thermostat-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", "AUTO", "ECO" ] } } } ``` **Атрибуты (Состояние):** ``` { "thermostatMode": "MANUAL" // Режим работы термостата. **Тип:** String. Допустимые значения: "MANUAL", "AUTO", "ECO". } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "thermostat": { "thermostat-mode": { "thermostatMode": "MANUAL" } } } ``` **Статус адаптивного восстановления термостата (thermostat/adaptive-recovery-status)** **Пример объявления возможности:** ``` { "capability": "thermostat", "permission": "0100", "name": "adaptive-recovery-status" // Статус адаптивного восстановления термостата } ``` **Атрибуты (Состояние):** ``` { "adaptiveRecoveryStatus": "HEATING" // Статус адаптивного восстановления термостата. **Тип:** String. Допустимые значения: "HEATING", "INACTIVE". } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "thermostat": { "adaptive-recovery-status": { "adaptiveRecoveryStatus": "HEATING" } } } ``` **Установка целевой температуры режима термостата (thermostat-target-setpoint)** **Пример объявления возможности:** ``` [[ { "capability": "thermostat-target-setpoint", "name": "manual-mode", "permission": "1110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 } } }, { "capability": "thermostat-target-setpoint", "name": "eco-mode", "permission": "1110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 } } }, { "capability": "thermostat-target-setpoint", "name": "auto-mode", "permission": "0110", "settings": { "temperatureUnit":{ "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange":{ "type": "numeric", "permission": "01", "min": 4, "max": 35, "step": 0.5 }, "weeklySchedule":{ "type": "object", "permission": "11", "value": { "maxEntryPerDay": 2, "Monday": [ { "startTimeInMinutes": 440, // Время начала в минутах. **Тип:** int. Например, 7:20 = 440 минут. "upperSetpoint": 36.5, // Максимальная целевая температура. **Тип:** number. "lowerSetpoint": 20 // Минимальная целевая температура. **Тип:** number. }, { "startTimeInMinutes": 900, // Время начала в минутах. Например, 15:00 = 900 минут. "upperSetpoint": 26.5, // Максимальная целевая температура. **Тип:** number. "lowerSetpoint": 21 // Минимальная целевая температура. **Тип:** number. } ], "Tuesday": [... ], "Wednesday": [... ], "Thursday": [... ], "Friday": [... ], "Saturday": [... ], "Sunday": [... ], } } } } ] ``` **Атрибуты (Состояние):** ``` { "targetSetpoint": 30 // Целевая температура для указанного режима. **Тип:** number, в единицах, заданных temperatureUnit. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "thermostat-target-setpoint": { "manual-mode": { "targetSetpoint": 30 }, "auto-mode": { "targetSetpoint": 30 } } } ``` **Обнаружение датчика (detect)** **Пример объявления возможности:** ``` { "capability": "detect", "permission": "0110", "settings": { // Необязательно "detectInterval": { "permission": "11", "type": "numeric", "value": 300 }, "detectSensitivity": { "permission": "11", "type": "numeric", "value": 1000 } } } ``` **Атрибуты (Состояние):** ``` { "detected": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "detect": { "detected": true } } ``` **Обнаружение температуры (temperature)** **Пример объявления возможности:** ``` { "capability": "temperature", "permission": "0110", "settings": { // Необязательно "temperatureCalibration": { // Необязательная калибровка температуры "type": "numeric", "permission": "11", "min": -7, // Минимальное значение "max": 7, // Максимальное значение "step": 0.2, // Шаг регулировки температуры, единица совпадает с temperatureUnit "value": 5.2 // Текущее значение калибровки температуры. **Тип:** number. }, "temperatureUnit": { // Необязательная единица температуры "type": "enum", "permission": "11", "value": "c", "values": [ "c", "f" ] }, "temperatureRange": { // Необязательный диапазон обнаружения температуры "type": "numeric", "permission": "01", "min": -40, "max": 80 } } } ``` **Атрибуты (Состояние):** ``` json Копировать код { "temperature": 26.5 // Текущая температура. **Тип:** Number, в градусах Цельсия. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "temperature": { "temperature": 20 } } ``` **Обнаружение влажности (humidity)** **Пример объявления возможности:** ``` { "capability": "humidity", "permission": "0100", "settings": { // Необязательный диапазон обнаружения влажности. "humidityRange": { "type": "numeric", "permission": "01", "min": 0, "max": 100 } } } ``` **Атрибуты (Состояние):** ``` { "humidity": 50 // Текущая относительная влажность (в процентах). **Тип:** Number, диапазон 0-100. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "humidity": { "humidity": 20 } } ``` **Обнаружение батареи (battery)** **Пример объявления возможности:** ``` { "capability": "battery", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "battery": 95 // Оставшийся заряд батареи в процентах. **Тип:** Number, диапазон -1 до 100. Примечание: -1 означает неизвестный уровень батареи. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "battery": { "battery": 40 } } ``` **Обнаружение одиночной кнопки (press)** **Пример объявления возможности:** ``` { "capability": "press", "permission": "1100", "settings": { // Необязательно "actions": { // Действия кнопки, необязательно. "type": "enum", "permission": "01", "values": [ // Необязательные действия кнопки. Значения по умолчанию: "singlePress", "doublePress", "longPress". Настроенные действия заменяют значения по умолчанию. ] } } } ``` **Атрибуты (Состояние):** ``` { "press": "singlePress" // Тип нажатия кнопки. **Тип:** String. Стандартные значения: "singlePress" (одиночное/короткое), "doublePress" (двойное), "longPress" (долгое). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "press": { "press": "singlePress" } } ``` **Обнаружение множественных нажатий (multi-press)** **Пример объявления возможности:** ``` { "capability": "multi-press", "permission": "0100", "name": "1", // Имя атрибута multi-press. **Тип:** String. Разрешены только буквенно-цифровые символы. "settings": { // Необязательно "actions": { // Действия кнопки, необязательно. "type": "enum", "permission": "01", "values": [ // Необязательные действия кнопки. Значения по умолчанию: "singlePress", "doublePress", "longPress". Настроенные действия заменяют значения по умолчанию. ] } } } ``` **Атрибуты (Состояние):** ``` { "press": "singlePress" // Тип нажатия кнопки. **Тип:** String. Стандартные значения: "singlePress" (одиночное/короткое), "doublePress" (двойное), "longPress" (долгое). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { [capability] :{ [multi-press-name]：{ press:[value] } } } пример: { "multi-press": { "1": { "press": "singlePress" }, "2": { "press": "doublePress" } } } ``` **Обнаружение уровня сигнала (rssi)** **Пример объявления возможности:** ``` { "capability": "rssi", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "rssi": -65 // Уровень беспроводного сигнала (Received Signal Strength Indicator). **Тип:** Number, единица dBm, отрицательное целое значение. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "rssi": { "rssi": -65 } } ``` **Обнаружение попытки вскрытия (tamper-alert)** **Пример объявления возможности:** ``` { "capability": "tamper-alert", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "tamper": "clear" // Статус вскрытия. **Тип:** String. Возможные значения: "clear" (не вскрыто), "detected" (вскрыто). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "tamper-alert": { "tamper": "clear" // Статус вскрытия. **Тип:** String. Возможные значения: "clear" (не вскрыто), "detected" (вскрыто). } } ``` **Обнаружение уровня освещенности (illumination-level)** **Пример объявления возможности:** ``` { "capability": "illumination-level", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "level": "brighter" // Уровень яркости. **Тип:** String. Возможные значения: "brighter" (ярче), "darker" (темнее). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "illumination-level": { "level": "brighter" } } ``` **Обнаружение напряжения (voltage)** **Пример объявления возможности:** ``` { "capability": "voltage", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "voltage": 50 // Текущее значение напряжения, в единицах 0.01V. **Тип:** Number, неотрицательное значение. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "voltage": { "voltage": 50 } } ``` **Обнаружение электрического тока (electric-current)** **Пример объявления возможности:** ``` { "capability": "electric-current", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "electric-current": 50 // Текущее значение тока, в единицах 0.01A. **Тип:** Number, неотрицательное целое. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "electric-current": { "electric-current": 50 } } ``` **Обнаружение электрической мощности (electric-power)** **Пример объявления возможности:** ``` { "capability": "electric-power", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "electric-power": 50 // Текущее значение мощности, в единицах 0.01W. **Тип:** Number, неотрицательное целое. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "electric-power": { "electric-power": 50 } } ``` **Обнаружение неисправности (fault)** **Пример объявления возможности:** ``` { "capability": "fault", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "fault": "none" // Статус неисправности. **Тип:** String. Возможные значения: "none" (без неисправностей), "detected" (неисправность обнаружена). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "fault": { "fault": "none" } } ``` **Пороговый переключатель (threshold-breaker)** **Пример объявления возможности:** ``` { "capability": "threshold-breaker", "permission": "0010", "settings": { "supportedSetting": { "type": "object", "permission": "11", "value": { "supported": [ { "name": "lowerPower", // Порог низкой мощности "value": { "value": 50, // Значение мощности для обнаружения, в единицах 0.01W. **Тип:** Integer. Диапазон: >=0. "min_range": 10, // Минимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0. "max_range": 3500 // Максимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0. } }, { "name": "upperPower", // Порог высокой мощности "value": { "value": 50, // Значение мощности для обнаружения, в единицах 0.01W. **Тип:** Integer. Диапазон: >=0. "min_range": 10, // Минимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0. "max_range": 3500 // Максимальное значение мощности для обнаружения, в 0.01W. **Тип:** Integer. Диапазон: >=0. } }, { "name": "lowerElectricCurrent", // Порог низкого тока "value": { "value": 50, // Значение тока для обнаружения, в единицах 0.01A. **Тип:** Integer. Диапазон: >=0. "min_range": 10, // Минимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0. "max_range": 1500 // Максимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0. } }, { "name": "upperElectricCurrent", // Порог высокого тока "value": { "value": 50, // Значение тока для обнаружения, в единицах 0.01A. **Тип:** Integer. Диапазон: >=0. "min_range": 10, // Минимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0. "max_range": 1500 // Максимальное значение тока для обнаружения, в 0.01A. **Тип:** Integer. Диапазон: >=0. } }, { "name": "lowerVoltage", // Порог низкого напряжения "value": { "value": 50, // Значение напряжения для обнаружения, в единицах 0.01V. **Тип:** Integer. Диапазон: >=0. "min_range": 10, // Минимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0. "max_range": 24000 // Максимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0. } }, { "name": "upperVoltage", // Порог высокого напряжения "value": { "value": 50, // Значение напряжения для обнаружения, в единицах 0.01V. **Тип:** Integer. Диапазон: >=0. "min_range": 10, // Минимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0. "max_range": 24000 // Максимальное значение напряжения для обнаружения, в 0.01V. **Тип:** Integer. Диапазон: >=0. } } ] } } } } ``` **Атрибуты (Состояние)** * Нет **Протокол (запрос статуса и управляющие инструкции)** * Нет **Функция импульса (inching)** **Пример объявления возможности:** ``` { "capability": "inching", "permission": "0010", "settings": { "inchingEnable": { // Настройка включения функции импульса "permission": "11", "type": "boolean", "value": false }, "inchingSwitch": { // Настройка действия импульса "type": "enum", "permission": "11", "value": "on", "values": ["on", "off"] }, "inchingDelay": { // Настройка времени импульса "type": "numeric", "permission": "11", "min": 500, "max": 100000, "value": 1000, "unit": "ms" } } } ``` **Атрибуты (Состояние):** * Нет **Протокол (запрос статуса и управляющие инструкции):** * Нет **Поток камеры (camera-stream)** **Пример объявления возможности:** ``` { "capability": "camera-stream", "permission": "0010", "settings": { "streamSetting": { "type": "object", "permission": "11", "value": { "username": "String", // Учетная запись доступа. **Тип:** String. Обязательно. "password": "String", // Пароль доступа. **Тип:** String. Обязательно. "streamUrl": "rtsp://:@:/streaming/channel01", // URL потока. **Тип:** String. Обязательно. "videoCodec": "", // Видео кодек. **Тип:** String. Обязательно. Дополнительные параметры должны быть определены. "resolution": { // Разрешение видео. Обязательно. "width": 1080, // Ширина. **Тип:** Number. Обязательно. "height": 720 // Высота. **Тип:** Number. Обязательно. }, "keyFrameInterval": 5, // Интервал ключевых кадров. **Тип:** String. Обязательно. "audioCodec": "G711", // Аудио кодек. **Тип:** String. Обязательно. Дополнительные параметры должны быть определены. "samplingRate": 50, // Частота дискретизации аудио, в Гц. **Тип:** Number. Обязательно. Дополнительные параметры должны быть определены. "dataRate": 50 // Битрейт. **Тип:** Number. Обязательно. Единица: kb/s. } } } } ``` **Атрибуты (Состояние):** * Нет **Протокол (запрос статуса и управляющие инструкции):** * Нет **Управление режимом (mode)** **Пример объявления возможности:** ``` [ { "capability": "mode", "name": "fanLevel", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["low", "medium", "high"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию. } } }, { "capability": "mode", "name": "thermostatMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["auto", "manual"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию. } } }, { "capability": "mode", "name": "airConditionerMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["cool", "heat", "auto", "fan", "dry"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию. } } }, { "capability": "mode", "name": "fanMode", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["normal", "sleep", "child"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию. } } }, { "capability": "mode", "name": "horizontalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию. } } }, { "capability": "mode", "name": "verticalAngle", "permission": "1100", "settings": { "supportedValues": { "type": "enum", "permission": "01", "values": ["30", "60", "90", "120", "180", "360"] // Пользовательские значения режимов. Настроенные значения заменяют значения по умолчанию. } } } ] ``` **Атрибуты (Состояние):** ``` { "modeValue": "low" // Значение режима. **Тип:** String. Обязательно. См. поддерживаемые предустановленные режимы. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "mode": { "fanLevel": { "modeValue": "low" } } } ``` **Обнаружение углекислого газа (co2)** **Пример объявления возможности:** ``` { "capability": "co2", "permission": "0100", "settings": { "co2Range": { "type": "numeric", "permission": "01", "min": 400, "max": 10000 } } } ``` **Атрибуты (Состояние):** ``` { "co2": 111 // Концентрация CO2. **Тип:** Integer. Единица: ppm. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "co2": { "co2": 500 } } ``` **Обнаружение освещенности (illumination)** **Пример объявления возможности:** ``` { "capability": "illumination", "permission": "0100", "settings": { "illuminationRange": { "type": "numeric", "permission": "01", "min": 0, "max": 160000 } } } ``` **Атрибуты (Состояние):** ``` { "illumination": 11 // Уровень освещенности. **Тип:** Integer. Единица: люкс. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "illumination": { "illumination": 50 } } ``` **Обнаружение дыма (smoke)** **Пример объявления возможности:** ``` { "capability": "smoke", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "smoke": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "smoke": { "smoke": true } } ``` **Обнаружение открытия/закрытия дверного магнита (контакт)** **Пример объявления возможности:** ``` { "capability": "contact", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "contact": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "contact": { "contact": true } } ``` **Обнаружение движения (motion)** **Пример объявления возможности:** ``` { "capability": "motion", "permission": "0110", "settings": { "motionInterval": { "type": "numeric", "permission": "11", "value": 300 }, "motionSensitivity": { "type": "numeric", "permission": "11", "value": 1000 } } } ``` **Атрибуты (Состояние):** ``` { "motion": true // Результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "motion": { "motion": true } } ``` **Обнаружение утечки воды (water-leak)** **Пример объявления возможности:** ``` { "capability": "water-leak", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "waterLeak": true // Поле `waterLeak` указывает текущий результат обнаружения. **Тип:** Boolean. `true` означает обнаружено, `false` означает не обнаружено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "water-leak": { "waterLeak": true } } ``` **Переключатель обнаружения окна (window-detection)** **Пример объявления возможности:** ``` { "capability": "window-detection", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "window-detection": { "powerState": "on" } } ``` **Защита от детей (child-lock)** **Пример объявления возможности:** ``` { "capability": "child-lock", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "child-lock": { "powerState": "on" } } ``` **Защита от прямого удара (anti-direct-blow)** **Пример объявления возможности:** ``` { "capability": "anti-direct-blow", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "anti-direct-blow": { "powerState": "on" } } ``` **Горизонтальный маятник (horizontal-swing)** **Пример объявления возможности:** ``` { "capability": "horizontal-swing", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "horizontal-swing": { "powerState": "on" } } ``` **Вертикальный маятник (vertical-swing)** **Пример объявления возможности:** ``` { "capability": "vertical-swing", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "vertical-swing": { "powerState": "on" } } ``` **Режим ECO (eco)** **Пример объявления возможности:** ``` { "capability": "eco", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "powerState": "on" // Поле `powerState` указывает состояние питания. **Тип:** String. `on` означает питание включено, `off` означает питание выключено. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "eco": { "powerState": "on" } } ``` **Переключатель запуска (toggle-startup)** **Пример объявления возможности:** ``` { "capability": "toggle-startup", "permission": "1100", "name": "1" // Поле `name` задает имя атрибута для `toggle-startup`. **Тип:** String. Допускаются только буквы и цифры. } ``` **Атрибуты (Состояние):** ``` { "startup": "on" // **Тип:** String. Опции: `on` (включить питание), `stay` (удерживать питание), `off` (выключить питание). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "toggle-startup": { "1": { "startup": "on" }, "2": { "startup": "off" } } } ``` **Задержка обнаружения (detect-hold)** **Пример объявления возможности:** ``` { "capability": "detect-hold", "permission": "0100", "settings": { "detectHoldEnable": { // Настройка включения задержки обнаружения "permission": "01", "type": "boolean", "value": false }, "detectHoldSwitch": { // Настройка действия задержки обнаружения "type": "enum", "permission": "01", "value": "on", "values": ["on", "off"] }, "detectHoldTime": { // Настройка времени задержки обнаружения "type": "numeric", "permission": "01", "min": 1, "max": 359, "value": 5, "unit": "minute" } } } ``` **Атрибуты (Состояние):** ``` { "detectHold": "on" // Поле `detectHold` указывает состояние удержания обнаружения. **Тип:** String. `on` означает, что удержание обнаружения активно, `off` означает, что удержание обнаружения не активно. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "detect-hold": { "detectHold": "on" } } ``` **Переключатель идентификации/активации (toggle-identify)** **Пример объявления возможности:** ``` { "capability": "toggle-identify", "permission": "1100", // Примечание: Эта возможность не используется для отчетности в текущей версии (V1.13.7) на ihost. "name": "1" // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4). } ``` **Атрибуты (Состояние):** ``` { "identify": true, // Указывает, что устройство активно сообщило об идентификации или активации. "countdown": 180 // Поле `countdown` указывает длительность активации. **Тип:** Number. Единица: секунды. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "toggle-identify": { "1": { "countdown": 180 // Активировать устройство на 180 секунд. } } } // Устройство сообщает о самості активации { "toggle-identify": { "1": { "identify": true } } } ``` **Переключатель измерения напряжения (toggle-voltage)** **Пример объявления возможности:** ``` { "capability": "toggle-voltage", "permission": "1100" } ``` **Атрибуты (Состояние):** ``` { "voltage": 230 // Поле `voltage` указывает измеренное напряжение. **Тип:** Number. Единица: Вольт. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "toggle-voltage": { "voltage": 230 } } ``` **Измерение электрического тока подкомпонента (toggle-electric-current)** **Пример объявления возможности:** ``` [ { "capability": "toggle-electric-current", "permission": "0100", "name": "1" // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4). } ] ``` **Атрибуты (Состояние):** ``` { "electricCurrent": 50 // Поле `electricCurrent` представляет текущее значение тока. **Единица:** 0.01 A. **Тип:** Integer. Значение должно быть >= 0. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "toggle-electric-current": { "1": { "electricCurrent": 50 } } } ``` **Измерение мощности подкомпонента (toggle-electric-power)** **Пример объявления возможности:** ``` [ { "capability": "toggle-electric-power", "permission": "0100", "name": "1" // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4). } ] ``` **Атрибуты (Состояние):** ``` { "electricPower": 50, // Поле `electricPower` представляет текущее значение мощности. **Единица:** 0.01 W. **Тип:** Integer. Значение должно быть >= 0. "reactivePower": 50, // Поле `reactivePower` представляет текущее значение реактивной мощности. **Единица:** 0.01 W. **Тип:** Integer. Необязательно. "activePower": 50, // Поле `activePower` представляет текущее значение активной мощности. **Единица:** 0.01 W. **Тип:** Integer. Необязательно. "apparentPower": 50 // Поле `apparentPower` представляет текущее значение полной мощности. **Единица:** 0.01 W. **Тип:** Integer. Необязательно. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "toggle-electric-power": { "1": { "electricPower": 50, "reactivePower": 50, "activePower": 50, "apparentPower": 50 } } } ``` **Статистика потребления энергии подкомпонента (toggle-power-consumption)** **Пример объявления возможности:** ``` [ { "capability": "toggle-power-consumption", "permission": "1101", "name": "1", // Имя компонента. **Тип:** String. Допустимые значения: "1" (Канал 1), "2" (Канал 2), "3" (Канал 3), "4" (Канал 4). "settings": { "resolution": { "permission": "01", "type": "numeric", "value": 3600 }, "timeZoneOffset": { "permission": "01", "type": "numeric", "min": -12, "max": 14, "value": 0 } } } ] ``` **Атрибуты (Состояние):** Запустить/Остановить статистику в реальном времени: ``` { "rlSummarize": true, // Запуск или остановка статистики в реальном времени. **Тип:** Boolean. Обязательно. "timeRange": { // Интервал времени для сводки. Обязательно. "start": "2020-07-05T08:00:00Z", // Время начала учета потребления энергии. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания учета потребления энергии. **Тип:** String. Обязательно. } } ``` Запросить потребление энергии за диапазон времени: ``` { "type": "summarize", // Тип сводки. **Тип:** String. Обязательно. Опции: "rlSummarize" (сводка в реальном времени), "summarize" (текущая сводка). "timeRange": { // Интервал времени для сводки, обязателен, когда type равен "summarize". "start": "2020-07-05T08:00:00Z", // Время начала учета потребления энергии. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания учета потребления энергии. **Тип:** String. Необязательно. Если не указано, по умолчанию используется текущее время. } } ``` Ответ по потреблению энергии за указанный период: ``` { "type": "summarize", // Тип сводки. **Тип:** String. Обязательно. "rlSummarize": 50.0, // Общее потребление энергии. **Единица:** 0.01 kWh. **Тип:** Number. Необязательно. "electricityIntervals": [ // Разделено по `configuration.resolution` на несколько записей. Необязательно. Отсутствует, когда type = "rlSummarize". { "usage": 26.5, // Потребление энергии. **Единица:** 0.01 kWh. **Тип:** Number. Обязательно. "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** String. Обязательно. Записи с интервалом меньше разрешения считаются недействительными. }, { "usage": 26.5, // Потребление энергии. **Единица:** 0.01 kWh. **Тип:** Number. Обязательно. "start": "2020-07-05T09:00:00Z", // Время начала. **Тип:** String. Обязательно. "end": "2020-07-05T10:00:00Z" // Время окончания. **Тип:** String. Обязательно. Записи с интервалом меньше разрешения считаются недействительными. } ] } ``` **Протокол (запрос статуса и управляющие инструкции):** Запустить статистику в реальном времени: ``` { "toggle-power-consumption": { "1": { "rlSummarize": true, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "" } } } } ``` Остановить статистику в реальном времени: ``` { "toggle-power-consumption": { "1": { "rlSummarize": false, "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Получить историческое потребление энергии: ``` { "toggle-power-consumption": { "1": { "type": "summarize", "timeRange": { "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z" } } } } ``` Получить потребление энергии в реальном времени: ``` { "toggle-power-consumption": { "1": { "type": "rlSummarize" } } } ``` **Индекс качества связи (lqi)** **Пример объявления возможности:** ``` { "capability": "lqi", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "lqi": 60 // Поле `lqi` представляет индекс качества связи. **Тип:** Number. Диапазон значений: 0–255. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "lqi": { "lqi": 60 } } ``` **Функциональная конфигурация (configuration)** **Пример объявления возможности:** ``` [ { "capability": "configuration", "permission": "1100" } ] ``` **Атрибуты (Состояние):** ``` { "deviceConfiguration": { // Функциональная конфигурация, связанная с устройством "defaultResolution": 300, // Разрешение по умолчанию для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно. "maxResolution": 86400, // Максимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно. "minResolution": 60 // Минимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно. } } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "configuration": { "deviceConfiguration": { // Функциональная конфигурация, связанная с устройством "defaultResolution": 300, // Разрешение по умолчанию для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно. "maxResolution": 86400, // Максимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно. "minResolution": 60 // Минимальное разрешение для чтения данных насыщения влагой. **Тип:** Integer. **Единица:** Секунды. Обязательно. } } } ``` **Система (system)** **Пример объявления возможности:** ``` [ { "capability": "system", "permission": "1000" } ] ``` **Атрибуты (Состояние):** ``` { "restart": true // Команда перезапуска устройства. **Тип:** Boolean. Обязательно. Значение должно быть `true`. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "system": { // Конфигурация, связанная с возможностью. Необязательно. "restart": true } } ``` **Влажность (moisture)** **Пример объявления возможности:** ``` [ { "capability": "moisture", "permission": "0100" } ] ``` **Атрибуты (Состояние):** ``` { "moisture": 55.5 // Поле `moisture` представляет процент насыщения влагой. **Тип:** Number. Обязательно. Диапазон: 0–100. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "moisture": { "moisture": 55.5 } } ``` **Барометрическое давление (barometric-pressure)** **Пример объявления возможности:** ``` [ { "capability": "barometric-pressure", "permission": "0100", "settings": { "barometricPressureRange": { "type": "numeric", "permission": "01", "min": 540, // Минимальное значение. **Тип:** Integer. Обязательно. Должно быть меньше `max`. "max": 1100 // Максимальное значение. **Тип:** Integer. Обязательно. Должно быть больше `min`. } } } ] ``` **Атрибуты (Состояние):** ``` { "barometricPressure": 50 // Значение барометрического давления. **Тип:** Integer. Обязательно. **Единица:** hPa. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "barometric-pressure": { "barometricPressure": 50 } } ``` **Скорость ветра (wind-speed)** **Пример объявления возможности:** ``` [ { "capability": "wind-speed", "permission": "0100", "settings": { "windSpeedRange": { "type": "numeric", "permission": "01", "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`. "max": 50 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`. } } } ] ``` **Атрибуты (Состояние):** ``` { "windSpeed": 50 // Значение скорости ветра. **Тип:** Number. Обязательно. **Единица:** м/с (метры в секунду). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "wind-speed": { "windSpeed": 50 } } ``` **Направление ветра (wind-direction)** **Пример объявления возможности:** ``` [ { "capability": "wind-direction", "permission": "0100" } ] ``` **Атрибуты (Состояние):** ``` { "windDirection": 10 // Направление ветра. **Тип:** Integer. Обязательно. **Единица:** градусы. Диапазон: 0–360 градусов (по часовой стрелке). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "wind-direction": { "windDirection": 10 } } ``` **Осадки (rainfall)** **Пример объявления возможности:** ``` [ { "capability": "rainfall", "permission": "0100", "settings": { "rainfallRange": { "type": "numeric", "permission": "01", "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`. "max": 450 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`. } } } ] ``` **Атрибуты (Состояние):** ``` { "rainfall": 11.11 // Значение осадков. **Тип:** Number. Обязательно. **Единица:** мм/ч (миллиметры в час). } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "rainfall": { "rainfall": 11.11 } } ``` **Ультрафиолетовый индекс (ultraviolet-index)** **Пример объявления возможности:** ``` [ { "capability": "ultraviolet-index", "permission": "0100", "settings": { "ultravioletIndexRange": { "type": "numeric", "permission": "01", "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`. "max": 16 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`. } } } ] ``` **Атрибуты (Состояние):** ``` { "ultravioletIndex": 11.1 // Ультрафиолетовый индекс. **Тип:** Number. Обязательно. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "ultraviolet-index": { "ultravioletIndex": 11.1 } } ``` **Электропроводимость (electrical-conductivity)** **Пример объявления возможности:** ``` [ { "capability": "electrical-conductivity", "permission": "0100", "settings": { "electricalConductivityRange": { "type": "numeric", "permission": "01", "min": 0, // Минимальное значение. **Тип:** Number. Обязательно. Должно быть меньше `max`. "max": 23 // Максимальное значение. **Тип:** Number. Обязательно. Должно быть больше `min`. } } } ] ``` **Атрибуты (Состояние):** ``` { "electricalConductivity": 11.11 // Значение электропроводимости. **Тип:** Number. Обязательно. **Единица:** dS/m. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "electrical-conductivity": { "electricalConductivity": 11.11 } } ``` **Мощность передачи (transmit-power)** **Пример объявления возможности:** ``` [ { "capability": "transmit-power", "permission": "1100" } ] ``` **Атрибуты (Состояние):** ``` { "transmitPower": 9 // Значение мощности передачи устройства. **Тип:** Integer. Обязательно. **Единица:** dBm. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "transmit-power": { "transmitPower": 9 } } ``` **Обнаружение PM2.5 (pm25)** **Пример объявления возможности:** ``` [ { "capability": "pm25", "permission": "0100" } ] ``` **Атрибуты (Состояние):** ``` { "pm25": 10 // Концентрация PM2.5 в воздухе. **Тип:** Number. Обязательно. **Единица:** µg/m³. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "pm25": { "pm25": 10 } } ``` **Индекс VOC (voc-index)** **Пример объявления возможности:** ``` { "capability": "voc-index", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "vocIndex": 10 // Индекс VOC, отражающий уровень загрязнения вредными газами. **Тип:** Number. Обязательно. **Единица:** µg/m³. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "voc-index": { "vocIndex": 10 } } ``` **Обнаружение природного газа (gas)** **Пример объявления возможности:** ``` { "capability": "gas", "permission": "0100" } ``` **Атрибуты (Состояние):** ``` { "gas": true // Указывает, обнаружена ли утечка природного газа. **Тип:** Boolean. Обязательно. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "gas": { "gas": true } } ``` **Статус работы орошения (irrigation/work-status)** **Пример объявления возможности:** ``` [ { "capability": "irrigation", "permission": "0101", "name": "work-status", "settings": { "volumeUnit": { "type": "enum", "permission": "01", "values": ["L"], "value": "L" } } } ] ``` **Атрибуты (Состояние):** ``` { "realTimeVolume": 20, // Текущий объем орошения. **Тип:** Number. Необязательно. **Единица:** L. "start": "2020-07-05T08:00:00Z", // Время начала орошения. **Тип:** Date. Необязательно. "end": "2020-07-05T09:00:00Z", // Время окончания орошения. **Тип:** Date. Необязательно. "dailyVolume": 20 // Суточный объем орошения. **Тип:** Number. Необязательно. **Единица:** L. } ``` **Протокол (запрос статуса и управляющие инструкции):** Отчет о статусе работы: ``` { "irrigation": { "work-status": { "realTimeVolume": 20, "start": "2020-07-05T08:00:00Z", "end": "2020-07-05T09:00:00Z", "dailyVolume": 20 } } } ``` Запрос статуса работы: ``` { "irrigation": { "type": "oneDay", // Тип агрегации. **Тип:** String. Обязательно. Опции: "oneDay", "30Days", "180Days". "timeRange": { // Интервал времени для агрегации. **Тип:** Object. Обязательно. "start": "2020-07-05T08:00:00Z", // Время начала агрегации данных о поливе. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания агрегации данных о поливе. **Тип:** String. Необязательно. Если опущено, используется текущее время. } } } ``` Результат запроса статуса работы: ``` { "irrigation": { "type": "oneDay", // Тип агрегации. **Тип:** String. Обязательно. "irrigationIntervals": [ { "volume": 6500, // Объем орошения. **Тип:** Number. Обязательно. **Единица:** L. "duration": 30, // Длительность орошения. **Тип:** Number. Обязательно. **Единица:** минуты. "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** String. Обязательно. }, { "volume": 6500, // Объем орошения. **Тип:** Number. Обязательно. **Единица:** L. "duration": 30, // Длительность орошения. **Тип:** Number. Обязательно. **Единица:** минуты. "start": "2020-07-05T08:00:00Z", // Время начала. **Тип:** String. Обязательно. "end": "2020-07-05T09:00:00Z" // Время окончания. **Тип:** String. Обязательно. } ] } } ``` **Режим работы орошения (irrigation/work-mode)** **Пример объявления возможности:** ``` [ { "capability": "irrigation", "permission": "0100", "name": "work-mode", "settings": { "supportedModes": { "type": "enum", "permission": "01", "values": [ "MANUAL", // Ручной режим "TIMER", // Одноразовое планирование "CYCLE-TIMER", // Повторяющееся планирование "VOLUME", // Одноразовый объем "CYCLE-VOLUME" // Повторяющийся объем ] } } } ] ``` **Атрибуты (Состояние):** ``` { "workMode": "MANUAL" // Режим работы орошения. **Тип:** String. Необязательно. Значения должны быть из `settings.supportedModes`. } ``` **Протокол (запрос статуса и управляющие инструкции):** ``` { "irrigation": { "work-mode": "MANUAL" } } ``` **Автоматический контроллер орошения (irrigation/auto-controller)** **Пример объявления возможности:** ``` [ { "capability": "irrigation", "permission": "1100", "name": "auto-controller", "settings": { "volumeRange": { // Диапазон объема "type": "enum", "permission": "01", "min": 0, "max": 6500, "unit": "L" }, "timeRange": { // Диапазон времени "type": "enum", "permission": "01", "min": 1, "max": 86400, "unit": "second" }, "cycleCountRange": { // Диапазон количества циклов "type": "enum", "permission": "01", "min": 1, "max": 100, "step": 1 } } } ] ``` **Атрибуты (Состояние):** Одноразовое или повторяющееся планирование: ``` { "type": "time", // Режим полива. **Тип:** String. Обязательно. Опции: "volume", "time". "action": { "perDuration": 60, // Длительность одного цикла полива. **Тип:** Number. Обязательно. "intervalDuration": 20, // Интервал между циклами полива. **Тип:** Number. Обязательно. "count": 3 // Количество циклов полива. **Тип:** Number. Обязательно. } } ``` Одноразовый или повторяющийся по объему: ``` { "type": "volume", // Режим полива. **Тип:** String. Обязательно. Опции: "volume", "time". "action": { "perConsumedVolume": 60, // Объем, расходуемый за один цикл полива. **Тип:** Number. Обязательно. "intervalDuration": 20, // Интервал между циклами полива. **Тип:** Number. Обязательно. "count": 3 // Количество циклов полива. **Тип:** Number. Обязательно. } } ``` **Протокол (запрос статуса и управляющие инструкции):** Одноразовое или повторяющееся планирование: ``` { "irrigation": { "auto-controller": { "type": "time", // Режим полива. **Тип:** String. Обязательно. "action": { "perDuration": 60, // Длительность одного цикла полива. **Тип:** Number. Обязательно. "intervalDuration": 20, // Интервал между циклами. **Тип:** Number. Обязательно. "count": 3 // Количество циклов. **Тип:** Number. Обязательно. } } } } ``` Одноразовый или повторяющийся по объему: ``` { "irrigation": { "auto-controller": { "type": "volume", // Режим полива. **Тип:** String. Обязательно. "action": { "perConsumedVolume": 60, // Объем, расходуемый за цикл. **Тип:** Number. Обязательно. "intervalDuration": 20, // Интервал между циклами. **Тип:** Number. Обязательно. "count": 3 // Количество циклов. **Тип:** Number. Обязательно. } } } } ``` **Поддерживаемые предустановленные режимы** | \*\*Имена режимов \*\* | \*\*Дополнительные значения \*\* | | ------------------------------------------------- | -------------------------------- | | fanLevel (уровень вентилятора) | "low" | | "medium" | | | "high" | | | thermostatMode (режим термостата) | "auto" | | "manual" | | | airConditionerMode >= 1.11.0 (режим кондиционера) | "cool" | | "heat" | | | "auto" | | | "fan" | | | "dry" | | | fanMode >= 1.11.0 (режим вентилятора) | "normal" | | "sleep" | | | "child" | | | horizontalAngle >= 1.11.0 (горизонтальный угол) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | | verticalAngle >= 1.11.0 (вертикальный угол) | "30" | | "60" | | | "90" | | | "120" | | | "180" | | | "360" | | #### c. Описание тегов * Специальный ключ toggle используется для установки имени подкомпонента toggle. ``` { "toggle": { '1': 'Канал1', '2': 'Канал2', '3': 'Канал3', '4': 'Канал4', }, } ``` * Специальный ключ temperature\_unit используется для установки единицы температуры. ``` { "temperature_unit":'c' // c — Цельсий; f — Фаренгейт } ``` #### d. Специальные коды ошибок и описание | **Код ошибки** | **Описание** | Версия iHost | | -------------- | ----------------------------------------------------------------- | ------------ | | 110000 | Под-устройство/группа, соответствующая id, не существует | ≥2.1.0 | | 110001 | Шлюз находится в состоянии поиска zigbee-устройств | ≥2.1.0 | | 110002 | Устройства в группе не имеют общей возможности | ≥2.1.0 | | 110003 | Неверное количество устройств | ≥2.1.0 | | 110004 | Неверное количество групп | ≥2.1.0 | | 110005 | Устройство офлайн | ≥2.1.0 | | 110006 | Не удалось обновить статус устройства | ≥2.1.0 | | 110007 | Не удалось обновить статус группы | ≥2.1.0 | | 110008 | Достигнуто максимальное количество групп. Создайте до 50 групп | ≥2.1.0 | | 110009 | IP-адрес камерного устройства неверен | ≥2.1.0 | | 110010 | Ошибка авторизации доступа к камере | ≥2.1.0 | | 110011 | Ошибка адреса потока камерного устройства | ≥2.1.0 | | 110012 | Кодирование видео камерой не поддерживается | ≥2.1.0 | | 110013 | Устройство уже существует | ≥2.1.0 | | 110014 | Камера не поддерживает офлайн-режим | ≥2.1.0 | | 110015 | Пароль учетной записи не совпадает с паролем в адресе RTSP-потока | ≥2.1.0 | | 110016 | Шлюз находится в состоянии поиска onvif-камер | ≥2.1.0 | | 110017 | Превышено максимальное количество добавленных камер | ≥2.1.0 | | 110018 | Путь ESP-камеры указан неверно | ≥2.1.0 | | 110019 | Не удалось получить доступ к адресу сервиса стороннего устройства | ≥2.1.0 | #### e. Поиск под-устройства Разрешить авторизованным пользователям включать или отключать поиск шлюзом под-устройств через этот интерфейс * 💡Примечание: В настоящее время поддерживается только поиск Zigbee-под-устройств. * 💡Примечание: Zigbee-под-устройства будут добавлены автоматически после поиска. Не нужно использовать интерфейс "Ручное добавление под-устройств" :::tips * **URL**：/open-api/V2/rest/devices/discovery * **Метод**: PUT * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------------------------- | | enable | boolean | N | true (Начать сопряжение); false (Приостановить сопряжение) | | type | string | N | Тип поиска: Zigbee | Успешный ответ с данными: пустой объект {} :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\* `200 OK` ::: **Пример ответа**: ``` { "error": 0, "data": {}, "message": "success" } ``` #### f. Ручное добавление под-устройства Разрешить авторизованным пользователям добавить **одно** под-устройство через этот интерфейс. * Примечание: В настоящее время поддерживаются только RTSP-камера и ESP32-камера :::tips * **URL**：/open-api/V2/rest/devices * **Метод**：POST * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------------- | ------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------- | | name | string | N | Название под-устройства | | display\_category | string | N | Тип устройства. Поддерживается только камера. | | capabilities | CapabilityObject\[] | N | Список возможностей. Когда display\_category = camera, capabilities включает только возможности camera-stream. | | protocal | string | N | Протокол устройства. RTSP; ESP32-CAM | | manufacturer | string | N | Производитель. | | model | string | N | Модель устройства | | firmware\_version | string | N | Версия прошивки устройства | CapabilityObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------- | ------------------------------- | ----------------- | ------------------------------------------------------ | | capability | string | N | Имя возможности. Поддерживается только "camera-stream" | | permission | string | N | Разрешение устройства. Поддерживается только чтение. | | configuration | CameraStreamConfigurationObject | Y | Конфигурация потокового видео камеры. | SettingsObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------- | ------------------- | ----------------- | ------------------------------- | | streamSetting | StreamSettingObject | N | Конфигурация потокового сервиса | StreamSettingObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------------------ | ----------------- | -------------------------------------------------------------- | | type | string | N | Конфигурация потокового сервиса | | permission | string | N | Разрешение возможности. Поддерживает только "11" (изменяемое). | | value | StreamSettingValueObject | N | Конкретные значения конфигурации | StreamSettingValueObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----------------- | ----------------- | | stream\_url | string | N | Формат URL потока | | Формат:`://:/:@` | | | | | Пример:`rtsp://admin:123456@192.168.10.115:554/streaming/channel01` | | | | | Варианты схемы: | | | | | `rtsp` (Протокол потоковой передачи в реальном времени) | | | | | `http` (Протокол гипертекста) — для устройств ESP32-CAM | | | | | \*Примечание: Некоторые камеры могут не требовать имени пользователя или пароля. В таких случаях вы можете опустить `` и `` поля из URL. | | | | Успешный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------- | ------- | ----------------- | ------------------------------------ | | serial\_number | string | N | Уникальный серийный номер устройства | :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ``` { "error": 0, "data": { "serial_number": "serial_number" }, "message": "success" } ``` Данные об ошибке при неудаче: пустой объект :::tips **Условие**： 1. Ошибка доступа к адресу потока камеры (ошибка формата, ошибка авторизации, сетевые исключения и т.д.) 2. Устройство уже существует 3. Если добавление одного устройства не удалось, возвращается ошибка для всех устройств. **Код состояния**: 200 OK **Код ошибки**： ● 110009 Ошибка IP-адреса камеры ● 110010 Ошибка авторизации доступа к камере ● 110011 Ошибка адреса потока камеры ● 110012 Видео кодирование камеры не поддерживается ● 110013 Устройство уже существует ::: **Пример ответа**: ``` { "error": 110009, "data": {}, "message": "не удалось получить доступ к IP камеры" } ``` #### g. Получить список под-устройств Разрешить авторизованным пользователям получить список под-устройств шлюза через этот интерфейс. :::tips * **URL**：/open-api/V2/rest/devices * **Метод**: GET * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: нет Успешный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------ | ----------------------- | ----------------- | ---------------- | | device\_list | ResponseDeviceObject\[] | N | Список устройств | ResponseDeviceObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | --------------------- | ------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Уникальный серийный номер устройства | | third\_serial\_number | string | "N" когда подключено стороннее устройство, иначе "Y" | Уникальный серийный номер стороннего устройства | | service\_address | string | "N" когда подключено стороннее устройство, иначе "Y" | Адрес сервиса стороннего устройства | | name | string | N | Название устройства; если оно не переименовано, будет отображаться на фронтенде по правилам отображения по умолчанию. | | manufacturer | string | N | Производитель | | model | string | N | Модель устройства | | firmware\_version | string | N | Версия прошивки. Может быть пустой строкой. | | hostname | string | Y | Имя хоста устройства | | mac\_address | string | Y | MAC-адрес устройства | | app\_name | string | Y | Название приложения, к которому оно принадлежит. Если app\_name был заполнен при получении сертификата открытого интерфейса, тогда все последующие устройства, подключенные через этот сертификат, будут записаны в это поле. | | display\_category | string | N | Категория устройства | | capabilities | CapabilityObject\[] | N | Возможности устройства | | protocol | string | "N" когда подключено стороннее устройство, иначе "Y" | Протокол устройства: zigbee, onvif, rtsp, esp32-cam | | state | object | Y | Объект состояния устройства. Для примеров состояний различных возможностей, пожалуйста, проверьте 【Поддерживаемые возможности устройства】 | | теги | object | Y | JSON-формат ключ-значение, пользовательская информация об устройстве. Функция следующая: - Используется для хранения каналов устройства - Используется для хранения единиц температуры - Пользовательская информация для других сторонних устройств | | в сети | boolean | N | Статус онлайн: True — в сети False — не в сети | | подсеть | boolean | Y | Находится ли в той же подсети, что и шлюз | CapabilityObject 💡Примечание: Пожалуйста, проверьте Примеры поддерживаемых возможностей устройства в разделе \[Поддерживаемые возможности устройства]. | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | capability | string | N | Название возможности. Подробности смотрите в \[Поддерживаемые возможности устройства] | | permission | string | N | Разрешение возможности. Возможные значения: "read" (чтение), "write" (запись), "readWrite" (чтение и запись). | | configuration | object | Y | Информация о конфигурации возможности. В настоящее время используется camera-stream, см. \[Поддерживаемые возможности устройства] | | name | string | Y | Поле name в toggle. Номер подканала, используемый для идентификации многоканальных устройств. Например, если name равен 1, это означает канал 1. | :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ``` { "error": 0, "data":{ "device_list": [ { "serial_number": "ABCDEFGHIJK", "name": "Мое устройство", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "readWrite" }, { "capability": "rssi", "permission": "read" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ], } "message": "success" } ``` #### h. Обновить указанную информацию или состояние устройства Разрешить авторизованным пользователям изменять базовую информацию суб-устройства и отправлять команды управления через этот интерфейс. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Метод**：PUT * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | Y | Название устройства | | теги | object | Y | JSON-формат ключ-значение, пользовательская информация об устройстве. | | state | object | Y | Объект состояния устройства. Для примеров состояний различных возможностей, пожалуйста, проверьте \[Поддерживаемые возможности устройства] | | configuration | object | Y | Информация о конфигурации возможности, в настоящее время только возможность camera\_stream поддерживает изменение. | Успешный ответ с данными: :::tips **Условия**: Параметры запроса корректны и проверка подлинности пользователя пройдена. \*\*Код состояния: \*\*200 OK **Код ошибки**: * 110000 Соответствующее id суб-устройства/группы не существует ::: **Пример ответа**: ``` { "error": 0, "data":{ "serial_number": "ABCDEFGHIJK", "third_serial_number": "third_serial_number", "name": "我的设备", "manufacturer": "SONOFF", "model": "BASICZBR3", "firmware_version": "1.1.0", "display_category": "switch", "capabilities": [ { "capability": "power", "permission": "1100" }, { "capability": "rssi", "permission": "0100" } ], "protocal": "zigbee", "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true }, "message": "success" } ``` #### i. Удалить суб-устройство Разрешить авторизованным пользователям удалять суб-устройства через этот интерфейс. :::tips * **URL**：/open-api/V2/rest/devices/{serial\_number} * **Метод**：DELETE * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------ | -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | Y | Имя устройства. | | теги | object | Y | Пары ключ-значение в формате JSON, используемые для хранения имен каналов устройства и другой информации о суб-устройствах. | | state | object | Y | Изменить состояние устройства; для подробностей протокола см. "Поддерживаемые возможности устройства." | | capabilities | CapabilityObject \[] | Y | Информация о конфигурации возможности; все возможности, поддерживающие установку конфигураций, могут быть изменены. Обратите внимание, что разрешения нельзя менять. | Успешный ответ с данными: :::tips **Условия**: Параметры запроса корректны и проверка подлинности пользователя пройдена. \*\*Код состояния: \*\*200 OK **Коды ошибок:** * 110000: Соответствующее ID суб-устройства/группы не существует. * 110006: Не удалось обновить состояние устройства. * 110019: Не удалось обратиться к сервисному адресу третьей стороны. * 110024: Не удалось обновить конфигурацию устройства. ::: **Пример ответа**: ``` { "error": 0, "data": {}, "message": "success" } ``` ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // включить устройство await axios({ url: `http:///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 ::: **Пример ответа**: ```json { "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 | Запросить состояние устройства; для подробностей протокола см. "Поддерживаемые возможности устройства." | ```javascript import axios from 'axios'; const serial_number = 'serial_number'; const access_token = 'access_token'; (async function main() { // включить устройство await axios({ url: `http:///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 ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` ### 3.4 Управление безопасностью #### a. Получить список безопасности Позволяет авторизованным пользователям изменять настройки шлюза через этот интерфейс. :::tips * **URL**：`/open-api/v2/rest/security` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------- | ------------------------- | ----------------- | ------------------------- | | security\_list | ResponseSecurityObject\[] | N | список устройств в ответе | ResponseDeviceObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | --------------- | | sid | int | N | ID охраны | | name | string | N | Название охраны | | enable | bool | N | Включено ли | * true Включено * false Выключено | :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "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 ::: **Пример ответа**: ```json { "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 ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### d. Однокнопочная настройка охраны Позволяет авторизованным пользователям включить режим однокнопочной настройки охраны через этот интерфейс.\ :::tips * **URL**：`/open-api/v2/rest/security/enable` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: пустой объект {} :::tips **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` #### e. Отключить охрану Позволяет авторизованным пользователям отключить охрану через этот интерфейс.\ :::tips * **URL**：`/open-api/v2/rest/security/disable` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: Нет Успешный ответ с данными: пустой объект {} :::tips **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\*200 OK ::: **Пример ответа**: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 4. Доступ третьих сторон к устройствам ### 4.1 Инструкция по доступу #### Доступ устройства
#### Доступ стороннего шлюза
#### Шаги доступа 1. Определите классификацию устройства в шлюзе. Подробности см. \[Поддерживаемые типы устройств]. 2. Определите возможности, к которым устройство может получить доступ. Подробности см. \[Поддерживаемые возможности устройства]. 3. Вызовите интерфейс \[Discovery Request], чтобы добавить устройство в шлюз. 1. *Внимание: Вам необходимо предоставить адрес сервиса для получения инструкций, выданных шлюзом, который используется для получения команд управления устройством, выданных шлюзом*. 4. Если статус стороннего устройства изменился, вам нужно вызвать интерфейс \[Device States Change Report], чтобы отправить последнее состояние обратно в шлюз. 5. После добавления стороннее устройство появится в Списке устройств, с большинством функций шлюза (в отличие от других не-сторонних устройств). Общие открытые интерфейсы, связанные с устройством, смогут использоваться в обычном режиме. * Выберите соответствующую категорию устройства. Классификация повлияет на конечное отображение в пользовательском интерфейсе после подключения устройства к шлюзу. * Выберите правильную способность устройства. Список возможностей определит протокол состояния устройства. #### Процесс программирования **a. Доступ устройства**
**b. Доступ стороннего шлюза**
### 4.2 Пример доступа #### Переключатель, Розетка **Синхронизировать сторонние устройства** ``` // Запрос URL：/open-api/v2/rest/thirdparty/event Метод：POST Заголовок： Content-Type: application/json Autorization: Bearer Тело: { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "2" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "my plug", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "1100" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "версия прошивки", "service_address": "http://192.168.31.14/webhook" } ] } } } ``` ``` { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number", "serial_number": "серийный номер" } ] } } ``` **Сообщить состояние устройства** ``` URL：/open-api/V2/rest/thirdparty/event Метод：POST Заголовок： Content-Type: application/json Autorization: Bearer Тело: { "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： Метод：POST Заголовок：  Content-Type: application/json B {  "directive": {    "header": {      "name": "UpdateDeviceStates",      "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4",      "version": "1"   },    "endpoint": {      "third_serial_number": "third_serial_number",      "serial_number": "serial_number"   },    "payload": {       "state": : {         "power": {           "powerState": "on"         }       }   } } } ``` ``` { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": {} } ``` **Запросить устройство** ``` URL：/open-api/V2/rest/devices Метод：GET Заголовок：  Content-Type: application/json  Autorization: Bearer   Тело: Нет ``` ``` { "error": 0, "data": { "device_list": [ { "serial_number": "серийный номер", "third_serial_number": "third_serial_number", "name": "my plug", "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "версия прошивки", "display_category": "plug", "capabilities": [ { "capability": "power", "permission": "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "online": true } ] }, "message": "success" } ``` ### 4.3 Веб-API #### Интерфейс запроса третьей стороны к шлюзу **Формат запроса** Разрешает авторизованным пользователям отправлять события в шлюз через этот интерфейс. :::tips * **URL**：/open-api/V2/rest/thirdparty/event * **Метод**：POST * **Заголовок**： * Content-Type: application/json * Autorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------- | ----------------- | --------------------------------- | | event | EventObject | N | Структура объекта события запроса | EventObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | -------------- | ----------------- | --------------------------------------------------------------------------------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | endpoint | EndpointObject | Y | Структура endpoint в запросе Примечание: Это поле пустое при синхронизации нового списка устройств. | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | string | N | Имя запроса. необязательный параметр: DiscoveryRequest: Синхронизировать новые устройства DeviceStatesChangeReport: Отчет об обновлении состояния устройства DeviceOnlineChangeReport: Отчет о статусе онлайн устройства | | message\_id | string | N | ID сообщения запроса, UUID\_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | EndpointObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | --------------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Уникальный серийный номер устройства | | third\_serial\_number | string | N | Уникальный серийный номер стороннего устройства | | теги | object | Y | JSON-формат ключ-значение, пользовательская информация об устройстве. \[Функция управления устройством] - \[Описание тегов] | PayloadObject В зависимости от header.name различается структура запроса. **Формат ответа** :::tips \*\*Код состояния: \*\*200 OK **Параметры ответа:** ::: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | -------------------------- | | header | HeaderObject | N | Структура заголовка ответа | | payload | PayloadObject | N | Структура payload ответа | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Имя заголовка ответа. необязательные параметры: Response: Успешный ответ ErrorResponse: Ответ с ошибкой | | message\_id | string | N | ID сообщения заголовка ответа, UUID\_V4. Передайте сюда message\_id из заголовка запроса \*Если входной параметр запроса не содержит message\_id, это поле будет пустой строкой в ответе. | | version | string | N | - Номер версии протокола запроса. В настоящее время фиксирован на 1. | > Успешный ответ--PayloadObject ： В зависимости от типа запроса структура ответа различается. Для подробностей см. документ конкретного запроса. > Ответ при ошибке--PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ------------ | | type | string | N | Типы ошибок: | * INVALID\_PARAMETERS: Ошибка параметров * AUTH\_FAILURE: Ошибка авторизации * INTERNAL\_ERROR: Внутренняя ошибка сервиса | | description | string | N | Описание ошибки | **DiscoveryRequest Синхронизировать новый список устройств** * Примечание: После синхронизации устройства в шлюз оно по умолчанию в сети, то есть online=true. Последующие изменения online полностью зависят от синхронизации с третьей стороной через интерфейс DeviceOnlineChangeReport. **Параметры запроса:** EndpointObject\*\*：\*\*Нет PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------------- | ----------------- | ---------------- | | endpoints | EndpointObject\[] | N | Список устройств | EndpointObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | --------------------- | ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | third\_serial\_number | string | N | Уникальный серийный номер стороннего устройства | | name | string | N | Название устройства | | display\_category | string | N | Категория устройства. Подробности см. в \[Поддерживаемые типы устройств]. \*Сторонние устройства сейчас не поддерживают добавление камер. | | capabilities | CapabilityObject\[] | N | Список возможностей | | state | object | N | Начальная информация о состоянии | | manufacturer | string | N | Производитель | | model | string | N | Модель устройства | | теги | object | Y | JSON-формат ключ-значение, пользовательская информация об устройстве: Используется для хранения каналов устройства Используется для хранения единиц температуры Другие пользовательские данные третьих сторон | | firmware\_version | string | N | Версия прошивки | | service\_address | string | N | Адрес сервиса. Например | Пример запроса : ``` { "event": { "header": { "name": "DiscoveryRequest", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "endpoints": [ { "third_serial_number": "third_serial_number_1", "name": "my plug", "display_category": "plug", "capabilities": [ { "capability": "power", "permission" "readWrite" } ], "state": { "power": { "powerState": "on" } }, "tags": { "key": "value" }, "manufacturer": "manufacturer name", "model": "model name", "firmware_version": "версия прошивки", "service_address": "http://192.168.31.14/service_address" } ] } } } ``` **Параметры ответа:** PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------------- | ----------------- | ---------------- | | endpoints | EndpointObject\[] | N | Список устройств | EndpointObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | --------------------- | ------- | ----------------- | ----------------------------------------------- | | serial\_number | string | N | Уникальный серийный номер устройства | | third\_serial\_number | string | N | Уникальный серийный номер стороннего устройства | Пример корректного ответа: ``` { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "endpoints": [ { "serial_number": "серийный номер", "third_serial_number": "third_serial_number" } ] } } ``` Пример ответа с ошибкой: ``` { "header": { "name": "ErrorResponse", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "webhook не может быть пустым" } } ``` **DeviceStatesChangeReport Отчет об изменении состояния устройства** * Примечание: Повторяющиеся отчеты о состоянии могут неправильно сработать связанные сцены. **Параметры запроса:** PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------------------------------------------- | | state | object | N | Состояние устройства, см. подробности в \[Поддерживаемые возможности устройства] | Пример запроса : ``` { "event": { "header": { "name": "DeviceStatesChangeReport", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Параметры ответа:** PayloadObject: Пустой объект Пример успешного ответа: ``` { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": {} } ``` **DeviceOnlineChangeReport Отчет о статусе онлайн устройства** * Примечание: Повторяющиеся отчеты о состоянии могут неправильно сработать связанные сцены. **Параметры запроса:** PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ---------------- | ------- | ----------------- | ------------------------------------- | | в сети | boolean | N | Статус онлайн устройства true: В сети | | false: Не в сети | | | | Пример запроса : ``` { "event": { "header": { "name": "DeviceOnlineChangeReport", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "2" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number" }, "payload": { "online": true } } } ``` **Параметры ответа:** PayloadObject: Пустой объект Пример успешного ответа: ``` { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": {} } ``` **DeviceInformationUpdatedReport Отчет об обновлении информации об устройстве** * Примечание: Обновление может повлиять на существующие сцены или функции безопасности. **Параметры запроса:** PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------ | ------- | ----------------- | ------------ | | capabilities | | | | \| CapabilityObject\[] \| N \| Список возможностей. Подробности можно найти в разделе поддерживаемых возможностей устройства. \*\*Примечание: \*\*Этот параметр обновит только `value` из `настройки` ключ внутри `CapabilityObject`, и обновления разрешены только если `permission` для `настройки` ключа является `11` или `01`. Для конкретного определения структуры `настройки` в `CapabilityObject`смотрите подробное описание в разделе 2.3 Категории отображения устройств и возможности устройства. | | tags \| объект \| Y \| JSON-формат ключ-значение, пользовательская информация об устройстве. * Может быть использовано для хранения каналов устройства * Может быть использовано для хранения единиц температуры * Другие пользовательские данные третьих сторон | Пример запроса : ```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: Пустой объект Пример успешного ответа: ```json { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "2" }, "payload": {} } ``` #### Шлюз отправляет интерфейс инструкции через адрес сервиса устройства * Примечание: 1. Сторонние должны ответить на запрос шлюза в течение 3 секунд. В противном случае шлюз сочтет выполнение команды вышедшим по таймауту. 2. Если сервис третьей стороны оффлайн, шлюз установит устройство в состояние оффлайн, и стороннему сервису потребуется сообщить состояние устройства (DeviceStatesChangeReport) или онлайн-состояние (DeviceOnlineChangeReport), прежде чем вернуться в онлайн. **Формат запроса** Шлюз отправляет инструкции третьей стороне через интерфейс адреса сервиса устройства. :::tips * **URL**： * **Метод**：POST * **Заголовок**： * Content-Type: application/json ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | --------------- | ----------------- | ---------------------------------------- | | directive | DirectiveObject | N | Информация о структуре объекта директивы | DirectiveObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | -------------- | ----------------- | ---------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | endpoint | EndpointObject | N | Структура endpoint в запросе | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------------------------------------------------------- | | name | string | N | Имя запроса. Необязательные параметры: UpdateDeviceStates: Обновить состояния устройства | | message\_id | string | N | ID сообщения запроса, UUID\_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1. | EndpointObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | --------------------- | ------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- | | serial\_number | string | N | Уникальный серийный номер устройства | | third\_serial\_number | string | N | Уникальный серийный номер стороннего устройства | | теги | object | N | JSON-формат ключ-значение, пользовательская информация об устройстве. \[Функция управления устройством] - \[Описание тегов] | PayloadObject: В зависимости от различных `header.name`, для каждого имеется конкретная структура запроса. Пример запроса : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "endpoint": { "serial_number": "serial_number", "third_serial_number": "third_serial_number", "tags": {} }, "payload": { "state": { "power": { "powerState": "on" } } } } } ``` **Формат ответа** :::tips \*\*HTTP Код состояния: \*\*200 OK **Атрибуты HTTP-ответа：** ::: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------- | ----------------- | ------------------------ | | event | EventObject | N | Структура события ответа | EventObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | --------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | name | string | N | Имя заголовка ответа. Необязательный параметр: UpdateDeviceStatesResponse: Ответ на обновление состояний устройства ErrorResponse: Ответ с ошибкой | | message\_id | string | N | ID сообщения заголовка ответа, UUID\_V4. Передайте сюда message\_id из заголовка запроса | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1. | > Успешный ответ--PayloadObject： В зависимости от типа запроса структура ответа различается. Для подробностей см. документ конкретного запроса. > Ответ при ошибке--PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------- | | type | string | N | **Типы ошибок**: | * **ENDPOINT\_UNREACHABLE**: Устройство недоступно или оффлайн * **ENDPOINT\_LOW\_POWER**: Устройство в режиме низкого энергопотребления и не может быть управляемо * **INVALID\_DIRECTIVE**: Аномальная директива от шлюза * **NO\_SUCH\_ENDPOINT**: Устройство не существует * **NOT\_SUPPORTED\_IN\_CURRENT\_MODE**: Текущий режим не поддерживает операцию * **INTERNAL\_ERROR**: Внутренняя ошибка сервиса * **REMOTE\_KEY\_CODE\_NOT\_LEARNED**: Код клавиши пульта дистанционного управления не выучен | :::советы **Условия**: Параметры запроса корректны. \*\*Код состояния: \*\*200 OK **Параметры ответа:** ::: ``` { "event": { "header": { "name": "UpdateDeviceStatesResponse", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": {} } } ``` ``` { "event": { "header": { "name": "ErrorResponse", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "type": "ENDPOINT_UNREACHABLE" } } } ``` **UpdateDeviceStates** **Параметры запроса:** PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | --------------------------------------------------------------------------------- | | state | object | N | Состояние устройства, см. подробности в \[Поддерживаемые возможности устройства]. | Пример запроса : ``` { "directive": { "header": { "name": "UpdateDeviceStates", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "endpoint": { "serial_number": "serial_number" }, "payload": { "state": : { "power": { "powerState": "on" } } } } } ``` **Параметры ответа:** PayloadObject：пустой объект Пример успешного ответа ``` { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": {} } ``` **QueryDeviceStates** **Параметры запроса:** PayloadObject： | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | --------------------------------------------------------------------------------- | | state | object | N | Состояние устройства, см. подробности в \[Поддерживаемые возможности устройства]. | Пример запроса : ```json { "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 | Состояние устройства, см. подробности в \[Поддерживаемые возможности устройства]. | **Пример ответа:** ```json { "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 нельзя изменить, при передаче синхронизации указывайте то же значение. | Пример запроса : ```json { "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：пустой объект Пример успешного ответа ```json { "event": { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "2" }, "payload": {} } } ``` ## 5. События, отправляемые сервером > Описание интерфейса MDN EventSource： ### 5.1 Инструкция Шлюз поддерживает отправку сообщений клиенту с помощью SSE (Server-sent events). Клиент может мониторить сообщения SSE после получения учетных данных доступа и разбирать содержимое push-сообщений в соответствии с протоколом уведомлений о событиях интерфейса разработки после получения сообщений, отправленных шлюзом. Следует отметить, что шлюз в настоящее время использует протокол HTTP1.1, поэтому в браузере для SSE существует ограничение максимум не более 6 соединений (Подробные инструкции см. в описании интерфейса MDN EventSource.) ### 5.2 Общий формат :::советы * **URL**：/open-api/V2/sse/bridge * **Метод**：`GET` ::: Параметры запроса: | Имя | Тип | Необязательно | Описание | | ------------- | ------ | ------------- | ------------- | | access\_token | string | N | Токен доступа | Примечание: При запросе соединения SSE шлюз проверяет access\_token, и при недействительном токене вернет ошибку аутентификации. { "error": 401, "data": {}, "message": "invalid access\_token"} > \## Например: Имя модуля: device Версия: 1,v2,v3 Тип сообщения: addDevice Пример: ```javascript const evtSource = new EventSource("http:///open-api/v2/sse/bridge?access_token=xxxxxx"); evtSource.addEventListener('device#v2#addDevice',function (event) { try { const data = JSON.parse(event.data); console.log('data', data); } catch (error) { console.error(`parse error`,error); } } ``` ### 5.3 Модуль устройства #### a. Событие добавления устройства :::tips Имя модуля：device Версия：v2 Тип сообщения：addDevice event.data параметры： ::: | Имя | Тип | Необязательно | Описание | | ------- | ----------------------------------------------------------------------------------- | ------------- | ------------------------ | | payload | ResponseDeviceObjectObject - Интерфейс такой же, как при получении списка устройств | N | Информация об устройстве | Пример: ```json // 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 | Уникальный серийный номер стороннего устройства. Для устройств, подключенных через открытые интерфейсы, это поле обязательно. | Пример: ```json // 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-формат ключ-значение для пользовательской информации об устройстве. | * Может быть использовано для хранения каналов устройства. * Может быть использовано для хранения единиц температуры. * Для других пользовательских данных третьих сторон. | Пример: ```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 | Уникальный серийный номер стороннего устройства. Для устройств, подключенных через открытые интерфейсы, это поле обязательно. | Пример: ```json // 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 | Статус онлайн устройства | Пример: ```json // 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` | Выключено | Пример: ```json // 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 | Название охраны | Пример ```json // event.data { "payload": { "arm_state": "arming", "detail": { "sid": 1, "name": "Home Mode" } } } ``` ## 6. TTS (**Функция движка синтеза речи (Text-to-Speech)** ### 6.1 Инструкция #### Ключевая роль * Поставщик TTS-сервиса: поставщик сервиса движка TTS отвечает за регистрацию TTS-движка на шлюзе и предоставление TTS-услуг * Сервер шлюза：iHost * Клиент Gateway Open API #### 6.1.1 Регистрация сервиса движка TTS 1. 【Поставщик TTS-сервиса】Вызывает интерфейс для регистрации TTS-движка на шлюзе. 2. 【Сервер шлюза】После успешной регистрации шлюз сохранит базовую информацию о TTS-движке (включая адрес сервиса server\_address, и последующая связь между шлюзом и поставщиком TTS-сервиса будет происходить через адрес server\_address), а также выделит идентификатор сервиса TTS в пределах шлюза.
#### 6.1.2 Получение списка синтезированных аудиофайлов 1. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка зарегистрированных TTS-сервисов. Вы можете получить текущий список зарегистрированных TTS-движков (включая идентификатор TTS-движка, выделенный шлюзом). 2. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка аудиофайлов указанного TTS-движка. Шлюз отправит синхронную команду списка аудио указанному поставщику TTS-сервиса и вернёт результат.
#### 6.1.3 Синтез речи с указанием движка синтеза 1. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка зарегистрированных TTS-сервисов. Вы можете получить текущий список зарегистрированных TTS-движков (включая идентификатор TTS-движка, выделенный шлюзом). 2. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка аудиофайлов указанного TTS-движка. Шлюз отправит синхронную команду списка аудио указанному поставщику TTS-сервиса и вернёт результат.
#### 6.1.4 Синтез аудио и воспроизведение TTS-речи. 1. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка зарегистрированных TTS-сервисов. Вы можете получить текущий список зарегистрированных TTS-движков (включая идентификатор TTS-движка, выделенный шлюзом). 2. 【Клиент Gateway Open API】Вызывает интерфейс для получения списка аудиофайлов указанного TTS-движка. Шлюз отправит синхронную команду списка аудио указанному поставщику TTS-сервиса и вернёт результат. (включая адрес файла TTS-аудио) 3. 【Клиент Gateway Open API】Фиксирует адрес TTS-аудиофайла из результата, возвращённого на предыдущем шаге, вызывает интерфейс воспроизведения аудиофайла и воспроизводит его через шлюз. ### 6.2 Модуль TTS-движка #### 6.2.1 Открытые возможности шлюза **a. Получить список зарегистрированных TTS-сервисов** :::советы * **URL**：`/open-api/V2/rest/tts/engines` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: отсутствуют Корректный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ---------------- | ----------------- | ------------------------------------- | | engines | EngineObject \[] | N | Список зарегистрированных TTS-движков | Структура EngineObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------- | | id | string | N | Идентификатор движка, назначенный шлюзом | | name | string | N | Название сервиса TS-движка | :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` **Пример ответа:**： ::: ```json { "error": 0, "data": { "engines": [ { "id": "engine id", "name": "engine name" } ] }, "message": "success" } ``` **b. Получить список аудио указанного TTS-движка** :::советы * **URL**：`/open-api/V2/rest/tts/engine/{id}/audio-list` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: отсутствуют Корректный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | --------------- | ----------------- | ------------ | | audio\_list | AudioObject \[] | N | Список аудио | Структура AudioObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------------------------------------------------- | ------- | ----------------- | ------------------------- | | url | string | N | URL аудиофайла, например: | | | | | | | label | string | Y | Метка аудиофайла | :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` \*\*Код ошибки: \*\* * 190000 Движок работает с ошибкой **Пример ответа:**： ::: ```json { "error": 0, "data": { "audio_list": [ { "url": "адрес tts-аудио", // например: https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "метка tts-аудио" } ] }, "message": "success" } ``` **c. Выполнение синтеза речи с использованием указанного TTS-движка** :::советы * **URL**：`/open-api/V2/rest/tts/engine/{id}/synthesize` * **Метод**：`POST` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Текст, используемый для синтеза аудио | | label | string | Y | Метка аудиофайла | | language | string | Y | Прозрачное поле. Необязательный код языка для запроса синтеза речи. Конкретный список поддерживаемых кодов языков предоставляется сервисом TTS-движка. Обратите внимание, что сервис TTS-движка должен поддерживать язык по умолчанию для синтеза, что означает, что если язык не передан, будет использован язык по умолчанию движка для синтеза. | | options | object | Y | Прозрачное поле. Используется для передачи конфигурационных параметров, требуемых для синтеза, сервису TTS-движка. | Корректный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------- | ----------------- | ------------ | | audio | AudioObject | N | Список аудио | Структура AudioObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------------------------------------------------- | ------- | ----------------- | ------------------------- | | url | string | N | URL аудиофайла, например: | | | | | | | label | string | Y | Метка аудиофайла | :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` \*\*Код ошибки: \*\* * 190000 Движок работает с ошибкой **Пример ответа:**： ::: ```json { "error": 0, "data": { "audio": { "url": "адрес tts-аудио" // например, https://dl.espressif.cn/dl/audio/gs-16b-2c-44100hz.mp3 "label": "метка tts-аудио" } }, "message": "success" } ``` #### 6.2.2 Взаимодействие между шлюзом и TTS-сервисом **a. Регистрация сервиса TTS-движка** > Отправка запроса на шлюз от поставщика TTS-сервиса :::советы * **URL**：`/open-api/V2/rest/thirdparty/event` * **Метод**：`POST` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------- | ----------------- | -------------------------------------------- | | event | EventObject | N | Структура объекта события запроса Информация | EventObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | --------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ------------------------------------- | | name | string | N | Имя запроса. Необязательный параметр. | * RegisterTTSEngine | | message\_id | string | N | Идентификатор сообщения запроса, UUID\_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | PayloadObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ---------------- | ------- | ----------------- | ---------------------------------- | | service\_address | string | N | Адрес сервиса. Например, http\:/// | | name | string | N | Название сервиса | Пример запроса: ```json { "event": { "header": { "name": "RegisterTTSEngine", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "service_address": "service_address", "name": "название tts-сервиса" } } } ``` \*\*Корректные параметры ответа: \*\* | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | --------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------------- | | name | string | N | Имя заголовка ответа. Необязательный параметр: | * Ответ (Успешный ответ) * ErrorResponse (Ошибка ответа) | | message\_id | string | N | Идентификатор сообщения заголовка ответа, UUID\_V4. Входящее здесь сообщение запроса: header.message\_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | PayloadObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------- | | engine\_id | string | N | Идентификатор движка, назначенный шлюзом | :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` **Пример ответа:**： ::: Пример корректного ответа:： ```json { "header": { "name": "Response", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "engine_id": "идентификатор движка" } } ``` \*\*Параметры ненормального ответа: \*\* | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ------------ | | type | string | N | Тип ошибки | * INVALID\_PARAMETERS (Ошибка параметров) * AUTH\_FAILURE (Ошибка аутентификации) * INTERNAL\_ERROR (Внутренняя ошибка сервиса) | | description | string | N | Описание ошибки | Пример ответа с ошибкой:： ```json { "header": { "name": "ErrorResponse", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address не может быть пустым" } } ``` **b. Команда синхронизации списка аудио** > Отправка команды поставщику TTS-сервиса от шлюза. :::советы * **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 | Идентификатор сообщения запроса, UUID\_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | Пример запроса: ```json { "directive": { "header": { "name": "SyncTTSAudioList", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": {} } } ``` \*\*Корректные параметры ответа: \*\* | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | --------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------------- | | name | string | N | Имя заголовка ответа. Необязательный параметр: | * Ответ (Успешный ответ) * ErrorResponse (Ошибка ответа) | | message\_id | string | N | Идентификатор сообщения заголовка ответа, UUID\_V4. Входящее здесь сообщение запроса: header.message\_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | PayloadObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | --------------- | ----------------- | ---------------- | | audio\_list | AudioObject \[] | N | Список TTS-аудио | Структура AudioObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------------------------------------------------- | ------- | ----------------- | ------------------------- | | url | string | N | URL аудиофайла, например: | | | | | | | label | string | Y | Метка аудиофайла | :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` **Пример ответа:**： ::: Пример корректного ответа:： ```json { "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 | Описание ошибки | Пример ответа с ошибкой:： ```json { "header": { "name": "ErrorResponse", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address не может быть пустым" } } ``` **c. Команда синтеза речи** > Отправка команды поставщику TTS-сервиса от шлюза. :::советы * **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 | Идентификатор сообщения запроса: UUID\_V4 | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | PayloadObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | text | string | N | Текст, используемый для синтеза аудио | | label | string | Y | Метка аудиофайла | | language | string | Y | Прозрачное поле. Необязательный код языка для запроса синтеза речи. Конкретный список поддерживаемых кодов языков предоставляется сервисом TTS-движка. Обратите внимание, что сервис TTS-движка должен поддерживать язык по умолчанию для синтеза, что означает, что если язык не передан, будет использован язык по умолчанию движка для синтеза. | | options | object | Y | Прозрачное поле. Используется для передачи конфигурационных параметров, требуемых для синтеза, сервису TTS-движка. | Пример запроса: ```json { "directive": { "header": { "name": "SynthesizeSpeech", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "text": "Входной текст для синтеза.", "label": "метка tts-аудио" } } } ``` \*\*Корректные параметры ответа: \*\* | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | --------------------------- | | header | HeaderObject | N | Структура заголовка запроса | | payload | PayloadObject | N | Структура payload в запросе | HeaderObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | ---------------------------------------------- | | name | string | N | Имя заголовка ответа. Необязательный параметр: | * Ответ (Успешный ответ) * ErrorResponse (Ошибка ответа) | | message\_id | string | N | Идентификатор сообщения заголовка ответа, UUID\_V4. Входящее здесь сообщение запроса: header.message\_id | | version | string | N | Номер версии протокола запроса. В настоящее время фиксирован на 1 | PayloadObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ----------- | ----------------- | ------------ | | audio | AudioObject | N | TTS-аудио | Структура AudioObject | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------------------------------------------------- | ------- | ----------------- | ------------------------- | | url | string | N | URL аудиофайла, например: | | | | | | | label | string | Y | Метка аудиофайла | :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` **Пример ответа:**： ::: Пример корректного ответа:： ```json { "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 | Описание ошибки | Пример ответа с ошибкой:： ```json { "header": { "name": "ErrorResponse", "message_id": "Уникальный идентификатор, предпочтительно UUID версии 4", "version": "1" }, "payload": { "type": "INVALID_PARAMETERS", "description": "service_address не может быть пустым" } } ``` ## 7. Модуль мультимедиа ### 7.1 Воспроизведение аудиофайла :::советы * **URL**：`/open-api/V2/rest/media/audio-player` * **Метод**：`POST` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | --------------- | | audio\_url | string | N | Адрес URL аудио | Корректный ответ с данными: :::подсказка Условия: Параметры запроса корректны, проверка удостоверения пользователя пройдена. \*\*Код состояния: \*\*`200 OK` **Пример ответа:**： ::: ```json { "error": 0, "data": {}, "message": "success" } ``` ## 8. Пользовательская UI-карта Пользовательские UI-карты позволяют отображать любое содержимое внутри карты. Это содержимое может быть веб-страницей, изображением или любым сервисом с пользовательским интерфейсом. Вам нужно лишь предоставить URL содержимого, которое вы хотите отобразить. UI-карта автоматически подстроит ширину и высоту, а содержимое будет отображаться с помощью iFrame. ### 8.1 Инструкция #### Ключевая роль * **Поставщик UI-сервиса**: Поставщик, отвечающий за создание пользовательских UI-карт на шлюзе. * **Сервер шлюза**: Сервер шлюза (iHost). * **Клиент Gateway Open API**: Клиент Open API для шлюза. #### 8.1.1 Создание пользовательской UI-карты * **\[Поставщик UI-сервиса]**: Вызывает API для создания пользовательской UI-карты на шлюзе. * **\[Сервер шлюза]**: После успешной регистрации шлюз сохраняет базовую информацию о UI-карте (включая конфигурацию размера и URL ресурса карты) и присваивает внутренний идентификатор UI-карты в пределах шлюза.
#### 8.1.2 Получение списка UI-карт * **\[Поставщик UI-сервиса]**: Вызывает API для получения списка UI-карт. * **\[Сервер шлюза]**: Возвращает список UI-карт, сохранённых на шлюзе, включая пользовательские UI-карты, не созданные вызывающей стороной.
#### 8.1.3 Изменение конфигурации указанной UI-карты * **\[Поставщик UI-сервиса]**: Вызывает API для изменения конфигурации указанной UI-карты, например конфигурации размера и URL ресурса. * **\[Сервер шлюза]**: После успешного изменения шлюз сохраняет обновлённую информацию о UI-карте, включая новую конфигурацию размера и URL ресурса.
#### 8.1.4 Удаление пользовательской UI-карты 1. **\[Поставщик UI-сервиса]**: Вызывает API для удаления указанной пользовательской UI-карты. 2. **\[Сервер шлюза]**: Шлюз удалит всю информацию, связанную с указанной UI-картой.
### 8.2 Модуль пользовательских UI-карт #### 8.2.1 Создание пользовательской UI-карты > Поставщик UI-сервиса отправляет запрос на шлюз для создания пользовательской UI-карты. :::советы * **URL**：`/open-api/v2/rest/ui/cards` * **Метод**：`POST` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------- | ------------------ | ----------------- | ------------------------------------------------------------------ | | label | string | Y | Метка карты: используется для описания карты. Это псевдоним карты. | | cast\_settings | CastSettingsObject | Y | Настройки Cast-карты: конфигурационные параметры для cast-карт. | | web\_settings | WebSettingsObject | N | Настройки Web-карты: конфигурационные параметры для web-карт. | CastSettingsObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------------- | ----------------- | ------------------------------------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Конфигурация размеров: должна включать по крайней мере одну конфигурацию. | | default | string | N | Спецификация по умолчанию: используется стандартная конфигурация размера, необязательные параметры: 2x2 | WebSettingsObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------------- | ------------------- | ----------------- | ------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Конфигурация размеров: должна включать по крайней мере одну конфигурацию. | | drawer\_component | DrawerObject | Y | Настройки отображения компонента drawer. | | default | string | N | Спецификация по умолчанию: | * 1x1 * 2x1 | DimensionObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------------------------------------- | ------- | ----------------- | -------------------------------------------- | | src | string | N | URL ресурса: например: | | size | string | N | Спецификации размера: | | Необязательные параметры CastSettingsObject: | | | | * 2×2 Необязательные параметры WebSettingsObject: * 1x1 * 2x1 | DrawerObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------- | | src | string | N | URL ресурса: например: | Успешный ответ с данными: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | --------------------------------- | | id | string | N | Уникальный идентификатор UI-карты | :::советы **Условия**: Параметры запроса являются корректными, и проверка идентичности пользователя пройдена. \*\*Код состояния: \*\* `200 OK` ::: Пример запроса： ```json { "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" } } ``` Пример ответа: ```json { "error": 0, "data": { "id": "72cc5a4a-f486-4287-857f-b482d7818b16" }, "message": "success" } ``` #### 8.2.2 Получение списка UI-карт :::советы * **URL**：`/open-api/v2/rest/ui/cards` * **Метод**：`GET` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: отсутствуют Параметры ответа: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------------- | ----------------- | -------------- | | data | CardObject\[] | N | Список UI-карт | Объект CardObjec: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------- | ------------------ | ----------------- | ------------------------------------------------------------------------------------- | | id | string | N | ID карты: уникальный идентификатор карты. | | label | string | Y | Метка карты: используется для описания карты. Служит псевдонимом или названием карты. | | cast\_settings | CastSettingsObject | Y | Метка карты: используется для описания карты. Это псевдоним карты. | | web\_settings | WebSettingsObject | N | Настройки Cast-карты: конфигурационные параметры для cast-карт. | | app\_name | string | Y | Настройки Web-карты: конфигурационные параметры для web-карт. | CastSettingsObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ---------------------------- | ------------------- | ----------------- | ------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Конфигурация размеров: должна включать по крайней мере одну конфигурацию. | | default | string | N | Спецификация по умолчанию: | | Необязательный параметр: 2x2 | | | | | used | string | N | Текущая спецификация: | | Необязательный параметр: 2x2 | | | | WebSettingsObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------------------ | ------------------- | ----------------- | ------------------------------------------------------------------------- | | dimensions | DimensionObject \[] | N | Конфигурация размеров: должна включать по крайней мере одну конфигурацию. | | drawer\_component | DrawerObject | Y | Настройки отображения компонента drawer. | | default | string | N | Спецификация по умолчанию: | | Необязательный параметр: | | | | * 1x1 * 2x1 | | used | string | N | Текущая спецификация: Необязательный параметр: * 1x1 * 2x1 | DimensionObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------------------ | ------- | ----------------- | -------------------------------------------- | | src | string | N | URL ресурса: например: | | size | string | N | Спецификации размера: | | Необязательный параметр: | | | | * 1x1 * 2x1 **Примечание**: В настоящее время cast-карты поддерживают только спецификацию 2x2. Спецификация 2x2 не будет действовать. | DrawerObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ----------- | ------- | ----------------- | -------------------------------------------- | | src | string | N | URL ресурса: например: | Пример ответа: ```json { "error": 0, "data": [ { "id": "72cc5a4a-f486-4287-857f-b482d7818b16", "label": "ewelink cube card", "cast_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×2" } ], "default": "2×2", "used": "2×2" }, "web_settings": { "dimensions": [ { "src": "https://ewelink.cc/ewelink-cube/", "size": "2×1" }, { "src": "https://ewelink.cc/ewelink-cube/", "size": "1×1" } ], "drawer_component": { "src": "https://ewelink.cc/ewelink-cube/" }, "default": "2×1", "used": "2×1" }, "appName": "ewelink-cube" } ], "message": "success" } ``` #### 8.2.3 Изменение конфигурации указанной UI-карты > Авторизованные пользователи могут изменить конфигурацию существующей UI-карты через этот интерфейс. Поставщики сервисов пользовательских карт могут изменять только UI-карты, которые они создали. :::советы * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Метод**：`PUT` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | -------------- | ------------------ | ----------------- | ----------------------------------------------------- | | label | string | Y | Используется для описания карты. Это псевдоним карты. | | cast\_settings | CastSettingsObject | Y | Настройки Cast-карты | | web\_settings | WebSettingsObject | Y | Настройки Web-карты | CastSettingsObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------- | --------------------- | | used | string | Y, Либо `used` или `src` должен быть предоставлен, но требуется как минимум один из этих параметров. | Текущая спецификация: | | Необязательный параметр: | | | | * 2x2 \| | src | string | Y, Либо `used` или `src` должен быть предоставлен, но требуется как минимум один из этих параметров. | URL ресурса: | WebSettingsObject: | **Атрибут** | **Тип** | **Необязательно** | **Описание** | | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------- | --------------------- | | used | string | Y, Либо `used` или `src` должен быть предоставлен, но требуется как минимум один из этих параметров. | Текущая спецификация: | | Необязательный параметр: | | | | * 1x1 * 2x1 | | src | string | Y, Либо `used` или `src` должен быть предоставлен, но требуется как минимум один из этих параметров. | URL ресурса: | Успешный ответ с данными: :::tips **Условия**: Параметры запроса корректны, проверка удостоверения пользователя пройдена. UI-карта, которую изменяют, должна быть создана поставщиком пользовательских UI-карт, вызывающим интерфейс. \*\*Код состояния: \*\* `200 OK` **Код ошибки:** * **406**: Нет разрешения на доступ к этому ресурсу ::: \*\*Пример ответа: \*\* ```json { "error": 0, "data": {}, "message": "success" } ``` \*\*Пример запроса: \*\* ```json { "cast_settings": { "used": "2×2" }, "web_settings": { "used": "1×1" } } ``` #### 8.2.4 Удаление пользовательской UI-карты > Авторизованные пользователи имеют право удалять существующую UI-карту с помощью этого интерфейса. Поставщики пользовательских карт могут удалять только UI-карты, которые они создали. :::советы * **URL**：`/open-api/v2/rest/ui/cards/{id}` * **Метод**：`DELETE` * **Заголовок**： * Content-Type: application/json * Authorization: Bearer ::: Параметры запроса: отсутствуют Успешный ответ с данными: :::подсказка **Условия**: Параметры запроса корректны, проверка удостоверения пользователя пройдена. UI-карта, которую изменяют, должна быть создана поставщиком пользовательских UI-карт, вызывающим интерфейс. \*\*Код состояния: \*\* `200 OK` **Код ошибки:** * **406**: Нет разрешения на доступ к этому ресурсу. ::: \*\*Пример ответа: \*\* ```json { "error": 0, "data": {}, "message": "success" } ```