cgse-common 0.15.0__py3-none-any.whl → 0.16.0__py3-none-any.whl

cgse_common/cgse.py

@@ -72,7 +72,7 @@ class SortedCommandGroup(TyperGroup):
         commands = super().list_commands(ctx)
 
         # Define priority commands in specific order
-        priority_commands = ["init", "version", "show", "top", "core", "registry", "log", "cm", "sm", "pm"]
+        priority_commands = ["init", "version", "show", "top", "core", "reg", "not", "log", "cm", "sm", "pm"]
 
         # Custom sort:
         # First the priority commands in the given order (their index)

{cgse_common-0.15.0.dist-info → cgse_common-0.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cgse-common
-Version: 0.15.0
+Version: 0.16.0
 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.15.0.dist-info → cgse_common-0.16.0.dist-info}/RECORD

@@ -1,14 +1,15 @@
 cgse_common/__init__.py,sha256=wTYOpVomEeDFFuqt4Ss9ROSAIa48UUnYCSafdEOx-CU,129
-cgse_common/cgse.py,sha256=FCai_6sHg6hPhzqk5pmnqOpA3Z1e2rAsUdiVGOAgadI,6588
+cgse_common/cgse.py,sha256=4ZCm5UfaXld0RGI-Mjnm6dSAqfWCPX1qz1pew46J-1s,6590
 cgse_common/settings.yaml,sha256=PS8HOoxbhwVoQ7zzDtZyhx25RZB6SGq3uXNuJTgtRIw,443
 egse/bits.py,sha256=cg6diLN2IwNtnrlZyLgXPfDf9ttcHzS2A7Tjwlwc-lQ,12498
 egse/calibration.py,sha256=a5JDaXTC6fMwQ1M-qrwNO31Ass-yYSXxDQUK_PPsZg4,8818
 egse/config.py,sha256=qNW3uvwuEV9VSjiaoQfM_svBYfz4Kwxd1-jv1eTGqyw,9530
+egse/connect.py,sha256=Kv6to6-4ihFcrAy9ErqAGdbhLHUAnqUgYfnBKMfgefU,15053
 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/env.py,sha256=mV5SHtMAr_FRyzrPWjIu0vbCJzJt1n_Tc6tIpwoEffA,28366
 egse/exceptions.py,sha256=QB3MZRJizecWOj1cPbvG0UcIqFn7NRJ6rw1xtdNSFxw,1225
 egse/heartbeat.py,sha256=xt5mePu9Zr9fLAhN1MLq1Z7aCOKtNIhRVCAmWhtNwP8,3039
 egse/hk.py,sha256=AumSpB8SYXes75CB2iiKXfLkMK5IkVDHITFKrf8IT6g,32010
@@ -25,21 +26,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=akT5uTSzCwdWhJBXeBl4V8fes8iirbbYRN1G0-YQCmo,74784
 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.15.0.dist-info/METADATA,sha256=rqvfWopU1HlKrgC_cjkUYL1Jo5VhGXqSBmf1WjKtTa0,3032
-cgse_common-0.15.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-cgse_common-0.15.0.dist-info/entry_points.txt,sha256=erQovXd1bGzsngB0_sfY7IYRNwHIhwq3K8fmQvGS12o,198
-cgse_common-0.15.0.dist-info/RECORD,,
+cgse_common-0.16.0.dist-info/METADATA,sha256=P4cA-5qH_HqxVpqDOcL5jsq9MEt3wChkYMeLQ9Zi8_0,3032
+cgse_common-0.16.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+cgse_common-0.16.0.dist-info/entry_points.txt,sha256=erQovXd1bGzsngB0_sfY7IYRNwHIhwq3K8fmQvGS12o,198
+cgse_common-0.16.0.dist-info/RECORD,,

egse/connect.py

