MENU

K8055-M.A.R.I.E.
(Management Application for Remote Internet Experiments)

Příkazy a řízení

Komunikace mezi řídicí webovou stránkou a aplikací K8055-MARIE je realizována pomocí javascriptového modulu XMLHttpRequest a řízení samotné využívá tzv. metody AJAX. Jedná se o kombinaci využívání javascriptového modulu, který je implementován do moderních internetových prohlížečů, na straně klienta a podpůrných PHP skriptů běžících na straně serveru. Díky tomuto způsobu řízení není třeba na straně klienta instalovat žádné potřebné rozšíření např. prostředí JAVA pro běh appletů, či prvky různých rozšíření ActiveX.

Vzdálené řízení je realizováno klasickou webovou stránkou psanou v HTML jazyce, rozšířenou o příkazy JavaScriptu ke komunikaci s deskou K8055 (viz obr. 1). Tyto příkazy jsou uloženy v externím souboru K8055.js, který se k dané webové stránce připojí stejně jako každý jiný javascriptový soubor. Z důvodů zachování kompatibility pro jednotlivé verze a typy internetových prohlížečů, je metoda AJAX zprostředkována standardní JavaScriptovou knihovnou jQuery, ta celé komunikaci dodává bezpečnost a spolehlivost.

schéma komunikace strany klienta a serveru při instalaci na dvou rozdílných PC
obr. 1 - Schéma komunikace strany klienta a serveru.

Rozšiřující JavaScriptové příkazy pro K8055

Knihovna příkazů K8055.js

Knihovnu javascriptových příkazů k řídicí webové stránce připojíme přilinkováním souborů jQuery.js a K8055.js v sekci <head>...</head> dané webové stránky. V ukázkovém demo-souboru jsou tyto soubory uloženy ve složce jvs.

Kód ukázkovém souboru K8055-MARIE_demo.htm pak vypadá následovně:


<!DOCTYPE html>
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<!-- BEGIN - JavaScripts for Remote Control -->
<script src="jvs/jquery.min.js"></script>
<script>
   var MARIE_URL = '
http://K8055-MARIE_IP:PORT';
</script>
<script src="jvs/K8055.js"></script>
<script>
   SetCurrentDevice(
K8055-ADR);
</script>

<!-- END - JavaScripts for Remote Control -->
:
atd./etc.

Soubor jquery.min.js je knihovna jQuery, která rozšiřuje HTML stránku o obecné příkazy komunikace AJAX. Soubor K8055.js pak stránku rozšiřuje o příkazy vzdáleného řízení karty K8055. Do proměnné MARIE_URL je třeba ještě před načtením knihovny K8055.js uložit IP adresu (nebo URL) počítače, na kterém je spuštěna aplikace K8055-MARIE (včetně nastaveného portu). Zde je tato hodnota označena formálním http://K8055-MARIE_IP:PORT. Pokud není proměnná MARIE_URL nastavena, je do ní knihovnou K8055.js vložena výchozí hodnota http://127.0.0.1:80 - což odpovídá tzv. localhost. Po načtení knihovny K8055.js je dobré nastavit adresu USB desky K8055, kterou chceme ovládat. To provedeme příkazem SetCurrentDevice(), jehož parametrem (zde označen K8055-ADR) je hodnota 0-3 - dle adresy použité desky (naspaveno pomocí přepínači switch přímo na desce).

Řídicí příkazy lze vyvolávat standardními událostmi JavaScriptu (např. načtení stránky, kliknutí na prvek, vypršení časovače… apod.). Vytvoření řídicí webové stránky je pak plně v kompetenci jejího tvůrce.

Příklad
Ukázka kódu webového prvku (tlačítka), které po kliknutí nastaví všechny digitálních výstupy desky K8055 na hodnoty logické 1:
<input type="BUTTON" value="Zapni výstupy" onClick="SetAllDigital();">
Příkazy knihovny K8055.js

