Konfigurace Scriptable pluginu

ScriptablePlugin umožňuje provádět nad piny složitější operace a dá se rovněž použít pro generování různých funkcí na výstupech. Celý plugin dokáže emulovat funkčnost většiny ostatních pluginů s vyjímkou těch, které přímo komunikují s HW (ISESCardPlugin, ISESProCardPlugin, PCI1202CardPlugin). Interface dostupný přímo z MeasureServeru je minimální a většina operací se provádí pomocí scriptu uloženého v samostatném souboru.

Dialog v MeasureServeru

Pomocí tohoto dialogu jdou měnit základní parametry. Jakákoliv změna parametru vyžaduje restart MeasureServeru.

V dialogu MeasureServeru (viz. hlavní dokumentace) je nejdůležitější řádek pro volbu souboru se scriptem, který popisuje chování pluginu, dostupné piny a ostatní použité pluginy.

V případě, že script používá i jiné pluginy, je možné pomocí dalšího prvku umístěného v dialogu, nastavovat jejich parametry.

Script

Scripty jsou textové soubory s koncovkou psc. Tyto scripty jsou načteny při startu MeasureServeru. Případné změny v nich provedené se projeví až při dalším spuštění MeasureServeru. Syntaxe použítá ve scriptu nejvíce připomíná programovací jazyk C s některými prvky z jiných jazyků. Všechny proměnné jsou reálná čísla (typ double v C), jiný datový typ není přímo podporovaný. Rozlišují se velká a malá písmena! Všechny operace prováděnné scriptem jsou synchronní s celým během serveru (dokud běží script, tak server nemůže provádět nic jiného).

Struktura scriptu je částečně fixní s tím, že většina částí je nepovinná, ale pokud jsou uvedeny tak musí být ve správném pořadí.

Struktura scriptu je následující:

1. Hlavička - povinná
2. Definice importu - nepovinná
3. Definice proměnných - nepovinná
4. Definice pinů a speciálních handlerů - nepovinná
5. Definice burst experimentů - nepovinná

Na většině míst v textu je možno používat komentáře uvedené znakem '#'. Cokoliv od tohoto znaku do konce řádku je ignorováno.

Hlavička

Hlavička má následující povinný formát

version 1.0
name example_generator

• version udává číslo verse scriptovacího jazyka a musí být 1.0
• name udává jméno, pod kterým se plugin zobrazí v rozhraní MeasureServeru.

Definice importu

Popisuje jaké piny a z kterých pluginů budou použity. Piny se ve zbytku scriptu chovají jako proměnné. Zápis do takovéto proměnné zapíše hodnotu do pinu druhého pluginu. Čtení z takovéto proměnné přečte hodnotu z pinu druhého pluginu. Tato sekce má dvě části, jejichž pořadí je pevně dáno. První část definuje další pluginy, které jsou použity, včetně jména jejich konfigurace. Formát této části je následující:

using plugin_id "path_to_plugin" config_id

• plugin_id je jméno identifikující plugin pro použití v druhé sekci.
• path_to_plugin je cesta k souboru pluginu.
• config_id identifikuje konfiguraci použitou pro inicializaci pluginu. Konfiguraci zde uvedenou je možné měnit pomocí konfiguračního dialogu v MeasureServeru.

using hw_lib "Plugins\ISESProCardPlugin.ldp" config1

Druhá část pak identifikuje piny z pluginů definovaných v první části, které jsou scriptem používány. Formát této části je následující:

import pin_id plugin_id "pin_name" [filter]

• pin_id je jméno identifikující pin pro použití ve zbytku scriptu.
• plugin_id je jméno identifikující plugin, ze kterého se pin bere.
• pin_name je jméno pinu v rámci pluginu plugin_id.
• filter pokud je uvedeno toto nepovinné slovo a je použit HW plugin, je hodnota přečtená z pinu průměrem několika hodnot získaných z HW.

import output_a hw_lib "Write D/A 1"

Definice proměnných

