pub
Fork of CANnucleo by
Diff: CAN.cpp
- Revision:
- 9:e9224f2c6d37
- Parent:
- 8:5c90d6b9a382
- Child:
- 10:227a455d0f9f
diff -r 5c90d6b9a382 -r e9224f2c6d37 CAN.cpp --- 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);