Документація

Користувацькі лічильники

Примітка: cFos Charging Manager може зчитувати дані більшості сонячних інверторів за допомогою SunSpec (тип пристрою "SunSpec Solar Inverter / Meter"). В цьому випадку вам не потрібно створювати власне визначення лічильника.

Диспетчер нарахувань cFos дозволяє створювати власні визначення лічильників для підтримки лічильників, яких немає в стандартному репертуарі. Наразі їх існує три види: Лічильники Modbus, лічильники HTTP/JSON та лічильники MQTT/JSON. Файли визначення для цих лічильників дуже схожі. Лічильники Modbus зчитують свої дані через Modbus з певних регістрів, тоді як лічильники HTTP/JSON отримують свої дані через HTTP-запит і розбирають JSON як відповідь. Для лічильників MQTT/JSON cFos Charging Manager підписується на теми MQTT і розбирає повідомлення, опубліковані в темі, як JSON. Для розбору cFos Charging Manager використовує невелику "мову запитів". Ось документація про можливості MQTT в cFos Charging Manager.

На додаток до ряду попередньо визначених змінних, таких як струм і напруга, лічильники, що визначаються користувачем, можуть також зчитувати невідомі змінні, визначені користувачем, запитувати входи і встановлювати виходи. Зчитування змінних та встановлення результатів дозволяє оцінити формули. У поєднанні зі змінними диспетчера заряджання та глобальними виходами диспетчера заряджання, описаними нижче, це потужна функція, яка навіть дозволяє виконувати певні завдання домашньої автоматизації та керувати зовнішніми пристроями, такими як акумуляторні батареї. Якщо ви реалізуєте контрольні завдання за допомогою цього, будь ласка, дайте нам зворотній зв'язок. Нам дуже цікаво, що люди контролюють за допомогою cFos Charging Manager, і це допомагає нам надалі розвивати Charging Manager відповідно до потреб клієнтів.

Ось простий приклад визначення для Modbus, який зчитує один регістр для активної потужності. Ви можете легко змінити номер регістра для вашого конкретного застосування:
Приклад визначення для одного регістру.

Ось приклад визначення для Modbus і один для HTTP/JSON:
Завантажити зразок визначення для лічильника Modbus
Завантажити зразок визначення для HTTP/JSON лічильника

Диспетчер зарядки вже постачається з декількома такими файлами, але ви можете завантажити власні файли в розділі "Конфігурація системи", а також видалити їх знову.
Тут ви знайдете більшість визначень meter, які ми надаємо:
Завантажити визначення лічильників, що постачаються

Якщо ви створили свій власний контр-файл і він може бути корисним для інших користувачів, ми будемо дуже вдячні, якщо ви надасте його нам. Тоді ми доставимо його з наступними версіями Диспетчера нарахувань.

Завантажити визначення лічильників для додаткових лічильників

Структура файлу визначення:

Визначення лічильників - це JSON-файли з глобальним JSON-об'єктом, який має властивості та підоб'єкти. 'rtype' визначає тип операції читання: 0 = Modbus, 1 = HTTP/JSON, 2 = MQTT/JSON. 'mtype' визначає тип пристрою: 0 = Інший пристрій, 1 = Лічильник, 2 = Інвертор, 4 = Акумуляторна батарея.

Числа можна вказувати як у десятковій, так і у шістнадцятковій системі числення з префіксом 0x. Допускаються також однорядкові коментарі з використанням //.

Ми рекомендуємо запускати ваші файли визначень через валідатор JSON5, наприклад, цей валідатор JSON5 Ви обов'язково повинні були прочитати розділ Формули, щоб зрозуміти, які значення можна використовувати у формулах, наведених у наступному посиланні.

Визначення Modbus мають об'єкт 'rtu' з наступними властивостями:

silence_period, в мсек. визначається тривалість паузи перед доступом до Modbus RTU, щоб пристрій розпізнав початок повідомлення.
silence_same_slave, true: Пауза також спостерігається при декількох доступах до одного пристрою.
retries: Кількість повторних спроб, якщо пристрій не відповідає.
rcv_timeout: в мсек. максимальний час очікування на один доступ, поки пристрій не відповість.

