micropython
diff --git a/‎docs/library/pyb.CAN.rst
Lines changed: 92 additions & 48 deletions b/‎docs/library/pyb.CAN.rst
Lines changed: 92 additions & 48 deletions
@@ -4,20 +4,29 @@
 class CAN -- controller area network communication bus
 ======================================================
 
-CAN implements the standard CAN communications protocol.  At
-the physical level it consists of 2 lines: RX and TX.  Note that
-to connect the pyboard to a CAN bus you must use a CAN transceiver
-to convert the CAN logic signals from the pyboard to the correct
+CAN implements support for classic CAN (available on F4, F7 MCUs) and CAN FD (H7 series) controllers.
+At the physical level CAN bus consists of 2 lines: RX and TX.  Note that to connect the pyboard to a
+CAN bus you must use a CAN transceiver to convert the CAN logic signals from the pyboard to the correct
 voltage levels on the bus.
 
-Example usage (works without anything connected)::
+Example usage for classic CAN controller in Loopback (transceiver-less) mode::
 
     from pyb import CAN
     can = CAN(1, CAN.LOOPBACK)
     can.setfilter(0, CAN.LIST16, 0, (123, 124, 125, 126))  # set a fil
10000
ter to receive messages with id=123, 124, 125 and 126
     can.send('message!', 123)   # send a message with id 123
     can.recv(0)                 # receive message on FIFO 0
 
+Example usage for CAN FD controller with all of the possible options enabled::
+
+    # FD frame + BRS mode + Extended frame ID. 500 Kbit/s for arbitration phase, 1Mbit/s for data phase.
+    can = CAN(1, CAN.NORMAL, baudrate=500_000, brs_baudrate=1_000_000, sample_point=80)
+    can.setfilter(0, CAN.RANGE, 0, (0xFFF0, 0xFFFF))
+    can.send('a'*64, 0xFFFF, fdf=True, brs=True, extframe=True)
+    can.recv(0)
+
+The following CAN module functions and their arguments are available
+for both classic and FD CAN controllers, unless otherwise stated.
 
 Constructors
 ------------
@@ -35,43 +44,48 @@ Constructors
      - ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)``
      - ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)``
 
-Class Methods
--------------
-.. classmethod:: CAN.initfilterbanks(nr)
-
-   Reset and disable all filter banks and assign how many banks should be available for CAN(1).
-
-   STM32F405 has 28 filter banks that are shared between the two available CAN bus controllers.
-   This function configures how many filter banks should be assigned to each. *nr* is the number of banks
-   that will be assigned to CAN(1), the rest of the 28 are assigned to CAN(2).
-   At boot, 14 banks are assigned to each controller.
-
 Methods
 -------
 
-.. method:: CAN.init(mode, extframe=False, prescaler=100, *, sjw=1, bs1=6, bs2=8, auto_restart=False, baudrate=0, sample_point=75)
+.. method:: CAN.init(mode, prescaler=100, *, sjw=1, bs1=6, bs2=8, auto_restart=False, baudrate=0, sample_point=75,
+        num_filter_banks=14, brs_sjw=1, brs_bs1=8, brs_bs2=3, brs_baudrate=0, brs_sample_point=75)
 
    Initialise the CAN bus with the given parameters:
 
      - *mode* is one of:  NORMAL, LOOPBACK, SILENT, SILENT_LOOPBACK
-     - if *extframe* is True then the bus uses extended identifiers in the frames
-       (29 bits); otherwise it uses standard 11 bit identifiers
-     - *prescaler* is used to set the duration of 1 time quanta; the time quanta
-       will be the input clock (PCLK1, see :meth:`pyb.freq()`) divided by the prescaler
-     - *sjw* is the resynchronisation jump width in units of the time quanta;
-       it can be 1, 2, 3, 4
-     - *bs1* defines the location of the sample point in units of the time quanta;
-       it can be between 1 and 1024 inclusive
-     - *bs2* defines the location of the transmit point in units of the time quanta;
-       it can be between 1 and 16 inclusive
+     - *prescaler* is the value by which the CAN input clock is divided to generate the
+       nominal bit time quanta. The prescaler can be a value between 1 and 1024 inclusive
+       for classic CAN, and between 1 and 512 inclusive for CAN FD.
+     - *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.
+     - *bs1* 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.
+     - *bs2* 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.
      - *auto_restart* sets whether the controller will automatically try and restart
        communications after entering the bus-off state; if this is disabled then
        :meth:`~CAN.restart()` can be used to leave the bus-off state
      - *baudrate* if a baudrate other than 0 is provided, this function will try to automatically
