Diff: CAN.cpp

Revision:

8:5c90d6b9a382

Parent:

6:c5a40d5fd9f1

Child:

9:e9224f2c6d37

--- a/CAN.cpp	Fri Oct 23 19:51:51 2015 +0000
+++ b/CAN.cpp	Fri Oct 30 23:55:13 2015 +0000
@@ -130,12 +130,80 @@
 }
 
 /**
- * @brief
- * @note
- * @param
- * @retval
+ * @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).
+ *          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.
+ *          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,
+ *          the message is discarded by hardware without disturbing the software.
+ *
+ * @param   id: 'Filter ID' defines the bit values to be compared with the corresponding received bits
+ *
+ * Mapping of 32-bits (4-bytes) : | STID[10:3] | STID[2:0] EXID[17:13] | EXID[12:5] |  EXID[4:0] IDE RTR 0 |
+ *
+ * STID - Stardard Identifier bits
+ * EXID - Extended Identifier bits
+ * [x:y]- bit range
+ * IDE  - Identifier Extension bit (0 -> Standard Identifier, 1 -> Extended Identifier)
+ * RTR  - Remote Transmission Request bit
+ *
+ * @param   mask: 'Filter mask' defines which bits of the 'Filter ID' are compared with the received bits
+ *                and which bits are disregarded.
+
+ * Mapping of 32-bits (4-bytes) : | STID[10:3] | STID[2:0] EXID[17:13] | EXID[12:5] |  EXID[4:0] IDE RTR 0 |
+ *
+ * STID - Stardard Identifier bits
+ * EXID - Extended Identifier bits
+ * [x:y]- bit range
+ * IDE  - Identifier Extension bit
+ * RTR  - Remote Transmission Request bit
+ *
+ * 1 : bit is considered
+ * 0 : bit is disregarded
+ *
+ * Example of filter set-up and filtering:
+ *
+ * Let's assume we would like to receive only messages with standard identifier STID = 0x0207  (STID[15:0] = 00000010 00000111)
+ *
+ * We map the STID to filter ID by shifting the bits appropriately:
+ * 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
+ *
+ * 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
+ * and no message would reach filter #1!
+ * To set-up filter #0 we call:
+ * can.filter(0x0207 << 21, 0xFFE00000, 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.
+ *
+ * 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
+ *  
  */
-int CAN::filter(unsigned int id, unsigned int mask, CANFormat format /* CANAny */, int handle /* 0 */) {
+int CAN::filter(unsigned int id, unsigned int mask, CANFormat format /* = CANAny */, int handle /* = 0 */) {
     return can_filter(&_can, id, mask, format, handle);
 }