Uwe Vogt, UV Software

Running CAN and CAN FD on Mac

The PCBUSB library realizes a USB-to-CAN user-space driver under macOS for PCAN-USB interfaces from PEAK-System Technik, Darmstadt. Its API is almost compatible to PEAK´s PCANBasic DLL on Windows. For the realization of multi-vendor applications UV Software provides a CAN API V3 compatible wrapper library.

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 PCBUSB library comes with a PCANBasic compatible API. The PCBUSB wrapper library provides a CAN API V3 compatible API for it.

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

Note: UV Software also provides a CAN API V3 compatible Wrapper Library for PEAK´s PCANBasic DLL for Windows.

Features

Feature PCAN USB
 		 PCAN USB
FD		 Remarks
CAN 2.0 :heavy_check_mark: :heavy_check_mark: Classical CAN
CAN FD :x: :heavy_check_mark: 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: :heavy_check_mark: 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: :heavy_check_mark: CAN FD only
Bit-rate switching (BRS) :x: :heavy_check_mark: CAN FD only
Listen-only mode (MON) :heavy_check_mark: :heavy_check_mark: CAN 2.0 and CAN FD
Identifier filtering :heavy_check_mark: :heavy_check_mark: CAN 2.0 and CAN FD
Operation modes:      
- Monitor mode enable/disable (MON) :heavy_check_mark: :heavy_check_mark: disabled by default
- Error frames enable/disable (ERR) :x: :x: not supported
- 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: :heavy_check_mark: disabled by default
- CAN FD operation enable/disable (FDOE) :x: :heavy_check_mark: 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 :x: :x: not supported
- Buffered write :heavy_check_mark: :heavy_check_mark: buffer size depends on the hardware
Software Development Kit:      
- PCANBasic API (:heavy_check_mark:) (:heavy_check_mark:) with the underlying PCBUSB library
- 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: libUVCANPCB.dylib, libPeakCAN.dylib
- Static library :heavy_check_mark: :heavy_check_mark: libUVCANPCB.a, libPeakCAN.a
- Source code :heavy_check_mark: :heavy_check_mark: BDS-2-Clause or GPL-3.0-or-later
- M1 chip :heavy_check_mark: :heavy_check_mark: Universal macOS Binary
- Linux support :heavy_check_mark: :heavy_check_mark: requires PCAN Linux chardev driver
- Swift wrapper :x: :x: not available
- Python wrapper :heavy_check_mark: :heavy_check_mark: Python 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++, Python

Change-log

Version 0.3 (Commit b3ab49a of August 2, 2024):

  • Integrated changes from PCBUSB library v0.13:
    • Acceptance filtering by setting parameter:
      • PCAN_ACCEPTANCE_FILTER_11BIT
      • PCAN_ACCEPTANCE_FILTER_29BIT
      • PCAN_MESSAGE_FILTER
      • PCAN_RECEIVE_STATUS
    • Suppression of status frames by setting parameter:
      • PCAN_ALLOW_STATUS_FRAMES
    • Suppression of remote frames by setting parameter:
      • PCAN_ALLOW_RTR_FRAMES
  • Updated CAN API V3 sources to rev. 1356:
    • Implemented acceptance filtering
    • Solved an issue with PCAN_RECEIVE_STATUS
  • Updated CAN API V3 testing to rev. 1373:
    • GoogleTest framework v1.15.0
    • Test suites for acceptance filtering
  • Updated CAN API V3 utilities to rev. 1375:
    • Filtering options (can_moni and can_test)
    • Option to send extended frames (can_test)
    • Fixed a bug with extended frames (can_moni)
  • Updated the Python wrapper and examples
  • Fixed an installation issue on Linux

Note: This release requires version 0.13 (or later) of the PCBUSB library to be installed.

Version 0.2.9 (Commit 44b0d6e of June 12, 2024):

  • Updated CAN API V3 sources to rev. 1312
  • Updated CAN API V3 Xcode testing to rev. 1334
  • Updated CAN API V3 GoogleTest testing to rev. 1336
  • Removed upper size limit of string properties
  • Reworked CAN API V3 return values (C vs. C++)
  • Optimized PeakCANBasic wrapper (can_api.c)
  • Fixed a bug with compiler switch __MAC_11_0
  • Fixed some findings from static code analysis
  • Moved the run-time loader into a separate file
  • Integrated generic CAN API V3 Utilities (rev. 1323)
  • Updated release documents

Version 0.2.8 (Commit 4b57e39 of April 26, 2024):

  • Added common Version.h to the project
  • Updated CAN API V3 sources to rev. 1270
  • Updated CAN API V3 testing sources to rev. 1273
  • Removed unused attributes from class CPeakCAN
  • Changed the resolution of CTimer to 64 bit
  • Added option --list-bitrates to the utilities
  • Updated Makefiles and build_no.sh
  • Improved compiler and linker flags
  • Updated the Python wrapper
  • Updated the examples
  • Updated the deployment rules

