macOS User-Space Driver for CAN Leaf 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 CAN Leaf Interfaces from Kvaser is provided by UV Software.

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

MacCAN-KvaserCAN Driver

The macOS driver for CAN Leaf 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 driver comes with an 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
Light
Leaf
Pro
Remarks
CAN 2.0 :heavy_check_mark: :heavy_check_mark: Classical CAN
CAN FD :x: :x: Flexible Data-rate CAN
Bit-rate, CAN 2.0 :heavy_check_mark: :heavy_check_mark: high speed: up to 1 Mbps
Bit-rate, CAN FD :x: :x: nominal: up to 1 Mbps
data phase: up to 8 Mbps
11-bit identifier (STD) :heavy_check_mark: :heavy_check_mark: CAN 2.0 and CAN FD
29-bit identifier (XTD) :heavy_check_mark: :heavy_check_mark: CAN 2.0 and CAN FD
Remote frames (RTR) :heavy_check_mark: :heavy_check_mark: CAN 2.0 only
Error frames (ERR) :heavy_check_mark: :heavy_check_mark: CAN 2.0 and CAN FD
Error indicator (ESI) :x: :x: CAN FD only
Bit-rate switching (BRS) :x: :x: CAN FD only
Silent operation (MON) :x: :heavy_check_mark: CAN 2.0 and CAN FD
Identifier filtering :x: :x: CAN 2.0 and CAN FD
Operation modes:      
- Monitor mode enable/disable (MON) :x: :heavy_check_mark: disabled by default
- Error frames enable/disable (ERR) :heavy_check_mark: :heavy_check_mark: disabled by default
- Remote frames disable/enable (NRTR) :heavy_check_mark: :heavy_check_mark: enabled by default
- Extended frames disable/enable (NXTD) :heavy_check_mark: :heavy_check_mark: enabled by default
- Shared access enable/disable (SHRD) :x: :x: not supported
- Non-ISO CAN FD enable/disable (NISO) :x: :x: not supported
- Bit-rate switching enable/disable (BRSE) :x: :x: disabled by default
- CAN FD operation enable/disable (FDOE) :x: :x: disabled by default
Bit-rate settings:      
- Pre-defined bit-timing indexes :heavy_check_mark: :heavy_check_mark: acc. CiA CANopen specification
- BTR register values :heavy_check_mark: :heavy_check_mark: 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) :heavy_check_mark: :heavy_check_mark: up to 64K CAN messages
- Polling :heavy_check_mark: :heavy_check_mark: return immediately
- Timed out :heavy_check_mark: :heavy_check_mark: wait up to 65’534 milliseconds
- Blocking read :heavy_check_mark: :heavy_check_mark: wait infinitely
Message transmission:      
- Acknowledged write :heavy_check_mark: :heavy_check_mark: wait up to 65’534 milliseconds
- Buffered write :heavy_check_mark: :heavy_check_mark: buffer size depends on the hardware
Software Development Kit:      
- Kvaser CANlib :x: :x: not available
- CAN API V3 :heavy_check_mark: :heavy_check_mark: C API and C++ API by UV Software
- Dynamic library :heavy_check_mark: :heavy_check_mark: libUVCANKVL.dylib, libKvaserCAN.dylib
- Static library :heavy_check_mark: :heavy_check_mark: libUVCANKVL.a, libKvaserCAN.a
- Source code :heavy_check_mark: :heavy_check_mark: BDS-2-Clause or GPL-3.0-or-later
- Apple silicon :grey_question: :grey_question: not tested
- Swift wrapper :heavy_check_mark: :heavy_check_mark: Swift 5.4 (including SPM)
- Python wrapper :heavy_check_mark: :heavy_check_mark: Python 2.7 and 3.8
- Windows wrapper :heavy_check_mark: :heavy_check_mark: CAN API V3 Wrapper Library
- Utilities :heavy_check_mark: :heavy_check_mark: CLI utilities can_moni and can_test
- Examples :heavy_check_mark: :heavy_check_mark: C, C++, Swift, Python

Change-log

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)

Note: Leaf Pro HS v2 devices can currently only be operated in CAN 2.0 mode!

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.

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 are 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.