Update usb2can.

Docs and internal api

Author: hardbyte

can/bus.py

@@ -7,7 +7,6 @@
 
 
 class BusABC(object):
-
     """CAN Bus Abstract Base Class
 
     Concrete implementations must implement the following methods:

can/interfaces/usb2can/__init__.py

@@ -1 +1,2 @@
 from can.interfaces.usb2can.usb2canInterface import Usb2canBus
+from can.interfaces.usb2can.usb2canabstractionlayer import Usb2CanAbstractionLayer

can/interfaces/usb2can/usb2canInterface.py

@@ -3,7 +3,7 @@
 import logging
 
 from can import BusABC, Message
-from can.interfaces.usb2can.usb2can import *
+from can.interfaces.usb2can.usb2canabstractionlayer import *
 
 bootTimeEpoch = 0
 try:
@@ -18,7 +18,7 @@
 log = logging.getLogger('can.usb2can')
 
 
-def set_string(deviceID, baudrate='500'):
+def format_connection_string(deviceID, baudrate='500'):
     """setup the string for the device
 
     config = deviceID + '; ' + baudrate
@@ -70,13 +70,27 @@ def message_convert_rx(messagerx):
     return msgrx
 
 
-# interface functions
 class Usb2canBus(BusABC):
-    def __init__(self, channel, *args, **kwargs):
+    """Interface to a USB2CAN Bus.
+
+    Note the USB2CAN interface doesn't implement set_filters, or flush_tx_buffer methods.
+
+    :param str channel:
+        The device's serial number. If not provided, Windows Management Instrumentation
+        will be used to identify the first such device. The *kwarg* `serial` may also be
+        used.
+
+    :param int bitrate:
+        Bitrate of channel in bit/s. Values will be limited to a maximum of 1000 Kb/s.
+        Default is 500 Kbs
 
-        self.can = usb2can()
+    :param int flags:
+        Flags to directly pass to open function of the usb2can abstraction layer.
+    """
+
+    def __init__(self, channel, *args, **kwargs):
 
-        enable_flags = c_ulong
+        self.can = Usb2CanAbstractionLayer()
 
         # set flags on the connection
         if 'flags' in kwargs:
@@ -88,6 +102,8 @@ def __init__(self, channel, *args, **kwargs):
         # code to get the serial number of the device
         if 'serial' in kwargs:
             deviceID = kwargs["serial"]
+        elif channel is not None:
+            deviceID = channel
         else:
             from can.interfaces.usb2can.usb2canSerialFindWin import serial
             deviceID = serial()
@@ -103,25 +119,25 @@ def __init__(self, channel, *args, **kwargs):
         else:
             baudrate = 500
 
-        connector = set_string(deviceID, baudrate)
+        connector = format_connection_string(deviceID, baudrate)
 
-        self.handle = self.can.CanalOpen(connector, enable_flags)
+        self.handle = self.can.open(connector, enable_flags)
 
     def send(self, msg):
         tx = message_convert_tx(msg)
-        self.can.CanalSend(self.handle, byref(tx))
+        self.can.send(self.handle, byref(tx))
 
     def recv(self, timeout=None):
 
         messagerx = CanalMsg()
 
         if timeout is None:
-            status = self.can.CanalReceive(self.handle, byref(messagerx))
+            status = self.can.receive(self.handle, byref(messagerx))
 
         else:
             time = c_ulong
             time = timeout
-            status = self.can.CanalBlockingReceive(self.handle, byref(messagerx), time)
+            status = self.can.blocking_receive(self.handle, byref(messagerx), time)
 
         if status is 0:
             rx = message_convert_rx(messagerx)
@@ -133,4 +149,4 @@ def recv(self, timeout=None):
 
     def shutdown(self):
         """Shut down the device safely"""
-        status = self.can.CanalClose(self.handle)
+        status = self.can.close(self.handle)

can/interfaces/usb2can/usb2can.py renamed to can/interfaces/usb2can/usb2canabstractionlayer.py

@@ -3,8 +3,10 @@
 from ctypes import *
 from struct import *
 import logging
-# type definitions
 
