.. currentmodule:: machine

.. _machine.CAN:

class CAN -- Controller Area Network protocol

.. warning:: Currently no MicroPython ports have ``machine.CAN`` controllers.

This is a design document only.

CAN is a two-wire serial protocol used for reliable real-time message delivery

between one or more nodes connected to a common bus. CAN 2.0 was standardised in

ISO-11898, and is now also known as CAN Classic.

There is also a newer, backwards compatible, protocol named CAN FD (CAN with

Flexible Data-Rate).

CAN support requires a controller (often an internal microcontroller

peripheral), and an external transceiver to level-shift the signals onto the CAN

bus.

The ``machine.CAN`` interface is a *low level basic* CAN messaging interface

that abstracts a CAN controller as an outgoing priority queue for sending

messages, an incoming queue for receiving messages, and mechanisms for reporting

errors.

.. note:: The forthcoming ``can`` and ``aiocan`` micropython-lib modules are the

recommended way to use CAN with MicroPython.

Constructor

.. class:: CAN(id, **kwargs)

Construct a CAN controller object of the given id:

- ``id`` identifies a particular CAN controller object; it is board and port specific.

- ``**kwargs`` are hardware-specific identifiers for the particular

board and port. For example, to set which GPIO pins to use for the

CAN controller.

Methods

.. method:: CAN.init(bitrate, mode=CAN.Mode.NORMAL, sample_point=75, sjw=None, tseg1=None, tseg2=None, f_clock=None)

Initialise the CAN bus with the given parameters:

- ``bitrate`` is the desired bus bit rate in bits per second.

- ``mode`` is one of :class:`CAN.Mode` enumerated values, indicating the

desired mode of operation.

- ``sample_point`` is a percentage of the data bit time. It specifies the

position of the bit sample with respect to the whole nominal bit time.

The remaining parameters all relate to CAN bit timings. If not specified, the CAN controller

will pick nominal values based on the specified bit rate.

Otherwise, they can be specified:

- ``sjw`` is the resynchronisation jump width in units of time quanta for nominal bits;

it can be a value between 1 and 4 inclusive for classic CAN, and between 1 and 128 inclusive for CAN FD.

- ``tseg1`` defines the location of the sample point in units of the time quanta for nominal bits;

it can be a value between 1 and 16 inclusive for classic CAN, and between 2 and 256 inclusive for CAN FD.

- ``tseg2`` defines the location of the transmit point in units of the time quanta for nominal bits;

it can be a value between 1 and 8 inclusive for classic CAN, and between 2 and 128 inclusive for CAN FD.

- ``f_clock`` is the system clock frequency for the CAN peripheral. This

can be omitted on many ports where the value is known to the hardware.

In this case, the CAN controller is configured correctly for the desired

``bitrate`` and the specified total number of time quanta per bit.

.. method:: CAN.init_fd(bitrate, sample_point=None, sjw=None, tseg1=None, tseg2=None, f_clock=None)

Initialise CAN FD for controllers which support it.

.. note:: This method is not present on the class for controllers that only

support CAN Classic.

This must be called after :func:`CAN.init()`. The parameters all have the

same meanings and behaviour as that function, however they configure the

Bit Rate Switch (BRS) feature of CAN FD.

When specifying exact timing parameters, the accepted ranges are:

- ``sjw`` can be a value between 1 and 16 inclusive.

- ``tseg1`` can be a value between 1 and 32 inclusive

- ``tseg2`` can be a value between 1 and 32 inclusive

.. method:: CAN.detect_bitrate([timeout_ms])

Detect the CAN bit rate by monitoring the CAN bus.

..note:: This method is only present on the class for controllers that

support this feature.

If successful, returns the detected bit rate and also configures the hardware

CAN controller for this rate.

If the optional ``timeout`` parameter is specified then detection only runs

for this many milliseconds before timing out and returning ``None``. In this

case the CAN controller configuration will remain unchanged after returning.

.. method:: CAN.set_filters(filters)

Set receive filters in the CAN controller. ``filters`` should be an iterable,

where each item is a tuple or list with three elements:

- ``identifier`` is a CAN identifier (int).

- ``bit_mask`` is a bit mask for bits in the CAN identifier field (int).

- ``flags`` is one or more bitwise OR-ed values from

:class:`CAN.MessageFlags` that the incoming message needs to match. Not

all controllers support filtering on all flags, a ``ValueError`` is raised

if an unsupported flag is requested.

Incoming messages are accepted if the bits masked in ``bit_mask`` match between

the message identifier and the filter ``identifier`` value, and flags set in the

filter match the incoming message.

All filters are ORed together in the controller. Passing an empty list (``[]``)

for the filters argument disables the receive filter (all messages received.)

.. note:: If the caller passes a list with more entries than :data:`CAN.filters_max`,

