Version: 2

ConnectHome Butler API

Загальне

Для локального доступу до точки входу для HTTP API використовується http://{controller-ip}/api/v2/, де controller-ip - IP адреса контролера в локальній мережі, а v2 - версія API.

Кожний виклик API має бути автентифікованим, за винятком тих, де це зазначено обернено.

Аутентифікація

Існують два методи аутентифікації, які можуть бути використані в контролері.

Базова аутентифікація

Це стандартна базова HTTP аутентифікація.

Кожний виклик API повинен містити заголовок Authorization, значення якого повинно бути закодоване в Base64 комбінацією username, крапка-кома(:) і password, перед цим додаючи Basic .

Наприклад, для користувача з ім'ям користувача admin та паролем 12345678 вірний заголовок буде: Authorization: Basic YWRtaW46MTIzNDU2Nzg= де YWRtaW46MTIzNDU2Nzg= - закодовано в Base64 admin:12345678.

Аутентифікація на основі токенів

Для цього методу, користувач повинен отримати токен з виклику POST /api/v2/auth/login, використовуючи Базову аутентифікацію

У випадку успішної відповіді буде містити токен (див. посилання для формату відповіді)

Кожний наступний запит повинен містити наступний заголовок:

Authorization: Bearer abcdefg1234567

де abcdefg1234567 - це раніше отриманий токен.

Кожен токен має свій термін дії, який оновлюється при кожному запиті.

Визначення контролера

Щоб знайти всі контролери в локалній мережі, клієнтська програма повинна слухати на довільному UDP порту та відправляти розповсюджені пакети на порт 17318 наступного формату:

CONNECTHOME_BUTLER_DETECT{listening_port}

тобто, якщо клієнтська програма слухає на порті 20000, то вірний пакет буде CONNECTHOME_BUTLER_DETECT20000.

У відповідь на броадкастовий пакет, всі контролери відповідатимуть UDP JSON пакетом на цей порт. Формат:

{
  "name": "Ім'я контролера",
  "ip": "192.168.1.123",
  "mac": "01:23:45:67:89:AB"
}

Повідомлення про помилки

Усі помилки, що виникли під час обробки запиту, повідомляються наступним чином

{
  "errorMessage":"Повідомлення про помилку",
  "errorCode":1,
  "errorParameters":{}
}

де errorParameters є необов'язковим та містить поля, що є специфічними для кожного коду помилки (див. таблицю нижче)

Коди помилок (Робота в процесі)

Код помилки	Опис	Параметри
0	Помилки немає

Сутності

Розділ

Елемент, який інкапсулює кімнати в зручні, задані користувачем групи. Має наступні властивості:

id - ціле число
name - рядок

API Reference

Кімната

Кімната - це кімната.

Має наступні властивості:

id - ціле число
name - рядок
section_id - ціле число, id батьківського розділу
order - ціле число, порядок сортування в розділі
background_image - рядок, назва зображення тла
icon - рядок, назва іконки з попереднього набору іконок
main_devices - колекція пов'язаних датчиків (пристроїв)
- temperature_sensor - ціле число, id пристрою
- humidity_sensor - ціле число
- luminosity_sensor - ціле число

API Reference

Пристрій

Пристрій - основна сутність в контролері, він представляє будь-який інтерактивний об'єкт.

Тип та можливості пристрою можуть бути визначені двома властивостями:

type - основний тип пристрою, дозволяє визначити, які інтерфейси пристрій обов'язково повинен підтримувати (див. таблицю нижче)
interfaces - список інтерфейсів. Тут під інтерфейсом мається на увазі колекція підтриманих параметрів та дій (див. таблицю нижче)

Загалом пристрій визначається наступними властивостями:

id - ціле число
name - рядок
room_id - ціле число, id батьківської кімнати
type - рядок, описаний вище
role - рядок, роль пристрою
icon - рядок, назва іконки з попереднього набору іконок
order - ціле число, порядок сортування в кімнаті
hidden - булеве значення, видимість пристрою в Інтерфейсі користувача
interfaces - масив рядків, описаний вище
params - об'єкт, колекція параметрів пристрою
note_text - Текст нотатки пристрою
note_image - Зображення для нотатки пристрою ПОВИННО бути завантажено через storage API

Типи пристроїв (У розробці)

Тип пристрою	Опис	Обов'язкові інтерфейси
DevGateway	Шлюз (контролер Z-Wave)	Gateway
DevSwitch	Бінарний перемикач	SwitchBinary
DevDimmer	Димер світла	SwitchMultilevel, SwitchBinary
DevShutter	Ролети	SwitchMultilevel, SwitchBinary, Shutter
DevSwitchMultilevel	Невідомий багатопозиційний перемикач	SwitchMultilevel, SwitchBinary
DevBinarySensor	Бінарний датчик	SensorBinary
DevTemperature	Датчик температури	SensorMultilevel
DevHygrometry	Датчик вологості	SensorMultilevel
DevLuminosity	Датчик освітленості	SensorMultilevel
DevGenericSensor	Інші типи багатозональних датчиків	SensorMultilevel
DevThermostat	Термостат HVAC	Принаймні один із: ThermostatMode, ThermostatSetpoint, ThermostatOperatingState, ThermostatFanMode
DecDimmerColor	RGB(W) димер	SwitchMultilevel, SwitchColor, SwitchBinary
DevUnknown	Невизначений пристрій	-

примітка

Усі пристрої Z-Wave також матимуть інтерфейс ZWaveDevice

Параметри інтерфейсів (В процесі)

