pub
Fork of CANnucleo by
Diff: CAN.cpp
- Revision:
- 8:5c90d6b9a382
- Parent:
- 6:c5a40d5fd9f1
- Child:
- 9:e9224f2c6d37
diff -r 62684572ae9c -r 5c90d6b9a382 CAN.cpp --- 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); }