AN31 Node-RED příklad REST XML komunikace s NETIO 4x

Tagy: 
User library

Node-RED je programovací nástroj pro propojení hardwarových zařízení, API a online služeb. Aplikační poznámka AN31 představuje jak z Node-RED ovládat NETIO chytré elektrické zásuvky s výstupem 110/230V pomocí HTTP  - REST XML.

 

Můžeme Vám nějak pomoci?

Podporovaná zařízení: NETIO 4All, NETIO PowerPDU 4C, NETIO 4, PowerCable REST, PowerBOX 3Px, PowerPDU 4PS, PowerDIN 4Pz, PowerBOX 4Kx, PowerPDU 8QS

 

Node-RED je unikátní nástroj díky částečně grafickému propojení programových bloků. NETIO používá ve svých příkladech standardní bloky jako je http get, parsování hodnot z XML struktury a podobně, aby uživatel rozuměl zpracování dat.

Příklad NETIO AN31 obsahuje dva příklady práce s NETIO zásuvkami pomocí http přenosu netio.xml souborů.

  • První příklad lépe vysvětluje funkce a možnosti měření a ovládání jednoho výstupu (Output 1).
  • Druhý příklad AN31v2 je zjednodušená verze prakticky použitelná pro Vaše Node-RED projekty.

 

První AN31 Node-RED skript (flow) demonstruje ovládání výstupu 1 z Dashboardu, který běží v prostředí Node-RED. Pět tlačítek zobrazených na Dashboardu volá všechny možné akce výstupu (vypni, zapni, krátké vypnutí (restart), krátké zapnutí, přepnutí stavu). Soubor netio.xml se posílá do http serveru chytrých zásuvek metodou http POST.

V dashboardu se periodicky zobrazují stavy všech výstupů a měřené hodnoty z NETIO 4x zařízení (proud, napětí, celkové zatížení zařízení), pokud zařízení umí měřit elektrické hodnoty. Čtení stavu výstupů a měřených hodnot probíhá pomocí stahování souboru netio.xml každou sekundu z http serveru zařízení (NETIO zásuvky) pomocí http GET.

Podrobnosti o M2M protokolu: Specifikace protokolu NETIO XML http(s) REST

 

Node-RED

Prostředí Node-RED lze spustit na lokálním PC, na Raspberry Pi, v cloudu (MS Azure, IBM) a podobně.

Díky popularitě Node-RED jsme pro Vás připravili víc příkladů:

 

Flow (Node-RED skript) pro AN31:


 

Dashboard pro AN31:

 

Jak funguje NETIO REST XML http(s) protokol

Aktuální stav zásuvky v okamžiku čtení (0 / 1) je uveden v proměné State. Tato proměnná je určena pro čtení i zápis, pokud není proměná Action uvedena vůbec, nebo je nastavena na hodnotu 6.

Pokud je proměnná Action v odeslaném souboru netio.xml nastavena na jinou hodnotu než 6, dostane přednost a hodnota nastavená v proměnné State bude ignorována.

 

Akce, které lze aplikovat na každý výstup (elektrickou zásuvku)

NETIO elektrické zásuvky používají ve všech M2M protokolech stejné akce, které lze vykonávat na jednotlivých zásuvkách. Do každého výstupu lze například zapsat akci typu Toggle=přepni na druhý stav, nebo Short Off=vypni na několik sekund.
 

Proměnná Action je ale určena pouze pro zápis hodnoty, nelze z ní číst aktuální stav elektrické zásuvky.

  •  0 = Vypnutí výstupu (Off)
  •  1 = Zapnutí výstupu (On)
  •  2 = Vypnutí výstupu na krátkou dobu (short Off)
  •  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)
  •  6 = Ignorováno

Hodnota 6 v tagu akce znamená, ignoruj číslo akce a zapiš hodnotu v proměnné “State” kde se vyskytuje pouze 0 nebo 1. Viz dokumentace k M2M XML.

Ukázka XML souboru pro přepnutí stavu výstupu 1

<set:Root xmlns:set="http://www.netio-products.com/XMLSchema/NETIO.xsd">

              <Outputs>

                            <Output>

                                          <ID>1</ID>

                                          <Action>4</Action>

                             </Output>

              </Outputs>

