https://github.com/djarek/canary
A lightweight implementation of Linux SocketCAN bindings for ASIO/Boost.ASIO
https://github.com/djarek/canary
asio boost-asio can can-bus cpp11 socketcan
Last synced: 27 days ago
JSON representation
A lightweight implementation of Linux SocketCAN bindings for ASIO/Boost.ASIO
- Host: GitHub
- URL: https://github.com/djarek/canary
- Owner: djarek
- License: bsl-1.0
- Created: 2020-01-25T20:16:10.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2022-07-31T00:50:28.000Z (over 3 years ago)
- Last Synced: 2026-01-13T22:14:25.488Z (about 1 month ago)
- Topics: asio, boost-asio, can, can-bus, cpp11, socketcan
- Language: C++
- Size: 67.4 KB
- Stars: 27
- Watchers: 3
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE_1_0.txt
Awesome Lists containing this project
README
# Canary
Language|Build|Coverage|License|Documentation|
|-------|-----|--------|-------|-------------|
|[](https://en.wikipedia.org/wiki/C%2B%2B#Standardization) | [](https://dev.azure.com/damianjarek93/canary/_build/latest?definitionId=11&branchName=master) | [](https://codecov.io/gh/djarek/canary) | [](https://opensource.org/licenses/BSL-1.0) | [](doc/generated/standardese_entities.md)
## Introduction
**Canary** is a thin, C++11 wrapper over the SocketCAN API in Linux, which
enables communication over [CAN bus](https://en.wikipedia.org/wiki/CAN_bus)
using idioms from the [Boost.ASIO](https://github.com/boostorg/asio) and
[ASIO](https://github.com/chriskohlhoff/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:
```bash
mkdir build
cd build
cmake ..
make install
```
After installation, a project built with CMake can consume the library using
`find_package`:
```cmake
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:
```bash
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](https://github.com/hartkopp/can-isotp). 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](doc/generated/standardese_entities.md)
- [API Reference - files](doc/generated/standardese_files.md)