Skip to content
Open in AI

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:

FilePurpose
ControlCAN.hData structures, constants, and function declarations
ControlCAN.libImport library linked at compile time
ControlCAN.dllDynamic-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 ​

ParameterTypical CANalyst-Ⅱ ValueDescription
DevTypeVCI_USBCAN2 (4)Dual-channel CANalyst-Ⅱ device type
DevIndex0First connected device; increments (0, 1, …) when multiple devices are attached
CANIndex0 or 10 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 ​

text
VCI_OpenDevice
       ↓
VCI_InitCAN
       ↓
VCI_StartCAN
       ↓
VCI_Transmit / VCI_Receive
       ↓
VCI_CloseDevice

Open 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:

FunctionPurpose
VCI_ReadBoardInfoRead hardware, firmware, driver, and serial-number information
VCI_GetReceiveNumQuery the count of unread frames in a channel's receive buffer
VCI_ClearBufferClear receive and transmit buffers for a channel
VCI_ResetCANReset a specific CAN channel
VCI_FindUsbDevice2Enumerate 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:

BitrateTiming0Timing1
125 kbit/s0x030x1C
250 kbit/s0x010x1C
500 kbit/s0x000x1C
1 Mbit/s0x000x14

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:

cpp
#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: Return 1 on success.
  • VCI_Transmit: Returns the number of frames actually transmitted.
  • VCI_Receive: Returns the number of frames read (0 means no unread frames are currently buffered).
  • Because the header declares return types as unsigned DWORD, compare error sentinel values against static_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 ​

Treat the ControlCAN.h header and manual shipped in your downloaded package as authoritative for function prototypes and struct layouts.

CANmeleon · USB-CAN / CAN FD Hardware, Firmware & Solutions

Image preview0 × 0 px
100%
Click backdrop or press Esc to return