Ці глобальні властивості застосовуються до Modbus TCP та RTU:

modbus_read: Номер функції команди читання Modbus, зазвичай 3 або 4.
modbus_read_max_registers: Максимальна кількість регістрів, які можна прочитати за один раз.
modbus_allow_gaps: true = невикористані області регістрів можуть бути прочитані в операції читання.

Для Modbus TCP та HTTP/JSON існує об'єкт 'tcp' з наступними властивостями:

connect_timeout: в мс. максимальний час очікування TCP з'єднання.
delay_after_connect: в мс. Пауза після встановлення з'єднання перед подачею першої команди.

Обидва типи визначень (Modbus та HTTP/JSON) мають наступні додаткові властивості:

upd_delay: в мсек. визначає інтервал, через який можна зчитувати дані з пристрою. Деякі пристрої перевантажуються, якщо їх запитувати занадто часто.
manufacturer: String, назва виробника. Відображається у розширеній інформації плитки.
delay_accumulated: true = Накопичені значення (кВт-год) запитуються лише кожні 3 секунди або за наявності достатньої потужності. false = Ці значення запитуються завжди.
ui_addr: URL, якщо відрізняється від адреси пристрою для виклику веб-інтерфейсу.
зарезервовано: Масив зі значеннями, які інтерпретуються як 0 (корисно, якщо пристрій підтримує певні значення залежно від моделі).

Якщо ви не вкажете перелічені вище властивості, cFos Charging Manager прийме значення за замовчуванням, які добре працюють у більшості випадків.

Наступним кроком у визначенні JSON є визначення змінних, які лічильник використовує для зчитування або обчислення значень струму, напруги і т.д. Наступні змінні використовуються менеджером зарядки. Диспетчеру заряджання відомі такі змінні:
type_designation, version, firmware_version, serial: Вони формують назву моделі, як показано в розширеній інформації на плитці. Вони запитуються один раз під час налаштування або скидання лічильника.
voltage_l1..voltage_l3, current_l1..current_l3, power_w, power_var, power_va, power_w_l1..power_w_l3: CFos Charging Manager намагається обчислити значення для voltage_l1..l3, signature current_l1.l3, power_w і power_va з цих значень. Вам не обов'язково вказувати всі змінні. Диспетчер заряджання cFos намагається обчислити значення з наявних змінних.
import_wh, export_wh: Диспетчер заряджання використовує ці змінні для відображення import_wh та export_wh. Для односпрямованих лічильників (наприклад, інверторів) завжди слід визначати лише import_wh. Export_wh слід визначати лише для двонаправлених лічильників (таких як акумуляторні батареї або еталонні лічильники мережі).

soc: Якщо доступно, стан заряду акумуляторної батареї відображається у відсотках у плитці.
Крім того, ви можете визначити інші змінні з різними назвами, які зчитуються при кожному оновленні або обчислюються за формулами. Якщо ви визначите змінні, які починаються з CM, наприклад, CM._set_price, присвоєні значення зберігаються у глобальних змінних Диспетчера заряджання (див. нижче) і можуть бути запитані відповідним чином.
Змінні з символом *: Якщо ви визначаєте змінні, які починаються з *, вони відображаються в інтерфейсі у плитці лічильника під розширеною інформацією, наприклад, температура акумуляторної батареї.

Визначення змінної:


Об'єкт називається за назвою змінної, перерахованої вище, і має такі властивості: fixed: Рядок з фіксованим значенням.

Корисно, якщо, наприклад, неможливо визначити значення, наприклад, для type_designation або напруги. expr: Рядок, змінна не зчитується, а обчислюється як формула. type: Якщо не fixed або expr, то тип змінної: int16, uint16, int32, uint32, float, int64, string. Це важливо для Modbus, щоб читати регістри в правильному форматі. uint16 і uint32 - це типи, які можуть приймати тільки додатні числа.
З JSON/HTTP зазвичай можна використовувати float. resolution: float, зчитане значення множиться на "роздільну здатність". Значення для напруги повинні бути у вольтах, струмів у міліамперах, потужності у ватах, енергії у ват-годинах (Wh).


