Repository files navigation

This library implements Controller Area Network (CAN) communications on Linux using the SocketCAN interfaces. This provides a network socket interface to the CAN bus.

Linux SocketCAN

Please see thedocumentation for details about the Rust API provided by this library.

Version 3.0 adds integrated support for async/await, with the most popular runtimes,tokio, async-std, andsmol. To get started we have already merged thetokio-socketcan crate into this one and implementedasync-io.

Unfortunaly this required a minor breaking change to the existing API, so we bumped the version to 3.0.

The async support is optional, and can be enabled with a feature for the target runtime:tokio,async-std, orsmol.

• Support for Rust async/await
  • All oftokio-socketcan has been merged into this crate and will be available with anasync-tokio build feature.
  • #41 Added initial support forasync-io for use withasync-std andsmol
  • SplitSocketOptions trait out ofSocket trait for use with async (breaking)
  • Added cargo build features fortokio orasync-io.
  • Also created specific build features forasync-std andsmol which just bring in theasync-io module and alias the module name toasync-std orsmol, respectively, and build examples for each.

• MadeCanAddr pulic and added functions to help interact with low-level sockaddr types. Sockets can now be opened with an address.
• Can create anError directly from aCanErrorFrame orstd::io::ErrorKind.
• #46 Applications can create error frames:
  • CanErrorFrame::new() now works.
  • CanErrorFrame::new_error() is similar but more intuitive using a raw ID word.
  • From<CanError> for CanErrorFrame to create an error frame from aCanError.
• AddedFrame::from_raw_id() andFrame::remote_from_raw_id()
• Bumped MSRV to 1.65.0

A number of items still did not makei into a release. These will be added in v3.x, coming soon.

• Issue#22 Timestamps, including optional hardware timestamps
• Issue#32 Better coverage of the Netlink API to manipulate the CAN interfaces programatically.
• Better documentation. This README will be expanded with basic usage information, along with better doc comments, and perhaps creation of the wiki

The current version of the crate targets Rust Edition 2021 with an MSRV of Rust v1.65.0.

Note that, at this time, the MSRV is mostly diven by use of theclap v4.0 crate for managing command-line parameters in the utilities and example applications. The core library could likely be built with an earlier version of the compiler if required.

Thetokio-socketcan crate was merged into this one to provide async support for CANbus using tokio.

This is enabled with the optional feature,tokio.

This is a simple example of sending data frames from one CAN interface to another. It is included inthe example applications astokio_bridge.rs.

use futures_util::StreamExt;use socketcan::{tokio::CanSocket,CanFrame,Result};use tokio;#[tokio::main]asyncfnmain() ->Result<()>{letmut sock_rx =CanSocket::open("vcan0")?;let sock_tx =CanSocket::open("can0")?;whileletSome(Ok(frame)) = sock_rx.next().await{ifmatches!(frame,CanFrame::Data(_)){            sock_tx.write_frame(frame)?.await?;}}Ok(())}

New support was added for theasync-io runtime, supporting theasync-std andsmol runtimes.

This is enabled with the optional feature,async-io. It can also be enabled with either feature,async-std orsmol. Either of those specific runtime flags will simply build theasync-io support but then also alias theasync-io submodule with the specific feature/runtime name. This is simply for convenience.

Additionally, when building examples, the specific examples for the runtime will be built if specifying theasync-std orsmol feature(s).

This is a simple example of sending data frames from one CAN interface to another. It is included inthe example applications asasync_std_bridge.rs.

use socketcan::{async_std::CanSocket,CanFrame,Result};#[async_std::main]asyncfnmain() ->Result<()>{let sock_rx =CanSocket::open("vcan0")?;let sock_tx =CanSocket::open("can0")?;loop{let frame = sock_rx.read_frame().await?;ifmatches!(frame,CanFrame::Data(_)){            sock_tx.write_frame(&frame).await?;}}}

Integrating the full suite of tests into a CI system is non-trivial as it relies on avcan0 virtual CAN device existing. Adding it to most Linux systems is pretty easy with root access, but attaching a vcan device to a container for CI seems difficult to implement.

Therefore, tests requiringvcan0 were placed behind an optional feature,vcan_tests.

The steps to install and add a virtual interface to Linux are in thescripts/vcan.sh script. Run it with root proveleges, then run the tests:

$ sudo ./scripts/vcan.sh$ cargotest --features=vcan_tests