Příkazy se snaží svou syntaxí korespondovat s originálními příkazy použitými v DLL knihovně příkazů firmy Velleman. Pro potřeby rozšířeného a rychlejšího vzdáleného řízení byly od verze 2.00 přidány další příkazy. Přehled příkazů knihovny K8055.js je uveden v tabulce níže.

K8055D.DLL v5.0.0.0 - Technická příručka - česky

Popis funkcí a procedur obsažených v DLL knihovně K8055D.DLL pro přímé řízení USB desky K8055 (český překlad, anglický originál na webu firmy Velleman).

Následující tabulka zobrazuje seznam příkazů javascriptové knihovny K8055.js včetně jejich popisu:

K8055-MARIE (ver. 1.00 → x.xx)

Příkaz

Popis příkazu

ReadAnalogChannel(Channel)

Funkce vrací celé číslo (0-255) odpovídající napětí na analogovém vstupu. Proměnná Channel udává zda jde o vstup 1 či 2

Příklad: (načtení analogovém vstupu 1 do proměnné AD1)

var AD1 = ReadAnalogChannel(1);

ReadAllAnalog()

Funkce vrací řetězec znaků složený z dvojice čísel odpovídající napětím na analogových vstupech. Obě hodnoty jsou odděleny znakem |.

Příklad: (převod výstupního řetězce do číselných proměnných hod1 a hod2)

var vyst = ReadAllAnalog();
var hod = new Array(2);
hod = vyst.split('|');
var hod1 = parseInt(hod[0]);
var hod2 = parseInt(hod[1]);

OutputAnalogChannel(Channel, Data)

Nastavení analogového výstupu - proměnná Channel určuje zda se jedná o výstup 1 či 2. Číselná proměnná Data (rozmezí 0-255) určuje hodnotu výstupního napětí (resp. šířky modulovaného signálu)

Funkce vrací hodnotu true při úspěšném nastavení výstupu (resp. false při nezdaru).

SetAnalogChannel(Channel)

Nastaví zadaný analogový výstup (proměnná Channel) na maximální hodnotu 255.

Funkce vrací hodnotu true při úspěšném nastavení výstupu (resp. false při nezdaru).

Pozn.:
Totéž jako funkce OutputAnalogChannel(Channel, 255)

ClearAnalogChannel(Channel)

Nastaví zadaný analogový výstup (proměnná Channel) na minimální hodnotu 0.

Funkce vrací hodnotu true při úspěšném nastavení výstupu (resp. false při nezdaru).

Pozn.:
Totéž jako funkce OutputAnalogChannel(Channel, 0)

OutputAllAnalog(Data1, Data2)

Nastaví oba analogové výstupy na zadané hodnoty proměnných Data1 a Data2.

Funkce vrací hodnotu true při úspěšném nastavení výstupů (resp. false při nezdaru).

SetAllAnalog()

Nastaví oba analogové výstupy na maximální hodnotu 255.

Funkce vrací hodnotu true při úspěšném nastavení výstupů (resp. false při nezdaru).

Pozn.:
Totéž jako funkce OutputAllAnalog(255, 255)

ClearAllAnalog()

Nastaví oba analogové výstupy na minimální hodnotu 0.

Funkce vrací hodnotu true při úspěšném nastavení výstupů (resp. false při nezdaru).

Pozn.:
Totéž jako funkce OutputAllAnalog(0, 0)

SetDigitalChannel(Channel)

Nastaví zadaný bit (proměnná Channel) z osmice výstupních digitálních linek na hodnotu logické 1 (tj. na výstupní svorkovnici stav sepnuto).

Funkce vrací hodnotu true při úspěšném nastavení výstupu (resp. false při nezdaru).

ClearDigitalChannel(Channel)

Nastaví zadaný bit (proměnná Channel) z osmice výstupních digitálních linek na hodnotu logické 0 (tj. na výstupní svorkovnici stav vypnuto).

Funkce vrací hodnotu true při úspěšném nastavení výstupu (resp. false při nezdaru).

WriteAllDigital(Data)

Nastaví jednotlivé bity osmice výstupních digitálních linek na hodnoty odpovídající binární podobě čísla zadaného proměnnou Data.

