AN30 Node-RED příklad REST JSON komunikace s NETIO 4x

Tags: 
User library

Aplikační poznámka AN30 je ukázka jak z Node-RED číst měření spotřeby a ovládat (přepínat výstupy) pro chytré elektrické zásuvky NETIO 4x a PowerCable REST pomocí REST API – JSON. Soubor netio.json se přenáší pomocí http. Node-RED je programovací nástroj pro propojení hardwarových zařízení, API a online služeb. Může běžet v Cloudu, na lokálním PC nebo například v Raspberry Pi.

 

Do you have any questions?

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

 

Příklad AN30 obsahuje dva příklady práce s NETIO zásuvkami pomocí http přenosu netio.json 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 AN30v2 je zjednodušená verze prakticky použitelná pro Vaše Node-RED projekty.

 

První AN30 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.json se zapisuje do http serveru chytrých zásuvek 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.json každou sekundu z http serveru zařízení (NETIO zásuvky) pomocí http GET.

Podrobnosti o M2M protokolu: Popis protokolu http(s) REST JSON

 

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 AN30:


 

Dashboard pro AN30:

 

NETIO REST JSON 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ěná Action v odeslaném souboru netio.json 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ěná 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 JSON.
 

Ukázka JSON souboru pro změnu stavu (Toggle / přepnutí) výstupu číslo 1:

{

 "Outputs": [{

  "ID": 1,

  "Action": 4

 }]

}

 

Nastavení NETIO 4x chytrých zásuvek

Ve webovém rozhraní zařízení v sekci M2M API Protocols - JSON API , je třeba povolit URL JSON 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).

 

Try online demo on the NETIO 4All product 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.

AN30 flow (skript)

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

 NETIO AN30: Node-RED flow ke stažení

 

Import AN30 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ů.

Bloky 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 bloky, které vám chybí.

 

Jak funguje AN30 (JSON REST API) Flow

 

AN30 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.json 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.json 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.json jako GET request a vrátí jako odpověď od serveru kompletní JSON soubor se stavem zásuvky.
  • Blok JSON Parse změní JSON soubor, který dostal od HTTP Request (GET) bloku na JSON Object, díky čemuž je možno pracovat s jednotlivými vlastnostmi JSON souboru.
  • Blok Function bere jednotlivé části JSON 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 JSON 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í netio.json soubor.

Jako payload je nastaven netio.json soubor.

netio.json soubor 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 netio.json souboru:

 

HTTP Request node

HTTP Request (POST)

Tento blok odesílá ovládací netio.json 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 AN30 zobrazují proud, napětí, model, verzi firmwaru či JSON 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.

 

JSON node

Tento blok parsuje JSON soubor na JSON objekt.

HTTP Request node na GET request vrátí jako odpověď od serveru JSON 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 JSON soubor na JSON 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 AN30 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 AN30 tato funkce vybírá hodnoty z naparsovaného JSON souboru (nyní již JSON objekt) a přiděluje je vlastnostem msg objektu. 

 

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

  • Přidělování hodnot z JSON 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 JSON objektu danou vlastnost např.: msg.payload.GlobalMeasure.Voltage, protože JSON 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 AN30 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:

 

AN30 v2 flow (skript)

AN30v2 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.

AN30 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.

 AN30 v2: Node-RED flow ke stažení

 

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 outputů, tak číslo outputu lze změnit změněním čísla ID v ovládacím NETIO.json souboru v Button nodu.

Příklad: {"Outputs":[{"ID":2,"Action":1}]}

 

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 JSON souborů ?

Ne, JSON 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. AN30 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.
 

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.json souboru. Zkontrolujte ve všech button nodes, zdali jsou tam NETIO.json soubory správně napsány

 

 

 

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í

Ask for a price or technical parameters

For device testing use name/password demo/demo