</set:Root>

 

Nastavení NETIO 4x chytrých zásuvek

Ve webovém rozhraní NETIO 4x v sekci M2M API Protocols – XML API, je třeba povolit URL XML API.

Nastavte Username a Password pro READ-WRITE.

READ-WRITE přihlašovací údaje fungují pro čtení i zápis. V obou HTTP Request blocích (POST i GET) lze použít tytéž READ-WRITE přihlašovací údaje.

Pro uložení stiskněte tlačítko Save Changes. Po uložení dojde k restartu zařízení (cca 1 minuta).

 

Online demo access on NETIO device web

NETIO 4All Online demo

Online demo je fyzické zařízení NETIO, připojené na internetu na veřejné IP adrese. Výrobce poskytuje Online demo zařízení pro každý model. Online dema mají různou konfiguraci a lze tak otestovat chování aniž byste měli zařízení fyzicky v ruce.

Online dema nelze překonfigurovat.

Na Online demo každého produktu se dostanete z ikony „TRY ON-LINE DEMO“ na stránce každého produktu.

 

Node-RED

Node-RED je programovací nástroj pro spojení hardwarových zařízení, API a online služeb v novém a zajímavém způsobu. Node-RED nabízí flow editor v browseru a veliký výběr bloků a možností. Navíc je postavený na Node.JS, což mu umožnuje běžet na nízkorozpočtových zařízeních jako Raspberry Pi a dokonce i v cloudu.

AN31 flow (skript)

Konfigurace pro node-RED se přenáší jako json struktura a lze ji vložit přes clipboard.

>> AN31: Node-RED flow

 

Import AN31 flow (skriptu) do node-RED

V menu vyberte Import -> Clipboard.

Následně zkopírujte text do označeného pole a dejte import.

 

Instalace chybějících bloků.

Nodes se vám nahrají do vybrané flow. Je možné, že se vypíše chybová hláška se seznamem bloků, které se snažíte naimportovat, ale nemáte je ještě nainstalované v Node-RED. V takovémto případě si musíte dané bloky doinstalovat.

V případě chybějících nodes v menu vyberte Manage palette -> klikněte na Install a vyhledejte nodes, které vám chybí.

 

Jak funguje AN31 (XML REST API) Flow

 

AN31 se primárně skládá ze dvou částí: POST a GET

POST: Zápis O1

  • Pět tlačítek vytvořených v dashboardu ve Flow se zobrazuje na Dashboardu
  • Po zmáčknutí tlačítka Output 1 = ON v Dashboardu, se nastaví payload na netio.xml soubor určující output a akci (definováno na každém tlačítku, podle akcí výstupu).
  • Blok HTTP Request (POST) odešle netio.xml soubor jako request na IP adresu.
  • Odpověď od serveru (stav odeslání) vrátí jako výstup.
  • Blok Msg.payload zobrazí výstup od HTTP Request (POST)

 

GET: Čtení O1 – O4

  • Blok 1 Second Repeat po sekundových intervalech spíná HTTP Request (GET) blok, který odešle netio.xml jako GET request a vrátí jako odpověď od serveru kompletní XML soubor se stavem zásuvky.
  • Blok XML Parse změní XML soubor, který dostal od HTTP Request (GET) bloku na XML Object, díky čemuž je možno pracovat s jednotlivými vlastnostmi XML souboru.
  • Blok Function bere jednotlivé části XML objektu a nastavuje je jako vlastnosti msg objektu, pro pozdější použití.
  • Blok Current Chart je funkce, která nastavuje msg.payload na vlastnost msg objektu msg.TotalCurrent, protože Current Chart (Device) blok, který je na ní napojen je schopen zobrazit pouze hodnotu msg.payload.
  • Poté následují různé výstupní bloky, které zobrazují v Dashboardu vybrané vlastnosti msg objektu, kterému jsme přiřadili vlastnosti z XML  objektu. 

 

Msg object a msg.payload

Je jednodušše a přehledně vysvětleno zde:

http://www.steves-internet-guide.com/node-red-message-object/

 

