Skip to content
Open in AI

Vector XL Driver Library (vxlapi) ​

Overview ​

Alongside off-the-shelf tools such as CANoe and CANalyzer, automotive engineering teams often build standalone applications such as automated flash programmers, end-of-line testers, and hardware-in-the-loop scripts. Vector XL Driver Library (vxlapi) is Vector's Windows driver API for controlling VN-series hardware interfaces directly from C/C++, C#, or Python without running CANoe.

When a CANmeleon device runs Vector VN16xx firmware (VN1610 / VN1640A), applications built on vxlapi access its physical channels through the installed Vector Windows driver.

Core Capabilities ​

AreaDetails
Bus interfacesvxlapi covers CAN, CAN FD, LIN, and other Vector bus families; on CANmeleon VN16xx firmware, available CAN / CAN FD (and LIN in applicable VN1640A modes) channels depend on the active firmware, hardware, and license
Hardware timestampsHardware-generated timestamps for frame ordering and timing analysis (see VN16xx firmware specifications for device parameters)
Virtual channelsVector Virtual CAN channels allow offline software logic testing without physical hardware attached
Concurrent accessMultiple client applications can share access to the same physical channel when using compatible bit timing

Development Environment Setup ​

Prerequisites ​

C/C++ Header and Library Setup ​

Match the library architecture (vxlapi.lib vs. vxlapi64.lib) to your compiler target:

cpp
#include "vxlapi.h"
#pragma comment(lib, "vxlapi.lib") // Use vxlapi64.lib for x64 builds

Core CAN FD Workflow ​

For CAN FD networks, use the XL Driver Library extended CAN FD API (XL_INTERFACE_VERSION_V4).

1. Initialization and Channel Configuration ​

  1. Open the driver: Call xlOpenDriver().
  2. Read hardware configuration: Call xlGetDriverConfig() (or xlGetApplConfig() / xlGetChannelMask()) to inspect connected VN16xx physical channels.
  3. Open a port: Call xlOpenPort() with XL_INTERFACE_VERSION_V4 for CAN FD to obtain a portHandle and permission mask.
  4. Configure bit timing: Configure timing when your application holds initAccess for the channel:
    • Classic CAN: Call xlCanSetChannelBitrate().
    • CAN FD: Call xlCanFdSetConfiguration() to set both arbitration-phase and data-phase bit timing, then activate the channel with xlActivateChannel().

2. Event-Driven Reception ​

Use a Windows notification event handle instead of tight polling loops to keep CPU usage low:

cpp
HANDLE hEvent = INVALID_HANDLE_VALUE;
xlSetNotification(portHandle, &hEvent, 1); // Bind a Windows event handle

// Wait for incoming events on a dedicated worker thread
while (running) {
    WaitForSingleObject(hEvent, INFINITE); // Wake up when RX queue is non-empty
    // Read pending events with xlCanReceive() (V4 / CAN FD) or xlReceive() (V3 / Classic CAN)
    // in a loop until XL_ERR_QUEUE_IS_EMPTY is returned
}

C/C++ Example: Transmit a CAN FD Frame ​

cpp
void SendCANFD(XLportHandle portHandle, XLaccess accessMask, const unsigned char* myData) {
    XLcanTxEvent txEvent;
    memset(&txEvent, 0, sizeof(txEvent));

    txEvent.tag = XL_CAN_EV_TAG_TX_MSG;
    txEvent.tagData.canMsg.canId = 0x123;
    txEvent.tagData.canMsg.msgFlags = XL_CAN_TXMSG_FLAG_EDL | XL_CAN_TXMSG_FLAG_BRS; // CAN FD + BRS
    txEvent.tagData.canMsg.dlc = 15; // DLC 15 = 64-byte payload
    memcpy(txEvent.tagData.canMsg.data, myData, 64);

    unsigned int msgCount = 1;
    xlCanTransmitEx(portHandle, accessMask, msgCount, &msgCount, &txEvent);
}

Check the exact xlCanTransmitEx parameter signature in the vxlapi.h header shipped with your installed XL Driver Library version.

Practical Recommendations ​

Performance ​

Drain the Receive Queue per Wakeup

When WaitForSingleObject signals, read frames in a loop (or batch multiple events per call where supported) until XL_ERR_QUEUE_IS_EMPTY is returned, reducing kernel transitions under high bus load.

Size the Receive Queue Appropriately

On heavily loaded CAN FD buses (for example, 80% bus utilization), allocate a sufficiently large rxQueueSize in xlOpenPort() so bursts do not overflow the receive buffer.

Reliability and Cleanup ​

Release Channels Cleanly on Exit

Always call xlDeactivateChannel(), xlClosePort(), and xlCloseDriver() during normal shutdown and error handling so the channel does not remain occupied when you open CANoe or another application.

Monitor Controller Chip State

Handle XL_CAN_EV_TAG_CHIP_STATE events (and call xlCanRequestChipState() when needed) to detect Error Passive or Bus-Off states early during testing.

Reference Documentation ​

  • Vector XL Driver Library manual: XL Driver Library Description.pdf (included in the Vector XL Driver Library installation directory).
  • Official product & download page: Vector XL Driver Library.

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

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