> For the complete documentation index, see [llms.txt](https://cube.ewelink.cc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cube.ewelink.cc/cube-os-ru/resursy/rukovodstvo-dlya-razrabotchikov-i-api.md). # Руководство для разработчиков и 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" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://cube.ewelink.cc/cube-os-ru/resursy/rukovodstvo-dlya-razrabotchikov-i-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.