Knihovna podporující využití převodníku USB2CAN v Matlabu Matlab-To-Can Toolbox Pavel Pačes, 2010, Verze 1 1 Pavel Pačes, 2010, Verze 1
Obsah Předmluva... 2 Seznam změn... 2 Úvod... 3 Link a citace... 3 Požadavky... 3 Toolbox... 3 Seznam funkcí... 5 Příklady... 6 Inicializace spojení... 6 Komunikace se zařízením... 7 Uzavření spojení... 8 Chyby... 9 Problém s nahráním toolboxu... 9 Bibliografie... 10 Reference seznam projektů, kde byl tbx použitý... 11 Popis funkcí... 12 CANTBX interface general functions... 12 CAN adapters interface... 13 ETH adapters interface... 14 Serial adapters interface... 16 Miscellaneous functions... 18 Předmluva Tento dokument vznikl na základě požadavku číst data z vyvíjených zařízení s rozhraním CAN v prostředí Matlab. Výhodou propojení s prostředím Matlab je možnost využití dalších funkcí pro práci s daty a jejich prezentací. První verzi knihovny jsem vytvořil pro studenta pana Nedvěda, který s tímto SW získal výsledky pro jeho diplomovou práci. Seznam změn 5. 5. 2010 Malé změny přidané příklady použití toolboxu 1. 1. 2010 První verze dokumentu 2 Pavel Pačes, 2010, Verze 1
Úvod Toolboxy v Matlabu se tak skládají z množiny M souborů a dalších podpůrných programů, které umožňují rozšiřování funkcionality prostředí. Pro získávání dat je vhodný například Instrument Toolbox, který využívá knihovny VISA pro komunikaci s externími, laboratorními přístroji. Prostředí Matlab samo o sobě neposkytuje možnost využívat rozhraní sběrnice CANbus pro komunikaci s externími zařízeními. Ovšem jako většina vývojových prostředí umožňuje nahrávat externí DLL (Dynamic Link Libraries), které mohou rozšiřovat jeho funkce. Tento dokument popisuje aplikační rozhraní, toolbox, pro komunikaci se zařízením USB2CAN a umožňující přímou interakci prostředí Matlab s přístroji připojenými na sběrnici CAN. Link a citace Tento popis je možné stáhnout na adrese (1) a softwarové vybavení na (2). Požadavky Toolbox, který je dostupný ke stažení, neobsahuje následující knihovny: FTD2XX.dll, x2can_c_dll.dll, x2can_c_lib.lib a to z důvou nevyřešených licenčních podmínek. Tyto knihovny jsou potřeba pro plné zprovoznění převodníku USB2CAN a tohoto toolboxu v prostředí Matlab a je možné je zakoupit v rámci vývojového API dodávaného k převodníku jeho výrobcem. Tento toolbox byl úspěšně používán na Matlabu verze 7.1, 2008b, 2009b a 2010a. Toolbox O propojení vyvinutých zařízení a programů mezi sebou a prostředím Matlab je použitý Matlab Can Toolbox. Toolbox, vyvinutý v této práci, se skládá z několika knihoven uložených v adresáři lib, popisu jak zprovoznit nahrávání knihoven DLL na verzích Matlab 7.0 a nižších, který je umístěný v adresáři Workaround, a v základním adresáři je množství souborů, které uživateli zpřístupňují jednotlivé funkce knihovny. Jednotlivé funkce toolboxu je možné rozdělit na funkce používané pro inicializaci, měření a ovládání připojených přístrojů, a ukončení činnosti toolboxu. Tabulka 1 zobrazuje jednotlivé funkce implementované v toolboxu a jejich význam. Funkce jsou rozlišeny prefixy, které mají následující význam: CANTBX_ souvisí přímo s ovládáním komunikační DLL knihovny a integrací do prostředí Matlab, CAN_ umožňují ovládat převodník USB2CAN, SER_ funkce komunikují po spojení typu RS232 a ETH_ funkce využívají rozhraní ethernet. Nápověda k funkcím je realizována tak, jak je v Matlabu zvykem tj. pomocí příkazu help název-funkce. Z důvodů problémů s přesností synchronizace měření v distribuovaných systémech jsou v knihovně implementovány základní funkce založené na standardu časové synchronizace podle normy 3 Pavel Pačes, 2010, Verze 1
IEEE1588. Přístup k těmto funkcím je řešen pomocí funkcí, které jsou uvozeny prefixem SYNC. Rozhraní není ještě zcela implementováno a tak není uvedeno v tabulce 1. 4 Pavel Pačes, 2010, Verze 1
Seznam funkcí Inicializační funkce CANTBX_InstallToolbox CANTBX_InitTxb CAN_Open, ETH_Open, SER_Open Měřící a ovládací funkce CAN_Send, ETH_Send, SER_Send SER_SendByte, SER_ReceiveByte CAN_Receive, ETH_Receive, SER_Receive Funkce pro ukončení činnosti toolboxu CAN_Close, ETH_Close, SER_Close CAN_CloseAll, ETH_CloseAll, SER_CloseAll CANTBX_CloseAll Různé CANTBX_ComposeUint32 CANTBX_SplitUint32 CANTBX_UintToSingleFloat CST_ValvesSet Tabulka 1 Seznam funkcí toolboxu Registrace toolboxu v prostředí Matlab. Nahrání DLL knihovny do paměti. Inicializace komunikace s rozhraním CAN, ethernet nebo RS232. Funkce pro odesílání dat Funkce pro odeslání a příjem jednotlivých bytů přes rozhraní RS232. Funkce pro příjem dat Ukončení práce s rozhraním. Uzavření všech rozhraní jednoho druhu. Uzavření všech rozhraní a odstranění knihovny z paměti prostředí Matlab. Funkce umožňuje složení 32 bitové hodnoty ze čtyř bytových elementů. Rozložení 32 bitové hodnoty na čtyři bytové elementy. Převedení 32 bitového čísla na 32 bitový float podle normy IEEE 754. Funkce určená pro ovládání ventilů při testování přepínání přívodů vzduchu k senzorům. FG_ETH_GetParam Funkce určená pro komunikaci se simulátorem FlightGear. DLL Library Matlab Optional Part Add Msg. Message Generor Send Receive Send FiFo Receive FiFo Thread Send Receive CAN BUS, ETH optional IO, XML Load Message Parser Obrázek 1 Vnitřní implementace knihovny 5 Pavel Pačes, 2010, Verze 1
Příklady Následující kapitola v příkladech popisuje interakci s toolboxem. Inicializace spojení Pro práci s toolboxem je nutné tento toolbox přidat do seznamu cest viditelných v prostředí a obnovit cache prostředí Matlab. Inicializace probíhá při přepnutí do adresáře s toolboxem a vyvolání příkazu CANTBX_InstallToolbox. >> cd 'D:\Path\srcCantbx_v12\' >> CANTBX_InstallToolbox Adding path: D:\ Path\srcCantbx_v12 In case not to call CAN_InstallToolbox each time, save your path settings by: savepath command ans = >> 1 Na základě úspěšné instalace je nutné do prostředí Matlab nahrát DLL knihovnu pro komunikaci s převodníkem USB2CAN příkazem CANTBX_InitTxb, který vypíše seznam funkcí poskytovaných knihovnou a verzi jak toolboxu, tak i DLL knihovny. >> CANTBX_InitTxb Functions in library Usb2CAN_IO_DLL: ETH_Close GetDllVertion SER_SendDataByte TestStop U2C_SendData ETH_CloseAll SER_Close Sync_SyncClose U2C_Close ETH_GetData SER_CloseAll Sync_SyncFrame U2C_CloseAll ETH_Open SER_GetDataByte Sync_SyncIn U2C_GetDataTest ETH_SendData SER_Open TestStart U2C_Open CAN_InitTbx: Version 1.2 Usb2CAN_IO_DLL: Version 1.2 ans = >> 1 V případě kladné návratové hodnoty je možné v prostředí Matlab využívat všechny funkce a otevírat požadované zařízení, např. pomocí funkce CAN_Open. >> CAN_Open( 0, 100 ) ans = >> 1 6 Pavel Pačes, 2010, Verze 1
Komunikace se zařízením Komunikace s cílovým zařízení se sestává z funkcí pro odeslání a příjem dat. Následující funkce odešle CAN paket na první převodník USB2CAN. >> CAN_Send( 0, 50, 8, 0, 1, 2, 3, 4, 5, 6, 7 ) ans = >> 1 V případě požadavku na čtení dat by syntaxe příkazu vypadala: >> [iretval cnid cnlength cndata] = CAN_Receive( 0 ) iretval = 0 cnid = 0 cnlength = 0 cndata = >> 0 0 0 0 0 0 0 0 V uvedeném případě došlo při čtení dat k chybě, která je indikovaná v návratové hodnotě proměnné iretval. Následující příklad ilustruje úspěšné čtení hodnoty. >> [iretval cnid cnlength cndata] = CAN_Receive( 0 ) iretval = 1 cnid = 336 cnlength = 8 cndata = 7 Pavel Pačes, 2010, Verze 1
>> 1 0 17 0 0 0 0 0 Příklad komunikace s externím zařízením, kdy skript v prostředí Matlab odešle požadavek a pak čeká na odpověď, může probíhat například následovně: iretval = CAN_Send( iadapter, iparamid, 1, 0, 1, 2, 3, 4, 5, 6, 7 ); if iretval < 0 disp( ' GetParam problem'); fretval = single(-1.0); else [iretval cnid cnlength cndata] = CAN_Receive( iadapter ); while ( cnid ~= iparamid ) % wait for specific ID [iretval cnid cnlength cndata] = CAN_Receive( iadapter ); end end ivalue = CANTBX_ComposeUint32(cnData(5),cnData(6),cnData(7),cnData(8)); Uzavření spojení Poslední částí programu je vždy uzavírání použitých zdrojů. Toolbox v tomto případě nabízí funkce pro uzavírání pouze daného spojení (CAN_Close(0)), nebo pro ukončení činnosti všech rozhraní spravovaných DLL knihovnou (CANTBX_CloseAll). >> CANTBX_CloseAll ans = >> 1 Tato funkce uzavírá všechna otevřená spojení a zároveň vymaže knihovnu DLL z paměti prostředí Matlab. 8 Pavel Pačes, 2010, Verze 1
Chyby Problém s nahráním toolboxu V některých případech může dojít k problémům s nahráním DLL knihovny po vyvolání funkce CANTBX_InitTxb, viz: >> CANTBX_InitTxb??? Error using ==> loadlibrary at 244 There was an error loading the library "F:\srcCantbx_v12\lib\Usb2CAN_IO_DLL.dll" Error using ==> loaddefinedlibrary The specified module could not be found. Error in ==> loadlibrary at 244 loaddefinedlibrary(library,fcns,classname,structs,enums); Error in ==> CANTBX_InitTxb at 30 loadlibrary(... >> Tato chyba je způsobena chybějícími knihovnami MFC71D.DLL a DWMAPI.DLL, které je třeba nahrát do adresáře X:\Windows\System32. 9 Pavel Pačes, 2010, Verze 1
Bibliografie 1. Pačes, Pavel. Matlab-To-Can Toolbox - Popis. [Online] 2010. www.pacespavel.net/download/index.php?soubor=pacescantbx. 2.. Matlab-To-Can Toolbox - Program. [Online] 2010. www.pacespavel.net/download/index.php?soubor=pacescantbxsw. 3.. Automatizované měření - příklady. *Online+ 2009. www.pacespavel.net/download/index.php?soubor=pacesjaknaautomatizovanemerenisw. 4. Microsoft. Microsoft Developer Network Academic Alliance. [Online] http://www.microsoft.com/cze/education/licence/msdn_academic_alliance/default.mspx. 5.. Microsoft Visual Studio. [Online] http://www.microsoft.com/cze/msdn/produkty/vstudio/default.mspx. 6. Pačes, Pavel. Krátké doporučení pro tvorbu akademických prací: Automatizované měření. *Online+ 1. 1 2010. [Citace: 31. 5 2010.] www.pacespavel.net/download/index.php?soubor=pacesjaknaautomatizovanemereni. 10 Pavel Pačes, 2010, Verze 1
Reference seznam projektů, kde byl tbx použitý Nedvěd, J.: Aerometrický systém pro malá letadla, diplomová práce, vedoucí Pavel Pačes, 2007 Nekvasil, V.: Algoritmus navedení letounu na bezpečné přiblížení k zemi při mimořádných událostech, diplomová práce, vedoucí Pavel Pačes, 2010 Veselý, M.: Využití prostředí Simulink/Matlab pro generování aplikací vestavných systémů, diplomová práce, vedoucí Pavel Pačes, 2010 Vaško, O.: Měření úhlu náběhu u malých letadel, diplomová práce, vedoucí doc. Ing. Karel Draxler, CSc., 2010 Řezníček, P.: Integrovaný systém měření výšky, diplomová práce, vedoucí doc. Ing. Karel Draxler, CSc., 2010 11 Pavel Pačes, 2010, Verze 1
Popis funkcí CANTBX interface general functions CANTBX_InstallToolbox CAN_InstallToolbox makes all necessary steps to do the CanTbx available from Matlab environment. run $matlabroot\toolbox\cantbx\cantbx_installtoolbox.m run CAN_InstallToolbox.m No input necessary. It returns 1 in case of success. CANTBX_InitTxb CANTBX_InitTxb inits data and loads necessary library. CAN_InitTxb RV = CAN_InitTxb No input necessary. CANTBX_CloseAll CANTBX_CloseAll closes all interfaces and unloads the DLL library CANTBX_CloseAll() RV = CANTBX_CloseAll No inputs required. CANTBX_ComposeUint32 CANTBX_ComposeUint32 compose four bytes into one UINT32 integer. CANTBX_ComposeUint32 ( btmsb, bt2, bt3, btlsb ) RV = CANTBX_ComposeUint32( 1, 2, 3, 4 ) dec2hex( RV ) ans = 1020304 btmsb, bt2, bt3, btlsb byte values in range from 0 to 255. 12 Pavel Pačes, 2010, Verze 1
Function returns composed value. CAN adapters interface CAN_Open CAN_Open opens a USB to CAN converter at given position with given speed. CAN_Open( iadapter, ispeed ) CAN_Open( 0, 100 ) iadapter refers to a USB2CAN device - number from 0 to max. ispeed CAN bus speed 10 = 10k, 100 = 100k, 250, 500, 1000. Function returns 1 in case of successful open. CAN_Send CAN_Send sends message imsgid, through iadapter, with length ilength. CAN_Send( iadapter, imsgid, ilength, idata0, idata1, idata2, idata3, idata4, idata5, idata6, idata7 ) CAN_Send( 0, 50, 8, 0, 1, 2, 3, 4, 5, 6, 7 ) iadapter refers to an USB2CAN device - number from 0 to max. imsgid CAN message ID ilength CAN message length idata[x] data fields, range from 0 to 255. Function returns 1 in case of successful operation. CAN_Receive CAN_Receive receives data from a USB to CAN converter. [iretval cnid cnlength cndata] = CAN_Receive( iadapter ) RV = CAN_Receive(0) iadapter refers to an USB2CAN device - number from 0 to max. Returns iretval is 1 in case of success. cnid is ID of the received CAN bus frame. cnlength is lenght of received data, number from 0 to 8. cndata is array of received data - length of valid items is from 0 to cnlength. 13 Pavel Pačes, 2010, Verze 1
CAN_Close CAN_Close closes adapter iadapter. CAN_Close( iadapter ) CAN_Close( 0 ) iadapter refers to an USB2CAN device - number from 0 to max. Returns CAN_CloseAll CAN_CloseAll closes all CAN interfaces. CAN_CloseAll RV = CAN_CloseAll No inputs required. ETH adapters interface ETH_Open ETH_Open opens connection through a UDP. ETH_Open( iadapter, straddress, isendport, ilistenport ) iretval = ETH_Open( 0, '127.0.0.1', 6000, 6001 ) iadapter refers to an USB2CAN device - number from 0 to max. straddress address string in form '127.0.0.1'. isendport send port, integer from 0 to 65535. ilistenport receive port, integer from 0 to 65535. ETH_Receive ETH_Receive receives data from the ethernet connection. [iretval cnid cnlength cndata] = ETH_Receive( iadapter ) [iretval cnid cnlength cndata] = ETH_Receive( 0 ) 14 Pavel Pačes, 2010, Verze 1
iadapter refers to an ETH device - number from 0 to max. Returns iretval is 1 in case of success. cnid is ID of the received CAN bus frame. cnlength is lenght of received data - number from 0 to 8. cndata is array of received data - length from 0 to cnlength. ETH_Send ETH_Send sends data through the ethernet connection. ETH_Send( iadapter, imsgid, ilength, idata0, idata1, idata2, idata3, idata4, idata5, idata6, idata7 ) RV = ETH_Send( 0, 122, 1, 0, 1, 2, 3, 4, 5, 6, 7 ) iadapter refers to an USB2CAN device - number from 0 to max. imsgid CAN message ID ilength CAN message length idata0, idata1, idata2, idata3, idata4, idata5, idata6, idata7 data fields, range from 0 to 255. ETH_Close ETH_Close closes adapter iadapter. ETH_Close( iadapter ) RV = ETH_Close( 0 ) iadapter refers to an ETH device - number from 0 to max. ETH_CloseAll ETH_CloseAll closes all ethernet adapters. ETH_CloseAll RV = ETH_CloseAll No inputs required. 15 Pavel Pačes, 2010, Verze 1
Serial adapters interface SER_Open SER_Open opens a USB to CAN converter at given position with given speed. SER_Open( iadapter, icomid, ibaudrate ) SER_Open( 0, 26, 9600 ) iadapter refers to a serial device - number from 0 to max. icomid refers to a serial interface at a computer (1 means COM1, etc.). ibaudrate refers to the baudrate (9600 means baudrate 9600) Function returns 1 in case of successful open. SER_Close SER_Close closes adapter iadapter. SER_Close( iadapter ) RV = SER_Close( 0 ) iadapter refers to a serial device - number from 0 to max. SER_CloseAll SER_CloseAll closes all serial adapters. SER_CloseAll RV = SER_CloseAll No inputs required. SER_Send SER_Send sends message imsgid, through iadapter, with length ilength. SER_Send( iadapter, imsgid, ilength, idata0, idata1, idata2, idata3, idata4, idata5, idata6, idata7 ) SER_Send( 0, 50, 8, 0, 1, 2, 3, 4, 5, 6, 7 ) 16 Pavel Pačes, 2010, Verze 1
iadapter refers to a serial device - number from 0 to max. imsgid CAN message ID ilength CAN message length idata0, idata1, idata2, idata3, idata4, idata5, idata6, idata7 data fields, range from 0 to 255. Function returns 1 in case of successful operation. SER_Receive SER_Receive receives data from a serial device. [iretval cnid cnlength cndata] = SER_Receive( iadapter ) RV = SER_Receive iadapter refers to a serial device - number from 0 to max. Returns iretval is 1 in case of success. cnid is ID of the received CAN bus frame. cnlength is lenght of received data, number from 0 to 8. cndata is array of received data - length of valid items is from 0 to cnlength. SER_SendByte SER_SendByte sends a byte through a serial interface. SER_SendByte( iadapter, ibyte ) SER_SendByte( 0, 20 ) ans = 1 iadapter refers to a serial device - number from 0 to max. ibyte a byte to be sent. Function returns 1 in case of successful operation. SER_ReceiveByte SER_ReceiveByte receives data from a serial device. [iretval ibyte] = SER_ReceiveByte( iadapter ) RV = SER_ReceiveByte iadapter refers to a serial device - number from 0 to max. Returns iretval is 1 in case of success. ibyte contains received byte. 17 Pavel Pačes, 2010, Verze 1
Miscellaneous functions FG_ETH_GetParam FG_ETH_GetParam Gets param (iparamid) from FG server connected to iadapter. Require opened ETH interface. See ETH_Open. fretval = FG_ETH_GetParam( iadapter, iparamid ) FG_ETH_GetParam( 0, 53 ) >Param 53, 359.169037 ans = 359.1690% iadapter Refers to an USB2CAN device - number from 0 to max. iparamid Parameter ID. Function returns -1.0 in case of problems. 18 Pavel Pačes, 2010, Verze 1