``ValueError`` will be raised.

.. data:: CAN.filters_max

Constant value that reads the maximum number of supported receive filters

for this hardware controller.

.. method:: CAN.send(identifier, data, flags=0, fifo_equal=True)

- ``identifier`` is an integer CAN identifier value.

- ``data`` is a bytes object (or similar) containing the CAN message data.

- ``flags`` is OR-ed together flags :class:`CAN.MessageFlags` specifying

properties of the outgoing CAN message (Extended ID, Remote request, etc.)

- ``keep_equal`` is a flag for whether messages with the same identifiers

should be kept in the queue or replaced (see below).

Write a new CAN message into the controller's hardware transmit queue to be

sent onto the bus. The transmit queue is a priority queue sorted first on CAN

identifier priority (lower numeric identifiers have higher priority), and

second on order of insertion.

If the queue is full and the new message has higher priority than the lowest

priority message in the queue then the lowest priority message will be

de-queued and replaced.

If the queue is full and the new message has equal priority to the lowest

priority message in the queue, then the behaviour depends on the

``keep_equal`` argument:

- If ``True`` (default), the queue remains unchanged and the new message is

not queued. This allows reliable transmission of messages in FIFO order.

- If ``False``, the oldest matching message in the transmit queue is

de-queued and replaced with the new message.

The function returns an integer index (1-based) which identifies the queue

entry where the new message was written. This is a hardware-specific index

value that does not reflect which message will be sent next.

An additional value ``CAN.SEND_FLAG`` is bitwise ORed with the result if the

previously queued message at this entry indexed was de-queued and replaced

with the new message.

If the hardware queue was full and the new message could not be written into

the queue at all due to priorities, then the return value is ``0``.

.. note:: This intentionally low-level implementation is designed so the

caller tracks the messages in each hardware queue entry. See the ``can`` and

``aiocan`` modules for details.

.. data:: CAN.SEND_FLAG

Constant bit value that is ORed with the index result from :func:`CAN.send`

if another message was de-queued and replaced with the new message.

.. data:: CAN.send_max

Constant, indicating the maximum number of entries in the hardware transmit

queue (this is also the highest possible index returned from ``send``).

.. method:: CAN.irq_send(callback, hard=False)

Sets an interrupt ``callback`` function to be called when the controller sends

a message on the bus, or has attempted to send.

Callback arguments are a tuple or list with three elements:

- ``send_id`` is the same index value returned from :func:`CAN.send` when the

corresponding message was queued.

- ``send_status`` is 0 if the message was sent successfully, or a bitwise OR

of :class:`CAN.SendErrors` flags otherwise.

- ``requeued`` is a ``bool`` that is set to ``True`` if the CAN controller

hardware has already re-queued this message to retry sending.

If ``hard`` is set to True then the callback will be called in "hard"

interrupt context on ports which support this. The parameter is ignored

otherwise.

.. method:: CAN.irq_recv(callback, hard=False)

Sets an interrupt ``callback`` function to be called when the controller receives

a message on the bus, or detects an error condition while receiving.

Callback arguments for a successful receive are a tuple or list with the following elements:

- ``timestamp`` is a ``time.ticks_us`` timestamp indicating when the message was

received.

- ``identifier`` is the CAN identifier which was received. If receive filters

are set, the identifier will be one that matches.

- ``data`` is a bytes object (or equivalent) showing the data portion of the

message.

- ``msg_flags`` is an integer comprised of bitwise ORed values from

:class:`CAN.MessageFlags`. This indicates metadata about the message.

- ``error_flags`` is ``0`` if the message was received successfully, or

bitwise ORed values of :func:`CAN.RecvErrors` otherwise. Note that if error

flags are set, the values of ``identifier``, ``data``, and ``msg_flags``

may be ``None``.

Argument values are only valid while the callback is running, they must be

copied into another variable or buffer in order to retain them.

If ``hard`` is set to True then the callback will be called in "hard"

interrupt context on ports which support this. The parameter is ignored

otherwise.

Unless not possible due to hardware limitations, the controller will call the

``irq_recv()`` callback in the same order that messages were received on the

bus.

.. note:: As a low-level class, :class:`machine.CAN` does not contain a

normal ``recv()`` method. Refer to (planned) ``can`` and ``iocan``

modules, instead.

.. method:: CAN.get_state()

Returns a :class:`CAN.State` value indicating the state of the controller.

.. method:: CAN.irq_state(callback, hard=False)

Sets a callback which is called whenever the controller state changes. The

callback argument is the new :class:`CAN.State` value.

If ``hard`` is set to True then the callback will be called in "hard"

interrupt context on ports which support this. The parameter is ignored

otherwise.

.. method:: CAN.get_counters([list])