Funkce vrací hodnotu true při úspěšném nastavení výstupů (resp. false při nezdaru).

SetAllDigital()

Nastaví všechny výstupní digitální linky na hodnotu logické 1 (tj. na výstupní svorkovnici stav sepnuto).

Funkce vrací hodnotu true při úspěšném nastavení výstupů (resp. false při nezdaru).

Pozn.:
Totéž jako funkce WriteAllDigital(255)

ClearAllDigital()

Nastaví všechny výstupní digitální linky na hodnotu logické 0 (tj. na výstupní svorkovnici stav vypnuto).

Funkce vrací hodnotu true při úspěšném nastavení výstupů (resp. false při nezdaru).

Pozn.:
Totéž jako funkce WriteAllDigital(0)

ReadDigitalChannel(Channel)

Vrací hodnotu true (resp. false) pokud je v okamžiku dotazu stisknutý jeden z pětice (určen proměnnou Channel) digitálních vstupů.

ReadAllDigital()

Vrací celé číslo sestavující se z hodnot stisknutých digitálních vstupů. (první vstup: 1, druhý: 2, třetí: 4, čtvrtý: 8, pátý: 16)

Příklad: (vymaskování stavů digitálních vstupů)

var pom = ReadAllDigital();
if ((pom & 1) != 0) {1. vstup JE stisknut}
   else {1. vstup NENÍ stisknut};
if ((pom & 2) != 0) {2. vstup JE stisknut}
   else {2. vstup NENÍ stisknut};
if ((pom & 4) != 0) {3. vstup JE stisknut}
    else {3. vstup NENÍ stisknut};
if ((pom & 8) != 0) {4. vstup JE stisknut}
   else {4. vstup NENÍ stisknut};
if ((pom & 16) != 0) {5. vstup JE stisknut}
   else {5. vstup NENÍ stisknut};

ReadCounter(CounterNr)

Vrací hodnotu (0-65535) jednoho ze dvou čítačů (digitální vstupy 1 a 2). Číslo čítače je určeno proměnnou CounterNr.

Čítač registruje od okamžiku svého vynulování a reaguje jen na pulsy zadané délky (viz dále).

ResetCounter(CounterNr)

Vynulování hodnoty čítače 1 či 2 (určeno proměnnou CounterNr)

Funkce vrací hodnotu true při úspěšném vynulování čítače (resp. false při nezdaru).

SetCounterDebounceTime(CounterNr, TimeDebounceTime)

Nastavení minimální délky impulsů v milisekundách (celočíselná proměnná TimeDebounceTime), která budou registrovány zadaným čítačem 1 nebo 2 (proměnná CounterNr).

Funkce vrací hodnotu true při úspěšném nastavení čítače (resp. false při nezdaru).


Všechny příkazy uvedené v tabulce výše byly (od verze 2.7) rozšířeny o nepovinný parametr callback - je popsán níže. Výše uvedené příkazy jsou ve vyšších verzích zpětně kompatibilní s verzemi nižšími (pochopitelně bez parametru callback).

Příkazy v následující tabulce jsou platné až od verze 2.5 (bez callback) a 2.7 (s callback).


K8055-MARIE (ver. 2.7 → x.xx)

Příkaz

Popis příkazu  Pozn.: Parametr v  [ ] je volitelný

SearchDevices([callback])

Vrátí řetězec složený z adres (0-3) USB desek K8055 připojených k PC a povolených aplikací K8055-MARIE (Adresy desek jsou oddělené znakem | ).

Pozn.: Parametr callback vysvětlen na konci tabulky

SetCurrentDevice(CardAddr)

Nastaví desku dané adresy CardAddr (0-3) jako příjemce dalších příkazů.

Funkce vrací hodnotu true při úspěšném nastavení desky (resp. false při nezdaru).

ReadBackDigitalOUT([callback])

Vrací zpětně načtenou hodnotu (0-255) digitálních výstupů, která je aktuálně nastavena na výstupech USB desky (USB deska je určená příkazem SetCurrentDevice()).

