AN20 XML HTTP(s) ovládání NETIO zásuvek na 230V

Tagy: 
M2M API

Aplikační poznámka AN20 demonstruje ovládání chytrých zásuvek NETIO 4x pomocí XML protokolu. Protokol XML přenáší textový soubor s xml strukturou přes http(s). NETIO zásuvky obsahují nástroje pro snadné otestování tohoto protokolu uživatelem.  XML protokol podporují všechna NETIO 4x zařízení (NETIO 4 / 4All / 4C). 

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

XML přes http(s) je jeden z preferovaných protokolů.



Výhody XML protokolu:

  • Struktura XML 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 XML http(s) nejméně náchylný k 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é.
    Pomocí http get lze stáhnout /netio.xml soubor se stavem zařízení a jednotlivých výstupů (zásuvek).
    Ovládat výstupy lze odesláním souboru na adresu /netio.xml přes http post.
  • Přečtení stavu je uživatelsky přívětivé (prostě kliknete v prohlížeči).
    Pro zápis XML souborů směrem do zařízení připravilo NETIO funkci HTTP(s) file upload. Tou lze snadno poslat předem připravené 3 .xml soubory.

 

Jak funguje NETIO XML http(s) protokol

  1. Povolte na webu zařízení - M2M API Protocols – XML 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í NETIO 4x (ON/OFF zásuvek + spotřeba elektřiny pro model NETIO 4All) lze zjistit v souboru /netio.xml na IP adrese zařízení. Soubor netio.xml se stáhne přes http(s) a zobrazí se v prohlížeči stejně jako webová stránka.
  3. Ovládání přes XML je trochu složitější, protože je potřeba se správným heslem přenést do NETIO 4x zařízení pomocí protokolu http(s) post na správném portu soubor „netio.xml“, který bude mít správný formát. Http(s) se ještě může zeptat na heslo pro zápis souboru.
  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 nástroj HTTP(s) file upload, který vše velmi zjednoduší. Pro ověření funkce XML protokolu lze použít před-připravené .xml soubory. Viz dále.
  5. V NETIO implementaci XML protokolu lze během jednoho TCP/IP spojení na http server zároveň odeslat netio.xml soubor (přes http post) a po provedení akce přijmout aktualizovaný soubor netio.xml.
    Popis XML struktury (XSD soubor) je ke stažení v zařízení. Podrobný popis struktury NETO XML protokolu najdete v M2M XML dokumentaci. Vyžádejte si formulářem poslední verzi.

 

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. Přečíst lze ale jen stav zásuvky v okamžik čtení (0 / 1), akce výstupu lze do zařízení pouze zapsat.

 

  • 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)

 

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

 

Ukázka XML M2M API pomocí online dema

Co to je Online Demo

Online demo je reálné zařízení NETIO, připojené na internetu na veřejné IP adrese. Do zařízení se vstupuje přihlašovacím jménem a heslem „demo“ / „demo“ a lze otestovat chování web rozhraní zařízení a ovládat jednotlivé výstupy.

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.

 

Online demo pro NETIO 4ALL: https://www.netio-products.com/en/device/netio-4all

Nastavení XML API v online demu NETIO 4All:

 

Náhled na soubor netio.xml lze otevřít odkazem z web rozhraní.
http://netio-4all.netio-products.com:8080/netio.xml.

 

Výpis obsahu souboru netio.xml z online dema:

 

Ovládání chytrých zásuvek NETIO přes HTTP XML lze vyzkoušet pomocí produktu na Vašem stole, stejně jako oproti ONLINE DEMO zařízení. Postup jak posílat do zařízení .xml soubor s výběrem příkazů v nástroji HTTP(s) file upload  je dále popsán podrobněji. Můžete si jej také vyzkoušet přes online demo.

 

XML soubor, který přepne výstup 1

Ukázka jednoduchého .xml souboru, který přepne stav prvního výstupu:

 

Obsah souboru pro přepnutí stavu prvního výstupu:


 
  
   1
   4

