# 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)

  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.

  `__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`

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

## 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.