USB CAN FD B API Manual
USB CAN FD B API Manual
User Manual
Version:V1.3
Update Date:2022.08.08
1
:
API library(Secondary Development Library)User Manual
Revision History
2
:
API library(Secondary Development Library)User Manual
Contents
API Library(Secondary Development Library)...................................................................................................... 1
1 Overview .......................................................................................................................................................... 5
2 Data Structure Definition.................................................................................................................................. 5
2.1 ZCAN_DEVICE_INFO...................................................................................................................... 5
2.2 ZCAN_CHANNEL_INIT_CONFIG.................................................................................................. 6
2.3 can_frame ........................................................................................................................................... 9
2.4 canfd_frame ...................................................................................................................................... 10
2.5 ZCAN_Transmit_Data...................................................................................................................... 10
2.6 ZCAN_TransmitFD_Data..................................................................................................................11
2.7 ZCAN_Receive_Data ........................................................................................................................11
2.8 ZCAN_ReceiveFD_Data .................................................................................................................. 12
2.9 IProperty ........................................................................................................................................... 12
3 APIs Description............................................................................................................................................. 13
3.1 ZCAN_OpenDevice.......................................................................................................................... 13
3.2 ZCAN_CloseDevice ......................................................................................................................... 13
3.3 ZCAN_GetDeviceInf........................................................................................................................ 14
3.4 ZCAN_IsDeviceOnLine ................................................................................................................... 14
3.5 ZCAN_InitCAN ............................................................................................................................... 14
3.6 ZCAN_StartCAN ............................................................................................................................. 15
3.7 ZCAN_ResetCAN ............................................................................................................................ 15
3.8 ZCAN_ClearBuffer .......................................................................................................................... 16
3.9 ZCAN_Transmit ............................................................................................................................... 16
3.10 ZCAN_TransmitFD ........................................................................................................................... 16
3.11 ZCAN_GetReceiveNum .................................................................................................................... 17
3.12 ZCAN_Receive.................................................................................................................................. 17
3.13 ZCAN_ReceiveFD ............................................................................................................................ 18
3.14 GetIProperty ...................................................................................................................................... 18
3.15 ReleaseIProperty................................................................................................................................ 19
3.16 ZCAN_SetAbitBaud.......................................................................................................................... 19
3.17 ZCAN_SetDbitBaud.......................................................................................................................... 20
3.18 ZCAN_SetBaudRateCustom ............................................................................................................. 20
3.19 ZCAN_SetCANFDStandard.............................................................................................................. 21
3.20 ZCAN_SetResistanceEnable ............................................................................................................. 21
3.21 ZCAN_ClearFilter ............................................................................................................................. 21
3.22 ZCAN_SetFilterMode ....................................................................................................................... 22
3.23 ZCAN_SetFilterStartID ..................................................................................................................... 22
3.24 ZCAN_SetFilterEndID ...................................................................................................................... 23
3.25 ZCAN_AckFilter ............................................................................................................................... 24
4 Attribute List................................................................................................................................................... 25
5. Flow of Using API ......................................................................................................................................... 27
5.1 Flow ..................................................................................................................................................... 27
5.2 Sample Code........................................................................................................................................ 29
3
:
API library(Secondary Development Library)User Manual
4
:
API library(Secondary Development Library)User Manual
1 Overview
If users only use USBCANFD devices for CAN/CANFD bus debugging,you can directly use the provided
If users plan to write software programs for their own products. Please carefully read the following
Note1: ControlCANFD.lib, ControlCANFD.dll Relying on the VC2008 runtime, which is typically included
in most systems but not in very few lean systems, it needs to be installed.
Note2: The secondary development interface functions and data structures supported by this device are
2.1 ZCAN_DEVICE_INFO
This structure contains some basic information about the device, which can be filled in the function
ZCAN_GetDeviceInf.
Member
hw_Version
5
:
API library(Secondary Development Library)User Manual
fw_Version
dr_Version
in_Version
irq_Num
can_Num
str_Serial_Num
The serial number of this board, such as "USBCANFD0002" (note: including the string terminator '\0').
str_hw_Type
hardware type.
reserved
2.2 ZCAN_CHANNEL_INIT_CONFIG
This structure defines the parameters for channel initialization configuration and initialize the structure before
call ZCAN_InitCAN.
6
:
API library(Secondary Development Library)User Manual
Member
can_type
CAN Device
acc_code
The frame filtering acceptance code of SJA1000 matches the "relevant bits" filtered by the mask code.
After all matches are successful, this message can be received, otherwise it will not be received.
Recommended setting is 0.
acc_mask
The frame filtering mask code of SJA1000 filters the received CAN frame ID, with bits 0 being "relevant
bits" and 8 bits 1 being "irrelevant bits". It is recommended to set it to 0xFFFFFFFF, that is, receive all.
reserved
filter
timing0
timing1
mode
Working mode,=0 represents normal mode (equivalent to a normal node),=1 represents listening only
CANFD Device
acc_code
acc_mask
abit_timing
dbit_timing
brp
filter
mode
pad
reserved
Note: The Baud (abit_timing and dbit_timing) of the device is set by GetIProperty. See Chapter 5.2 for details。
8
:
API library(Secondary Development Library)User Manual
2.3 can_frame
Member
can_id
The frame ID, 32 bits, and the upper 3 bits belong to the flag bits. The meaning of the flag bits is as follows:
The 31st bit (highest bit) represents the extended frame flag,=0 represents the standard frame,=1 represents the
The 30th bit represents the remote frame flag,=0 represents the data frame,=1 represents the remote frame,
The 29th digit represents the error frame standard,=0 represents the CAN frame, and=1 represents the error
The remaining bits represent the actual frame ID value, using the macro MAKE_CAN_ID Construct ID, using
can_dlc
data length.
__pad
Align, ignore.
__res0
__res1
data
9
:
API library(Secondary Development Library)User Manual
2.4 canfd_frame
Member
can_id
Frame ID, same as chapter 2.3.
len
data length.
flags
Additional flags, such as using CANFD baud rate switch, then set to macro CANFD_BRS.
__res0
Reserved only, not set.
__res1
Reserved only, not set.
data
Message data, with an effective length of len.
2.5 ZCAN_Transmit_Data
Member
frame
transmit_type
Sending type: 0=normal sending, 1=single sending, 2=spontaneous self receiving, and 3=single spontaneous
self receiving.
Normal sending: When the ID arbitration is lost or there is an error in sending, the CAN controller will
10
:
API library(Secondary Development Library)User Manual
automatically resend until the transmission is successful, or the transmission times out, or the bus is turned off.
Single sending: In some applications, automatic retransmission is meaningless when partial data loss is
allowed but transmission delay cannot occur. In these applications, data is generally sent at fixed time intervals, and
automatic resending can cause subsequent data to be unable to be sent, resulting in transmission delays. If a single
transmission is used, arbitration is lost or transmission error occurs, and the CAN controller will not resend the
message.
Spontaneous self reception: generates a normal transmission with self reception characteristics, and after the
transmission is completed, the sent message can be read from the receiving buffer.
Single spontaneous self reception: A single transmission with self reception characteristics is generated, and
retransmission will not be executed in case of transmission error or arbitration loss. After the transmission is
completed, the sent message can be read from the receive buffer.
2.6 ZCAN_TransmitFD_Data
Member
frame
transmit_type
2.7 ZCAN_Receive_Data
11
:
API library(Secondary Development Library)User Manual
Member
frame
timestamp
2.8 ZCAN_ReceiveFD_Data
Member
frame
timestamp
Timestamp, in microseconds.
2.9 IProperty
The details of the structure are as follows, used to obtain/set device parameter information. For example code,
Member
SetValue
Set the equipment attribute values, see Chapter 4 Property list for details.
GetValue
12
:
API library(Secondary Development Library)User Manual
GetPropertys
3 APIs Description
3.1 ZCAN_OpenDevice
This function is used to open the device. A device can only be opened once.
parameter
device_type
For the device type, see the macro definition in the Header file zlgcan.h.
device_index
Device index number, for example, when there is only one USBCANFD, the index number is 0. If another
USBCANFD is inserted, the device index number inserted later will be 1, and so on.
reserved
Reserved only.
return value
INVALID_DEVICE_HANDLE indicates that the operation failed, otherwise it indicates that the operation
was successful. The device handle value is returned, please save the handle value. Future operations will need to
use.
3.2 ZCAN_CloseDevice
This function is used to shut down the device, and the closing and opening devices correspond one by one.
parameter
device_handle
The handle value of the device that needs to be closed, i.e. the value returned by ZCAN_OpenDevice
13
:
API library(Secondary Development Library)User Manual
successfully execute.
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.3 ZCAN_GetDeviceInf
parameter
device_handle
pInfo
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.4 ZCAN_IsDeviceOnLine
parameter
device_handle
return value
3.5 ZCAN_InitCAN
parameter
14
:
API library(Secondary Development Library)User Manual
device_handle
can_index
Channel index number, channel 0's index number is 0, channel 1's index number is 1, and so on.
pInitConfig
return value
INVALID_CHANNEL_HANDLE indicates that the operation failed, otherwise it indicates that the operation
was successful. The channel handle value is returned. Please save the handle value for future operations.
3.6 ZCAN_StartCAN
parameter
channel_handle
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.7 ZCAN_ResetCAN
This function is used to reset the CAN channel, which can be accessed through ZCAN_StartCAN to recovery.
parameter
channel_handle
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
15
:
API library(Secondary Development Library)User Manual
3.8 ZCAN_ClearBuffer
parameter
channel_handle
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.9 ZCAN_Transmit
parameter
channel_handle
pTransmit
len
frame number.
return value
3.10 ZCAN_TransmitFD
parameter
channel_handle
16
:
API library(Secondary Development Library)User Manual
pTransmit
len
frame number.
return value
3.11 ZCAN_GetReceiveNum
parameter
channel_handle
type
return value
3.12 ZCAN_Receive
This function is used to receive CAN frames, it is recommended to use ZCAN_GetReceiveNum to ensures
parameter
channel_handle
pReceive
len
17
:
API library(Secondary Development Library)User Manual
Array length (maximum number of frames received this time, actual return value is less than or equal to this
value).
wait_time
There is no data in the buffer. The waiting time for function blocking is in milliseconds. If it is -1, it indicates
return value
3.13 ZCAN_ReceiveFD
This function is used to receive CANFD frames, it is recommended to use ZCAN_GetReceiveNum to ensures
parameter
channel_handle
pReceive
len
Array length (maximum number of frames received this time, actual return value is less than or equal to this
value).
wait_time
There is no data in the buffer. The waiting time for function blocking is in milliseconds. If it is -1, it indicates
return value
3.14 GetIProperty
18
:
API library(Secondary Development Library)User Manual
parameter
device_handle
return value
Returns the pointer to the property configuration interface, see chapter 2.9 for details. If it is empty, it indicates
3.15 ReleaseIProperty
Release the property interface and pair it with GetIProperty for use.
parameter
pIProperty
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.16 ZCAN_SetAbitBaud
This function is used to set the baudrate of the CANFD arbitration domain. When using the attribute
'n/canfd_abit_baud_rate' to set baudrate fails, then this function can be called to set the baudrate. For example,
when the development environment is VC, you can call this function interface to set the CANFD arbitration
baudrate.
parameter
device_handle
can_index
Channel index number, channel 0's index number is 0, channel 1's index number is 1, and so on.
19
:
API library(Secondary Development Library)User Manual
abitbaud
For the baudrate value of the arbitration domain, see the baudrate value of the arbitration domain in the
Property list.
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.17 ZCAN_SetDbitBaud
This function is used to set the baudrate of the CANFD data domain. When using the attribute
'n/canfd_dbit_baud_rate' to set baudrate fails, then this function can be called to set the baudrate. For example,
when the development environment is VC, you can call this function interface to set the CANFD date baudrate.
parameter
device_handle
can_index
Channel index number, channel 0's index number is 0, channel 1's index number is 1, and so on.
dbitbaud
For the baudrate value of the data domain, see the baudrate value of the data domain in the Property list.
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.18 ZCAN_SetBaudRateCustom
This function is used to set the CANFD custom baudrate. When using the attribute 'n/baud_rate_custom' to set
the baudrate fails, then this function can be called to set the custom baudrate. For example, when the development
environment is VC, you can call this function interface to set the CANFD custom baudrate.
parameter
device_handle
can_index
Channel index number, channel 0's index number is 0, channel 1's index number is 1, and so on.
RateCustom
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.19 ZCAN_SetCANFDStandard
This function is used to set the CANFD standard type. When using the attribute 'n/canfd_standard' to set the
CANFD standard fails, then this function can be called to set it. If the development environment is VC, this
parameter
device_handle
can_index
Channel index number, channel 0's index number is 0, channel 1's index number is 1, and so on.
canfd_standard
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.20 ZCAN_SetResistanceEnable
3.21 ZCAN_ClearFilter
This function is used to clear channel filtering settings. When using the attribute 'n/filter_clear' to clear filter
fails, then this function can be called. e.g. when the development environment is VC, this function can be called to
21
:
API library(Secondary Development Library)User Manual
clear the filtering settings. This function is not called separately. Each configuration is carried out in the order of
clearing filter settings, configuration mode, configuration start ID, configuration end ID, and filtering effectiveness;
If you want to set multiple filters, you can set multiple filters between clearing the filter and filtering effectiveness.
parameter
channel_handle
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.22 ZCAN_SetFilterMode
This function is used to configure the channel filtering mode. This function can be called when using the
attribute 'n/filter_mode' to set the filter mode fails. e.g. this function can be called when the development
environment is VC. This function is not called separately. Each configuration is carried out in the order of clearing
filter settings, configuration mode, configuration start ID, configuration end ID, and filtering effectiveness; If you
want to set multiple filters, you can set multiple filters between clearing the filter and the filter effectiveness.
parameter
channel_handle
mode
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.23 ZCAN_SetFilterStartID
This function is used to configure the channel filtering start ID. This function can be called when using the
attribute 'n/filter_start' to set the start ID fails. e.g. this function interface setting can be called when the
22
:
API library(Secondary Development Library)User Manual
development environment is VC. This function is not called separately. Each configuration is carried out in the
order of clearing filter settings, configuration mode, configuration start ID, configuration end ID, and filtering
effectiveness; If you want to set multiple filters, you can set multiple filters between clearing the filter and the filter
effectiveness.
parameter
channel_handle
startID
start ID value.
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
3.24 ZCAN_SetFilterEndID
This function is used to configure the channel filtering end ID. This function can be called when using the
attribute 'n/filter_end' to set the end ID fails. e.g. this function interface setting can be called when the development
environment is VC. This function is not called separately. Each configuration is carried out in the order of clearing
filter settings, configuration mode, configuration start ID, configuration end ID, and filtering effectiveness; If you
want to set multiple filters, you can set multiple filters between clearing the filter and the filter effectiveness.
parameter
channel_handle
EndID
end ID value.
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
23
:
API library(Secondary Development Library)User Manual
3.25 ZCAN_AckFilter
This function is used to validate channel filtering settings. This function can be called when the 'n/filter_ack'
setting fails to take effect. e.g. this function interface setting can be called when the development environment is
VC. This function is not called separately. Each configuration is carried out in the order of clearing filter settings,
configuration mode, configuration start ID, configuration end ID, and filtering effectiveness; If you want to set
multiple filters, you can set multiple filters between clearing the filter and the filter effectiveness.
parameter
channel_handle
return value
STATUS_OK indicates successful operation, STATUS_ERR indicates that the operation failed.
24
:
API library(Secondary Development Library)User Manual
4 Attribute List
The Property list supported by this device is shown in the following table.
1,1=channel 2 500000:500kbps
250000:250kbps
125000:125kbps
100000:100kbps
50000:50kbps
ZCAN_InitCAN
date domain baudrate n/ canfd_dbit_baud_rate 5000000:5Mbps
n Indicates the channel number, 0=channel 4000000:4Mbps
1,1=channel 2 2000000:2Mbps
1000000:1Mbps
800000:800kbps
500000:500kbps
250000:250kbps
125000:125kbps
100000:100kbps
Note:set before call
ZCAN_InitCAN
custom baudrate n/baud_rate_custom Note:set before call
n Indicates the channel number, 0=channel ZCAN_InitCAN
1,1=channel 2
filter mode n/filter_mode “0”=standard frame
n Indicates the channel number, 0=channel “1”=extended frame
1,1=channel 2 Note:set after call ZCAN_InitCAN
Filter start frame n/filter_start “0x00000000”,hex char
n Indicates the channel number, 0=channel Note:set after call ZCAN_InitCAN
1,1=channel 2
Filter end frame n/filter_end “0x00000000”,hex char
n Indicates the channel number, 0=channel Note:set after call ZCAN_InitCAN
25
:
API library(Secondary Development Library)User Manual
1,1=channel 2
Clear filter n/filter_clear “0”
n Indicates the channel number, 0=channel Note:set after call ZCAN_InitCAN
1,1=channel 2
Filter effective n/filter_ack “0”
n Indicates the channel number, 0=channel Note:set after call ZCAN_InitCAN
1,1=channel 2
CANFD standard type n/canfd_standard “0”=CANFD ISO
n Indicates the channel number, 0=channel “1”=CANFD BOSCH
1,1=channel 2 Note:set before call
ZCAN_InitCAN
26
:
API library(Secondary Development Library)User Manual
5.1 Flow
OPEN DEVICE
Necessary ops ZCAN_OpenDevice
Optional ops
SET BAUDRATE
GetIProperty->SetValue 或
ZCAN_SetAbitBaud\ZCAN_SetDbitBaud
INIT CHANNEL
ZCAN_InitCAN
SET FILTER
CLOSE DEVICE
ZCAN_CloseDevice
27
:
API library(Secondary Development Library)User Manual
Each channel:
Standard frame filtering can
be set up to 64 groups CLEAR FILTER
Extended frame filtering can GetIProperty->SetValue 或
be set up to 32 groups ZCAN_ClearFilter
FILTER ACTIVE
Note: These functions/attributes for GetIProperty->SetValue 或
filtering settings need to be called ZCAN_AckFilter
in groups; Invoking it alone is
meaningless.
28
:
API library(Secondary Development Library)User Manual
OPEN DEVICE
CLOSE DEVICE
29
:
API library(Secondary Development Library)User Manual
SET BAUDRATE
30
:
API library(Secondary Development Library)User Manual
SET BAUDRATE 2
31
:
API library(Secondary Development Library)User Manual
32
:
API library(Secondary Development Library)User Manual
33
:
API library(Secondary Development Library)User Manual
34
:
API library(Secondary Development Library)User Manual
SEND FRAME
RECV FRAME
35
:
API library(Secondary Development Library)User Manual
If this device uses standard CAN, it is compatible with ZLG CANtest and CANPro protocol analysis software.
This chapter provides an overview of its data structure and function. For detailed instructions on how to use
CANtest software and CANPro software, please refer to the analyzer materials 'How to Compatible with the Use of
Zhou Ligong CANTest Software' and 'How to Compatible with the Use of Zhou Ligong CANPro Protocol Analysis
Platform V1.50.pdf'. To use the ControlCAN.dll, ControlCAN.lib, and ControlCAN.h files mentioned in the
document, simply replace the relevant files provided by this driver library with the corresponding file names.
6.1.1 VCI_BOARD_INFO
The structure VCI_BOARD_INFO contains the device information of the USB-CAN series interface card.
member
hw_Version
Hardware version number, represented in hexadecimal. For example, 0x0100 represents V1.00.
fw_Version
The firmware version number, represented in hexadecimal. For example, 0x0100 represents V1.00.
dr_Version
Driver version number, represented in hexadecimal. For example, 0x0100 represents V1.00.
in_Version
36
:
API library(Secondary Development Library)User Manual
The version number of the interface library, expressed in hexadecimal. For example, 0x0100 represents V1.00
irq_Num
Retention parameter.
can_Num
str_Serial_Num
str_hw_Type
Hardware type, such as' USBCANFD0002 '(note: includes string terminator '\0').
Reserved
Reserved.
6.1.2 VCI_CAN_OBJ
The structure VCI_CAN_OBJ is CAN frame structure. One structure represents the data structure of one frame.
In send function VCI_Transmit and Receive Function VCI_Receive, it is used to transmit CAN frames.
member
ID
TimeStamp
The time identifier of a frame received by the device. The time indicator starts counting from the device being
37
:
API library(Secondary Development Library)User Manual
TimeFlag
It indicates a the timestamp used or not. When it is 1, TimeStamp is valid. TimeFlag and TimeStamp are only
SendType
Send type.
=0 indicates normal transmission (if the transmission fails, it will automatically resend for 4 seconds, and if it
= 1 indicates single transmission (only once, if the transmission fails, it will not be automatically resend, and
RemoteFlag
=0 indicates the data frame; =1 indicates the remote frame (data segment is empty)。
ExternFlag
=0 indicates standard frame(11 bits ID), =1 indicates extended frame(29 bits ID).
DataLen
The data length, DLC (<=8) refers to the number of bytes in the CAN frame Data. Constrained the valid bytes
in Data[8].
Data[8]
CAN frame data. Due to the CAN specification of a maximum of 8 bytes, a space of 8 bytes is reserved here,
subject to DataLen constraints. If DataLen is defined as 3, that is, Data [0], Data [1], and Data [2] are valid.
Reserved
Reserved.
6.1.3 VCI_INIT_CONFIG
The structure VCI_INIT_CONFIG defines the configuration of CAN. The structure will be filled in function
38
:
API library(Secondary Development Library)User Manual
member
AccCode
Acceptance code. Frame filtering acceptance code for SJA1000. After filtering the masked code into "relevant
bits" for matching, once all matches are successful, this frame can be received. Otherwise, it will not be accepted.
Can be set to 0.
AccMask
Block code. Filter the received CAN frame ID using a frame filtering mask code for SJA1000. Use a
corresponding bit of 0 for the 'relevant bit' and a corresponding bit of 1 for the 'irrelevant bit'. It is recommended to
set the blocking code to 0xFFFFFF to receive all frames. The blocking code can also be set to 0.
Reserved
Reserved.
Filter
Timing0
Timing1
Mode
mode
=0 represents normal mode (equivalent to a normal node),=1 represents listening mode (only receiving
without affecting the bus), and=2 represents spontaneous self collection mode (loopback mode).
39
:
API library(Secondary Development Library)User Manual
6.2.1 VCI_OpenDevice
This function is used to open the device. Note that one device can only be opened once.
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
The device index number is assigned based on the order of insertion. For instance, if there is only one
USBCANFD adapter, its index number is 0. When another USBCANFD adapter is inserted, the device index
Reserved
return value
example
6.2.2 VCI_CloseDevice
parameter
40
:
API library(Secondary Development Library)User Manual
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
return value
example
6.2.3 VCI_InitCAN
This function is used to initialize the specified CAN channel. When there are multiple CAN channels, multiple
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
41
:
API library(Secondary Development Library)User Manual
pInitConfig
return value
example
6.2.4 VCI_ReadBoardInfo
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
pInfo
42
:
API library(Secondary Development Library)User Manual
return value
example
6.2.5 VCI_GetReceiveNum
This function retrieves the number of frames that have been received but not yet read in the receive buffer of
the specified CAN channel. Its main purpose is to work in conjunction with VCI_Receive, which assumes that the
In practical applications, users can improve program efficiency by directly looping calls to VCI_Receive and
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
return value
Returns the number of frames that have not been read yet,=-1 indicates that the USBCANFD device does not
43
:
API library(Secondary Development Library)User Manual
example
6.2.6 VCI_ClearBuffer
This function is used to clear the buffer of the specified CAN channel. Mainly used in situations where
receiving buffer data needs to be cleared, and sending buffer data will also be cleared.
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
return value
example
44
:
API library(Secondary Development Library)User Manual
6.2.7 VCI_StartCAN
This function is used to activate a CAN channel of the CAN card. When there are multiple CAN channels,
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
return value
45
:
API library(Secondary Development Library)User Manual
6.2.8 VCI_ResetCAN
This function is used to reset CAN. Mainly used in conjunction with VCI_StartCAN, the normal state of the
CAN card can be restored without further initialization. For example, when the CAN card enters the bus off state,
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
return value
example
6.2.9 VCI_Transmit
Send function. The return value is the actual number of frames successfully sent.
46
:
API library(Secondary Development Library)User Manual
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
pSend
Length
The length of the frame structure array to be sent (the number of frames sent). The maximum is 1000, it is
recommended to set it to 1 and send a single frame each time to improve transmission efficiency.
return value
Returns the actual number of frames sent,=-1 indicates that the USBCANFD device does not exist or the USB
is disconnected.
example
47
:
API library(Secondary Development Library)User Manual
6.2.10 VCI_Receive
Receive function. This function reads data from the receive buffer of the specified device CAN channel.
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
pReceive
The first pointer of structure array VCI_CAN_OBJ which used for reception frames. Note: The size of the
array must be larger than the len parameter below, otherwise memory read and write errors may occur。
Len
The length of the frame structure array used to receive (the maximum number of frames received this time,
and the actual return value is less than or equal to this value). This value is the size of the provided storage space.
The device has set a receive cache area of around 2000 frames for each channel. Users can choose an appropriate
receive array length between 1 and 2000 based on their own system and working environment requirements.
Generally, the size of the pReceive array and Len are set to be greater than 2000, such as 2500, which can
effectively prevent address conflicts caused by data overflow. Simultaneously call VCI_Receive every 30ms is
appropriate. While meeting the timeliness of the application, try to reduce the frequency of calling VCI_Receive as
much as possible. As long as the internal cache is not overflowed and more frames are read and processed each
WaitTime
Retention parameter.
return value
Returns the actual number of frames read,=-1 indicates that the USBCANFD device does not exist or the USB
48
:
API library(Secondary Development Library)User Manual
is disconnected.
example
6.2.11 VCI_SetReference
Attribute setting function, which can be used to set Baud and filter.
parameter
DevType
Device type. Please refer to the definition of adapter device type for different product models.
DevIndex
Device index, for example, when there is only one USBCANFD adapter, the index number is 0. If another
USBCANFD adapter is inserted, the device index number inserted later is 1, and so on.
CANIndex
CAN channel index. Which CAN channel is it. The CAN channel number of the corresponding card, with
RefType
pData
The data pointer corresponding to the attribute type is shown in the table below.
49
:
API library(Secondary Development Library)User Manual
50
:
API library(Secondary Development Library)User Manual
6.3.1 Flow
OPEN DEVICE
Necessary ops VCI_OpenDevice
Optional ops
SET BAUDRATE
VCI_SetReference
INIT CHANNEL
VCI_InitCAN
SET FILTER
CLOSE DEVICE
VCI_CloseDevice
51
:
API library(Secondary Development Library)User Manual
FILTER ACTIVE
VCI_SetReference,
RefType=2
Note: Filter settings need to be called
in groups as shown in the figure;
Invoking it alone is meaningless.
52
: