Вы находитесь на странице: 1из 43

Shenzhen Fangxing Liutong Industrial Co., Ltd.

Interface Function Library User Instruction

USB-CAN Bus Interface Adapter

Interface Function Library

User Instruction

Instruction Version:V1.80
Version Update Date:2013.10.01

1 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

Contents
Part One Overview .................................................................................................................... 4

Part Two Compatible ZLG Function Library and Data Structure ............................................. 5
2.1 Type Definition ............................................................................................................. 5

2.1.1 Device Type .............................................................................................................. 5

2.1.2 VCI_BOARD_INFO ..................................................................................................... 5

2.1.3 VCI_CAN_OBJ............................................................................................................ 6

2.1.4 VCI_CAN_STATUS ..................................................................................................... 7

2.1.5 VCI_ERR_INFO .......................................................................................................... 9

2.1.6 VCI_INIT_CONFIG ..................................................................................................... 9


2.2 Function description ............................................................................................... 12

2.2.1 VCI_OpenDevice ....................................................................................................... 12

2.2.2 VCI_CloseDevice ..................................................................................................... 13

2.2.3 VCI_InitCan ............................................................................................................. 13

2.2.4 VCI_ReadBoardInfo ................................................................................................ 17

2.2.5 VCI_ReadErrInfo ..................................................................................................... 18

2.2.6 VCI_ReadCanStatus ................................................................................................ 19

2.2.7 VCI_GetReference .................................................................................................. 20

2.2.8 VCI_SetReference ................................................................................................... 21

2.2.9 VCI_GetReceiveNum .............................................................................................. 22

2.2.10 VCI_ClearBuffer .................................................................................................... 23

2.2.11 VCI_StartCAN ........................................................................................................ 24

2.2.12 VCI_ResetCAN....................................................................................................... 25

2.2.13 VCI_Transmit ........................................................................................................ 26

2.2.14 VCI_Receive .......................................................................................................... 28

Part Three Other Functions and Data Structure Description ................................................... 30


3.1 Type definition ....................................................................................................... 30

3.1.1 VCI_BOARD_INFO1 ................................................................................................. 30

3.1.2 VCI_REF_NORMAL .................................................................................................. 31

3.1.3 VCI_BAUD_TYPE ..................................................................................................... 33

2 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

3.1.4 VCI_REF_STRUCT .................................................................................................... 34


3.3 Function description ............................................................................................. 34

3.3.1 VCI_GetReference2 ................................................................................................ 34

3.3.2 VCI_SetReference2 ................................................................................................. 36

3.3.3 VCI_ResumeConfig ................................................................................................. 38

3.3.4 VCI_ConnectDevice ................................................................................................ 39

3.3.5 VCI_UsbDeviceReset............................................................................................... 40

3.3.6 VCI_FindUsbDevice................................................................................................. 41

Part Four Interface Library Functions Using Process .......................................................... 43

3 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. 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 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:

①LabVIEW②C++Builder③VC④VB⑤Delphi.
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

4 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

Part Two Compatible ZLG Function Library and Data Structure

2.1 Type Definition

2.1.1 Device Type

Type
Type Definition Description
value

DEV_USBCAN 3 USB-CAN-1x Series Adapter,x represents A,B,C

DEV_USBCAN2 4 USB-CAN-2x Series Adapter ,x represents A,B,C

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.
5 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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

Represents the total number of CAN channel.

str_Serial_Num

This board card's serial number, (Note: Includes string terminator ’\0’)

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.

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;

6 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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, 1:00 is the effective TimeStamp. TimeFlag and

TimeStamp are only meaningful when the frame is received .

SendType

Sending type.

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.

Note: setting the SendType as invalid spontaneous admission and sending , spontaneous admission

and sending mode should be set in the VCI_InitCan.

2.1.4 VCI_CAN_STATUS

VCI_CAN_STATUS structure includes CAN Controller status information. The structure will be filled

in the VCI_ReadCanStatus function.

typedef struct _VCI_CAN_STATUS {

7 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

UCHAR ErrInterrupt;

UCHAR regMode;

UCHAR regStatus;

UCHAR regALCapture;

UCHAR regECCapture;

UCHAR regEWLimit;

UCHAR regRECounter;

UCHAR regTECounter;

DWORD Reserved;

} VCI_CAN_STATUS, *PVCI_CAN_STATUS;
Member:

ErrInterrupt

CAN receive error interrupt recording, the read operation will be cleared.

regMode

CAN controller mode register, temporarily unused, reserved.

regStatus

