USB-CAN Analyzer Secondary Development: A Complete Guide to the ControlCAN Interface Library

USB-CAN Analyzer Secondary Development with ControlCAN Interface Library

Overview and Architecture

The USB-CAN bus interface adapter family from Zhuhai Chuangxin Technology Co., Ltd. enables robust, high-fidelity CAN communication for industrial, automotive, and embedded test applications. For secondary development—i.e., integration into custom host software—the vendor provides the ControlCAN interface function library, a dynamic-link library (DLL) designed to deliver full hardware control while maintaining strict compatibility with the widely adopted ZLG (Zhou Liguang) CAN API standard. This compatibility significantly reduces porting effort for developers already familiar with ZLG-based toolchains.

The supported device family includes USBCAN-2A, USBCAN-2C, CANalyst-II series, MiniPCIe-CAN modules, and OBDII-specific variants—all unified under the device type identifier VCI_USBCAN2 = 4. The library delivers platform flexibility: Windows (32/64-bit ControlCAN.dll), Linux (libcontrolcan.so), and cross-language support via language-specific header files and bindings.

The core delivery package comprises:

  • ControlCAN.dll (Windows) / libcontrolcan.so (Linux): The runtime binary implementing all CAN I/O and device management functions.
  • ControlCAN.lib: Windows import library for static linking in C/C++ projects.
  • ControlCAN.h, ControlCAN.bas, ControlCAN.pas, ControlCAN.llb: Language-specific interface declarations for C/C++, VB6, Delphi, and LabVIEW respectively.

Core Data Structures and Configuration

VCI_CAN_OBJ: The Fundamental CAN Frame Structure

All CAN message transmission and reception operate through the VCI_CAN_OBJ structure—a fixed-size, 24-byte container defining every aspect of a CAN frame. Its layout strictly follows SJA1000 register conventions and is critical for correct data interpretation.

Field Type Description
ID UINT (32-bit) Frame identifier. Right-aligned: standard ID occupies bits 0–10; extended ID occupies bits 0–28.
TimeStamp UINT Timestamp in 0.1 ms units, measured from device power-on. Valid only if TimeFlag == 1.
TimeFlag BYTE Enable flag for timestamp capture on received frames.
SendType BYTE Transmission mode: 0 = normal (auto-retry on failure); 1 = single-shot (no retry).
RemoteFlag BYTE 0 = data frame; 1 = remote transmission request (RTR) frame.
ExternFlag BYTE 0 = standard frame (11-bit ID); 1 = extended frame (29-bit ID).
DataLen BYTE Data Length Code (DLC). Must be ≤ 8. Actual data bytes are stored in Data[0..DataLen-1].
Data[8] BYTE[8] Payload data array. Only first DataLen bytes are valid.
Reserved[3] BYTE[3] Reserved for future use. Must be zero-initialized.

VCI_INIT_CONFIG: CAN Channel Initialization Parameters

Before enabling a CAN channel, it must be configured using the VCI_INIT_CONFIG structure. This defines bus timing, filtering behavior, and operational mode.

  • AccCode & AccMask: 32-bit acceptance code and mask, implementing SJA1000-style hardware filtering. A mask value of 0xFFFFFFFF disables filtering and accepts all frames.
  • Filter: Global filter mode: 1 = accept all frames; 2 = standard frames only; 3 = extended frames only.
  • Timing0 & Timing1: BTR0/BTR1 values for target baud rate. Precomputed values for common rates (e.g., 500 Kbps = 0x00/0x1C) are provided in documentation. Sampling point is fixed at 87.5%.
  • Mode: Operational mode: 0 = normal; 1 = listen-only (no TX driver activation); 2 = loopback (TX output fed directly to RX input, no physical bus activity).

Note: These adapters use high-speed CAN transceivers and do not support baud rates below 10 Kbps.

Core API Functions

ZLG-Compatible Standard Functions (10)

The primary interface consists of ten functions mirroring the ZLG CAN API, ensuring broad ecosystem interoperability. All return 1 on success, 0 on failure, or -1 if the device is absent or disconnected.

  • VCI_OpenDevice(DeviceType, DeviceIndex, Reserved): Opens the specified device. Each physical unit can be opened only once per process.
  • VCI_CloseDevice(DeviceType, DeviceIndex, Reserved): Releases resources and closes the device handle.
  • VCI_InitCAN(DeviceType, DeviceIndex, CANIndex, pInitConfig): Configures timing, filtering, and mode for a specific CAN channel.
  • VCI_StartCAN(DeviceType, DeviceIndex, CANIndex): Activates the initialized CAN channel and begins bus communication.
  • VCI_Transmit(DeviceType, DeviceIndex, CANIndex, pSendBuffer, Len): Sends up to Len frames. Returns number of frames successfully queued for transmission. Maximum Len is 1000; for reliability, single-frame submission is recommended.
  • VCI_Receive(DeviceType, DeviceIndex, CANIndex, pReceiveBuffer, Len, WaitTime): Retrieves up to Len frames from the receive buffer. The internal hardware buffer holds ~2500 frames per channel; allocate pReceiveBuffer accordingly. WaitTime specifies timeout in milliseconds (0 = non-blocking).
  • VCI_GetReceiveNum(DeviceType, DeviceIndex, CANIndex): Returns current count of unread frames in the receive buffer.
  • VCI_ClearBuffer(DeviceType, DeviceIndex, CANIndex): Empties both transmit and receive buffers for the specified channel.
  • VCI_ResetCAN(DeviceType, DeviceIndex, CANIndex): Resets the CAN controller without reinitializing hardware—useful for recovering from bus-off state.
  • VCI_ReadBoardInfo(DeviceType, DeviceIndex, pBoardInfo): Reads device metadata including hardware version, firmware version, driver version, serial number, and number of available CAN channels.

Vendor-Specific Extended Functions (3)

Three additional functions provide capabilities beyond the ZLG standard:

  • VCI_UsbDeviceReset(DeviceType, DeviceIndex, Reserved): Performs a full USB reset of the adapter, equivalent to physically unplugging and reinserting it.
  • VCI_FindUsbDevice2(pDevInfoArray, MaxCount): Enumerates all connected USB-CAN devices and returns their hardware serial numbers. Supports up to 50 devices simultaneously. Critical for multi-device systems and software licensing via hardware binding.
  • VCI_SetReference(DeviceType, DeviceIndex, CANIndex, RefType, pRefData): Configures advanced intelligent filtering. RefType=1 adds an ID to the smart filter table; RefType=2 enables the table; RefType=3 clears it.

Supported Development Languages and Environments

The ControlCAN library supports a wide spectrum of development platforms. Crucially, bitness matching is mandatory: a 32-bit application must link against the 32-bit DLL; a 64-bit application requires the 64-bit DLL. Mismatched bitness results in load failures or undefined behavior.

All Windows DLLs depend on the Microsoft Visual C++ 2008 Redistributable. Missing runtime libraries manifest as error code 0x0150002. Deployment requires installing vcredist_x86.exe (32-bit) or vcredist_x64.exe (64-bit) alongside the application.

Language support details:

Leave a Reply

Your email address will not be published. Required fields are marked *