.. currentmodule:: machine .. _machine.CAN: class CAN -- Controller Area Network protocol ============================================= 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). *The machine.CAN driver does not currently support CAN FD features, use `pyb.CAN` on stm32 if you need CAN FD*. 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 planned ``can`` and ``aiocan`` micropython-lib modules will be the recommended way to use CAN with MicroPython. Constructor ----------- .. class:: CAN(id, *args, **kwargs) Construct a CAN controller object of the given id: - ``id`` identifies a particular CAN controller object; it is board and port specific. - All other arguments are passed to :func:`CAN.init`. At least one argument (``bitrate``) must be provided. Future versions of this class may also accept port-specific keyword arguments here which configure the hardware. Currently no such keyword arguments are implemented. Example ^^^^^^^ Construct and initialise CAN controller 1 with bitrate 500kbps:: from machine import CAN can = CAN(1, 500_000) .. Add a table of port-specific keyword arguments here, once they exist Methods ------- .. method:: CAN.init(bitrate, mode=CAN.MODE_NORMAL, sample_point=75, sjw=1, tseg1=None, tseg2=None) Initialise the CAN bus with the given parameters: - *bitrate* is the desired bus bit rate in bits per second. - *mode* is one of the values shown under `can-modes`, indicating the desired mode of operation. The default is "normal" operation on the bus. The next parameters are optional and relate to CAN bit timings. In most cases you can leave these parameters set to the default values: - *sample_point* is an integer percentage of the data bit time. It specifies the position of the bit sample with respect to the whole nominal bit time. The CAN driver will calculate parameters accordingly. This parameter is ignored if *tseg1* and *tseg2* are set. - *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. - *tseg1* defines the location of the sample point in units of time quanta for nominal bits; it can be a value between 1 and 16 inclusive for classic CAN. This is the sum of the ``Prop_Seg`` and ``Phase_Seg1`` phases as defined in the ISO-11898 standard. If this value is set then *tseg2* must also be set and *sample_point* is ignored. - *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. This corresponds to ``Phase_Seg2`` in the ISO-11898 standard. If this value is set then *tseg1* must also be set. If these arguments are specified then the CAN controller is configured correctly for the desired *bitrate* and the specified total number of time quanta per bit. The *tseg1* and *tseg2* values override the *sample_point* argument if all of these are supplied. .. note:: Individual controller hardware may have additional restrictions on valid values for these parameters, and will raise a ``ValueError`` if a given value is not supported. .. note:: Specific controller hardware may accept additional optional keyword parameters for hardware-specific features such as oversampling. .. method:: CAN.set_filters(filters) Set receive filters in the CAN controller. *filters* can be: - ``None`` to accept all incoming messages, or - ``[]`` or ``()`` to disable all message receiving, or - An iterable of one or more items defining the filter criteria. Each item should be 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 an integer with zero or more of the bits defined in `can-flags` set. This specifies properties 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. If the `CAN.FLAG_EXT_ID` bit is set in flags, the filter matches Extended CAN IDs only. If the `CAN.FLAG_EXT_ID` bit is not set, the filter matches Standard CAN IDs only. All filters are ORed together in the controller. Passing an empty list or tuple for the filters argument means that no messages will be received. Some CAN controllers require each filter to be associated with only one receive FIFO. In these cases, the filter items in the argument are allocated round-robin to the available FIFOs. This driver does not distinguish between FIFOs in the receive IRQ. .. note:: If the caller passes an iterable with more items than :data:`CAN.FILTERS_MAX`, ``ValueError`` will be raised. .. note:: If either the ``identifier`` or the ``bit_mask`` is out of range for the specified ID type, a ``ValueError`` with reason "invalid id" will be raised. Examples ^^^^^^^^ Receive all incoming messages:: can.set_filters(None) Receive messages with Standard ID values 0x301 and 0x700 only:: can.set_filters(((0x301, 0x7FF, 0), (0x700, 0x7FF, 0))) Receive messages with Standard ID values in range 0x300-0x3FF, and Extended ID value 0x50700 only:: can.set_filters(((0x300, 0x700, 0), (0x50700, 0x1FFF_FFFF, CAN.FLAG_EXT_ID))) .. data:: CAN.FILTERS_MAX Constant value that reads the maximum number of supported receive filters for this hardware controller. Note that some controllers may have more complex hardware restrictions on the number of filters in use (for example, counting Standard and Extended ID filters independently.) In these cases `CAN.set_filters` may raise a ``ValueError`` even when the ``FILTERS_MAX`` limit is not exceeded. .. method:: CAN.send(id, data, flags=0) Copy 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 on CAN identifier priority (lower numeric identifiers have higher priority). - *id* is an integer CAN identifier value. - *data* is a bytes object (or similar) containing the CAN message data, or describing a Remote Transmission Request (see below). - *flags* is an integer with zero or more of the bits defined in `can-flags` set, specifying properties of the outgoing CAN message (Extended ID, Remote Transmission Request, etc.) If the message is successfully queued for transmit onto the bus, the function returns an integer in the range ``0`` to `CAN.TX_QUEUE_LEN` (exclusive). This value is the transmit buffer index where the message is queued to send, and can be used by the `CAN.cancel_send` function and in `CAN.IRQ_TX` events. If the queue is full then the send will fail and ``None`` is returned. The send can also fail and return ``None`` if the provided *id* value has equal priority to an existing message in the transmit queue and the CAN controller hardware cannot guarantee that messages with the same ID will be sent onto the bus in the same order they were added to the queue. To queue the message anyway, pass the value :data:`CAN.FLAG_UNORDERED` flag in the *flags* argument. This flag indicates that it's OK to send messages with the same CAN ID onto the bus in any order. If the controller is in the "Bus Off" error state or disabled then calling this function will raise an ``OSError``. .. note:: This intentionally low-level implementation is designed so the caller can establish a software queue of outgoing messages. .. important:: The CAN "transmit queue" is not a FIFO queue, it is priority ordered, and although it can hold up to `CAN.TX_QUEUE_LEN` items there may be other hardware restrictions on messages which can be queued at the same time. Remote Transmission Requests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the bit `CAN.FLAG_RTR` is set in the *flags* argument then the controller will send a Remote Transmission Request instead of a message. In this case the contents of the *data* argument is ignored. The controller will send a request where the ``DLC`` length field is equal to the length of the *data* argument. Examples ^^^^^^^^ Attempt to send a message with three byte payload ``0a0b0c`` and Standard ID 0x200:: can.send(0x200, b"\x0a\x0b\x0c", 0) Attempt to send a message with an empty payload and Extended ID 0x180008. Indicate that the controller can send messages with this ID in any order, in case other messages are already queued to send with the same ID:: can.send(0x180008, b"", can.FLAG_EXT_ID | can.FLAG_UNORDERED) Attempt to send a Remote Transmission Request with length 8 bytes and Standard ID 0x555:: can.send(0x555, b" " * 8, can.FLAG_RTR) .. method:: CAN.recv(arg=None) Return a CAN message that has been received by the controller, according to filters set by :func:`CAN.set_filters`. This function takes a single optional argument, if provided then it must be a list of at least 4 elements where the second element is a `memoryview` object that refers to a `bytearray` or similar object that has enough capacity to hold any received CAN message (8 bytes for CAN Classic, 64 bytes for CAN FD). The provided list will be returned as a successful result, and avoids memory allocation inside the function. If no messages have been received by the CAN controller, this function returns ``None``. .. note:: `CAN.set_filters` must be called before any messages can be received by the controller. To receive all messages, call ``set_filters(None)``. If a message has been received by the CAN controller, this function returns a list with 4 elements: - Index 0 is the CAN ID of the received message, as an integer. - Index 1 is a memoryview that provides access to the received message data. - If *arg* is not provided then this is a `memoryview` holding the bytes which were received. This `memoryview` is backed by a newly allocated `bytearray` large enough to hold any received CAN message. This allows the result to be safely reused as a future *arg*, to save memory allocations. - If *arg* is provided then the provided `memoryview` will be resized to hold exactly the bytes which were received. The caller is responsible for making sure the backing object for the `memoryview` can hold a CAN message of any length. - Index 2 is an integer with zero or more of the bits defined in `can-flags` set. It indicates metadata about the received message. - Index 3 is an integer with zero or more of the bits defined in `can-recv-errors` set. Any non-zero value indicates potential issues when receiving CAN messages. These flags are reset inside the controller each time this function returns. Remote Transmission Requests ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If a Remote Transmission Request is received then the bit `CAN.FLAG_RTR` will be set in Index 2 and the memoryview at Index 1 will contain all zeroes, with a length equal to the ``DLC`` field of the received request. Example ^^^^^^^ :: can.set_filters(None) # receive all while True: res = can.recv() if res: can_id, data, flags, errs = res print("Received", hex(can_id), data.hex(), hex(flags), hex(errs)) else: time.sleep_ms(1) # not a good pattern, use the irq instead! .. method:: CAN.irq(handler=None, trigger=0, hard=False) Sets an interrupt *handler* function to be called when one or more of the events flagged in *trigger* has occurred. - *handler* is a function to be called when the interrupt event triggers. The handler must take exactly one argument which is the :class:`CAN` instance. - *trigger* configures the event(s) which can generate an interrupt. Possible values are a mask of one or more of the following: - `CAN.IRQ_RX` event occurs after the CAN controller has received at least one message into its RX FIFO (meaning that :func:`CAN.recv()` will return successfully). - `CAN.IRQ_TX` event occurs after the CAN controller has either successfully sent a message onto the CAN bus or failed to send a message. This trigger has additional requirements for the handler, see `machine_can_irq_flags` for details. - `CAN.IRQ_STATE` event occurs when the CAN controller has transitioned into a more severe error state. Call :func:`CAN.state()` to get the updated state. - *hard* if True, a hard interrupt is used. This reduces the delay between the CAN controller event and the handler being called. Hard interrupt handlers may not allocate memory; see :ref:`isr_rules`. Returns an irq object. If called with no arguments then a previously-configured irq object is returned. See `machine_can_irq_flags` for an example. .. method:: CAN.cancel_send(index) Request the CAN controller to cancel sending a message onto the bus. Argument *index* identifies a single transmit buffer. It should be an integer in the range ``0`` to ``CAN.TX_QUEUE_LEN`` (exclusive). Generally this will be a value previously returned by :func:`CAN.send()`. The result is ``True`` if a message was pending transmission in this buffer and transmission was cancelled. The result is ``False`` otherwise (either no message was pending transmission in this buffer, or transmission succeeded already). The IRQ event `CAN.IRQ_TX` should be used to determine if a message was definitely sent or not, but note there are potential race conditions if a transmission is cancelled and then the same buffer is used to send another message (especially if the CAN controller IRQ is not "hard"). .. method:: CAN.state() Returns an integer value indicating the current state of the controller. The value will be one of the values defined in `can-states`. Lower severity error states may automatically clear if the bus recovers, but the `CAN.STATE_BUS_OFF` state can only be recovered by calling :func:`CAN.restart()`. .. method:: CAN.get_counters(list=None /) Returns controller's error counter values. The result is a list of eight 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 Warning state from the Active state. - Number of times the controller entered the Error Passive state from the Warning state. - Number of times the controller entered the Bus Off state from the Error Passive 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_timings(list=None /) Returns a list of elements indicating the current timings configured in the CAN controller. This can be used to verify timings for debugging purposes. The result is a list of six 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: - Exact bitrate used by the controller. May vary from *bitrate* argument passed to :func:`CAN.init()` due to quantisation to meet hardware constraints. - Resynchronisation jump width (SJW) in units of time quanta for nominal bits. Has the same meaning as the *sjw* parameter of :func:`CAN.init()`. - Location of the sample point in units of time quanta for nominal bits. Has the same meaning as the *tseg1* parameter of :func:`CAN.init()`. - Location of the transmit point in units of time quanta for nominal bits. Has the same meaning as the *tseg2* parameter of :func:`CAN.init()`. - CAN FD timing information. ``None`` for controllers which don't support CAN FD, or if CAN FD is not initialised. Otherwise, a nested list of four elements corresponding to the items above but applicable to the CAN FD BRS feature. - Optional controller-specific timing information. Depending on the controller this will either be ``None`` if controller doesn't report any, or it will be a constant length list whose elements are specific to a particular hardware controller. .. note:: If :func:`CAN.init()` has not been called then this function still returns a result, but the result depends on the controller internals and may not be accurate. .. method:: CAN.restart() Causes the controller to exit `STATE_BUS_OFF` without clearing any other internal state. Also clears some of the error counters (always the number of times each error state has been entered, possibly TEC and REC depending on the controller.) Calling this function also cancels any messages waiting to be sent. No `IRQ_TX` interrupts are delivered for these messages. Note that this function may or may not cause the controller to exit the "Error Passive" state, depending whether the controller hardware zeroes TEC and REC or not. .. method:: CAN.deinit() De-initialises a previously active CAN instance. All pending messages (transmit and receive) are dropped and the controller stops interacting on the bus. To use this instance again, call :func:`CAN.init()`. No `IRQ_TX` or `IRQ_RX` interrupts are called in response to calling this function. See also :func:`CAN.restart()`. Constants --------- .. data:: CAN.TX_QUEUE_LEN Maximum number of CAN messages which can be queued in the outgoing hardware message queue of the controller. The "transmit buffer indexes" used by :func:`CAN.send()`, :func:`CAN.cancel_send()` and `machine_can_irq_flags` will be in this range. .. _can-modes: Modes ^^^^^ These values represent controller modes of operation, as passed to `CAN.init()`. Not all controllers may support all modes. Changing the mode of a running controller requires calling `CAN.deinit()` and then calling `CAN.init()` again with the new mode. .. data:: CAN.MODE_NORMAL The controller is active as a standard CAN network node (will acknowledge valid messages and may transmit errors depending on its current `State `). .. data:: CAN.MODE_SLEEP CAN controller is asleep in a low power mode. Depending on the controller, this may support waking the controller and transitioning to `CAN.MODE_NORMAL` if CAN traffic is received. .. data:: CAN.MODE_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. .. data:: CAN.MODE_SILENT CAN controller receives messages but does not interact with the CAN bus (including sending ACKs, errors, etc.) .. data:: CAN.MODE_SILENT_LOOPBACK A testing mode that does not require a CAN transceiver to be connected at all. The CAN controller receives its own transmitted messages without interacting with the CAN bus at all. The CAN TX and RX pins remain idle. .. _can-states: States ^^^^^^ These values are returned by :func:`CAN.state()` and reflect the error state of the CAN controller: .. data:: CAN.STATE_STOPPED The controller has not been initialised. .. data:: CAN.STATE_ACTIVE The controller is active and ``TEC`` and ``REC`` error counters are both below the warning threshold of 96. See :func:`CAN.get_counters()`. .. data:: CAN.STATE_WARNING The controller is active but at last one of the ``TEC`` and ``REC`` error counters are between 96 and 127. See :func:`CAN.get_counters()`. .. data:: CAN.STATE_PASSIVE The controller is in the "Error Passive" state meaning it no longer transmits active errors to the bus, but it is otherwise functional. This state is entered when at least one of the ``TEC`` and ``REC`` error counters is 128 or greater, but ``TEC`` is less than 255. See :func:`CAN.get_counters()`. .. data:: CAN.STATE_BUS_OFF The controller is in the Bus-Off state, meaning ``TEC`` error counter is greater than 255. The CAN controller will not interact with the bus in this state, and needs to be restarted via :func:`CAN.restart()` to continue. .. _can-flags: Message Flags ^^^^^^^^^^^^^ These values represent metadata about a CAN message. Functions :func:`CAN.send()`, :func:`CAN.recv()`, and :func:`CAN.set_filters()` either accept or return an integer value made up of zero or more of these flags bitwise ORed together. .. data:: CAN.FLAG_RTR Indicates a message is a remote transmission request. .. data:: CAN.FLAG_EXT_ID If set, indicates a Message identifier is Extended (29-bit). If not set, indicates a message identifier is Standard (11-bit). .. data:: CAN.FLAG_UNORDERED If set in the ``flags`` argument of :func:`CAN.send`, indicates that it's OK if messages with the same CAN ID are sent in any order onto the bus. Otherwise trying to queue multiple messages with the same ID may result in :func:`CAN.send` failing if the controller hardware can't enforce ordering. This flag is never set on received messages, and is ignored by `CAN.set_filters()`. .. _can-recv-errors: Receive Error Flags ^^^^^^^^^^^^^^^^^^^ The result of :func:`CAN.recv()` includes an integer value made up of zero or more of these flags bitwise ORed together. If set, these flags indicate potential general issues with receiving CAN messages. .. data:: CAN.RECV_ERR_FULL The hardware FIFO where this message was received is full, and additional incoming messages may be lost. .. data:: CAN.RECV_ERR_OVERRUN The hardware FIFO where this message was received is full, and one or more incoming messages has been lost. IRQ values ^^^^^^^^^^ .. data:: CAN.IRQ_RX CAN.IRQ_TX CAN.IRQ_STATE IRQ event triggers. Used with :func:`CAN.irq()` and `machine_can_irq_flags`. .. data:: CAN.IRQ_TX_FAILED CAN.IRQ_TX_IDX_SHIFT CAN.IRQ_TX_IDX_MASK Additional IRQ event flags for `CAN.IRQ_TX`. See `machine_can_irq_flags`. .. _machine_can_irq_flags: IRQ flags --------- Calling :func:`CAN.irq()` registers an interrupt handler with one or more of the triggers `CAN.IRQ_RX`, `CAN.IRQ_TX` and `CAN.IRQ_STATE`. The function returns an IRQ object, and calling the ``flags()`` function on this object returns an integer indicating which trigger event(s) triggered the interrupt. A CAN IRQ handler should call the ``flags()`` function repeatedly until it returns ``0``. When the ``flags()`` function returns with `CAN.IRQ_TX` bit set, the handler can also check the following flag bits in the result for additional information about the TX event: * ``CAN.IRQ_TX_FAILED`` bit is set if the transmit failed. Usually this will only happen if :func:`CAN.cancel_send()` was called, although it may also happen if the controller enters an error state. * ``CAN.IRQ_TX_MASK << CAN.IRQ_TX_SHIFT`` is a bitmasked region of the flags value that holds the index of the transmit buffer which generated the event. This will be an integer in the range ``0`` to `CAN.TX_QUEUE_LEN` (exclusive), and will match the result of a previous call to `CAN.send()`. IRQ_TX Example ^^^^^^^^^^^^^^ :: from machine import CAN def irq_send(can): while flags := can.irq().flags(): if flags & can.IRQ_TX: idx = (flags >> can.IRQ_TX_IDX_SHIFT) & can.IRQ_TX_IDX_MASK success = not (flags & can.IRQ_TX_FAILED) print("irq_send", idx, success) can = CAN(1, 500_000) can.irq(irq_send, trigger=can.IRQ_TX, hard=True) .. important:: If the `CAN.IRQ_TX` trigger is set then the handler **must** call ``flags()`` repeatedly until it returns ``0``, as shown in this example. Otherwise, CAN interrupts may not be correctly re-enabled.