SDS-C: sharing

Tato stránka popisuje programovací jazyk SDS-C, který je dostupný na vybraných zařízeních SDS. 
Některá zařízení používají FULL-C, pro který máme návody jinde na této WiKi.

Proměnné nastavitelné uživatelem z webového rozhraní

Často je potřeba, aby uživatel (správce zařízení) měl možnost zasáhnout do běhu programu (SDS-C), a přitom jeho činnost nezastavit. Příkladem může být jednoduchý program, fungující jako termostat, kde uživatel chce ručně nastavovat cílovou teplotu. Ideálně se k tomu hodí právě následující popsaná vlastnost.

Využívají se k tomu tzv. "sdílené proměnné" - k těm má současně přístup jak SDS-C program, tak také uživatel.

Základní vlastností je možnost změny hodnot sdílených proměnných prostřednictvím webové stránky, poskytované zařízením. Stejně tak vaše nahraná webová stránka do zařízení můze prostřednictvím těchto funkcí ovládat SDS-C program.

Rozšířenou vlastností je možnosti změny hodnot sdílených proměnných mezi jednotlivými zařízeními navzájem, viz text dále.

Co je v SDS-C k dispozici

Základní sdílené proměnné, které jsou uživatelem nastavitelné, jsou v této verzi SDS-C přístupné přes pole sys[]. Dále je k dispozici samostatné pole share[].

Je zde možnost zabezpečení přístupu, kdy se po konfiguraci (zápisu nenulové hodnoty do vyhrazené proměnné) dá omezit přístup ke změně sdílených proměnných (jen po přihlášení do webové administrace heslem).

K dispozici je:

• deset samostatných základních sdílených proměnných formátu "signed integer 32 bit" - tedy typ int32_t (přístup je přes specifické indexy v poli sys[]).
• pole znaků (tj. pole share[])

Adresa výchozí nastavovací webové stránky (generované zařízením) je (IP je zde pro příklad):

http://192.168.1.250/control 

To znamená, že za IP adresu zařízení stačí dopsat control a zobrazí se zabudovaná editační webová stránka. Samozřejmě pokud si nahrajete do zařízení svou vlastní webovou stránku, můžete z této své stránky měnit obsah sdílených proměnných také (ale pak bude přístupová adresa, k této vlastní stránce, samozřejmě jiná).

Editace sdílených proměnných pomocí jiného zařízení nebo programu

Změnu proměnných nemusí provádět ručně uživatel, lze také využít i jiného zařízení s programem SDS-C, nebo to může být nějaký váš server nebo cokoliv jiného.

Podstatné je, že po zaslání HTTP GET požadavku, se správně vyplněným URL, dojde k úpravě hodnoty konkrétní sdílené proměnné.

Dá se tak dosáhnout spolupráce více zařízení řady SDS/OnlineTechnology mezi sebou (komunikace jednotlivých SDS-C programů), nebo např. pokud máte centrální řídící program (nebo centrální řídící web), můžete tak jednoduše hromadně ovládat vzdálené zařízení (jejich SDS-C programy).

Můžete ovlivnit, jaké data budou prostřednictvím odpovědi webového serveru navráceny.

• zadáte-li jako parametr p=0 ("znak p rovná se nula") - bude vrácena pouze a jenom nově nastavená hodnota sys[]
• zadáte-li jako parametr p=6 ("znak p rovná se šest") - bude vrácena celá kompletní webová stránka pro sds-c (ale pouze pokud jste přihlášeni přes vstupní stránku)
• nezadáte-li vůbec zmíněný parameter (tj. p=cokoliv) - (do 4/2015: nebude vrácen byť jediný znak) (od 4/2015: bude vrácena pouze a jenom nově nastavená hodnota)

Každá aplikace vzdáleného nastavování sys[] potřebuje jinou reakci na zaslaný HTTP GET požadavek, a právě proto máte předchozí vyjmenované možnosti. Pozn. Pokud vám něco z nich nefunguje, pak máte v zařízení nahrán starý firmware - aktualizujte na nejnovější.

Příklad URL:

http://192.168.1.250/sdscep?p=6&sys140=123456

nastaví sys[140] na hodnotu 123456 a současně vrátí celou HTML stránku z webového rozhraní (paramter p=6).