Popisuje globální proměnné dostupné v celém scriptu. Proměnné vzniknou při startu serveru a nastaví se na hodnotu uvedenou v jejich definici. Následně může script jejich hodnoty libovolně číst a měnit. Formát definice proměnné je následující:

variable variable_id = value

• variable_id je jméno identifikující proměnnou pro použití ve zbytku scriptu.
• value je hodnota, která se do proměnné uloží při startu serveru.

variable sfrequency = 1.345

Definice pinů a speciálních handlerů

Tato část obsahuje výkonnou činnost scriptu. Celá je tvořena z bloků které mají následující syntaxi:

block_type [block_id] { operations }

• block_type je typ bloku. V současnosti existuje 5 typů bloků (pin_read, pin_write, on_each_second, on_user_change, experiment), které budou popsány dále.
• block_id jméno identifikující blok. Musí být přítomno u bloků definujících piny (pin_read, pin_write) a nesmí být přítomno u handlerů (on_each_second, on_user_change)
• operations operace, které je potřeba provést pokud dojde ke zpracování bloku.

Typy bloků

Handlery on_each_second a on_user_change

Operace asociované s jedním z těchto handlerů se spustí, pokud nastane operace asociovaná s handlerem.

Operace asociované s on_each_second se spusti přibližně každou sekundu.

Operace asociované s on_user_change se spustí, když dojde ke změně uživatele nebo odpojení posledního uživatele.

V případě, že je v souboru scriptu definováno několik handlerů stejného typu, se všechny provedou v pořadí uvedeném ve scriptu.

Piny pin_read a pin_write

Operace asociované s těmito piny se spustí pří přečtení nebo žápisu hodnoty pinu jménem block_id. Je možné mít v jednom scriptu pin_read i pin_write se stejným block_id, ale není možné mít ve scriptu několik pin_read/pin_write se stejným block_id.

Neexistuje žádné omezení z jakých pinů z ostatních pluginů je možné v rámci bloku číst nebo na které je možné zapisovat. Čtecí handler pro pin může klidně zapisovat na pin jiného pluginu. To umožňuje tvorbu generátorů signálu jak je uvedeno v kapitole Příklady

V případě, že běží handler pin_write, je dostupná speciální proměnna new_value s hodnotou, která se má zapsat do pinu.

V případě, že běží handler pin_read, je dostupná speciální proměnná time, která obsahuje čas v sekundách od posledního zápisu do tohoto pinu popřípadě od startu serveru pokud k žádnému zápisu dosud nedošlo. V případě, že odpovídající pin_write handler neexistuje, je zápis na tento pin ignorován, ale k restartu času dojde. Dále je zde dostupná speciální proměnná result, do níž by měl pin uložit hodnotu, která se vrátí jako hodnota přečtená z pinu. Defaultně je v této proměnné na začátku bloku uložena hodnota 0. Dále je dostupná proměnná reset_time, která (pokud je na konci nastavena na kladnou hodnotu), způsobi restart hodnoty time. V případě experimentů, jejichž server běží dlouhodoběji, je potřeba jednou za čas provést tento restart, jinak dojde ke ztrátě přesnosti času uloženého v proměnné time. V závislosti na HW počítače a velikosti hodnoty proměnné time může být čas vyjádřen až s přesností na desetinu milisekundy.

Experiment

Úvod

• Inicializační část, která může připravit výstupy či předpočítat pomocné hodnoty. Tato část je uvedena pomocí klíčového slova init
• Blok, který je zavolán pro každý naměřený vzorek a generuje výstupy. Tato část je uvedena pomocí klíčových slov on_sample nebo on_manual_sample, za kterými je uvedena plugin_id pluginu, který se má použít pro fyzické měření. V současnosti je podporován pouze HW plugin pro PCI1202CardPlugin
• Finalizační část, která může nastavit výstupy po skončení experimentu. Tato část je uvedena pomocí klíčového slova finalize

