macOS Library for PCAN-USB Interfaces
macOS Library for PCAN-USB Interfaces
Developed by UV Software, Berlin.

Running CAN and CAN FD on Mac


The PCBUSB library realizes an 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. PCAN-USB FD devices can be operated in CAN 2.0 and CAN FD mode.

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.

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.

Except where otherwise noted, all software offered below are freeware without any warranty or support. Please note the copyright and license agreements.

Downloads

PCBUSB Library


The PCBUSB library realizes a 'PCAN-USB Driver for macOS' using Apple's IOUSBKit. 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. See the doxygen documentation and the header-file for details.

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)

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; see issue #11)
  • Added missing linker option '-rpath /usr/local/lib' to the C++ examples (see issue #17)
  • Updated the README file (unsupported parameter PCAN_HARD_RESET_STATUS)

Version 0.12.1 (Build 1768 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)

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)

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

  • Fixed the CAN FD URB issue #9 ('Messages lost on high CAN FD bit-rates').
  • Added an installation instruction (after all these years).

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

  • Fixed the Monterey issue #6 ('Driver not loaded').
  • Fixed some findings from static code analysis.
  • Added `@rpath` to all build environments.
  • Improved the installation script.
  • Updated the README file.

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

  • 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:
    - CAN_GetValue: PCAN_LISTEN_ONLY, PCAN_RECEIVE_STATUS, PCAN_LISTEN_ONLY
  • Return PCAN_ERROR_ILLCLIENT if an invalid channel handle is given:
    - 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
  • * PEAK-System harmonized its return codes in PCANBasic DLL version 4.6.0. Now the return codes matches my expectation.
  • Added `@rpath` to the build environment (it got lost for some releases).
  • Code signed the Universal macOS Binary (Apple Development certificate).

Version 0.10 SR1 (Build 1016 of December 6, 2021):

  • 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 usec 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 Febuary 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

Older versions of the PCBUSB library can be downloaded from GitHub (binaries only).

 Download

 Readme

 Show doxygen

MacCAN Monitor App


The MacCAN Monitor App is a demo program to show the functionally of the PCBUSB library.

The program displays received CAN messages in a table view. Furthermore it is possible to send single standard CAN messages with 0 to 8 data bytes.