Node-RED flow bloky

Button node

Přidá Button do Dashboardu.

Kliknutí na Button node generuje zprávu obsahující msg.payload.

Jako payload je nastaven XML string.

XML string lze upravit a zobrazit kliknutím na označené tlačítko.

Možnosti akce výstupu:

  • 0 = Vypnutí výstupu  (Off)
  • 1 = Zapnutí výstupu (On)
  • 2 = Vypnutí výstupu na krátkou dobu (short Off)
  • 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)

 

Ukázka XML stringu:

<set:Root xmlns:set="http://www.netio-products.com/XMLSchema/NETIO.xsd">

            <Outputs>

                       <Output>

                                   <ID>1</ID>

                                   <Action>4</Action>

            </Output>

            </Outputs>

</set:Root>

 

 

HTTP Request node

HTTP Request (POST)

Tento blok odesílá ovládací netio.xml soubor jako HTTP Request (POST) a tím ovládá NETIO 4x zařízení.

 

HTTP Request (GET)

Tento blok odešle HTTP Request (GET) a vrátí odpověď o stavu doručení.

 

Předvyplněná adresa je online demo, kde můžete vyzkoušet spojení, aniž byste měli NETIO zařízení na stole.

http://netio-4all.netio-products.com

V těchto blocích je možno nastavit si vlastní IP adresu, ale je nutné změnit IP adresu v obou HTTP Request blocích, POST i GET.


Text node

Zobrazí textové pole v Dashboardu. V AN31 zobrazují proud, napětí, model, verzi firmwaru či XML verzi.

Label určuje název, který se zobrazuje v dashboardu a Name určuje jméno bloku, které se zobrazuje ve Flow v node-REDu.

{{msg.O1_Color}} mění barvu textu podle hodnoty {{msg.O1_State}}.

 

 

Debug node

Vypisuje msg.payload.

Defaultně je nastaven na msg.payload a tudíž v tomto případě zobrazuje v node-RED odpověď od serveru

 

XML node

Tento blok parsuje XML soubor na XML objekt.

HTTP Request node na GET request vrátí jako odpověď od serveru XML soubor obsahující aktuální informace o vašem NETIO 4x zařízení.

Pokud ale chceme s jednotlivými hodnotami pracovat, tak je nutné naparsovat XML soubor na XML objekt.

 

Inject node

Tento blok po sekundových intervalech aktivuje HTTP Request node, který odešle GET request díky čemuž se v Dashboardu aktualizují hodnoty po sekundových intervalech.

 

Chart node

Tento blok vykresluje graf proudu v Dashboardu  podle payload hodnoty.

Tento blok umí vykreslit graf pouze podle payload hodnoty.

Proto je použit pomocný function node. Nastavuje jako msg.payload pouze tu hodnotu, kterou chceme zobrazit.

msg.payload = msg.TotalCurrent;

 

Gauge node

Tento blok přidává do Dashboardu widget měřiče.

V AN31 zobrazuje každý jednu vlastnost msg objektu: Napětí [V], proud [A], frekvenci [Hz] a Overall True Power Factor (TPF).

 

Function node

Function node je speciální node, který umožňuje napsat si vlastní JavaScript funkci.

V AN31 tato funkce vybírá hodnoty z naparsovaného XML souboru (nyní již XML objekt) a přiděluje je vlastnostem msg objektu.

 

Kód rozdělen do čtyř částí:

  • Přidělování hodnot z XML objektu jednotlivým vlastnostem msg objektu

 

  • Error handling v případě, že NETIO 4x zařízení nepodporuje měření globálních hodnot

 

V případě, že vaše NETIO 4x zařízení nepodporuje měření globálních hodnot, se v node-RED vypisují chyby, protože tato funkce nemůže najít v XML objektu danou vlastnost např.: msg.payload["set:Root"].GlobalMeasure[0].Voltage[0], protože XML objekt ji neobsahuje. A v tomto případě je nastavena vlastnost msg objektu např.: msg.Voltage na 0 a chyba je odchycena a nenastane.

 

  • Přidělení hodnot stavu outputů

 

  • Měnění barvy zobrazené hodnoty stavu outputu podle stavu outputu

 