Jak otestovat XML rozhraní na NETIO 4x

Následující postup předpokládá, že máte chytré zásuvky NETIO 4x k dispozici. Pro otestování lze použít online demo.

 

Povolení XML API

Ve webové administraci produktu NETIO 4x v sekci M2M API Protocols - XML API, povolte XML API. Zařízení je možné používat ve 2 režimech. V režimu READ-ONLY je možné pouze získávat data z NETIO (GET), režim READ-WRITE slouží k ovládání stavu výstupu.

Každý režim má odlišné heslo. Heslo může být prázdné.

Nastavení uložte kliknutím na tlačítko Save Changes. Po uložení dojde k restartu zařízení (cca 1 minuta).

 

Přepínání výstupů pomocí předpřipraveného xml souboru

  • Uvnitř web rozhraní NETIO zařízení je v nástroj HTTP(s) file upload, přes který je možné nahrát .xml soubor do zařízení.
  • V záložce pro konfiguraci XML API jsou předpřipravené tři ukázkové .xml soubory, které stačí stáhnout do PC.
    • Set output 1 to ON - zapne výstup 1
    • Set output 1 to OFF - vypne výstup 1
    • Toggle output 1 - přepne výstup 1 do opačného stavu

 

1) Download předpřipraveného .xml souboru

Ukázkový .xml soubor lze stáhnout a uložit na disk kliknutím na jeden z odkazů

 

2) Uložení vzorového xml souboru na disk

 

Po uložení lze .xml soubor lze otevřít i editovat například v Poznámkovém bloku (Notepad) nebo WordPadu

 

3) Použití nástroje HTTP(s) file upload

Pomocí tlačítka Upload XML file to the device otevřete nástroj HTTP(s) file upload. Tím lze odesílat do konfigurovaného zařízení xml soubory z lokálního PC.

 

Otevření nástroje HTTP(s) file upload:

 

Klinkutím na tlačítko „Upload XML to the device“  otevřete nástroj HTTP(s) file upload:

 

4) Nastavení HTTP(s) file upload

  • Host
    • http://<NETIO_IP>/netio.xml
    • Stačí ponechat výchozí nastavení (aktuální zařízení)
    • Všimněte si, že nezávisle na jménu Vašeho .xml souboru se vždy nahrává soubor /netio.xml
  • Port
    • Výchozí http port je 80
  • Username
    • Uživatelské jméno pro READ-WRITE
  • Password
    • Heslo pro READ-WRITE

 

  • Po stisknutí tlačítka Choose file je nutné vybrat .xml soubor, který jste si předtím stáhli do počítače (případně nějak pozměnili).

 

 

5) Odeslání souboru přes nástroj HTTP(s) file upload

Stisknutím tlačítka Send file se soubor odešle.

Při výběru více souborů je lze odesílat v potřebném pořadí.

 

Po odeslání .xml souboru se výstupy nastaví do požadovaných stavů. Pokud nemáte zařízení na stole, lze to zkontrolovat na stránce Outputs v zařízení.

Po odeslání .xml souboru se v rámečku „Response“ zobrazí odpověď, kterou zaslalo NETIO. Jako odpověď pošle NETIO zpátky kompletní .xml soubor, aby tím potvrdilo například přepnutí výstupu. 

Pokud se tato odpověď nezobrazí, („---“ nebo „error“) zkontrolujte nastavení.

 

Popis XML struktury souboru netio.xml

Zde ve stručnosti popíšeme XML strukturu pro soubor netio.xml.
Podrobný popis struktury najdete v XML M2M dokumentaci, která je na vyžádání k dispozici.

  • Soubor netio.xml lze stáhnout ze zařízení (pokud je XML API aktivní) jako /netio.xml nebo kliknutím na odkaz vlevo pod čárou v sekci „Test XML API“. 

 

  • Pro XML strukturu existuje popisný XSD soubor. Ten stáhnete po kliknutí na tlačítko „Download XML Schema (XSD)“

 