Version 0.5 SR1 (Service release of November 4, 2023):

  • Fixed a bug with pipe numbers for PCAN-USB FD devices (hardware version 6.0)
  • Added missing linker option '-rpath /usr/local/lib' (issue #8 with Xcode 15)
  • Included version 0.12.2 of the PCBUSB library

Version 0.5 (Release of February 4, 2023):

  • Trace files are written to the users home directory
  • The PCBUSB wrapper has been updated
  • Included version 0.12 of the PCBUSB library

Version 0.4 (Release of December 10, 2021):

  • Added support for Apple Silicon (M1 chip)
  • Fixed some deprecated methods with NSAlert
  • Included version 0.10 of the PCBUSB library

Version 0.3 (Release of July 2, 2020):

  • Check for required version of the PCBUSB library
  • Write to file: trace file instead of log file
  • Included version 0.9 of the PCBUSB library

Version 0.2 SR4 (Service release of September 21, 2017):

  • Included version 0.8 of the PCBUSB library

Version 0.2 SR3 (Service release of December 1, 2016):

  • Included version 0.7 of the PCBUSB library

Version 0.2 SR2 (Service release of February 21, 2015):

  • Included version 0.6 of the PCBUSB library

Version 0.2 SR1 (Service release of November 24, 2014):

  • Included version 0.5 of the PCBUSB library

Version 0.2 (Release of February 24, 2014):

  • Minor changes (to run with version 0.4 of the PCBUSB library)

Version 0.1 (Release of September 8, 2013):

  • 1st release (demo version)

Older versions of the MacCAN Monitor App can be downloaded from here.

The MacCAN Monitor App and its source code is also available on GitHub (BSD-2-Clause License).

 Download

 Readme

 Play Video

Command-line Tool


If you prefer to work in a terminal session, here is a command-line version of the CAN Monitor application.

The command-line tool 'can_moni' runs as a standalone program, therefor it is not necessary to install the PCBUSB library to run the program.

Version 0.6 (Build 1986 of July 29, 2024):

  • Realized new program options:
    - '--no-status-frames' suppress reception of status frame
    - '--no-remote-frames' suppress reception of remote frame
    - '--code=<id>' acceptance code for 11-bit IDs
    - '--mask=<id>' acceptance mask for 11-bit IDs
    - '--xtd-code=<id>' acceptance code for 29-bit IDs
    - '--xtd-mask=<id>' acceptance mask for 29-bit IDs
    - '--trace=(ON|OFF)' write a trace file (default=OFF)
  • Compiled against PCBUSB v0.13 sources as Universal macOS Binary
  • Version 0.5 SR8 (Build 1865 of November 3, 2023):

    • Fixed a bug with pipe numbers for PCAN-USB FD devices (hardware version 6.0)
    • Compiled against PCBUSB v0.12.2 sources as Universal macOS Binary

    Version 0.5 SR7 (Build 1792 of July 15, 2023):

    • Fixed some bugs with bit-rate string conversion (SAM issue among others)
    • Compiled against PCBUSB v0.12.1 sources as Universal macOS Binary

    Version 0.5 SR6 (Build 1679 of February 2, 2023):

    • Display device id. when listing available CAN interfaces (option -T).
    • Fixed a bug with default CAN FD bit-rate settings (250kbps:2Mbps).
    • Compiled against PCBUSB v0.12 sources as Universal macOS Binary.

    Version 0.5 SR5 (Build 1240 of July 31, 2022):

    • Compiled against PCBUSB v0.11.2 sources as Universal macOS Binary.

    Version 0.5 SR4 (Build 1153 of February 5, 2022):

    • Fixed a bug with channel state 'occupied' when used by another process.
    • Compiled against PCBUSB v0.11 sources as Universal macOS Binary.

    Version 0.5 SR3 (Build 1030 of December 7, 2021):

    • Compiled against PCBUSB v0.10.1 sources as Universal macOS Binary (requires macOS 11.x or 12.x)

    Version 0.5 SR2 (Build 962 of December 22, 2020):

    • Compiled against PCBUSB v0.10 sources (PCAN-USB Pro FD CAN1)

    Version 0.5 SR1 (Build 915 of June 28, 2020):

    • Compiled against PCBUSB v0.9 sources (<MacTypes.h>)

    Version 0.5 (Build 850 of December 1, 2019):

    • Reworked command-line option handling:
    • --listen-only - monitor mode (transmitter is off)
    • --list-boards - list all supported CAN interfaces
    • --test boards - list all available CAN interfaces
    • Compiled against PCBUSB v0.8.1 sources

    Version 0.4 (Build 698 of September 22, 2017):

    • Support of PCAN-USB FD interface

    Version 0.3 (Build 371 of November 23, 2014):

    • Time-stamps are taken from CAN controller

    Version 0.2 (Build 138 of May 17, 2013):

    • Initial revision

    Version 0.1 (Build 86 of July 6, 2012):

    • reverted

    Older versions of the 'can_moni' tool can be downloaded from GitHub.

    A Linux version of the 'can_moni' tool using BerliOS SocketCAN can be downloaded from here.

 Download

 Readme

 Other Stuff

Tips and Tricks

Blocking Read


With the PCBUSB library blocking reading of CAN messages can be realized with a file descriptor and the Posix system call select. The file descriptor is – in contrast to the Windows DLL – provided by the driver. An example can be found as a Gist in the MacCAN GitHub repo.


Python Wrapper


To use the PCBUSB library in a cross-platform Python project, the Python wrapper from PEAK's PCANBasic DLL can be used without further modifications. You just have to import the file PCANBasic.py from the PCANBasic DLL version 4.5.1 or higher and install the PCBUSB library in the library search path (e.g. in /usr/local/lib).


Monterey and/or Apple Silicon


In case you have problems using the PCBUSB library on macOS Monterey (12.x) and/or Apple Silicon (M1 chip), there is a toubleshooting guide as a Gist to help you isolate the problem.

This and That

Qt Integration


The Qt Serial Bus API is delivered with a plug-in for PCAN interfaces from PEAK-System Technik. Under macOS this plug-in uses the PCBUSB library. You can use it to create beautiful Qt applications that run CAN and CAN FD on a Mac with PCAN-USB interfaces. The Qt CAN Bus example runs out-of-the-box, it only requires version 0.9 or higher of the PCBUSB library being installed.

Many thanks to Miklós Márton fom Digitroll Kft. AG Electronics who patched the PCAN-Plugin for use with macOS. Great job!


MacCAN-Core


Running CAN and CAN FD on Mac is the mission of the MacCAN project. MacCAN-Core 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.

TouCAN USB Interfaces from Rusoku

Rusoku Technologies is an innovative engineering team based in Lithuania, Europe. They offer CAN adapter at a reasonable price. Drivers and utilities for Windows and Linux are available as open-source. A macOS user-space driver for TouCAN USB interfaces from Rusoku is provided by UV Software. Visit MacCAN-TouCAN to learn more.

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 CAN Leaf Interfaces from Kvaser is provided by UV Software. Visit MacCAN-KvaserCAN to learn more.


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

CAN API V3

The goal of the CAN API V3 project is to have a multi-vendor, cross-platform CAN Interface API (Application Programming Interface). Each CAN adapter manufacturer provides its own CAN software SDK (Software Development Kit) for the development of CAN applications based on the provided SDK. Unfortunately, the APIs of the different manufacturers are not compatible with each other. The CAN Interface API by UV Software (CAN API V3) solves the problems arising from this incompatibility.

A documentation of the CAN API V3 application programming interface and a list of CAN API V3 compatible wrapper implementations for Windows®, macOS® and Linux® can be found here.

MacCAN Monitor App


Play Video

Quick Time Video (Length 0:00:27, Size 25MB)
Copyright © 2013-2023 by UV Software, Berlin.



Links

PEAK-System


PEAK-System

You CAN get it...

Hardware, software and system solutions for many sectors including automotive, aircraft, machinery and equipment building and consumer goods.

https://www.peak-system.com


Qt Serial Bus API


Qt

You CAN use it...

The Qt Serial Bus API supports CAN adapters from PEAK-System, among others. Under macOS it requires the installation of the PCBUSB library.

https://doc.qt.io/qt-6/qtserialbus-index.html


CAN Interface API, V3


GitHub

You CAN get more...

CAN API V3 is a wrapper specification to have a uniform CAN Interface API for various CAN interfaces from different vendors running under multiple operating systems.

https://mac-can.github.io/

Donations


Donations to my work are gratefully welcome.

Contact

© 2012-2024 UV Software, Berlin. All rights reserved. Facebook Twitter LinkedIn Mail
Privacy Policy Imprint
  2024-07-29