Прошивка UMNI UNI

Техническое описание программного обеспечения контроллера автоматизации УМНЫЙ К1

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

Данная глава описывает REST API для взаимодействия с универсальной прошивкой (программным обеспечением) контроллера УМНЫЙ К1.

Основной упор сделан на простоту интеграций, автономность и децентрализованность.

REST API может использоваться в связке с любым языком программирования, поддерживающим работу с протоколом HTTP

Универсальный 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
    }
  }
}
Пояснения
hostname имя устройства строка
capabilities список доступных возможностей контроллера массив строк
networks список сетевых подключений объект
heap список общей и доступной оперативной памяти объект
Возможности контроллера (capabilities)
ethernet устройство использует проводное подключение
wifi устройство использует wifi
sdcard устройство использует microSD карту памяти
webserver устройство использует веб-сервер
mqtt устройство использует клиента mqtt
opentherm устройство использует opentherm (для газовых котлов)
rf433 устройство использует беспроводной канал 433 мГц
onewire устройство использует onewire
alarm у устройства есть вывод по датчики наличия 12в
ntc1 у устройства есть NTC термистор №1 (резистор 10К)
ntc2 у устройства есть NTC термистор №2 (резистор 10К)
ai1 у устройства имеется аналоговый вход №1
ai2 у устройства имеется аналоговый вход №2
opencollectors устройство имеет выходы "открытый коллектор"
oc1 устройство имеет выход открытого коллектора №1
oc2 устройство имеет выход открытого коллектора №2
buzzer устройство имеет на своем борту бипер (buzzer)
inputs устройство имеет цифровые входы
inp1 устройство имеет цифровой вход №1
inp2 устройство имеет цифровой вход №2
inp3 устройство имеет цифровой вход №3
inp4 устройство имеет цифровой вход №4
inp5 устройство имеет цифровой вход №5
inp6 устройство имеет цифровой вход №6
outputs устройство имеет цифровые выходы (релейные выходы)
out1 устройство имеет выход №1
out2 устройство имеет выход №2
out3 устройство имеет выход №3
out4 устройство имеет выход №4
out5 устройство имеет выход №5
out6 устройство имеет выход №6
out7 устройство имеет выход №7
out8 устройство имеет выход №8

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

Возвращает 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": []
  }
}

opencollectors

{
  "success": true,
  "data": {
    "opencollectors": [
      {
        "index": 0,
        "label": "OC1",
        "active": true,
        "state": false
      },
      {
        "index": 1,
        "label": "OC2",
        "active": true,
        "state": false
      }
    ],
    "count": 2
  }
}

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

POST /api/settings

Тело запроса

{
  "setting": "{setting}",
  "values": {...{values}}
}
setting ключ настройки
values значения настройки (объект)
Типы тела POST запроса для ключа настройки
mqtt

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

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

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

en Активен ли Opentherm в контроллере. Вы можете отключить и не использовать этот функционал.
ch_en Флаг активации режима отопления. При установке значения true, включится режим нагрева теплоносителя на контур отопления.
ch_sp Пороговое значение температуры теплоносителя, которое будет поддерживаться в контуре отопления при нагреве теплоносителя.
dhw_en Флаг активации режима горячего водоснабжения. Если отключен, котел не будет включать контур горячей воды или переключать трехходовой клапан (Buderus U072)
dhw_sp Пороговое значение температуры теплоносителя в контуре горячего водоснабжения.
ch2_en Второй контур отопления.
cool_en Охлаждение
mod Уровень модуляции (0-100)
otc_en
 Outside temperature compensation. Режим компенсации температуры по наружному датчику.

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

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:

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

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

Получение списка Wifi сетей
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",
      "subtype":?string,
      "op": ">",
      "value": 30.0
    },
    "then": [
      { "capability": "out1", "action": 1 }
    ],
    "else": [
      { "capability": "out1", "action": 0 }
    ]
  }
]
Создание автоматизации
POST /api/automations

Тело запроса

 {
   "if": {
     "capability": "ntc1",
     "op": ">",
     "subtype": ?string // может быть серийным номером или подтипом-действием opentherm (ch dhw)
     "value": 30.0
   },
   "then": [
     { "capability": "out1", "action": 1 }
   ],
   "else": [
     { "capability": "out1", "action": 0 }
   ]
 }
Обновление автоматизации
PUT /api/automations/{id}

Тело запроса

{
  "if": {
    "capability": "ntc1",
    "op": ">",
    "subtype": "28FF1234567890AB", // может быть серийным номером или подтипом-действием opentherm (ch dhw)
    "value": 35.0
  },
  "then": [
    { "capability": "out1", "action": 1 },
    { "capability": "opentherm", "subtype": "ch", "action": 1 }
  ],
  "else": [
    { "capability": "out1", "action": 0 }
  ]
}
Удаление автоматизации
DELETE /api/automations/{id}

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

opentherm 
{
  "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
      }
    }
  }
}
ntc1 
{
  "success": true,
  "data": {
    "state": {
      "value": 27.62923812866211
    },
    "history": {
      "name": "ntc1",
      "timestamps": [
        1777483230583
      ],
      "values": [
        27.62923812866211
      ],
      "count": 1
    }
  }
}
ntc2 аналогично ntc1
ai1 аналогично ntc1
ai2 аналогично ntc1




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

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

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

В настоящее время UMNI UNI отказался от MQTT и промежуточных брокеров в пользу RESP API, SSE и Syslog!

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

