Add support for ICS neoVI interface

Adding support for ICS (INTREPID CONTROL SYSTEMS) neoVI interface via pyneovi

Author: pierreluctg

can/interfaces/interface.py

@@ -4,7 +4,7 @@
 
 VALID_INTERFACES = set(['kvaser', 'serial', 'pcan', 'socketcan_native',
                         'socketcan_ctypes', 'socketcan', 'usb2can', 'ixxat',
-                        'nican', 'remote', 'virtual'])
+                        'nican', 'remote', 'virtual', 'neovi'])
 
 
 class Bus(object):
@@ -75,6 +75,9 @@ def __new__(cls, other, channel=None, *args, **kwargs):
         elif interface == 'virtual':
             from can.interfaces.virtual import VirtualBus
             cls = VirtualBus
+        elif interface == 'neovi':
+            from can.interfaces.neovi_api import NeoVIBus
+            cls = NeoVIBus
         else:
             raise NotImplementedError("CAN interface '{}' not supported".format(interface))
 

can/interfaces/neovi_api/__init__.py

@@ -0,0 +1 @@
+from can.interfaces.neovi_api.neovi_api import NeoVIBus

can/interfaces/neovi_api/neovi_api.py

@@ -0,0 +1,208 @@
+"""
+pyneovi interface module.
+
+pyneovi is a Python wrapper around the API provided by Intrepid Control Systems
+for communicating with their NeoVI range of devices.
+
+Implementation references:
+* http://pyneovi.readthedocs.io/en/latest/
+* https://bitbucket.org/Kemp_J/pyneovi
+"""
+
+import logging
+
+import sys
+
+logger = logging.getLogger(__name__)
+
+try:
+    from queue import Queue, Empty
+except ImportError:
+    from Queue import Queue, Empty
+
+if sys.platform == "win32":
+    try:
+        from neovi import neodevice
+        from neovi import neovi
+        from neovi.structures import icsSpyMessage
+    except ImportError as e:
+        logger.warning("Cannot load pyneovi: %s", e)
+else:
+    # Will not work on other systems, but have it importable anyway for
+    # tests/sphinx
+    logger.warning("pyneovi library does not work on %s platform", sys.platform)
+
+from can import Message
+from can.bus import BusABC
+
+
+SPY_STATUS_XTD_FRAME = 0x04
+SPY_STATUS_REMOTE_FRAME = 0x08
+
+
+# For the neoVI hardware, TimeHardware2 is more significant than TimeHardware.
+# The resolution of TimeHardware is 1.6us and and TimeHardware2 is 104.8576 ms.
+# To calculate the time of the message in seconds use the following formula:
+# "Timestamp (sec) = TimeHardware2* 0.1048576 + TimeHardware * 0.0000016".
+NEOVI_TIMEHARDWARE_SCALING = 0.0000016
+NEOVI_TIMEHARDWARE2_SCALING = 0.1048576
+
+# For the neoVI PRO or ValueCAN hardware, TimeHardware2 is more significant than
+# TimeHardware. The resolution of TimeHardware is 1.0us and and TimeHardware2 is
+# 65.536 ms. To calculate the time of the message in seconds use the following
+# formula: "Timestamp (sec) = TimeHardware2* 0.065536 + TimeHardware * 0.000001"
+VALUECAN_TIMEHARDWARE_SCALING = 0.000001
+VALUECAN_TIMEHARDWARE2_SCALING = 0.065536
+
+
+def neo_device_name(device_type):
+    names = {
+        neovi.NEODEVICE_BLUE: 'neoVI BLUE',
+        neovi.NEODEVICE_DW_VCAN: 'ValueCAN',
+        neovi.NEODEVICE_FIRE: 'neoVI FIRE',
+        neovi.NEODEVICE_VCAN3: 'ValueCAN3',
+        neovi.NEODEVICE_YELLOW: 'neoVI YELLOW',
+        neovi.NEODEVICE_RED: 'neoVI RED',
+        neovi.NEODEVICE_ECU: 'neoECU',
+        # neovi.NEODEVICE_IEVB: ''
+    }
+    return names.get(device_type, 'Unknown neoVI')
+
+
+class NeoVIBus(BusABC):
+    """
+    The CAN Bus implemented for the pyneovi interface.
+    """
+
+    def __init__(self, channel=None, can_filters=None, **config):
+        """
+
+        :param int channel:
+            The Channel id to create this bus with.
+        :param list can_filters:
+            A list of dictionaries each containing a "can_id" and a "can_mask".
+
+                >>> [{"can_id": 0x11, "can_mask": 0x21}]
+
+        """
+        type_filter = config.get('type_filter', neovi.NEODEVICE_ALL)
+        neodevice.init_api()
+        self.device = neodevice.find_devices(type_filter)[0]
+        self.device.open()
+        self.channel_info = '%s %s on channel %s' % (
+            neo_device_name(self.device.get_type()),
+            self.device.device.SerialNumber,
+            channel
+        )
+
+        if self.device.get_type() in [neovi.NEODEVICE_DW_VCAN]:
+            self._time_scaling = (VALUECAN_TIMEHARDWARE_SCALING,
+                                  VALUECAN_TIMEHARDWARE2_SCALING)
+        else:
+            self._time_scaling = (NEOVI_TIMEHARDWARE_SCALING,
+                                  NEOVI_TIMEHARDWARE2_SCALING)
+
+        self.sw_filters = None
+        self.set_filters(can_filters)
+        self.rx_buffer = Queue()
+
+        self.network = int(channel) if channel is not None else None
+        self.device.subscribe_to(self._rx_buffer, network=self.network)
+
+    def __del__(self):
+        self.shutdown()
+
+    def shutdown(self):
+        self.device.pump_messages = False
+        if self.device.msg_queue_thread is not None:
+            self.device.msg_queue_thread.join()
+
+    def _rx_buffer(self, msg, user_data):
+        self.rx_buffer.put_nowait(msg)
+
+    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
+
+        logging.info("%s not matching" % arb_id)
+        return False
+
+    def _ics_msg_to_message(self, ics_msg):
+        return Message(
+            timestamp=(
+                self._time_scaling[1] * ics_msg.TimeHardware2 +
+                self._time_scaling[0] * ics_msg.TimeHardware
+            ),
+            arbitration_id=ics_msg.ArbIDOrHeader,
+            data=ics_msg.Data,
+            dlc=ics_msg.NumberBytesData,
+            extended_id=bool(ics_msg.StatusBitField &
+                             SPY_STATUS_XTD_FRAME),
+            is_remote_frame=bool(ics_msg.StatusBitField &
+                                 SPY_STATUS_REMOTE_FRAME),
+        )
+
+    def recv(self, timeout=None):
+        try:
+            ics_msg = self.rx_buffer.get(block=True, timeout=timeout)
+        except Empty:
+            pass
+        else:
+            if ics_msg.NetworkID == self.network and \
+                    self._is_filter_match(ics_msg.ArbIDOrHeader):
+                return self._ics_msg_to_message(ics_msg)
+
+    def send(self, msg):
+        data = tuple(msg.data)
+        flags = SPY_STATUS_XTD_FRAME if msg.is_extended_id else 0
+        if msg.is_remote_frame:
+            flags |= SPY_STATUS_REMOTE_FRAME
+
+        ics_msg = icsSpyMessage()
+        ics_msg.ArbIDOrHeader = msg.arbitration_id
+        ics_msg.NumberBytesData = len(data)
+        ics_msg.Data = data
+        ics_msg.StatusBitField = flags
+        ics_msg.StatusBitField2 = 0
+        ics_msg.DescriptionID = self.device.tx_id
+        self.device.tx_id += 1
+        self.device.tx_raw_message(ics_msg, self.network)
+
+    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.
+
+        :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``
+
+        """
+        self.sw_filters = can_filters
+
+        if self.sw_filters is None:
+            logger.info("Filtering has been disabled")
+        else:
+            for can_filter in can_filters:
+                can_id = can_filter["can_id"]
+                can_mask = can_filter["can_mask"]
+                logger.info("Filtering on ID 0x%X, mask 0x%X", can_id, can_mask)

doc/interfaces/neovi.rst

@@ -0,0 +1,54 @@
+neoVI Interface
+===============
+
+.. warning::
+
+    This ``neoVI`` documentation is a work in progress. Feedback and revisions
+    are most welcome!
+
+
+Interface to `Intrepid Control Systems <https://www.intrepidcs.com/>`__ neoVI
+API range of devices via `pyneovi <http://kempj.co.uk/projects/pyneovi/>`__
+wrapper on Windows.
+
+.. note::
+
+    This interface is not supported on Linux, however on Linux neoVI devices
+    are supported via :doc:`socketcan` with ICS `Kernel-mode SocketCAN module
+    for Intrepid devices
+    <https://github.com/intrepidcs/intrepid-socketcan-kernel-module>`__ and
+    `icsscand <https://github.com/intrepidcs/icsscand>`__
+
+
+Installation
+------------
+This neoVI interface requires the installation of the ICS neoVI DLL and pyneovi
+package.
+
+- Download and install the Intrepid Product Drivers
+    `Intrepid Product Drivers <https://cdn.intrepidcs.net/updates/files/ICSDrivers.zip>`__
+
+- Install pyneovi using pip and the pyneovi bitbucket repo:
+    .. code-block:: bash
+
+        pip install https://bitbucket.org/Kemp_J/pyneovi/get/default.zip
+
+
+Configuration
+-------------
+
+An example `can.ini` file for windows 7:
+
+::
+
+    [default]
+    interface = neovi
+    channel = 1
+
+
+Bus
+---
+
+.. autoclass:: can.interfaces.neovi_api.NeoVIBus
+
+