USB2CAN USB2CAN-VCP USB2CAN-FIFO API Reference Manual ver. 1.00 Updated in November 2013
1 1. INTRODUCTION 2 2. DOWNLOAD 2 2-1. Windows Desktop & Server 2 2-2. Max OS X, Linux, Windows CE 2 3. API REFERENCE 3 3-1. CAN_OpenVcp 3 3-2. CAN_OpenUsb 4 3-3. CAN_Close 5 3-4. CAN_IsOpened 5 3-5. CAN_ SetTimeout 6 3-6. CAN_CountRxQueue 7 3-7. CAN_ Purge 8 3-8. CAN_ Recv 9 3-9. CAN_Send 10 3-10. CAN_ GetConfig 12 3-11. CAN_ SetConfig 13 3-12. CAN_ SetTransferMode 14
2 1. Introduction 은 Host PC에서 USB 포트를이용하여 CAN bus에쉽게접근할수있게해주는 USB to CAN BUS 어댑터모듈입니다. 이문서는 USB2CAN 컨버터를엑세스하기위한 CAN Access DLL에서사용가능한기능들에대하여설명합니다. [ 그림 1-1] 2. Download 2-1. Windows Desktop & Server 엔티렉스의공식홈페이지 (ntrexgo.com) 에서 Library.zip 파일을다운로드받으시고압축을해제하면 CAN_Access.dll, CAN_Access.lib, CAN_Access.h, CAN_Test.exe 총 4개의파일이있는것을확인할수있습니다. 사용자는별도의개발모듈을사용하거나또는, CAN_Test.exe를통해서 USB2CAN을테스트할수있습니다. 2-2. Max OS X, Linux, Windows CE 이 API 는 Mac OS X, Linux, Windows CE 에서는사용할수없습니다.
3 3. API Reference 3-1. CAN_OpenVcp USB2CAN(UART) 컨버터를엑세스하기위해핸들을얻어옵니다. CAN_HANDLE CAN_OpenVcp(const char *comportname, long combaudrate) comportname : COM port 이름을나타내는문자열포인터 combaudrate : Baudrate 값을나타내는숫자 : 921600bps 로고정 성공한경우 USB2CAN 컨버터의핸들을리턴하고실패한경우 -1 을리턴합니다. Remarks 이함수는 FTDI FT232칩을기반으로만들어진 USB2CAN 컨버터를오픈하는데사용합니다. FT232 칩의 Windows용드라이버는가상시리얼포트 (VCP; Virtual COM Port) 드라이버를제공하는데, 가상시리얼포트를통해 COM 포트를엑세스하는것과동일하게 USB2CAN 컨버터를엑세스하게됩니다. Examples CAN_HANDLE hbus = CAN_OpenVcp ("\\\\.\\COM3", 921600); if (0 <= hbus) { CAN_SetTransferMode (hbus, 1); // Open 성공 else { // Open 실패, Error 처리
4 3-2. CAN_OpenUsb USB2CAN(FIFO) 컨버터를엑세스하기위해핸들을얻어옵니다. CAN_HANDLE CAN_OpenUsb(const char *serialnumber) serialnumber : USB2CAN 의 Serial Number 문자열포인터 성공한경우핸들을리턴하고실패한경우 -1 을리턴합니다. Remarks 이함수는 FTDI FT245칩을기반으로만들어진 USB2CAN 컨버터를오픈하는데사용합니다. FT245 칩이 USB로 PC에연결되었을때칩을구분하는 Serial Number가제공되는데, 이 Serial Number를통해 FIFO 포트를오픈하여 USB2CAN 컨버터를엑세스하게됩니다. Serial Number는 USB2CAN UI를실행하면다음과같이검색됩니다. Examples CAN_HANDLE hbus = CAN_OpenUsb ("NTWXHPOP"); if (0 <= hbus) { CAN_SetTransferMode (hbus, 1); // Open 성공 else { // Open 실패, Error 처리
5 3-3. CAN_Close USB2CAN 컨버터의열린핸들을닫아사용을종료합니다. int CAN_Close(CAN_HANDLE handle) handle : USB2CAN 컨버터의핸들 성공한경우 1 을리턴하고실패한경우 0 을리턴합니다. 여기서실패한경우란, 열려있 지않은핸들을닫으려고하는경우입니다. 3-4. CAN_IsOpened USB2CAN 핸들이열려있는지확인합니다. int CAN_IsOpened (CAN_HANDLE handle) handle : USB2CAN 컨버터의핸들 USB2CAN 컨버터의핸들이열려있는경우 1 을리턴하고열려있지않은경우 0 을리턴 합니다.
6 3-5. CAN_ SetTimeout 읽기와쓰기요청에대한타임아웃값을밀리초단위로설정합니다. int CAN_SetTimeout (CAN_HANDLE handle, unsigned long readtimeout, unsigned long writetimeout, unsigned long latencytimer) handle readtimeout writetimeout latencytimer : USB2CAN 컨버터의핸들 : 읽기요청에대한타임아웃값 ( 범위 : 1 ~ 1000 ms) : 쓰기요청에대한타임아웃값 ( 범위 : 1 ~ 1000 ms) : USB2CAN(UART) 인경우, Inter character timeout 값 ( 범위 : 1~1000 ms); USB2CAN(FIFO) 인경우, Latency timer 값 ( 범위 : 0 ~ 32 ms) 성공한경우 1 을리턴하고실패한경우 0 을리턴합니다. Remarks Inter character timeout은문자를받은후다음문자를받기까지얼마나기다릴것인지를밀리초단위로설정합니다. Latency timer는수신버퍼에문자가들어왔는지를체크하는타이머주기를설정합니다. 이값을줄이면수신버퍼를체크하는주기가짧아져 CPU의부하를증가시키고읽기요청에대한응답속도가빨라집니다. 반대로이값을늘이면 CPU의부하를줄이는대신읽기요청에대한응답속도가느려집니다.
7 Examples CAN_HANDLE hbus = CAN_OpenUsb ("NTWXHPOP"); if (0 <= hbus) { CAN_SetTransferMode (hbus, 1); CAN_SetTimeout (hbus, 33, 100, 0); // Open 성공 else { // Open 실패, Error 처리 3-6. CAN_CountRxQueue 수신버퍼에들어온문자수를셉니다. int CAN_CountRxQueue (CAN_HANDLE handle) handle : USB2CAN 컨버터의핸들 성공한경우수신버퍼의문자수를리턴하고실패한경우 0 을리턴합니다. 즉, 0 이리 턴된경우는함수호출이실패하였거나수신버퍼에들어온문자가없다는의미입니다.
8 Examples while (1) { if (0 < CAN_CountRxQueue (hbus)) { long ID; int length; char data[8]; int ext, rtr; if (CAN_Recv (hbus, &ID, &length, data, &ext, &rtr)) { // CAN message 읽기성공 else { Sleep (10); 3-7. CAN_ Purge 송신과수신버퍼의문자들을비웁니다. void CAN_Purge (CAN_HANDLE handle) handle : USB2CAN 컨버터의핸들
9 3-8. CAN_ Recv 수신버퍼의문자열로부터하나의 CAN 메시지를읽습니다. int CAN_Recv (CAN_HANDLE handle, long *ID, int *length, char data[8], int *Ext, int *RTR) handle : USB2CAN 컨버터의핸들 ID : CAN 메시지를송신한장치의 ID 를담는변수의포인터 ( 범위 : Standard message 인경우 0x000 ~ 0x7FF, Extended message 인경우 0x00000000 ~ 0x1FFFFFFF) length : CAN 메시지에서 data 의길이를담는변수의포인터 ( 범위 : 0 ~ 8 byte) data : CAN 메시지의데이터를저장하는배열의포인터 ( 크기 : 최대 8 byte) Ext : 수신된 CAN ID 가 Standard 혹은 Extended 인지를구분하는변수의포인터 : - 변수의값이 0 인경우 Standard CAN message, - 변수의값이 1 인경우 Extended CAN message RTR : 수신된 CAN 메시지의종류가 RTR 인지를구분하는변수의포인터 : - 변수의값이 0 인경우데이터전송, - 변수의값이 1 인경우 RTR 로데이터전송요청 * RTR(Remote Transmission Request) - 일반적으로데이터전송은센서와같은데이터를발생시키는노드에의해자동으로 Data Frame을전송되게됩니다. 어쨌거나, 데이터를수집하는노드가 Remote Frame을보냄으로데이터전송을요청하는것도가능합니다. CAN 메시지를읽기성공한경우 1 을리턴하고실패한경우 0 을리턴합니다.
10 Remarks CAN_Recv() 함수는수신버퍼에수신된문자열이존재하고, 이문자열로부터하나의 CAN 메시지를조립할수있다면즉각적으로리턴합니다. 하지만수신버퍼에문자가수신되지않았거나수신된문자열이하나의 CAN 메시지를조립하기에부족하다면 CAN_SetTimeout() 함수로설정된 readtimeout 시간동안완전한문자열이수신되기를기다립니다. Examples while (1) { long ID; int length; char data[8]; int ext, rtr; if (CAN_Recv (hbus, &ID, &length, data, &ext, &rtr)) { // CAN message 읽기성공 else { Sleep (10); 3-9. CAN_Send CAN 메시지를전송합니다. int CAN_Send (CAN_HANDLE handle, long ID, int length, char data[8], int Ext, int RTR)
11 Handle ID : USB2CAN 컨버터의핸들 : CAN 메시지를수신할장치의 ID ( 범위 : Standard message 인경우 0x000 ~ 0x7FF, Extended message 인경우 0x00000000 ~ 0x1FFFFFFF) length data : CAN 메시지에서 data 의길이를저장 ( 범위 : 0 ~ 8 byte) : CAN 메시지의데이터를저장하는배열의포인터 ( 크기 : 최대 8 byte) Ext : 전송할 CAN ID 가 Standard 혹은 Extended 인지를구분하는변수 : - 변수의값이 0 인경우 Standard CAN message, - 변수의값이 1 인경우 Extended CAN message RTR : 전송할 CAN 메시지의종류가 RTR 인지를구분하는변수 : - 변수의값이 0 인경우데이터전송, - 변수의값이 1 인경우 RTR 로데이터전송요청 CAN 메시지의전송을성공한경우 1 을리턴하고실패한경우 0 을리턴합니다. Examples char data[8] = {0x83, 0x11, 0x00, 0x03, ; // 최대 8 byte if (CAN_Send (hbus, 0x11, 4, data, 0, 0)) { // 전송성공
12 3-10. CAN_ GetConfig CAN 포트의설정을읽어옵니다. int CAN_GetConfig (CAN_HANDLE handle, long *bitrate, unsigned long *filterid, unsigned long *filtermask) handle bitrate filterid filtermask : USB2CAN 컨버터의핸들 : CAN 통신속도를저장하는변수의포인터 ( 단위 : kbps) : CAN Filter Identifier를담는변수의포인터 ( 범위 : 0x0 ~ 0x1FFFFFFF) : CAN Filter Mask를담는변수의포인터 ( 범위 : 0x0 ~ 0x1FFFFFFF) 성공한경우 1 을리턴하고실패한경우 0 을리턴합니다. Examples long bitrate; unsigned long filterid; unsigned long filtermask; if (CAN_GetConfig (hbus, &bitrate, &filterid, &filtermask)) { // 설정값읽기성공
13 3-11. CAN_ SetConfig CAN 포트의설정을 USB2CAN 컨버터로내려보냅니다. int CAN_SetConfig (CAN_HANDLE handle, long bitrate, unsigned long filter_id, unsigned long filter_mask) handle bitrate : USB2CAN 컨버터의핸들 : CAN 통신속도 ( 단위 : kbps). 설정가능한 CAN 통신속도는다음과같습니다 : 1000-1M Bps 800-800K Bps 500-500K Bps 250-250K Bps 125-125K Bps 50-50K Bps 25-25K Bps 10-10K Bps filterid filtermask : CAN Filter Identifier ( 범위 : 0x0 ~ 0x1FFFFFFF) : CAN Filter Mask ( 범위 : 0x0 ~ 0x1FFFFFFF) 성공한경우 1 을리턴하고실패한경우 0 을리턴합니다.
14 Remarks CAN_SetConfig() 함수가호출되면 USB2CAN 컨버터에서는다음과같은과정을거치게 됩니다 : 1 bitrate, filterid, filtermask 값으로 CAN port 를설정합니다. 2 bitrate, filterid, filtermask 값을 Flash memory 에저장합니다. 이함수에의해설정된값은 USB2CAN 컨버터가재시작되어도 Flash memory 에저장 된설정값에의해 CAN port 의설정이유지됩니다. Examples if (CAN_GetConfig (hbus, 1000, 0x0000, 0x0000)) { // 설정값읽기성공 3-12. CAN_ SetTransferMode 컨버터의 CAN port와 PC간패킷전송을활성화 / 비활성화하거나전송방식을결정합니다. 선택가능한전송방식은다음과같습니다. 0 CAN port와 PC간 CAN 메시지패킷만의송수신을금지합니다. 하지만설정이나명령과관련된패킷의송수신은가능합니다. 1 USB2CAN 컨버터와 PC간바이너리형식의패킷을송수신합니다. 이때, CAN 메시지및설정, 명령과관련된패킷의송수신형태는바이너리형식으로인코딩됩니다. 2 - USB2CAN 컨버터와 PC간텍스트형식의패킷을송수신합니다. 이때, CAN 메시지및설정, 명령과관련된패킷의송수신형태는텍스트형식으로인코딩됩니다. int CAN_SetTransferMode (CAN_HANDLE handle, int mode)
15 handle : USB2CAN 컨버터의핸들 mode : 패킷전송모드설정 : 0 Disable transmit 1 패킷을 Binary 형식으로인코딩하여송수신 2 - 패킷을 Text 형식으로인코딩하여송수신 성공한경우 1 을리턴하고실패한경우 0 을리턴합니다. Remarks CAN_Access.DLL 파일에서는 Text/Binary 형식의인코딩이내부적으로처리되기때문에사용자에게 Text와 Binary 형식의전송방식을구분하는것은중요하지않습니다. 그이유는사용자는 CAN_Recv(), CAN_Send() 함수에의해항상디코딩된 CAN message 형식으로읽고쓰기때문입니다. 또한, 전송모드의설정과상관없이, PC에서 USB2CAN 컨버터로 CAN 메시지를전송할때는항상바이너리형식으로인코딩된패킷을전송하게됩니다. 그렇기때문에, 사용자가텍스트모드로변경하더라도패킷을주고받는과정에서바이너리형식으로변경하게됩니다.