Add license, copyright notices and docs

Author: projectgus

LICENSE

@@ -0,0 +1,11 @@
+Copyright (c) 2021 Angus Gratton
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,18 +1,21 @@
 # Canalyst-II Driver for Python
 
-Unofficial Python userspace driver for the low cost USB analyzer "Canalyst-II".
+Unofficial Python userspace driver for the low cost USB analyzer "Canalyst-II" by Chuangxin Technology (创芯科技).
 
-Uses [pyusb](https://pyusb.github.io/pyusb/) library for USB support, should work on Windows, MacOS and Linux.
+Uses [pyusb](https://pyusb.github.io/pyusb/) library for USB support on Windows, MacOS and Linux.
 
-This driver is based on black box reverse engineering and the original python-can canalystii source. It's mostly intended for use with python-can, but can also be used standalone.
+This driver is based on black box reverse engineering of the USB behaviour of the proprietary software, and reading the basic data structure layouts in the original python-can canalystii source.
 
-## Usage
+Intended for use as a backend driver for [python-can](https://python-can.readthedocs.io/). However it can also be used standalone.
+
+## Standalone Usage
 
 ```py
 import canalystii
 
 # Connect to the Canalyst-II device
-dev = canalystii.CanalystDevice(bitrate=500*1000)
+# Passing a bitrate to the constructor causes both channels to be initialized and started.
+dev = canalystii.CanalystDevice(bitrate=500000)
 
 # Receive all pending messages on channel 0
 for msg in dev.receive(0):
@@ -26,16 +29,31 @@ new_message = canalystii.Message(can_id=0x300,
                                  data=(0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08))
 # Send one copy to channel 1
 dev.send(1, new_message)
-# Send 3 copies to channel 0 (argument can be any iterable, or single instance of canalystii.Message)
+# Send 3 copies to channel 0 (argument can be an instance of canalystii.Message or a list of instances)
 dev.send(0, [new_message] * 3)
+
+# Stop both channels (need to call start() again to resume capturing or send any messages)
+dev.stop(0)
+dev.stop(1)
 ```
 
+## Limitations
+
+Currently, the following things are either not possible or not easy to support based on the known Canalyst-II protocol:
+
+* CAN bus error conditions. There is a function `get_can_status()` that seems to provide access to some internal device state, not clear if this can be used to determine when errors occured or invalid messages seen.
+* Receive buffer hardware overflow detection (see Performance, below).
+* ACK status of sent CAN messages.
+* Failure status of sent CAN messages. If the device fails to get bus arbitration after some unknown amount of time, it will drop the message silently.
+* Hardware filtering of incoming messages. Currently all filtering is done in software. There is a `filter` field of `InitCommand` structure, not clear how it works.
+* Configuring whether messages are ACKed by Canalyst-II. This may be possible, see `InitCommand` `acc_code` and `acc_mask`.
+
 ## Performance
 
-Because the Canalyst-II USB protocol requires polling, there is a trade-off between CPU usage and both latency and maximum receive throughput. The host needs to constantly poll the device to request any new CAN messages.
+Because the Canalyst-II USB protocol requires polling, the host needs to constantly poll the device to request any new CAN messages. There is a trade-off of CPU usage against both latency and maximum receive throughput.
 
-The hardware seems able to buffer 1000-2000 messages (possibly a little more) per channel. The maximum number seems to depend on relative timing of the messages. Therefore, a 1Mbps (maximum speed) CAN channel receiving the maximum possible ~7800 messages/second should call `receive()` at least every 100ms in order to avoid lost messages. The USB protocol doesn't provide any way to tell if any messages in the hardware buffer were lost.
+The hardware seems able to buffer 1000-2000 messages (possibly a little more) per channel. The maximum number seems to depend on relative timing of the messages. Therefore, if a 1Mbps (maximum speed) CAN channel is receiving the maximum possible ~7800 messages/second then software should call `receive()` at least every 100ms in order to avoid lost messages. It's not possible to tell if any messages in the hardware buffer were lost due to overflow.
 
-Testing Linux CPython 3.9 on an older i7-6500U CPU, calling `receive()` in a tight loop while receiving maximum message rate (~7800 messages/sec) on both channels (~15600 messages/sec total)  uses approximately 40% of a single CPU. Adding a 50ms delay `time.sleep(0.05)` in the loop drops CPU usage to around 10% without losing any messages. Longer sleep periods in the loop reduce CPU usage further but some messages are dropped. See the `tests/can_spammer_test.py` file for the test code.
+Testing Linux CPython 3.9 on a i7-6500U CPU (~2016 vintage), calling `receive()` in a tight loop while receiving maximum message rate (~7800 messages/sec) on both channels (~15600 messages/sec total)  uses approximately 40% of a single CPU. Adding a 50ms delay `time.sleep(0.05)` in the loop drops CPU usage to around 10% without losing any messages. Longer sleep periods in the loop reduce CPU usage further but some messages are dropped. See the `tests/can_spammer_test.py` file for the test code.
 
 In systems where the CAN message rate is lower than the maximum, `receive()` can be called less frequently without losing messages. In systems where the Python process may be pre-empted, it's possible for messages to be lost anyhow.

canalystii/__init__.py

@@ -1,2 +1,8 @@
+# Copyright (c) 2021 Angus Gratton
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# This module contains the public package-level interface to Canalyst-II device.
+
 from .protocol import Message  # noqa: F401
 from .device import CanalystDevice  # noqa: F401

canalystii/device.py

@@ -1,3 +1,8 @@
+# Copyright (c) 2021 Angus Gratton
+#
+# SPDX-License-Identifier: Apache-2.0
+#
+# This module contains device-level interface to Canalyst-II
 import ctypes
 import logging
 import usb.core
@@ -13,6 +18,24 @@
 
 
 class CanalystDevice(object):
+    """Encapsulates a low-level USB interface to a Canalyst-II device.
+
+    Constructing an instance of this class will cause pyusb to acquire the
+    relevant USB interface, and retain it until the object is garbage collected.
+
+    :param:device:_index if more than one Canalyst-II device is connected, this is
+        the index to use in the list.
+    :param:usb_device: Optional argument to ignore device_index and provide an instance
+        of a pyusb device object directly.
+    :param:bitrate: If set, both channels are initialized to the specified bitrate and
+        started automatically. If unset (default) then the "init" method must be called
+        before using either channel.
+    :param:timing0: Optional parameter to provide BTR timing directly. Either both or
+        neither timing0 and timing1 must be set, and setting these arguments is mutually
+        exclusive with setting bitrate. If set, both channels are initialized and started
+        automatically.
+    """
+
     # Small optimization, build common command packet one time
     COMMAND_MESSAGE_STATUS = protocol.SimpleCommand(protocol.COMMAND_MESSAGE_STATUS)
 
@@ -21,6 +44,7 @@ class CanalystDevice(object):
     def __init__(
         self, device_index=0, usb_device=None, bitrate=None, timing0=None, timing1=None
     ):
+        """Constructor function."""
         if usb_device is not None:
             self._dev = usb_device
         else:
@@ -80,16 +104,28 @@ def __del__(self):
     def clear_rx_buffer(self, channel):
         """Clears the device's receive buffer for the specified channel.
 
-        Note that this doesn't seem to 100% work, it's possible to get a small number of messages even
+        Note that this doesn't seem to 100% work in the device firmware, on a busy bus
+        it's possible to receive a small number of "old" messages even after calling this.
+
+        :param:channel: Channel (0 or 1) to clear the RX buffer on.
         """
         self.send_command(
             channel, protocol.SimpleCommand(protocol.COMMAND_CLEAR_RX_BUFFER)
         )
 
     def flush_tx_buffer(self, channel, timeout=0):
-        """Return only after all messages have been sent to this channel or timeout is reached.
-
-        Returns True if flush is successful, False if timeout was reached. Pass 0 timeout to poll once only.
+        """Check if all pending messages have left the hardware TX buffer and optionally keep polling until
+        this happens or a timeout is reached.
+
+        Note that due to hardware limitations, "no messages in TX buffer" doesn't necessarily mean
+        that the messages were sent successfully - for the default send type 0 (see Message.send_type), the
+        hardware will attempt bus arbitration multiple times but if it fails then it will still "send" the
+        message. It also doesn't consider the ACK status of the message.
+
+        :param:channel: Channel (0 or 1) to flush the TX buffer on.
+        :param:timeout: Optional number of seconds to continue polling for empty TX buffer. If 0 (default),
+            this function will immediately return the current status of the send buffer.
+        :return: True if flush is successful (no pending messages to send), False if flushing timed out.
         """
         deadline = None
         while deadline is None or time.time() < deadline:
@@ -106,6 +142,15 @@ def flush_tx_buffer(self, channel, timeout=0):
         return False  # timeout!
 
     def send_command(self, channel, command_packet, response_class=None):
+        """Low-level function to send a command packet to the channel and optionally wait for a response.
+
+        :param:channel: Channel (0 or 1) to flush the TX buffer on.
+        :param:command_packet: Data to send to the channel. Usually this will be a ctypes Structure, but can be
+           anything that supports a bytes buffer interface.
+        :param:response_class: If None (default) then this function doesn't expect to read anything back from the
+           device. If not None, should be a ctypes class - 64 bytes will be read into a buffer and returned as an
+           object of this type.
+        """
         ep = CHANNEL_TO_COMMAND_EP[channel]
         self._dev.write(ep, memoryview(command_packet).cast("B"))
         if response_class:
@@ -118,9 +163,18 @@ def send_command(self, channel, command_packet, response_class=None):
 
     def init(self, channel, bitrate=None, timing0=None, timing1=None, start=True):
         """Initialize channel to a particular baud rate. This can be called more than once to change
-        the baud rate of an active channel.
-
-        By default, the channel is started after being initialized (set start parameter to False to not do this.)
+        the channel bit rate.
+
+        :param:channel: Channel (0 or 1) to initialize.
+        :param:bitrate: Bitrate to set for the channel. Either this argument of both
+             timing0 and timing1 must be set.
+        :param:timing0: Raw BTR0 timing value to determine the bitrate. If this argument is set,
+             timing1 must also be set and bitrate argument must be unset.
+        :param:timing1: Raw BTR1 timing value to determine the bitrate. If this argument is set,
+             timing0 must also be set and bitrate argument must be unset.
+        :param:start: If True (default) then the channel is started after being initialized.
+             If set to False, the channel will not be started until the start function is called
+             manually.
         """
         if bitrate is None and timing0 is None and timing1 is None:
             raise ValueError(
@@ -143,7 +197,7 @@ def init(self, channel, bitrate=None, timing0=None, timing1=None, start=True):
 
         init_packet = protocol.InitCommand(
             command=protocol.COMMAND_INIT,
-            acc_code=0x0,
+            acc_code=0x1,
             acc_mask=0xFFFFFFFF,
             filter=0x1,  # placeholder
             timing0=timing0,
@@ -156,20 +210,32 @@ def init(self, channel, bitrate=None, timing0=None, timing1=None, start=True):
         self.start(channel)
 
     def stop(self, channel):
-        """Stop this channel. Data won't be sent or received on this channel until it is started again."""
+        """Stop this channel. CAN messages won't be sent or received on this channel until it is started again.
+
+        :param:channel: Channel (0 or 1) to stop. The channel must already be initialized.
+        """
         if not self._initialized[channel]:
             raise RuntimeError(f"Channel {channel} is not initialized.")
         self.send_command(channel, protocol.SimpleCommand(protocol.COMMAND_STOP))
         self._started[channel] = False
 
     def start(self, channel):
-        """Start this channel."""
+        """Start this channel. This allows CAN messages to be sent and received. The hardware
+           will buffer received messages until the receive() function is called.
+
+        :param:channel: Channel (0 or 1) to start. The channel must already be initialized.
+        """
         if not self._initialized[channel]:
             raise RuntimeError(f"Channel {channel} is not initialized.")
         self.send_command(channel, protocol.SimpleCommand(protocol.COMMAND_START))
         self._started[channel] = True
 
     def receive(self, channel):
+        """Poll the hardware for received CAN messages and return them all as a list.
+
+        :param:channel: Channel (0 or 1) to poll. The channel must be started.
+        :return: List of Message objects representing received CAN messages, in order.
+        """
         if not self._initialized[channel]:
             raise RuntimeError(f"Channel {channel} is not initialized.")
         if not self._started[channel]:
@@ -178,6 +244,8 @@ def receive(self, channel):
             channel, self.COMMAND_MESSAGE_STATUS, protocol.MessageStatusResponse
         )
 
+        print(status.unknown)
+
         if status.rx_pending == 0:
             return []
 
@@ -208,6 +276,20 @@ def receive(self, channel):
         return result
 
     def send(self, channel, messages, flush_timeout=None):
+        """Send one or more CAN messages to the channel.
+
+        :param:channel: Channel (0 or 1) to send to. The channel must be started.
+        :param:messages: Either a single Message object, or a list of
+              Message objects to send.
+        :param:flush_timeout: If set, don't return until TX buffer is flushed or timeout is
+              reached.
+              Setting this parameter causes the software to poll the device continuously
+              for the buffer state. If None (default) then the function returns immediately,
+              when some CAN messages may still be waiting to sent due to CAN bus arbitration.
+              See flush_tx_buffer() function for details.
+        :return: None if flush_timeout is None (default). Otherwise True if all messages sent
+             (or failed), False if timeout reached.
+        """
         if not self._initialized[channel]:
             raise RuntimeError(f"Channel {channel} is not initialized.")
         if not self._started[channel]:
@@ -228,9 +310,14 @@ def send(self, channel, messages, flush_timeout=None):
             return self.flush_tx_buffer(channel, flush_timeout)
 
     def get_can_status(self, channel):
-        """Return some internal CAN-related values. The actual meaning of these is currently unknown."""
+        """Return some internal CAN-related values. The actual meaning of these is currently unknown.
+
+        :return: Instance of the CANStatusResponse structure. Note the field names may not be accurate.
+        """
         if not self._initialized[channel]:
-            logger.warning(f"Channel {channel} is not initialized, CAN status may be invalid.")
+            logger.warning(
+                f"Channel {channel} is not initialized, CAN status may be invalid."
+            )
         return self.send_command(
             channel,
             protocol.SimpleCommand(protocol.COMMAND_CAN_STATUS),

canalystii/protocol.py

@@ -1,4 +1,9 @@
+# Copyright (c) 2021 Angus Gratton
+#
+# SPDX-License-Identifier: Apache-2.0
+#
 # This module containts all of the on-the-wire USB protocol format for the Canalyst-II
+
 from ctypes import (
     c_bool,
     c_byte,
@@ -86,17 +91,20 @@ class InitCommand(LittleEndianStructure):
     _pack_ = 1
     _fields_ = [
         ("command", c_uint32),  # COMMAND_INIT
-        ("acc_code", c_uint32),  # Unknown (ACKs?), set to 0x0 for now
-        ("acc_mask", c_uint32),  # Unknown (ACKs?), set to 0x0 for now
+        ("acc_code", c_uint32),  # Unknown (ACK behvaiour?), set to 0x1 by CANPro(?)
+        ("acc_mask", c_uint32),  # Similar, set to 0xFFFFFFFF by CANPro
         ("unknown0", c_uint32),  # 0x0 always? maybe related to filter?
         (
             "filter",
-            c_uint32,  # Set to 0x1 for "SingleFilter", 0x0 for "DualFilter" - function unknown
-        ),
+            c_uint32,
+        ),  # CANPro sets to 0x1 for "SingleFilter", 0x0 for "DualFilter" - meaning unknown
         ("unknown1", c_uint32),  # 0x0 always? maybe related to filter?
         ("timing0", c_uint32),  # BTR0
         ("timing1", c_uint32),  # BTR1
-        ("mode", c_uint32),  # Unknown, set to 0x0 for now
+        (
+            "mode",
+            c_uint32,
+        ),  # Unknown, set to 0x0 for now. Setting 0x1 seems to cause device to crash(?)
         ("unknown2", c_uint32),  # Always 0x1 - function unknown
         ("padding", c_uint32 * (0x10 - 0x0A)),
     ]
@@ -112,7 +120,10 @@ class MessageStatusResponse(LittleEndianStructure):
     _fields_ = [
         ("command", c_uint32),
         ("rx_pending", c_uint32),
-        ("tx_pending", c_uint32),
+        ("tx_pending", c_uint16),
+        # at one point this value was set to 0x1 which might have been an error condition (failed to send),
+        # but might also have been a firmware bug (!). Have been unable to reproduce.
+        ("unknown", c_uint16),
         ("padding", c_uint32 * (0x10 - 0x03)),
     ]