API Reference

adafruit_mcp2515

A CircuitPython library for working with the MCP2515 CAN bus controller using the CircuitPython canio API

  • Author(s): Bryan Siepert

Implementation Notes

Hardware:

Software and Dependencies:

class adafruit_mcp2515.MCP2515(spi_bus, cs_pin, *, baudrate: int = 250000, crystal_freq: Literal[8000000, 10000000, 16000000] = 16000000, loopback: bool = False, silent: bool = False, auto_restart: bool = False, debug: bool = False)

A common shared-bus protocol.

Parameters:

  • spi (SPI) – The SPI bus used to communicate with the MCP2515

  • cs_pin (DigitalInOut) – SPI bus enable pin

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

  • crystal_freq (Literal) – MCP2515 crystal frequency. Valid values are: 16000000, 10000000 and 8000000. Defaults to 16000000 (16MHz). :param bool loopback: Receive only packets sent from this device, and send only to this device. Requires that silent is also set to True, but only prevents transmission to other devices. Otherwise the send/receive behavior is normal.

  • silent (bool) – When True the controller does not transmit and all messages are received, ignoring errors and filters. This mode can be used to “sniff” a CAN bus without interfering. Defaults to False.

  • auto_restart (bool) – Not supported by hardware. An `AttributeError` will be raised if `auto_restart` is set to `True` If True, will restart communications after entering bus-off state. Defaults to False.

  • debug (bool) – If True, will enable printing debug information. Defaults to False.

property baudrate

The baud rate (read-only)

property bus_off_state_count

Not supported by hardware. Raises an AttributeError if called

deinit()

Deinitialize this object, freeing its hardware resources

deinit_filtering_registers()

Clears the Receive Mask and Filter Registers

property error_passive_state_count

Not supported by hardware. Raises an AttributeError if called

property error_warning_state_count

Not supported by hardware. Raises an AttributeError if called

initialize()

Return the sensor to the default configuration

listen(matches=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.

The MCP2515 has space for 2 masks (RXM0/RXM1) and 6 filters (RXMF0-RXMF5). Mask RXM0 is paired with 2 filters (RXF0-1) and mask RXM1 is paired with 4 filters (RXF2-5). Read the MCP2515 datasheet for more details on masks and filters.

You can use up to 6 matches (match = mask & filter) in the array. The order of the match objects in the array matters. The first unique mask will be placed in RXM0 and can be paired with up to 2 filters. The second unique mask will be placed in RXM1 and can be paired with up to 4 filters. When no mask is defined in the match object, an ‘exact match’ mask of all 1’s will be used. You can use the same mask in multiple matches, however if there are more than 2 unique masks in the matches array, a RuntimeError will be raised. Similarly if there are more than 2 filters used with the first unique mask or more than 4 filters used with the second unique mask a RuntimeError will be raised.

An empty matches array causes all messages to be accepted.

Parameters:

  • matches ([canio.Match], optional) – ID patterns used to restrict the packets received. Defaults to None.

  • timeout (float, optional) – dictates how long receive() will block. Defaults to 10.

Returns:

Listener object used to receive CANio packets based on the arguments passed into listen()

Return type:

canio.Listener

property loopback

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

read_message()

Read the next available message

Returns:

The next available message or None if one is not available

Return type:

canio.Message

property receive_error_count

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.

restart()

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

send(message_obj)
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.

Parameters:

message (canio.Message) – The message to send. Must be a valid canio.Message

property silent

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

property state

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

property transmit_error_count

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.

property unread_message_count

The number of messages that have been received but not read with read_message

Returns:

The unread message count

Return type:

int

Python implementation of the CircuitPython core canio API

class adafruit_mcp2515.canio.BusState

The state of the CAN bus

BUS_OFF = 3

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.

ERROR_ACTIVE = 0

The bus is in the normal (active) state

ERROR_PASSIVE = 2

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.

ERROR_WARNING = 1

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.

class adafruit_mcp2515.canio.Listener(can_bus_obj, timeout=1.0)

Listens for a CAN message

canio.Listener is not constructed directly, but instead by calling the listen method of a canio.CAN object.

deinit()

Deinitialize this object, freeing its hardware resources

in_waiting()

Returns the number of messages waiting

receive()

Receives a message. If after waiting up to self.timeout seconds if no message is received, None is returned. Otherwise, a Message is returned.

property timeout

The maximum amount of time in seconds that read or readinto will wait before giving up

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

A class representing an ID pattern to match against

class adafruit_mcp2515.canio.Message(id, data, extended=False)

A class representing a CANbus data frame

Parameters:

  • id (int) – The numeric ID of the message

  • data (bytes) – The content of the message, from 0 to 8 bytes of data

  • extended (bool) – True if the message has an extended identifier, False if it has a standard identifier

property data

The content of the message

extended: bool

Indicates whether the the message has an extended identifier

id: int

The numeric ID of the message

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

A class representing a CANbus remote frame

Parameters:

  • id (int) – The numeric ID of the message

  • int (length) – The length of the requested message

  • extended (bool) – True if the message has an extended identifier, False if it has a standard identifier

extended: bool

Indicates whether the the message has an extended identifier

id: int

The numeric ID of the message

length: int

The length of the requested message, from 0 to 8