Прошивка устройств UMNI через ESP Launchpad (веб-браузер)

Эта инструкция описывает процесс прошивки устройства через онлайн-инструменты на примере Esp Launchpad.

image.png

Перед прошивкой подайте внешнее питание на контроллер и подключите USB, либо снимите перемычку КОНФ. Либо используйте хороший USB кабель и порт компьютера.

Скачать последний релиз прошивки (файл umni-uni.bin) со страницы https://github.com/umni-su/umni-uni/releases .

image.png

Скачать и установить драйвера для чипа CH340 по ссылкам ниже или из файлов инструкции.

OS Source URL
Linux https://www.wch-ic.com/downloads/CH341SER_LINUX_ZIP.html
macOS https://www.wch-ic.com/downloads/CH341SER_MAC_ZIP.html
Windows https://www.wch-ic.com/downloads/CH341SER_ZIP.htm

Подключить контроллер UMNI к компьютеру по USB.

Перейти на сайт https://espressif.github.io/esp-launchpad/ 

Нажать "Connect"

image.png

Во всплывающем окне выбрать COM порт, к которому подключен контроллер.

Перейти на вкладку DIY и важно - указать Flash Address 0x100000

image.png

Выбрать файл ,bin, нажать Program

image.png

Если видите в терминале такой вывод, то все прошло успешно!

esptool.js
Serial port WebSerial VendorID 0x1a86 ProductID 0x7523
Connecting...
Detecting chip type... ESP32
Chip is ESP32-D0WD-V3 (revision 3)
Features: Wi-Fi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
Crystal is 40MHz
MAC: 44:1d:64:83:89:b4
Uploading stub...
Running stub...
Stub running...
Changing baudrate to 921600
Changed
Manufacturer: 46
Device: 4016
Detected flash size: 4MB
Compressed 1175312 bytes to 751024...
Writing at 0x100000... (2%)
Writing at 0x10d071... (4%)
Writing at 0x11a7e2... (6%)
Writing at 0x1243df... (8%)
Writing at 0x12be9d... (10%)
Writing at 0x134589... (13%)
Writing at 0x139e45... (15%)
Writing at 0x13fb0d... (17%)
Writing at 0x145a07... (19%)
Writing at 0x14b7b2... (21%)
Writing at 0x1515cd... (23%)
Writing at 0x15725d... (26%)
Writing at 0x15cc78... (28%)
Writing at 0x163248... (30%)
Writing at 0x169097... (32%)
Writing at 0x16eb74... (34%)
Writing at 0x174945... (36%)
Writing at 0x17a58c... (39%)
Writing at 0x1802bd... (41%)
Writing at 0x1862a2... (43%)
Writing at 0x18b8cc... (45%)
Writing at 0x1912f8... (47%)
Writing at 0x196973... (50%)
Writing at 0x19bf45... (52%)
Writing at 0x1a1ab5... (54%)
Writing at 0x1a71a1... (56%)
Writing at 0x1ac753... (58%)
Writing at 0x1b1e4c... (60%)
Writing at 0x1b7b87... (63%)
Writing at 0x1bd47c... (65%)
Writing at 0x1c2cd7... (67%)
Writing at 0x1c85a9... (69%)
Writing at 0x1ce451... (71%)
Writing at 0x1d3ebf... (73%)
Writing at 0x1d98d2... (76%)
Writing at 0x1df49f... (78%)
Writing at 0x1e5681... (80%)
Writing at 0x1ea75b... (82%)
Writing at 0x1efa65... (84%)
Writing at 0x1f53dc... (86%)
Writing at 0x1fb183... (89%)
Writing at 0x2017f2... (91%)
Writing at 0x2091b8... (93%)
Writing at 0x20ea65... (95%)
Writing at 0x214e5c... (97%)
Writing at 0x21a245... (100%)
Wrote 1175312 bytes (751024 compressed) at 0x100000 in 11.372 seconds.
Leaving...

Нажмите Reset

image.png

Увидите логи приложения - можно отключаться. ПО обновлено.

image.png

UMNI UNI Tool - управление контроллерами UMNI из одного места

Экосистема содержит в себе программное обеспечение для централизованного управления контроллерами. Так как контроллер UMNI создан на базе ESP32, данное программное обеспечение подойдет для управления любым совместимым контроллером ESP32. Важно помнить, что контроллер должен быть прошит оригинальным ПО UMNI UNI и подключен к необходимой периферии согласно открытой документации.

UMNI-UNI-D-CLIMATE.png

UMNI UNI TOOL - это по сути обвертка надо открытым REST HTTP API, о котором вы можете почитать тут.

С помощью этого приложения, вы можете централизованно управлять контроллерами UMNI:

Релиз можно скачать с официального репозитория на Github.

Разработка и поддержка

Каждый из вас может вложить вклад в проект. Поддержим развитие отечественного опенсорса, да и опенсорса в целом!

Запуск проекта

npm run tauri dev

npm run tauri android dev

Сборка проекта

npm run tauri build

npm run android build

Скриншоты

UMNI-UNI-D-HOME.png

UMNI-UNI-D-DIO.png

UMNI-UNI-D-OW.png

UMNI-UNI-D-RF.png

UMNI-UNI-0.png

UMNI-UNI-1.png

UMNI-UNI-2.png

UMNI-UNI-3.png

UMNI-UNI-4.png