macOS^® User-Space Driver and SDK for USB CAN Interfaces from Kvaser

The Swedish company Kvaser AB supplies advanced CAN solutions to engineers designing and deploying systems for manifold areas of applications. They offer a wide range of CAN hardware and CAN software, mainly for applications under Windows but also under Linux. A macOS user-space driver for USB CAN Interfaces from Kvaser is provided by UV Software.

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

MacCAN-KvaserCAN Driver

The macOS driver for USB CAN interfaces from Kvaser is based on MacCAN-Core which is an abstraction (or rather a wrapper) of Apple´s IOUsbKit to create USB user-space drivers for CAN interfaces from various vendors under macOS. The GitHub repository contains the source code for the MacCAN-KvaserCAN driver and several alternatives to build dynamic libraries for macOS, either as a C++ class library (libKvaserCAN), or as a CAN API V3 wrapper library (libUVCANKVL), as well as some example programs and my beloved CAN utilities can_moni and can_test.

The MacCAN-KvaserCAN SDK comes with a CAN API V3 compatible API. 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. See header file CANAPI.h for the CAN API V3 interface.

Note: This project does not aim to implement Kvaser´s CANlib API on macOS.

Features

Feature	Leaf Devices	Mhydra Devices	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)			not supported
- Non-ISO CAN FD enable/disable (NISO)			not supported
- 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)			up to 64K CAN messages
- 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:
- Kvaser CANlib			not available
- CAN API V3			C API and C++ API by UV Software
- Dynamic library			`libUVCANKVL.dylib`, `libKvaserCAN.dylib`
- Static library			`libUVCANKVL.a`, `libKvaserCAN.a`
- Source code			BDS-2-Clause or GPL-3.0-or-later
- Apple silicon			and Intel architecture
- Swift wrapper			Swift 5.5 (including SPM)
- Python wrapper			Python 2.7 and 3.8
- Windows wrapper			CAN API V3 Wrapper Library
- Utilities			CLI utilities `can_moni` and `can_test`
- Examples			C, C++, Swift, Python

Change-log

Version 0.3.4 (Commit e8fb32f of June 11, 2024):

Updated CAN API V3 sources to rev. 1312
Updated CAN API V3 Xcode testing to rev. 1334
Updated CAN API V3 GoogleTest suites to rev. 1336
Removed unnecessary class attributes
Removed upper size limit of string properties
Reworked CAN API V3 return values (C vs. C++)
Optimized CAN API V3 wrapper (can_api.c)
Integrated generic CAN API V3 Utilities (rev. 1323)
Updated release documents

Version 0.3.3 (Commit d950b79 of November 11, 2023):

Updated MacCAN-Core sources to rev. 1816
Updated CAN API V3 sources to rev. 1212
Updated CAN API V3 testing sources to rev. 1219
Updated GoogleTest to version 1.14.0
Updated the trial program
Updated the Python wrapper
Updated Doxygen configuration
Updated deployment rules
Replaced deprecated gettimeofday and usleep
Added linker option -rpath /usr/local/lib (Xcode 15)

Version 0.3.2 (Commit 2f3cb7c of September 10, 2023):

Updated MacCAN Core sources to rev. 1757 (core 0.4)
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
Added bit-rate settings for 5kbps
Fixed a bug with bus error state flags
Fixed a bug with capability flag ERR
Fixed a bug with mode flag ERR
Fixed a bug with message flag ESI
Fixed a bug with message flag RTR
Made the utilities more generic
Updated Swift wrapper and package
Updated the trial program
Updated the examples

Version 0.3.1 (Commit aaa925f of August 4, 2022):

Realized new property GET_CAN_CLOCK
Applied changes from module can_btr
Updated CAN API V3 Testing sources to rev. 1084
Fixed a bug with CAN bus load resolution
Fixed a possible bug with USB device name length
Updated the scanner for test case annotations
Updated the trial program

Version 0.3 (Commit 1ef5e9f of July 8, 2022):

Refactoring of the device driver layer:
- one module KvaserUSB_LeafDevice to access all devices from Kvaser CAN Leaf device family (i.e. Leaf Light v2)
- one module KvaserUSB_MhydraDevice to access all devices from Kvaser CAN Mhydra device family (i.e . U100P)
- new module KvaserCAN_Devices with USB ProductId and other properties for all devices from both device families
- implemented error event handling for Mhydra compatible devices
Updated MacCAN-Core sources to rev. 1200
Updated CAN API sources to rev. 1053
Updated CAN API Testing sources to rev. 1062
Adapted bit-rate settings according to Kvaser´s Linux driver
Added test suites for function SetBusParams and SetBusParamsFd
Fixed a bug with outdated clocks array
Fixed a bug with CAN clock from software options
Fixed a bug with READ_CLOCK_NOW for Leaf compatible devices
Fixed a bug with time-stamp conversion (24MHz issue)
Fixed a bug with DRIVERMODE_OFF for Leaf compatible devices
Fixed a bug with operation mode NISO in the driver layer
Fixed a bug with getting capabilities from device
Fixed a bug with HE addresses in the Mhydra driver
Fixed a bug with setting CAN bus parameters
Fixed a bug with setting CAN FD bus parameters
Fixed a bug with data phase settings w/o flag BRSE (U100P issue)
Fixed a bug with converting Kvaser bus params to CAN API bit-rate settings
Fixed a bug with error handling of device info commands
Fixed a bug with incorrectly mapped firmware error code
Fixed a bug with tx message flags in the Swift wrapper (SwiftCAN issue)
Fixed a bug with mask & value in the response CMD_GET_CAPABILITIES_RESP
Fixed a bug with unsupported command CMD_GET_INTERFACE_INFO_REQ
Fixed some findings from static code analysis (cppcheck)
Added @rpath to linker option --install_name
Added a scanner for test case annotations to generate the test specs