Pozn.: Parametr callback vysvětlen na konci tabulky

ReadBackAnalogOUT([callback])

Vrací řetězec složený z dvojice zpětně načtených hodnot (0-255) analogových výstupů USB desky (Hodnoty výstupů jsou oddělené znakem | ).

Pozn.: Parametr callback vysvětlen na konci tabulky

ReadBothCounters([callback])

Vrací řetězec složený z dvojice hodnot (0-255) obou čítačů USB desky (Hodnoty čítačů jsou oddělené znakem | ).

Pozn.: Parametr callback vysvětlen na konci tabulky

Pozn.:
Jde o příkaz, který nahrazuje dvojici příkazů
ReadCounter(1);
ReadCounter(2);

ReadAllInputs([callback])

Vrací řetězec složený z dvojice hodnot (0-255) analogových vstupů, hodnoty reprezentující stisknuté digitální vstupy (viz ReadAllDigital()) a hodnot obou čítačů USB desky (Hodnoty všech vstupů jsou oddělené znakem | ).

Pozn.: Parametr callback vysvětlen na konci tabulky

Pozn.:
Jde o příkaz, který nahrazuje sérii příkazů
ReadAllAnalog;
ReadAllDigital();
ReadBothCounters();

ReadStatus([callback])

Vrací řetězec složený z hodnot kompletního stavu USB desky (tedy: analogové vstupy, digitální vstupy, čítače, hodnoty analogových výstupů a digitálních výstupů). Všechny hodnoty jsou oddělené znakem |.

Pozn.: Parametr callback vysvětlen na konci tabulky

Pozn.:
Jde o příkaz, který nahrazuje sérii příkazů
ReadAllInputs();
ReadBackAnalogOUT();
ReadBackDigitalOUT();

GeneratorType(Channel, Type, [callback])

Nastavuje na typ (Type) průběhu (1 - sinus, 2 - square, 3 - ramp, 4 - sawtooth, 5 - triangle), který se bude generovat (rozmezí 0-255) na analogovém výstupu Channel (1-2).

Funkce vrací hodnotu true při úspěšném nastavení desky (resp. false při nezdaru).

wave form

   Pozn.: Parametr callback vysvětlen na konci tabulky

GeneratorFrequency(Channel, Freq, [callback])

Nastavuje frekvenci Freq (0,01-10 Hz) průběhu, který se bude generovat na analogovém výstupu Channel (1-2).

Funkce vrací hodnotu true při úspěšném nastavení desky (resp. false při nezdaru).

Pozn.: Parametr callback vysvětlen na konci tabulky

GeneratorTimeInterval(Channel, Time, [callback])

Nastavuje dobu trvání Time (1-300 s), po kterou se bude zadaný průběh, generovat na analogovém výstupu Channel (1-2).

Funkce vrací hodnotu true při úspěšném nastavení desky (resp. false při nezdaru).

Pozn.: Parametr callback vysvětlen na konci tabulky

GeneratorStart(Channel, [callback])

Odstartuje generování funkčního průběhu (parametry viz dříve) na zadaném analogovém výstupu Channel (1-2).

Funkce vrací hodnotu true při úspěšném nastavení desky (resp. false při nezdaru).

Pozn.: Parametr callback vysvětlen na konci tabulky

GeneratorStop(Channel, [callback])

Zastaví generování funkčního průběhu (nezávisle na zadaném čase - viz GeneratorTimeInterval()) na analogovém výstupu určeném hodnotou Channel (1-2).

Funkce vrací hodnotu true při úspěšném nastavení desky (resp. false při nezdaru).

Pozn.: Parametr callback vysvětlen na konci tabulky

K8055_Json(cardAdr, [callback])

Řídicí aplikace K8055-MARIE odešle kompletní stav zadané desky K8055 (cardAdr) ve speciálním formátu JSON čitelném pro JavaScript. Kupříkladu stav analogového výstupu č. 2 desky adresy 0 je pak dostupný v  proměnné: card[0].OUT.ANALOG.B
(viz Pozn. v části CallBack procedure)