Інтерфейс	Назва параметра	Опис	Тип параметра
ZWave Device	nodeId	Ідентифікатор вузла пристрою в мережі ZWave	ціле число
Multichannel Endpoint	endpointId	Ідентифікатор кінцевої точки	ціле число
-	parentDeviceId	Ідентифікатор батьківського пристрою	ціле число
Switch Binary	Status	Статус бінарного перемикача (true = увімкнено, false = вимкнуто, для багаторівневих перемикачів false означає вимкнено, true - ненульовий рівень)	булеве значення
-	pulseable	Чи може перемикач бути пульсованим	булеве значення
Switch Multilevel	Рівень	Рівень багаторівневого перемикача (0-99, де 0 - вимкнено, а 99 - повна потужність)	ціле число
Version	firmwareVersion	Версія(и) прошивки пристрою	масив цілих чисел
Association	groupsCount	Кількість груп асоціацій	ціле число
-	multichannelSupported	Чи підтримуються багаторівневі асоціації	булеве значення
-	associations	Асоційовані пристрої пристроєм	json
Sensor Binary	armable	Вказує, чи може датчик бути включений у захищений стан	булеве значення
-	ackable	Показує, чи є у датчика можливість підтвердження користувачем	булеве значення
-	Armed	Чи включений стан	булеве значення
-	Tripped	Стан датчика (true - спрацьовано, false - спокійний)	булеве значення
-	lasttrip	Останній раз, коли пристрій був спрацьований (у форматі UNIX часу)	ціле число
Sensor Multilevel	Значення	Значення датчика	дробове число
-	sensorType	Тип датчика (наразі, це може бути один з: Температура, Вологість, Світлота, Потужність)	рядок
-	valueScale	Масштаб датчика (залежить від типу датчика)	рядок
-	valueUnit	Одиниці вимірювання датчика (залежить від типу датчика)	рядок
Shutter	stopable	Чи можна зупинити ролети (ігноруйте це, сумісність ISS)	булеве значення
Thermostat Mode	currentMode	Поточний режим термостата (один з `availableModes`)	рядок
-	availableModes	Доступні режими термостата	json
Thermostat Setpoint	currentSetpoints	Поточні установки(WIP)	json
Thermostat OperatingState	currentState	Поточний стан термостата (WIP)	рядок
SwitchColor	supportedComponents	Підтримувані кольорові компоненти, звільнені пристроєм	масив json рядків, підтримувані варіанти елементів: `ТеплийБілий`, `Холодний Білий`, `Червоний`,`Зелений`, `Синій`, `Бурштиновий`, `Ціан`, `Ліловий`, `Індексований`
-	currentComponentValues	Значення поточно підтримуваних компонентів	json об'єкт, що містить ключ-значення для кольорових компонентів (наприклад `{"Червоний":100, "Зелений":50, "Синій":"200"}`)

API Reference

<div
  style={{"marginBottom":"2rem"}}
>
  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"HTTP: Basic Auth"}
      value={"Basic"}
    >
      
      
      Це стандартна [базова HTTP аутентифікація](https://en.wikipedia.org/wiki/Basic_access_authentication).
       
      Кожний виклик API повинен містити заголовок `Authorization`, значення якого повинно бути Base64-кодованою комбінацією `username`, двокрапки (:) і `password`, з передставленням `Basic `. 
      
      Наприклад, для користувача з ім'ям користувача `admin` та пароля `12345678`, правильний заголовок буде:

Authorization: Basic YWRtaW46MTIzNDU2Nzg=

де `YWRtaW46MTIzNDU2Nzg=` - це Base64-кодоване значення `admin:12345678`.

<div>
  <table>
    <tbody>
      <tr>
        <th>
          Security Scheme Type:
        </th><td>
          http
        </td>
      </tr><tr>
        <th>
          HTTP Authorization Scheme:
        </th><td>
          basic
        </td>
      </tr>
    </tbody>
  </table>
</div>
</TabItem><TabItem
label={"HTTP: Bearer Auth"}
value={"Token"}
>


Для використання цього методу користувач має отримати токен за допомогою виклику `POST /api/v2/auth/login` з використанням [Базової Аутентифікації](#section/Authentication/Basic-Authentication)

У разі успішного відгуку відповідь буде містити токен (див. [посилання](#tag/Authorization) на формат відповіді)

Кожний наступний запит повинен містити наступний заголовок:
 

Authorization: Bearer abcdefg1234567

де `abcdefg1234567` - це отриманий раніше токен.
:::note

Доступовий токен має час спливу, коли він закінчується, **Оновлювальний Токен** повинен бути використаний для отримання нового.
:::

<div>
  <table>
    <tbody>
      <tr>
        <th>
          Security Scheme Type:
        </th><td>
          http
        </td>
      </tr><tr>
        <th>
          HTTP Authorization Scheme:
        </th><td>
          bearer
        </td>
      </tr>
    </tbody>
  </table>
</div>
</TabItem>
</SchemaTabs>
</div><div
style={{"display":"flex","flexDirection":"column","marginBottom":"var(--ifm-paragraph-margin-bottom)"}}
>
<h3
style={{"marginBottom":"0.25rem"}}
>
Contact
</h3><span>
me: 
</span>
</div>

ConnectHome Butler API

Аутентифікація

Базова аутентифікація​

Аутентифікація на основі токенів​

Визначення контролера

Повідомлення про помилки

Коди помилок (Робота в процесі)​

Сутності

Розділ​

Кімната​

Пристрій​

Типи пристроїв (У розробці)​

Параметри інтерфейсів (В процесі)​

Базова аутентифікація

Аутентифікація на основі токенів

Коди помилок (Робота в процесі)

Розділ

Кімната

Пристрій

Типи пристроїв (У розробці)

Параметри інтерфейсів (В процесі)