stmhal: Add support for CAN rx callbacks.

1 files changed, 53 insertions, 19 deletions

diff --git a/docs/library/pyb.CAN.rst b/docs/library/pyb.CAN.rst
index e160f6797..8f417f735 100644
--- a/docs/library/pyb.CAN.rst
+++ b/docs/library/pyb.CAN.rst
@@ -26,30 +26,30 @@ Constructors
    initialised (it has the settings from the last initialisation of
    the bus, if any).  If extra arguments are given, the bus is initialised.
    See ``init`` for parameters of initialisation.
-   
+
    The physical pins of the CAN busses are:
-   
+
      - ``CAN(1)`` is on ``YA``: ``(RX, TX) = (Y3, Y4) = (PB8, PB9)``
      - ``CAN(2)`` is on ``YB``: ``(RX, TX) = (Y5, Y6) = (PB12, PB13)``
 
 Class Methods
 -------------
 .. method:: 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). 
+   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)
 
    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
@@ -83,14 +83,14 @@ Methods
    Turn off the CAN bus.
 
 .. method:: can.setfilter(bank, mode, fifo, params)
-   
+
    Configure a filter bank:
-   
+
    - ``bank`` is the filter bank that is to be configured.
    - ``mode`` is the mode the filter should operate in.
-   - ``fifo`` is which fifo (0 or 1) a message should be stored in, if it is accepted by this filter.   
+   - ``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 parameter array                              |
    +===========+=========================================================+
@@ -106,11 +106,11 @@ Methods
    +-----------+---------------------------------------------------------+
    |CAN.MASK32 |As with CAN.MASK16 but with only one 32 bit id/mask pair.|
    +-----------+---------------------------------------------------------+
-   
+
 .. method:: can.clearfilter(bank)
 
    Clear and disables a filter bank:
-   
+
    - ``bank`` is the filter bank that is to be cleared.
 
 .. method:: can.any(fifo)
@@ -120,22 +120,56 @@ Methods
 .. method:: can.recv(fifo, \*, timeout=5000)
 
    Receive data on the bus:
-   
+
      - ``fifo`` is an integer, which is the FIFO to receive on
      - ``timeout`` is the timeout in milliseconds to wait for the receive.
-   
+
    Return value: buffer of data bytes.
 
 .. method:: can.send(send, addr, \*, timeout=5000)
 
    Send a message on the bus:
-   
+
      - ``send`` is the data to send (an integer to send, or a buffer object).
      - ``addr`` is the address to send to
      - ``timeout`` is the timeout in milliseconds to wait for the send.
-   
+
    Return value: ``None``.
 
+.. method:: can.rxcallback(fifo, fun)
+
+   Register a function to be called when a message is accepted into a empty fifo:
+
+   - ``fifo`` is the receiving fifo.
+   - ``fun`` is the function to be called when the fifo becomes non empty.
+
+   The callback function takes two arguments the first is the can object it self the second is
+   a integer that indicates the reason for the callback.
+
+   +--------+------------------------------------------------+
+   | Reason |                                                |
+   +========+================================================+
+   | 0      | A message has been accepted into a empty FIFO. |
+   +--------+------------------------------------------------+
+   | 1      | The FIFO is full                               |
+   +--------+------------------------------------------------+
+   | 2      | A message has been lost due to a full FIFO     |
+   +--------+------------------------------------------------+
+
+   Example use of rxcallback::
+
+     def cb0(bus, reason):
+       print('cb0')
+       if reason == 0:
+           print('pending')
+       if reason == 1:
+           print('full')
+       if reason == 2:
+           print('overflow')
+
+     can = CAN(1, CAN.LOOPBACK)
+     can.rxcallback(0, cb0)
+
 Constants
 ---------
 
@@ -151,4 +185,4 @@ Constants
 .. data:: CAN.LIST32
 .. data:: CAN.MASK32
 
-	the operation mode of a filter
+   the operation mode of a filter