4.USB-CAN Bus Interface Adapter Interface Function Library User Instruction
4.USB-CAN Bus Interface Adapter Interface Function Library User Instruction
Instruction VersionV2.02
Version Update Date2016.06.01
Contents
I
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
Page 1
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
Description
value
DEV_USBCAN2
USBCAN-2A/USBCAN-2C/CANalyst-II
2.1.2 VCI_BOARD_INFO
VCI_BOARD_INFO structure contains USB-CAN Series interface card device information.
The structure will be filled in VCI_ReadBoardInfo function.
typedef struct
_VCI_BOARD_INFO {
USHORT
hw_Version;
USHORT
fw_Version;
USHORT
dr_Version;
USHORT
in_Version;
USHORT
irq_Num;
BYTE
can_Num;
CHAR
str_Serial_Num[20];
CHAR
str_hw_Type[40];
USHORT
Reserved[4];
} VCI_BOARD_INFO, *PVCI_BOARD_INFO;
Member
hw_Version
Hardware version number, hexadecimal notation. E.g. 0x0100 represents V1.00.
fw_Version
Hardware version number, hexadecimal notation. E.g. 0x0100 represents V1.00.
dr_Version
Page 2
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
2.1.3 VCI_CAN_OBJ
In the functions VCI_Transmit and VCI_Receive, VCI_CAN_OBJ structure is used to
transmit CAN message frame.
typedef struct
_VCI_CAN_OBJ {
UINT
ID;
UINT
TimeStamp;
BYTE
TimeFlag;
BYTE
SendType;
BYTE
RemoteFlag;
BYTE
ExternFlag;
BYTE
DataLen;
BYTE
Data[8];
BYTE
Reserved[3];
}VCI_CAN_OBJ, *PVCI_CAN_OBJ;
Member
Page 3
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
ID
Message identifier. Direct ID format, right-aligned, please refer to: Annex One
ID Alignment Details.
TimeStamp
Receiving the stamp information of the time frame, start timing when the CAN controller is
initialized, the unit is 0.1ms.
TimeFlag
In terms of whether to use the time stamp, 1is the effective TimeStamp. TimeFlag and
TimeStamp are only meaningful when the frame is received .
SendType
Sending type. = 0 indicates Normal type, = 1 indicates Single Send.
RemoteFlag
Whether it is a remote flag. = 1 indicates remote flag, = 0 indicates data flag.
ExternFlag
Whether it is a extern flag. = 1 indicates extern flag, = 0 indicates standard flag.
DataLen
Data length(<=8)that is, the length of data.
Data
Packet data.
Reserved
System reserved.
2.1.4 VCI_INIT_CONFIG
VCI_INIT_CONFIG structure defines the initialization configuration of the CAN. The
structure will be filled in VCI_InitCan function.
typedef struct
_INIT_CONFIG {
DWORD
AccCode;
DWORD
AccMask;
DWORD
Reserved;
Page 4
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
UCHAR
Filter;
UCHAR
Timing0;
UCHAR
Timing1;
UCHAR
Mode;
filtering.
} VCI_INIT_CONFIG, *PVCI_INIT_CONFIG;
Member
AccCode
Receive filtered acceptance code.
AccMask
Receive filter mask.
Reserved
Reserved.
Filter
Filtering method, allowing setting range 0-3, refer to section 2.2.3 of the filter mode table
for details.
Timing0
SJA1000 Baud rate parameter, Timing0BTR0.
Timing1
SJA1000 Baud rate parameter, Timing1BTR1.
Mode
Operating mode, 0 = normal operation, 1 = Listen-only mode, 2 = spontaneous admission
and sending test mode.
Remarks:
About the filter settings please refer to: Annex II: CAN parameter setup instructions.
CAN Timing0 and Timing1 are used to set baud rate, these two parameters are only used at the
initialization stage.
Conventional Baud reference table:
Page 5
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
Timing0(BTR0)
Timing1(BTR1)
10k bps
0xBF
0xFF
20k bps
0x18
0x1C
40k bps
0x87
0xFF
50k bps
0x09
0x1C
80k bps
0x83
0xFF
100k bps
0x04
0x1C
125k bps
0x03
0x1C
200k bps
0x81
0xFA
250k bps
0x01
0x1C
400k bps
0x80
0xFA
500k bps
0x00
0x1C
666k bps
0x80
0xB6
800k bps
0x00
0x16
1000k bps
0x00
0x14
Note:
1. Users only need to follow SJA1000 (16MHz) to set the Baud rate parameter.
2. The adapter does not support temporarily Baud rate below 10K.
Page 6
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
DWORD dwRel;
dwRel = VCI_OpenDevice(nDeviceType, nDeviceInd, 0);
if(dwRel != 1)
{
MessageBox(_T("Fail to open the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);
return FALSE;
}
Page 7
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
2.2.2 VCI_CloseDevice
This function is used to close the connection.
DWORD __stdcall VCI_CloseDevice(DWORD DevType,DWORD DevIndex);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
Returns:
Return value = 1, which means that the operation is successful; = 0 indicates that the operation
failed; = -1 indicates that the device does not exist.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
DWORD dwRel;
dwRel = VCI_CloseDevice(nDeviceType, nDeviceInd);
if(dwRel != 1)
{
MessageBox(_T("Fail to close the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);
return FALSE;
}
2.2.3 VCI_InitCan
This function is used to initialize the specified CAN.
DWORD __stdcall VCI_InitCAN(DWORD DevType, DWORD DevIndex, DWORD CANIndex,
Page 8
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
PVCI_INIT_CONFIG pInitConfig);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
CANIndex
CAN channel index, such as when there is only one CAN channel, the index number is 0, if
there are two, the index number can be 0 or 1.
pInitConfig
Initialization parameter structure.
Parameter list of members:
Member
Functional Description
AccCode and AccMask can work together to
determine which packets can be accepted. These
pInitConfig->AccCode
pInitConfig->AccMask
Page 9
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
Member
Functional Description
bits). If the AccCode value is set to 0x24600000,
AccMask value is set to 0x600000 (0x03 is shifted
to the left by 21 bits), and then only the packets
with the CAN message frame ID is 0x120 ~ 0x123
can be accepted (AccMask value 0x600000
indicates that apart from bit0 ~ bit1 other bits
(bit2 ~ bit10) are relevant bit).
Note: This filter setting examples to the standard
frame, for example, high 11-bit is the valid bit; in
the case of the extended frame, and then the
valid ID is 29-bit. AccCode and AccMask set high
29-bit as the valid bit!
reserved
pInitConfig->Reserved
pInitConfig->Timing0
pInitConfig->Timing1
pInitConfig->Mode
Name
Description
Suitable to both standard and extended
frame!
Page 10
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
Value
Name
Description
frame will be removed by filtration directly!
Suitable to extended frame, and standard
frame
will
be
removed
by
filtration
directly!
Returns:
Return value = 1, which means that the operation is successful; = 0 indicates that the
operation failed; = -1 indicates that the device does not exist.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
DWORD dwRel;
VCI_INIT_CONFIG vic;
dwRel = VCI_OpenDevice(nDeviceType, nDeviceInd, 0);
if(dwRel != 1)
{
MessageBox(_T("Fail to open the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);
return FALSE;
}
vic .AccCode=0x80000008;
vic .AccMask=0xFFFFFFFF;
vic.Filter=1;
vic .Timing0=0x00;
vic .Timing1=0x14;
vic .Mode=0;
dwRel = VCI_InitCAN(nDeviceType, nDeviceInd, nCANInd, &vic);
if(dwRel !=1)
{
Page 11
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
VCI_CloseDevice(nDeviceType, nDeviceInd);
MessageBox(_T("fail to initialize the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);
return FALSE;
}
2.2.4 VCI_ReadBoardInfo
This function is used to read the adapter hardware information. Generally speaking, it can
be ignored.
DWORD __stdcall VCI_ReadBoardInfo(DWORD DevType,DWORD
DevIndex,PVCI_BOARD_INFO pInfo);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
pInfo
VCI_BOARD_INFO is used to store device information structure pointer.
Returns:
Return value = 1, which means that the operation is successful; = 0 indicates that the
operation failed; = -1 indicates that the device does not exist.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
int
nCANInd = 0;
VCI_BOARD_INFO vbi;
DWORD dwRel;
Page 12
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
2.2.5 VCI_GetReceiveNum
This function is used to specify the received but has not been read frames in the designated
receiving buffer.
DWORD __stdcall VCI_GetReceiveNum(DWORD DevType,DWORD DevIndex,DWORD CANIndex);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
CANIndex
CAN channel index.
Returns:
Return frames that have not been read yet.
E.g.
#include "ControlCan.h"
int ret=VCI_GetReceiveNum(2,0,0);
2.2.6 VCI_ClearBuffer
This function is used to clear the receive and send buffer of the designated channel specified by
USB-CAN adapter.
Page 13
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
int
nCANInd = 0;
/* zeroth channel */
DWORD dwRel;
bRel = VCI_ClearBuffer(nDeviceType, nDeviceInd, nCANInd);
2.2.7 VCI_StartCAN
This function is used to start the CAN controller and the internal interrupt reception function of
the adapter.
DWORD __stdcall VCI_StartCAN(DWORD DevType,DWORD DevIndex,DWORD CANIndex);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Page 14
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
CANIndex
CAN channel index.
Returns:
Return value = 1, which means that the operation is successful; = 0 indicates that the
operation failed; = -1 indicates that the device does not exist.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
int
nCANInd = 0;
/* zeroth channel */
DWORD dwRel;
VCI_INIT_CONFIG vic;
if(VCI_OpenDevice(nDeviceType, nDeviceInd, 0) != 1)
{
MessageBox(_T("Fail to open the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);
return FALSE;
}
if(VCI_InitCAN(nDeviceType, nDeviceInd, nCANInd, &vic) != 1)
{
VCI_CloseDevice(nDeviceType, nDeviceInd);
MessageBox(_T("Fail to initialize the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);
return FALSE;
}
if(VCI_StartCAN(nDeviceType, nDeviceInd, nCANInd) !=1)
{
VCI_CloseDevice(nDeviceType, nDeviceInd);
Page 15
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
2.2.8 VCI_ResetCAN
This function is used to reset the CAN controller.
DWORD __stdcall VCI_ResetCAN(DWORD DevType,DWORD DevIndex,DWORD CANIndex);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
CANIndex
CAN channel index.
Returns:
Return value = 1, which means that the operation is successful; = 0 indicates that the
operation failed; = -1 indicates that the device does not exist.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
int
nCANInd = 0;
DWORD dwRel;
bRel = VCI_ResetCAN(nDeviceType, nDeviceInd, nCANInd);
if(dwRel != 1)
{
Page 16
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
2.2.9 VCI_Transmit
This function is used to send CAN message frame.
DWORD __stdcall VCI_Transmit(DWORD DeviceType,DWORD DeviceInd,DWORD
CANInd,PVCI_CAN_OBJ pSend,DWORD Length);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
CANIndex
CAN channel index.
pSend
The first address of the data frame arrays that have to be sent.
Length
The number of the data frames that have to be sent, the maximum number is 1000, the
recommended value is 48 under high speed.
Returns:
Return the actual number of frames already sent, the return value = -1 indicates a device
error.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
Page 17
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
int
nCANInd = 0;
DWORD dwRel;
VCI_CAN_OBJ vco[48];
ZeroMemory(&vco, sizeof(VCI_CAN_OBJ)*48);
for(int i=0;i<48;i++)
{
vco[i].ID = i;
vco[i].RemoteFlag = 0;
vco[i].ExternFlag = 0;
vco[i].DataLen = 8;
for(int j = 0;j<8;j++)
vco.Data[j] = j;
}
dwRel = VCI_Transmit(nDeviceType, nDeviceInd, nCANInd, &vco,48);
2.2.10 VCI_Receive
This function is used to request reception.
DWORD __stdcall VCI_Receive(DWORD DevType, DWORD DevIndex, DWORD CANIndex,
PVCI_CAN_OBJ pReceive, ULONG Len, INT WaitTime);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
CANIndex
CAN channel index.
pReceive
Page 18
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
int
nCANInd = 0;
long lRel;
VCI_CAN_OBJ vco[100];
lRel = VCI_Receive(nDeviceType, nDeviceInd, nCANInd, &vco,100,1000);
if(lRel > 0)
{
/*data processing */
}
else if(lRel == -1)
{
Page 19
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
typedef struct
_VCI_BOARD_INFO1 {
USHORT
hw_Version;
USHORT
fw_Version;
USHORT
dr_Version;
USHORT
in_Version;
USHORT
irq_Num;
BYTE
can_Num;
BYTE
Reserved;
CHAR
str_Serial_Num[8];
CHAR
str_hw_Type[16];
USHORT
str_Usb_Serial [4][4];
} VCI_BOARD_INFO1, *PVCI_BOARD_INFO1;
Member
hw_Version
Hardware version number, hexadecimal notation. E.g. 0x0100 represents V1.00.
fw_Version
Hardware version number, hexadecimal notation. E.g. 0x0100 represents V1.00.
Page 20
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
dr_Version
Driver version number, hexadecimal notation. E.g. 0x0100 represents V1.00.
in_Version
Interface library version number, hexadecimal notation. E.g. 0x0100 represents V1.00.
irq_Num
Interrupt number used by the board, invalid parameter.
can_Num
Indicates the total number of CAN channel.
Reserved
System reserved.
str_Serial_Num
This board card's serial number.
str_hw_Type
Hardware type, such as USBCAN V1.00.
str_Usb_Serial
USB-CAN serial number, return four groups of four characters long ASCII string, each string
represents a device serial number, the same computer can support four USB-CAN device.
Email: [email protected]
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
Returns
1 communication available0 communication unavailable.
E.g.
#include "ControlCan.h"
int ret=VCI_ConnectDevice(2,0);
if(ret==1)
SetWindowText("normal communication");
else if(ret==0)
{
SetWindowText("dropped");
StopFlag=1;
for(int i=0;i<10;i++)
{
Sleep(1000);
VCI_BOARD_INFO vbi;
int temp=VCI_FindUsbDevice(&vbi);//Check whether the device is plugged into the
computer USB port.
if(temp==1)
SetWindowText("inside the computer, please start the device");//Re-open the device
with executable OpenDevice function.
else
SetWindowText("the device is not in the computer");
}
}
Page 22
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
3.3.2 VCI_UsbDeviceReset
Reset USB-CAN adapter, need to re-open the device after reset by using VCI_OpenDevice.
DWORD __stdcall VCI_UsbDeviceReset(DWORD DevType,DWORD DevIndex,DWORD Reserved);
Parameters:
DevType
Device type. See: Adapter device type definition.
DevIndex
Device Index, for example, when there is only one USB-CAN adapter, the index number is 0,
when there are multiple USB-CAN adapters, the index numbers in an ascending order starting
from 0.
Reserved
Reserved.
Returns:
Return value = 1, which means that the operation is successful; = 0 indicates that the
operation failed; = -1 indicates that the device does not exist.
E.g.
#include "ControlCan.h"
int
nDeviceType = 4;
/*USB-CAN2.0 */
int
nDeviceInd = 0;
/* zeroth device */
int
nCANInd = 0;
DWORD dwRel;
bRel = VCI_UsbDeviceReset(nDeviceType, nDeviceInd, 0);
3.3.3 VCI_FindUsbDevice
When the same PC using multiple USB-CAN, user can use this function to find the current
device.
DWORD __stdcall VCI_FindUsbDevice(PVCI_BOARD_INFO1 pInfo);
Parameters:
Page 23
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
pInfo
pInfo is used to store the parameters of the first data buffer address pointer.
Returns
Return the number of the USB-CAN adapter plugged into the computer.
E.g.
#include "ControlCan.h"
CString ProductSn[5];
VCI_BOARD_INFO1 vbi;
int num=VCI_FindUsbDevice(&vbi);
CString strtemp,str;
for(int i=0;i<num;i++)
{
str="";
for(int j=0;j<4;j++)
{
strtemp.Format("%c",pData->str_Usb_Serial[i][j]);
str+=strtemp;
}
ProductSn[i]="USBCAN-"+str;
}
Page 24
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]
second development, these functions are not necessarily to be invoked. Even these functions are
ignored, all USB-CAN adapter functions can be achieved.
VCI_FindUsbDevice
VCI_OpenDevice
VCI_InitCAN
VCI_UsbDeviceReset
VCI_ConnectDevice
VCI_GetReceiveNum
VCI_ClearBuffer
VCI_ReadBoardInfo
VCI_SetReference
VCI_GetReference2
VCI_SetReference2
VCI_StartCAN
VCI_ResetCAN
VCI_Transmit
VCI_Recive
VCI_CloseDevice
Page 25
Zhuhai Chuangxin Optoelectronics Technology Co., Ltd
Email: [email protected]