Tutoriál
Od verze 0.9.0
Na této stránce najdete krátký kurz s příkladem scénáře skriptování, který vám pomůže začít se skripty Shelly. Postupujte podle pokynů k vytvoření prvního skriptu o výstrahách nečinnosti. Výsledný skript bude monitorovat vstup(y) Shelly a pokud nedošlo k žádné interakci uživatele se vstupy, zavolá URL s předdefinovanou zprávou.
Více informací o skriptovacím jazyce naleznete zde. Chcete-li se dozvědět více o skriptovacím API společnosti Shelly, klikněte sem.
Krok 1: Vytvoření prázdného skriptu
Vytvořte skript s názvem nazev_scriptu. To můžete provést ve webovém rozhraní vašeho zařízení:
- Otevřete webové rozhraní a zvolte menu Skripts:
- Klikněte na Add script
- Zadejte nazev_scriptu a klepněte na tlačítko Save
Případně můžete použít metodu RPC:
curl -X POST -d '{"id":1, "method":"Script.Create",
"params":{"name":"my_idle_alert_script"}}' http://${SHELLY}/rpc
Výsledkem této metody bude nějaké id, řekněme id=3.
Krok 2: Povolení ladění přes WebSocket
Abychom mohli snadno přijímat výsledky ze skriptů, které vytváříme, a ladit je, povolíme nejprve protokoly ladění (například přes websocket).
Opět by to mohlo být snadno provedeno prostřednictvím webového rozhraní:
Poté se vrátíme na stránku skriptu, který jsme právě vytvořili, a obdržíme tam protokoly.
V opačném případě, jak je popsáno zde a zde, můžeme k tomu použít metodu RPC:
Povolení protokolů ladění přes WebSocket
export SHELLY=10.33.55.152 # IP of your device
curl -X POST -d '{"id":1, "method":"Sys.SetConfig",
"params":{"config":{"debug":{"websocket":{"enable":true}}}}}' http://${SHELLY}/rpc
V tomto případě začneme přijímat protokoly provedením následujícího příkazu:
wscat --connect ws://${SHELLY}/debug/log
Krok 3: Jednoduchý skript
Chcete-li začít vytvářet skripty, vytvořte nějaký kód, který vytiskne "Hello world!":
let greeting = "Hello world!";
print(greeting);
Chcete-li nahrát tento kód do skriptu, který jsme právě vytvořili, vložte kód na stránku skriptu ve webovém rozhraní a klikněte na tlačítko Save.
Alternativně můžeme vytvořit kód v souboru, řekněme hello_world.txt a nahrát jej v jednom kroku pomocí put_script skriptu. Tento skript má tři parametry:
- IP adresa zařízení, na které budeme skript nahrávat (již nastavena jako hodnota env proměnné SHELLY)
- id objektu skriptu, kam nahrajeme kód (v našem případě id=3)
- název souboru obsahujícího samotný kód
put_script.py ${SHELLY} 3 "hello_world.txt"
Opět můžete také nahrát tento kód (blok po bloku) do skriptu prostřednictvím požadavku RPC:
curl -X POST -d '{"id":1, "method":"Script.PutCode",
"params":{"id":3,"code":"let greeting = \"Hello world!\";", "append": false}}'\
http://${SHELLY}/rpc
curl -X POST -d '{"id":1, "method":"Script.PutCode",
"params":{"id":3,"code":"print(greeting);", "append": true}}' http://${SHELLY}/rpc
Všimněte si, že v tomto případě, když je kód dlouhý, musí být nahrán blok po bloku. V příkladu se nahrává řádek po řádku, ale můžete ho rozdělit odlišně napříč voláními Script.PutCode.
Další věc, kterou je třeba poznamenat, je, že protože naše první vyvolání Script.PutCode obsahovalo parametr "append":false, veškerý kód nahraný dříve v tomto objektu Script bude automaticky odstraněn a obsah skriptu bude nahrazen novým kódem.
Krok 4: Spuštění skriptu
Nakonec máme kód nahraný a můžeme spustit náš první Shelly skript (ten s id = 3).
K tomu stačí kliknout na tlačítko Start z webového rozhraní:
... nebo můžeme poslat požadavek RPC:
curl -X POST -d '{"id":1, "method":"Script.Start", "params":{"id":3}}'\
http://${SHELLY}/rpc
To by mělo následně vytisknout 'Hello world!' v konzoli. Takto to vypadá ve webovém rozhraní:
Krok 5: Zastavte skript
Zastavení scénáře. To můžeme udělat pomocí:
nebo:
curl -X POST -d '{"id":1, "method":"Script.Stop", "params":{"id":3}}'\
http://${SHELLY}/rpc
Všimněte si, že tento skript nemůžeme znovu spustit, aniž bychom jej nejprve zastavili! To je potřeba zejména při aktualizaci skriptu - pokud je již spuštěn, bude pokračovat v provádění staré verze kódu, dokud nebude zastaven a poté znovu spuštěn. Budeme to potřebovat v dalších krocích tutoriálu, kde budeme krok za krokem upgradovat náš kód.
Krok 6: Vytvoření objektu ve skriptu
Nyní začneme vytvářet sofistikovanější a užitečnější skripty.
Nejprve vytvoříme některé proměnné: objekt CONFIG a alertTimer s hodnotou null:
let CONFIG = {
timeoutBeforeAlert: 12 * 60 * 60 * 1000,
inputID: "", // string
inputEvent: -1, // int
alertEndpoint: "http://myalert.bot/?message=${message}"
};
let alertTimer = null;
Vytvořte nový objekt skriptu, jak je popsáno v kroku 1, nebo jednoduše změňte kód předchozího objektu skriptu, jak je popsáno v kroku 3. Výsledný skript (řekněme opět s id=3) lze spustit jako doposud, ale na terminál nic nevytiskne.
Krok 7: Vytvoření funkce, která nahradí řetězce
Pojďme vytvořit funkci nazvanou "nahradit". Bude mít tři řetězce: origin, substr a replace, kde substr je podřetězec origin. Funkce nahradí substr s replace v origin.
function replace(origin, substr, replace) {
return origin.slice(0, origin.indexOf(substr)) + replace + origin.slice(origin.indexOf(substr) + substr.length, origin.length)
}
Přidejte funkci do kódu z předchozího kroku a nahrajte ji. Výsledný skript (řekněme opět s id=3) lze spustit jako dříve, ale neměli bychom zapomenout jej nejprve zastavit, pokud byl spuštěn při aktualizaci kódu. Opět platí, že na terminál nebude nic vytištěno. Nicméně, když je skript spuštěn, funkce, kterou jsme právě přidali, může být snadno vyhodnocena metodou RPC:
curl -X POST -d '{"id":1, "method":"Script.Eval", "params":{"id":3, "code":"replace(\"The first generation of Shelly devices rule the world!\", \"first\", \"second\")"}}'\
http://${SHELLY}/rpc
Výsledkem musí být řetězec "The second generation of Shelly devices rule the world!".
Krok 8: Vytvoření funkcí, které spustí a zastaví časovač
Nastavíme časovač, který se spouští opakovaně každých 12 hodin a odesílá požadavek http get. Pokud je kód odpovědi z tohoto požadavku 200, vytiskne se zpráva s oznámením o úspěchu. Zde použité hodnoty jsou ty, které jsme vytvořili v kroku 5.
function startTimer() {
alertTimer = Timer.set(CONFIG.timeoutBeforeAlert,
true,
function (ud) {
let alertURL = replace(CONFIG.alertEndpoint, "${message}", "Grandpa:_No_activity_for_12_hours!");
Shelly.call("HTTP.GET",
{ url: alertURL },
function (res, error_code, error_msg, ud) {
if (res.code === 200) {
print("Successfully transmitted a message");
};
},
null);
},
null
);
}
function stopTimer() {
Timer.clear(alertTimer);
}
Opět připojte tento kód k již přidanému.
Krok 9: Přidání obslužné rutiny události
Pojďme přidat obslužnou rutinu události, která restartuje časovač, když dojde k jakékoli události. Na každý časovač resetování budete upozorněni zprávou "TIMER WAS RESET" vytištěnou v protokolech.
Shelly.addEventHandler(
function (event, ud) {
// while we don't have better selectivity for event source
if (typeof (event.info.state) !== 'undefined') {
stopTimer();
startTimer();
print("TIMER WAS RESET");
}
},
null
);
Připojte tento kód k již vytvořenému. Nakonec máme celý skript a můžete ho nahrát.
Nyní zastavte skript (pokud byl spuštěn při aktualizaci kódu) a znovu jej spusťte, jak je popsáno v kroku 4.
Pokud jste postupovali správně, budete upozorněni pokaždé, když v posledních 12 hodinách nedošlo k žádné události (může to znamenat problém doma nebo jen skutečnost, že někdo je na dovolené :-) ).
