macOS User-Space Driver for PCAN-USB Interfaces from PEAK-System

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 and 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 Readme

PCBUSB Library

The dynamic library libPCBUSB is running under macOS 10.13 and later (x86_64 architecture). The API is almost compatible to PEAK´s PCANBasic DLL on Windows. See the MacCAN website for details.

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 :x: not realized yet
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: binary for x86_64 only
Static library (.a) :heavy_check_mark: not available
Source code :x: not available
M1 Chip :x: not supported
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 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.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.

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