CAN controller mode register, temporarily unused, reserved.

regALCapture

CAN controller arbitration lost registers, temporarily unused, reserved.

regECCapture

CAN controller error register, temporarily unused, reserved.

regEWLimit

CAN controller error warning and limit register, temporarily unused, reserved.

regRECounter

CAN controller error receiving register, temporarily unused, reserved.

regTECounter

CAN controller error sending register, temporarily unused, reserved.

Reserved

System reserved.

8 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

2.1.5 VCI_ERR_INFO

VCI_ERR_INFO structure is used to load the error messages generated when run VCI

library . The structure will be filled in VCI_ReadErrInfo function.

typedef struct _ERR_INFO{

DWORD ErrCode;

BYTE Passive_ErrData[3];

BYTE ArLost_ErrData;

} VCI_ERR_INFO,*PVCI_ERR_INFO;
Member:

ErrCode

Error code.

Passive_ErrData

When there is a passive error generated when an error is expressed as a passive error identification

data.

ArLost_ErrData

When the resulting error contains arbitration lost error, and then the error is expressed as arbitration

error identification data.

2.1.6 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;

UCHAR Filter; //0,1 receives all frames. 2 standard frame filtering, 3 is an extended frame

filtering.

UCHAR Timing0; //SJA1000 Baud rate parameter,Timing0(BTR0)


9 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

UCHAR Timing1; //SJA1000 Baud rate parameter,Timing1(BTR1)

UCHAR Mode; //mode,0 represents normal mode, 1represents listening-only mode, 2

represents self-test mode.

} 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, 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: 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:

CAN Baud rate Timing0(BTR0) Timing1(BTR1)

10k bps 0x9F 0xFF

20k bps 0x18 0x1C

10 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

CAN Baud rate Timing0(BTR0) Timing1(BTR1)

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.Due to the CAN controller crystal frequency varies, the oscillator frequency of the CAN controller
applied by this adapter is 32MHz, the frequency of the compatible (SJA1000) CAN controller is 16MHz. Thus
in order to ensure the compatibility of the Baud rate parameter, internally, this adapter set the prescale BRP
parameter in Baud rate parameter by taking two processing to achieve the same effect. So users only need to
follow SJA1000 (16MHz) to set the Baud rate parameter.
2. In SJA1000 (16MHz) parameter, prescale BRP value must be less than or equal to 32. Therefore,
we do some correction work on 10K Baud rate parameters. The adapter does not support temporarily
Baud rate below 10K.

11 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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.

E.g.:

#include "ControlCan.h"

int 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;

12 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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,

13 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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
two registers are used to set the ID left-aligned,
that is, the highest bit (Bit31) of the AccCode and
pInitConfig->AccCode
AccMask is aligned with the highest bit of the ID
value.
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

pInitConfig->AccMask only the packets with CAN message frame ID is


0x123 can be accepted (AccMask value of
0x00000000 indicates that all bits are relevantbits).
If the AccCode value is set to 0x24600000, AccMask

14 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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
Filtering mode settings please refer to the
pInitConfig->Filter
section of the filter mode table.
pInitConfig->Timing0 Baud rateT0 setting
pInitConfig->Timing1 Baud rateT1 setting
Operating mode:

0-normal operation

1-Listen-only mode
pInitConfig->Mode
2-spontaneous admission and sending test mode

(this value is excluded from the ZLG function

library)

Filter mode table:

Value Name Description

Suitable to both standard and extended


1 Receive all types
frame!

2 Only receive standard frame Suitable to standard frame, and extended

15 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

Value Name Description

frame will be removed by filtration directly!

Suitable to extended frame, and standard

3 Only receive extended frame 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)