З від'ємною роздільною здатністю можна інвертувати значення, якщо воно має протилежний знак. once: bool (true або false), якщо true, значення зчитується лише один раз під час ініціалізації пристрою, інакше періодично. address: число (Modbus) або рядок (HTTP/JSON), номер регістра Modbus або HTTP URL значення, яке потрібно зчитати. query:
Рядок, для HTTP JSON - специфікація на мові запитів диспетчера заряджання, за допомогою якої він знаходить значення, яке потрібно прочитати у відповіді JSON. порядок: рядок, для Modbus - порядок байт, "hl" або "lh", в якому знаходиться значення. довжина: число, для Modbus - довжина рядка в регістрах. Для змінних 'version' та 'firmware_version' параметр 'length' використовується для перетворення числових версій у рядки з крапками. Для 'length' допускаються значення 2 або 4, які потім призводять до форматів версій a.b та a.b.c.d. При значенні 'length' 2 і типі 'int16' або 'uint16' диспетчер заряджання відокремлює крапкою молодший і старший байт, при 'int32' або 'uint32' - молодше і старше слово, при 'int64' - молодше і старше dword. Для 'lenth' 4 та 'int32' або 'uint32' диспетчер заряджання розбиває значення на 4 байти, розділені крапкою.
Для 'int64' на 4 слова відповідно. regex: Рядок. Якщо вказано регулярний вираз, відповідь лічильника не обов'язково має бути у форматі JSON. Як результат оцінюється або весь збіг регулярного виразу, або перша група. Будь ласка, використовуйте це тільки якщо пристрій не повертає JSON.

Ось список можливостей наших регулярних виразів: будь-які char: . іменовані класи:



\d \s \w \D \S \W анонімні класи: [a-z0-9_], [^0-9], [^\d] групи з альтернативами: (ab|cd|ef) не захоплені групи: (?:ab|cd) (жадібні) один раз або жодного: a?, a???
(жадібні ) багато або жодного: a*, a*?


(жадібний ) один раз або більше: a+, a+? початок рядка: ^ кінець рядка: $

Визначення вхідних даних:

Диспетчер зарядки може запитувати до 32 вхідних значень з різних регістрів або елементів JSON на один пристрій. Властивість "Inputs" є масивом JSON. Для кожного входу необхідно визначити наступні властивості:
адреса: Адреса (регістр Modbus або URL).
рахувати: Кількість вхідних бітів, які будуть прочитані при даному запиті.
запит: Для HTTP/JSON - мова запиту для пошуку значення у відповіді.

При кожному оновленні cFos Charging Manager зчитує всі входи, визначені таким чином, і поміщає біти всередину масиву, який потім можна запитувати за допомогою формул, Input1...InputN...

Визначення результатів:

