Дакументацыя

Вобласці прымянення MQTT

MQTT - гэта інтэрнэт-пратакол з цэнтральным брокерам паведамленняў. З дапамогай гэтага брокера паведамленняў удзельнікі могуць падпісвацца на пэўныя "тэмы" і адпраўляць паведамленні па тэмах. cFos Charging Manager можа праслухоўваць паведамленні на пэўныя тэмы і, такім чынам, ім можна кіраваць праз MQTT. Ён таксама можа перадаваць статус прылад, якімі ён кіруе. cFos Power Brain Wallbox таксама можна кіраваць праз MQTT і перадаваць яго статус. Гэта карысна пры падключэнні да сістэмы хатняй аўтаматызацыі, для прамысловага кіравання (M2M), а таксама для кантролю і запісу. Усе тэмы пачынаюцца з cfos_mqtt. Калі вы хочаце падключыць некалькі прылад cFos MQTT да брокера MQTT, тэма можа пачынацца з cfos_mqtt_<Seriennummer>/, які можна наладзіць у канфігурацыі. У канфігурацыі вы таксама можаце паказаць URL для стандартнага брокера MQTT. URL-адрасы могуць пачынацца з mqtt:// і mqtts://. З mqtts:// cFos Charging Manager або cFos Power Brain Wallbox усталёўвае злучэнне TLS. Выкарыстоўваюцца стандартныя парты 1883 для незашыфраваных злучэнняў і 8883 для TLS-злучэнняў. Аднак вы таксама можаце паказаць порт у URL. Вы можаце ўвесці імя карыстальніка і пароль у звычайнай натацыі URL, напрыклад, mqtt://user:password@192.168.2.111. Калі вы ўказваеце брокера MQTT у канфігурацыі cFos Charging Manager, вы можаце ўказаць асобнага брокера або проста напісаць mqtt. Затым выкарыстоўваецца брокер па змаўчанні, захаваны ў канфігурацыі.

cFos Charging Manager падтрымлівае як MQTT 3.1.1, так і MQTT 5. Калі вы пачынаеце URL з mqtt3:// або mqtt5:// (mqtts3:// і mqtts5:// для зашыфраванага злучэння), вы вызначаеце версію пратакола. Па змаўчанні - MQTT 3.1.1. З MQTT 5 менеджэр зарадкі cFos спрабуе пераключыцца назад на MQTT 3.1.1, калі з'яўляецца адпаведнае паведамленне пра памылку. Гэта працуе са старымі брокерамі Mosquitto, але не абавязкова з іншымі брокерамі.

Заўвага: паколькі для наладжвання MQTT патрабуецца пароль адміністратара, менеджэр спагнання апрацоўвае даныя адпаведна. Такім чынам, даныя наўмысна адпраўляюцца, да якіх можна атрымаць доступ толькі з паролем адміністратара.

