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:
Adafruit CircuitPython firmware for the supported boards: https://github.com/adafruit/circuitpython/releases
Adafruit’s Bus Device library: https://github.com/adafruit/Adafruit_CircuitPython_BusDevice
- 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 toTrue
, 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 toFalse
.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 toFalse
.debug (bool) – If
True
, will enable printing debug information. Defaults toFalse
.
- 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.
An empty filter list causes all messages to be accepted.
Timeout dictates how long
receive()
will block.- Args:
match (Optional[Sequence[Match]], optional): [description]. Defaults to None. timeout (float, optional): [description]. Defaults to 10.
- Returns:
Listener: [description]
- 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:
- 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:
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
orreadinto
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:
- property data¶
The content of the message