Диспетчер заряджання може перемикати до 32 виходів на пристрій. Виходи визначені у розділі "outputs" як JSON-масив вихідних об'єктів. Всі виходи перемикаються в кінці кожного циклу оновлення, якщо стан відповідного виходу змінився.
Для кожного виходу ви повинні визначити такі властивості в об'єкті виходу:
адреса: HTTP URL з необов'язковим HTTP-методом, наприклад, GET http://www.example.com?output1=${var1}. Для налаштування регістрів Modbus можна використовувати HTTP API cFos Charging Manager. Charging Manager виявляє відповідні доступи на localhost і перенаправляє запит на внутрішній обробник, тому вам не потрібна авторизація, як у випадку із зовнішнім доступом до HTTP API. Якщо після всіх замін URL-адреса порожня, виведення не відбувається. Наприклад, ви можете перемикати виводи, тільки якщо певні змінні існують (див. формули: функція exists()). В адресі ви можете додатково вказати ${address} та ${id}. Це поточна адреса пристрою та Modbus ID, визначені у налаштуваннях. Адреса та ідентифікатор в основному використовуються для використання Modbus API (див. нижче).
body: Необов'язкове тіло HTTP для POST або PUT.
В URL та тілі можна використовувати формули ${expr}, які посилаються на глобальні змінні Диспетчера заряджання або на дані відповідного лічильника. Формула 'expr' обчислюється під час налаштування виводу і замінюється в тексті URL-адреси або тіла. Якщо у наведеному вище прикладі http://www.example.com?output1=1 встановлює вивід, а http://www.example.com?output1=0 видаляє його, ви можете визначити змінну "var1" і встановити її в 1 або 0 за бажанням. Таким чином, ви також можете записувати числові значення для контролю продуктивності пам'яті в регістрах Modbus, які ви попередньо зберегли у змінній за допомогою формули.
Якщо замість передачі числового значення в URL-адресі потрібно замінити один текст на інший в залежності від формули, як, наприклад, у випадку з WLAN-розетками Shelly, ви можете записати його так: ${if expr`text1`text2}. Апостроф - це символ повернення (ASCII код 96). Якщо 'expr' != 0, буде вставлено текст1, інакше - текст2. Для WLAN-сокета Shelly URL-адреса має такий вигляд: http://<ip-addr>/relay/0?turn=${if expr`on`off}, тобто якщо expr != 0, диспетчер заряджання викликає http://<ip-addr>/relay/0?turn=on, інакше http://<ip-addr>/relay/0?turn=off.

Якщо ви введете відносний шлях як URL-адресу, диспетчер заряджання візьме адресу, налаштовану для відповідного пристрою. Якщо ви введете "localhost" як домен, диспетчер заряджання візьме адресу пристрою, на якому він запущений. Якщо він виявляє доступ до власного API, він використовує внутрішній обробник замість виконання повного HTTP-доступу, тому вам не потрібно зберігати ім'я користувача та пароль у визначенні лічильника. URL-адреса, яка починається з *, змусить Диспетчер нарахувань завжди виконувати повний HTTP-доступ.

Скидання виходів: На додаток до масиву "outputs", ви також можете визначити масив з назвою "resets", який має таку саму структуру, як і масив "outputs". Його можна використовувати для скидання виходів до початкових значень, коли пристрій вимкнено. За допомогою цього, у поєднанні з визначеними користувачем змінними та "once": true, ви можете повернути пристрій до початкового стану.
Періодично записуйте виходи: Для деяких пристроїв виходи потрібно записувати періодично, інакше пристрій скидає значення до "за замовчуванням". Наприклад, пам'ять Kostal знову використовує свої правила за замовчуванням, якщо керування пам'яттю не було активним протягом певного часу. Для періодичного налаштування виходів можна додати до адреси префікс #xxx#, де xxx вказує на те, через скільки секунд вихід перезаписується, навіть якщо значення, що записується, залишилося незмінним. Наприклад, якщо адреса має вигляд /cnf?cmd=set_cm_vars&name=test&val=42, ви можете використати #30#/cnf?cmd=set_cm_vars&name=test&val=42, щоб забезпечити запис цього значення кожні 30 секунд.

Визначення мови запиту:

Наразі у пошукових виразах "query", прикладах, можна використовувати імена членів та оператори "." і "[]":

випробуванняЕлемент з назвою "тест"
ім'я1.ім'я2Елемент з іменем "name2" в дочірньому об'єкті "name1"
ім'я[idx]Елемент "idx" елементу об'єкту "name". "idx" може бути числом, наприклад, для масивів або рядком
name["u2"]Елемент "u2" об'єктного елементу "name", відповідає "name.u2"
name[{"el1": "v1", "el2": 3}].valueВибирається елемент масиву, який задовольняє умову об'єктної нотації та обчислюється елемент з іменем value. Тут, наприклад, в масиві name вибирається елемент, що має в якості об'єкта елементи el1 зі значенням v1 та el2 зі значенням 3, а потім з цього об'єкта повертається значення елементу value.

Змінні Global Charging Manager:

