macOS® User-Space Driver and SDK for 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.
Download Sources (zip) Sources (tar.gz) @GitHub
MacCAN-TouCAN Driver
The macOS driver for TouCAN USB Interfaces from Rusoku is based on MacCAN-Core which 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.
The GitHub repository contains the source code for the MacCAN-TouCAN driver and several alternatives to build dynamic libraries for macOS, either as a C++ class library (libTouCAN), or as a CAN API V3 wrapper library (libUVCANTOU), as well as some example programs and my beloved CAN utilities can_moni and can_test.
The MacCAN-TouCAN SDK comes with a CAN API V3 compatible 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. See header file CANAPI.h for the CAN API V3 wrapper specification.
Features
| Feature | Supported | Remarks | |
|---|---|---|---|
| CAN 2.0 |  |
Classical CAN | |
| CAN FD |  |
Flexible Data-rate CAN | |
| Bit-rate, CAN 2.0 | |
high speed: up to 1 Mbps | |
| Bit-rate, CAN FD | |
nominal: up to 1 Mbps data phase: up to 8 Mbps |
|
| 11-bit identifier (STD) | |
CAN 2.0 | |
| 29-bit identifier (XTD) | |
CAN 2.0 | |
| Remote frames (RTR) | |
CAN 2.0 | |
| Error frames (ERR) | |
CAN 2.0 | |
| Error indicator (ESI) | |
CAN FD only | |
| Bit-rate switching (BRS) | |
CAN FD only | |
| Listen-only mode (MON) | |
CAN 2.0 | |
| Identifier filtering | |
CAN 2.0, Std. and Xtd. IDs | |
| Operation modes: | |||
| - Monitor mode enable/disable (MON) | |
disabled by default | |
| - Error frames enable/disable (ERR) | |
disabled by default | |
| - Remote frames disable/enable (NRTR) | |
not supported | |
| - Extended frames disable/enable (NXTD) | |
not supported | |
| - Shared access enable/disable (SHRD) | |
not supported | |
| - Non-ISO CAN FD enable/disable (NISO) | |
not supported | |
| - Bit-rate switching enable/disable (BRSE) | |
not supported | |
| - CAN FD operation enable/disable (FDOE) | |
not supported | |
| Bit-rate settings: | |||
| - Pre-defined bit-timing indexes | |
acc. CiA CANopen specification | |
| - BTR register values | |
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) | |
up to 64K CAN messages | |
| - Polling | |
return immediately | |
| - Timed out | |
wait up to 65’534 milliseconds | |
| - Blocking read | |
wait infinitely | |
| Message transmission: | |||
| - Acknowledged write | |
not supported | |
| - Buffered write | |
buffer size depends on the hardware | |
| Software Development Kit: | |||
| - VSCP CANAL API | |
not available | |
| - CAN API V3 | |
C API and C++ API by UV Software | |
| - Dynamic library | |
libUVCANTOU.dylib, libTouCAN.dylib
|
|
| - Static library | |
libUVCANTOU.a, libTouCAN.a
|
|
| - Source code | |
BDS-2-Clause or GPL-3.0-or-later | |
| - Apple silicon | |
and Intel architecture | |
| - Swift wrapper | |
Swift 5.5 (including SPM) | |
| - Python wrapper | |
Python 3.8 | |
| - Windows wrapper | |
not available | |
| - Utilities | |
CLI utilities can_moni and can_test
|
|
| - Examples | |
C, C++, Swift, Python |
Change-log
Version 0.3 (Commit e8ab458 of April 25, 2024):
- Removed all CANAL references from the project
- Created a new TouCAN USB command interface
- Added common
Version.hto the project - Updated CAN API V3 sources to rev. 1270
- Updated CAN API V3 testing sources to rev. 1273
- Removed unused attributes from class
CTouCAN - Changed the resolution of
CTimerto 64 bit - Implemented identifier acceptance filtering
- Added test suites for acceptance filtering
- Added filtering option to utility
can_moni - Added option
--list-bitratesto the utilities - Fixed a bug with macro
DLC2LEN() - Updated
Makefiles andbuild_no.sh - Improved compiler and linker flags
- Updated the Python wrapper and examples
- Updated the Swift wrapper and examples
- Updated the deployment rules
Version 0.2.6 (Commit 1b0d095 of November 12, 2023):
- Updated MacCAN-Core sources to rev. 1816
- Updated CAN API V3 sources to rev. 1212
- Updated CAN API V3 testing sources to rev. 1219
- Updated GoogleTest to version 1.14.0
- Updated deployment rules
- Added linker flag
-rpath /usr/local/lib(C++ examples)
Version 0.2.5 (Commit 032d7bc of September 24, 2023):
- Updated MacCAN Core sources to rev. 1757 (core 0.4)
- Updated CAN API V3 sources to rev. 1187 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
fdoeandbrsefromstruct 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
fdoeandbrsefromstruct 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_ILLPARAon 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
strtolif 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 have been shifted by 8)
- Fixed a bug with saturation of CAN FD DLC conversion
- Updated description of compiler switches
- Reworked formatting of message flags
- Activated suppression of extended frames and remote frames
- Activated time-out handling for reading asynchronous pipes
- Fixed a bug with terminating the worker thread
- Reworked handling of status frames
- Added CAN API V3 Tests with GoogleTest (rev. 1205)
- Added Rusoku-specific bit-rate defaults
- Made the utilities more generic
- Updated the Python wrapper
- Updated the Swift wrapper
- Updated the trial program
- Updated the examples
Version 0.2.4 (Commit 46ecb27 of August 5, 2022):
- Updated CAN API V3 sources to rev. 1082
- Realized new property
GET_CAN_CLOCK - Applied changes from module
can_btr - Updated CAN API V3 Testing sources to rev. 1084
- Fixed a possible bug with USB device name length
- Fixed a bug with missing check of the CAN clock frequency (50MHz)
- Fixed a bug with tx message flags in the Swift wrapper (SwiftCAN issue #23)
- Fixed some findings from static code analysis
- Added a scanner for test case annotations
- Added
@rpathto the library Makefiles
Version 0.2.3 (Commit c1a3633 of February 25, 2022):
- Updated MacCAN-Core sources to rev. 1090
- Removed class
CMacCANfrom project (R.I.P.) - Updated CAN API sources to rev. 1036 and applied the changes
- Fixed a bug with probing a device when it is used by another process
- Fixed a bug with string length of device vendor
- Added operations to class
CTouCANto query channel information - Updated the utilities to get the list of channels from library
- Moved unit test suites into
$(PROJROOT)/Tests/UnitTests - Added
cppchecktarget toMakefileof the Trial program - Updated the Swift and Python examples
Version 0.2.2 (Commit d93fbfe of December 27, 2021):
- Reworked the driver layer (to solve the copy constructor issue #16):
- rename sub-folders in
$(PROJROOT)/Sources - switch CAN API V3 wrapper from C++ to C
- create a lot of new driver layer modules
- prepare the driver to support further devices
- no obvious functional changes
- rename sub-folders in
- Added a Swift wrapper including SPM configuration
- Added two simple Swift examples for sending and receiving CAN frames
- Added an Xctest target for CAN API V3 C interface to the trial program
- take over all test suites and test cases from MacCAN-KvaserCAN
- test execution: 131 tests, 6 failed - but false positives
- Fixed a testing issue with unsupported acknowledge of transmit messages
- Fixed a testing issue with unsupported bit-timing index 1 (800kbps)
- Fixed a bug with unchecked device handle
- Fixed a bug with missing header file in class
CTouCAN - Fixed an omission with forgotten TouCAN specific properties
- Fixed a bug with non-boolean return value in a boolean function
- Fixed an issue with deprecated function
IOMasterPort(first deprecated in macOS 12.0) - 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 - Updated my beloved utilities
- Updated the C++ examples
Version 0.2.1 (Commit 0b4a139 of June 5, 2021):
- Fixed the hibernation issue (issue #11)
- Fixed a bug when trying to send a status message
- Fixed a bug when the channel number is invalid
- Fixed a bug when requested operation mode is not supported
- Fixed an out-of-bound violation in companion module
can_btr - Fixed some issues from code analysis
Version 0.2 (Commit 52f784a of February 28, 2021):
- Worked in the latest changes from MacCAN-Core (SVN rev. 986)
- Added a CAN API V3 compatible Python wrapper and two Python examples
- Added two simple C++ examples for sending and receiving CAN frames
- Weakened the sizeof check while reading numerical properties
- Fixed a bug with a locked mutex when device is not present
- Fixed a bug with signaling a wait condition
- Updated the trial program and the utilities
Version 0.1 SR 1 (Commit e89ac9c of December 30, 2020):
- Fixed a bug with looping over the list of registered devices
- Fixed a bug with non-dereferenceable void* array
- Fixed a bug with
SIGNAL_WAIT_CONDITION - Plastic surgery
Version 0.1 (Commit 461df7c of April 19, 2020):
- First release of the MacCAN-TouCAN driver
Supported Devices
Only the following devices from Rusoku Technologies are supported:
- TouCAN USB (Model F4FS1)
For technical specifications, prices and delivery terms see Rusoku´s website.
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.
SPDX-License-Identifier: BSD-2-Clause OR GPL-3.0-or-later
Trademarks
Mac and macOS are trademarks of Apple Inc., registered in the U.S. and other countries.
Windows is a registered trademark of Microsoft Corporation in the United States and/or other countries.
Linux is a registered trademark of Linus Torvalds.
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.