# REST API v1.0

## Спецификация протокола REST API

<p class="callout warning">Внимание! Не подключайте контроллер в публичную сеть Интернет! Вместо этого используйте локальную сеть, или выделенную подсеть для безопасного администрирования контроллера и прокси сервера (Nginx, Apache как обратный прокси).</p>

### Формат данных ответа

Каждый ответ от контроллера формируется в виде JSON строки и имеет вид

```json
{
  "success": true,
  "data": {...}
}
```

Свойство data имеет внутри состояние запрашиваемого функционала.

### Список методов

Получение системной информации

```bash
GET /api/systeminfo
```

Ответ

```json
{
  "success": true,
  "data": {
    "hostname": "umni-838a74",
    "capabilities": [
      "ethernet",
      "sdcard",
      "webserver",
      "mqtt",
      "opentherm",
      "rf433",
      "onewire",
      "alarm",
      "ntc1",
      "ntc2",
      "ai1",
      "ai2",
      "opencollectors",
      "oc1",
      "oc2",
      "buzzer",
      "inputs",
      "inp1",
      "inp2",
      "inp3",
      "inp4",
      "inp5",
      "inp6",
      "outputs",
      "out1",
      "out2",
      "out3",
      "out4",
      "out5",
      "out6",
      "out7",
      "out8"
    ],
    "networks": [
      {
        "name": "ethernet",
        "mac": "44:1d:64:83:8a:77",
        "ip": "192.168.88.122",
        "mask": "255.255.252.0",
        "gw": "192.168.88.9",
        "active": true
      }
    ],
    "heap": {
      "total": 380928,
      "free": 190464,
      "min": 166876
    }
  }
}
```

##### Пояснения

<table border="1" id="bkmrk-hostname-%D0%B8%D0%BC%D1%8F-%D1%83%D1%81%D1%82%D1%80%D0%BE%D0%B9%D1%81" style="border-collapse: collapse; width: 100%; height: 106.188px;"><colgroup><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col><col style="width: 33.3731%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">hostname</td><td style="height: 29.7969px;">имя устройства</td><td style="height: 29.7969px;">строка</td></tr><tr style="height: 46.5938px;"><td style="height: 46.5938px;">capabilities</td><td style="height: 46.5938px;">список доступных возможностей контроллера</td><td style="height: 46.5938px;">массив строк</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">networks</td><td style="height: 29.7969px;">список сетевых подключений</td><td style="height: 29.7969px;">объект</td></tr><tr><td>heap</td><td>список общей и доступной оперативной памяти</td><td>объект</td></tr></tbody></table>

##### Возможности контроллера (capabilities)

<table border="1" id="bkmrk-ethernet-%D1%83%D1%81%D1%82%D1%80%D0%BE%D0%B9%D1%81%D1%82%D0%B2%D0%BE-" style="border-collapse: collapse; width: 100%; height: 983.298px;"><colgroup><col style="width: 50.0596%;"></col><col style="width: 50.0596%;"></col></colgroup><tbody><tr style="height: 29.7969px;"><td style="height: 29.7969px;">ethernet</td><td style="height: 29.7969px;">устройство использует проводное подключение</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">wifi</td><td style="height: 29.7969px;">устройство использует wifi</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">sdcard</td><td style="height: 29.7969px;">устройство использует microSD карту памяти</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">webserver</td><td style="height: 29.7969px;">устройство использует веб-сервер</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">mqtt</td><td style="height: 29.7969px;">устройство использует клиента mqtt</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">opentherm</td><td style="height: 29.7969px;">устройство использует opentherm (для газовых котлов)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">rf433</td><td style="height: 29.7969px;">устройство использует беспроводной канал 433 мГц</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">onewire</td><td style="height: 29.7969px;">устройство использует onewire</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">alarm</td><td style="height: 29.7969px;">у устройства есть вывод по датчики наличия 12в</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">ntc1</td><td style="height: 29.7969px;">у устройства есть NTC термистор №1 (резистор 10К)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">ntc2</td><td style="height: 29.7969px;">у устройства есть NTC термистор №2 (резистор 10К)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">ai1</td><td style="height: 29.7969px;">у устройства имеется аналоговый вход №1</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">ai2</td><td style="height: 29.7969px;">у устройства имеется аналоговый вход №2</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">opencollectors</td><td style="height: 29.7969px;">устройство имеет выходы "открытый коллектор"</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">oc1</td><td style="height: 29.7969px;">устройство имеет выход открытого коллектора №1</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">oc2</td><td style="height: 29.7969px;">устройство имеет выход открытого коллектора №2</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">buzzer</td><td style="height: 29.7969px;">устройство имеет на своем борту бипер (buzzer)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inputs</td><td style="height: 29.7969px;">устройство имеет цифровые входы</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inp1</td><td style="height: 29.7969px;">устройство имеет цифровой вход №1</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inp2</td><td style="height: 29.7969px;">устройство имеет цифровой вход №2</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inp3</td><td style="height: 29.7969px;">устройство имеет цифровой вход №3</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inp4</td><td style="height: 29.7969px;">устройство имеет цифровой вход №4</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inp5</td><td style="height: 29.7969px;">устройство имеет цифровой вход №5</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">inp6</td><td style="height: 29.7969px;">устройство имеет цифровой вход №6</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">outputs</td><td style="height: 29.7969px;">устройство имеет цифровые выходы (релейные выходы)</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out1</td><td style="height: 29.7969px;">устройство имеет выход №1</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out2</td><td style="height: 29.7969px;">устройство имеет выход №2</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out3</td><td style="height: 29.7969px;">устройство имеет выход №3</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out4</td><td style="height: 29.7969px;">устройство имеет выход №4</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out5</td><td style="height: 29.7969px;">устройство имеет выход №5</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out6</td><td style="height: 29.7969px;">устройство имеет выход №6</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out7</td><td style="height: 29.7969px;">устройство имеет выход №7</td></tr><tr style="height: 29.7969px;"><td style="height: 29.7969px;">out8</td><td style="height: 29.7969px;">устройство имеет выход №8</td></tr></tbody></table>