Často je potřeba jen změnit nastavení a nechceme jakoukoliv odpověď. Potom je vhodné využít následující typ URL:

http://192.168.1.250/sdscep?sys140=123456

Opět pro stejný příklad, (do 4/2015: bez vrácení jakéhokoliv HTML obsahu) (po 4/2015: vrátí text: 8190). Všimněte si, že tam není paramter p=X. Toto přednostně používejte pro komunikaci mezi dvěma SDS.

Nakonec příklad:

http://192.168.1.250/sdscep?p=0&sys143=8910

nastaví sys[143] na hodnotu 8910 a současně vrátí novou hodnotu v sys[143] tedy text: 8910

V současné verzi firmware lze najednou nastavit jen jednu položku v sys[]. Více sys[] najednou změnit nelze (toto bude až v některém z nových firmware).

Pozor, použitelný rozsah sys[] je 140 až 149 (viz seznam, část "Proměnné nastavitelné uživatelem z webového rozhraní") - ostatní sys[] se nedají přes sdscep nastavovat.

Pozor, toto funguje (se současnou verzí firmware) jen pokud není přístup ke sdíleným proměnným zablokován (lze zablokovat zápisem nenulové hodnoty do sys[150] - potom musí být daná IP adresa, ze které je poslán sdscep požadavek, nejprve "přihlášena" do webového rozhraní zařízení SDS).

Předávání více informací v jedné proměnné

Protože firmware umožňuje předávat (zapisovat) v jednom URL jen jedno sys[], je potřeba znát postup, jak tímto způsobem předat více informací. Jedním z možných řešení je použití bitové manipulace.

Příklad URL:

http://192.168.1.250/sdscep?sys140=20

Tímto nastavíme sys[140] na hodnotu 20. Program v SDS-C následně podle jednotlivých bitů něco udělá (příklad):

if (sys[140] & 1) prvni_bit_je_nastaven();
if (sys[140] & 2) druhy_bit_je_nastaven();
if (sys[140] & 4) treti_bit_je_nastaven();
if (sys[140] & 8) ctvrty_bit_je_nastaven();
if (sys[140] & 16) paty_bit_je_nastaven();

Pro náš příklad, kdy do sys[140] nastavíme číslo 20, které je binárně 0b10100, se zavolají funkce paty_bit_je_nastaven a treti_bit_je_nastaven. Funkce je tedy zřejmá - stačí vhodně vytvořit vstupní údaj.

Komunikace mezi různými zařízeními SDS

Protože v SDS-C je funkce http_get(), můžete z jednoho zařízení změnit hodnoty v zařízení jiném, stačí pouze správně vyplnit potřebné parametry, a znát IP adresu zařízení.

Nezapomeňte vždy správně vyplnit všechny potřebné údaje (ip, host, ...) pro HTTP GET - toto se týká zejména použití SDS-C funkce, kdy chcete pomocí HTTP GET ovládat jiné zařízení.

Pozn.: funkci http_get() pro komunikaci s jiným zařízením SDS je možné použít jen pro komunikaci se zařízení SDS, které má verzi SDS-C č. 04 nebo novější.

Příklad pro nastavení sys[141] na hodnotu 1234:

http_get(192,168,1,250,'192.168.1.250','/sdscep?sys141=1234');

Všimněte si, že musíte vyplnit IP adresu vzdáleného (!) zařízení, tj. první čtyři čísla. IP adresu buď znáte, nebo pokud má vzdálené zařízení DNS záznam, můžete IP adresu získat pomocí funkce dns_resolv. Následuje jeden textový údaj, což je host name.

Informace: pro zařízení SDS může být položka host i prázdný údaj (tj. přesněji znak ' '), ovšem kvůli případným firewalům (které se mohou vyskytnout po cestě posílaného HTTP GET požadavku) je vhodné to vyplnit správně, tj. pokud má vzdálené zařízení DNS záznam, pak celým názvem domény ukazujícím na zařízení, nebo textově zapsat IP adresu vzdáleného zařízení.

Nakonec pak patří textový zápis požadavku, zde v uvedeném příkladu je to zavolání sdscep s parametrem sys141=1234, vy si tam dáte to co potřebujete.

Konec příkladu.

Samozřejmě http_get() můžete využít i pro jiný způsob získávání údajů z jiného zařízení SDS, viz informace dole na této stránce.