-       calculate a CAN bit-timing (overriding *prescaler*, *bs1* and *bs2*) that satisfies both
-       the baudrate and the desired *sample_point*.
-     - *sample_point* given in a percentage of the bit time, the *sample_point* specifies the position
-       of the last bit sample with respect to the whole bit time. The default *sample_point* is 75%.
+       calculate the CAN nominal bit time (overriding *prescaler*, *bs1* and *bs2*) that satisfies
+       both the baudrate and the desired *sample_point*.
+     - *sample_point* given in a percentage of the nominal bit time, the *sample_point* specifies the position
+       of the bit sample with respect to the whole nominal bit time. The default *sample_point* is 75%.
+     - *num_filter_banks* for classic CAN, this is the number of banks that will be assigned to CAN(1),
+       the rest of the 28 are assigned to CAN(2).
+     - *brs_prescaler* is the value by which the CAN FD input clock is divided to generate the
+       data bit time quanta. The prescaler can be a value between 1 and 32 inclusive.
+     - *brs_sjw* is the resynchronisation jump width in units of time quanta for data bits;
+       it can be a value between 1 and 16 inclusive
+     - *brs_bs1* defines the location of the sample point in units of the time quanta for data bits;
+       it can be a value between 1 and 32 inclusive
+     - *brs_bs2* defines the location of the transmit point in units of the time quanta for data bits;
+       it can be a value between 1 and 16 inclusive
+     - *brs_baudrate* if a baudrate other than 0 is provided, this function will try to automatically
+       calculate the CAN data bit time (overriding *brs_prescaler*, *brs_bs1* and *brs_bs2*) that satisfies
+       both the baudrate and the desired *brs_sample_point*.
+     - *brs_sample_point* given in a percentage of the data bit time, the *brs_sample_point* specifies the position
+       of the bit sample with respect
2364
 to the whole data bit time. The default *brs_sample_point* is 75%.
+
 
    The time quanta tq is the basic unit of time for the CAN bus.  tq is the CAN
    prescaler value divided by PCLK1 (the frequency of internal peripheral bus 1);
@@ -140,17 +154,17 @@ Methods
    - number of pending RX messages on fifo 0
    - number of pending RX messages on fifo 1
 
-.. method:: CAN.setfilter(bank, mode, fifo, params, *, rtr)
+.. method:: CAN.setfilter(bank, mode, fifo, params, *, rtr, extframe=False)
 
    Configure a filter bank:
 
-   - *bank* is the filter bank that is to be configured.
-   - *mode* is the mode the filter should operate in.
+   - *bank* is the classic CAN controller filter bank, or CAN FD filter index, to configure.
+   - *mode* is the mode the filter should operate in, see the tables below.
    - *fifo* is which fifo (0 or 1) a message should be stored in, if it is accepted by this filter.
    - *params* is an array of values the defines the filter. The contents of the array depends on the *mode* argument.
 
    +-----------+---------------------------------------------------------+
-   |*mode*     |contents of *params* array                               |
+   |*mode*     |Contents of *params* array for classic CAN controller    |
    +===========+=========================================================+
    |CAN.LIST16 |Four 16 bit ids that will be accepted                    |
    +-----------+---------------------------------------------------------+
@@ -165,10 +179,20 @@ Methods
    |CAN.MASK32 |As with CAN.MASK16 but with only one 32 bit id/mask pair.|
    +-----------+---------------------------------------------------------+
 
-   - *rtr* is an array of booleans that states if a filter should accept a
-     remote transmission request message.  If this argument is not given
-     then it defaults to ``False`` for all entries.  The length of the array
-     depends on the *mode* argument.
+   +-----------+---------------------------------------------------------+
+   |*mode*     |Contents of *params* array for CAN FD controller         |
+   +===========+=========================================================+
+   |CAN.RANGE  |Two ids that represent a range of accepted ids.          |
+   +-----------+---------------------------------------------------------+
+   |CAN.DUAL   |Two ids that will be accepted. For example (1, 2)        |
+   +-----------+---------------------------------------------------------+
+   |CAN.MASK   |One filter ID and a mask. For example (0x111, 0x7FF)     |
+   +-----------+---------------------------------------------------------+
+
+   - *rtr* For classic CAN controllers, this is an array of booleans that states if
+     a filter should accept a remote transmission request message. If this argument
+     is not given then it defaults to ``False`` for all entries. The length of the
+     array depends on the *mode* argument. For CAN FD, this argument is ignored.
 
    +-----------+----------------------+
    |*mode*     |length of *rtr* array |