Returns controller's error counter values. The result is a list of 8 values.

If the optional ``list`` parameter is specified then the provided list object

is updated and returned as the result, to avoid an allocation.

The list items are:

- TEC (Transmit Error Counter) value

- REC (Receive Error Counter) value

- Number of times the controller entered the Error Warning state.

- Number of times the controller entered the Error Passive state.

- Number of times the controller entered the Bus Off state.

- Total number of pending TX messages in the hardware queue.

- Total number of pending RX messages in the hardware queue.

- Number of times an RX overrun occurred.

.. note:: Depending on the controller, these values may overflow back to 0 after

a certain value.

.. note:: If a controller doesn't support a particular counter, it will return

``None`` for that list element.

.. method:: CAN.get_errors()

Returns an integer which is a bitwise OR of :class:`CAN.ErrorFlags` representing

error conditions tracked by the CAN controller.

.. method:: CAN.reset(mode=CAN.Mode.NORMAL)

Fully resets the CAN controller hardware. Restores values previously set by :func:`CAN.init()`.

All hardware queues are emptied, error counters and flags reset, etc.

The controller transitions into the ``mode`` specified by the argument (see :class:`CAN.Mode`).

.. method:: CAN.restart()

Restart the CAN controller without resetting its internal state, except for

TEC and REC. Can be used to manually recover from the ``BUS_OFF`` state.

.. method:: CAN.mode(mode)

Transitions the CAN controller to a new mode of operation, without resetting it.

Argument is one of :func:`CAN.Mode`.

.. note:: Note all modes are supported by all CAN controller hardware.

Passing an unsupported mode value will raise ``ValueError``.

.. class:: CAN.Mode

Enumeration class that holds the following constant values (integers) representing controller modes of operation:

- ``NORMAL`` - CAN controller interacts normally on the bus.

- ``SLEEP`` - CAN controller is asleep in a low power mode. Depending on the

controller, this may support waking the controller and transitioning to

``NORMAL`` mode if CAN traffic is received.

- ``LOOPBACK`` - A testing mode. The CAN controller is still connected to the

external bus, but will also receive its own transmitted messages and ignore

any ACK errors.

- ``SILENT`` - CAN controller receives messages but does not interact with

the CAN bus (including sending ACKs, errors, etc.)

- ``SILENT_LOOPBACK`` - A testing mode that does not require a CAN bus. The

CAN controller receives its own transmitted messages without interacting

with the CAN bus at all. The CAN TX and RX pins remain idle.

.. class:: CAN.State

Enumeration class that holds the following constant values (integers) representing the state of the controller on the bus:

- ``STOPPED`` - The controller is not interacting with the bus.

- ``ERROR_ACTIVE`` - The controller is in the Error-Active and TEC and REC are both less than 96.

- ``ERROR_WARNING`` - The controller is in the Error-Warning state, meaning

at least one of ``TEC`` or ``REC`` is 96 or greater.

- ``ERROR_PASSIVE`` - The controller is in the Error-Passive state, meaning

at least one of ``TEC`` or ``REC`` is 128 or greater.

- ``BUS_OFF`` - The controller is in the Bus-Off state, meaning ``TEC`` is

greater than 255. It does not currently have any influence on Bus activity.

.. class:: CAN.ErrorFlags

Enumeration class representing error conditions that have been detected by the controller. Cleared on reset. :func:`CAN.get_errors()`.

TODO

.. class:: CAN.MessageFlags

Enumeration class representing possible conditions of a CAN message, as bitwise ORed together flags.

- ``RTR`` - Message is a remote transmission request. If this bit is set, the

``data`` value should be an integer (indicating the length from the ``DLC``

field), not a bytes object.

- ``EXTENDED_ID`` - Message identifier is Extended (29-bit). If not set, message

identifier is Standard (11-bit).

- ``FD_F``- Message is CAN FD in the FD data format, meaning data payload

can be up to 64 bytes long. Passing this flag to a controller which lacks

CAN FD support will raise ``ValueError``.

- ``BRS`` - For CAN FD controllers and FD data format messages, indicates the

bitrate should be switched during the data phase.

.. class:: CAN.RecvErrors

Enumeration class representing possible error statuses when

receiving a CAN message. Multiple values may be ORed together.

- ``CRC`` - A CRC error occurred.

- ``FORM`` - A form error occurred in a fixed-form bit field.

- ``OVERRUN`` - One or more messages overran the receive hardware

queue and were lost.

- ``ESI`` - The ESI flag of a received CAN FD message was set.

.. class:: CAN.SendErrors

Enumeration class representing possible error statuses when

sending a CAN message. Multiple values may be ORed together.

- ``NACK`` - Sent message was not ACKed.

- ``BIT`` - A bit error was detected.

machine.CAN.rst