Змінні можна створювати в конфігурації Charging Manager. В якості значення можна використовувати фіксоване значення або формулу. Наприкінці кожного циклу оновлення диспетчер тарифікації перераховує значення цих змінних, якщо це необхідно. Потім ви можете використовувати їх у (певних) параметрах Диспетчера зарядки, Правилах зарядки або для керування виходами. Ви також можете записати Ex.member або Mx.member як змінні. Тут Exта Mx- це ідентифікатор пристрою настінного зарядного пристрою або лічильника, налаштованого в Диспетчері заряджання. member - це "визначена користувачем" змінна, яка зберігається у відповідному пристрої. Деякі змінні можуть мати особливе значення: Для лічильників KEBA "out1" - комутаційний вихід, для лічильників ABB B23 "out1" і "out2" - комутаційні виходи (для моделей, які це підтримують). 1 вмикає вихід, 0 вимикає його знову.

Якщо у вас є прилади, які вмикаються за певних умов, а потім працюють деякий час (наприклад, пральна машина, посудомийна машина), ви також можете визначити змінну як "тригер". Тоді формула змінної - це умова, за якої змінна набуває значення 1. Через певний час вона знову стає рівною 0. "Умова повторного запуску" дозволяє продовжувати час до вимкнення (тобто встановлення змінної в 0) знову і знову, доки виконується умова.

Для тестування ви можете відобразити змінні диспетчера заряджання та лічильника, наприклад, поточні ціни Awattar:


                        Скріншот відображення змінних лічильника

Результати роботи Глобального менеджера зарядки:

У конфігурації Диспетчера зарядки ви можете налаштувати глобальні виходи, як описано вище у визначенні лічильника в розділі "Виходи". Вони встановлюються в кінці кожного циклу оновлення, якщо їх статус змінився. Якщо ви хочете керувати комутаційними виходами в пристроях, визначених користувачем, рекомендується використовувати вищезазначену конвенцію (див. Змінні диспетчера заряджання): Ви задаєте в користувацькому лічильнику змінні з іменами "out1", "out2" і т.д. та налаштовуєте виходи в користувацькому лічильнику, які перемикають вихід в залежності від значення цих змінних.

Глобальний Modbus API диспетчера зарядки:

Modbus API зарядного пристрою використовується для керування пристроями Modbus, які мають будь-яку Modbus RTU або TCP-адресу (доступну з зарядного пристрою). Для Modbus RTU введіть COMx,bd,8,p,s в якості адреси, де x - номер COM-порту, bd - швидкість передачі, p - парність ('N', 'E' або 'O') і s - кількість стоп-біт (1 або 2), як в конфігурації окремих пристроїв. Для Modbus TCP адресатом є IP-адреса пристрою в мережі Диспетчера заряджання, включаючи номер порту.
URL (для HTTP GET) Modbus API:
/cnf?cmd=modbus_get або /cnf?cmd=modbus_set
cFos Charging Manager підтримує наступні додаткові параметри запиту:
addr: Адреса пристрою Modbus RTU або TCP, згадана вище.
func: номер функції Modbus, наприклад, для читання 3 або 4, для запису 6 або 16.
id: ідентифікатор пристрою пристрою Modbus.
reg: номер регістру Modbus. Значення може бути задано в десятковому або шістнадцятковому вигляді (з префіксом 0x).
val: номер, значення для запису в реєстр. Опускати при читанні.
type: 'w' 16bit (default), d = 32bit, f = float, q = 64bit, s = string.
cnt: число, максимальна довжина рядка в регістрах, опускається для інших типів або встановлюється в 1.
order: рядок, порядок байт, або "hl" або "lh".

Примітка: Якщо Ваш "лічильник" виконує в першу чергу контрольні завдання, Ви можете відмітити опцію "Приховати пристрій" в налаштуваннях цієї плитки, щоб цей пристрій не відображався на стартовій сторінці.

Примітка: Деякі лічильники, які зчитуються через HTTP, вимагають ім'я користувача/пароль для авторизації. Ви можете вказати це в адресі для HTTP-доступу, наприклад, http://username:password@192.168.2.111. Якщо ваше ім'я користувача або пароль містить символ "@", ви повинні замінити його на "%40".