{
16 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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;

17 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

bRel = VCI_ReadBoardInfo(nDeviceType, nDeviceInd, nCANInd, &vbi);

if(dwRel != 1)

MessageBox(_T("Fail to obtain device information!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

2.2.5 VCI_ReadErrInfo

This function is used to get the last error message.

DWORD __stdcall VCI_ReadErrInfo(DWORD DevType,DWORD DevIndex,DWORD

CANIndex,PVCI_ERR_INFO pErrInfo);

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.

Remarks:

ReadErrInfo function is set to take care of the compatibility of the ZLG USBCAN card for some

users. Due to the USB_CAN adapter provided by us has different structure with that of the ZLG USBCAN

card, so the existence of these two functions is to ensure using our USB_CAN adapter based on

relevant ZLG debugging software or on the basis of the ZLG, there will be no memory errors or crashes and

so on. Return value is invalid.

18 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

E.g.:

#include "ControlCan.h"

int nDeviceType = 4; /*USB-CAN2.0 */

int nDeviceInd = 0; /* zeroth device */

int nCANInd = 0;

VCI_ERR_INFO vei;

DWORD dwRel;

bRel = VCI_ReadErrInfo(nDeviceType, nDeviceInd, nCANInd, &vei);

if(dwRel != 1)

MessageBox(_T("Fail to read!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

2.2.6 VCI_ReadCanStatus

This function is used to read the current state of the CAN interface. Generally speaking, it can be ignored.

DWORD __stdcall VCI_ReadCANStatus(DWORD DevType,DWORD DevIndex,DWORD

CANIndex,PVCI_CAN_STATUS pCANStatus);

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.

pCANStatus

pCANStatus is used to store the state of VCI_CAN_STATUS structure pointer.

19 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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.

Remarks:

ReadCanStatus function is set to take care of the compatibility of the ZLG USBCAN card for some users.

Due to the USB_CAN adapter provided by us has different structure with that of the ZLG USBCAN card, so

the existence of these two functions is to ensure using our USB_CAN adapter based on relevant ZLG

debugging software or on the basis of the ZLG, there will be no memory errors or crashes and so on. Return

value is invalid.

E.g.:

#include "ControlCan.h"

int nDeviceType = 4; /*USB-CAN2.0 */

int nDeviceInd = 0; /* zeroth device */

int nCANInd = 0;

VCI_CAN_STATUS vcs;

DWORD dwRel;

bRel = VCI_ReadCANStatus(nDeviceType, nDeviceInd, nCANInd, &vcs);

if(dwRel != 1)

MessageBox(_T("Fail to obtain status!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

2.2.7 VCI_GetReference

This function can help users get the adapter internal parameters.

DWORD __stdcall VCI_GetReference(DWORD DevType,DWORD DevIndex,DWORD


CANIndex,DWORD Reserved,PVOID pData);

20 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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.

Reserved

Reserved, you can fill in 0.

pData

pData is used to store the parameters of the first data buffer address pointer and return

8-byte one-dimensional arrays.

Returns:

Return value = 1, which means that the operation is successful; = 0 indicates that the operation failed.

Remarks:

GetReference and SetReference functions are set to take care of the compatibility of the ZLG

USBCAN card for some users. Due to the USB_CAN adapter provided by us has different structure with that

of the ZLG USBCAN card, so the existence of these two functions is to ensure using our USB_CAN adapter

based on relevant ZLG debugging software or on the basis of the ZLG, there will be no memory errors or

crashes and so on. Return value is invalid.

2.2.8 VCI_SetReference

This function is used to set the related parameters for the adapter, compatible with ZLG (ZLG) USB_CAN

corresponding interface functions.

DWORD __stdcall VCI_SetReference(DWORD DevType,DWORD DevIndex,DWORD

CANIndex,DWORD RefType,PVOID pData);

21 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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.

RefType

Parameter type.

pData

pData is used to store the parameters of the first data buffer address pointer and return

8-byte one-dimensional arrays.

Returns:

Return value = 1, which means that the operation is successful; = 0 indicates that the operation

failed.

Remarks:

GetReference and SetReference functions are set to take care of the compatibility of the

ZLG USBCAN card for some users. Due to the USB_CAN adapter provided by us has different

structure with that of the ZLG USBCAN card, so the existence of these two functions is to ensure

using our USB_CAN adapter based on relevant ZLG debugging software or on the basis of the ZLG,

there will be no memory errors or crashes and so on. Return value is invalid.

2.2.9 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

22 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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

23 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

E.g.:

#include "ControlCan.h"

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

E.g.:

#include "ControlCan.h"

int nDeviceType = 4; /*USB-CAN2.0 */

int nDeviceInd = 0; /* zeroth device */

int nCANInd = 0; /* zeroth channel */

24 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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);

MessageBox(_T("Fail to start the device!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

2.2.12 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,

25 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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)

MessageBox(_T("Fail to reset!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

2.2.13 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,
26 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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 */

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;

27 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

dwRel = VCI_Transmit(nDeviceType, nDeviceInd, nCANInd, &vco,48);

2.2.14 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 48 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 48-2000.

WaitTime

Wait timeout, in milliseconds, generally take 10 ~ 50ms, -1 means unlimited, infinite wait.

Returns:

Return the number of frames that actually have been read, -1 indicates device errors.

E.g.:

#include "ControlCan.h"

int nDeviceType = 4; /*USB-CAN2.0 */

28 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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)

… /* receive error treatment */

29 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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 Type definition

3.1.1 VCI_BOARD_INFO1

VCI_BOARD_INFO1 structure contains series of USB-CAN interface card and device information on your

computer while inserting the first four series of USB-CAN interface card serial number information. The

structure will be filled in VCI_FindUsbDevice function.

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.

30 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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.

3.1.2 VCI_REF_NORMAL
VCI_REF_NORMAL structure defines a routine parameter type. When RefType = 15, the tructure will

be filled in the VCI_SetReference2 function.

typedef struct _REF_NORMAL{

BYTE Mode; //operation mode

BYTE Filter; //filtering method

DWORD ACR; //receive filtering acceptance code

DWORD AMR; //receive filtering mask code

UCHAR kCanBaud; //Baud rate index number,Unused reserved

UCHAR Timing0; //SJA1000Baud rate parameter,Timing0(BTR0)

UCHAR Timing1; //SJA1000Baud rate parameter,Timing1(BTR1)

31 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

BYTE CANRX_EN; //Unused, reserved

BYTE UARTBAUD; //Unused, reserved

}VCI_REF_NORMAL,*PVCI_REF_NORMAL;
Member:

Mode
Operation mode,0=normal operation,1=listen-only mode,2=spontaneous admission and sending test

mode.

Filter

Filtering methods, allowing set range 0-3, refer to the filter mode table of section 2.2.3 for details.

AccCode

Receive filtering acceptance code.

AccMask

Receive filtering mask code.

kCanBaud

Baud rate index number, unused reserved.

Timing0
SJA1000Baud rate parameter,Timing0(BTR0).

Timing1
SJA1000Baud rate parameter,Timing1(BTR1).

CANRX_EN

Reserved, unused.

UARTBAUD

Reserved, unused.
Remarks:

For conventional Baud rate, please refer to the conventional Baud rate reference table in section 2.1.6.

32 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

3.1.3 VCI_BAUD_TYPE

VCI_BAUD_TYPE structure defines a custom Baud rate parameter structure. When the

RefType = 16, the structure will be filled in the VCI_SetReference2 function.

typedef struct _BAUD_TYPE{

DWORD Baud; //store Baud rate actual value

BYTE SJW; //Synchronized jump width, value 1-4

BYTE BRP; //Pre-scale value, value 1-64

BYTE SAM; //Sampling points, 0 = sample once, 1 = sample three times

BYTE PHSEG2_SEL; //Phase Segment 2 select bit value 0 = is determined by Phase

Segment 1 time, 1 = programmable

BYTE PRSEG; //Prop-seg,value 1-8

BYTE PHSEG1; //Phase-seg1,value1-8

BYTE PHSEG2; //Phase-seg 2,value1-8

}VCI_BAUD_TYPE,*PVCI_BAUD_TYPE;
Member:

Baud
Baud rate actual value,unit bps.

SJW

Synchronized jump width, value 1-4.

BRP

Pre-scale value, value 1-64.

SAM

Sampling points, 0 = sample once, 1 = sample three times.

PHSEG2_SEL

Phase Segment 2 select bit value 0 = is determined by Phase Segment 1 time, 1 =

programmable.

PRSEG
Prop-seg,value 1-8.

PHSEG1
33 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

Phase-seg1,value1-8.

PHSEG2
Phase-seg 2,value1-8.

Remarks:

About Custom Baud rate settings, please refer to Section 2.3.2 VCI_SetReference2.

3.1.4 VCI_REF_STRUCT

VCI_REF_STRUCT structure defines the parameter type structure. Structure returned in the pointer of

the VCI_GetReference2function.

typedef struct _REF_STRUCT{

VCI_REF_NORMAL RefNormal;

BYTE Reserved;

VCI_BAUD_TYPE BaudType;

}VCI_REF_STRUCT,*PVCI_REF_STRCUT;
Member:

RefNormal

Conventional parameter type.

Reserved

Reserved, unused.

BaudType

Custom Baud rate parameter type.

3.3 Function description

3.3.1 VCI_GetReference2

This function is used to get all the parameters inside the adapter.

DWORD __stdcall VCI_GetReference2(DWORD DevType,DWORD DevIndex,DWORD

CANIndex,DWORD Reserved,PVCI_REF_STRCUT pRefStruct);

Parameters:
34 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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.

Reserved

Reserved, fill in 0 for call.

pRefStruct

pRefStruct is used to store the parameters of the first data buffer address pointer and return

VCI_REF_STRCUT type of data structure.

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_REF_STRCUT refStruct;

DWORD dwRel;

dwRel = VCI_GetReference2(nDeviceType, nDeviceInd, nCANInd, 0,&refStruct);

if(dwRel != 1)

MessageBox(_T("Fail to obtain parameter!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

35 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

3.3.2 VCI_SetReference2

This function is used to set the parameters related to the adapter.

DWORD __stdcall VCI_SetReference2(DWORD DevType,DWORD DevIndex,DWORD

CANIndex,DWORD RefType, BYTE *pData);

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

Parmeter type.

pData

pData is used to store the parameters of the first data buffer address 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.

Remarks:RefType values table:

RefType pData
name pData return ontent
value length

0 REFTYPE_MODE 1byte Operation mode

1 REFTYPE_FILTER 1byte Filtering mode

2 REFTYPE_ACR 4bytes Acceptance filter value, 32-bit

6 REFTYPE_AMR 4bytes Mask filter value, 32-bit

10 REFTYPE_kCANBAUD 3bytes Baud rate index value+Timing0+Timing1

36 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

RefType pData
name pData return ontent
value length

Array with 3 bytes length

15 REFTYPE_ALL 15bytes VCI_REF_NORMAL type structure setting

16 REFTYPE_BAUD 11bytes VCI_BAUD_TYPE type structure setting

Note: When refType = 16, REFTYPE_kCANBAUD parameter is automatically set to 0. That is

automatically set to Custom Baud rate mode!

Some important instructions on Custom Baud rate setting:

1. CAN Nominal Bit Time = Sync Segment + Propagation Segment + Phase Segment 1 + Phase

Segment 2, (8 ~ 25TQ)

2. (Propagation Segment + Phase Segment 1) must be greater than or equal to the length of phase segment

2.

3. Phase Segment 2 must be greater than the synchronization jump width.

CAN bit timing diagram is as follows:

E.g.:

#include "ControlCan.h"

int nDeviceType = 4; /*USB-CAN2.0 */


37 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

int nDeviceInd = 0; /* zeroth device */

int nCANInd = 0;

BYTE mode = 1; /* spontaneous admission and sending mode */

DWORD dwRel;

dwRel = VCI_SetReference2(nDeviceType, nDeviceInd, nCANInd, 0,&mode);

if(dwRel != 1)

MessageBox(_T("Fail to set the parameter!"), _T("warning"), MB_OK|MB_ICONQUESTION);

return FALSE;

3.3.3 VCI_ResumeConfig

This function is used to restore the factory parameters.

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

Note: With this function to restore the factory settings, the device will be restored to all

channels.

E.g.:

38 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

#include "ControlCan.h"

int nDeviceType = 4; /*USB-CAN2.0 */

int nDeviceInd = 0; /* zeroth device */

int nCANInd = 0;

DWORD dwRel;

bRel = VCI_ResumeConfig(nDeviceType, nDeviceInd, nCANInd);

if(dwRel != 1)

MessageBox(_T("Fail to restore the factory settings !"), _T("warning"),

MB_OK|MB_ICONQUESTION);

return FALSE;

3.3.4 VCI_ConnectDevice

Check whether the USB-CAN device and your computer can communicate properly.
USB-CAN operation may be subject to outside interference or abnormal operation,which will cause
USB-CAN device dropped from the operating system. This function is used to detect communication
connection status such as relative abnormal situations. If there is any abnormality, relative tips can be brought
up and relative problems will be dealt with accordingly.
DWORD __stdcall VCI_ConnectDevice(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:
1 communication available,0 communication unavailable.
E.g.:

39 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

#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");

3.3.5 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
40 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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

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;

41 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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;

42 / 43
Shenzhen Fangxing Liutong Industrial Co., Ltd. Interface Function Library User Instruction

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_FindUsbDevice 、 VCI_UsbDeviceReset 、 VCI_ResumeConfig 、

VCI_ConnectDevice 、 VCI_GetReference2 and VCI_SetReference2. 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.

VCI_FindUsbDevice

VCI_OpenDevice

VCI_InitCAN

VCI_UsbDeviceReset VCI_ReadErrInfo

VCI_ResumeConfig VCI_ConnectDevice

VCI_GetReceiveNum VCI_ClearBuffer

VCI_ReadBoardInfo VCI_ReadCanStatus

VCI_GetReference VCI_SetReference

VCI_GetReference2 VCI_SetReference2

VCI_StartCAN

VCI_ResetCAN

VCI_Transmit VCI_Recive

VCI_CloseDevice

43 / 43