experiment foo {
  init { operations }
  on_sample plugin_id { operations }
  finalize { operations }
}

Průběh experimentu

• Uživatel (klient na internetu) dá pokyn k provedenní experimentu.
• Spustí se inicializační blok experimentu, který jednak může vyslat hodnoty na výstupní piny jako v případě běžných handlerů nebo pomocí funkce write_output vygenerovat seznam časů od začátku experimentu a hodnot (až 1000000 hodnot), které se mají v uvedené časy poslat na analogový výstup HW pluginu. V proměnné duration dostane požadovanou délku měření v ms, kterou může podle potřeby změnit. Hodnota, která v této proměnné zůstane na konci funkce, je použita jako délka experimentu (hodnoty delší než 10s jsou omezeny na 10s).
• Provede se HW měření prvních 4 analogových vstupů HW pluginu po uvedenou dobu. Hodnoty, které mají být poslané na výstup (pokud je init blok vygeneroval), se posílají v odpovídající časy a zároveň se ukládají jako další vstup.
• Pro každý naměřený HW vzorek se zavolá blok on_sample/on_manual_sample. Ve vstupních proměnných sample_count, sample_index, burst_in_time, burst_in_0-burst_in_7 dostane hodnoty ze vzorku. V současnosti jsou naměřené hodnoty uložené do burst_in_0-burst_in_3 a burst_in_7 obsahuje hodnotu naposledy poslanou na výstup. Blok uloží hodnoty, které mají být výsledkem experimentu pro tento vzorek do proměnných burst_out_time (defaultně je na začátku bloku přednastavené na stejnou hodnotu jako burst_in_time) a burst_out_0-burst_out_7. V případě, že se jedná o blok on_sample, je obsah těchto proměnných automaticky poslán na výstup po skončení bloku. Blok on_manual_sample musí hodnoty, pokud se mají zaznamenat, zapsat explicitně pomocí funkce write_output. Je možné z jednoho vstupního vzorku vygenerovat několik výstupních vzorků několika voláními write_output, nicméně celkový výstup nemůže obsahovat více než desetinásobek počtu HW vzorků. Případné přebytečné výstupy se ignorují. Pokud je zavolána funkce stop, zpracování zbývajících naměřených HW vzorků se přeskočí.
• Je zavolána finalizační funkce, která může zapsat cokoliv na výstupní piny.
• Výstup vygenerovaný on_sample/on_manual_sample blokem je v serveru zaznamenaný jako nový experiment.

Oproti běžným handlerům obsahují bloky experimentů speciální podporu pro předávání dat mezi bloky. Obsah dočasných proměnných (t0-t99) se přenáší mezi voláními bloků (například hodnota zapsaná do proměnné t50 v init bloku v ní bude dostupná i v průběhu on_sample bloku).

V blocích init a on_manual_sample je možné používat funkci write_output, která zapíše aktuální stav burst_out_* proměnných do seznamu dat posílaných na výstup v případě init bloku nebo do záznamu experimentu v případě on_manual_sample bloku. V případě init bloku je možné zapsat až 1000000 vzorků. V případě on_manual_sample je možné zapsat desetinásobek naměřeného množství HW vzorků (uložené v sample_count).

Blok on_sample/on_manual_sample na začátku dostane v proměnných sample_index, burst_in_time a burst_in_0-burst_in_7 parametry HW vzorku pro který je právě volán. Hodnota burst_out_time je nastavena na stejnou hodnotu jako burst_in_time. V rámci bloku je možné použít funkce sample a isample pro načtení parametrů i jiných naměřených vzorků. Volání jedné z těchto funkcí naplní hodnoty burst_in_time a burst_in_0-burst_in_7 hodnotami pro příslušný vzorek. Ostatní proměnné, hlavně burst_out_time a sample_index, zůstanou nezměněnné.

Operace

