djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/library/pyb.CAN: Update CAN docs to match revised API.

Browse Source
This commit is contained in:
iabdalkader 2022-02-20 20:29:32 +02:00 committed by Damien George
parent 5562ed3f43
commit 5cdf964571
1 changed files with 92 additions and 48 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
docs/library/pyb.CAN.rst
View File

@ -4,13 +4,12 @@
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)
@ -18,6 +17,16 @@ Example usage (works without anything connected)::
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 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.