@@ -182,11 +206,17 @@ Methods
    |CAN.MASK32 |1                     |
    +-----------+----------------------+
 
-.. method:: CAN.clearfilter(bank)
+   - *extframe* If True the frame will have an extended identifier (29 bits),
+     otherwise a standard identifier (11 bits) is used.
+
+
+.. method:: CAN.clearfilter(bank, extframe=False)
 
    Clear and disables a filter bank:
 
-   - *bank* is the filter bank that is to be cleared.
+   - *bank* is the classic CAN controller filter bank, or CAN FD filter index, to clear.
+   - *extframe* For CAN FD controllers, if True, clear an extended filter (configured with extframe=True),
+     otherwise the clear a standard identifier (configured with extframe=False).
 
 .. method:: CAN.any(fifo)
 
@@ -200,21 +230,22 @@ Methods
      - *list* is an optional list object to be used as the return value
      - *timeout* is the timeout in milliseconds to wait for the receive.
 
-   Return value: A tuple containing four values.
+   Return value: A tuple containing five values.
 
      - The id of the message.
+     - A boolean that indicates if the message ID is standard or extended.
      - A boolean that indicates if the message is an RTR message.
      - The FMI (Filter Match Index) value.
      - An array containing the data.
 
    If *list* is ``None`` then a new tuple will be allocated, as well as a new
-   bytes object to contain the data (as the fourth element in the tuple).
+   bytes object to contain the data (as the fifth element in the tuple).
 
-   If *list* is not ``None`` then it should be a list object with a least four
-   elements.  The fourth element should be a memoryview object which is created
+   If *list* is not ``None`` then it should be a list object with a least five
+   elements.  The fifth element should be a memoryview object which is created
    from either a bytearray or an array of type 'B' or 'b', and this array must
    have enough room for at least 8 bytes.  The list object will then be
-   populated with the first three return values above, and the memoryview object
+   populated with the first four return values above, and the memoryview object
    will be resized inplace to the size of the data and filled in with that data.
    The same list and memoryview objects can be reused in subsequent calls to
    this method, providing a way of receiving data without using the heap.
@@ -225,7 +256,7 @@ Methods
         # No heap memory is allocated in the following call
         can.recv(0, lst)
 
-.. method:: CAN.send(data, id, *, timeout=0, rtr=False)
+.. method:: CAN.send(data, id, *, timeout=0, rtr=False, extframe=False, fdf=False, brs=False)
 
    Send a message on the bus:
 
@@ -236,6 +267,13 @@ Methods
        a remote transmission request.  If *rtr* is True then only the length
        of *data* is used to fill in the DLC slot of the frame; the actual
        bytes in *data* are unused.
+     - *extframe* if True the frame will have an extended identifier (29 bits),
+       otherwise a standard identifier (11 bits) is used.
+     - *fdf* for CAN FD controllers, if set to True, the frame will have an FD
+       frame format, which supports data payloads up to 64 bytes.
+     - *brs* for CAN FD controllers, if set to True, the bitrate switching mode
+       is enabled, in which the data phase is transmitted at a differet bitrate.
+       See :meth:`CAN.init` for the data bit timing configuration parameters.
 
      If timeout is 0 the message is placed in a buffer in one of three hardware
      buffers and the method returns immediately. If all three buffers are in use
@@ -302,4 +340,10 @@ Constants
           CAN.LIST32
           CAN.MASK32
 
-   The operation mode of a filter used in :meth:`~CAN.setfilter()`.
+   The operation mode of a filter used in :meth:`~CAN.setfilter()` for classic CAN.
+
+.. data:: CAN.DUAL
+          CAN.RANGE
+          CAN.MASK
+
+   The operation mode of a filter used in :meth:`~CAN.setfilter()` for CAN FD.