<span style="color: rgb(187, 187, 187); font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Oxygen, Ubuntu, Roboto, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; font-size: 1.666em; font-weight: 400;">Получение конфигурации</span>

Возвращает JSON объект конфигурации для указанной секции

```
GET /api/conf?section={string}
```

##### Список ответов конфигурационных секций

**adc**

```json
{
  "success": true,
  "data": {
    "channels": [
      {
        "id": 0,
        "label": "ADC Input 1",
        "active": true
      },
      {
        "id": 1,
        "label": "ADC Input 2",
        "active": true
      }
    ]
  }
}
```

**ntc**

```json
{
  "success": true,
  "data": {
    "channels": [
      {
        "id": 0,
        "label": "NTC Sensor 1",
        "active": true
      },
      {
        "id": 1,
        "label": "NTC Sensor 2",
        "active": true
      }
    ]
  }
}
```

**dio**

```json
{
  "success": true,
  "data": {
    "inputs": [
      {
        "config_index": 1,
        "port_index": 1,
        "label": "Input 1 (port 1)",
        "active": true
      },
      ...
    ],
    "outputs": [
      {
        "config_index": 1,
        "port_index": 0,
        "label": "Output 1 (port 0)",
        "active": true,
        "default_state": 0
      },
      ...
    ]
  }
}
```

**onewire**

```json
{
  "success": true,
  "data": {
    "sensors": [
      {
        "sn": "F7062454B2EE5528",
        "label": "Sensor F7062454B2EE5528",
        "active": true
      }
    ]
  }
}
```

**rf433**

```json
{
  "success": true,
  "data": {
    "devices": []
  }
}
```

#### Сохранение конфигурации (сенсоры)

```
POST /api/settings
```

Тело запроса

```json
{
  "setting": "{setting}",
  "values": {...{values}}
}
```

<table border="1" id="bkmrk-setting-%D0%BA%D0%BB%D1%8E%D1%87-%D0%BD%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>setting</td><td>ключ настройки</td></tr><tr><td>values</td><td>значения настройки (объект)</td></tr></tbody></table>

##### Типы тела POST запроса для ключа настройки

<div id="bkmrk-mqtt"><div>**mqtt**</div><div>  
</div></div>```json
{
  "en": bool, 
  "host": string, 
  "port": int, 
  "user": ?string, 
  "password": ?string
}
```

<div id="bkmrk-webhook"><div>**webhook**</div><div>  
</div></div>```json
{
  "en": bool, 
  "url": string
}
```

**outputs**

```json
{
  "en": bool, 
  "label": ?string, 
  "index": int
}
```

**inputs**

```json
{
  "en": bool, 
  "label": ?string, 
  "index": int
}
```

**ntc**

```json
{
  "channel":int,
  "active": bool,
  "offset":float,
  "label":string
}
```

**adc**

```json
{
  "channel":int,
  "active": bool,
  "offset":float,
  "label":string
}
```

**onewire**

```json
{
  "serial": string,
  "label": string,
  "active" : bool,
  "calibration": float
}
```

**rf433**

```json
{
  "mode": ?string, //null or delete
  "serial": number, 
  "label": string, 
  "alaram": bool, 
  "type": number
}
```

**opentherm**

