Bus

The Bus class, as the name suggests, provides an abstraction of a CAN bus. The bus provides a wrapper around a physical or virtual CAN Bus.

Filtering

Message filtering can be set up for each bus. Where the interface supports it, this is carried out in the hardware or kernel layer - not in Python.

API

class can.BusABC(channel=None, can_filters=None, **config)

Bases: object

CAN Bus Abstract Base Class

Concrete implementations must implement the following methods:

• send
• recv

As well as setting the channel_info attribute to a string describing the interface.

Parameters:

• channel – The can interface identifier. Expected type is backend dependent.
• can_filters (list) –

  A list of dictionaries each containing a “can_id”, a “can_mask”, and an “extended” key.

  >>> [{"can_id": 0x11, "can_mask": 0x21, "extended": False}]
  

  A filter matches, when <received_can_id> & can_mask == can_id & can_mask

• config (dict) – Any backend dependent configurations are passed in this dictionary

__iter__()

Allow iteration on messages as they are received.

>>> for msg in bus:
...     print(msg)

Yields:can.Message msg objects.

channel_info = 'unknown'

a string describing the underlying bus channel

flush_tx_buffer()

Discard every message that may be queued in the output buffer(s).

recv(timeout=None)

Block waiting for a message from the Bus.

Parameters:timeout (float) – Seconds to wait for a message. Returns:None on timeout or a can.Message object.

send(msg, timeout=None)

Transmit a message to CAN bus. Override this method to enable the transmit path.

Parameters:

• msg (can.Message) – A message object.
• timeout (float) – If > 0, wait up to this many seconds for message to be ACK:ed or for transmit queue to be ready depending on driver implementation. If timeout is exceeded, an exception will be raised. Might not be supported by all interfaces.

Raise:

can.CanError if the message could not be written.

send_periodic(msg, period, duration=None)

Start sending a message at a given period on this bus.

Parameters:

• msg (can.Message) – Message to transmit
• period (float) – Period in seconds between each message
• duration (float) – The duration to keep sending this message at given rate. If no duration is provided, the task will continue indefinitely.

Returns:

A started task instance

Return type:

can.CyclicSendTaskABC

Note the duration before the message stops being sent may not be exactly the same as the duration specified by the user. In general the message will be sent at the given rate until at least duration seconds.

set_filters(can_filters=None)

Apply filtering to all messages received by this Bus.

Calling without passing any filters will reset the applied filters.

Parameters:can_filters (list) –

A list of dictionaries each containing a “can_id” and a “can_mask”.

>>> [{"can_id": 0x11, "can_mask": 0x21}]

A filter matches, when <received_can_id> & can_mask == can_id & can_mask

shutdown()

Called to carry out any interface specific cleanup required in shutting down a bus.

class can.interface.Bus

Bases: object

Instantiates a CAN Bus of the given bustype, falls back to reading a configuration file from default locations.

Takes the same arguments as can.BusABC with the addition of:

Parameters:kwargs – Should contain a bustype key with a valid interface name. Raises:NotImplementedError if the bustype isn’t recognized Raises:ValueError if the bustype or channel isn’t either passed as an argument or set in the can.rc config.

Transmitting

Writing to the bus is done by calling the send() method and passing a Message object.

Receiving

Reading from the bus is achieved by either calling the recv() method or by directly iterating over the bus:

for msg in bus:
    print(msg.data)

Alternatively the Listener api can be used, which is a list of Listener subclasses that receive notifications when new messages arrive.