AN04 Ovládání zásuvky pomocí URL (http GET přes Lua skript) | Chytré zásuvky NETIO ovládané pomocí WiFi a LAN
Tagy: 
Lua tutorials

Elektrické zásuvky NETIO 4 jsou připojeny do LAN nebo WiFi sítě. Jednotlivé zásuvky lze zapínat a vypínat jednoduše zavoláním url adresy z prohlížeče nebo příkazové řádky. Použití tohoto volání je velmi snadné. NETIO AN04 popisuje vytvoření Lua scriptu, který reaguje na parametry obsažené v http get adrese (url). Uživatelský Lua skript může oproti standardnímu M2M API rozhraní na bázi URL neboli http GET měnit chování zásuvek na různě pojmenované parametry. 

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

Podporovaná zařízení: NETIO 4All, NETIO 4C, NETIO 4

 

NETIO zásuvky podporují ovládání pomocí “URL API” rozhraní (voláním url s parametry) dvěma různými způsoby:

  1. Pomocí uživatelského Lua skriptu (to popisuje toto AN04)
  2. Použitím standardního M2M API typu “http GET” což popisuje NETIO AN19.

 

Rozdíl mezi ovládáním popsaným v AN04 a AN19 je v tom, že standardní M2M API rozhraní (AN19) nemůže uživatel nijak změnit a může se mu jen přizpůsobit. Při použití zákaznického Lua scriptu, který běží v NETIO zásuvkách (zde popsaná AN04) lze v Lua skriptu modifikovat chování zásuvek i ovládací parametry.

Lua skript je ale třeba přes web do zásuvek vložit, nastavit a spustit, zatímco standardní M2M API rozhraní běží ihned po kliknutí na web rozhraní.

---

Skript se spustí pokaždé po zaslání požadavku http get. V praxi to znamená vždy po zavolání IP adresy NETIO s “event” za posledním lomítkem (<NETIO_IP>/event). Argumenty, které Lua skript zpracovává se vkládají za otazník a oddělují se symbolem “&”.

Pro ovládání je použitý HTTP (HTTPs) Request / URL a navázané uživatelské akce v jazyce Lua.

Pro zajištění alespoň elementární bezpečnosti je třeba k příkazu přidat heslo, které je zde nastaveno na defaultní mickemouse..

Ukázkou rozšířených možností uživatelského skriptu v Lua je akce blink, která podle hodnoty proměnné counter zabliká s nastavným výstupem.

Pro rychlé ovládání NETIO zásuvek od uživatele lze vytvořit například spustitelný script na plochu, záložky nebo tlačítka ve webovém prohlížeči, které přímo provádějí naprogramovanou akci na NETIO4 odesláním příslušného HTTP Request.

 

Vytvoření pravidla (rule)

Pro vytvoření a spuštění Lua skriptu je nutné následující:

1) Ve webové administraci NETIO 4 v sekci Actions, přidejte pravidlo pomocí tlačítka Create Rule


2)Vyplňte následující parametry:

  • Enable rule: zaškrtnuto
  • Name: HTTP control (uživatelsky definovatelné)
  • Description: Allow control of outputs via web browser (uživatelsky definovatelné)
  • Trigger: Incoming URL API request
  • Schedule: Always

 

3) Do pole pro skript v jazyce Lua vložte následující kód:

 

------------Section 1------------
local myPassword = "mickeymouse" 
---------End of Section 1---------

local password = event.args.password
local action = event.args.action
local output = tonumber(event.args.output)
local actionDelay = tonumber(event.args.delay)
local counter = tonumber(event.args.counter)

local state = false -- inner variable

function blink()
  state = not state
  if counter > 0 then 
    devices.system.SetOut{output=output,value=state}
    counter = counter - 1
    delay(actionDelay,function() blink() end)
  end  
end

if password ~= myPassword then
  logf("Invalid password for %s output %d", action, output)
  return
end

-- log what is going to happen
logf("Going to %s output %d", action, output)

if action == "on" then -- turn on output
  devices.system.SetOut{output=output, value=true}
elseif action == "off" then -- turn off output
  devices.system.SetOut{output=output, value=false}
elseif action == "reset" then -- cycle power
  if actionDelay == nil then
    devices.system.ResetOut{output=output}
  else
    logf("%d", actionDelay)
    devices.system.ResetOut{output=output,resetDelay=actionDelay*1000}
  end
elseif action == "toggle" then -- switch output state
  if devices.system["output" ..output.. "_state"] == 'on' then  
    devices.system.SetOut{output=output,value=false}
  else
    devices.system.SetOut{output=output, value=true}
  end
elseif action == "blink" then -- turn off output
  if devices.system["output" ..output.. "_state"] == 'on' then
	state = true
  else
	state = false
  end
  if actionDelay == nil then
    actionDelay = 1
  end
  blink() 
else -- by default do nothing
  logf("Invalid action: %s", action)
end

4) Tvorbu pravidla ukončete stisknutím kliknutím na tlačítko Create Rule v dolní části obrazovky.

 

