Crate socketcan

SocketCAN support.

The Linux kernel supports using CAN-devices through a network-like API (see https://www.kernel.org/doc/Documentation/networking/can.txt). This crate allows easy access to this functionality without having to wrestle libc calls.

An introduction to CAN

The CAN bus was originally designed to allow microcontrollers inside a vehicle to communicate over a single shared bus. Messages called frames are multicast to all devices on the bus.

Every frame consists of an ID and a payload of up to 8 bytes. If two devices attempt to send a frame at the same time, the device with the higher ID will notice the conflict, stop sending and reattempt to sent its frame in the next time slot. This means that the lower the ID, the higher the priority. Since most devices have a limited buffer for outgoing frames, a single device with a high priority (== low ID) can block communication on that bus by sending messages too fast.

The CAN Flexible Data-Rate (CAN FD) standard extended the data payload up to 64 bytes and added the ability to increase the the bitrate for the data bit in the frame.

The Linux socketcan subsystem makes the CAN bus available as a regular networking device. Opening a network interface allows an application to receive all CAN messages from the bus and/or to filter for specific messages based on the CAN ID field. A device can be opened multiple times, every client will receive all CAN frames simultaneously.

Similarly, CAN frames can be sent to the bus by multiple client simultaneously as well.

Hardware and more information

More information on CAN can be found on Wikipedia. When not running on an embedded platform with already integrated CAN components, Thomas Fischl’s USBtin (see section 2.4) is one of many ways to get started.

RawFd and OwnedFd

Raw access to the underlying file descriptor and construction through one is available through the AsRawFd, IntoRawFd and FromRawFd, and similar implementations.

Crate Features

Default

• netlink - Whether to include programmable CAN interface configuration capabilities based on netlink kernel communications. This brings in the neli library and its dependencies.

• dump - Whether to include candump parsing capabilities.

Non-default

• enumerate - Include the enumerate module which can be used to get a list of the CANbus network interfaces attached to the host. This brings in the dependency for libudev

• utils - Whether to build command-line utilities. This brings in additional dependencies like anyhow and clap

• tokio - Include support for async/await using tokio.

• async-io - Include support for async/await using async-io This will work with any runtime that uses async_io, including async-std and smol.

• async-std - Include support for async/await using async-io with a submodule aliased for async-std and examples for that runtime.

• smol - Include support for async/await using async-io with a submodule aliased for smol and examples for that runtime.

Test Features

Additional test can be built and run, but have requirements:

• vcan_tests - Requires a virtual CAN interface to be installed on the host. This can be done by running the vcan.sh script included with the crate.

• netlink_tests - Requires superuser privileges to run/pass.

Re-exports

pub use errors::CanError;

pub use errors::CanErrorDecodingFailure;

pub use errors::ConstructionError;

pub use errors::Error;

pub use errors::IoError;

pub use errors::IoErrorKind;

pub use errors::IoResult;

pub use errors::Result;

pub use addr::CanAddr;

pub use id::CanId;

pub use frame::CanAnyFrame;

pub use frame::CanDataFrame;

pub use frame::CanErrorFrame;

pub use frame::CanFdFrame;

pub use frame::CanFrame;

pub use frame::CanRawFrame;

pub use frame::CanRemoteFrame;

pub use frame::Frame;

pub use socket::CanFdSocket;

pub use socket::CanFilter;

pub use socket::CanSocket;

pub use socket::ShouldRetry;

pub use socket::Socket;

pub use socket::SocketOptions;

pub use nl::CanCtrlMode;

pub use nl::CanInterface;

pub use nl::InterfaceCanParams;

pub use embedded_can;

Modules

addr

SocketCAN address type.

dump

candump format parsing

errors

CAN bus errors.

frame

CAN bus frames.

id

Implementation of CANbus standard and extended identifiers.

nl

CAN Netlink access

socket

Implementation of sockets for CANbus 2.0 and FD for SocketCAN on Linux.

Structs

ExtendedId

Extended 29-bit CAN Identifier (0..=1FFF_FFFF).

StandardId

Standard 11-bit CAN Identifier (0..=0x7FF).

Enums

Id

A CAN Identifier (standard or extended).

Traits

BlockingCan

A blocking CAN interface that is able to transmit and receive frames.

EmbeddedFrame

A CAN2.0 Frame

NonBlockingCan

A CAN interface that is able to transmit and receive frames.