canio – CAN bus access

The canio module contains low level classes to support the CAN bus protocol.

CAN and Listener classes change hardware state and should be deinitialized when they are no longer needed if the program continues after use. To do so, either call deinit() or use a context manager. See Lifetime and ContextManagers for more info.

For example:

import canio
from board import *

can = canio.CAN(board.CAN_RX, board.CAN_TX, baudrate=1000000)
message = canio.Message(id=0x0408, data=b"adafruit")
can.send(message)
can.deinit()

This example will write the data ‘adafruit’ onto the CAN bus to any device listening for message id 0x0408.

A CAN bus involves a transceiver, which is often a separate chip with a “standby” pin. If your board has a CAN_STANDBY pin, ensure to set it to an output with the value False to enable the transceiver.

Other implementations of the CAN device may exist (for instance, attached via an SPI bus). If so their constructor arguments may differ, but otherwise we encourage implementors to follow the API that the core uses.

class canio.BusState

The state of the CAN bus

ERROR_ACTIVE :object

The bus is in the normal (active) state

ERROR_WARNING :object

The bus is in the normal (active) state, but a moderate number of errors have occurred recently.

NOTE: Not all implementations may use ERROR_WARNING. Do not rely on seeing ERROR_WARNING before ERROR_PASSIVE.

ERROR_PASSIVE :object

The bus is in the passive state due to the number of errors that have occurred recently.

This device will acknowledge packets it receives, but cannot transmit messages. If additional errors occur, this device may progress to BUS_OFF. If it successfully acknowledges other packets on the bus, it can return to ERROR_WARNING or ERROR_ACTIVE and transmit packets.

BUS_OFF :object

The bus has turned off due to the number of errors that have occurred recently. It must be restarted before it will send or receive packets. This device will neither send or acknowledge packets on the bus.

class canio.CAN(tx: microcontroller.Pin, rx: microcontroller.Pin, *, baudrate: int = 250000, loopback: bool = False, silent: bool = False, auto_restart: bool = False)

CAN bus protocol

A common shared-bus protocol. The rx and tx pins are generally connected to a transceiver which controls the H and L pins on a shared bus.

Parameters:
  • rx (Pin) – the pin to receive with
  • tx (Pin) – the pin to transmit with
  • baudrate (int) – The bit rate of the bus in Hz. All devices on the bus must agree on this value.
  • loopback (bool) – When True the rx pin’s value is ignored, and the device receives the packets it sends.
  • silent (bool) – When True the tx pin is always driven to the high logic level. This mode can be used to “sniff” a CAN bus without interfering.
  • auto_restart (bool) – If True, will restart communications after entering bus-off state
auto_restart :bool

If True, will restart communications after entering bus-off state

baudrate :int

The baud rate (read-only)

transmit_error_count :int

The number of transmit errors (read-only). Increased for a detected transmission error, decreased for successful transmission. Limited to the range from 0 to 255 inclusive. Also called TEC.

receive_error_count :int

The number of receive errors (read-only). Increased for a detected reception error, decreased for successful reception. Limited to the range from 0 to 255 inclusive. Also called REC.

state :State

The current state of the bus. (read-only)

loopback :bool

True if the device was created in loopback mode, False otherwise (read-only)

silent :bool

True if the device was created in silent mode, False otherwise (read-only)

restart(self)

If the device is in the bus off state, restart it.

listen(self, matches: Optional[Sequence[Match]] = None, *, timeout: float = 10)

Start receiving messages that match any one of the filters.

Creating a listener is an expensive operation and can interfere with reception of messages by other listeners.

There is an implementation-defined maximum number of listeners and limit to the complexity of the filters.

If the hardware cannot support all the requested matches, a ValueError is raised. Note that generally there are some number of hardware filters shared among all fifos.

A message can be received by at most one Listener. If more than one listener matches a message, it is undefined which one actually receives it.

An empty filter list causes all messages to be accepted.

Timeout dictates how long receive() and next() will block.

send(message: Union[RemoteTransmissionRequest, Message])

Send a message on the bus with the given data and id. If the message could not be sent due to a full fifo or a bus error condition, RuntimeError is raised.

deinit(self)

Deinitialize this object, freeing its hardware resources

__enter__(self)

Returns self, to allow the object to be used in a The with statement statement for resource control

__exit__(self, unused1, unused2, unused3)

Calls deinit()

class canio.Listener

Listens for CAN message

canio.Listener is not constructed directly, but instead by calling canio.CAN.listen.

In addition to using the receive method to retrieve a message or the in_waiting method to check for an available message, a listener can be used as an iterable, yielding messages until no message arrives within self.timeout seconds.

timeout :float
receive(self)

Reads a message, after waiting up to self.timeout seconds

If no message is received in time, None is returned. Otherwise, a Message or RemoteTransmissionRequest is returned.

in_waiting(self)

Returns the number of messages (including remote transmission requests) waiting

__iter__(self)

Returns self

This method exists so that Listener can be used as an iterable

__next__(self)

Reads a message, after waiting up to self.timeout seconds

If no message is received in time, raises StopIteration. Otherwise, a Message or is returned.

This method enables the Listener to be used as an iterable, for instance in a for-loop.

deinit(self)

Deinitialize this object, freeing its hardware resources

__enter__(self)

Returns self, to allow the object to be used in a The with statement statement for resource control

__exit__(self, unused1, unused2, unused3)

Calls deinit()

class canio.Match(id: int, *, mask: Optional[int] = None, extended: bool = False)

Describe CAN bus messages to match

Construct a Match with the given properties.

If mask is not None, then the filter is for any id which matches all the nonzero bits in mask. Otherwise, it matches exactly the given id. If extended is true then only extended ids are matched, otherwise only standard ids are matched.

id :int

The id to match

mask :int

The optional mask of ids to match

extended :bool

True to match extended ids, False to match standard ides

class canio.Message(id: int, data: bytes, *, extended: bool = False)

Construct a Message to send on a CAN bus.

Parameters:
  • id (int) – The numeric ID of the message
  • data (bytes) – The content of the message
  • extended (bool) – True if the message has an extended identifier, False if it has a standard identifier

In CAN, messages can have a length from 0 to 8 bytes.

id :int

The numeric ID of the message

data :bytes

The content of the message

extended :bool

True if the message’s id is an extended id

class canio.RemoteTransmissionRequest(id: int, length: int, *, extended: bool = False)

Construct a RemoteTransmissionRequest to send on a CAN bus.

Parameters:
  • id (int) – The numeric ID of the requested message
  • length (int) – The length of the requested message
  • extended (bool) – True if the message has an extended identifier, False if it has a standard identifier

In CAN, messages can have a length from 0 to 8 bytes.

id :int

The numeric ID of the message

extended :bool

True if the message’s id is an extended id

length :int

The length of the requested message.