kopia lustrzana https://github.com/micropython/micropython
docs/library/pyb.CAN: Update CAN docs to match revised API.
iabdalkader
Damien George
rodzic
5562ed3f43
commit
5cdf964571
|
|
@ -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.
|
||||
|
|
|
|||
Ładowanie…
Reference in New Issue