Podporovaná zařízení: PowerCable MQTT, PowerBOX 3Px, PowerPDU 4PS, PowerDIN 4Pz, PowerBOX 4Kx, PowerPDU 8QS
MQTT (Message Queuing Telemetry Transport) je jednoduchý protokol k výměně zpráv mezi zařízeními. MQTT je oblíbený protokol pro IoT aplikace a na ně navázané cloudové služby. Standardní MQTT protokol se používá v různých strukturách topic a payload. Na straně serveru je tak typicky potřeba konfigurovat vstup dat pro konkrétní zařízení.
MQTT-flex je rozšířená implementace MQTT protokolu. Zařízení obsahuje konfigurační textový soubor, kde lze definovat struktury tématu (MQTT topic) i obsahu (MQTT payload).
Jak to funguje
V příkladu AN40 chytrá zásuvka PowerCable MQTT měří spotřebu elektrické energie a je trvale připojena na MQTT broker. Zprávy odesílá podle nastavení v konfiguračním skriptu MQTT-flex. Zprávy se odesílají na veřejný HiveMQ MQTT broker, PowerCable MQTT proto musí být připojen do WiFi sítě s přístupem na Internet. Tyto zprávy pak z MQTT serveru stahuje mobilní aplikace (MQTT Dash nebo MQTTool).
Z mobilní aplikace lze pak snadno ovládat elektrický výstup kliknutím na tlačítko.
Příklad NETIO AN40 se skládá z částí:
- Základní popis MQTT-flex
- Konfigurace MQTT-flex protokolu na NETIO zařízení (PowerCable MQTT 101x).
- Připojení NETIO zařízení přes MQTT-flex protokol na veřejný broker hostovaný HiveMQ.
- Postup jak ovládat PowerCable zásuvku z mobilní aplikace přes MQTT-flex protokol.
Video tutorial na Youtube:
NETIO MQTT-flex
MQTT-flex je implementováno jako M2M API protokol, kde NETIO zařízení je poskytovatel zpráv (tzv. publisher), který dodává stav výstupu a měřené hodnoty. NETIO zařízení je zároveň příjemce zpráv (tzv. „Subscriber“), přijetím zprávy lze ovládat výstup NETIO zařízení. Obě komunikace (Publisher/Subscriber) lze spustit paralelně proti veřejnému nebo soukromému MQTT „Brokeru“. Jako příklad veřejného MQTT brokeru je zde použitý broker.hivemq.com, soukromý MQTT broker může fungovat v lokální síti (např. Raspberry Pi), nebo to může být LTE/WiFi gateway s podporou funkce MQTT Broker.
Možné akce pro ovládání výstupu pomocí MQTT-flex
Čísla akcí pro každý jeden výstup odpovídají standardnímu NETIO číslování ve všech M2M protokolech:
0 = Vypnutí výstupu (Off)
1 = Zapnutí výstupu (On)
2 = Vypnutí výstupu na krátkou dobu (Short OFF) – restart zařízení
3 = Zapnutí výstupu na krátkou dobu (Short ON)
4 = Přepnutí výstupu z jednoho stavu do druhého (Toggle)
5 = Ponechání stavu výstupu (no change)
Pro akce 2 a 3 je možné ve zprávě definovat i parametr Delay v milisekundách. Pokud tento parametr není ve zprávě uveden, použije se výchozí nastavení (definovatelné přes webovou administraci).
- NETIO zásuvky se chovají jako MQTT subscriber. Na základě přijatých příkazů provedou požadovanou akci (přepne výstup).
- NETIO zároveň funguje jako MQTT publisher a posílá zprávy o měření a stavu svých výstupů (periodicky dle nastavení času nebo při změně hodnoty o určitou odchylku (delta).
NETIO MQTT-flex konfigurační skript
NETIO MQTT-flex konfigurace je definována pomocí JSON formátu, který se skládá ze tří “částí”:
- Broker
- Subscribe
- Publish
{
"config":{
"broker":{
<broker definitions>
},
"subscribe":[
{
<subscribe topic 1 definitions>
}
],
"publish":[
{
<publish topic 1 definitions>
},
{
<publish topic 2 definitions>
}
]
}
}
Broker sekce (konfigurační skript MQTT-flex)
V této sekci se nastavují údaje brokeru, ke kterému se chcete připojit.
Zde lze změnit použitý MQTT broker, přihlašovací údaje atd.
Příklad
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
}
Více informací k nastavení brokeru v MQTT-flex protokolu naleznete zde:
https://wiki.netio-products.com/index.php?title=MQTT-flex#Broker
Subscribe sekce (konfigurační skript MQTT-flex)
V subscribe sekci definujeme topic, který MQTT-flex zařízení poslouchá a jedná podle něj.
Hodnoty zpráv na subscribe topic indikují jaká akce se aplikuje na výstup:
netio/{DEVICE_NAME}/output/1/action se zprávou pro ovládání výstupu: (0 – off, 1 – on, 2 – short off, 3 – short on, 4 – toggle, 5 – no change)
IF zařízení dostane zprávu v topicu THEN provede action (akci) na target (cíl)
- topic - řetězec s cestou
- target - jmého výstupu/hodnoty, která se ovládá/zapisuje
-
action – akce provedená na daném targetu (ovládání nebo zápis hodnoty)
- podpora NETIO actions: 0 – off, 1 – on, 2 – short off, 3 – short on, 4 – toggle, 5 – no change
Příklad
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],
Vice informací k nastavení Subscribe sekce v MQTT-flex protokolu naleznete zde:
https://wiki.netio-products.com/index.php?title=MQTT-flex#Subscribe
Publish sekce (konfigurační skript MQTT-flex)
Pokud chcete poslat nějaká data ze zařízení do MQTT brokeru, nastavte Publish sekci.
Pomocí konfigurace „events“ lze vybrat kdy bude zařízení posílat data do MQTT brokeru. Zprávy lze odesílat periodicky (zde „timer“ a hodnota 1111 sekund) nebo při změně hodnoty nějaké proměnné oproti poslední odeslané hodnotě (zde load [mW] na výstupu 1). Zde uvedený příklad pošle MQTT zprávu na broker při každé změně výkonu o jediný mW na výstupu 1, ale i při konstantní hodnotě alespoň jednou za 1111 sekund. To v praxi znamená záplavu zpráv a doporučujeme nastavit hodnotu delta:10000 to znamená odeslat zprávu při změně zátěže o 10W (43 mA na 230V).
Publish sekce se skládá z jednotlivých segmentů. Segment vždy obsahuje:
- "topic":"netio/${DEVICE_NAME}/output/1/state"
Na který topic se publishují data
- "payload":"${OUTPUTS/1/STATE}",
Jaká data se publishují
- "events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
}
Při jaké akci se data publishují (v tomto případě při změně stavu výstupu)
Možné akce jsou: change, delta, timer
IF event, THEN pošli zprávu s hodnotou (payload) na topic
Příklad
"publish":[
{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":1111
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":1
}
]
}
Je možné posílat zprávy s těmito hodnotami:
- OUTPUTS/X/VOLTAGE" [V]
- OUTPUTS/X/CURRENT" [mA]
- OUTPUTS/X/POWER_FACTOR [1]
- OUTPUTS/X/LOAD mW
- OUTPUTS/X/STATE [1]
- OUTPUTS/X/ACTION
- OUTPUTS/X/DELAY unsigned int [ms]
- OUTPUTS/X/NAME [string]
- OUTPUTS/X/FREQUENCY [Hz] two decimals
- OUTPUTS/X/ENERGY [Wh]
- OUTPUTS/X/ENERGY_START [epoch]
- OUTPUTS/X/ENERGY_START_FMT [YYYY-MM-DD]
Vice informací k nastavení Subscribe sekce v MQTT-flex protokolu naleznete zde:
https://wiki.netio-products.com/index.php?title=MQTT-flex#Publish
Jak nastavit MQTT-flex protokol na vašem NETIO zařízení
Krok 1) Přihlaste se přes web na vaše NETIO zařízení.
Vlevo nahoře – označeno na dalším obrázku – je jméno zařízení.
Zde v příkladu používáme „NETIO-AN40“. Jméno se nastavuje v nabídce SETTINGS > SYSTEM > DEVICE NAME a zjistěte si jméno vašeho zařízení.
Vaše zařízení se bude jmenovat jinak, ale díky vložení proměnné „DEVICE_NAME“ do flex konfigurace se právě tohle jméno použije pro identifikaci zařízení. Stejně tak můžete použít unikátní MAC adresu když do MQTT-flex konfigurace vložíte proměnnou „DEVICE_MAC“.
Poznámka:
Všude kde zde v příkladu zobrazujeme „NETIO-AN40“ se použije jméno Vašeho zařízení.
Krok 2) Přejděte do M2M protokolů a povolte MQTT-flex protocol
Krok 3) Zkopírujte následující skript s nastavením do MQTT-flex Config oblasti a dejte „Save Changes“
{
"config":{
"broker":{
"url":"broker.hivemq.com",
"protocol":"mqtt",
"port":1883,
"ssl":false,
"type":"generic",
"username":"freedom",
"password":"peace|LOVE|empathy4ALL"
},
"subscribe":[
{
"topic":"netio/${DEVICE_NAME}/output/1/action",
"qos":0,
"target":"OUTPUTS/1/ACTION",
"action":"${payload}"
}
],
"publish":[
{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
}
]
},
{
"topic":"netio/${DEVICE_NAME}/output/1/load",
"qos":0,
"retain":false,
"payload":"${OUTPUTS/1/LOAD}",
"events":[
{
"type":"timer",
"period":1111
},
{
"type":"delta",
"source":"OUTPUTS/1/LOAD",
"delta":1
}
]
}
]
}
}
Zde je možné si nastavit vlastní přihlašovací údaje:
Krok 4) Pokud vše dopadlo dobře, měli byste vidět zelený text „Saved“ indikující, že se nastavení uložilo do paměti vašeho zařízení.
Krok 5) Zdali jste se úspěšně spojili s brokerem je možno také ověřit z logu NETIO PowerCable MQTT 101x WiFi zásuvky. Měli byste vidět alespoň tyto zprávy indikující úspěšné spojení:
Client connected – indikuje, že vaše chytrá zásuvka je připojena přes internet na HiveMQ server hostující MQTT broker
Subscribed XYZ – tento záznam ukazuje, že jste se úspěšně přihlásili k MQTT brokeru
a můžete použít „action“ topic pro ovládání zásuvky, což bude ukázáno později
Published netio/${DEVICE_NAME}/output1/state – ukazuje, že PowerCable odeslal zprávu s topicem netio/${DEVICE_NAME}/output1/state, která obsahovala aktuální stav zařízení
Jak připojit vaše NETIO zařízení přes MQTT-flex protokol na veřejný broker hostovaný HiveMQ
HiveMQ Websocket Client (zobrazení zpráv)
Krok 1) Jakmile máte připojenou vaší zásuvku k MQTT brokeru tak si otevřete tuto adresu:
http://www.hivemq.com/demos/websocket-client/
Krok 2) Vložte z MQTT nastavení co jste vložili dříve hodnotu „username“ (v našem případě ‚freedom‘) do pole Username a to samé pro Password zbytek polí nevyplňujte.
Krok 3) Jakmile jste hotoví tak klikněte na Connect.
Pokud jste vyplnili údaje správně tak byste měli vidět, že jste připojení.
Krok 4) Oveříme přes web rozhraní Websocket client, zda HiveMQ přijímá zprávy z připojeného zařízení PowerCable MQTT.
Přidáme „Subscription“, abychom viděli, zprávy z NETIO zařízení.
Krok 5) Do Topic sekce napište netio/NETIO-AN40/#.
NETIO-AN40 je jméno zařízení v ukázce.
Vaše zařízení na stole se bude pravděpodobně jmenovat jinak. Viz krok 1 (jméno Vašeho NETIO zařízení se zobrazuje na jeho webu vlevo nahoře pod zeleným „PowerCable MQTT“.
Kde se vzalo „netio/NETIO-AN40/#“ ?
HiveMQ Vám ukáže zprávy, definované topicem. Topic na kterém zařízení vysílá zprávy se definuje v MQTT-flex konfiguraci zařízení (sekce publish).
Zde uvedené nastavení zobrazení reaguje na zprávy označené jako:
"netio/${DEVICE_NAME}/output/1/state" s aktuální hodnotou stavu výstupu ("payload":"${OUTPUTS/1/STATE}")
"publish":[
{
"topic":"netio/${DEVICE_NAME}/output/1/state",
"qos":0,
"retain":true,
"payload":"${OUTPUTS/1/STATE}",
"events":[
{
"type":"change",
"source":"OUTPUTS/1/STATE"
}
]
}
wildcard – vysvětlení
v případě subscribe je možné v topicu použít tzv. „wildcard“ (#). Zápis netio/NETIO-AN40/# tak říká sleduj (subscribe) všechny Topicy z NETIO zařízení, které začínají „netio/NETIO-AN40/.
V AN40 použitém nastavení to budou dva topicy „load“ (energie [mW]) a „status“ (stav – 1 / 0).
Krok 6) A klikněte na Subscribe
Pokud MQTT broker již přijímá nějaké zprávy (běží a je správne nakonfigurovaný), tak se po kliknutí zobrazí nejaké zprávy.
Přinejmenším zpráva obsahující poslední stav zařízení (1 nebo 0) a pokud máte připojené nějaké zařízení (například lampu) tak při každé změně spotřeby (zapnutí a vypnutí lampy) se odešle zpráva na MQTT broker. Tuto zprávu můžete vidět přes Websocket client.
HiveMQ Websocket Client (ovládání výstupu)
Pro změnu stavu PowerCable výstupu můžete odeslat (publish) Topic: netio/NETIO-AN40/output/1/action a do Message sekce zapište hodnotu 4 (přepnutí (Toggle) stavu výstupu)
0 = Vypnutí výstupu (Off)
1 = Zapnutí výstupu (On)
2 = Vypnutí výstupu na krátkou dobu (Short OFF) – restart zařízení
3 = Zapnutí výstupu na krátkou dobu (Short ON)
4 = Přepnutí výstupu z jednoho stavu do druhého (Toggle)
5 = Ponechání stavu výstupu (no change)
Kliknutím na tlačítko „Publish“ odešlete příkaz přepnutí výstupu (výstupní zásuvka 230V NETIO PowerCable MQTT).
Po odeslání zprávy („Publish“), zařízení změní stav výstupu a odešle zprávu o změně stavu (MQTT-flex konfigurace – sekce „publish“ - "events" - "type":"change") .
Jak ovládat NETIO zařízení z mobilní aplikace přes MQTT protokol
Pro ovládání NETIO chytrých zásuvek přes MQTT doporučujeme použít aplikaci:
- Android - MQTT Dash https://play.google.com/store/apps/details?id=net.routix.mqttdash
- Apple iOS – MQTTool https://apps.apple.com/us/app/mqttool/id1085976398
Na ukázku bude použito MQTT Dash.
Přidání MQTT broker
Takto vypadá základní obrazovka po prvním otevření aplikace.
Krok 1) Nyní klikněte na zvýrazněnou ikonu vpravo nahoře pro přidání nového MQTT brokeru.
Krok2) Zadejte údaje HiveMQ brokeru.
Krok 3) A poté uložte opět zvýrazněnou ikonou vpravo nahoře.
Krok 4) A broker máme přidaný.
Krok 5) Nyní si rozklikněte broker pro přidání ovládacích prvků
Přidání ovládacích prvků
Krok 6) Klikněte na zvýrazněnou ikonu vpravo nahoře.
Krok 7) Ukáže se vám výběr ovládacích prvků, ze kterých je možno vybrat. Pro ukázku použiji Switch/button
Krok 8) Nastavte Switch/button prvek
U přidání Switch/button prvku stačí pouze nastavit jméno prvku a Topic na který bude publishovat zprávy.
Např. netio/NETIO-AN40/output/1/action
Víc informací ohledně možných topiců a dalších onformací ohledně NETIO MQTT-flex zde: https://wiki.netio-products.com/index.php?title=MQTT-flex
Krok 9) Opět uložte
Po uložení se vám přidá ovládací blok
A je to. Až takto jednoduché to je.
Nakonec může aplikace vypadat nějak takto:
FAQ
1) Co mám dělat, když HiveMQ je offline?
Chvíli počkat. HiveMQ je bezplatná služba, takže se může stát, že bude na chvíli nedostupná, ale nikdy ne na dlouho, takže stačí chvíli počkat, než bude zase online.
2) Co mám dělat, když potřebuji Apple iOS aplikaci?
Pro uživatele Apple iOS doporučujeme použít aplikaci MQTTool. Vyzkoušeli jsme ji a funguje podobně jako podrobně popsaná aplikace pro Android.
3) Jsem připojen v HiveMQ websocket clientu, ale pokaždé když dám Subscribe tak mě websocket odpojí?
Subscribe topic je ve špatném formátu.
Topic by měl být ve formátu netio/{DEVICE_NAME}/#
4) PowerCable nedovoluje uložit konfiguraci MQTT-flex protokolu?
Konfigurace je ve špatném formátu. Zkontrolujte, zdali jste správně zkopírovali/nastavili konfiguraci.
5) Lze použít nastavitelné MQTT-flex v produktech NETIO 4x (NETIO 4All / NETIO 4 / PowerPDU 4C)?
Podporu plánujeme, ale v době psaní – Září 2019 to ještě podporované není.
6) Lze odesílat MQTT data z elektrického měření pouze jednou za čas?
Ano, je možné použít kombinaci akcí, které NETIO MQTT-flex podporuje: change, delta, timer.
7) Lze vytvořit v MQTT-flex formát kompatibilni se standardním NETIO MQTT?
Standartní NETIO M2M MQTT má Payload ve formátu JSON.
Pro NETIO-flex bude tato funkce přidána do konce roku 2019.
8) Může NETIO zařízení pomocí MQTT-flex přijímat / odesílat zprávy pro několik topiců najednou?
Ano, v rámci jednoho MQTT brokeru lze nastavit více topiců pro publish i subscribe jako pole v sekcích „publish“ a „subscribe“.
9) Lze propojit několik NETIO zařízení mezi sebou pomocí MQTT-flex
Ano, v rámci jednoho MQTT brokeru lze nastavit situaci, kdy Device-B kopíruje na svém výstupu stav výstupu na Device-A.
Podporované verze FW PowerCable MQTT:
2.0.2 a vyšší (Archiv firmware)