CAN API V3 Wrapper Library for Kvaser CAN Interfaces (Windows)

The Kvaser CANlib SDK is a software development kit providing everything you need to develop software for the Kvaser CAN and LIN interfaces on Windows. For the realization of multi-vendor CAN applications UV Software provides a CAN API V3 compatible wrapper library build upon Kvaser´s CANlib DLL.

Download Sources (zip) Sources (tar.gz) @GitHub

CAN API V3 Wrapper

CAN API V3 is a wrapper specification by UV Software to have a uniform CAN Interface API for various CAN interfaces from different vendors running under multiple operating systems. The KvaserCAN wrapper library provides a CAN API V3 compatible API for Kvaser´s CANlib DLL on Windows.

The GitHub repository contains the source code for the KvaserCAN wrapper library and several alternatives to build dynamic link libraries, either as a C++ class library (uvKvaserCAN.dll), or as a CAN API V3 wrapper library (u3cankvl.dll), as well as some example programs and my beloved CAN utilities can_moni.exe and can_test.exe.

Note: UV Software also provides a CAN API V3 compatible Wrapper Library for macOS.

Features

Feature	Supported	Remarks
CAN 2.0		Classical CAN
CAN FD		Flexible Data-rate CAN
Bit-rate, CAN 2.0		high speed: up to 1 Mbps
Bit-rate, CAN FD		nominal: up to 1 Mbps data phase: up to 8 Mbps
11-bit identifier (STD)		CAN 2.0 and CAN FD
29-bit identifier (XTD)		CAN 2.0 and CAN FD
Remote frames (RTR)		CAN 2.0 only
Error frames (ERR)		CAN 2.0 and CAN FD
Error indicator (ESI)		CAN FD only
Bit-rate switching (BRS)		CAN FD only
Silent operation (MON)		CAN 2.0 and CAN FD
Identifier filtering		CAN 2.0 and CAN FD
Operation modes:
- Monitor mode enable/disable (MON)		disabled by default
- Error frames enable/disable (ERR)		disabled by default
- Remote frames disable/enable (NRTR)		enabled by default
- Extended frames disable/enable (NXTD)		enabled by default
- Shared access enable/disable (SHRD)		disabled by default
- Non-ISO CAN FD enable/disable (NISO)		disabled by default
- Bit-rate switching enable/disable (BRSE)		disabled by default
- CAN FD operation enable/disable (FDOE)		disabled by default
Bit-rate settings:
- Pre-defined bit-timing indexes		acc. CiA CANopen specification
- BTR register values		register fields: - `freq` (clock frequency in [Hz]) - `brp` (bit-rate prescaler) - `tseg1` (time segment 1) - `tseg2` (time segment 2) - `sjw` (synchronization jump width) - `sam` (number of samples)
Message reception:
- Message queue (FIFO)		queue size depends on the hardware
- Polling		return immediately
- Timed out		wait up to 65’534 milliseconds
- Blocking read		wait infinitely
Message transmission:
- Acknowledged write		wait up to 65’534 milliseconds
- Buffered write		buffer size depends on the hardware
Software Development Kit:
- CAN API V3		C API and C++ API by UV Software
- Dynamic link library		`u3cankvl.dll`, `uvKvaserCAN.dll`
- Static library		`u3cankvl.lib`, `uvKvaserCAN.lib`
- 32-bit version (x86)		supported
- 64-bit version (x64)		supported
- Source code		BDS-2-Clause or GPL-3.0-or-later
- Python wrapper		Python 3
- macOS wrapper		macOS Driver and SDK
- Utilities		CLI utilities `can_moni` and `can_test`
- Examples		C, C++, Python

Change-log

Version 0.3 (Commit 1fe917a of April 24, 2024):

Added an unified version file
Recreated the library projects
Updated all MSBuild environments
Updated Kvaser canLib DLL (version 5.44)
Updated CAN API V3 sources to rev. 1270
Updated CAN API V3 testing sources to rev. 1273
Changed the resolution of CTimer to 64 bit
Implemented identifier acceptance filtering
Added test suites for acceptance filtering
Added filtering option to utility can_moni
Added option /LIST-BITRATES to the utilities
Implemented Kvaser-specific properties
Fixed a bug with flag ESI in TC05.20
Fixed a bug with Kvaser vs. CiA bit-rate settings
Fixed compiler warnings with legacy CAN 2.0 frame format
Updated the Python wrapper
Updated the examples

Version 0.2.5 (Commit b5157f3 of November 11, 2023):

Realized “Blocking Write” (CANlib canWriteWait)
Updated CAN API V3 testing sources to rev. 1219
Updated Kvaser CAN bit-rate defaults
Updated the utilities (class CTimer)
Updated the Python wrapper
Updated the trial program
Updated Doxygen configuration
Updated the deployment rules

Version 0.2.4 (Commit 0831da1 of September 10, 2023):