Link node

Link node in a out fungují jako tunel.

Do link node in dojde msg.payload a z link node out zase vyjde.

V AN31 je použit pouze ke zpřehlednění flow.

 

Node-RED Dashboard

Dashboard je grafickým zobrazením dashboard prvků.

Dashboard lze otevřít kliknutím na označený symbol, nebo na adrese vašeho node-RED serveru s přidáním ui na konci adresy.  například 127.0.0.1:1880/ui.

 

V Dashboard je v menu uveden odkaz na stránky NETIO products:

 

AN31 v2 flow (skript)

AN31v2 je zjednodušená verze prakticky použitelná pro Vaše Node-RED projekty, kde potřebujete jen číst stav zásuvek a ovládat je.

AN31 v2 funguje jako ovladač výstupů 1 až 4 a čtení jejich stavů.

 

 

Konfigurace pro node-RED se přenáší jako JSON struktura a lze ji vložit přes clipboard.

>> AN31 v2: Node-RED flow

 

FAQ

1) Je možné použít jinou IP adresu než předvyplněnou?

Ano, IP adresu lze nastavit v HTTP Request nodech, ale je nutné ji změnit v obou. HTTP Request (POST) i HTTP Request (GET) node.

 

2) Je možné ovládat jiný output než output 1?

Ano, má-li zařízení více výstupů (například NETIO 4x), lze číslo výstupu (1 až 4) změnit změněním čísla ID v ovládacím XML stringu v Button nodu.

Příklad: Toggle output 2

<set:Root xmlns:set="http://www.netio-products.com/XMLSchema/NETIO.xsd"> 

<Outputs>  

<Output>   

<ID>2</ID>   

<Action>4</Action>  

</Output> 

</Outputs>

</set:Root>

 

3) Provedl/a jsem změny ve Flow v node-RED, ale v dashboardu se změny neprojevily.

Pro zobrazení a uložení změn ve všech Flow je nutné dát v node-RED v pravo nahoře Deploy.

 

4) Jak mohu nainstalovat Node-RED na PC?

Na oficiálních stránkách node-RED je podrobný návod + free installer.

Website: https://nodered.org/docs/getting-started/

 

5) Lze nainstoval Node-RED i na jiná zařízení než PC ?

Ano, node-RED může být spustěn např. Raspberry Pi, Arduino nebo Microsoft Azure.

 

6) Je třeba mít speciální program pro úpravu XML souborů ?

Ne, XML soubor je v zásadě prostý textový soubor a díky tomu ho lze otevřít a upravovat dokonce i v poznámkovém bloku nebo ve MS Word.

 

7) Lze použít i DNS vyjádření IP adresy ?

Ano, lze použít číselné i textové vyjádření.

Defaultně je například nastavena DNS adresa Online Dema pro NETIO 4All. AN31 lze vyzkoušet aniž musíte mít zařízení na stole.

 

8) V node-RED v debug sekci se mi vypisuje {"Result":{"Error":{"Code":401,"Message":"Unauthorized"}}}.

Jsou špatně přihlašovací údaje. Je možné, že jste použil READ-ONLY přihlašovací údaje i pro metodu zápisu (WRITE) do zařízení na HTTP POST.
Přihlašovací údaje READ-WRITE lze použít pro čtení i zápis souboru netio.xml.
 

9) V node-RED v debug sekci se mi vypisuje Error: connect ETIMEDOUT.

Pravděpodobně je špatně IP adresa.
 

10) V node-RED v debug sekci se mi vypisuje "{"Result":{"Error":{"Code":400,"Message":"Bad request"}}}"

Špatný formát netio.xml souboru. Zkontrolujte syntaxi ve všech button nodes. Je třeba přesně dodržet syntaxi netio.xml souboru.

 

 

 

Podporované verze FW pro NETIO 4x:

3.1.0 a vyšší (Archiv firmware)

 

Podporované verze FW pro PowerCable xxx:

2.0.2 a vyšší (Archiv firmware)

 

 

Podporovaná zařízení

Zeptejte se na cenu nebo technické parametry

Pro otestování zařízení použijte jméno/heslo demo/demo