Version 0.2.1 (Commit e334212 of June 1, 2022):

Fixed bit-rate issue for devices not running at 80 MHz (issue #10)
Added methods to query channel information to the Swift wrapper
Added a cppcheck configuration to the project

Version 0.2 (Commit 18b198f of February 11, 2022):

Implemented CAN FD operation mode for Leaf Pro devices
Implemented properties NUM_CHANNELS, CAN_CHANNEL, QUEUE_OVFL, QUEUE_SIZE and QUEUE_HIGH
MacCAN-Core changes:
- Updated MacCAN-Core sources to rev. 1090
- Removed class CMacCAN from project
- Replaced CAN API error codes by MacCAN error codes
- Fixed a bug with forgotten NULL pointer check in CANUSB_ReadPipe
- Fixed a bug with calculation of queue high counter
CAN API V3 changes:
- Updated CAN API sources to rev. 1036 and applied latest changes
- Fixed a bug with probing a device when it is used by another process
- Fixed a bug with CAN FD operation dependent mode flags
- Fixed some omissions with handling of device properties
- Fixed a bug with property GET_DEVICE_TYPE
- Fixed a bug with Swift property deviceInfo
- Fixed a bug with device vendor instead of library vendor
- Added operations to class CCanApi to query channel information
- Updated the utilities to get the list of channels from library
- Updated the Swift wrapper and examples
Testing changes:
- Updated CAN API Testing sources to rev. 1086
- Changed template concept for CAN API Testing
- Moved CAN API Testing sources to $(PROJROOT)/Tests/UnitTests
- Replaced test suite for can_software by can_firmware
- Reworked test suite for function can_property
- Implemented a test case to measure time-stamp accuracy
- Add a workaround to TC11.10 for Kvaser bus parameters
Set deployment target to macOS 11.0
Updated the Travis CI configuration (osx_image: xcode12.5)
Updated the Makefiles to build the artifacts as Universal macOS Binary
Updated README.md (“Running CAN and CAN FD on Mac”)

Version 0.1 SR1 (Commit 7f6274f of July 10, 2021):

Added a CAN API V3 compatible Swift wrapper and two Swift examples
Added Swift Package Manager (SPM) configuration and test template
Moved CAN API wrapper code from C++ class to C interface (can_api.c)
Added abstract class CCanApi (as replacement for class CMacCAN)
Fixed a bug with checking for valid handle in function can_init
Fixed a bug with uncleared receive queue after re-start
Fixed a bug when teardown all channels (CANEXIT_ALL)
Fixed a bug with reading device independent properties
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
Temporary fix for investigation of issue #5

Version 0.1 (Commit 64e4388 of June 3, 2021):

CAN 2.0:
- 11-bit and 29-bit identifier
- bit-rates up to 1’000 kbps
Bit-rate settings:
- via register values (clock, prescaler, time segment TSeg1 and TSeg2, SJW, SAM)
- as pre-defined bit-timing index (according to CiA CANopen specification)
Operation modes:
- Monitor mode enable/disable (default=disabled)
- Error frames enable/disable (default=disabled)
- Extended frames disable/enable (default=enabled)
- Remote frames disable/enable (default=enabled)
Message reception:
- Message queue (FIFO) for 64K CAN message
- Read queue via polling, blocking read, or with time-out up to 65 seconds
Message transmission:
- with or without acknowledge (with time-out up to 65 seconds)
Application Programming Interface:
- CAN API V3 by UV Software (C and C++ API)
- CAN API V3 Python Wrapper (Python 2.7 and 3.8)
Supported Kvaser CAN Leaf devices:
- Kvaser Leaf Light v2 (EAN: 73-30130-00685-0)
- Kvaser Leaf Pro HS v2 (EAN: 73-30130-00843-4)
Limitations (selected):
- Leaf Pro HS v2 devices can currently only be operated in CAN 2.0 mode!
- Monitor mode (listen-only) is not supported by the Leaf Light v2 hardware.

Supported Devices

Only the following devices from Kvaser AB are supported:

Kvaser Leaf Light v2 (EAN: 73-30130-00685-0)
Kvaser Leaf Pro HS v2 (EAN: 73-30130-00843-4)
Kvaser U100P (EAN: 73-30130-01174-8)

Since version 0.3 theoretically all (single-channel) CAN interfaces from Kvaser´s device family Leaf Interfaces (CAN 2.0 interfaces, e.g. Leaf Light v2) and from Kvaser´s device family Mhydra Interfaces (CAN FD interfaces, e.g. U100P) are supported. To add a new CAN USB interface from Kvaser, only its USB ProductID and some device specific attributes have to be entered or enabled in the source code.

Note: The CAN devices listed above are the ones that are enabled and have been tested.

For technical specifications, prices and delivery terms 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

Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other countries.
Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries.
Linux is a registered trademark of Linus Torvalds.
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.

Depends on the device hardware or firmware. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸ ↩⁹ ↩¹⁰ ↩¹¹ ↩¹²

Uwe Vogt, UV Software