_canio – CAN bus access

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

All 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.BUS(board.CANRX, board.CANTX)
can.write(408, b"adafruit")
can.deinit()

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

class _canio.CAN(rx: microcontroller.Pin, tx: Optional[microcontroller.Pin] = None, *, baudrate: int = 250000, loopback: 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, or None if the peripheral should operate in “silent” mode.

  • baudrate (int) – The bit rate of the bus in Hz. All devices on the bus must agree on this value.

  • loopback (bool) – True if the peripheral will be operated in loopback mode.

baudrate :int

The baud rate(read-only)

state :State

The status of the hardware (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.

error_warning_state_count :int

The number of times the controller enterted the Error Warning state (read-only). This number wraps around to 0 after an implementation-defined number of errors.

error_passive_state_count :int

The number of times the controller enterted the Error Passive state (read-only). This number wraps around to 0 after an implementation-defined number of errors.

bus_off_state_count :int

The number of times the controller enterted the Bus Off state (read-only). This number wraps around to 0 after an implementation-defined number of errors.

listen(filters: Optional[Sequence[Filter]] = None, *, timeout=10) → Listener

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 filters, 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. An empty filter list causes all messages to be accepted. Timeout dictates how long readinto, read and next() will block. Readinto will return false(), read will return None, and next() will raise StopIteration.

send(message: Message) → None

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) → None

Deinitialize this object, freeing its hardware resources

__enter__(self) → CAN

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

__exit__(self, unused1, unused2, unused3) → None

Calls deinit()

class _canio.Match(address: int, *, mask: int = 0, extended: bool = False)

Describe CAN bus messages to match

Construct a Match with the given properties.

If mask is nonzero, then the filter is for any sender which matches all the nonzero bits in mask. Otherwise, it matches exactly the given address. If extended is true then only extended addresses are matched, otherwise only standard addresses are matched.

address :int

The address to match

mask :int

The optional mask of addresses to match

extended :bool

True to match extended addresses, False to match standard addresses

class _canio.Message(id: int, data: Optional[bytes] = None, *, size: Optional[int] = None, rtr: 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

  • size (int) – The amount of data requested, for an rtr

  • rtr (bool) – True if the message represents an rtr (Remote Transmission Request)

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

For a non-rtr message, specify data. For an rtr-message, specify either data (a dummy buffer of the requested size) or size.

id :int

The numeric ID of the message (read only)

data :bytes

The content of the message, or dummy content in the case of an rtr (read only)

size :int

The length of the message, or the length of the requested data in the case of an rtr (read-only)