Uwe Vogt, UV Software

Running CAN and CAN FD on Mac

The PCANBasic DLL provides an easy to use API (Application Programming Interface) for all PCAN interfaces from PEAK-System Technik, Darmstadt. For the realization of multi-vendor applications UV Software provides a CAN API V3 compatible wrapper library build upon PEAK´s PCANBasic DLL.

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 PCANBasic wrapper library provides a CAN API V3 compatible API for PEAK´s PCANBasic DLL on Windows.

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

A generic documentation of the CAN API V3 application programming interface can be found here.

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

Features

Feature Supported Remarks
CAN 2.0 :heavy_check_mark: Classical CAN
CAN FD :heavy_check_mark: Flexible Data-rate CAN
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
29-bit identifier (XTD) :heavy_check_mark: CAN 2.0 and CAN FD
Remote frames (RTR) :heavy_check_mark: CAN 2.0 only
Error frames (ERR) :heavy_check_mark: CAN 2.0 and CAN FD
Error indicator (ESI) :heavy_check_mark: CAN FD only
Bit-rate switching (BRS) :heavy_check_mark: CAN FD only
Silent operation (MON) :heavy_check_mark: CAN 2.0 and CAN FD
Identifier filtering :heavy_check_mark: CAN 2.0 and CAN FD
Operation modes:    
- Monitor mode enable/disable (MON) :heavy_check_mark: disabled by default
- Error frames enable/disable (ERR) :heavy_check_mark: disabled by default
- Remote frames disable/enable (NRTR) :heavy_check_mark: enabled by default
- Extended frames disable/enable (NXTD) :heavy_check_mark: enabled by default
- Shared access enable/disable (SHRD) :x: not supported
- Non-ISO CAN FD enable/disable (NISO) :x: HW settings of the device cannot be changed by the library
- Bit-rate switching enable/disable (BRSE) :heavy_check_mark: disabled by default
- CAN FD operation enable/disable (FDOE) :heavy_check_mark: disabled by default
Bit-rate settings:    
- Pre-defined bit-timing indexes :heavy_check_mark: acc. CiA CANopen specification
- BTR register values :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: queue size depends on the hardware
- Polling :heavy_check_mark: return immediately
- Timed out :heavy_check_mark: wait up to 65’534 milliseconds
- Blocking read :heavy_check_mark: wait infinitely
Message transmission:    
- Acknowledged write :x: not supported by the firmware
- Buffered write :heavy_check_mark: buffer size depends on the hardware
Software Development Kit:    
- CAN API V3 :heavy_check_mark: C API and C++ API by UV Software
- Dynamic link library :heavy_check_mark: u3canpcb.dll, uvPeakCAN.dll
- Static library :heavy_check_mark: u3canpcb.lib, uvPeakCAN.lib
- 32-bit version (x86) :heavy_check_mark: supported
- 64-bit version (x64) :heavy_check_mark: supported
- Source code :heavy_check_mark: BDS-2-Clause or GPL-3.0-or-later
- Python wrapper :heavy_check_mark: Python 3
- macOS wrapper :heavy_check_mark: macOS Driver and SDK
- Utilities :heavy_check_mark: CLI utilities can_moni and can_test
- Examples :heavy_check_mark: C, C++, Python

Change-log

Version 0.5.2 (Commit b429a55 of August 2, 2024):

  • Updated CAN API V3 sources to rev. 1356
  • Updated GoogleTest framework to v1.15.0
  • Updated CAN API V3 testing to rev. 1373
  • Updated CAN API V3 utilities to rev. 1375
    • Added an option to send extended frames (can_test)
    • Fixed a bug with receiving extended frames (can_moni)

Version 0.5.1 (Commit af5d678 of June 12, 2024):

  • Updated PCANBasic DLL (version 4.9.0)
  • Updated CAN API V3 sources to rev. 1312
  • Updated CAN API V3 testing sources 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)
  • Integrated generic CAN API V3 Utilities (rev. 1323)
  • Updated release documents

