Merged in kvaser-set-filters (pull request #33)

Improved filters for Kvaser. Hardware and software filtering options.

Author: hardbyte

can/interfaces/kvaser/canlib.py

@@ -349,16 +349,6 @@ def __init__(self, channel, can_filters=None, **config):
                  4)
         canSetBusParams(self._read_handle, bitrate, tseg1, tseg2, sjw, no_samp, 0)
 
-        if can_filters is not None and len(can_filters):
-            log.info("The kvaser canlib backend is filtering messages")
-            code, mask = 0, 0
-            for can_filter in can_filters:
-                code |= can_filter['can_id']
-                mask |= can_filter['can_mask']
-            log.info("Filtering on: {}  {}".format(code, mask))
-            canSetAcceptanceFilter(self._read_handle, code, mask, 0)
-            canSetAcceptanceFilter(self._read_handle, code, mask, 1)
-
         if self.single_handle:
             log.debug("We don't require separate handles to the bus")
             self._write_handle = self._read_handle
@@ -367,6 +357,9 @@ def __init__(self, channel, can_filters=None, **config):
             self._write_handle = canOpenChannel(channel, canstat.canOPEN_ACCEPT_VIRTUAL)
             canBusOn(self._read_handle)
 
+        self.sw_filters = []
+        self.set_filters(can_filters)
+
         can_driver_mode = canstat.canDRIVER_SILENT if driver_mode == DRIVER_MODE_SILENT else canstat.canDRIVER_NORMAL
         canSetBusOutputControl(self._write_handle, can_driver_mode)
         log.debug('Going bus on TX handle')
@@ -384,6 +377,41 @@ def __init__(self, channel, can_filters=None, **config):
 
         super(KvaserBus, self).__init__()
 
+    def set_filters(self, can_filters=None):
+        """Apply filtering to all messages received by this Bus.
+
+        Calling without passing any filters will reset the applied filters.
+
+        Since Kvaser only supports setting one filter per handle, the filtering
+        will be done in the :meth:`recv` if more than one filter is requested.
+
+        :param list can_filters:
+            A list of dictionaries each containing a "can_id" and a "can_mask".
+
+            >>> [{"can_id": 0x11, "can_mask": 0x21}]
+
+            A filter matches, when ``<received_can_id> & can_mask == can_id & can_mask``
+        """
+        can_id = 0
+        can_mask = 0
+
+        if not can_filters:
+            log.info('Filtering has been disabled')
+            self.sw_filters = []
+        elif len(can_filters) == 1:
+            can_id = can_filters[0]['can_id']
+            can_mask = can_filters[0]['can_mask']
+            log.info('canlib is filtering on ID 0x%X, mask 0x%X', can_id, can_mask)
+            self.sw_filters = []
+        elif len(can_filters) > 1:
+            log.info('Filtering is handled in Python')
+            self.sw_filters = can_filters
+
+        # Set same filter for both handles as well as standard and extended IDs
+        for handle in (self._read_handle, self._write_handle):
+            for ext in (0, 1):
+                canSetAcceptanceFilter(handle, can_id, can_mask, ext)
+
     def flush_tx_buffer(self):
         """
         Flushes the transmit buffer on the Kvaser
@@ -417,6 +445,26 @@ def __convert_timestamp(self, value):
             self.pc_time_offset += lag
         return timestamp
 
+    def _is_filter_match(self, arb_id):
+        """
+        If SW filtering is used, checks if the `arb_id` matches any of
+        the filters setup.
+
+        :param int arb_id:
+            CAN ID to check against.
+
+        :return:
+            True if `arb_id` matches any filters
+            (or if SW filtering is not used).
+        """
+        if not self.sw_filters:
+            # Filtering done on HW or driver level or no filtering
+            return True
+        for can_filter in self.sw_filters:
+            if not (arb_id ^ can_filter['can_id']) & can_filter['can_mask']:
+                return True
+        return False
+
     def recv(self, timeout=None):
         """
         Read a message from kvaser device.
@@ -441,6 +489,8 @@ def recv(self, timeout=None):
 
         if status == canstat.canOK:
             log.debug('read complete -> status OK')
+            if not self._is_filter_match(arb_id.value):
+                return None
             data_array = data.raw
             flags = flags.value
             is_extended = bool(flags & canstat.canMSG_EXT)

doc/kvaser.rst

@@ -16,25 +16,20 @@ Internals
 The Kvaser :class:`~can.Bus` object with a physical CAN Bus can be operated in two
 modes; ``single_handle`` mode with one shared bus handle used for both reading and
 writing to the CAN bus, or with two separate bus handles.
