djarek / canary

A lightweight implementation of Linux SocketCAN bindings for ASIO/Boost.ASIO

Canary

Language	Build	Coverage	License	Documentation

Introduction

Canary is a thin, C++11 wrapper over the SocketCAN API in Linux, which enables communication over CAN bus using idioms from the Boost.ASIO and ASIO libraries.

Dependencies

Canary depends only on ASIO and the C++11 standard library. By default, it uses Boost.ASIO, but can be configured to use standalone ASIO. The CANARY_STANDALONE_ASIO macro makes the library depend only on standalone ASIO.

Running tests requires lightweight test facilities from Boost.Core (which is a header only library).

Installation

Canary is header-only, so you only need to add the include directory to the include paths in your build system. An install target is available in CMake which will install the headers and a CMake find_package configuration script for easy consumption in projects built with CMake:

mkdir build
cd build
cmake ..
make install

After installation, a project built with CMake can consume the library using find_package:

find_package(canary REQUIRED)
target_link_libraries(my_target PUBLIC canary::canary)

Running tests

Tests require the existence of 2 virtual CAN interfaces - vcan0 and vcan1, which can be created with the create_vcans.sh script:

sudo tools/create_vcans.sh vcan0 vcan1

Tests can be run using the standard test target generated by CMake:

mkdir build
cd build
cmake ..
make test

Supported protocols

Raw CAN frames

Canary exposes the raw CAN frame socket API from Linux's SocketCAN module. When using this API, data read from the socket will contain a frame header at the start. Users can parse it on their own, or use the provided frame_header class, which is trivially copyable and can be filled by reading from the socket directly. Note that the header is not an exact CAN frame header - the underlying API does not expose lower-level protocol detail, such as CRCs.

ISO-TP kernel module

Canary provides a wrapper for the in-kernel ISO 15765-2(also known as ISO-TP) implementation which is loadable as a kernel module, see more details. When using this transport-layer protocol, a socket is bound to a CAN ID pair (rx, tx), often referred to as "ISO-TP addresses". If more addresses are to be used, a socket per (rx, tx) pair must be constructed.

Note: The ISO-TP kernel module must either be loaded prior to creating an ISO-TP socket, or the module must be configured to be loaded on socket creation attempt (using depmod -A after installation)

Documentation

• Examples (TODO)
• API Reference - entities
• API Reference - files