+log = logging.getLogger('can.usb2can')
+
+# type definitions
 flags = c_ulong
 pConfigureStr = c_char_p
 handle = c_long
@@ -47,100 +49,102 @@ class CanalMsg(Structure):
                 ('timestamp', c_ulong)]
 
 
-msg = CanalMsg
+class Usb2CanAbstractionLayer:
+    """A low level wrapper around the usb2can library.
 
+    Documentation: http://www.8devices.com/media/products/usb2can/downloads/CANAL_API.pdf
 
-class usb2can:
+    """
     def __init__(self):
         self.__m_dllBasic = windll.LoadLibrary("usb2can.dll")
 
-        if self.__m_dllBasic == None:
-            logging.warning('DLL failed to load')
+        if self.__m_dllBasic is None:
+            log.warning('DLL failed to load')
 
-    def CanalOpen(self, pConfigureStr, flags):
+    def open(self, pConfigureStr, flags):
         try:
             res = self.__m_dllBasic.CanalOpen(pConfigureStr, flags)
             return res
         except:
-            logging.warning('Failed to open')
+            log.warning('Failed to open')
             raise
 
-    def CanalClose(self, handle):
+    def close(self, handle):
         try:
             res = self.__m_dllBasic.CanalClose(handle)
             return res
         except:
-            logging.warning('Failed to close')
+            log.warning('Failed to close')
             raise
 
-    def CanalSend(self, handle, msg):
+    def send(self, handle, msg):
         try:
             res = self.__m_dllBasic.CanalSend(handle, msg)
             return res
         except:
-            logging.warning('Sending error')
+            log.warning('Sending error')
             raise can.CanError("Failed to transmit frame")
 
-    def CanalReceive(self, handle, msg):
+    def receive(self, handle, msg):
         try:
             res = self.__m_dllBasic.CanalReceive(handle, msg)
             return res
         except:
-            logging.warning('Receive error')
+            log.warning('Receive error')
             raise
 
-    def CanalBlockingSend(self, handle, msg, timeout):
+    def blocking_send(self, handle, msg, timeout):
         try:
             res = self.__m_dllBasic.CanalBlockingSend(handle, msg, timeout)
             return res
         except:
-            logging.warning('Blocking send error')
+            log.warning('Blocking send error')
             raise
 
-    def CanalBlockingReceive(self, handle, msg, timeout):
+    def blocking_receive(self, handle, msg, timeout):
         try:
             res = self.__m_dllBasic.CanalBlockingReceive(handle, msg, timeout)
             return res
         except:
-            logging.warning('Blocking Receive Failed')
+            log.warning('Blocking Receive Failed')
             raise
 
-    def CanalGetStatus(self, handle, CanalStatus):
+    def get_status(self, handle, CanalStatus):
         try:
             res = self.__m_dllBasic.CanalGetStatus(handle, CanalStatus)
             return res
         except:
-            logging.warning('Get status failed')
+            log.warning('Get status failed')
             raise
 
-    def CanalGetStatistics(self, handle, CanalStatistics):
+    def get_statistics(self, handle, CanalStatistics):
         try:
             res = self.__m_dllBasic.CanalGetStatistics(handle, CanalStatistics)
             return res
         except:
-            logging.warning('Get Statistics failed')
+            log.warning('Get Statistics failed')
             raise
 
-    def CanalGetVersion(self):
+    def get_version(self):
         try:
             res = self.__m_dllBasic.CanalGetVersion()
             return res
         except:
-            logging.warning('Failed to get version info')
+            log.warning('Failed to get version info')
             raise
 
-    def CanalGetDllVersion(self):
+    def get_library_version(self):
         try:
             res = self.__m_dllBasic.CanalGetDllVersion()
             return res
         except:
-            logging.warning('Failed to get DLL version')
+            log.warning('Failed to get DLL version')
             raise
 
-    def CanalGetVendorString(self):
+    def get_vendor_string(self):
         try:
             res = self.__m_dllBasic.CanalGetVendorString()
             return res
         except:
-            logging.warning('Failed to get vendor string')
+            log.warning('Failed to get vendor string')
             raise