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
| Area | Details |
|---|---|
| Bus interfaces | vxlapi 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 timestamps | Hardware-generated timestamps for frame ordering and timing analysis (see VN16xx firmware specifications for device parameters) |
| Virtual channels | Vector Virtual CAN channels allow offline software logic testing without physical hardware attached |
| Concurrent access | Multiple client applications can share access to the same physical channel when using compatible bit timing |
Development Environment Setup
Prerequisites
- Hardware driver: Install the appropriate driver from the Vector Driver Setup download page and follow the Vector driver installation guide.
- XL Driver Library: Download the SDK headers, import libraries, and documentation from the Vector XL Driver Library official page.
- Language options:
- C/C++: Direct native calls to
vxlapi.dll/vxlapi64.dllfor low-overhead throughput. - Python: Rapid test scripting through
python-can(interface="vector"). - C#: Managed development using Vector's
.NETwrapper.
- C/C++: Direct native calls to
C/C++ Header and Library Setup
Match the library architecture (vxlapi.lib vs. vxlapi64.lib) to your compiler target:
#include "vxlapi.h"
#pragma comment(lib, "vxlapi.lib") // Use vxlapi64.lib for x64 buildsCore 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
- Open the driver: Call
xlOpenDriver(). - Read hardware configuration: Call
xlGetDriverConfig()(orxlGetApplConfig()/xlGetChannelMask()) to inspect connected VN16xx physical channels. - Open a port: Call
xlOpenPort()withXL_INTERFACE_VERSION_V4for CAN FD to obtain aportHandleand permission mask. - Configure bit timing: Configure timing when your application holds
initAccessfor the channel:- Classic CAN: Call
xlCanSetChannelBitrate(). - CAN FD: Call
xlCanFdSetConfiguration()to set both arbitration-phase and data-phase bit timing, then activate the channel withxlActivateChannel().
- Classic CAN: Call
2. Event-Driven Reception
Use a Windows notification event handle instead of tight polling loops to keep CPU usage low:
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
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
xlCanTransmitExparameter signature in thevxlapi.hheader 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.