Ovladač DbDrv systému REX - uživatelská příručka

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.8
Plzeň
25.2.2016
Obsah
1 Ovladač DbDrv a systém REX
1.1 Úvod . . . . . . . . . . . . . . . . . . . . .
1.2 Požadavky na systém . . . . . . . . . . . .
1.3 Instalace ovladače na vývojovém počítači
1.4 Instalace ovladače na cílovém zařízení . .
1.4.1 Zařízení s Windows . . . . . . . . .
1.4.2 Zařízení s Windows CE . . . . . .
1.4.3 Zařízení s Linuxem . . . . . . . . .
1.4.4 ODBC ovladač . . . . . . . . . . .
.
.
.
.
.
.
.
.
2
2
2
3
3
3
3
3
4
2 Zařazení ovladače do projektu aplikace
2.1 Přidání ovladače DbDrv do projektu . . . . . . . . . . . . . . . . . . . . . .
2.2 Konfigurace ovladače . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2.2.1 Formát konfiguračního souboru . . . . . . . . . . . . . . . . . . . .
5
5
7
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
Vývojové nástroje systému REX
Cílové zařízení
Runtime jádro systému REX
Ovladač IO
jeden ze systémů: Windows XP, Vista, 7 nebo 8
verze pro operační systémy Windows
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
verze pro danou platformu
2
ODBC interface
verze pro konkrétní databázi (MySQL, PostgreSQL, 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
1.4.1
Instalace ovladače na cílovém zařízení
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 (DataSourceName), 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.
Tabulka se předpokládá seřazená podle sloupce Time (sekundárně podle
2
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: 5898
15