Struktura XML souboru

Struktura je složena ze tří hlavních sekcí
 

  • Agent
    • V této sekci se nachází hlavní informace o zařízení (model, verze firmwaru apod.)

 

  • GlobalMeasure*
    • Zde je možné najít měřené proměnné, které se vztahují k celému zařízení (napětí, frekvence, celkový proud, apod.)

 

  • Outputs
    • V této sekci je stav jednotlivých výstupů. Každý výstup má svou vlastní sekci Output, která se liší v ID..
    • ID
      • ID výstupu
    • Name
      • Jméno výstupu, je možné ho změnit ve webové aplikaci v sekci Outputs
    • State
      • Stav, ve kterém se výstup v danou chvíli nachází (hodnota 0 nebo 1)
    • Action
      • Proměnná s akcí pro změnu stavu zásuvky, v režimu pro čtení je její hodnota vždy 6.
    • Delay
      • Zpoždění pro akce 2 a 3. Nastavitelná ve webové aplikaci v sekci Outputs (proměnná Switch delay).
    • Current*
      • Proud procházející daným výstupem v miliampérech.
    • PowerFactor*
      • Účiník pro daný výstup
    • Load*
      • Příkon dodávaný výstupem ve wattech.
    • Energy*
      • Spotřeba daného výstupu ve watthodinách.

 

(* Proměnné s výsledky měření jsou obsaženy jen pro zařízení s měřením energie)

Pro kompletní popis si je možné vyžádat XML dokumentaci.
 

Vytvoření xml souboru pro ovládání

Soubor ve formátu xml, který je třeba odeslat do NETIO zařízení musí obsahovat jen nezbytné tagy.

 

Každá xml struktura soubor musí být uzavřena do:

Nebo zjednodušená verze:
  • Pro práci s výstupy je nutné dodržet předepsanou syntaxi při vytváření xml souborů.
  • Poté je nutné vytvořit třídu Output pro každý výstup, jehož stav se má měnit.
  • S každým výstupem lze provést jednu z těchto akcí:
    • 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)
  • U každého výstupu je nutné vyplnit proměnnou ID a Action.
  • Pro nastavení hodnoty výstupu je možné použít i proměnnou State (pouze hodnoty 0/1 - Off/On). V tom případě je ale nutné proměnnou Action nastavit na hodnotu 6 (tato proměnná je povinná, není tedy možné ji vynechat) a poté se stav výstupu nastaví podle hodnoty proměnné State.
  • Příklad pro zapnutí výstupu 1:

  
    
      1
      1

Příklad pro zapnutí výstupu 1 pomocí proměnné State:


  
    
      1
      6
      1

Příklad pro přepnutí stavu všech výstupů najednou:


  
    
      1
      4
    
    
      2
      4
    
    
      3
      4
    
    
      4
      4
  • Pro akce 2 a 3 je možné i přímo specifikovat dobu (Short time), po kterou bude daná akce trvat pomocí proměnné Delay. Do ní uložte hodnotu v milisekundách (minimální hodnota je 100ms).
  • Příklad pro provedení akce 2 (short Off)  u výstupu 1 na 3 sekundy:

  
    
      1
      2
      3000

3 ukázkové soubory XML

Ukázku xml souboru pro ovládání výstupu 1 lze stáhnout přímo z webu zařízení:
XML API - Download example XML API file.

  • Set output 1 to ON
  • Set output 1 to OFF
  • Toggle output 1

 

Návratové hodnoty

Jako stavovou odpověď HTTP serveru na xml get/post požadavek je možné obdržet:
 

  • 200 OK
    Vše proběhlo v pořádku
  • 400 Bad request
    Syntaktická chyba v požadavku
  • 401 Unauthorized
    Špatné uživatelské jméno nebo heslo
  • 403 Forbidden
    xml API není na zařízení NETIO povolena (viz sekce Nastavení NETIO 4x) nebo je nastavena jen pro čtení (při pokusu o zápis)
  • 500 Internal Server Error
    Chyba vnitřního serveru, nebo vnitřní server ještě nenaběhl (např. po restartu).

 