Migrated to VS 2022
Updated Kvaser canLib DLL to version 5.41
Updated CAN API V3 sources to rev. 1187 and applied the changes
- Added old error code -40 as queue overrun error and renumbered error error frame received from -40 to -19
- Removed unused error code CANERR_ERR_FRAME (note: the error code -19 is marked as reserved)
- Removed flag fdoe and brse from struct can_speed_t (note: the flags are marked as reserved)
- Integrated reworked module can_btr:
  - btr_check_bitrate: if FDOE w/o BRSE then check data phase field acc. OPTION_CANBTR_DATA_FIELDS
  - btr_bitrate2speed: no range checks anymore, calculation is done completely in float
  - btr_bitrate2index: returns the index if an index is given
  - btr_bitrate2string: no range checks anymore
  - btr_sja10002bitrate: set data phase field acc. OPTION_CANBTR_DATA_FIELDS
  - btr_compare_bitrates: comparision on basis of transmission rates (new function)
  - Removed flag fdoe and brse from struct btr_speed_t (standalone variant)
  - Documented all interface functions by Doxygen comments
  - Added header file CANBTR_Defaults.h
  - Reworked the bit-rate string scanner (btr_string2bitrate):
    - Return a flag if any data phase key is found
    - Return a flag if no. samp. key is found
    - Return BTRERR_ILLPARA on error
    - Removed the range checks
    - Set miminum frequency to 1
    - Checked for duplicated keys
    - Accept only case sensitive keys
  - Reworked the bit-rate string printer (btr_bitrate2string):
    - Added a parameter to output data phase keys
    - Added a parameter to output no. samp. key
    - Added a parameter for maximum buffer size
  - Fixed a bug with strtol if a correct value is outside the range of representable values (note: long is 32 bit wide for MS compilers and 64 bit for gcc based compilers!)
- Added property values for transmit queue properties (note: values for filtering have been shifted by 8)
- Fixed a bug with saturation of CAN FD DLC conversion
- Updated description of compiler switches
- Reworked formatting of message flags
Added CAN API V3 Tests with GoogleTest (rev. 1194)
Added Kvaser-specific bit-rate defaults
Reworked error frame handling
Fixed a bug when all channels torn down
Fixed a bug with bit-rate adjustment
Made the utilities more generic
Updated the examples

Version 0.2.3 (Commit e5504dc August 3, 2022):

Updated Kvaser canLib DLL (version 5.39)
Updated CAN API V3 sources to rev. 1082
Fixed a bug with transceiver off in function can_reset
Fixed a bug with field SAM in BTR0BTR1 register
Fixed a bug with Kvaser CAN bus params (noSamp)
Updated class CKvaserCAN (some property keys)
Updated the trial program
Updated the utilities

Version 0.2.2 (Commit 4971c3f of February 8, 2022):

Updated CAN API sources to rev. 1036
Fixed a bug with message flag sts on reception
Fixed a bug with getting properties from device
Fixed a bug with state of virtual CAN channels
Changed resolution of property GET_BUSLOAD
Added two operations to class CPeakCAN to query channel information
Updated the utilities to get the list of channels from the library

Version 0.2.1 (Commit c4bb537 of January 5, 2022):

Updated Kvaser canLib DLL (version 5.37)
Updated CAN API sources to rev. 1020 and applied the changes
Resolved firmware version vs. software version confusion
Fixed some bugs with getting properties from device and from library:
- accept NULL pointer for SET_FIRST_CHANNEL and SET_NEXT_CHANNEL
- getting device properties requires a valid handle
- string values must be at least one byte in size
Fixed a bug with missing length for property CANPROP_GET_DEVICE_NAME
Fixed a possible build issue with outdated define CAN_20_ONLY
Updated Python examples (although they do not work under Windows)
Updated my beloved utilities

Version 0.2 (Commit 5799eff of June 3, 2021):

Migrated to Visual Studio 2019 and adapted the MSC build environments
Switched to a dual-license: BSD-2-Clause OR GPL-3.0-or-later
Updated to Kvaser´s CANlib SDK version 5.35
Realized class CKvaserCAN: public CCANAPI (uvKvaserCAN.dll)
Implemented operation mode NXTD and NRTR
Added a check for operation mode bit FDOE when bit BRSE is set
Added a check for valid identifier range in can_write
Added a check for operation capability in can_init
Fixed a mistake with channel name displayed instead of device name
Fixed an out-of-bound violation in companion module can_btr
Fixed a bug with wrong return values from kvaser_capacity
Fixed an unnecessary decl-specifier on can_boards[]
Added my beloved CAN utilities
Added two simple C++ examples
Added a Doxygen configuration

Version 0.1 (Commit bc8301d of January 19, 2021):

Last sources from subversion repo to build version 1.1 (old versioning scheme)

Supported Devices

For a list of supported device see Kvaser´s website.

Known Bugs and Caveats

For a list of known bugs and caveats see tab Issues in the GitHub repo.

CAN API V3 Reference

A generic documentation of the CAN API V3 application programming interface can be found here.

Dual-License

This work is dual-licensed under the terms of the BSD 2-Clause “Simplified” License and under the terms of the GNU General Public License v3.0 (or any later version). You can choose between one of them if you use this work in whole or in part.

Trademarks

Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries.
Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other countries.
All other company, product and service names mentioned herein may be trademarks, registered trademarks, or service marks of their respective owners.

Hazard Note

If you connect your CAN device to a real CAN network when using this library, you might damage your application.

Uwe Vogt, UV Software