Прошивка UMNI UNI

• Универсальный REST API для управления устройствами
• REST API v1.0
• Формат MQTT сообщений
• Описание протокола сообщений MQTT v1.0

Универсальный REST API для управления устройствами

REST API v1.0

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

Внимание! Не подключайте контроллер в публичную сеть Интернет! Вместо этого используйте локальную сеть, или выделенную подсеть для безопасного администрирования контроллера и прокси сервера (Nginx, Apache как обратный прокси).

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

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

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

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

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

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

GET /api/systeminfo

Ответ

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

Пояснения

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

Получение конфигурации

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

GET /api/conf?section={string}

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

adc

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

ntc

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

dio

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

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

rf433

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

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

POST /api/settings

Тело запроса

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

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

{
  "en": bool, 
  "host": string, 
  "port": int, 
  "user": ?string, 
  "password": ?string
}

{
  "en": bool, 
  "url": string
}

outputs

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

inputs

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

ntc

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

adc

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

onewire

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

rf433

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

opentherm

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

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

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

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

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

{
    // Системные настройки
    "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"
  }
 

Внимание! После установки token, все запросы к API должны идти с заголовком 'Authorization': 'Bearer my_token', либо с передачей параметра запроса &token=my_token  в URL.

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

POST /api/switch

Тело запроса

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

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

• outputs
• opencollectors

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

• для outputs 1-8

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

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

POST /api/wifi/scan

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

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

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

POST /api/beep

тело запроса

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

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

POST /api/state

Тело запроса

{
  "capability": string
}

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

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

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

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

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

GET /api/automations

Ответ

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

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

POST /api/automations

Тело запроса

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

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

PUT /api/automations/{id}

Тело запроса

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

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

{
  "success": true,
  "data": {
    "state": {
      "value": 27.62923812866211
    },
    "history": {
      "name": "ntc1",
      "timestamps": [
        1777483230583
      ],
      "values": [
        27.62923812866211
      ],
      "count": 1
    }
  }
}

Формат MQTT сообщений

Описание протокола сообщений MQTT v1.0

Publish

/LWT

device/umni-838a74/lwt 

{
  "state":"online"
}

{
  "state":"offline"
}

/PONG

device/umni-838a74/pong

{
  "ping":"pong"
}

/REGISTER

device/umni-838a74/register

{
  "hostname": "umni-838a74",
  "capabilities": [
    "ethernet",
    "sdcard",
    ...
  ],
  "networks": [
    {
      "name": "ethernet",
      "ip": "192.168.88.122",
      "mask": "255.255.252.0",
      "gw": "192.168.88.9",
      "active": true
    }
  ],
  "heap": {
    "total": 383104,
    "free": 191552,
    "min": 178628
  },
  "device_type": "generic"
}

/CONFIG (onewire)

device/umni-838a74/config

{
  "key":"onewire",
  "config":{
    "sensors":[
      {
        "sn":"F7062454B2EE5528",
        "label":"Sensor F7062454B2EE5528",
        "active":true
      }
    ]
  }
}

/CONFIG (rf433)

device/umni-838a74/config

{
  "key":"rf433",
  "config":{
    "devices":[]
  }
}

/CONFIG (ntc)

device/umni-838a74/config

{
  "key":"ntc",
  "config":{
    "channels":[
      {
        "id":0,
        "label":"NTC Sensor 1",
        "active":true
      },
      {
        "id":1,
        "label":"NTC Sensor 2",
        "active":true
      }
    ]
  }
}

/CONFIG (adc)

device/umni-838a74/config 

{
  "key":"adc",
  "config":{
    "channels":[
      {
        "id":0,
        "label":"ADC Input 1",
        "active":true
      },
      {
        "id":1,
        "label":"ADC Input 2",
        "active":true
      }
    ]
  }
}

/CONFIG (inputs)

device/umni-838a74/config

{
  "key": "inputs",
  "config": {
    "inputs": [
      {
        "config_index": 1,
        "port_index": 1,
        "label": "Input 1 (port 1)",
        "active": true
      },
      ...
    ],
  }
}

/SENSORS (onewire)

device/umni-838a74/sensors

{
  "category": "onewire",
  "capability":"onewire",
  "value":28.25,
  "serial":"F7062454B2EE5528"
}

/SENSORS (ntc)

device/umni-838a74/sensors

{
  "category": "ntc",
  "capability":"ntc1",
  "value":27.906805038452148,
  "serial":null
}

/SENSORS (adc)

device/umni-838a74/sensors

{
  "category": "adc",
  "capability":"ai1",
  "value":27.906805038452148,
  "serial":null
}

 /SENSORS (outputs)

device/umni-838a74/sensors:

{
  "category": "outputs",
  "capability":"out2",
  "value":1,
  "serial":null
}

/SENSORS (inputs)

device/umni-838a74/sensors: 

{
  "category": "inputs",
  "capability":"inp4",
  "value":0,
  "serial":null
}

/SENSORS (outputs)

device/umni-838a74/sensors: 

{
  "key": "dio",
  "config": {
    "outputs": [
      {
        "config_index": 1,
        "port_index": 0,
        "label": "Output 1 (port 0)",
        "active": true,
        "default_state": 0
      },
      ...
    ]
  }
}

Subscribe

Ping

device/umni-838a74/ping

Payload ""