syndesi 0.1.5__tar.gz → 0.2.0__tar.gz

{syndesi-0.1.5/syndesi.egg-info → syndesi-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: syndesi
-Version: 0.1.5
+Version: 0.2.0
 Summary: Syndesi
 Author: Sebastien Deriaz
 Author-email: sebastien.deriaz1@gmail.com
@@ -16,6 +16,8 @@ License-File: LICENSE
 
 # Syndesi Python Implementation
 
+Syndesi description is available [here](https://github.com/syndesi-project/Syndesi/README.md)
+
 ## Installation
 
 The syndesi Python package can be installed through pip
@@ -25,14 +27,16 @@ The syndesi Python package can be installed through pip
 The package can also be installed locally by cloning this repository
 
 ```bash
-git clone ...
+git clone https://github.com/syndesi-project/Syndesi
 cd Syndesi/Python
 pip install .
 ```
 
 ## Usage
 
-To instantiate a device / testbench, one must import the device and a suitable adapter 
+
+
+To instantiate a device, one must import the device and a suitable adapter
 
 ```python
 # 1) Import the device
@@ -46,16 +50,6 @@ mm = SDM3055(IP("192.168.1.123"))
 ## 4) Use
 voltage = mm.measure_dc_voltage()
 ```
-
-The Syndesi Python package provides the user with the necessary tools to control compatible devices
-
-- drivers : device-specific implementation
-- descriptors : Each class represents a particular way of connecting to a device, the user must provide que necessary information (IP, com port, ID, etc...)
-- communication wrapper (wrappers) : Wrappers for low-level communication (TCP, UDP, UART, etc...)
-  - IP (TCP / UDP)
-  - UART
-  - USB (?)
-
 ## Layers
 
 The first layer is the "Device" base class
@@ -88,6 +82,14 @@ The Syndesi Device Protocol is a light-weight and easy interface to send / recei
 
 ## Notes
 
-15.08.2023 : The adapters must work with bytearray data only
-
 06.09.2023 : bytearray is changed to bytes everywhere
+
+23.10.2023 : continuation timeout isn't suitable for TCP, but it can work for UDP as a UDP server can send multiple response packets after a single packet from the client. This can be handled in different ways by firewalls. Thankfull that's none of our business so continuation timeout can be implemented
+
+22.11.2023 : The timeout and stop conditions strategy is a bit complicated :
+
+- What if we receive the message b'ACK\nNCK\n' using a termination stop condition but we receive b'ACK', then a timeout, then b'\nNCK\n' ?
+  - Should the first part be kept ? should an error be raised at the timeout because nothing was read ?
+    - Two kinds of timeouts ?
+      - One where "we read as much as possible during the available time"
+      - One where "we expect a response within X otherwise it's trash" 

{syndesi-0.1.5 → syndesi-0.2.0}/README.md

@@ -1,5 +1,7 @@
 # Syndesi Python Implementation
 
+Syndesi description is available [here](https://github.com/syndesi-project/Syndesi/README.md)
+
 ## Installation
 
 The syndesi Python package can be installed through pip
@@ -9,14 +11,16 @@ The syndesi Python package can be installed through pip
 The package can also be installed locally by cloning this repository
 
 ```bash
-git clone ...
+git clone https://github.com/syndesi-project/Syndesi
 cd Syndesi/Python
 pip install .
 ```
 
 ## Usage
 
-To instantiate a device / testbench, one must import the device and a suitable adapter 
+
+
+To instantiate a device, one must import the device and a suitable adapter
 
 ```python
 # 1) Import the device
@@ -30,16 +34,6 @@ mm = SDM3055(IP("192.168.1.123"))
 ## 4) Use
 voltage = mm.measure_dc_voltage()
 ```
-
-The Syndesi Python package provides the user with the necessary tools to control compatible devices
-
-- drivers : device-specific implementation
-- descriptors : Each class represents a particular way of connecting to a device, the user must provide que necessary information (IP, com port, ID, etc...)
-- communication wrapper (wrappers) : Wrappers for low-level communication (TCP, UDP, UART, etc...)
-  - IP (TCP / UDP)
-  - UART
-  - USB (?)
-
 ## Layers
 
 The first layer is the "Device" base class
@@ -72,6 +66,14 @@ The Syndesi Device Protocol is a light-weight and easy interface to send / recei
 
 ## Notes
 
-15.08.2023 : The adapters must work with bytearray data only
-
 06.09.2023 : bytearray is changed to bytes everywhere
+
+23.10.2023 : continuation timeout isn't suitable for TCP, but it can work for UDP as a UDP server can send multiple response packets after a single packet from the client. This can be handled in different ways by firewalls. Thankfull that's none of our business so continuation timeout can be implemented
+
+22.11.2023 : The timeout and stop conditions strategy is a bit complicated :
+
+- What if we receive the message b'ACK\nNCK\n' using a termination stop condition but we receive b'ACK', then a timeout, then b'\nNCK\n' ?
+  - Should the first part be kept ? should an error be raised at the timeout because nothing was read ?
+    - Two kinds of timeouts ?
+      - One where "we read as much as possible during the available time"
+      - One where "we expect a response within X otherwise it's trash" 

{syndesi-0.1.5 → syndesi-0.2.0}/setup.py

@@ -1,6 +1,6 @@
 from setuptools import setup, find_packages
 
-VERSION = '0.1.5'
+VERSION = '0.2.0'
 DESCRIPTION = 'Syndesi'
 
 with open("README.md", "r", encoding="utf-8") as fh:
@@ -15,7 +15,11 @@ setup(
     description=DESCRIPTION,
     long_description_content_type="text/markdown",
     long_description=long_description,
-    scripts=['bin/syndesi'],
+    entry_points = {
+        'console_scripts': [
+            'syndesi=syndesi.shell.syndesi:main',
+            'syndesi-proxy=syndesi.proxy.proxy:main'],
+    },
     packages=find_packages(),
     install_requires=[''],
     keywords=['python', 'syndesi', 'interface', 'ethernet'],

syndesi-0.2.0/syndesi/adapters/__init__.py

@@ -0,0 +1,8 @@
+from .adapter import Adapter
+from .ip import IP
+from .serialport import SerialPort
+from .visa import VISA
+from .proxy import Proxy
+
+from .timeout import Timeout
+from .stop_conditions import Termination, Length, StopCondition

syndesi-0.2.0/syndesi/adapters/adapter.py

@@ -0,0 +1,321 @@
+# adapters.py
+# Sébastien Deriaz
+# 06.05.2023
+#
+# Adapters provide a common abstraction for the media layers (physical + data link + network)
+# The following classes are provided, which all are derived from the main Adapter class 
+#   - IP
+#   - Serial
+#   - VISA
+# 
+# Note that technically VISA is not part of the media layer, only USB is.
+# This is a limitation as it is to this day not possible to communicate "raw"
+# with a device through USB yet
+#
+# An adapter is meant to work with bytes objects but it can accept strings.
+# Strings will automatically be converted to bytes using utf-8 encoding
+#
+
+from abc import abstractmethod, ABC
+from .timed_queue import TimedQueue
+from threading import Thread
+from typing import Union
+from enum import Enum
+from .stop_conditions import StopCondition, Termination, Length
+from .timeout import Timeout, TimeoutException, timeout_fuse
+from typing import Union
+from ..tools.types import is_number
+from ..tools.log import LoggerAlias
+import logging
+from time import time
+from dataclasses import dataclass
+from ..tools.others import DEFAULT
+
+DEFAULT_TIMEOUT = Timeout(response=1, continuation=100e-3, total=None)
+DEFAULT_STOP_CONDITION = None
+
+
+class AdapterDisconnected(Exception):
+    pass
+
+STOP_DESIGNATORS = {
+    'timeout' : {
+        Timeout.TimeoutType.RESPONSE : 'TR',
+        Timeout.TimeoutType.CONTINUATION : 'TC',
+        Timeout.TimeoutType.TOTAL : 'TT'
+    },
+    'stop_condition' : {
+        Termination : 'ST',
+        Length : 'SL'
+    },
+    'previous-read-buffer' : 'RB'
+}
+
+class Origin(Enum):
+    TIMEOUT = 'timeout'
+    STOP_CONDITION = 'stop_condition'
+
+@dataclass
+class ReturnMetrics:
+    read_duration : float
+    origin : Origin
+    timeout_type : Timeout.TimeoutType
+    stop_condition : StopCondition
+    previous_read_buffer_used : bool
+    n_fragments : int
+    response_time : float
+    continuation_times : list
+    total_time : float
+
+class Adapter(ABC):
+    class Status(Enum):
+        DISCONNECTED = 0
+        CONNECTED = 1
+
+    def __init__(self, alias : str = '', stop_condition : Union[StopCondition, None] = DEFAULT, timeout : Union[float, Timeout] = DEFAULT) -> None:
+        """
+        Adapter instance
+
+        Parameters
+        ----------
+        alias : str
+            The alias is used to identify the class in the logs
+        timeout : float or Timeout instance
+            Default timeout is Timeout(response=1, continuation=0.1, total=None)
+        stop_condition : StopCondition or None
+            Default to None
+        """
+        super().__init__()
+        self._alias = alias
+
+        self._default_stop_condition = stop_condition == DEFAULT
+        if self._default_stop_condition:
+            self._stop_condition = DEFAULT_STOP_CONDITION
+        else:
+            self._stop_condition = stop_condition
+        self._read_queue = TimedQueue()
+        self._thread : Union[Thread, None] = None
+        self._status = self.Status.DISCONNECTED
+        self._logger = logging.getLogger(LoggerAlias.ADAPTER.value)
+
+        # Buffer for data that has been pulled from the queue but
+        # not used because of termination or length stop condition
+        self._previous_read_buffer = b''
+
+        self._default_timeout = timeout == DEFAULT
+        if self._default_timeout:
+            self._timeout = DEFAULT_TIMEOUT
+        else:
+            if is_number(timeout):
+                self._timeout = Timeout(response=timeout, continuation=100e-3)
+            elif isinstance(timeout, Timeout):
+                self._timeout = timeout
+            else:
+                raise ValueError(f"Invalid timeout type : {type(timeout)}")
+
+    def set_default_timeout(self, default_timeout : Union[Timeout, tuple, float]):
+        """
+        Set the default timeout for this adapter. If a previous timeout has been set, it will be fused
+
+        Parameters
+        ----------
+        default_timeout : Timeout or tuple or float
+        """
+        if self._default_timeout:
+            self._timeout = default_timeout
+        else:
+            self._timeout = timeout_fuse(self._timeout, default_timeout)
+
+    def set_default_stop_condition(self, stop_condition):
+        """
+        Set the default stop condition for this adapter.
+
+        Parameters
+        ----------
+        stop_condition : StopCondition
+        """
+        if self._default_stop_condition:
+            self._stop_condition = stop_condition
+
+    def flushRead(self):
+        """
+        Flush the input buffer
+        """
+        self._read_queue.clear()
+        self._previous_read_buffer = b''
+
+    @abstractmethod
+    def open(self):
+        """
+        Start communication with the device
+        """
+        pass
+
+    @abstractmethod
+    def close(self):
+        """
+        Stop communication with the device
+        """
+        pass
+
+    @abstractmethod
+    def write(self, data : Union[bytes, str]):
+        """
+        Send data to the device
+
+        Parameters
+        ----------
+        data : bytes or str
+        """
+        pass
+    
+    # TODO : Return None or b'' when read thread is killed while reading
+    # This is to detect if a server socket has been closed
+
+
+    def read(self, timeout=None, stop_condition=None, return_metrics : bool = False) -> bytes:
+        """
+        Read data from the device
+
+        Parameters
+        ----------
+        timeout : Timeout or None
+            Set a custom timeout, if None (default), the adapter timeout is used
+        stop_condition : StopCondition or None
+            Set a custom stop condition, if None (Default), the adapater stop condition is used
+        return_metrics : ReturnMetrics class
+        """
+        read_start = time()
+        if self._status == self.Status.DISCONNECTED:
+            self.open()
+
+        # Use adapter values if no custom value is specified
+        if timeout is None:
+            timeout = self._timeout
+        elif isinstance(timeout, float):
+            timeout = Timeout(timeout)
+        
+        
+        if stop_condition is None:
+            stop_condition = self._stop_condition
+
+        # If the adapter is closed, open it
+        if self._status == self.Status.DISCONNECTED:
+            self.open()
+
+        if self._thread is None or not self._thread.is_alive():
+            self._start_thread()
+
+        timeout_ms = timeout.initiate_read(len(self._previous_read_buffer) > 0)
+
+        if stop_condition is not None:
+            stop_condition.initiate_read()
+
+        deferred_buffer = b''
+
+        # Start with the deferred buffer
+        # TODO : Check if data could be lost here, like the data is put in the previous_read_buffer and is never
+        # read back again because there's no stop condition
+        if len(self._previous_read_buffer) > 0 and stop_condition is not None:
+            stop, output, self._previous_read_buffer = stop_condition.evaluate(self._previous_read_buffer)
+            previous_read_buffer_used = True
+        else:
+            stop = False
+            output = b''
+            previous_read_buffer_used = False
+        
+        n_fragments = 0
+        # If everything is used up, read the queue
+        if not stop:
+            while True:
+                (timestamp, fragment) = self._read_queue.get(timeout_ms)
+                n_fragments += 1
+
+                if fragment == b'':
+                    raise AdapterDisconnected()
+
+                # 1) Evaluate the timeout
+                stop, timeout_ms = timeout.evaluate(timestamp)
+                if stop:
+                    data_strategy, origin = timeout.dataStrategy()
+                    if data_strategy == Timeout.OnTimeoutStrategy.DISCARD:
+                        # Trash everything
+                        output = b''
+                    elif data_strategy == Timeout.OnTimeoutStrategy.RETURN:
+                        # Return the data that has been read up to this point
+                        output += deferred_buffer
+                        if fragment is not None:
+                            output += fragment
+                    elif data_strategy == Timeout.OnTimeoutStrategy.STORE:
+                        # Store the data
+                        self._previous_read_buffer = output
+                        output = b''
+                    elif data_strategy == Timeout.OnTimeoutStrategy.ERROR:
+                        raise TimeoutException(origin)
+                    break
+                else:
+                    origin = None
+                    
+                
+                
+                # Add the deferred buffer
+                if len(deferred_buffer) > 0:
+                    fragment = deferred_buffer + fragment
+
+                # 2) Evaluate the stop condition
+                if stop_condition is not None:
+                    stop, kept_fragment, deferred_buffer = stop_condition.evaluate(fragment)
+                    output += kept_fragment
+                    if stop:
+                        self._previous_read_buffer = deferred_buffer
+                else:
+                    output += fragment
+                if stop:
+                    break
+            
+            if origin is not None:
+                # The stop originates from the timeout
+                designator = STOP_DESIGNATORS['timeout'][origin]
+            else:
+                designator = STOP_DESIGNATORS['stop_condition'][type(stop_condition)]
+        else:
+            designator = STOP_DESIGNATORS['previous-read-buffer']
+        
+        read_duration = time() - read_start
+        if self._previous_read_buffer:
+            self._logger.debug(f'Read [{designator}, {read_duration*1e3:.3f}ms] : {output} , previous read buffer : {self._previous_read_buffer}')
+        else:
+            self._logger.debug(f'Read [{designator}, {read_duration*1e3:.3f}ms] : {output}')
+
+        if return_metrics:
+            return output, ReturnMetrics(
+                read_duration=read_duration,
+                origin=Origin.TIMEOUT if origin is not None else Origin.STOP_CONDITION,
+                timeout_type=origin if origin is not None else None,
+                stop_condition=type(stop_condition) if origin is None else None,
+                previous_read_buffer_used=previous_read_buffer_used,
+                n_fragments=n_fragments,
+                response_time=timeout.response_time,
+                continuation_times=timeout.continuation_times,
+                total_time=timeout.total_time
+            )
+        else:
+            return output
+
+    @abstractmethod
+    def _start_thread(self):
+        pass
+
+    def __del__(self):
+        self.close()
+
+    @abstractmethod
+    def query(self, data : Union[bytes, str], timeout=None, stop_condition=None, return_metrics : bool = False) -> bytes:
+        """
+        Shortcut function that combines
+        - flush_read
+        - write
+        - read
+        """
+        pass
+    

syndesi-0.2.0/syndesi/adapters/auto.py

@@ -0,0 +1,45 @@
+# auto.py
+# Sébastien Deriaz
+# 24.06.2024
+#
+# Automatic adapter function
+# This function is used to automatically choose an adapter based on the user's input
+# 192.168.1.1 -> IP
+# COM4 -> Serial
+# /dev/tty* -> Serial
+# etc...
+# If an adapter class is supplied, it is simply passed through
+#
+# Additionnaly, it is possible to do COM4:115200 so as to make the life of the user easier
+# Same with /dev/ttyACM0:115200
+
+from typing import Union
+import re
+from . import Adapter, IP, SerialPort
+
+IP_PATTERN = '([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)(:[0-9]+)*'
+
+WINDOWS_SERIAL_PATTERN = '(COM[0-9]+)(:[0-9]+)*'
+LINUX_SERIAL_PATTERN = '(/dev/tty[a-zA-Z0-9]+)(:[0-9]+)*'
+
+def auto_adapter(adapter_or_string : Union[Adapter, str]):
+    if isinstance(adapter_or_string, Adapter):
+        # Simply return it
+        return adapter_or_string
+    elif isinstance(adapter_or_string, str):
+        # Parse it
+        ip_match = re.match(IP_PATTERN, adapter_or_string)
+        if ip_match:
+            # Return an IP adapter
+            return IP(address=ip_match.groups(0), port=ip_match.groups(1))
+        elif re.match(WINDOWS_SERIAL_PATTERN, adapter_or_string):
+            port, baudrate = re.match(WINDOWS_SERIAL_PATTERN, adapter_or_string).groups()
+            return SerialPort(port=port, baudrate=int(baudrate))
+        elif re.match(LINUX_SERIAL_PATTERN, adapter_or_string):
+            port, baudrate = re.match(LINUX_SERIAL_PATTERN, adapter_or_string)
+            return SerialPort(port=port, baudrate=int(baudrate))
+        else:
+            raise ValueError(f"Couldn't parse adapter description : {adapter_or_string}")
+
+    else:
+        raise ValueError(f"Invalid adapter : {adapter_or_string}")

syndesi-0.2.0/syndesi/adapters/ip.py

@@ -0,0 +1,150 @@
+import socket
+from enum import Enum
+from .adapter import Adapter
+from ..tools.types import to_bytes
+from .timeout import Timeout
+from threading import Thread
+from .timed_queue import TimedQueue
+from typing import Union
+from time import time
+import argparse
+from ..tools import shell
+
+class IP(Adapter):
+    DEFAULT_RESPONSE_TIMEOUT = 1
+    DEFAULT_CONTINUATION_TIMEOUT = 1e-3
+    DEFAULT_TOTAL_TIMEOUT = 5
+
+
+    DEFAULT_TIMEOUT = Timeout(
+                        response=DEFAULT_RESPONSE_TIMEOUT,
+                        continuation=DEFAULT_CONTINUATION_TIMEOUT,
+                        total=DEFAULT_TOTAL_TIMEOUT)
+    DEFAULT_BUFFER_SIZE = 1024
+    class Protocol(Enum):
+        TCP = 'TCP'
+        UDP = 'UDP'
+
+    def __init__(self,
+                address : str,
+                port : int = None,
+                transport : str = 'TCP',
+                timeout : Union[Timeout, float] = DEFAULT_TIMEOUT,
+                stop_condition = None,
+                alias : str = '',
+                buffer_size : int = DEFAULT_BUFFER_SIZE,
+                _socket : socket.socket = None):
+        """
+        IP stack adapter
+
+        Parameters
+        ----------
+        address : str
+            IP description
+        port : int
+            IP port
+        transport : str
+            'TCP' or 'UDP'
+        timeout : Timeout | float
+            Specify communication timeout
+        stop_condition : StopCondition
+            Specify a read stop condition (None by default)
+        alias : str
+            Specify an alias for this adapter, '' by default
+        buffer_size : int
+            Socket buffer size, may be removed in the future
+        socket : socket.socket
+            Specify a custom socket, this is reserved for server application
+        """
+        super().__init__(alias=alias, timeout=timeout, stop_condition=stop_condition)
+        self._transport = self.Protocol(transport)
+        self._is_server = _socket is not None
+
+        self._logger.info(f"Setting up {self._transport.value} IP adapter ({'server' if self._is_server else 'client'})")
+
+        if self._is_server:
+            # Server
+            self._socket = _socket
+            self._status = self.Status.CONNECTED
+        elif self._transport == self.Protocol.TCP:
+            self._socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        elif self._transport == self.Protocol.UDP:
+            self._socket = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+        
+        self._address = address
+        self._port = port
+        self._buffer_size = buffer_size
+
+    def set_default_port(self, port):
+        """
+        Sets IP port if no port has been set yet.
+
+        This way, the user can leave the port empty
+        and the driver/protocol can specify it later
+        
+        Parameters
+        ----------
+        port : int
+        """
+        if self._port is None:
+            self._port = port
+
+    def open(self):
+        if self._is_server:
+            raise SystemError("Cannot open server socket. It must be passed already opened")
+        if self._port is None:
+            raise ValueError(f"Cannot open adapter without specifying a port")
+
+        self._logger.debug(f"Adapter {self._alias} connect to ({self._address}, {self._port})")
+        self._socket.connect((self._address, self._port))
+        self._status = self.Status.CONNECTED
+        self._logger.info(f"Adapter {self._alias} opened !")
+
+    def close(self):
+        if hasattr(self, '_socket'):
+            self._socket.close()
+        self._logger.info("Adapter closed !")
+        self._status = self.Status.DISCONNECTED
+            
+    def write(self, data : Union[bytes, str]):
+        data = to_bytes(data)
+        if self._status == self.Status.DISCONNECTED:
+            self._logger.info(f"Adapter {self._alias} is closed, opening...")
+            self.open()
+        write_start = time()
+        self._socket.send(data)
+        write_duration = time() - write_start
+        self._logger.debug(f"Written [{write_duration*1e3:.3f}ms]: {repr(data)}")
+
+    def _start_thread(self):
+        self._logger.debug("Starting read thread...")
+        self._thread = Thread(target=self._read_thread, daemon=True, args=(self._socket, self._read_queue))
+        self._thread.start()
+
+    # EXPERIMENTAL
+    def read_thread_alive(self):
+        return self._thread.is_alive()
+
+
+    def _read_thread(self, socket : socket.socket, read_queue : TimedQueue):
+        while True: # TODO : Add stop_pipe ? Maybe it was removed ?
+            try:
+                payload = socket.recv(self._buffer_size)
+                if len(payload) == self._buffer_size and self._transport == self.Protocol.UDP:
+                    self._logger.warning("Warning, inbound UDP data may have been lost (max buffer size attained)")
+            except OSError:
+                break
+            # If payload is empty, it means the socket has been disconnected
+            if payload == b'':
+                read_queue.put(payload)
+                break
+            read_queue.put(payload)
+
+    def query(self, data : Union[bytes, str], timeout=None, stop_condition=None, return_metrics : bool = False):
+        if self._is_server:
+            raise SystemError("Cannot query on server adapters")
+        self.flushRead()
+        self.write(data)
+        return self.read(timeout=timeout, stop_condition=stop_condition, return_metrics=return_metrics)
+    
+