www.rexcontrols.cz www.contlab.eu www.pidlab.com Ovladač DbDrv systému REX Uživatelská příručka REX Controls s.r.o. Verze 2.10.7 (revize 2) Plzeň 28.8.2015
Obsah 1 Ovladač DbDrv a systém REX 2 1.1 Úvod....................................... 2 1.2 Požadavky na systém.............................. 2 1.3 Instalace ovladače na vývojovém počítači.................. 3 1.4 Instalace ovladače na cílovém zařízení.................... 3 1.4.1 Zařízení s Windows........................... 3 1.4.2 Zařízení s Windows CE........................ 3 1.4.3 Zařízení s Linuxem........................... 3 1.4.4 ODBC ovladač............................. 4 2 Zařazení ovladače do projektu aplikace 5 2.1 Přidání ovladače DbDrv do projektu...................... 5 2.2 Konfigurace ovladače.............................. 7 2.2.1 Formát konfiguračního souboru.................... 7 3 Připojení vstupů a výstupů do řídicího algoritmu 11 4 Poznámky k implementaci 13 5 Co dělat při problémech 14 Literatura 15 1
Kapitola 1 Ovladač DbDrv a systém REX 1.1 Úvod V této příručce je popsáno používání ovladače DbDrv řídicího systému REX pro připojení libovolné SQL databáze, pro kterou na dané platformě existuje ODBC interface. Ovladač umožňuje číst data z databáze a data také zapisovat. Dále je možné do databáze exportovat archivy systému REX, tj. alarmy, události a trendy. Ovladač byl vyvinut firmou REX Controls. 1.2 Požadavky na systém Obecně lze říci, že pro použití ovladače DbDrv musí být dodrženy minimální požadavky nutné k provozování řídicího systému REX. Pro konfiguraci ovladače postačuje běžný počítač PC (případně v průmyslovém provedení). Provozování ovladače je možné na jakémkoliv cílovém zařízení se systémem REX, musí však být nainstalován ODBC ovladač používané databáze. Aby bylo možno ovladač využívat, musí být na vývojovém (konfiguračním) počítači a na cílovém zařízení (počítači) nainstalováno programové vybavení: Vývojový počítač Operační systém jeden ze systémů: Windows XP, Vista, 7 nebo 8 Vývojové nástroje systému REX verze pro operační systémy Windows Cílové zařízení Runtime jádro systému REX verze pro zvolené cílové zařízení s jedním z podporovaných operačních systémů: Windows CE, Windows XP/Vista/7/8, Linux Debian/Xenomai/OpenWrt Ovladač IO verze pro danou platformu 2
ODBC interface verze pro konkrétní databázi (MySQL, Postgre- SQL, MS-SQL,... ) V případě, že vývojový počítač je přímo cílovým zařízením (řídicí systém REX bude provozován v jedné z variant Windows), instaluje se pouze jedna kopie řídicího systému REX. 1.3 Instalace ovladače na vývojovém počítači Ovladač DbDrv se instaluje jako součást řídicího systému REX. Je obsažen v instalátoru vývojových nástrojů systému REX, pro jeho nainstalování je pouze nutné ho v instalačním programu systému REX zaškrtnout. Po typické instalaci se řídicí systém REX nainstaluje do cílového adresáře C:\Program Files\REX Controls\REX_<version>, kde <version> označuje verzi systému REX. Po úspěšné instalaci se do cílového adresáře zkopírují soubory: DbDrv_H.dll Konfigurační část ovladače DbDrv. DbDrv_T.dll Cílová část ovladače DbDrv spouštěná exekutivou RexCore. Tato verze se používá, pokud na cílovém zařízení běží operační systém Windows XP/Vista/7/8. Pro jinou cílovou platformu je na ni třeba nainstalovat příslušnou verzi systému REX. DOC\CZECH\DbDrv_CZ.pdf Tato uživatelská příručka. 1.4 Instalace ovladače na cílovém zařízení 1.4.1 Zařízení s Windows Část ovladače pro cílové zařízení, která se používá pro připojení k databázi, je součástí instalace Vývojových nástrojů řídicího systému REX, která již byla zmíněna výše. 1.4.2 Zařízení s Windows CE Část ovladače pro cílové zařízení, která se používá pro připojení k databázi, je součástí instalačního balíčku (soubor.cab) runtime jádra systému REX. 1.4.3 Zařízení s Linuxem Pokud na cílovém zařízení dosud není instalováno runtime jádro RexCore systému REX, nejdříve jej nainstalujte podle příručky Začínáme se systémem REX pro danou platformu. Pro napojení na databázi z algoritmů řídicího systému REX je potřeba nainstalovat ovladač. To se provede z příkazové řádky pomocí příkazu Debian: 3
sudo apt-get install rex-dbdrvt OpenWrt: opkg install rex-dbdrvt 1.4.4 ODBC ovladač Na všech operačních systémech je dále potřeba nainstalovat ODBC ovladač používané databáze. Linux/Debian a MySQL Je potřeba nainstalovat balíčky unixodbc a libmyodbc: sudo apt-get install unixodbc libmyodbc Navíc je potřeba do souboru /etc/odbcinst.ini přidat sekci: [MySQL] Description Driver Setup = MySQL driver = /usr/lib/odbc/libmyodbc.so = /usr/lib/odbc/libodbcmys.so Raspberry Pi/Raspbian a MySQL Je potřeba nainstalovat balíčky unixodbc a libmyodbc: sudo apt-get install unixodbc libmyodbc Navíc je potřeba do souboru /etc/odbcinst.ini přidat sekci: [MySQL] Description Driver Setup = MySQL driver = /usr/lib/arm-linux-gnueabihf/odbc/libmyodbc.so = /usr/lib/arm-linux-gnueabihf/odbc/libodbcmys.so Další platformy a databázové systémy Postup instalace ODBC ovladače na vaší platformě by měl být součástí dokumentace vámi používaného databázového systému (MySQL, PostgreSQL, MsSQL atp.). 4
Kapitola 2 Zařazení ovladače do projektu aplikace Zařazení ovladače do projektu aplikace spočívá v přidání ovladače do hlavního souboru projektu a v připojení vstupů a výstupů ovladače v řídicích algoritmech. 2.1 Přidání ovladače DbDrv do projektu Přidání ovladače DbDrv do hlavního souboru projektu je znázorněno na obrázku 2.1. Obrázek 2.1: Příklad zařazení ovladače DbDrv do projektu aplikace Pro zařazení ovladače do projektu slouží dva zvýrazněné bloky. Nejprve je na výstup Modules bloku exekutivy EXEC připojen blok typu MODULE s názvem DbDrv, který nemá žádné další parametry. Druhý blok DB typu IODRV, připojený na výstup Drivers exekutivy má parametry: 5
module jméno modulu ovladače, které se pro tento ovladač zadává: DbDrv classname jméno třídy ovladače, které se pro tento ovladač zadává: DbDrv POZOR! Jméno rozlišuje velká a malá písmena! cfgname jméno konfiguračního souboru ovladače. Vytváření konfiguračního souboru je popsáno v kapitole 2.2. Doporučeno je zadávat jej ve tvaru <jméno_třídy>.rio, kde přípona.rio (REX Input/Output) byla zavedena pro tento účel. Jménem tohoto bloku, na obr. 2.1 zadaným jako DB, začínají názvy všech vstupních a výstupních signálů připojených k tomuto ovladači. Přesněji řečeno, kdyby byl např. blok DB z obr. 2.1 přejmenován na XY, začínala by pak jména všech vstupně výstupních bloků připojených k ovladači DbDrv znaky XY (viz dále). Z praktických důvodů je však doporučeno volit prefix mnemotechnicky blízký názvu ovladače. Právě popsané parametry bloku IODRV se konfigurují v programu RexDraw v dialogovém okně, jak je patrno z obr. 2.2. Obrázek 2.2: Vlastnosti ovladače pro zařazení do projektu 6
2.2 Konfigurace ovladače Konfigurace ovladače spočívá ve vytvoření implicitní konfigurace (po stisku tlačítka Special edit, viz Obr. 2.2), čímž se vytvoří soubor *.rio se všemi povinnými objekty. Dále je nutné soubor *.rio přímo editovat v textovém editoru. V tomto souboru je obsažena jak obecná konfigurace ovladače, tak definice a pojmenování jednotlivých signálů, jejichž čtení/zápis tento ovladač zprostředkovává. 2.2.1 Formát konfiguračního souboru Soubor *.rio je textový, takže jej lze upravovat v libovolném textovém editoru pracujícím s prostým textem (například Notepad). Struktura souboru je ilustrována následujícím příkladem: ODBC { Connection "DRIVER=MySQL;SERVER=192.168.1.200;PORT=3306;" "DATABASE=dbname;UID=dbuser;PWD=dbpassword;" #Connection "DSN=mydatabase;" Archive { Mode 1 SQL "alarm1" ArchiveID 0 Items 0,104,114,1000 } #Archive { Mode 2 SQL "trend1" ArchiveID 0 Items 100,100 } Archive { Mode 3 SQL "insert into trend1 (Time, GroupID, Value1, Value2, Value4)" "values(?t,?i,?1,?,?4)" ArchiveID 0 Items 100,111 } Group { Mode 2 SQL "test1" Period 5 Items "r1,i2,i3,r4" } Group { Mode 130 7
SQL "test2" Period 60 Items "d1,d2,i10,i11" } Group { Mode 3 SQL "select d1,d2,i10,i11, Time from test2 where Time <? and " "StationID=000 order by Time desc,id desc limit 2" Period 5 Items "gr1,gr2,gr3,gr4" } Group { Mode 131 SQL "insert into test2 (Time,StationID,d1,d2,i10,i11) values " "(UTC_TIMESTAMP(),2,?1,?,?,?)" Period 10 Items "gw1,gw2,gw3,gw4" } } Platí, že parametry, jejichž název začíná znakem # jsou ignorovány a lze je tedy využít jako komentář. Dlouhé SQL dotazy lze psát na jednu řádku nebo je rozdělit jak je ukázáno výše, při odřádkování však nesmí být na začátku následující řádky žádná mezera. Sekce Alarm se opakuje tolikrát, kolik definujeme různých pravidel (filtrů) pro export archivů systému REX. Obdobně sekce Group se opakuje pro každý zápis do databáze nebo čtení z databáze. V názvech parametrů i sekcí se rozlišují velká a malá písmena. Význam jednotlivých parametrů je následující: Connection Tzv. connection-string určující databázi, která má být připojena. Lze psát buď plný connection-string se všemi parametry nebo jen tzv. DSN (DataSource- Name), které se definuje prostředky ODBC ovladače a interně obsahuje potřebné identifikátory pro připojení databáze. 8
Mode Upravuje způsob zápisu a čtení dat z/do databáze. Možnosti jsou: Pro sekci Archive: 0 Nic se neexportuje (slouží pro dočasné vypnutí). 1 Exportují se jen alarmy a události (filtrované podle dalších parametrů). Tabulka v databázi musí mít sloupce Time, AlarmID, Code, Level, Value. 2 Exportují se jen trendy, tj. skupiny hodnot ukládané např. blokem TRND (filtrované podle dalších parametrů). Tabulka v databázi musí mít sloupce Time, GroupID, Value1, Value2,... 3 Exportují se jen trendy, ale narozdíl od předchozího případu má parametr SQL význam celého SQL příkazu, do kterého se vkládají hodnoty na místo otazníku (? = následující položka v pořadí čas, itemid, 1. hodnota, 2. hodnota,...;?t = čas;?i =itemid;?1 =1. položka;?2 =2. položka;...) Pro sekci Group: 0 Nic se nečte (slouží pro dočasné vypnutí). 1 Tabulka se předpokládá seřazená podle sloupce ID, přečte se řádek s nejvyšším číslem a hodnoty se předají do odpovídajících vlajek v úloze. Sloupce v databázi a položky/vlajky musí mít stejný název. 2 Tabulka se předpokládá seřazená podle sloupce Time (sekundárně podle ID), přečte se řádek s nejvyšším časem menší než aktuální a hodnoty se předají do odpovídajících vlajek v úloze. Sloupce v databázi a položky/vlajky musí mít stejný název. Tento režim umožňuje mít v databázi vygenerované hodnoty, které se postupně aplikují. 3 Vykoná se SQL dotaz z parametru SQL, do položek se zapíšou hodnoty z prvního řádku odpovědi (1. sloupec odpovědi do 1. položky,...). V SQL dotazu lze použít?, který se nahradí aktuálním časem. 128 Nic se nezapisuje (slouží pro dočasné vypnutí). 129 Zapisují se hodnoty odpovídajících vlajek v úloze, sloupce v databázi a položky/vlajky musí mít stejný název. 130 Jako předchozí případ a navíc se do sloupce Time nastaví aktuální čas exekutivy systému REX v UTC. 131 Vykoná se SQL příkaz v parametru SQL, do kterého se vkládají hodnoty na místo otazníku (? = následující položka v pořadí čas, itemid, 1. hodnota, 2. hodnota,...;?t = čas;?i =itemid;?1 =1. položka;?2 =2. položka;...) SQL Název tabulky (někdy může být potřeba <jméno databáze>.<název tabulky> ) nebo celý SQL dotaz (podle parametru Mode) ArchiveID Číslo archivu, ze kterého se čtou data. Archivy se číslují od 0 v pořadí, v jakém jsou uvedeny v konfiguraci exekutivy systému REX (blok EXEC a na něj připojené bloky ARCHIVE). Period Perioda v sekundách s jakou je generován SQL dotaz do databáze. 9
Items V sekci Group je to seznam čtených/zapisovaných položek. V sekci Archive je to rozsah ID (parametr id bloku, který alarm/trend vygeneroval), které se z archivu exportují do databáze. V případě archivů musí být zadán sudý počet čísel, kde lichá čísla definují začátek intervalu a sudá čísla definují jeho konec. Například "100,100,104,109" tak znamená, že se mají exportovat ID 100, 104, 105,..., 109. Čísla musí být seřazena ve vzestupném pořadí. 10
Kapitola 3 Připojení vstupů a výstupů do řídicího algoritmu Vstupy a výstupy z ovladačů se připojují do souborů s příponou.mdl jednotlivých úloh. V hlavním souboru projektu jsou soubory úloh uvedeny pouze odkazem v blocích typu QTASK nebo TASK připojovaných na výstupy QTask, Level0,..., Level3 exekutivy. Pro připojení vstupů a výstupů z ovladače DbDrv do řídicího systému REX lze použít bloky, znázorněné na obrázku 3.1. Obrázek 3.1: Příklady použití vstupně-výstupních bloků s ovladačem DbDrv Pokud je dodrženo pojmenování uvedené v kapitole a znázorněné na obr. 2.1, odkazujeme se na ovladač pomocí prefixu DB. Blok typu From sloužící pro připojení jednoho vstupu pak má parametr GotoTag roven DB <IN>, blok typu Goto používaný pro připojení jednoho výstupu má tento parametr nastaven na DB <OUT>, kde <IN> a <OUT> jsou řetězce odkazující na zkonfigurované vstupní nebo výstupní položky ovladače (viz dále). Obdobně je tomu u bloků vícenásobných vstupů a výstupů, kdy se odkazy na data poskytovaná a přijímaná ovladačem DbDrv zadávají jako jméno bloku. Vždy je tedy v řetězci prefix DB povinně následovaný dvěma znaky _ (podtržítko). Zbytek řetězce odkazujícího na vstupní nebo výstupní data je jméno položky definované v *.rio souboru (viz výše). 11
Ke každé položce je možné číst/zapisovat další pomocné signály. To se provede přidáním přípony do názvu. Možnosti jsou: Disable Pokud je True, pozastaví se čtení/zápis z/do databáze (pro danou skupinu). Trigger Náběžnou hranou se provede zápis. Age Udává počet sekund od posledního čtení/zápisu z/do databáze. AgeDb Udává počet sekund od posledního čtení/zápisu z/do databáze, narozdíl od předchozího případu se čas přečtení určuje z položky v databázi. Period Obsahuje/nastavuje parametr Period (tj. periodu SQL dotazů pro zvolenou skupinu v sekundách). Protože ovladač umožňuje pod jedním symbolickým jménem získávat několik hodnot nebo je zapisovat, lze s výhodou používat bloky čtyřnásobných, osminásobných a šestnáctinásobných vstupů a výstupů (INQUAD, OUTQUAD, INOCT, OUTOCT a INHEXD, OUTHEXD), viz obr. 3.1. V tomto případě je v názvu bloku odkaz na první požadovanou položku a v následujících signálech jsou následující položky dané skupiny. Výhodou takového užití je zvýšení rychlosti a částečně i přehlednosti algoritmů. Podrobný popis vícenásobných vstupů a výstupů lze nalézt v příručce [1]. 12
Kapitola 4 Poznámky k implementaci V této kapitole jsou soustředěny poznatky, které vznikly z dosavadních zkušeností. Některé položky v konfiguraci jsou často nesprávně pochopeny, ale podrobný popis výše by zhoršoval čitelnost textu. Proto jsou tyto postřehy uvedeny ve zvláštní kapitole. Parametr Items v sekci Archive je seznam čísel, přičemž lichá v pořadí mají význam od a sudá v pořadí význam do. Například při Items "2, 5, 10, 15" se exportují položky s číslem 2 až 5 a 10 až 15. Vždy musí být zadán sudý počet čísel, a to i v případě, že jsou exportovány položky s jediným ID. Většina databází nerozlišuje v SQL dotazech velká a malá písmena. Proto je ani ovladač DbDrv ve vlajkách nerozlišuje (odpovídají sloupcům v databázi). Přesto je lépe velikost písmen dodržovat, protože např. MySQL rozlišuje velikost písmen u názvů tabulek a databází. Všechny hodnoty zapisované nebo čtené z/do databáze jsou desetinná čísla (typ double). Sloupce v databázi mohou být definovány i jinak, protože do SQL dotazu se vše předává v textové formě. Zdá se to být dostatečně obecné, nicméně pokud je v názvu položky počáteční písmeno i tak je příslušná vlajka typu long, pro počáteční písmeno b je vlajka typu bool a pro počáteční písmeno s je příslušná vlajka typu string. Pro tuto speciální funkci musí být počáteční písmeno malé, takže pokud je Items "I1, r2, R2, i3", tak pouze i3 bude typu int, ostatní typu double a navíc R2 bude nedostupné, protože se nerozlišuje velikost písmen. Protože se do vlajek nedává identifikace skupiny (sekce igroup) musí být názvy položek jednoznačné v celé konfiguraci. Pokud by se nějaký název opakoval, bude dostupný jen první výskyt. 13
Kapitola 5 Co dělat při problémech Jako v případě všech problémů je nejprve vhodné zkontrolovat chybové a ladící výpisy (záložka System Log v RexView). V případě, že je problém s připojením k databázi nebo vykonáním SQL příkazu, bude v logu bližší popis problému. Nejčastější zdroje problémů jsou: Na cílovém zařízení není správně nainstalovaný ODBC ovladač pro použitou databázi nebo není správně nakonfigurován (v Linuxu soubory odbcinst.ini a odbc.ini). Špatný connection-string. Neexistují požadované tabulky v databázi nebo mají jinak pojmenované sloupce. Databáze může rozlišovat velká a malá písmena. Přestože DbDrv používá jen velmi jednoduchou formu SQL, rozdíly mezi databázemi existují. Zejména pokud uživatel vytváří SQL dotazy ručně, je potřeba důkladně prověřit jejich správný zápis. Duplicitní název položky (v parametru Items), který pak není dostupný ve vlajce. V případě, že daný ovladač DbDrv funguje v jednoduchých testovacích příkladech správně a při potřebné konfiguraci nefunguje, prosíme o zaslání informace o problému (nejlépe elektronickou cestou) na adresu dodavatele. Pro co nejrychlejší vyřešení problému by informace by měla obsahovat: Identifikační údaje Vaší instalace verzi, číslo sestavení (build), datum vytvoření instalace, licenční číslo. Stručný a výstižný popis problému. Co možná nejvíce zjednodušenou konfiguraci řídicího systému REX, ve které se problém ještě vyskytuje (ve formátu souboru s příponou.mdl). Konfigurační soubor ovladače DbDrv s příponou.rio. 14
Literatura [1] REX Controls s.r.o.. Funkční bloky systému REX Referenční příručka, 2013. Referenční číslo dokumentace: 5423 15