Merge pull request #65 from pylessard/59-handle-listen-mode

#59 - Support Listen Mode where no Flow Control is sent.

Author: pylessard

doc/source/isotp/implementation.rst

@@ -211,6 +211,17 @@ The transport layer ``params`` parameter must be a dictionary with the following
    Refer to :ref:`Rate Limiter Section<rate_limiter_section>` for more details
 
 
+.. _param_listen_mode:
+
+.. attribute:: listen_mode
+   :annotation: (bool)
+
+   **default: False**
+
+   When Listen Mode is enabled, the :class:`TransportLayer<isotp.TransportLayer>` will correctly receive and transmit ISO-TP Frame, but will not send Flow Control
+   message when receiving a frame. This mode of operation is usefull to listen to a transmission between two third-party devices without interferring. 
+
+
 -----
 
 .. _rate_limiter_section:
@@ -232,7 +243,7 @@ It is important to understand that this product also defines the maximum burst s
 rate limiter is intended to fix (See `issue #61 <https://github.com/pylessard/python-can-isotp/issues/61>`_). Consider the case where a big payload of 10000 bytes must be transmitted, 
 after the transmission of the FirstFrame, the receiving party sends a FlowControl message with BlockSize=0 and STMin=0. In that situation, the whole payload can be sent immediately
 but writing 10000 bytes in a single burst might be too much for the CAN driver to handle and may overflow its internal buffer.  In
- this situation, it is useful to use the rate limiter to reduces the strain on the driver internal buffer.
+this situation, it is useful to use the rate limiter to reduces the strain on the driver internal buffer.
 
 In the above scenario, having a bitrate of 80000 bps and a window size of 0.1 sec would make the :class:`isotp.TransportLayer<isotp.TransportLayer>` output a burst of 8000 bits (1000 bytes) every 0.1 seconds.
 

isotp/protocol.py

@@ -300,7 +300,7 @@ class Params:
         __slots__ = (   'stmin', 'blocksize', 'squash_stmin_requirement', 'rx_flowcontrol_timeout', 
                         'rx_consecutive_frame_timeout', 'tx_padding', 'wftmax', 'tx_data_length', 'tx_data_min_length', 
                         'max_frame_size', 'can_fd', 'bitrate_switch', 'default_target_address_type',
-                        'rate_limit_max_bitrate', 'rate_limit_window_size', 'rate_limit_enable'
+                        'rate_limit_max_bitrate', 'rate_limit_window_size', 'rate_limit_enable', 'listen_mode'
                         )
 
         def __init__(self):
@@ -320,6 +320,7 @@ def __init__(self):
             self.rate_limit_max_bitrate         = 100000000
             self.rate_limit_window_size         = 0.2
             self.rate_limit_enable              = False
+            self.listen_mode                    = False
 
         def set(self, key, val, validate=True):
             param_alias = {
@@ -425,6 +426,8 @@ def validate(self):
             if self.rate_limit_max_bitrate * self.rate_limit_window_size < self.tx_data_length * 8:
                 raise ValueError('Rate limiter is so restrictive that a SingleFrame cannot be sent. Please, allow a higher bitrate or increase the window size. (tx_data_length = %d)' % self.tx_data_length)
 
+            if not isinstance(self.listen_mode, bool):
+                raise ValueError('listen_mode must be a boolean value')
 
     class Timer:
         def __init__(self, timeout):
@@ -695,7 +698,9 @@ def process_tx(self):
             self.pending_flow_control_tx = False
             if self.pending_flowcontrol_status == PDU.FlowStatus.ContinueToSend:
                 self.start_rx_cf_timer()    # We tell the sending party that it can continue to send data, so we start checking the timeout again
-            return self.make_flow_control(flow_status=self.pending_flowcontrol_status);	# No need to wait.
+
+            if not self.params.listen_mode: # Inhibit Flow Control in listen mode.
+                return self.make_flow_control(flow_status=self.pending_flowcontrol_status);	# No need to wait.
 
         # Handle flow control reception
         flow_control_frame = self.last_flow_control_frame	# Reads the last message received and clears it. (Dequeue message)

isotp/protocol.pyi

@@ -35,6 +35,7 @@ class TransportLayer:
         max_frame_size: int
         can_fd: bool
         bitrate_switch: bool
+        listen_mode: bool
         target_address_type: Optional[TargetAddressType]
         def __init__(self) -> None: ...
         def set(self,

test/test_transport_layer.py

@@ -120,6 +120,23 @@ def test_receive_multiframe_check_flowcontrol(self):
         self.assertEqual(data, bytearray(payload))
         self.assertIsNone(self.rx_isotp_frame())
 
+    def test_receive_multiframe_check_no_flowcontrol_listen_mode(self):
+        self.stack.params.set('stmin', 0x02)
+        self.stack.params.set('blocksize', 0x05)
+        self.stack.params.set('listen_mode', True)
+
+        payload_size = 10
+        payload = self.make_payload(payload_size)
+        self.simulate_rx(data = [0x10, payload_size] + payload[0:6])
+        self.stack.process()
+        self.assertIsNone(self.get_tx_can_msg())    # No Flow Control here. We are in listen mode
+        self.assertIsNone(self.rx_isotp_frame())
+        self.simulate_rx(data = [0x21] + payload[6:10])
+        self.stack.process()
+        data = self.rx_isotp_frame()
+        self.assertEqual(data, bytearray(payload))
+        self.assertIsNone(self.rx_isotp_frame())
+
     def test_receive_overflow_handling(self):
         self.stack.params.set('stmin', 0)
         self.stack.params.set('blocksize', 0)