cgse-common 0.14.1__py3-none-any.whl → 0.15.1__py3-none-any.whl

{cgse_common-0.14.1.dist-info → cgse_common-0.15.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgse-common
-Version: 0.14.1
+Version: 0.15.1
 Summary: Software framework to support hardware testing
 Author: IvS KU Leuven
 Maintainer-email: Rik Huygen <rik.huygen@kuleuven.be>, Sara Regibo <sara.regibo@kuleuven.be>

{cgse_common-0.14.1.dist-info → cgse_common-0.15.1.dist-info}/RECORD

@@ -6,7 +6,7 @@ egse/calibration.py,sha256=a5JDaXTC6fMwQ1M-qrwNO31Ass-yYSXxDQUK_PPsZg4,8818
 egse/config.py,sha256=qNW3uvwuEV9VSjiaoQfM_svBYfz4Kwxd1-jv1eTGqyw,9530
 egse/counter.py,sha256=7UwBeTAu213xdNdGAOYpUWNQ4jD4yVM1bOG10Ax4UFs,5097
 egse/decorators.py,sha256=B-zRa1WdLO71zqS5M27JBglcThYPho7seYfa4HOGj5c,27171
-egse/device.py,sha256=-FVwbf95kp_BTYs_Evl6kRs5Jb-oMUfaX3z3atkoT7I,10973
+egse/device.py,sha256=nn2HkN1KIHAmo37WZcqig-p2mQz1LgqpIfj1wPrUTLc,13240
 egse/dicts.py,sha256=dUAq7PTPvs73OrZb2Fh3loxvYv4ifUiK6bBcgrFU77Y,3972
 egse/env.py,sha256=0YFBGrA4xnk7MgGdHYSFEpiUj6EjLJ54S3-MqtXUm5Y,28367
 egse/exceptions.py,sha256=QB3MZRJizecWOj1cPbvG0UcIqFn7NRJ6rw1xtdNSFxw,1225
@@ -25,21 +25,21 @@ egse/ratelimit.py,sha256=JdJxD6UIi9LYngKEsG9zh8bTE9r_56D4EZCnp_fkrI0,9161
 egse/reload.py,sha256=PzOE0m1tmcNcQPVFH8orMe_cMoQIIiH9Gw2anpQTC40,4717
 egse/resource.py,sha256=kzNI6kJOE6Jd5QKJs2MkVAycUpwpOTLi1qydh3NSRng,15345
 egse/response.py,sha256=F04uqOYv1ClpHgDLYZlKTuOCSldHs5TezI_4x6zf2Fw,2717
-egse/scpi.py,sha256=DBTvB_p7yaGVW1aNJ6yhxGhWCuSe2uFzMCjFOy3XmZM,13375
+egse/scpi.py,sha256=WJ73EaLgRUV6ah1V41l0L7AXI-Dc6Jct7hPHlbbCIcg,15461
 egse/settings.py,sha256=YrRsMUn_IpOVnhTqUGREQUjMw8-AQ6aUBulQiij9MwY,15486
 egse/settings.yaml,sha256=mz9O2QqmiptezsMvxJRLhnC1ROwIHENX0nbnhMaXUpE,190
 egse/setup.py,sha256=1k-5CjzY3_tZ6XCitNOIyZEWyAUC8LqGcnmdKS68vYw,33945
 egse/signal.py,sha256=zW_36xm-RpzwuCu6x30dTvjkfnuyRebKKpl69Yk1QSc,7990
 egse/socketdevice.py,sha256=R8XwYHTH3lFhFngfsGbi_L7bTnTLHxMTEKIF7gmm5rc,7465
 egse/state.py,sha256=HdU2MFOlYRbawYRZmizV6Y8MgnZrUF0bx4fXaYU-M_s,3023
-egse/system.py,sha256=PfE0-Y6-ZEtMIVjt7R7qEXQXGts9m7yDKA3AA9H18Xw,72867
+egse/system.py,sha256=SiWJNet9eI1ut5htX6A0M93WstzeJjAMfLZ-7IQfg6Q,74781
 egse/task.py,sha256=ODSLE05f31CgWsSVcVFFq1WYUZrJMb1LioPTx6VM824,2804
 egse/version.py,sha256=e9GvelUZ9mfCDlRju4MWEJeMHJW9kUzK6SKzJpyj91s,6156
 egse/zmq_ser.py,sha256=d2lETLkLUll_F1Phc1pI7MEeA41uX7YZ8lhSFmBQZVw,3022
 egse/plugins/metrics/duckdb.py,sha256=E2eeNo3I7ajRuByodaYiPNvC0Zwyc7hsIlhr1W_eXdo,16148
 egse/plugins/metrics/influxdb.py,sha256=ecxjA_csYwf8RW3sXjiQxZHREfyrfStH1HA_rAs1AA8,6690
 egse/plugins/metrics/timescaledb.py,sha256=Ug0NWDV1Ky2VeFY6tDZL9xg6AFgnAEh2F_llVPnlRBA,21191
-cgse_common-0.14.1.dist-info/METADATA,sha256=7mu_CKI3uRvkTZwkFDFFbM6Bsdo8jWz641lcdQ7x_5g,3032
-cgse_common-0.14.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cgse_common-0.14.1.dist-info/entry_points.txt,sha256=erQovXd1bGzsngB0_sfY7IYRNwHIhwq3K8fmQvGS12o,198
-cgse_common-0.14.1.dist-info/RECORD,,
+cgse_common-0.15.1.dist-info/METADATA,sha256=IwIBVVopd15h4-PcEBumskB92pxsPSwdNZY7j0KX1_k,3032
+cgse_common-0.15.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cgse_common-0.15.1.dist-info/entry_points.txt,sha256=erQovXd1bGzsngB0_sfY7IYRNwHIhwq3K8fmQvGS12o,198
+cgse_common-0.15.1.dist-info/RECORD,,

egse/device.py

@@ -236,6 +236,9 @@ class DeviceTransport:
 
         raise NotImplementedError
 
+    def read_string(self, encoding="utf-8") -> str:
+        return self.read().decode(encoding).strip()
+
     def trans(self, command: str) -> bytes:
         """
         Send a single command to the device controller and block until a response from the
@@ -330,6 +333,76 @@ class AsyncDeviceTransport:
         return await self.trans(command)
 
 
+class AsyncDeviceConnectionInterface(DeviceConnectionObservable):
+    """Generic connection interface for all Device classes and Controllers.
+
+    This interface shall be implemented in the Controllers that directly connect to the
+    hardware, but also in the simulators to guarantee an identical interface as the controllers.
+
+    This interface will be implemented in the Proxy classes through the
+    YAML definitions. Therefore, the YAML files shall define at least
+    the following commands: `connect`, `disconnect`, `reconnect`, `is_connected`.
+    """
+
+    def __init__(self):
+        super().__init__()
+
+    def __enter__(self):
+        self.connect()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.disconnect()
+
+    async def connect(self) -> None:
+        """Connect to the device controller.
+
+        Raises:
+            ConnectionError: when the connection can not be opened.
+        """
+
+        raise NotImplementedError
+
+    async def disconnect(self) -> None:
+        """Disconnect from the device controller.
+
+        Raises:
+            ConnectionError: when the connection can not be closed.
+        """
+        raise NotImplementedError
+
+    async def reconnect(self):
+        """Reconnect the device controller.
+
+        Raises:
+            ConnectionError: when the device can not  be reconnected for some reason.
+        """
+        raise NotImplementedError
+
+    async def is_connected(self) -> bool:
+        """Check if the device is connected.
+
+        Returns:
+            True if the device is connected and responds to a command, False otherwise.
+        """
+        raise NotImplementedError
+
+
+class AsyncDeviceInterface(AsyncDeviceConnectionInterface):
+    """Generic interface for all device classes."""
+
+    def is_simulator(self) -> bool:
+        """Checks whether the device is a simulator rather than a real hardware controller.
+
+        This can be useful for testing purposes or when doing actual movement simulations.
+
+        Returns:
+            True if the Device is a Simulator; False if the Device is connected to real hardware.
+        """
+
+        raise NotImplementedError
+
+
 class DeviceFactoryInterface:
     """
     Base class for creating a device factory class to access devices.

egse/scpi.py

@@ -4,13 +4,13 @@ from typing import Any
 from typing import Dict
 from typing import Optional
 
+from egse.device import AsyncDeviceInterface
 from egse.device import AsyncDeviceTransport
 from egse.device import DeviceConnectionError
 from egse.device import DeviceError
 from egse.device import DeviceTimeoutError
 from egse.log import logger
 
-# Constants that can be overridden by specific device implementations
 DEFAULT_READ_TIMEOUT = 1.0  # seconds
 DEFAULT_CONNECT_TIMEOUT = 3.0  # seconds
 IDENTIFICATION_QUERY = "*IDN?"
@@ -32,7 +32,7 @@ class SCPICommand:
         raise NotImplementedError("Subclasses must implement get_cmd_string().")
 
 
-class AsyncSCPIInterface(AsyncDeviceTransport):
+class AsyncSCPIInterface(AsyncDeviceInterface, AsyncDeviceTransport):
     """Generic asynchronous interface for devices that use SCPI commands over Ethernet."""
 
     def __init__(
@@ -56,6 +56,7 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
             read_timeout: Timeout for read operations in seconds
             id_validation: String that should appear in the device's identification response
         """
+        super().__init__()
         self.device_name = device_name
         self.hostname = hostname
         self.port = port
@@ -73,6 +74,53 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
         """Prevents multiple coroutines from attempting to read, write or query from the same stream
         at the same time."""
 
+    def is_simulator(self) -> bool:
+        return False
+
+    async def initialize(self, commands: list[tuple[str, bool]] = None, reset_device: bool = False):
+        """Initialize the device with optional reset and command sequence.
+
+        Performs device initialization by optionally resetting the device and then
+        executing a sequence of commands. Each command can optionally expect a
+        response that will be logged for debugging purposes.
+
+        Args:
+            commands: List of tuples containing (command_string, expects_response).
+                Each tuple specifies a command to send and whether to wait for and
+                log the response. Defaults to None (no commands executed).
+            reset_device: Whether to send a reset command (*RST) before executing
+                the command sequence. Defaults to False.
+
+        Returns:
+            None
+
+        Raises:
+            Any exceptions raised by the underlying write() or trans() methods,
+            typically communication errors or device timeouts.
+
+        Example:
+            >>> await device.initialize([
+            ...     ("*IDN?", True),           # Query device ID, expect response
+            ...     ("SYST:ERR?", True),       # Check for errors, expect response
+            ...     ("OUTP ON", False)         # Enable output, no response expected
+            ... ], reset_device=True)
+        """
+
+        commands = commands or []
+
+        if reset_device:
+            logger.info(f"Resetting the {self.device_name}...")
+            await self.write("*RST")  # this also resets the user-defined buffer
+
+        for cmd, expects_response in commands:
+            if expects_response:
+                logger.debug(f"Sending {cmd}...")
+                response = (await self.trans(cmd)).decode().strip()
+                logger.debug(f"{response = }")
+            else:
+                logger.debug(f"Sending {cmd}...")
+                await self.write(cmd)
+
     async def connect(self) -> None:
         """Connect to the device asynchronously.
 
@@ -146,11 +194,9 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
 
     async def reconnect(self) -> None:
         """Reconnect to the device asynchronously."""
-        async with self._connect_lock:
-            if self._is_connection_open:
-                await self.disconnect()
-                await asyncio.sleep(0.1)
-            await self.connect()
+        await self.disconnect()
+        await asyncio.sleep(0.1)
+        await self.connect()
 
     async def is_connected(self) -> bool:
         """Check if the device is connected and responds correctly to identification.
@@ -177,8 +223,7 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
             return True
 
         except DeviceError as exc:
-            logger.exception(exc)
-            logger.error(f"{self.device_name}: Connection test failed")
+            logger.error(f"{self.device_name}: Connection test failed: {exc}", exc_info=True)
             await self.disconnect()
             return False
 
@@ -201,6 +246,7 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
                 if not command.endswith("\n"):
                     command += "\n"
 
+                logger.info(f"-----> {command}")
                 self._writer.write(command.encode())
                 await self._writer.drain()
 
@@ -233,6 +279,7 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
                     response = await asyncio.wait_for(
                         self._reader.readuntil(separator=b"\n"), timeout=self.read_timeout
                     )
+                    logger.info(f"<----- {response}")
                     return response
 
                 except asyncio.IncompleteReadError as exc:
@@ -279,6 +326,7 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
                 if not command.endswith("\n"):
                     command += "\n"
 
+                logger.info(f"-----> {command}")
                 self._writer.write(command.encode())
                 await self._writer.drain()
 
@@ -290,6 +338,7 @@ class AsyncSCPIInterface(AsyncDeviceTransport):
                     response = await asyncio.wait_for(
                         self._reader.readuntil(separator=b"\n"), timeout=self.read_timeout
                     )
+                    logger.info(f"<----- {response}")
                     return response
 
                 except asyncio.IncompleteReadError as exc:

egse/system.py

@@ -29,6 +29,7 @@ import operator
 import os
 import platform  # For getting the operating system name
 import re
+import shutil
 import socket
 import subprocess  # For executing a shell command
 import sys
@@ -2256,6 +2257,56 @@ def snake_to_title(snake_str: str) -> str:
     return snake_str.replace("_", " ").title()
 
 
+def caffeinate(pid: int = None):
+    """Prevent your macOS system from entering idle sleep while a process is running.
+
+    This function uses the macOS 'caffeinate' utility to prevent the system from
+    going to sleep due to inactivity. It's particularly useful for long-running
+    background processes that may lose network connections or be interrupted
+    when the system sleeps.
+
+    The function only operates on macOS systems and silently does nothing on
+    other operating systems.
+
+    Args:
+        pid (int, optional): Process ID to monitor. If provided, caffeinate will
+            keep the system awake as long as the specified process is running.
+            If None or 0, defaults to the current process ID (os.getpid()).
+
+    Returns:
+        None
+
+    Raises:
+        FileNotFoundError: If 'caffeinate' command is not found in PATH (shouldn't
+            happen on standard macOS installations).
+        OSError: If subprocess.Popen fails to start the caffeinate process.
+
+    Example:
+        >>> # Keep system awake while current process runs
+        >>> caffeinate()
+
+        >>> # Keep system awake while specific process runs
+        >>> caffeinate(1234)
+
+    Note:
+        - Uses 'caffeinate -i -w <pid>' which prevents idle sleep (-i) and monitors
+          a specific process (-w)
+        - The caffeinate process will automatically terminate when the monitored
+          process exits
+        - On non-macOS systems, this function does nothing
+        - Logs a warning message when caffeinate is started
+
+    See Also:
+        macOS caffeinate(8) man page for more details on the underlying utility.
+ """
+    if not pid:
+        pid = os.getpid()
+
+    if get_os_name() == "macos":
+        logger.warning(f"Running 'caffeinate -i -w {pid}' on macOS to prevent the system from idle sleeping.")
+        subprocess.Popen([shutil.which('caffeinate'), "-i", "-w", str(pid)])
+
+
 ignore_m_warning("egse.system")
 
 if __name__ == "__main__":