:mod:`_canio`
=============

.. py:module:: _canio

.. autoapi-nested-parse::

   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 :py:meth:`!deinit` or use a context manager. See
   :ref:`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.





.. py:class:: 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.

   :param ~microcontrller.Pin rx: the pin to receive with.
   :param ~microcontrller.Pin tx: the pin to transmit with, or None if the peripheral should operate in "silent" mode.
   :param int baudrate: The bit rate of the bus in Hz.  All devices on the bus must agree on this value.
   :param bool loopback: True if the peripheral will be operated in loopback mode.

   .. attribute:: baudrate
      :annotation: :int

      The baud rate(read-only)


   .. attribute:: state
      :annotation: :State

      The status of the hardware (read-only)


   .. attribute:: transmit_error_count
      :annotation: :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.


   .. attribute:: receive_error_count
      :annotation: :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.


   .. attribute:: error_warning_state_count
      :annotation: :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.


   .. attribute:: error_passive_state_count
      :annotation: :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.


   .. attribute:: bus_off_state_count
      :annotation: :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.


   .. method:: 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.


   .. method:: 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.


   .. method:: deinit(self) -> None

      Deinitialize this object, freeing its hardware resources


   .. method:: __enter__(self) -> CAN

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


   .. method:: __exit__(self, unused1, unused2, unused3) -> None

      Calls deinit()



.. py:class:: 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.

   .. attribute:: address
      :annotation: :int

      The address to match


   .. attribute:: mask
      :annotation: :int

      The optional mask of addresses to match


   .. attribute:: extended
      :annotation: :bool

      True to match extended addresses, False to match standard addresses



.. py:class:: Message(id: int, data: Optional[bytes] = None, *, size: Optional[int] = None, rtr: bool = False)

   Construct a Message to send on a CAN bus

   :param int id: The numeric ID of the message
   :param bytes data: The content of the message
   :param int size: The amount of data requested, for an rtr
   :param bool rtr: 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`.

   .. attribute:: id
      :annotation: :int

      The numeric ID of the message (read only)


   .. attribute:: data
      :annotation: :bytes

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


   .. attribute:: size
      :annotation: :int

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