Version 0.2.7 (Commit f60fed3 of November 7, 2023):

  • Updated PCBUSB header file (version 4.8.0)
  • Updated CAN API V3 sources to rev. 1212
  • Updated CAN API V3 testing sources to rev. 1219
  • Updated the trial program
  • Updated deployment rules
  • Replaced deprecated gettimeofday() and usleep()
  • Added linker option -rpath /usr/local/lib (issue #15)

Version 0.2.6 (Commit e088ff of September 21, 2023):

  • Updated CAN API V3 testing sources to rev. 1201
  • Updated CAN API V3 sources to rev. 1187 and applied the changes
    • Fixed a small bug in btr_compare_bitrates
    • Reworked formatting of message flags
  • Reworked handling of receive queue empty
  • Fixed a possible string truncation
  • Made the utilities more generic
  • Updated the examples
  • Linux support

Version 0.2.5 (Commit fa172d5 of August 25, 2023):

  • Updated PCBUSB-Library header (version 4.7.0.1)
  • Added a compatibility check from PCAN_CHANNEL_VERSION (v0.9 or higher)
  • Updated CAN API V3 sources to SVN rev. 1155 and apply 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 (except frequency greater than 0)
      • 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
        • Check 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 has been shifted by 8)
    • Fixed a bug with saturation of CAN FD DLC conversion
    • Updated description of compiler switches
  • Reworked status message and error frame handling (mode flag err and message flag sts)
  • Synchronized the Utilities with PCBUSB-Utilities v0.5.7
    • Fixed an issue with option --verbose
  • Added CAN API V3 Tests with GoogleTest
  • Updated CAN API V3 Xctest suites
  • Updated the trial program

Tested with PCBUSB-Library version 0.12.1

Version 0.2.4 (Commit d42365c of August 2, 2022):

  • Updated CAN API V3 sources to SVN rev. 1082
  • Updated CAN API V3 Testing sources to SVN rev. 1084
  • Fixed a bug with transceiver off in can_reset
  • Fixed a bug with BTR0BTR1 register in CAN FD mode
  • Fixed a bug with mapping CAN FD bit-rate to Peak string
  • Realized feature NXTD and NRTR (software solution)
  • Updated class CPeakCAN (some property values)
  • Updated the trial program
  • Updated the Python wrapper
  • Updated the utilities

Tested with PCBUSB-Library version 0.11.2

Version 0.2.3 (Commit d2e9369 of February 6, 2022):

  • Updated CAN API sources to rev. 1036
  • Fixed a bug with property GET_DEVICE_TYPE (re-renamed property GET_DEVICE_CHANNEL into GET_DEVICE_TYPE to display the device type as specified instead of the channel no of the device)
  • Fixed a bug with reading property GET_DEVICE_VENDOR and GET_DEVICE_DLLNAME (they can also be read without a handle)
  • Fixed a bug with message flag sts on reception
  • Added operations GetFirstChannel and GetNextChannel to class CPeakCAN to query channel information
  • Updated the utilities to get the list of channels from the library (like can_boards[] in C interface)

Version 0.2.2 (Commit 58dd221 of January 5, 2022):

  • Updated CAN API sources to rev. 1020 and applied the changes
  • Renamed C interface function can_software in can_firmware
  • Reworked output of function can_hardware and can_firmware
  • Added a check for minimum required PCBUSB library version (v0.9 and above)
  • Fixed an issue with missing copy constructor (to avoid dynamic allocation of class members)
  • Fixed a bug with uncleared initialization flag when all handles have been released
  • Fixed a bug with vendor-specific property values
  • Fixed a bug with enumeration of PCAN channels
  • Activated option for PCBUSB issue 198 (old messages in URB of the reception queue)
  • Added an Xctest target for CAN API V3 C interface to the trial program:
    • workaround to run the test suites with PCBUSB.dylib in Xcode
    • workaround for PCANBasic init delay issue and PCBUSB flag QXMTFULL issue
  • Set all Xcode deployment targets to macOS 11.0 (Makefiles still work on OS X 10.13)
  • Updated the Makefiles to build the artifacts as Universal macOS Binary

Version 0.2.1 (Commit 95dcdc6 of June 8, 2021):

  • Added a check for valid identifier range in can_write
  • Added a check for valid messages flags in can_write
  • Added a check for operation capability in can_init
  • Added a check for operation mode bit FDOE when bit BRSE is set
  • Fixed a mistake with channel name displayed instead of device name
  • Fixed a bug with casting from CAN API channel to PCAN handle
  • Fixed an out-of-bound violation in companion module can_btr
  • Repaired the Python examples (they still not work with Python 2.7)
  • Switched to a dual-license: BSD-2-Clause OR GPL-3.0-or-later

Version 0.2 (Commit 0354cb4 of February 7, 2021):

  • Applied changes from CAN API V3 specification (rev. 925 to 987)
  • Added C++ class CPeakCAN derived from abstract class CCANAPI
  • Reworked the trial program (it is now based on class CPeakCAN)
  • Reorganized the entire folder structure of the repository
  • Added my beloved CAN utilities can_moni and can_test
  • Added two simple C++ examples for sending and receiving CAN frames
  • Added a Python wrapper and two Python examples
  • Added a Doxygen configuration

Version 0.1 (Commit 28c611e of March 13, 2019):

  • Initial git tag

Supported Devices

For a list of supported device see page PCBUSB library.

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

Except where otherwise noted, 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 these portions of this work in whole or in part.

Trademarks

Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other countries.
PCAN is a registered trademark of PEAK-System Technik GmbH, Darmstadt, Germany. POSIX is a registered trademark of the Institute of Electrical and Electronic Engineers, Inc.
GNU C/C++ is a registered trademark of Free Software Foundation, Inc.
Linux is a registered trademark of Linus Torvalds.
Windows is a registered trademark of Microsoft Corporation in the United States and/or 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.