@@ -0,0 +1,369 @@
+import random
+import threading
+import time
+from enum import Enum
+
+from egse.log import logging
+
+logger = logging.getLogger("egse.connect")
+
+# random.seed(time.monotonic())  # uncomment for testing only, main application should set a seed.
+
+
+class ConnectionState(Enum):
+    DISCONNECTED = "disconnected"
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    CIRCUIT_OPEN = "circuit_open"  # Temporarily stopped trying
+
+
+class BackoffStrategy(Enum):
+    """
+    Specifies the strategy for increasing the delay between retry attempts
+    in backoff algorithms to reduce load and avoid overwhelming services.
+
+    Strategies:
+        EXPONENTIAL:
+            The delay doubles with each retry attempt (e.g., 1s, 2s, 4s, 8s).
+            This is the most widely used approach because it quickly reduces load on struggling systems.
+        LINEAR:
+            The delay increases by a fixed amount each time (e.g., 1s, 2s, 3s, 4s).
+            This provides a more gradual reduction in request rate.
+        FIXED:
+            Uses the same delay between all retry attempts.
+            Simple but less adaptive to system conditions.
+
+    References:
+        - AWS Architecture Blog: Exponential Backoff And Jitter
+    """
+
+    EXPONENTIAL = "exponential"
+    """The delay doubles with each retry attempt (e.g., 1s, 2s, 4s, 8s). 
+    This is the most widely used approach because it quickly reduces load on struggling systems."""
+    LINEAR = "linear"
+    """The delay increases by a fixed amount each time (e.g., 1s, 2s, 3s, 4s). 
+    This provides a more gradual reduction in request rate."""
+    FIXED = "fixed"
+    """Uses the same delay between all retry attempts. Simple but less adaptive to system conditions."""
+
+
+class JitterStrategy(Enum):
+    """
+    Specifies the strategy for applying jitter (randomization) to retry intervals
+    in backoff algorithms to avoid synchronized retries and reduce load spikes.
+
+    Strategies:
+        NONE:
+            No jitter is applied. The retry interval is deterministic.
+        FULL:
+            Applies full jitter by selecting a random value uniformly between 0 and the calculated interval.
+            This maximizes randomness but can result in very short delays.
+        EQUAL:
+            Applies "equal jitter" as described in the AWS Architecture Blog.
+            The interval is randomized within [interval/2, interval], ensuring a minimum delay of half the interval.
+            Note: This is not the same as "a jitter of 50% around interval" (which would be [0.5 * interval, 1.5 * interval]).
+        PERCENT_10:
+            Applies a jitter of ±10% around the base interval, resulting in a random interval within [0.9 * interval, 1.1 * interval].
+
+    References:
+        - AWS Architecture Blog: Exponential Backoff And Jitter
+    """
+
+    NONE = "none"
+    """No jitter is applied to the backoff."""
+    FULL = "full"
+    """Maximum distribution but can be too random with very short intervals."""
+    EQUAL = "equal"
+    """Best balance, maintains backoff properties while preventing synchronization."""
+    PERCENT_10 = "10%"
+    """Add a jitter of 10% around the base interval."""
+
+
+def calculate_retry_interval(
+    attempt_number,
+    base_interval,
+    max_interval,
+    backoff_strategy: BackoffStrategy = BackoffStrategy.EXPONENTIAL,
+    jitter_strategy: JitterStrategy = JitterStrategy.EQUAL,
+):
+    """
+    Calculates the next retry interval based on the given backoff and jitter strategies.
+
+    Args:
+        attempt_number (int): The current retry attempt (starting from 0).
+        base_interval (float): The initial interval in seconds.
+        max_interval (float): The maximum allowed interval in seconds.
+        backoff_strategy (BackoffStrategy): Strategy for increasing the delay (exponential, linear, or fixed).
+        jitter_strategy (JitterStrategy): Strategy for randomizing the delay to avoid synchronization.
+
+    Returns:
+        float: The computed retry interval in seconds.
+
+    Notes:
+        - See the docstrings for BackoffStrategy and JitterStrategy for details on each strategy.
+        - Based on best practices from the AWS Architecture Blog: Exponential Backoff And Jitter.
+    """
+
+    if backoff_strategy == BackoffStrategy.EXPONENTIAL:
+        interval = min(base_interval * (2**attempt_number), max_interval)
+    elif backoff_strategy == BackoffStrategy.LINEAR:
+        interval = min(base_interval + attempt_number, max_interval)
+    else:
+        interval = base_interval
+
+    if jitter_strategy == JitterStrategy.NONE:
+        return interval
+    elif jitter_strategy == JitterStrategy.FULL:
+        return random.uniform(0, interval)
+    elif jitter_strategy == JitterStrategy.EQUAL:
+        return interval / 2 + random.uniform(0, interval / 2)
+    elif jitter_strategy == JitterStrategy.PERCENT_10:
+        jitter_amount = interval * 0.1
+        return interval + random.uniform(-jitter_amount, jitter_amount)
+
+    return interval
+
+
+class AsyncServiceConnector:
+    """
+    Asynchronous base class for robust service connection management with retry, backoff, and circuit breaker logic.
+
+    This class is intended to be subclassed for managing persistent connections to external services
+    (such as devices, databases, or remote APIs) that may be unreliable or temporarily unavailable.
+
+    Features:
+        - Automatic retry with configurable backoff and jitter strategies.
+        - Circuit breaker to prevent repeated connection attempts after multiple failures.
+        - Connection state tracking (disconnected, connecting, connected, circuit open).
+
+    Usage:
+        1. Subclass `AsyncServiceConnector` and override the `connect_to_service()` coroutine with your
+           actual connection logic. Optionally, override `health_check()` for custom health verification.
+        2. Store the actual connection object (e.g., socket, transport) as an instance attribute in your subclass.
+        3. Use `attempt_connection()` to initiate connection attempts; it will handle retries and backoff automatically.
+        4. Use `is_connected()` to check connection status.
+
+    Example:
+        class MyConnector(AsyncServiceConnector):
+            async def connect_to_service(self):
+                self.connection = await create_socket()
+                return self.connection is not None
+
+            def get_connection(self):
+                return self.connection
+
+    Note:
+        The base class does not manage or expose the underlying connection object.
+        Your subclass should provide a method or property to access it as needed.
+    """
+
+    def __init__(self, service_name: str):
+        self.state = ConnectionState.DISCONNECTED
+        self.last_attempt = 0
+        self.base_interval = 1
+        self.retry_interval = 1  # Start with 1 second
+        self.max_retry_interval = 300  # Max 5 minutes
+        self.failure_count = 0
+        self.max_failures_before_circuit_break = 5
+        self.circuit_break_duration = 60  # 1 minute
+        self.circuit_opened_at = None
+
+        self.service_name = service_name
+
+    async def connect_to_service(self) -> bool:
+        logger.warning(
+            f"The connect_to_service() method is not implemented for {self.service_name}, connection will always fail."
+        )
+        return False
+
+    async def health_check(self) -> bool:
+        logger.warning(
+            f"The health_check() method is not implemented for {self.service_name}, check will always return false."
+        )
+        return False
+
+    def should_attempt_connection(self) -> bool:
+        """Return True if we should attempt a new connection."""
+        now = time.monotonic()
+
+        # If circuit is open, check if we should close it
+        if self.state == ConnectionState.CIRCUIT_OPEN:
+            if now - self.circuit_opened_at > self.circuit_break_duration:
+                self.state = ConnectionState.DISCONNECTED
+                self.failure_count = 0
+                self.retry_interval = 1
+                return True
+            return False
+
+        # Regular backoff logic
+        return now - self.last_attempt >= self.retry_interval
+
+    async def attempt_connection(self):
+        """Try to connect to the service.
+
+        This will execute the callable argument `connect_to_service` that was passed
+        into the constructor. That function shall return True when the connection
+        succeeded, False otherwise.
+        """
+        if not self.should_attempt_connection():
+            return
+
+        self.state = ConnectionState.CONNECTING
+        self.last_attempt = time.monotonic()
+
+        try:
+            success = await self.connect_to_service()
+
+            if success:
+                self.state = ConnectionState.CONNECTED
+                self.failure_count = 0
+                self.retry_interval = 1  # Reset backoff
+                logger.info(f"Successfully connected to service {self.service_name}")
+            else:
+                # warning should have been logged by the connect_to_service() callable.
+                self.handle_connection_failure()
+
+        except Exception as exc:
+            logger.warning(f"Failed to connect to service {self.service_name}: {exc}")
+            self.handle_connection_failure()
+
+    def handle_connection_failure(self):
+        self.failure_count += 1
+
+        # Open circuit breaker if too many failures
+        if self.failure_count >= self.max_failures_before_circuit_break:
+            self.state = ConnectionState.CIRCUIT_OPEN
+            self.circuit_opened_at = time.time()
+            logger.warning(
+                f"Circuit breaker opened for service {self.service_name} after {self.failure_count} failures"
+            )
+        else:
+            self.state = ConnectionState.DISCONNECTED
+            self.retry_interval = calculate_retry_interval(
+                self.failure_count,
+                self.base_interval,
+                self.max_retry_interval,
+                BackoffStrategy.EXPONENTIAL,
+                JitterStrategy.EQUAL,
+            )
+            logger.debug(f"retry_interval={self.retry_interval}")
+
+    def is_connected(self) -> bool:
+        return self.state == ConnectionState.CONNECTED
+
+
+class ServiceConnector:
+    """
+    Synchronous base class for robust service connection management with retry, backoff, and circuit breaker logic.
+
+    This class is intended to be subclassed for managing persistent connections to external services
+    (such as devices, databases, or remote APIs) that may be unreliable or temporarily unavailable.
+
+    Features:
+        - Automatic retry with configurable backoff and jitter strategies.
+        - Circuit breaker to prevent repeated connection attempts after multiple failures.
+        - Connection state tracking (disconnected, connecting, connected, circuit open).
+        - Thread-safe operation using a lock for all state changes.
+
+    Usage:
+        1. Subclass `ServiceConnector` and override the `connect_to_service()` method with your
+           actual connection logic. Optionally, override `health_check()` for custom health verification.
+        2. Store the actual connection object (e.g., socket, transport) as an instance attribute in your subclass.
+        3. Use `attempt_connection()` to initiate connection attempts; it will handle retries and backoff automatically.
+        4. Use `is_connected()` to check connection status.
+
+    Example:
+        class MyConnector(ServiceConnector):
+            def connect_to_service(self):
+                self.connection = create_socket()
+                return self.connection is not None
+
+            def get_connection(self):
+                return self.connection
+
+    Note:
+        The base class does not manage or expose the underlying connection object.
+        Your subclass should provide a method or property to access it as needed.
+    """
+
+    def __init__(self, service_name: str):
+        self.state = ConnectionState.DISCONNECTED
+        self.last_attempt = 0
+        self.base_interval = 1
+        self.retry_interval = 1
+        self.max_retry_interval = 300
+        self.failure_count = 0
+        self.max_failures_before_circuit_break = 5
+        self.circuit_break_duration = 60
+        self.circuit_opened_at = None
+        self.service_name = service_name
+        self._lock = threading.RLock()
+
+    def connect_to_service(self) -> bool:
+        logger.warning(
+            f"The connect_to_service() method is not implemented for {self.service_name}, connection will always fail."
+        )
+        return False
+
+    def health_check(self) -> bool:
+        logger.warning(
+            f"The health_check() method is not implemented for {self.service_name}, check will always return false."
+        )
+        return False
+
+    def should_attempt_connection(self) -> bool:
+        now = time.monotonic()
+        with self._lock:
+            if self.state == ConnectionState.CIRCUIT_OPEN:
+                if now - self.circuit_opened_at > self.circuit_break_duration:
+                    self.state = ConnectionState.DISCONNECTED
+                    self.failure_count = 0
+                    self.retry_interval = 1
+                    return True
+                return False
+            return now - self.last_attempt >= self.retry_interval
+
+    def attempt_connection(self):
+        with self._lock:
+            if not self.should_attempt_connection():
+                return
+            self.state = ConnectionState.CONNECTING
+            self.last_attempt = time.monotonic()
+
+        try:
+            success = self.connect_to_service()
+            with self._lock:
+                if success:
+                    self.state = ConnectionState.CONNECTED
+                    self.failure_count = 0
+                    self.retry_interval = 1
+                    logger.info(f"Successfully connected to service {self.service_name}")
+                else:
+                    self.handle_connection_failure()
+        except Exception as exc:
+            logger.error(f"Failed to connect to service {self.service_name}: {exc}")
+            with self._lock:
+                self.handle_connection_failure()
+
+    def handle_connection_failure(self):
+        self.failure_count += 1
+        if self.failure_count >= self.max_failures_before_circuit_break:
+            self.state = ConnectionState.CIRCUIT_OPEN
+            self.circuit_opened_at = time.monotonic()
+            logger.warning(
+                f"Circuit breaker opened for service {self.service_name} after {self.failure_count} failures"
+            )
+        else:
+            self.state = ConnectionState.DISCONNECTED
+            self.retry_interval = calculate_retry_interval(
+                self.failure_count,
+                self.base_interval,
+                self.max_retry_interval,
+                BackoffStrategy.EXPONENTIAL,
+                JitterStrategy.EQUAL,
+            )
+            logger.debug(f"retry_interval={self.retry_interval}")
+
+    def is_connected(self) -> bool:
+        with self._lock:
+            return self.state == ConnectionState.CONNECTED

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/env.py

@@ -451,7 +451,7 @@ def set_local_settings(path: str | Path | None):
     _env.set("LOCAL_SETTINGS", path)
 
 
-def get_local_settings_path() -> str or None:
+def get_local_settings_path() -> str | None:
     """
     Returns the fully qualified filename of the local settings YAML file. When the local settings environment
     variable is not defined or is an empty string, None is returned.

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__":