Proměnná card tvoří pole s indexy 0-3 (dle čísel připojených desek K8055). Struktura těchto proměnných je následující:

Analog OUTs:
card[0].OUT.ANALOG.A
card[0].OUT.ANALOG.B
Digital OUT:
card[0].OUT.DIGITAL
Analog INs:
card[0].IN.ANALOG.A
card[0].IN.ANALOG.B
Digital IN:
card[0].IN.DIGITAL.A
Counters:
card[0].IN.COUNTER.A
card[0].IN.COUNTER.B

CallBack procedure

Parametr callback uvádí jméno javascriptové procedury, která se provede po úspěšném dokončení funkce knihovny K8055.js, u které je procedura callback uvedena jako parametr.

Např.
Pro zápis hodnoty 155 na digitální výstup a následné zobrazení této informace procedurou, kterou kupříkladu nazveme ZapisVystup, můžeme zvolit dvě možnosti.
V první (klasické):

   WriteAllDigital(155);
   ZapisVystupy();
   Command1;
   Command2;

dojde k zavolání funkce WriteAllDigital(155), po jejím dokončení bude vykonána procedura ZapisVystupy a až po jejím dokončení mohou pokračovat příkazy Command1 a Command2, které však na výsledku předešlých dvou příkazů nemusí vůbec záviset. To může někdy zdržovat.
Naopak, při použití druhého zápisu:

   WriteAllDigital(155, ZapisVystupy);
   Command1;
   Command2;

dojde k vykonávání příkazů Command1 a Command2 hned po zavolání funkce WriteAllDigital(155) a procedura ZapisVystupy probíhá paralelně s těmito příkazy.

Funkce pro zápis výstupů a stavů desky K8055 jsou (od verze 2) řešeny jako asynchronní, tedy zápis probíhá zcela bez jakéhokoliv zastavení běhu následujícího javascriptového kódu. Použijeme-li jako příklad výše uvedenou ukázku s příkazy WriteAllDigital(155), Command1 a Command2, začnou se příkazy Command1 a Command2 vykonávat ihned po zavolání procedury WriteAllDigital(155), nikoliv až po jejím dokončení. Procedura ZapisVystupy pak musí být zadána jako callback, protože by se začala vykonávat ještě ve chvíli, kdy nevíme, jak dopadl zápis do desky. Na druhou stranu, často potřebujeme do desky „jen” zapsat, aniž bychom potřebovali nějak reagovat na stav, že k tomu došlo (pak funkci callback nepotřebujeme a je tedy jen volitelným parametrem).
      Naopak funkce pro čtení vstupů a stavů desky probíhají stále synchronně. Prvním důvodem je zpětná kompatibilita kvůli příkazům verze 1, druhým důvodem je jednodušší programování synchronního kódu (speciálně pro začínající programátory). Synchronní způsob, jak již tušíme, však výrazně zpomaluje běh celého javascriptového kódu (musí se čekat se na odpověď desky K8055), proto i tyto příkazy byly doplněny o možnost funkce callback, aby bylo možné alespoň paralelní zpracování výsledku funkce při souběžném běhu následujícího kódu (opět možné použití je zcela volitelné).

Pozn.:
Pro výrazné zrychlení načítání desky K8055 byla vyvinuta asynchronní funkce K8055_Json(), která bez zastavení výkonného kódu naplňuje proměnnou card. Pokud je aktualizace této proměnné řešena na pozadí stránky pomocí funkce K8055_Json() např. pomocí události časovače (musí vyřešit autor ovládacího skriptu), je možné dotazy na stav vstupů desky K8055 výrazně zrychlit. Načítá se totiž potřebná hodnota z aktuální proměnné card namísto synchronního dotazování pomocí synchronních funkcí (viz tab. funkcí verze 1). Tento způsob je plně asynchronní a nejrychlejší možný. Je však doporučován až po úplném pochopení filozofie asynchronního ovládání a bezchybném zvládnutí techniky vzdáleného řízení desky K8055 - tedy zkušenějším tvůrcům.