Заўвага пра брокераў MQTT: дзякуючы Стэфану Г. (#diebestenuserderwelt) мы змаглі праверыць брокера MQTT, убудаванага ў ioBroker. Гэты брокер MQTT 3.1.1 (па стане на люты 2023 г.) паводзіць сябе не ў адпаведнасці са стандартам у некалькіх аспектах: спробы злучэння моўчкі спыняюцца без паведамлення пра памылку, карысная нагрузка часам адсутнічае ў пакетах PUBLISH, пакеты PUBLISH, відавочна, адпраўляюцца двойчы (ці можна гэта зрабіць з выключанай наладай канфігурацыі?). Такім чынам, гэты брокер не падыходзіць для кіравання API Charging Manager, паколькі запыты API могуць выконвацца некалькі разоў. Хоць мы зацікаўлены ў сумяшчальнасці нашай рэалізацыі MQTT з як мага большай колькасцю брокераў, у цяперашні час мы рэкамендуем выкарыстоўваць Mosquitto для ioBroker.

Інтэграцыя лічыльнікаў і насценных боксаў з дапамогай прылады тыпу «HTTP Input».

Замест таго, каб пастаўляць гэтыя прылады праз HTTP (гл. HTTP API -> HTTP Counters і Wallboxes), гэтыя прылады могуць таксама слухаць MQTT. Увядзіце mqtt або URL брокера MQTT у якасці адраса прылады. Затым адпаведны глюкометр або Wallbox праслухоўвае тэму cfos_mqtt/set/<Geräte-ID>, напрыклад, для глюкометра з ідэнтыфікатарам прылады M1 да cfos_mqtt/set/M1. Затым лічыльнік уводу HTTP чакае радок JSON у якасці паведамлення, як апісана ў API HTTP у раздзеле "Лічыльнікі HTTP і Wallbox". Такім чынам, ваша крыніца MQTT павінна дастаўляць дадзеныя ў гэтым фармаце. Вы можаце інтэграваць прылады, якія cFos Charging Manager не падтрымлівае, атрымаўшы даныя з іншай крыніцы (напрыклад, сістэмы хатняй аўтаматызацыі), а потым імпартаваўшы іх у Charging Manager.
Заўвага: Калі зыходныя дадзеныя маюць фармат, які адрозніваецца ад таго, які чакае лічыльнік HTTP, вы таксама можаце стварыць уласны лічыльнік. Для MQTT гэта апісана ніжэй.

прыклад:
Вы стварылі лічыльнік уводу HTTP, і ён мае M3 у якасці ідэнтыфікатара прылады. У якасці адраса вы ўказалі адрас брокера Mosquitto, напрыклад, mqtt://. Калі вы ўвядзеце наступную каманду ў камандным радку на кампутары, на якім працуе Mosquitto:
mosquitto_pub -h localhost -t cfos_mqtt/set/M3 -m '{ "model": "TestModell", "import_wh": 12345, "export_wh": 23456, "voltage": [231, 232, 233], "current": [10001, 10002, 10003] }'
тады лічыльнік павінен утрымліваць вышэйзгаданыя значэнні.

Перадача стану прылад Charging Manager

У канфігурацыі Charging Manager вы можаце ўказаць URL брокера MQTT (або mqtt для стандартнага брокера), пад якім Charging Manager потым публікуе стан усіх прылад у тэме cfos_mqtt/get/dev_info. Ён перадае гэта ў фармаце, вядомым з HTTP get_dev_info. Гэта дае вам усе значэнні прылад, як яны бачныя ў карыстальніцкім інтэрфейсе, напрыклад, значэнні прадукцыйнасці лічыльнікаў або статус насценных скрынак. Калі вы хочаце падпісацца толькі на асобныя прылады, вы можаце зняць сцяжок «Апублікаваць інфармацыю аб MQTT» і замест гэтага паставіць галачку ў опцыі «Апублікаваць інфармацыю аб MQTT» у наладах для асобных прылад у раздзеле «Адлюстраванне». Адпаведны радок JSON для адпаведнай прылады затым публікуецца ў тэме cfos_mqtt/get/<ID прылады>. Вы таксама можаце падпісацца на ўсе глабальныя значэнні ў тэме cfos_mqtt/get/params, паколькі яны выводзяцца ў фармаце, вядомым як HTTP get_dev_info, у раздзеле «params».

Кіруйце cFos Charging Manager API праз MQTT

У канфігурацыі cFos Charging Manager вы можаце ўказаць URL брокера MQTT (або mqtt для стандартнага брокера) у раздзеле «Брокер для доступу да API праз MQTT». Калі гэта значэнне не пустое, cFos Charging Manager падпісваецца на ўсе тэмы, якія пачынаюцца з cfos_mqtt/api/ . Затым ён інтэрпрэтуе паведамленні ў такой тэме так, як калі б назва тэмы была HTTP URL, які заканчваецца на /cnf? запускае і перасылае яго ў HTTP API. Затым Charging Manager публікуе адказ HTTP API у выглядзе JSON у тэме cfos_mqtt/api_res. У вас ёсць амаль увесь HTTP API пад вашым кантролем праз MQTT. Выключэнне складаюць выклікі API, якія вяртаюць доўгія адказы JSON. Прыклад: cfos_mqtt/api/cmd=set_cm_vars&name=x&val=1 выкарыстоўвае функцыю API set_cm_var, каб усталяваць зменную x дыспетчара аплаты ў 1. У cfos_mqtt/api/cmd=enter_rfid&rfid=5678&dev_id=E1 ёсць паведамленне cfos_mqtt/api/cmd=enter_rfid&rfid=5678&dev_id=E1 Увядзіце RFID 5678 для Wallbox з ідэнтыфікатарам прылады E1 (гл. таксама нашы пашыраныя функцыі RFID).
Вы можаце змясціць дадзеныя, якія перадаюцца праз HTTP POST, у паведамленні пад тэмай.

Прыклад: перыядычнае змяненне максімальнага агульнага току, даступнага дыспетчару зарадкі:
Увядзіце свайго брокера ў агульных наладах Charging Manager у раздзеле «Брокер для доступу да API праз MQTT» (ці проста mqtt, калі будзе выкарыстоўвацца брокер па змаўчанні, захаваны ў раздзеле «Канфігурацыя»). Затым апублікуйце ў тэме з дапамогай MQTT
cfos_mqtt/API/cmd=set_params
аб'ект JSON з наступным зместам:
{"max_total_cur_prc": p}
дзе p - працэнт ад зададзенага максімальнага агульнага току, які трэба прыняць.
Заўвага: некаторыя з выклікаў HTTP API прыводзяць да таго, што Charging Manager захоўвае канфігурацыю. Калі вы запускаеце іх занадта часта, успышка (у cFos Power Brain або cFos Wallbox Booster) або SD-карта ў Raspberry зношваюцца. Такім чынам, выклік API "set_params" з асобным параметрам "max_total_cur_prc" не прыводзіць да захавання параметраў.

Кіруйце Wallbox праз MQTT

Калі cFos Charging Manager знаходзіцца не ў рэжыме «кіравання нагрузкай», а ў рэжыме «маніторынгу», вы можаце ўзяць на сябе кантроль над усімі прыладамі Wallbox самастойна з дапамогай MQTT. У прыватнасці, гэта датычыцца насценных скрынак cFos Power Brain, якія працуюць як падпарадкаваныя ў рэжыме «Назіранне». Каб зрабіць гэта, вы павінны адзначыць опцыю «Актываваць кіраванне Wallbox» у раздзеле MQTT у наладах Charging Manager. Затым cFos Charging Manager праслухоўвае тэму MQTT cfos_mqtt/ctl і чакае паведамленняў з аб'ектам JSON. Гэты аб'ект мае падаб'екты ў якасці ўласцівасцей з ідэнтыфікатарам прылады ў якасці назвы. Падаб'екты выглядаюць так: {"cur": c, "ena": b, "wke": b, "phs": p}, дзе c - ток зарадкі ў мА, а b можа быць ісцінай або ілжывым . "ena": false дэактывуе зарадку на Wallbox, "wke": true спрабуе адправіць каманду "аўтаматычнае абуджэнне" на Wallbox (у цяперашні час магчыма толькі з насценнымі скрынкамі cFos Power Brain). p можа быць 1 або 3 для пераключэння паміж 1-фазнай і 3-фазнай зарадкай. Вы таксама можаце апусціць "cur", "ena", "wke" і "phs", каб выконваць толькі пэўныя функцыі кіравання. прыклад:
{"E1":
{cur: 8000, ena: true, wke: true},
"E2":
{cur: 10000, phs: 3}}

Устанаўлівае ток зарадкі Wallbox з ідэнтыфікатарам прылады на 8A, актывуе зарадку і спрабуе разбудзіць аўтамабіль. Акрамя таго, зарадны ток для Wallbox E2 усталяваны на 10 A і пераключаецца на 3-фазную зарадку.

Адпраўляйце логі і журнал транзакцый праз MQTT

Вы можаце пазначыць URL брокера MQTT для перадачы запісаў часопіса ў сістэмным журнале ў раздзеле «Канфігурацыя». Затым cFos Charging Manager публікуе ўсе запісы часопіса ў тэме cfos_mqtt/log. Гэта дазваляе выдалена ацэньваць журналы для маніторынгу Charging Manager. Вы таксама можаце ўказаць URL брокера MQTT для запісаў у журнале транзакцый у раздзеле «Канфігурацыя». Затым усе транзакцыі загрузкі адпраўляюцца ў тэме cfos_mqtt/ta_log. Гэта дазваляе выдалена ацэньваць даныя плацежных транзакцый і ствараць рэзервовыя копіі плацежных транзакцый у іншай сістэме. Транзакцыя зарадкі пачынаецца, калі раз'ём для зарадкі падключаны, і заканчваецца, калі ён адключаецца.

Карыстальніцкія лічыльнікі з MQTT

Вы можаце ствараць уласныя лічыльнікі з дапамогай rtype=2 для MQTT. Гэтыя лічыльнікі вызначаюцца аналагічна лічыльнікам HTTP (rtype = 1). Аднак адрасы тут з'яўляюцца не URL-адрасамі HTTP, а тэмамі MQTT. прыклад:
"power_w": {
"address": "/test_topic3",
"type": "float",
"query": "power_w"
}

Тут вызначаны карыстальнікам лічыльнік падпісваецца на тэму /test_topic3 і чакае аб'ект JSON з уласцівасцю "power_w", г.зн. {"power_w": 1234}. Розныя зменныя лічыльніка могуць мець розныя тэмы і будуць абнаўляцца, як толькі будзе апублікавана паведамленне ў адпаведнай тэме.