+Two separate handles are needed if receiving and sending messages are done in
+different threads (see `Kvaser documentation
+<http://www.kvaser.com/canlib-webhelp/page_user_guide_threads_applications.html>`_).
 
 
 .. warning:: Any objects inheriting from `Bus`_ should *not* directly
         use the interface handle(/s).
 
 
-Threading
-~~~~~~~~~
+Message filtering
+~~~~~~~~~~~~~~~~~
 
-To avoid contention for the bus handle in ``single_handle`` mode, access is protected for
-the **read** and **write** daemon threads with a ``writing_event`` *Event* and a
-``done_writing`` *Condition*.
-
-The read thread acquires ``done_writing`` and while ``writing_event`` is set
-blocks waiting on the ``done_writing`` Condition. A 1ms blocking read is carried
-out before ``done_writing`` is released.
-
-The write thread blocks for 5ms on a queue (to allow the thread to stop). If
-a message was received it *sets* the writing_event to tell the read thread
-that a message in waiting to be sent. The ``done_writing`` is acquired for
-the actual write, the writing_event is cleared and the ``done_writing`` event
-is notified to start the read thread again.
+The Kvaser driver and hardware only supports setting one filter per handle.
+If one filter is requested, this is will be handled by the Kvaser driver.
+If more than one filter is needed, these will be handled in Python code
+in the ``recv`` method. If a message does not match any of the filters,
+``recv()`` will return None.

test/test_kvaser.py

@@ -26,6 +26,7 @@ def setUp(self):
         canlib.canClose = Mock()
         canlib.canSetBusOutputControl = Mock()
         canlib.canGetChannelData = Mock()
+        canlib.canSetAcceptanceFilter = Mock()
         canlib.canWriteWait = self.canWriteWait
         canlib.canReadWait = self.canReadWait
 
@@ -49,6 +50,61 @@ def test_bus_shutdown(self):
         self.assertTrue(canlib.canBusOff.called)
         self.assertTrue(canlib.canClose.called)
 
+    def test_filter_setup(self):
+        # No filter in constructor
+        expected_args = [
+            ((0, 0, 0, 0),),       # Disable filtering STD on read handle
+            ((0, 0, 0, 1),),       # Disable filtering EXT on read handle
+            ((0, 0, 0, 0),),       # Disable filtering STD on write handle
+            ((0, 0, 0, 1),),       # Disable filtering EXT on write handle
+        ]
+        self.assertEqual(canlib.canSetAcceptanceFilter.call_args_list,
+                         expected_args)
+
+        # One filter, will be handled by canlib
+        canlib.canSetAcceptanceFilter.reset_mock()
+        self.bus.set_filters([
+            {'can_id': 0x8, 'can_mask': 0xff}
+        ])
+        expected_args = [
+            ((0, 0x8, 0xff, 0),),       # Enable filtering STD on read handle
+            ((0, 0x8, 0xff, 1),),       # Enable filtering EXT on read handle
+            ((0, 0x8, 0xff, 0),),       # Enable filtering STD on write handle
+            ((0, 0x8, 0xff, 1),),       # Enable filtering EXT on write handle
+        ]
+        self.assertEqual(canlib.canSetAcceptanceFilter.call_args_list,
+                         expected_args)
+
+        # Multiple filters, will be handled in Python
+        canlib.canSetAcceptanceFilter.reset_mock()
+        multiple_filters = [
+            {'can_id': 0x8, 'can_mask': 0xff},
+            {'can_id': 0x9, 'can_mask': 0xff}
+        ]
+        self.bus.set_filters(multiple_filters)
+        expected_args = [
+            ((0, 0, 0, 0),),       # Disable filtering STD on read handle
+            ((0, 0, 0, 1),),       # Disable filtering EXT on read handle
+            ((0, 0, 0, 0),),       # Disable filtering STD on write handle
+            ((0, 0, 0, 1),),       # Disable filtering EXT on write handle
+        ]
+        self.assertEqual(canlib.canSetAcceptanceFilter.call_args_list,
+                         expected_args)
+        self.assertEqual(self.bus.sw_filters, multiple_filters)
+
+    def test_sw_filtering(self):
+        self.bus.set_filters([
+            {'can_id': 0x8, 'can_mask': 0xff},
+            {'can_id': 0x9, 'can_mask': 0xffff}
+        ])
+        self.assertTrue(self.bus._is_filter_match(0x8))
+        self.assertTrue(self.bus._is_filter_match(0x9))
+        self.assertTrue(self.bus._is_filter_match(0x108))
+        self.assertTrue(self.bus._is_filter_match(0x10009))
+        self.assertFalse(self.bus._is_filter_match(0x10))
+        self.assertFalse(self.bus._is_filter_match(0x0))
+        self.assertFalse(self.bus._is_filter_match(0x109))
+
     def test_send_extended(self):
         msg = can.Message(
             arbitration_id=0xc0ffee,