Merge development branch into default.

Adds consistent support for filtering messages received on a Bus.

Author: hardbyte

CONTRIBUTORS.txt

@@ -16,3 +16,4 @@ Bruno Pennati
 Jack Jester-Weinstein
 Joshua Villyard
 Giuseppe Corbelli <[email protected]>
+Christian Sandberg

README

@@ -19,169 +19,30 @@ python-can
 The **C**\ ontroller **A**\ rea **N**\ etwork is a bus standard designed
 to allow microcontrollers and devices to communicate with each other. It
 has priority based bus arbitration, reliable deterministic
-communication. It is used in cars, trucks, wheelchairs and more. See
-`wikipedia <http://en.wikipedia.org/wiki/CAN_bus>`__ for more info.
+communication. It is used in cars, trucks, boats, wheelchairs and more.
 
-This module provides controller area network support for
-`Python <http://python.org/download/>`__.
+The ``can`` package provides controller area network support for
+Python developers; providing `common abstractions to
+different hardware devices`, and a suite of utilities for sending and receiving
+messages on a can bus.
 
-Configuration File
-------------------
+The library supports Python 2.7, Python 3.3+ and runs on Mac, Linux and Windows.
 
-In order to use this library a CAN interface needs to be specified. A
-method to do this is to create a configuration file.
-On Linux systems the config file is searched in the following paths:
+You can find more information in the documentation, online at
+`python-can.readthedocs.org <https://python-can.readthedocs.org/en/stable/>`__.
 
-1. ``/etc/can.conf``
-2. ``$HOME/.can``
-3. ``$HOME/.canrc``
 
-On Windows systems the config file is searched in the following paths:
-1. ``can.ini`` (current working directory)
-2. ``$APPDATA/can.ini``
-
-The configuration file sets the default interface and channel:
-
-::
-
-    [default]
-    interface = <the name of the interface to use>
-    channel = <the channel to use by default>
-
-Interfaces
+Discussion
 ----------
 
-The interface available are:
-
-kvaser
-~~~~~~
-
-`Kvaser <http://www.kvaser.com>`__'s CANLib SDK for Windows (also
-available on Linux)
-
-socketcan
-~~~~~~~~~
-
-On linux the socketcan interface is exposed via either:
-
--  socketcan\_ctypes
--  socketcan\_native
-
-serial
-~~~~~~
-
-A text based interface. For example use over bluetooth with
-``/dev/rfcomm0``
-
-pcan
-~~~~
-
-`Peak-System <http://www.peak-system.com/>`__'s PCAN-Basic API.
-
-IXXAT
-~~~~~
-
-`IXXAT <http://www.ixxat.com/>`__'s Virtual CAN Interface V3 SDK ONLY on Windows.
-The Linux ECI SDK is currently unsupported.
-On Linux some devices are supported with socketcan.
-
-virtual
-~~~~~~~
-
-A virtual CAN bus that can be used for automatic tests. Any Bus instances
-connecting to the same channel (in the same python program) will get each
-others messages.
-
-Installation
-------------
-
-GNU/Linux dependencies
-----------------------
-
-Reasonably modern Linux Kernels (2.6.25 or newer) have an implementation
-of ``socketcan``. This version of python-can will directly use socketcan
-if called with Python 3.3 or greater, otherwise that interface is used
-via ctypes.
-
-Windows dependencies
---------------------
-
-Kvaser
-~~~~~~
-
-To install ``python-can`` using the Kvaser CANLib SDK as the backend:
-
-1. Install the `latest stable release of
-   Python <http://python.org/download/>`__.
-
-2. Install `Kvaser's latest Windows CANLib
-   drivers <http://www.kvaser.com/en/downloads.html>`__.
-
-3. Test that Kvaser's own tools work to ensure the driver is properly
-   installed and that the hardware is working.
-
-PCAN
-~~~~
-
-To use the PCAN-Basic API as the backend (which has only been tested
-with Python 2.7):
-
-1. Download the latest version of the `PCAN-Basic
-   API <http://www.peak-system.com/Downloads.76.0.html?>`__.
-
-2. Extract ``PCANBasic.dll`` from the Win32 subfolder of the archive or
-   the x64 subfolder depending on whether you have a 32-bit or 64-bit
-   installation of Python.
-
-3. Copy ``PCANBasic.dll`` into the working directory where you will be
-   running your python script. There is probably a way to install the
-   dll properly, but I'm not certain how to do that.
-
-Note that PCANBasic API timestamps count seconds from system startup. To
-convert these to epoch times, the uptime library is used. If it is not
-available, the times are returned as number of seconds from system
-startup. To install the uptime library, run ``pip install uptime``.
-
-IXXAT
-~~~~~
-
-To install ``python-can`` using the IXXAT VCI V3 SDK as the backend:
-
-1. Install the `latest stable release of
-   Python <http://python.org/download/>`__.
-
-2. Install `IXXAT's latest Windows VCI V3 SDK
-   drivers <http://www.ixxat.com/support/file-and-documents-download/drivers/vci-v3-driver-download>`__.
-
-3. Test that IXXAT's own tools (i.e. MiniMon) work to ensure the driver 
-   is properly installed and that the hardware is working.
-
-Install python-can
-------------------
-
-You may need to install
-`pip <http://www.pip-installer.org/en/latest/installing.html>`__ and
-`setuptools <https://pypi.python.org/pypi/setuptools>`__ first.
-
-Two options, install normally with:
-
-::
-
-    python setup.py install
-
-Or to do a "development" install of this package to your machine (this
-allows you to make changes locally or pull updates from the Mercurial
-repository and use them without having to reinstall):
-
-::
-
-    python setup.py develop
+If you run into bugs, you can file them in our
+`issue tracker <https://bitbucket.org/hardbyte/python-can/issues>`__.
 