Sestavení ovládacího příkazu

 

Důležitá poznámka: Nezapomeňte změnit heslo (v Lua scriptu i odkazech) z hodnoty “mickeymouse” na vaše tajné heslo, abyste zamezili ovládání zásuvky nepovolaným osobám!

Vytvoření Lua skriptu

  • Skript se spustí vždy když NETIO obdrží URL request.
  • Nejprve skript rozparsuje příchozí řetězec, uloží příslušné hodnoty do proměnných a provede určitou operaci s vybraným výstupem.

Proměnné

  • Proměnné používané ve skriptu jsou myPassword, password, action, output, actionDelay, counter.
  • Protože se nejedná o globální proměnné, jsou všechny deklarovány pomocí klíčového slova local.
  • Hodnota proměnné myPassword je nastavitelná uživatelem, ostatní se získávají z příchozího řetězce. Jejich hodnota se získává pomocí příkazu “event.args.”, kde po tečce následuje název argumentu tak jak je označen v URL (např. local password = event.args.password)
  • Proměnná actionDelay se nastavuje podle parametru delay. Proměnná se nemůže jmenovat delay, protože tento název je vyhrazen jedné ze systémových funkcí.
  • Proměnné, se kterými se pracuje jako s čísly (output, actionDelay, counter) jsou již při deklaraci přetypovány na číslo pomocí příkazu tonumber()
  • Význam proměnných je následující:
    • myPassword
      • Nastavuje heslo, které slouží k zabezpečení
      • Jediná, uživatelsky definovatelná proměnná v Lua skriptu (ostatní hodnoty se nastavují pomocí příchozího řetězce)
      • Jedná se o string (řetězec znaků), je nutné ho vložit do uvozovek
      • Příklad pro heslo netioURL987: local myPassword = "netioURL987"
      • Rozlišují se malá a velká písmena
    • password
      • Slouží k ověření odesílatele URL requestu
    • action
      • Slouží k výběru akce (viz níže)
    • output
      • Nastavuje číslo výstupu, se kterým se vykoná příslušná akce
    • actionDelay
      • Pokud je akcí reset, nastavuje dobu, za kterou se výstup zapne. Pokud není zadaný, jako výstup se zapne za dobu nastavenou u příslušné zásuvky (základní hodnota 5 sekund).
      • Pokud je akcí blink, nastavuje dobu mezi přepnutím stavu. Pokud není zadaný, jeho hodnota se nastaví na 1 sekundu.
    • counter
      • Nastavuje počet přepnutí stavu výstupu při akci blink
  • Skript dále obsahuje proměnnou state, která slouží k uchování hodnoty stavu výstupu pro akci blink.

Kontrola hesla

 

if password ~= myPassword then
  logf("Invalid password for %s output %d", action, output)
  return
end

  • První věc kterou skript vykoná je porovnání proměnné password s nastaveným heslem v proměnné myPassword pomocí podmínky if password ~= myPassword then (symbol ~= znamená “nerovná se”). Pokud je tato podmínka splněna, zadané heslo se tedy neshoduje, skript zapíše do logu pokus o změnu stavu funkcí logf() a následně se ukončí zavoláním return.
  • Při nesplnění podmínky skript běží dál.

Výběr akce

  • Pokud je heslo správné, skript do logu zapíše akci, kterou vykoná a poté podle hodnoty proměnné action rozhodne o dalším postupu. K tomu využívá rozvětvené podmínky, ve které zjistí, o jakou akci se jedná (on, off, reset, toggle, blink). Pokud se nejedná o žádnou z nastavených akcí, skript vypíše do logu “Invalid action:” a hodnotu proměnné action.
  • action == 'on'
    • Akce pro zapnutí výstupu
    • Výstup se zapne pomocí příkazu devices.system.SetOut{output=output, value=true}
  • action == 'off'
    • Akce pro vypnutí výstupu
    • K vypnutí slouží příkaz devices.system.SetOut{output=output, value=false}
  • action == 'reset'
    • Akce pro restartování výstupu
    • Skript zkontroluje jestli byl zadán parametr delay pomocí podmínky if actionDelay == nil then.
    • Pokud ne (podmínka je splněna), zavolá se příkaz pro restartování zásuvky devices.system.ResetOut{output=output}. Výstup se zapne za dobu Switch delay, která je pro každý výstup nastavitelná ve webové administraci.
    • Pokud je parametr zadán, jako doba pro opětovné zapnutí se použije hodnota tohoto parametru vynásobená 1000 (parametr se udává v milisekundách). Příkaz pro tuto variantu vypadá takto: devices.system.ResetOut{output=output, resetDelay=actionDelay*1000}.
  • action == 'toggle'
    • Akce pro přepnutí stavu výstupu
    • Nejprve se pomocí podmínky if devices.system["output" ..output.. "_state"] == 'on' then zjistí, jestli je výstup zapnutý.
    • Pokud je zapnutý, skript ho vypne pomocí příkazu devices.system.SetOut{output=output, value=false}.
    • Pokud je vypnutý, skript ho zapne pomocí příkazu devices.system.SetOut{output=output, value=true}
  • action == 'blink'
    •  Akce pro opakované přepnutí stavu výstupu.
    • Skript nejprve do proměnné state uloží současný stav zvoleného výstupu pomocí podmínky

 

