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. It supports up to 8 PCAN-USB or PCAN-USB FD devices. The library offers an easy to use API to read received CAN messages from a 64K message queue and to transmit CAN messages. Standard CAN frames (11-bit identifier) as well as extended CAN frames (29-bit identifier) are supported. The PCAN-USB FD device can be operated in CAN 2.0 and CAN FD mode.

Download (x86_64) Download (arm64) Readme mac-can.com

PCBUSB Library

The dynamic library libPCBUSB is running under macOS 10.13 and later (Intel architecture and Apple silicon). The API is almost compatible to PEAK´s PCANBasic DLL on Windows. See the MacCAN website to learn more.

The library comes with an Objective-C wrapper and a Demo App: MacCAN Monitor App
Furthermore, it can be used with the Qt Serial Bus API on a Mac: Qt CAN Bus example

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

Features

Feature Supported Remarks
CAN 2.0 :heavy_check_mark: supported by PCAN-USB, PCAN-USB FD
CAN FD :heavy_check_mark: supported by PCAN-USB FD only
Bit-rate, CAN 2.0 :heavy_check_mark: high speed: up to 1 Mbps
Bit-rate, CAN FD :heavy_check_mark: nominal: up to 1 Mbps
data phase: up to 8 Mbps
11-bit identifier (STD) :heavy_check_mark: CAN 2.0 and CAN FD mode
29-bit identifier (XTD) :heavy_check_mark: CAN 2.0 and CAN FD mode
Remote frames (RTR) :heavy_check_mark: CAN 2.0 mode only
Error frames (ERR) :x: not realized yet
Error indicator (ESI) :heavy_check_mark: CAN FD mode only
Monitor mode (MON) :heavy_check_mark: listen-only mode (transmitter off)
Receive queue (FIFO) :heavy_check_mark: up to 65’536 CAN messages
Blocking read :heavy_check_mark: via a file descriptor and system call select; see example
Identifier filtering :heavy_check_mark: only one filter for 11-bit and 29-bit identifier (SJA1000)
Non-ISO CAN FD mode (:heavy_check_mark:) HW settings of the device cannot be changed by the library
Software interface (API) :heavy_check_mark: compatible to PEAK´s PCANBasic API with some limitations
Dynamic library (.dylib) :heavy_check_mark: for Intel architecture and as Universal macOS Binary
Static library (.a) :heavy_check_mark: Universal macOS Binary
Source code :x: not available
M1 Chip :heavy_check_mark: Universal macOS Binary
Objective-C Wrapper :heavy_check_mark: available
Python Wrapper :heavy_check_mark: available
Swift Wrapper :x: not available
CAN API V3 Wrapper :heavy_check_mark: available for macOS, Linux and Windows
Utilities :heavy_check_mark: CLI utilities: can_moni and can_test
Examples :heavy_check_mark: C++, Python, Objective-C (Demo App)

Change-log

Version 0.13 (Build 1978 of July 28, 2024):

  • synchronized PCBUSB header with PCANBasic header from PEAK’s version 4.9.0
  • realized acceptance filtering by setting parameter:
    • PCAN_ACCEPTANCE_FILTER_11BIT (default = 0x00000000000007FF)
    • PCAN_ACCEPTANCE_FILTER_29BIT (default = 0x000000001FFFFFFF)
    • PCAN_MESSAGE_FILTER (default = PCAN_FILTER_OPEN)
    • PCAN_RECEIVE_STATUS (default = PCAN_PARAMETER_ON)
  • realized suppression of status frames by setting parameter:
    • PCAN_ALLOW_STATUS_FRAMES (default = PCAN_PARAMETER_ON)
  • realized suppression of remote frames by setting parameter:
    • PCAN_ALLOW_RTR_FRAMES (default = PCAN_PARAMETER_ON)

Artifacts:

Version 0.12.2 (Build 1856 of November 1, 2023):

  • synchronized PCBUSB header with PCANBasic header from PEAK’s version 4.8.0
  • fixed a bug with pipe numbers for PCAN-USB FD devices (hardware version 6.0)
  • added missing linker option ‘-rpath /usr/local/lib’ to the C++ examples
  • updated the README file (unsupported parameter PCAN_HARD_RESET_STATUS)

Artifacts:

Version 0.12.1 (Build 1678 of July 9, 2023):

  • fixed a bug with endianess of 32-bit device id. (issue #384: PCAN-USB [Pro] FD)
  • reworked return values of CAN_Read(), CAN_ReadFD(), CAN_Write(), CAN_WriteFD()
  • reset USB pipe #4 after write timed out (CAN Write stalled; macOS 11 and higher)

Artifacts:

Version 0.12 (Build 1668 of January 31, 2023):

  • Realized setting of device id. for PCAN-USB FD devices
  • Reworked status frame handling:
    • fixed some bugs in the driver layer (all device types)
    • suppressed initial CAN FD status frame in CAN 2.0 mode
    • corrected mapping of bus error states to PCAN status
    • fixed a bug with CAN id. of status messages
    • CAN_Read(), CAN_ReadFD(), CAN_Write(), CAN_WriteFD(): return bus error states
  • SetValue(): Set default value if argument ‘BufferLength’ is equal to 0:
    • PCAN_LISTEN_ONLY (default = OFF)
    • PCAN_DEVICE_ID (default = 0)
    • PCAN_TRACE_LOCATION (default = cwd)
    • PCAN_TRACE_STATUS (default = OFF)
    • PCAN_TRACE_SIZE (default 0 = 100k frames!)
    • PCAN_TRACE_CONFIGURE (default = SINGLE_FILE)
  • GetValue(): Implemented missing parameters:
    • PCAN_ALLOW_RTR_FRAMES (read-only!)
    • PCAN_ALLOW_STATUS_FRAMES (read-only!)
    • PCAN_ALLOW_ERROR_FRAMES (read-only!)
    • PCAN_CONTROLLER_NUMBER (read-only)
    • PCAN_DEVICE_PART_NUMBER (read-only)
  • Made GetValue(PCAN_RECEIVE_EVENT) more robust if argument is greater than size of int
  • Reading of additional bytes from firmware info packet to distinguish product variants
    (issue #11: PCAN-USB FD (IPEH-004022) cannot be initialized)
  • Fixed a bug with stuck in CAN_Write() when errors on bus
    (note: the solution only works on macOS 11.0 and newer)
  • Fixed a bug with status frames not triggering the pipe for blocking read
  • Fixed a bug with getting the firmware version from USB device name
    (note: since firmware 3.x the version is not encoded in the device name anymore)
  • Fixed a bug with string length for bit-rate strings
  • Fixed a bug with GetValue(BITRATE_INFO_FD) w/o BRSE
  • Fixed a bug with size of parameter PCAN_TRACE_SIZE
  • Fixed some findings from static code analysis (Xcode and cppcheck)

Artifacts:

Version 0.11.2 (Build 1228 of July 31, 2022):

Version 0.11.1 (Build 1183 of April 30, 2022):

Version 0.11 (Build 1143 of January 31, 2022):

  • Built the library as Universal macOS Binary (macOS_Library_for_PCANUSB_v0.11.tar.gz).
  • Built the library for x86_64 architecture (OS_X_Library_for_PCANUSB_v0.11.tar.gz).
  • Synchronized PCBUSB header with PCANBasic header for v4.6.0.
  • Fixed a bug with PCAN_CHANNEL_CONDITION when used by another process.
  • Fixed an omission with export declaration for CAN_LookUpChannel.
  • Implemented parameter PCAN_FIRMWARE_VERSION (read-only).
  • Added error text for PCAN_ERROR_ILLMODE (all languages).
  • Corrected some French error text (acc. to Peak´s changes).
  • Return PCAN_ERROR_HWINUSE when interface is used by another process:1
    • CAN_GetValue: PCAN_LISTEN_ONLY, PCAN_RECEIVE_STATUS, PCAN_LISTEN_ONLY
  • Return PCAN_ERROR_ILLCLIENT if an invalid channel handle is given:1
    • CAN_GetValue: PCAN_RECEIVE_EVENT, PCAN_CHANNEL_CONDITION, PCAN_TRACE_LOCATION, PCAN_TRACE_STATUS, PCAN_TRACE_SIZE, PCAN_TRACE_CONFIGURE, PCAN_BITRATE_INFO, PCAN_BITRATE_INFO_FD, PCAN_BUSSPEED_NOMINAL, PCAN_BUSSPEED_DATA, PCAN_FIRMWARE_VERSION
    • CAN_SetValue: PCAN_DEVICE_ID, PCAN_TRACE_LOCATION, PCAN_TRACE_STATUS, PCAN_TRACE_SIZE, PCAN_TRACE_CONFIGURE
    • CAN_Reset
    • CAN_GetStatus
    • CAN_Read
    • CAN_ReadFD
    • CAN_Write
    • CAN_WriteFD
  • Added @rpath to the build environment (it got lost for some releases).
  • Code signed the Universal macOS Binary (Apple Development certificate).

  1. Peak-System harmonized its return codes in PCANBasic DLL version 4.6.0. Now the return codes matches my expectation. ↩ ↩2

Version 0.10.1 (Build 1016 of December 6, 2021):

  • Built the library as Universal macOS Binary (macOS_Library_for_PCANUSB_v0.10.1.tar.gz).
  • Built the library for x86_64 architecture (OS_X_Library_for_PCANUSB_v0.10.1.tar.gz).
  • Parameter PCAN_CHANNEL_VERSION displays machine architecture from utsname().
  • Fixed a bug with parameter PCAN_EXT_HARDWARE_VERSION for PCAN-USB Pro FD devices.
  • Solved an issue with file system relative paths that are not allowed in hardened programs in Python 2.7 under macOS.
  • Updated the C++ examples: Blocking Read using system call select().

Version 0.10 (Build 957 of December 22, 2020):

  • Support of PCAN-USB Pro FD devices, but only the first channel (CAN1).
  • Set linker options -install_name, -compatibility_version, and -current_version.
  • Synchronized the API with Peak´s PCANBasic version 4.5.0.440
  • Updated the Python example: reworked the output format.

Version 0.9 (Build 902 of June 25, 2020):

  • Data types from <MacTypes.h> as replacement for Peak´s usage of Windows BYTE, WORD, DWORD and UINT64 (field CAN ID is now 32-bit wide)
  • Synchronized the API to Peak´s PCANBasic version 4.4.0.288
  • Parameter PCAN_DEVICE_ID can be read in pre-initialization state
  • Fixed some bugs with status bit: PCAN_ERROR_QXMTFULL, PCAN_ERROR_XMTFULL, PCAN_ERROR_QOVERRUN, PCAN_ERROR_BUSLIGHT
  • Added a delay of 1 μsec in CAN_Write to run on macOS 10.15 (Catalina)

Version 0.8 SR1 (Build 787 of September 27, 2019):

  • Adapted trace-file headers to Peak’s changes in version 4.3.4.246

Version 0.8 (Build 689 of September 20, 2017):

  • Support of PCAN-USB FD devices in CAN 2.0 mode (CAN classic) and CAN FD mode!
  • Adapted the API according to Peak’s changes in version 4.2.0.134 and harmonized return codes with it.
  • Fixed issue #208 ‘CAN_Write stuck when errors on the bus are present’.
  • Conducted an intermediate solution for issue #246 (writing into a trace file).
  • Added run-path-relative install name to the library (using the \@rpath macro).

Version 0.7 (Build 558 of November 30, 2016):

  • Adapted the API according to Peak’s changes in version 4.1.0.96 and harmonized return codes with it.
  • Implemented parameter PCAN_CHANNEL_FEATURE and PCAN_BITRATE_INFO.

Version 0.6 (Build 425 of February 20, 2015):

  • Parameter PCAN_RECEIVE_EVENT returns a file descriptor to realize ‘blocking read’ by select()` as on the Linux implementation of the PCAN-Basic API.
  • Added two C++ examples and one Python example using the PCBUSB library

Version 0.5 (Build 370 of November 23, 2014):

  • Feature ‘Reading/Writing of parameter PCAN_DEVICE_NUMBER implemented.
  • Fixed issue #104 ‘Hot plugging was not detected by the library/driver’.
  • Fixed issue #117 ‘Permission for libPCBUSB.x.y.lib wrong’ (chmod 755).
  • Return codes of API functions harmonized with PCANBasic.dll (1.3.3.61).

Version 0.4 (Build 293 of February 23, 2014):

  • Time-stamps are now taken from CAN controller instead of taking them from the system clock.
  • Getting and setting of PCAN_* parameters reworked (to be almost compatible to the PCANBasic DLL, version 1.3).
  • Resetting of RCV queue and XMT queue on the CAN controller realized.

Version 0.3 (Build 235 of November 2, 2013):

  • Fixed issue #11 ‘All channel initialized by the application will be closed even if they are in use’.
  • CAN_Unitialize: closing all channel initialized by the application at once implemented.
  • CAN_Read: receive queue overrun handling reworked.
  • CAN_*: wrong function return codes corrected.
  • CAN_GetErrorText: language support for English, German, French, Italian and Spanish added.

Version 0.2 (Build 163 of September 8, 2013):

  • Minor changes

Version 0.1 (Build 149 of June 30, 2013):

  • Initial revision

Supported Devices

Only the following devices from PEAK-System Technik are supported:

  • PCAN-USB (product code: IPEH-002021, IPEH-002022)

Since version 0.8 (Build 689 of September 20, 2017):

  • PCAN-USB FD (product code: IPEH-004022)

For technical specifications, prices and delivery terms see PEAK´s website.

Known Bugs and Caveats

For a list of known bugs and caveats see the README file delivered with each release and tab Issues in the GitHub repo.

License

The PCBUSB library is freeware without any warranty or support!
Please note the copyright and license agreement.

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.
Qt is a registered trademark of The Qt Company Ltd. and its subsidiaries.
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.