-On linux you will need ``sudo`` rights.
+There is also a `python-can <https://groups.google.com/forum/#!forum/python-can>`__
+mailing list for development discussion.
 
-Documentation and Help
-----------------------
+`Stackoverflow <https://stackoverflow.com/questions/tagged/can+python>`__ has several
+questions and answers tagged with ``python+can``.
 
-- The Sphinx documentation for python-can can be viewed online at `python-can.readthedocs.org <https://python-can.readthedocs.org/en/latest/>`__
-- Questions can be found on `StackOverflow <https://stackoverflow.com/questions/tagged/can+python>`__ (tagged with python+can)
-- `Google groups mailing list <https://groups.google.com/forum/#!forum/python-can>`__
+Wherever we interact, we strive to follow the
+`Python Community Code of Conduct <https://www.python.org/psf/codeofconduct/>`__.

can/__init__.py

@@ -1,18 +1,12 @@
 """
 can is an object-orient Controller Area Network interface module.
-
-Modules include:
-
-    :mod:`can.message`
-        defines the :class:`~can.Message` class which is the
-        lowest level of OO access to the library.
-
 """
 import logging
 log = logging.getLogger('can')
 
 rc = dict(channel=0)
 
+
 class CanError(IOError):
     pass
 

can/broadcastmanager.py

@@ -47,8 +47,8 @@ def modify_data(self, message):
         """Update the contents of this periodically sent message without altering
         the timing.
 
-        :param message: The :class:`~can.Message` with new :attr:`Message.data`. Note it must have the same
-        :attr:`Message.arbitration_id`.
+        :param message: The :class:`~can.Message` with new :attr:`Message.data`.
+            Note it must have the same :attr:`~can.Message.arbitration_id`.
         """
 
 

can/bus.py

@@ -43,6 +43,8 @@ def __init__(self, channel=None, can_filters=None, **config):
     def recv(self, timeout=None):
         """Block waiting for a message from the Bus.
 
+        :param float timeout: Seconds to wait for a message.
+
         :return:
             None on timeout or a :class:`can.Message` object.
         """
@@ -91,7 +93,7 @@ def set_filters(self, can_filters=None):
         raise NotImplementedError("Trying to set_filters on unsupported bus")
 
     def flush_tx_buffer(self):
-        """Used for CAN backends which need to flush their transmit buffer.
+        """Used for CAN interfaces which need to flush their transmit buffer.
 
         """
         pass

can/interfaces/interface.py

@@ -11,14 +11,18 @@ class Bus(object):
     """
     Instantiates a CAN Bus of the given `bustype`, falls back to reading a
     configuration file from default locations.
-
-    :raises: NotImplementedError if the bustype isn't recognized
-
     """
 
     @classmethod
     def __new__(cls, other, channel=None, *args, **kwargs):
+        """
+        Takes the same arguments as :class:`can.BusABC` with the addition of:
+
+        :param kwargs:
+            Should contain a bustype key with a valid interface name.
 
+        :raises: NotImplementedError if the bustype isn't recognized
+        """
         if 'bustype' in kwargs:
             can.rc['interface'] = kwargs['bustype']
             del kwargs['bustype']

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.
@@ -447,6 +495,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)

can/interfaces/pcan.py

@@ -60,9 +60,6 @@ def __init__(self, channel, *args, **kwargs):
         :param str channel:
             The can interface name. An example would be PCAN_USBBUS1
 
-        Backend Configuration
-        ---------------------
-
         :param int bitrate:
             Bitrate of channel in bit/s.
             Default is 500 Kbs