Operace asociované s blokem popisují, co se má stát, když se blok zpracovává. Jsou podporovány základní matematické operace jako je sčítání, odčítání, násobení, dělení, zbytek po dělení. Script také obsahuje několik goniometrických funkcí a nástroje pro tvorbu jednoduchých podmínek. V operacích je možné používat všechny proměnné uvedené v předchozích sekcích a dále je možno použít 100 dočasných proměnných, které platí pouze po dobu běhu bloku a na jeho začátku jsou nastavené na hodnotu 0.

Každý blok může mít libovolný počet operací. Každá operace může být jedno z následujícího:
Přiřazení:

Y = expression ;

if ( if_expression ) {
  operations
}
[ else { operations } ]

while ( if_expression ) {
  operations
}

exit ;

Možné řídící funkce:

Expression

Expression je výraz, který může obsahovat libovolnou syntakticky platnou kombinaci proměnných, explicitních číselných konstant (např. 2.4), operací a funkcí uvedených níže. V příkladech uvedených níže jsou pismena A a B jména proměnných.

Základní matematické operace

Podporované matematicé funkce

If_expression

Tento typ výrazu může být použit pouze v podmínce typu if. Oproti normálnímu výrazu je ještě rozšířen o následující užitečné zkratky.

Příklady

Příklad 1: Jednoduchý generátor sinusového výstupního signálu

Plugin je možné použit pro generování signálu přes ISES následujícím postupem.

• Ve scriptu se vyvoří pin_read handler který, na základě času získaného z proměnné time a případných globálních parametrů, zapíše odpovídající hodnotu na výstup pluginu řídícího kartu.
• V MeasureServeru se zapne fast log pro tento pin a nastaví se mu vhodná frekvence vzorkování. Tím se zajistí pravidelné čtení z pinu, které díky tomu jak byl pin vytvořen, generuje křivku na výstupu.
• V případě potřeby změny parametrů je toto mozno zajistit pomoci dalších pin_write bloků které nastavují globální proměnné pro generator.

Ukázka jednoduchého scriptu generujícího sinusový přůběh s nastavitelnou frekvencí

version 1.0
name sin_signal

# Importovani pinu do kterého budeme zapisovat.

using card_lib "plugins\ISESProCardPlugin.ldp" card_config_1
import output card_lib "Write D/A 1"

# Frequence generované křivky v HZ.

variable set_frequency = 1.0

# Pin jehož čtení generuje výstup.

pin_read generator {

     # Generovani hodnoty pro aktuální okamžik.

     result = sin( time * set_frequency * 6.28 ) * 2048 + 2048 ;
}

# Pin sloužící pro nastavení generované frequence.

pin_read frequency {
     result = set_frequency ;
}

pin_write frequency {
     set_frequency = new_value ;
}

Příklad 2: Generátor sinusového nebo pilového výstupního signálu

# Script generujici sinusovou krivku nebo pilu s uzivatelsky nastavitelnou
# frekvenci.
#
# Script ma nasledujici piny:
# frequency .. cteni vraci aktualne nastavenou frekvenci v Hz.
# frequency .. zapis nastavi novou frekvenci v Hz.
# measured_value .. cteni vraci hodnotu prectenou z prvniho analogoveho vstupu
#                   ISESu.
# generator .. precteni tohoto pinu vygeneruje na vystup jednu hodnotu. Pro
#              spravnou funkci generatoru je potreba mit u tohoto pinu zapnuty
#              fastlog s rozume vysokou vzorkovaci frekvenci.

# Verze scriptovaciho jazyka.

version 1.0

# Nazev scriptu. Tato polozka se pouzije jako nazev pluginu v MeasureServeru.

name example_generator

# Reference na HW plugin, ktery se bude pouzivat pro vystup a vystup.

using card_lib "plugins\ISESProCardPlugin.ldp" card_config_1

# Importovani pinu, do kterého budeme zapisovat vystup.

import output card_lib "Write D/A 1"

# Importovani pinu, ze ktereho budeme cist namerene hodnoty.

import vstup_1 card_lib "Read A/D 1"