Version 0.5 (Commit af5d678 of April 23, 2024):

  • Added an unified version file
  • Recreated the library projects
  • Updated all MSBuild environments
  • Updated PCANBasic DLL (version 4.8.2)
  • 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
  • Implemented identifier acceptance filtering
  • Added test suites for acceptance filtering
  • Added filtering option to utility can_moni
  • Added option /LIST-BITRATES to the utilities
  • Fixed a bug with flag ESI in TC05.20
  • Fixed a bug with Peak vs. CiA bit-rate settings
  • Fixed compiler warnings with legacy CAN 2.0 frame format
  • Updated the Python wrapper
  • Updated the examples

Version 0.4.7 (Commit 6734151 November 8, 2023):

  • Updated PCANBasic DLL (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

Version 0.4.6 (Commit ac17786 September 19, 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
  • Made the utilities more generic
  • Updated the Python examples

Version 0.4.5 (Commit 0b3f025 August 25, 2023):

  • Migrated to VS 2022 (version 17.7.2)
  • Updated PCANBasic DLL (version 4.7.1)
  • Updated CAN API V3 sources to rev. 1155 and applied 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
      • 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
        • Checked 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 handling of status and error frames
  • Removed old bit-rate mapping functions
  • Fixed a bug with property GET_DEVICE_NAME
  • Synchronized the Utilities with MacCAN-Wrapper
    • Fixed an issue with option --verbose
  • Added CAN API V3 Tests with GoogleTest

Version 0.4.4 (Commit 501c6e6 August 3, 2022):

  • Updated CAN API V3 sources to rev. 1082
  • Fixed a bug with transceiver off in function can_reset
  • Fixed a bug with field SAM in BTR0BTR1 register
  • Fixed a bug with BTR0BTR1 register in CAN FD mode
  • Fixed a bug with mapping CAN FD bit-rate settings to Peak bit-rate string
  • Fixed a bug with uncleared initialization flag when all channels released
  • Realized feature NXTD and NRTR (software solution)
  • Updated class CPeakCAN (some property keys)
  • Updated the trial program
  • Updated the utilities

Version 0.4.3 (Commit 7ffb5a3 of February 7, 2022):

  • Updated CAN API sources to rev. 1036
  • Fixed a bug with message flag sts on reception
  • Fixed a bug with getting properties from device
  • Changed resolution of property GET_BUSLOAD
  • Implemented device property GET_CAN_CHANNEL
  • Added a check for minimum required PCANBasic DLL version (4.5 or later)
  • Added two operations to class CPeakCAN to query channel information
  • Updated the utilities to get the list of CAN channels from the library

Version 0.4.2 (Commit cede7f7 of January 4, 2022):

  • Updated PCANBasic DLL (version 4.6.0)
  • Updated CAN API sources to rev. 1020 and applied the changes
  • Resolved firmware version vs. software version confusion
  • Fixed an issue with missing copy constructor (avoid dynamic allocation of class members)
  • 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
  • Fixed some issues with vendor-specific property values
  • Fixed findings from static code analysis (incl. C statement style)
  • Updated Python examples (although they do not work under Windows)
  • Updated my beloved utilities (and added GPL license text)

Version 0.4.1 (Commit 60fa2d4 of June 7, 2021):

  • Updated to PCANBasic DLL version 4.5.4
  • Switched to a dual-license: BSD-2-Clause OR GPL-3.0-or-later
  • Added a check operation mode bit FDOE when bit BRSE is set
  • 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
  • Fixed an out-of-bound violation in companion module can_btr
  • Fixed a but with casting from CAN API channel to PCAN handle
  • Fixed a mistake with channel name displayed instead of device name
  • Repaired the C++ examples; Python examples are still broken

Version 0.4 (Commit 53db869 of February 7, 2021):

  • Applied changes from CAN API V3 specification (rev. 951 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.3 (Commit 8514061 of January 15, 2021):

  • Last sources from subversion repo to build version 3.3 (old versioning scheme)

Supported Devices

For a list of supported device see PEAK´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

Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries.
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.
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.