Po úspěšném vykonání (odpověď OK) je zaslán zpět xml soubor se stavem zařízení. Formát zde odpovídá netio.xml

Při chybě je zaslán zpět následující xml soubor, například:


  Bad request

Změna čísla portu

XML over HTTP(s) ovládání může používat port pro web konfiguraci (defaultně 80), nebo odlišný M2M HTTP port.

 

Typ použitého portu je možné změnit ve webové aplikaci pomocí záložky Use custom M2M HTTP(S) port. Po jejím zaškrtnutí je možné port změnit v části Custom M2M HTTP(S) port. Změnu portu je potřeba potvrdit tlačítkem Save Changes.

 

FAQ:

1) Lze v rámci jednoho příkazu ovládat více výstupů najednou?

Ano, pomocí XML API můžete ovládat i více výstupů.

Příklad přepnutí stavu výstupu 1 a 2:


  
    
      1
      4
    
    
      2
      4

2) Pokouším se odeslat netio.xml soubor přes nástroj „HTTP(s) file upload“ na webu zařízení, ale zásuvky nereagují. Kde může být chyba?

Zkontrolujte, zdali jste postupoval podle výše uvedeného postupu. Nejčastěji problém vzniká z následujících důvodů:

  • Není povolen M2M protokol (M2M API Protocols - XML API - Enable XML API),
  • Soubor .xml je zasílán na špatnou adresu (jediná správná adresa je http://<NETIO_IP>/netio.xml, kde <NETIO_IP> je adresa NETIO zařízení)
  • Soubor .xml obsahuje špatně naformátovaný obsah (správný formát xml je popsán výše)
  • Je vyplněno špatné heslo nebo přihlašovací jméno (heslo i přihlašovací jméno musí být stejné jako ve skupině READ-WRITE v XML API web nastavení zařízení)
  • NETIO zařízení není aktuálně připojeno (výpadek sítě).

 

3) Zásuvku zapnu pomocí XML, ale potom přijde na řadu časovač (Scheduler) pro ovládání stejné zásuvky. Proběhne časová sekvence správně?

Ano, po vykonání XML M2M API příkazu je zásuvka dál dostupná pro všechny cesty ovládání (Scheduler, WatchDog, Mobilní aplikace, tlačítko,...)

 

4) Je možné použít i jiný port než 80?

Ano, ve webové administraci je možné číslo portu změnit pomocí okénka Use custom M2M HTTP(s) port.

 

5) Jaký je rozdíl mezi proměnnou Action a State?

Proměnná State je využívána primárně pro čtení. Její hodnoty jsou 0 a 1 podle stavu, ve kterém se výstup nachází. Pomocí proměnné Action lze nastavit výstup do požadovaného stavu.

 

6) Jak často lze posílat netio.xml na NETIO zařízení?

Http server má svá vlastní omezení, kvůli kterým je počet omezen na zhruba 1-2 požadavků za sekundu. Tato hodnota se může změnit při použití https.

 

7) Lze pro odesílání xml použít i jiný software?

Pro odeslání xml souboru je možné použít jakýkoli software, který je schopen odesílat xml např. Advanced REST client nebo cURL.

 

8) Jaký je rozdíl mezi xml a json M2M protokoly?

Rozdíl je pouze ve formátu odesílaného textového souboru, princip odesílání je stejný.

 

9) Musí být jednotlivé řádky v xml souboru “odenterovány” (znak CR+LF)?

NETIO akceptuje většinu kombinací konce řádek. Soubor xml je možné poslat celý v jednom řádku.

 

10) Je nutné posílat XML soubor do souboru netio.xml?

Ano, cílovým souborem pro přenos XML souboru musí být soubor /netio.xml.
Přenos na jinou adresu souboru bude ignorován.

 


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