# Typ generovane krivky.
#
# Hodnota >= 0.0 odpovida sinusove krivce.
# Hodnota < 0.0 odpovida pile.

variable output_type = 1.0 

# Frequence generované křivky v Hz.

variable generated_frequency = 1.0

# Promenna pouzita pro zastaveni generovani, kdyz neni komunikace
# s klientem. 

variable watchdog_counter = 0.0

# Pin, jehož čtení generuje výstup.

pin_read generator {

     # Generovani hodnoty pro aktuální okamžik. Pokud je generovani
     # zapnute, tak se spocita skutecna hodnota, jinak se pouzije
     # hodnota odpovidajici nule.

     if ( watchdog_counter > 0.0 ) {
     
         # Vygenerovani zvoleneho typu krivky jako hodnoty
         # v rozsahu <-1,1>
     
         if ( output_type >= 0.0 ) {
             t0 = sin( time * generated_frequency * 6.28 ) ;
         }
         else {
             t0 = fraction( time * generated_frequency ) * 2 - 1 ;
         }
         
         # Prepocet na vystupni rozsah 0 az 4095 (odpovida 12bitovemu rozliseni
         # ADDA karty a vystupnimu rozsahu <-5V,5V> tj. 0-4095 binarne)
         
         t0 = t0 * 2048 + 2048 ;
         
         # Vyslani spocitane hodnoty na vystup. Normalni experiment by mohl
         # spocitanou hodnotu vyslat i kdyz se nic negeneruje. Protoze vsak
         # ostatni ukazkove experimenty pouzivaji vystup, tak by takoveto
         # chovani tohoto prikladu zpusobilo nefunkcnost jejich vystupu.       
          
         output = t0 ;
     }
     else {
         t0 = 2048 ;

         # Nasledujici radek vynuti restart promenne time. Vsechny vypocty v
         # tomto scriptu se provadeji pomoci 64bitovych cisel s pohyblivou
         # desetinou carkou. Dusledkem je, ze u prilis velkych hodnot dochází
         # ke ztrátě přesnosti hodnoty. Pokud by se reset neprovedl, experiment
         # by po delsi dobe zacal generovat cim dal "zubatejsi" krivku.  

         reset_time = 1 ;
     }

     # Jeji vraceni jako hodnoty tohoto pinu. 
     
     result = t0 ;
}

# Pin, jehoz precteni nacte hodnotu z prvniho HW vstupu. 

pin_read measured_value {
     result = vstup_1 ;
}

# Pin sloužící pro cteni a nastavovani generovane frekvence.

pin_read frequency {
     result = generated_frequency ;
     
     # V ukazkove strance je applet, ktery periodicky cte tento pin (a zaroven
     # tento pin neni logovan), takze se tento pin cte prave kdyz je funkcni 
     # spojeni s klientem.
     # Pri kazdem precteni se nastavi promena watchdog_counter na vhodne
     # zvolenou hodnotu. Hodnota teto promenne je kazdou sekundu snizena 
     # o 1 (viz on_each_second nize) a generovani se zastavi pokud bude mensi
     # nez nula nebo rovna nule (viz. generator nahore).
     # Dusledkem je, ze generovani se zastavi pokud si tento pin nekdo neprecte
     # po odpovidajici pocet sekund.
     
     watchdog_counter = 5 ;     
}

pin_write frequency {
     generated_frequency = new_value ;
}

# Pin slouzici na nastavovani typu generovaneho vystupu.

pin_write type {
     output_type = new_value ;
}

# Nasledujici funkce je volana kazdou sekundu.

on_each_second {

    # Odpocet casu do zastaveni generovani pokud uz toto nebylo zastaveno.

    if ( watchdog_counter > 0.0 ) {
        watchdog_counter = watchdog_counter - 1 ; 
    }
}

# Kdyz se zmeni uzivatel, nastavime zpatky pocatecni frekvenci a
# typ krivky.

on_user_change {
    generated_frequency = 1.0 ;
    output_type = 1.0 ;
}