```json
{
  "en": bool,
  "ch_en": bool,
  "ch_sp": int,
  "dhw_en": bool,
  "dhw_sp": int,
  "ch2_en": bool,
  "cool_en": bool,
  "mod": int,
  "otc_en": bool
}
```

Пояснения по параметрам

<table border="1" id="bkmrk-en-%D0%90%D0%BA%D1%82%D0%B8%D0%B2%D0%B5%D0%BD-%D0%BB%D0%B8-openth" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>en</td><td>Активен ли Opentherm в контроллере. Вы можете отключить и не использовать этот функционал.</td></tr><tr><td>ch\_en</td><td>Флаг активации режима отопления. При установке значения true, включится режим нагрева теплоносителя на контур отопления.</td></tr><tr><td>ch\_sp</td><td>Пороговое значение температуры теплоносителя, которое будет поддерживаться в контуре отопления при нагреве теплоносителя.</td></tr><tr><td>dhw\_en</td><td>Флаг активации режима горячего водоснабжения. Если отключен, котел не будет включать контур горячей воды или переключать трехходовой клапан (Buderus U072)</td></tr><tr><td>dhw\_sp</td><td>Пороговое значение температуры теплоносителя в контуре горячего водоснабжения.</td></tr><tr><td>ch2\_en</td><td>Второй контур отопления.</td></tr><tr><td>cool\_en</td><td>Охлаждение</td></tr><tr><td>mod</td><td>Уровень модуляции (0-100)</td></tr><tr><td><div><div>otc_en</div></div></td><td>Outside temperature compensation. Режим компенсации температуры по наружному датчику.</td></tr></tbody></table>

Конфигурация устройства (чтение)

```
GET /api/configuration
```

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

```
{
  "success": true,
  "data": {
    "title": "My Device",
    "username": "admin",
    "password": null,
    "ntp": "pool.ntp.org",
    "timezone": "MSK-3",
    "socket_port": 8080,
    "token": "secret123",
    "network_mode": 1,
    "wifi_sta_ssid": "HomeWiFi",
    "wifi_sta_password": null,
    "wifi_sta_ip_type": 2,
    "wifi_sta_ip": "192.168.1.100",
    "wifi_sta_netmask": "255.255.255.0",
    "wifi_sta_gateway": "192.168.1.1",
    "wifi_sta_dns": "8.8.8.8",
    "wifi_ap_ssid": "HomeWiFi",
    "wifi_ap_password": null,
    "eth_ip_type": 1,
    "eth_ip": "192.168.1.200",
    "eth_netmask": "255.255.255.0",
    "eth_gateway": "192.168.1.1",
    "eth_dns": "8.8.8.8"
  }
}
```

#### Конфигурация устройства (сохранение)

```
POST /api/configuration
```

Тело запроса (элементы можно передавать не все, а выборочно)

```json
{
    // Системные настройки
    "title": "My Device",
    "username": "admin",
    "password": "1234",
    "ntp": "pool.ntp.org",
    "timezone": "MSK-3",
    "socket_port": 514,
    "token": "secret_token",
 
    // Настройки сети
    "network_mode": 1,           // 1-ETH, 2-WIFI_AP
 
    // Настройки WiFi STA
    "wifi_sta_ssid": "MyWiFi",
    "wifi_sta_password": "pass123",
    "wifi_sta_ip_type": 1,       // 1-DHCP, 2-STATIC
    "wifi_sta_ip": "192.168.1.100",
    "wifi_sta_netmask": "255.255.255.0",
    "wifi_sta_gateway": "192.168.1.1",
    "wifi_sta_dns": "8.8.8.8",
 
    // Настройки WiFi AP
    "wifi_ap_ssid": "UMNI_AP",
    "wifi_ap_password": "",
    "wifi_ap_channel": 6,
    "wifi_ap_max_connections": 4,
    "wifi_ap_hidden": false,
 
    // Настройки Ethernet
    "eth_ip_type": 1,            // 1-DHCP, 2-STATIC
    "eth_ip": "192.168.1.100",
    "eth_netmask": "255.255.255.0",
    "eth_gateway": "192.168.1.1",
    "eth_dns": "8.8.8.8"
  }
 
```

<p class="callout warning">**Внимание!** После установки token, все запросы к API должны идти с заголовком 'Authorization': 'Bearer my\_token', либо с передачей параметра запроса &amp;token=my\_token в URL.</p>

#### Переключение цифровых выходов

```bash
POST /api/switch
```

Тело запроса

```json
{
  "mode": "{mode}",
  "index": 1,
  "level": true|false
}
```

Возможные значения mode:

- outputs
- opencollectors

Возможные значения index:

- для outputs 1-8

Возможные значения level 0-1

##### Получение списка Wifi ctntq

