AN21 JSON HTTP(S) ovládání chytrých NETIO zásuvek 230V (REST API 3x jinak)

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

Výhody JSON protokolu:

• Struktura json souborů je snadno pochopitelná a existuje na ni řada nástrojů.
• Díky podpoře https lze přenos snadno a standardně zabezpečit.
• Díky přenosu přes http a standardně na portu 80 je M2M API protokol typu JSON přes http(s) odolný proti problémům s firewally a různým bezpečnostním omezením ve velkých firmách.
• Ovládání je obousměrné (READ – měření spotřeby, WRITE – zapni/vypni). Pomocí http get lze stáhnout /netio.json soubor se stavem zařízení a jednotlivých výstupů (zásuvek). Ovládat výstupy lze odesláním souboru na adresu /netio.json přes http post.
• Přečtení stavu je uživatelsky přívětivé (prostě kliknete a zobrazte v prohlížeči). Pro zápis .json souborů směrem do zařízení připravilo NETIO funkci HTTP(s) file upload. Lze díky ní snadno poslat předem připravené 3 .xml nebo .json soubory.

Jak funguje NETIO REST JSON http(s) protokol

1) Povolte na webu zařízení - M2M API Protocols – JSON API a nechte bez hesla v položce READ-ONLY. Jestli nebylo dosud nebylo povoleno, uložte (zařízení se zrestartujte).

2) Stav zařízení (ON/OFF zásuvek + spotřeba elektřiny) lze zjistit v souboru /netio.json na IP adrese zařízení. Soubor netio.json lze stáhnout přes http(s) a zobrazit v prohlížeči stejně jako webová stránka.

NETIO online dema

a. http://netio-4c.netio-products.com

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

3) Ovládání výstupů přes JSON protokol probíhá zápisem souboru netio.json do zařízení pomocí http(s) post. Zápis souboru je vhodné zabezpečit heslem.  Soubor „netio.json“ musí dodržet správný formát.

4) Pro posílání souborů lze použít spoustu různých utilit a nástrojů, ale pro zjednodušení jsme NETIO uživatelům připravili přímo do webu zařízení nástroj HTTP(s) file upload, který vše velmi zjednoduší.

5) NETIO AN21 demonstruje přenos textového souboru pomocí netio.json p5es http(s) pomocí 3 různých způsobů:

• AN21a: Device web - HTTP(s) file upload
• AN21b: Chrome - Advanced REST client
• AN21c: CMD - cURL

6) V naší implementaci REST JSON protokolu lze během jednoho TCP/IP spojení na http server zařízení provést zápis a ověřit nový stav. Ovládající odešle soubor netio.json (http post) a po provedení akce (například přepnutí výstupu) přijme aktualizovaný soubor netio.json pro ověření výsledku.

Podrobný popis struktury NETIO REST JSON protokolu najdete v M2M REST JSON dokumentaci.

NETIO REST JSON http(s) protokol

Aktuální stav každého výstupu v okamžiku čtení (0 / 1) je uveden v souboru netio.json v proměnné State. Proměnnou v tagu State lze použít pro čtení i zápis.

Pokud chcete pro zápis hodnoty (ovládání výstupu) použít proměnnou State, je třeba vynechat proměnnou Action, nebo ji nastavit na hodnotu Action = 6.

Action

Pro nastavení výstupu na krátké vypnutí (short Off) nebo přepnutí do druhého stavu (Toggle) lze použít u každého výstupu místo proměnné State proměnnou Action.

Proměnná Action je určena pouze pro zápis, při čtení zobrazí vždy 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.

Hodnoty Action:

• 0 = Vypnutí výstupu (Off)
• 1 = Zapnutí výstupu (On)
• 2 = Vypnutí výstupu na krátkou dobu (short Off / restart)
• 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 (pro zápis použij proměnnou State)

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.

AN21a: Device HTTP(s) File Upload

Ovládání zařízení pomocí JSON souboru lze snadno otestovat přímo z webu produktu, pomocí webového nástroje pro posílání textových souborů do zařízení „DEVICE HTTP(S) FILE UPLOAD“.

Otevřete webové rozhraní vašeho NETIO 4x zařízení.

Přejděte na M2M API Protocols -> JSON API

Povolte Používání JSON API protokolu, případně si nastavte heslo a port.

Dole na stránce je možné stáhnout do počítače již hotové vzorové .json soubory, pomocí nichž se dá ovládat NETIO 4x zařízení.

Klikněte na Upload JSON file to the device.

Klikněte na Choose file. Otevře se průzkumník souborů.

Vyberte .json soubor, který jste si buď stáhli nebo napsali.

Je možné nahrát najednou až 3 netio.json soubory, pro ovládání vaší chytré NETIO 4x zásuvky.

Vsiměte si, že nezávisle na jménu zdrojového souboru se vždy struktura posílá do souboru /netio.json

Po odeslání se dole vypíše odpověď od HTTP serveru. Pokud vše proběhlo v pořádku, vypíše se netio.json soubor obsahující informace o stavu zařízení. Pokud se něco pokazilo, vypíše se chybová hláška s detaily chyby.

Pokud máte nastavené heslo na vašem NETIO 4x zařízení, tak je nutné přidat header s autorizací.

AN21C: cURL

Ke stažení zde: https://curl.haxx.se/download.html

Po rozbalení není nutné mít utilitu curl v systémovém adresáři, curl lze spustit odkudkoliv.

cURL je nástroj v příkazové řádce pro přenášení dat pomocí URL.

Použitá verze: curl 7.55.1 (Windows) libcurl/7.55.1 WinSSL

curl -u netio:netio -d "{\"Outputs\":[{\"ID\":1,\"Action\":4}]}" -H "Content-Type: application/json" -X POST http:// 192.168.101.181:80/netio.json

Curl příkaz se skládá z několika částí: curl autorizace JSON -H "Content-Type: application/json URL

Pokud je vše v pořádku, měli byste dostat odpověď od serveru, že je vše v pořádku  v podobě JSON souboru obsahujícím informace o stavu NETIO 4x zařízení.

Tudíž pokud používáte windows, tak Váš curl příkaz může vypadat nějak takto:

curl -u netio:netio -d "{\"Outputs\":[{\"ID\":1,\"Action\":4}]}" -H "Content-Type: application/json" -X POST http:// 192.168.101.181:80/netio.json

Pokud používáte jiný operační systém, tak by váš příkaz může vypadat nějak takto:

curl -u netio:netio -d '{"Outputs":[{"ID":1,"Action":4}]}' -H "Content-Type: application/json" -X POST http://192.168.101.181:80/netio.json

cURL URL

-X POST your IP address/netio.json

-X POST http:// 192.168.101.181:80/netio.json

FAQ

1) Je možné použít IP adresu online dema ?

Ano, pro vyzkoušení lze použít IP adresu NETIO online dema, adresu najdete na stránkách jednotlivých produktů.

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

Ano, má-li zařízení více výstupů, číslo výstupu je uvedeno v ID v ovládacím netio.json souboru v JSON struktuře.

Příklad: {"Outputs":[{"ID":3,"Action":4}]}

3) Jak mohu nainstalovat cURL na PC?

Na oficiálních stránkách je možné zadarmo stáhnout cURL.

Website: https://curl.haxx.se/download.html

4) Lze nainstoval cURL i na jiný operační systém než windows?

Ano, cURL se běžně používá například na unixových systémech.

5) Je možné použít Advanced REST client i bez Google Chrome ?

Ano, Advanced REST client lze stáhnout jako program. Je podporována většina operačních systémů.

Website: https://install.advancedrestclient.com/install

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)