Zápis do pole share[]

Pole share[] je z hlediska použití v programu SDS-C prakticky shodné jako pole text[].

Důležitý rozdil je v tom, že pole text[] nelze "z venku" měnit - do pole text[] lze zapisovat jen z programu SDS-C samotného. Naopak pole share[] je určeno k tomu, aby do něj šlo zapisovat i přes webové rozhraní SDS (stejně tak jako lze zapisovat do ostatních sdílených proměnných).

Pole share[] je, stejně jako pole text[], souborem znaků (8bit char), kdy na každém indexu (položce) pole je jedna 8bitová hodnota. Prakticky se to tedy používá tak, že od zvoleného místa (indexu) v poli je zapsán text (složený ze znaků), a tento text je zakončen hodnotou 0x00.

Přístup (zápis) k poli share[] je proveden takto (wshare = write to share):

http://192.168.1.250/wshare?i=20&t=text

i = index do share[]
t = text zapsaný do share[p]

Tento příklad zapíše "text" (včetně zakončovací 0x00) do pole share[] na pozici 20. Takže:

share[20] = 't';
share[21] = 'e';
share[22] = 'x';
share[23] = 't';
share[24] = 0x00;

Pro použití wshare platí stejné podmínky, jako pro sdscep (tedy především řízení přístupu), včetně doplňkového parametru "p" (není v příkladu zmíněn).

Text zapsaný jako parametr t, je samozřejmě do SDS předán jako "URL-encoded string" - a je uvnitř SDS dékodován na plaintext.

Čtení stavu uživatelských proměnných

Pro kontrolu lze všechny hodnoty získat pomocí XML.

http://192.168.1.250/usys.xml

Toto funguje od verze firmware 27.2.2011.

Čtení pole sys[], ram[], text[], share[] nebo DF

Pole sys[], pole ram[], pole text[] a pole share[] máte plně k dispozici v SDS-C programu.

Pokud k obsah těchto datových polí chcete přistupovat externě - tzn. číst obsah buď z jiného zařízení, nebo obecně odkudkoliv - můžete využít následující funkci:

http://192.168.1.250/get_ram[index]

http://192.168.1.250/get_sys[index]

http://192.168.1.250/get_txt[index]

http://192.168.1.250/get_dfi[index]

http://192.168.1.250/get_var[index]

http://192.168.1.250/get_srd[index]

kde index je číslo prvku v poli.

Pro pole sys[] je povolený rozsah hodnot indexu od 1 do 1023.

Pro pole ram[] je povolený rozsah hodnot indexu od 0 do (záleží na verzi firmware). Protože některé nové verze firmware rozšiřují velikost pole ram[], není zde horní index napsán (pozn. verze SDS-C č. 03 měla maximální index pro pole ram[] hodnotu 128, nové verze (č. 06) mají maximum na 512 položkách).

Pro pole text[] je povolený rozsah hodnot indexu od 0 do (záleží na firmware) (512 položek).

Pro pole share[] je povolený rozsah hodnot indexu od 0 do (záleží na firmware) (256 položek).

Poslední položkou je dfi - to umožňuje získat obsah z DataFlash paměti, konkrétně z uživatelského prostoru v této paměti. Jako index zadejte první položku pro výpis (toto bude přímo odpovídat volání SDS-C funkce read_dataflash() - přičemž lze vypsat i více položek za sebou, viz návod v textu dole).

Položka var umožňuje získat hodnoty vnitřních proměnných uživatelského SDS-C programu. Jednotlivé indexy začínají od nuly a jsou přesně namapovány na seznam proměnných, tak jak je k dispozici v EXE při překladu (debugger okno).

Volitelný způsob předání informace

Můžete si zvolit dvě varianty způsobu přenosu číselné hodnoty.

V obou zmíněných polích jsou číselné hodnoty uloženy jako signed long (32 bit, to znamená 1 bit pro znaménko a 31 bitů pro hodnotu).

Můžete zvolit:

• vypsání obsahu položky v poli jako textový údaj, jedná se o text složený ze znaků: '-', '0' až '9'
• vypsání obsahu položky v poli jako čtyři bajty (= 32bitů), ve kterých je surový výpis obsahu

Volbu provedete nastavení paramteru ?p=1 (= bajtový výpis) nebo jeho vynecháním (= textový výpis).