```
POST /api/wifi/scan
```

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

```json
{
  "success": true,
  "data": [
    {
      "ssid": string,
      "rssi": int,
      "channel": int,
      "authmode": int,
      "authmode_name": string
    }
  ]
}
```

##### Работа с оповещателем (пьезоизлучатель)

```bash
POST /api/beep
```

тело запроса

```json
{
  "count": int, // >= 16
  "on_ms":int // 0 >= 1000,
  "off_ms":int //  0 >= 1000
}
```

##### Чтение данных сенсоров

```
POST /api/state
```

Тело запроса

```json
{
  "capability": string
}
```

Формат ответа

```json
{
  "success": true,
  "data": {
    "state": {
      "value": 0
    },
    "history": {
      "name": string,
      "timestamps": [ ],
      "values": [ ],
      "count": int
    }
  }
}
```

#### Автоматизации

Контроллеры поддерживают автоматизации - это правила в виде JSON данных, которые выполняются при срабатывании определенных условий (состоянии сенсоров).

##### Получение списка автоматизаций

```
GET /api/automations
```

Ответ

```json
[
  {
    "id": 1,
    "if": {
      "capability": "ntc1",
      "op": ">",
      "value": 30.0
    },
    "then": [
      { "capability": "out1", "action": 1 }
    ],
    "else": [
      { "capability": "out1", "action": 0 }
    ]
  }
]
```

##### Создание автоматизации

```
POST /api/automations
```

Тело запроса

```json
 {
   "if": {
     "capability": "ntc1",
     "op": ">",
     "value": 30.0
   },
   "then": [
     { "capability": "out1", "action": 1 }
   ],
   "else": [
     { "capability": "out1", "action": 0 }
   ]
 }
```

##### Обновление автоматизации

```
PUT /api/automations/{id}
```

Тело запроса

```json
{
  "if": {
    "capability": "ntc1",
    "op": ">",
    "value": 35.0
  },
  "then": [
    { "capability": "out1", "action": 1 },
    { "capability": "opentherm", "subtype": "ch", "action": 1 }
  ],
  "else": [
    { "capability": "out1", "action": 0 }
  ]
}
```

##### Удаление автоматизации

```
DELETE /api/automations/{id}
```

### Возможные значения - значения capabilities

<div id="bkmrk--1"></div><table border="1" id="bkmrk-opentherm-%7B-%22success" style="border-collapse: collapse; width: 100%;"><colgroup><col style="width: 50%;"></col><col style="width: 50%;"></col></colgroup><tbody><tr><td>opentherm</td><td>```
{
  "success": true,
  "state": {
    "ot_enabled": true,
    "ready": true,
    "adapter_success": false,
    "status_code": 3,
    "ch_enable": false,
    "ch_setpoint_requested": 60,
    "dhw_enable": true,
    "dhw_setpoint_requested": 50,
    "otc_enable": false,
    "cooling_enable": false,
    "ch2_enable": false,
    "modulation_level_set": 0,
    "heat_curve_ratio": 0,
    "central_heating_active": false,
    "hot_water_active": false,
    "flame_on": false,
    "is_fault": false,
    "boiler_temperature": 0,
    "return_temperature": 0,
    "dhw_temperature": 0,
    "outside_temperature": 0,
    "dhw_setpoint_current": 0,
    "ch_max_setpoint": 0,
    "modulation": 0,
    "pressure": 0,
    "flow_rate": 0,
    "flow_rate_ch2": 0,
    "fault_code": 0,
    "boiler_config": {
      "control_type": "ON/OFF",
      "dhw_present": false,
      "dhw_config": "INSTANTANEOUS",
      "ch2_present": false,
      "cooling_supported": false,
      "pump_control_allowed": false,
      "slave_ot_version": 0,
      "slave_product_version": 0
    },
    "bounds": {
      "ch": {
        "min": 0,
        "max": 0
      },
      "dhw": {
        "min": 0,
        "max": 0
      },
      "heat_curve": {
        "min": 0,
        "max": 0
      }
    }
  }
}
```

</td></tr><tr><td>ntc1</td><td>```
{
  "success": true,
  "data": {
    "state": {
      "value": 27.62923812866211
    },
    "history": {
      "name": "ntc1",
      "timestamps": [
        1777483230583
      ],
      "values": [
        27.62923812866211
      ],
      "count": 1
    }
  }
}
```

  
</td></tr><tr><td>ntc2</td><td>аналогично ntc1</td></tr><tr><td>ai1</td><td>аналогично ntc1</td></tr><tr><td>ai2</td><td>аналогично ntc1</td></tr><tr><td>  
</td><td>  
</td></tr><tr><td>  
</td><td>  
</td></tr></tbody></table>