ControlCAN API
ControlCAN API is the Windows interface library (ControlCAN.dll) for CANalyst-Ⅱ devices. Use it with CANmeleon devices running CANalyst-Ⅱ firmware to open dual Classic CAN channels and transmit and receive Classic CAN frames.
SDK Package Contents
Common C/C++ development files in the archive include:
| File | Purpose |
|---|---|
ControlCAN.h | Data structures, constants, and function declarations |
ControlCAN.lib | Import library linked at compile time |
ControlCAN.dll | Dynamic-link library loaded at runtime |
Match the architecture (x86 vs. x64) of your executable, ControlCAN.lib, and ControlCAN.dll. Official Chuangxin archives also provide sample projects for C#, VB, Delphi, LabVIEW, LabWindows/CVI, and MATLAB, all calling the same underlying ControlCAN exports.
Key Parameters and Structures
Device and Channel Indices
| Parameter | Typical CANalyst-Ⅱ Value | Description |
|---|---|---|
DevType | VCI_USBCAN2 (4) | Dual-channel CANalyst-Ⅱ device type |
DevIndex | 0 | First connected device; increments (0, 1, …) when multiple devices are attached |
CANIndex | 0 or 1 | 0 selects CAN1; 1 selects CAN2 |
Core Data Structures
VCI_INIT_CONFIG: Stores the acceptance code (AccCode), acceptance mask (AccMask), filter mode (Filter), bit-timing bytes (Timing0,Timing1), and operating mode (Mode).VCI_CAN_OBJ: Represents a single Classic CAN frame, including identifier (ID), frame flags (RemoteFlag,ExternFlag), payload length (DataLen), payload bytes (Data), and receive timestamp (TimeStamp).VCI_BOARD_INFO: Stores serial number, channel count, and hardware, firmware, driver, and library version metadata.
VCI_CAN_OBJ::Data holds up to 8 bytes, so ControlCAN is for Classic CAN frames only (not CAN FD).
Typical Call Sequence
VCI_OpenDevice
↓
VCI_InitCAN
↓
VCI_StartCAN
↓
VCI_Transmit / VCI_Receive
↓
VCI_CloseDeviceOpen a dual-channel device only once (VCI_OpenDevice). Then call VCI_InitCAN and VCI_StartCAN separately for CAN1 (CANIndex = 0) and CAN2 (CANIndex = 1), passing the corresponding CANIndex to VCI_Transmit and VCI_Receive.
Common helper functions:
| Function | Purpose |
|---|---|
VCI_ReadBoardInfo | Read hardware, firmware, driver, and serial-number information |
VCI_GetReceiveNum | Query the count of unread frames in a channel's receive buffer |
VCI_ClearBuffer | Clear receive and transmit buffers for a channel |
VCI_ResetCAN | Reset a specific CAN channel |
VCI_FindUsbDevice2 | Enumerate attached USB devices and read their serial numbers |
Common Bit-Timing Values
Configure Classic CAN bitrates via Timing0 and Timing1 in VCI_INIT_CONFIG. Standard combinations from the vendor manual are:
| Bitrate | Timing0 | Timing1 |
|---|---|---|
125 kbit/s | 0x03 | 0x1C |
250 kbit/s | 0x01 | 0x1C |
500 kbit/s | 0x00 | 0x1C |
1 Mbit/s | 0x00 | 0x14 |
Match Bus Bitrate
The example below uses 500 kbit/s. Always configure a bitrate that matches every node on your target CAN network; calculate custom Timing0 / Timing1 pairs using the documentation in the Chuangxin SDK archive when needed.
Minimal C/C++ Example
The example below opens CAN1 on the first CANalyst-Ⅱ interface at 500 kbit/s, transmits one 8-byte standard data frame, checks the receive buffer, and closes the device:
#include <cstdint>
#include <iostream>
#include "ControlCAN.h"
namespace {
constexpr DWORD kDeviceType = VCI_USBCAN2;
constexpr DWORD kDeviceIndex = 0;
constexpr DWORD kChannelIndex = 0;
constexpr DWORD kOk = 1;
}
int main() {
if (VCI_OpenDevice(kDeviceType, kDeviceIndex, 0) != kOk) {
std::cerr << "Failed to open CANalyst-II\n";
return 1;
}
VCI_INIT_CONFIG config{};
config.AccCode = 0;
config.AccMask = 0xFFFFFFFF;
config.Filter = 1; // Accept both standard and extended frames
config.Timing0 = 0x00; // 500 kbit/s
config.Timing1 = 0x1C;
config.Mode = 0; // Normal mode
if (VCI_InitCAN(kDeviceType, kDeviceIndex, kChannelIndex, &config) != kOk ||
VCI_StartCAN(kDeviceType, kDeviceIndex, kChannelIndex) != kOk) {
std::cerr << "Failed to initialize CAN1\n";
VCI_CloseDevice(kDeviceType, kDeviceIndex);
return 1;
}
VCI_CAN_OBJ tx{};
tx.ID = 0x123;
tx.SendType = 0; // Normal transmission (automatic retransmission on failure)
tx.RemoteFlag = 0; // Data frame
tx.ExternFlag = 0; // Standard identifier
tx.DataLen = 8;
for (std::uint8_t i = 0; i < tx.DataLen; ++i) {
tx.Data[i] = i;
}
const DWORD sent = VCI_Transmit(
kDeviceType, kDeviceIndex, kChannelIndex, &tx, 1
);
std::cout << "Sent frames: " << sent << '\n';
VCI_CAN_OBJ rx[100]{};
const DWORD received = VCI_Receive(
kDeviceType, kDeviceIndex, kChannelIndex, rx, 100, 0
);
if (received != static_cast<DWORD>(-1)) {
std::cout << "Received frames: " << received << '\n';
}
VCI_CloseDevice(kDeviceType, kDeviceIndex);
return 0;
}Production applications typically poll VCI_Receive periodically on a dedicated worker thread and ensure VCI_CloseDevice runs on both normal exit and error paths.
Return Value Checks
VCI_OpenDevice,VCI_InitCAN,VCI_StartCAN,VCI_CloseDevice: Return1on success.VCI_Transmit: Returns the number of frames actually transmitted.VCI_Receive: Returns the number of frames read (0means no unread frames are currently buffered).- Because the header declares return types as unsigned
DWORD, compare error sentinel values againststatic_cast<DWORD>(-1)(0xFFFFFFFF).
Check return values at every stage—not only VCI_OpenDevice—and log the device index, channel index, and failed stage for diagnostics.
Official Documentation
- Chuangxin ControlCAN interface library manual (Chinese)
- Chuangxin technical documentation center (Chinese)
Treat the ControlCAN.h header and manual shipped in your downloaded package as authoritative for function prototypes and struct layouts.