Příklady:

http://192.168.1.250/get_ram[123]             vypíše obsah ram[123] jako text

http://192.168.1.250/get_sys[87]              vypíše obsah sys[87] jako text

http://192.168.1.250/get_sys[5]?p=1           vypíše obsah sys[5] do čtyř bajtů (signed long)

http://192.168.1.250/get_txt[10]              vypíše obsah text[10]..text[konec-řetězce] jako text

http://192.168.1.250/get_srd[20]              vypíše obsah share[20]..share[konec-řetězce] jako text

http://192.168.1.250/get_var[1]               vypíše obsah druhé SDS-C proměnné (indexuje se od nuly) jako text

atd.

Podobně to funguje i pro textové proměnné (z pole sys[], text[] nebo share[]).

Další volbou je možnost výpisu více proměnných, následujících za sebou. To znamená, že určíte počáteční index, a počet za ním následujících indexů. Např. index je 100 a počet je 3, pak budou vypsány proměnné o indexu: 100, 101 a 102. Odděleny jsou znakem | . Počet se udává pomocí parametru "rn", počáteční index se zapíše do závorek. Pokud vás zajímá jen výpis jediného indexu, počet nemusíte uvádět.

Příklad: Výpis více následujících proměnných:

http://192.168.1.250/get_sys[140]?rn=4           vypíše obsah sys[140], [141], [142], [143], oddělené znakem |

Příklad: Kombinace parametru "p" a "rn":

http://192.168.1.250/get_sys[5]?p=1&rn=3           vypíše obsah sys[5], sys[6], sys[7], vše vždy po čtyřech bajtech (signed long)

Jak bylo napsáno, toto funguje pro sys[] a pro ram[] pole. Parametr rn nefunguje pro pole text[] popř. share[].

Praktický příklad

Nastavme si do ram[] určité hodnoty (ať je vůči čemu porovnávat):

main
{
  ram[0] = 1;
  ram[1] = 2;
  ram[2] = 3;  
  ram[3] = 4;
  ram[4] = 0;
}

Když se pak zavolá 192.168.1.250/get_ram[0]?rn=5 , vrácený text je

1|2|3|4|0

Což je v textové formě: obsah ram[0] (textově), pak oddělovací znak '|', pak obsah ram[1] (textově), pak oddělovací znak '|', atd. Pozor, protože se jedná o textovou reprezentaci (řetězec znaků), tak nelze očekávat přesné délky (budou tam různé počty znaků). Toto je výhodné pro zpracování pomocí PHP nebo JavaScriptu. Nebo i v SDS, kdy lze použít funkci atoi().

Pro zpracování ve vlastní aplikaci (např. Win32 Socket aplikace, a podobně, kde máte přístup k celému paketu), je naopak výhodné použít ?p=1, který způsobí, že výstup get_xxx se nezapíše textově, ale vždy jako čtyřbajtové číslo (signed long). Příklad dotazu: 192.168.1.250/get_ram[0]?p=1&rn=5 . Výstupem je (vypsáno jako jednotlivé hexadecimální hodnoty pro jednotlivé bajty):

01 00 00 00 02 00 00 00 03 00 00 00 04 00 00 00 00 00 00 00

Takže příjemce (ten kdo poslal ten výše uvedený dotaz), dostane jako odpověď sérii bajtů, viz výpis o řádek výše.

Každé čtyři za sebou jdoucí bajty jsou jednou položkou (ram[0], ram[1], ...).

Totéž platí i pro sys[].

Závěr

Toto si můžete vyzkoušet zadáním příslušných příkladů jako adres v Internetovém prohlížeči a podívat se na výsledek. Pro prohlídku bajtového výpisu doporučuji zachytit si komunikaci pomocí Wiresharku a prohlédnout si odpověd od zařízení SDS.

Tyto funkce jsou velice užitečné pro:

• komunikaci mezi SDS zařízeními (zařízení SDS pomocí SDS-C funkce http_get() zjistí hodnotu sys[], ram[], text[] či share[] z jiného zařízení SDS)
• ukládání informací na server (server pošle na zařízení SDS dotaz a odpověď - si zpracuje)
• čtení stavu v textové podobě (pole text[]), nebo zadávání stavu přes pole share[]
• pomoc při vývoji SDS-C programu (výpis hodnot)