Diff: CAN.cpp

Revision:

9:e9224f2c6d37

Parent:

8:5c90d6b9a382

Child:

10:227a455d0f9f

--- a/CAN.cpp	Fri Oct 30 23:55:13 2015 +0000
+++ b/CAN.cpp	Sat Oct 31 18:40:03 2015 +0000
@@ -130,13 +130,13 @@
 }
 
 /**
- * @brief   Sets-up a CAN filter
+ * @brief   Sets up a CAN filter
  * @note    At the present, CANnucleo supports only mask mode and 32-bit filter scale.
  *          Identifier list mode filtering and 16-bit filter scale are not supported.
- *          There are 14 filters available (0 - 13).
+ *          There are 14 filters available (0 - 13) for the application to set up.
  *          Each filter is a 32-bit filter defined by a filter ID and a filter mask.
- *          You may set-up up to 14 filters. If no filter is set-up then no CAN message is accepted!
- *          That's why filter #0 is set-up in the constructor to receive all CAN messages by default.
+ *          If no filter is set up then no CAN message is accepted (received)!
+ *          That's why filter #0 is set up in the constructor to receive all CAN messages by default.
  *          On reception of a message it is compared with filter #0. If there is a match, the message is stored.
  *          If there is no match, the incoming identifier is then compared with the next filter.
  *          If the received identifier does not match any of the identifiers configured in the filters,
@@ -150,7 +150,7 @@
  * EXID - Extended Identifier bits
  * [x:y]- bit range
  * IDE  - Identifier Extension bit (0 -> Standard Identifier, 1 -> Extended Identifier)
- * RTR  - Remote Transmission Request bit
+ * RTR  - Remote Transmission Request bit (0 -> Remote Transmission Request, 1 -> Standard message)
  *
  * @param   mask: 'Filter mask' defines which bits of the 'Filter ID' are compared with the received bits
  *                and which bits are disregarded.
@@ -174,34 +174,46 @@
  * Filter id = STID << (16 + (15 - 10)) = STID << 21 = 01000000 11100000 00000000 00000000 = 0x40E00000
  *
  * To compare only the bits representing STID we set the filter mask adequately:
- * Filter mask = 11111111 11100000 00000000 00000000 = 0xFFE00000
+ * Filter mask = 11111111 11100000 00000000 00000100 = 0xFFE00004
  *
- * Keep in mind that filter #0 was already set-up in the constructor to receive all CAN messages by default.
- * So we have to reconfigure it. If we were set-up filter #1 here then filter #0 would receive all messages
+ * Keep in mind that filter #0 was already set up in the constructor to receive all CAN messages by default.
+ * So we have to reconfigure it. If we were set up filter #1 here then filter #0 would receive all the messages
  * and no message would reach filter #1!
- * To set-up filter #0 we call:
- * can.filter(0x0207 << 21, 0xFFE00000, CANAny, 0);
+ *
+ * To set up filter #0 we call:
+ *     can.filter(0x0207 << 21, 0xFFE00004, CANAny, 0);
  *
- *                 -------------- Only these bits of filter id are compared with the corresponding bits of received message (the others are disregarded)
- *                 |||||||| |||
- * Filter mask   = 11111111 11100000 00000000 00000000 (= 0xFFE00000)
- * Filter id     = 01000000 11100000 00000000 00000000 (= 0x40E00000)
- *                 |||||||| |||
- *                 -------------- The values of these bits must match to received the message. Otherwise it is discarded.
- *                 |||||||| |||
- * Received id   = 01000000 11100000 00000000 00000010 (= 0x40E00002)
- *                             ||||| |||||||| ||||||||
- *                             ------------------------- These bits are disregarded (masked). They can have arbitrary values.
+ *             Only these bits of filter id are compared with the corresponding 
+ *             bits of received message (the others are disregarded)
+ *                                |
+ *                 ---------------------------------
+ *                 |||||||| |||                    |
+ *   Filter mask = 11111111 11100000 00000000 00000100 (= 0xFFE00004)
+ *   Filter id   = 01000000 11100000 00000000 00000000 (= 0x40E00000)
+ *                 |||||||| |||                    |
+ *                 ---------------------------------
+ *                                |
+ *            To receive the message the values of these bits must match. 
+ *            Otherwise the message is passed to the next filter or 
+ *            discarded if this was the last active filter.
+ *                                |
+ *                 ---------------------------------
+ *                 |||||||| |||                    |
+ *   Received id = 01000000 11100000 00000000 00000010 (= 0x40E00002)
+ *                             ||||| |||||||| ||||| ||
+ *                             -----------------------
+ *                                         |
+ *                          These bits are disregarded (masked).
+ *                          They can have arbitrary values.
  *
  * NOTE: For the meaning of individual bits see the mapping of 32-bits explained above.
  *
- * @format: This parameter must be CANAny
- * @handle: Selects the filter. This parameter must be a number between 0 and 13.
- * @retval:  0 - successful
- *           1 - error
- *           2 - busy
- *           3 - time out
- *  
+ * @param   format: This parameter must be CANAny
+ * @param   handle: Selects the filter. This parameter must be a number between 0 and 13.
+ * @param   retval: 0 - successful
+ *                  1 - error
+ *                  2 - busy
+ *                  3 - time out  
  */
 int CAN::filter(unsigned int id, unsigned int mask, CANFormat format /* = CANAny */, int handle /* = 0 */) {
     return can_filter(&_can, id, mask, format, handle);