if devices.system["output" ..output.. "_state"] == 'on' then
  state = true
else
  state = false
end

  • Poté zkontroluje, jestli byl zadán parametr delay podmínkou if actionDelay == nil then. Pokud nebyl (podmínka je splněná), jeho hodnotu nastaví na 1 sekundu.
  • Nakonec zavolá funkci blink, která se postará o přepnutí stavů.

Funkce blink

 

function blink()
  state = not state
  if counter > 0 then 
    devices.system.SetOut{output=output,value=state}
    counter = counter - 1
    delay(actionDelay,function() blink() end)
  end  
end

  • Funkce nejprve změní stav proměnné state (na opačný stav ve kterém je výstup) pomocí negace state = not state.
  • V dalším kroku ověří, jestli má přepnout stav výstupu if counter > 0 then. Pokud ano (proměnná counter je větší než 0), pomocí příkazu devices.system.SetOut{output=output,value=state} změní stav výstupu na opačný a sníží hodnotu proměnné counter o 1 (counter = counter - 1).
  • Nakonec pomocí funkce delay se znovu zavolá se zpožděním nastaveným v proměnné actionDelay: delay(actionDelay,function() blink() end).
  • Pokud není zadaný parametr counter, k přepínání stavu výstupu nedojde.

Ovládání z webového prohlížeče

Pomocí návodu výše vytvořte ovládací příkaz, který vložte do webového prohlížeče. Pokud NETIO přijalo URL request, zobrazí se vám ve vašem prohlížeči stránka s textem OK

 

V dlouhodobém výhledu je umožnit změnu výchozí odpověď “OK” na uživatelsky definovaný řetězec. To zatím ve fw 3.0.1 není možné.

 

Ve většině prohlížečů je možné vytvořit si záložky s nastavenými URL pro rychlejší ovládání. Například na obrázku jsou nastavené záložky pro zapínání, vypínání popřípadě přepnutí stavu výstupu jedním kliknutím ve vašem webovém prohlížeči.

 

Ovládání z příkazové řádky

Pro ovládání z příkazové řádky lze použít příkaz cURL (ke stažení z http://curl.haxx.se/download.html) nebo libovolný jiný příkaz, který umí otevřít URL adresu (např. webový prohlížeč).

 

Windows

Stáhněte program cURL, spusťte příkazový řádek (CMD) a v curl otevřete složku bin. Před ovládací příkaz je nutné napsat curl a příkaz samotný vložit do uvozovek.

Příklad zapnutí zásuvky 1: curl "http://192.168.101.118//event?password=mickeymouse&action=on&output=1"

 

Mac OS X a Linux

Program cURL je standardní součástí vašeho operačního systému. Postup pro ovládání výstupů je shodný s Windows, viz výše.

 

Zabezpečení pomocí HTTPs

Je možné zapnout zabezpečení připojení protokolem https.

Pro zapnutí https zapněte možnost Turn on secure connection (HTTPS) v nabídce Settings/Secure Connection. Pro uložení v nastavení klikněte na Save Changes.

Aktivace protokolu https může trvat delší dobu.

Je možné změnit HTTPS port ze základního 443 na jiný, vámi zvolený. V tom případě je ale nutné za IP adresu přidat dvojtečku a číslo portu (například pro port 400: https://192.168.101.118:400/)

 

FAQ:

1) Bude fungovat URL ovládání i přes WiFi?

Ano, je jedno jestli jste do sítě připojeni přes LAN nebo WiFi.
 

2) Lze nějak přes volání http Get zjistit stav výstupů?

Ne, doporučujeme použít Telnet nebo XML protokoly z M2M API.
 

3) Mohu nastavovat formát volané URL?

Ano, cokoliv za http://192.168.101.118/event? můžete konfigurovat v Lua scriptu. Parametry lze nazvat libovolně a přidat další podmínky pro vykonání. 
 

4) Zásuvku zapnu pomocí URL, 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í URL příkazu je zásuvka dál dostupná pro všechny cesty ovládání (Scheduler, WatchDog, Mobilní aplikace, tlačítko,...)
 

5) Lze do Lua skriptu vložit ochranu na volání pouze z určité IP adresy? Něco jako IP filtr?

Ne. Z Lua není možné zjistit, z jaké IP adresy byl http get požadavek odeslán.
 

6) Používá se v URL ovládání http post nebo http get?

Jedná se o metodu http get.
 

7) Lze jedním příkazem ovládat víc zásuvek?

Ne, narozdíl od AN19 je potřeba vyslat více příkazů.
 

8) Jaký je rozdíl mezi AN04 a AN19?

AN19 využívá standardní M2M API. AN04 využívá Lua skriptu, díky němuž je možné si parametry přizpůsobit.

 

Zeptejte se na cenu nebo technické parametry

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