USB-CAN Bus Interface
Adapter Interface Function
Library User Instruction

PART ONE OVERVIEW

If the user just use USB-CAN bus interface adapter to go on CAN bus communication test, and then he can directly use the supplied USB-CAN Tool software for sending and receiving data of the test.
If the user intends to write software program for his own products. Please carefully read the following instructions and take reference from the sample code we provide:
⑴ C++Builder ⑵C# ⑶VC ⑷VB ⑸VB.NET ⑹Delphi ⑺LabVIEW ⑻ LabWindows/CVI ⑼Matlab ⑽QT ⑾Python/Python-can.
Develop library file ：ControlCAN.lib, ControlCAN.DLL
VC version function declaration file ：ControlCAN.h
VB version function declaration file: ControlCAN.bas
LabVIEW version library function package module ：ControlCAN.llb
Delphi version function declaration file: ControlCAN.pas

PART TWO COMPATIBLE FUNCTION LIBRARY AND DATA STRUCTURE

2.1. TYPE DEFINITION
2.1.1. Device Type

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.

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 2
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
System reserved.
can_Num
Represents the total number of CAN channel.
str_Serial_Num
This board card’s serial number.
str_hw_Type
Hardware type, such as “USBCAN V1.00” (Note: Includes string terminator ’\0’).
Reserved
System reserved.
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.

Member：
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.

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, Timing0 (BTR0) .
Timing1
SJA1000 Baud rate parameter, Timing1 (BTR1) .
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: CANparameter 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:

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.

2.2. FUNCTION DESCRIPTION
2.2.1. VCI_OpenDevice
This function is used to connect devices.
DWORD __stdcall VCI_OpenDevice(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
Retention parameters, fill in 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.

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.

2.2.3. VCI_InitCan
This function is used to initialize the specified CAN.
DWORD __stdcall VCI_InitCAN(DWORD DevType, DWORD DevIndex, DWORD CANIndex,
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:

packets can be accepted. These two registers are used to set the ID left- aligned, that is, the highest bit (Bit31) of the AccCode and AccMask is aligned with the highest bit of the ID value.
pInitConfig->AccMask| About ID alignment refer annexes: Annex I:
ID alignment details.
E.g. ：If you set the value of the AccCode as 0x24600000 (i.e. 0x123 is shifted to the left by 21 bits), AccMask value
is set to 0x00000000, and then only the packets with CAN message frame ID is 0x123 can be accepted (AccMask value of 0x00000000 indicates that all bits are relevant
| 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!
pInitConfig->Reserved| reserved
pInitConfig->Filter| Filtering mode settings please refer to the section of the filter mode table.
pInitConfig->Timing0| Baud rateT0 setting
pInitConfig->Timing1| Baud rateT1 setting
pInitConfig->Mode| Operating mode:
0-normal operation
1-Listen-only mode
2-spontaneous admission and sending test mode (this value is excluded from the ZLG function library)

Filter mode table:

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.

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.

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.
DWORD __stdcall VCI_ClearBuffer(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.

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
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.

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.

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.

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
To receive the first set pointer of the data frames.
Len
The array length of the data frame must be more than 2500 to return normal message.
Otherwise, the return length will be zero whether the message is received or not. the adapter set a 2000-frame buffer for every channel. Based on his own system and working environment, the user can choose an appropriate array length from 2500.
WaitTime Reserved.
Returns:
Return the number of frames that actually have been read, -1 indicates device errors.
E.g.

PART THREE OTHER FUNCTIONS AND DATA STRUCTURE DESCRIPTION

This chapter describes other data types and functions of the incompatible ZLG interface library contained in USB-CAN adapter interface library ControlCAN.dll. Please do
not call these functions if use a compatible ZLG model for secondary development so as not to affect compatibility.
3.1 FUNCTION DESCRIPTION
3.1.1. 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.

bRel = VCI_UsbDeviceReset(nDeviceType, Independence, 0);
3.1.2. VCI_FindUsbDevice2
When the same PC using multiple USB-CAN, user can use this function to find the current device.
DWORD __stdcall VCI_FindUsbDevice2(PVCI_BOARD_INFO pInfo);
Parameters:
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.

Part Four Interface Library Functions Using Process
In order to multiply device function, we provided additional functions( functions presented with a green background), these functions include: VCI_FindUsbDevice2 VCI_UsbDeviceReset. During the second development, these functions are not necessarily to be invoked. Even these functions are ignored, all USB-CAN adapter functions can be achieved.

www.waveshare.com
www.waveshare.com/wiki

Documents / Resources

| WAVESHARE USB-CAN Bus Inter face Adapter Interface Function Library [pdf] Instruction Manual
USB-CAN Bus Inter face Adapter Interface Function Library, USB-CAN, Bus Inter face Adapter Interface Function Library, Interface Function Library, Function Library
---|---

References

• Waveshare Electronics
• Waveshare Wiki

Read User Manual Online (PDF format)

Download This Manual (PDF format)

Download this manual  >>