ekfsm 0.13.0a183__py3-none-any.whl → 1.5.0__py3-none-any.whl

ekfsm/devices/pmbus.py

@@ -1,84 +1,48 @@
+import re
 from enum import IntFlag
-from pathlib import Path
 
 from ekfsm.core.components import SysTree
+from ekfsm.devices.utils import retry
+from ekfsm.exceptions import ConfigError, HWMonError
+from ekfsm.log import ekfsm_logger
 
-from ..core.sysfs import SysFSDevice, sysfs_root
-
-from .generic import Device
 from ..core.probe import ProbeableDevice
+from ..core.sysfs import list_sysfs_attributes, sysfs_root
+from .generic import Device
 
-from time import sleep
-from functools import wraps
-from ekfsm.log import ekfsm_logger
-from threading import Lock
-import re
-
-__all__ = ["PsuStatus", "PmBus", "retry"]
+__all__ = [
+    "PSUStatus",
+    "PMBus",
+]
 
 logger = ekfsm_logger(__name__)
 
 
-def retry(max_attempts=5, delay=0.5):
-    """
-    Retry decorator.
-
-    Decorator that retries a function a number of times before giving up.
-
-    This is useful for functions that may fail due to transient errors.
-
-    Note
-    ----
-    This is needed for certain PMBus commands that may fail due to transient errors
-    because page switching timing is not effectively handled by older kernel versions.
-
-    Important
-    ---------
-    This decorator is thread-safe, meaning a read attempt is atomic and cannot
-    be interupted by scheduler.
-
-    Parameters
-    ----------
-    max_attempts
-        The maximum number of attempts before giving up.
-    delay
-        The delay in seconds between attempts.
-    """
-
-    lock = Lock()
-
-    def decorator(func):
-        @wraps(func)
-        def wrapper(*args, **kwargs):
-            attempts = 0
-            while attempts < max_attempts:
-                with lock:
-                    try:
-                        return func(*args, **kwargs)
-                    except Exception as e:
-                        attempts += 1
-                        if attempts == max_attempts:
-                            logger.exception(
-                                f"Failed to execute {func.__name__} after {max_attempts} attempts: {e}"
-                            )
-                            raise e
-                        logger.info(
-                            f"Retrying execution of {func.__name__} in {delay}s..."
-                        )
-                sleep(delay)
-
-        return wrapper
-
-    return decorator
-
-
-class PsuStatus(IntFlag):
+class PSUStatus(IntFlag):
     """
     Represents the status of a PSU according to STATUS_BYTE register.
 
-    See Also
+    See also
     --------
+    External Documentation:
     `PMBus Power System Management Protocol Specification - Part II - Revision 1.4, Fig. 60 <https://pmbus.org/>`_
+
+    Example
+    -------
+    >>> from ekfsm.devices.pmbus import PsuStatus
+    >>> status = PsuStatus(0x1F)
+    >>> status
+    <PsuStatus.OUTPUT_OVERCURRENT|INPUT_UNDERVOLTAGE|TEMP_ANORMALY|COMMUNICATION_ERROR|ERROR: 31>
+    >>> PsuStatus.OUTPUT_OVERCURRENT in status
+    True
+    >>> # OK is always present
+    >>> PsuStatus.OK in status
+    True
+    >>> # Instead, check if status is OK
+    >>> status == PsuStatus(0x00)
+    False
+    >>> PsuStatus.OUTPUT_OVERCURRENT in status
+    False
     """
 
     OUTPUT_OVERVOLTAGE = 0x20
@@ -90,41 +54,50 @@ class PsuStatus(IntFlag):
     OK = 0x00
 
 
-class PmBus(Device, ProbeableDevice):
+logger = ekfsm_logger(__name__)
+
 
+class PMBus(Device, ProbeableDevice):
     def __init__(
         self,
         name: str,
         parent: SysTree | None = None,
         children: list[Device] | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
-        super().__init__(name, parent, children, **kwargs)
+        super().__init__(name, parent, children, abort, *args, **kwargs)
         self.addr = self.get_i2c_chip_addr()
-        self.sysfs_device = self.get_i2c_sysfs_device(self.addr)
-
-        files = list(Path(self.sysfs_device.path).rglob("hwmon/*/in1_input"))
-        if len(files) == 0:
-            raise FileNotFoundError("No HWMON entries found in sysfs")
-        self.hwmon_sysfs = SysFSDevice(files[0].parent)
-
-        self.debugfs_root = sysfs_root() / "kernel/debug/pmbus"
-        files = list(self.debugfs_root.rglob("hwmon*/status*_input"))
-        if len(files) == 0:
-            raise FileNotFoundError("No HWMON entries found in debugfs")
-        self.hwmon_debugfs = SysFSDevice(files[0].parent)
+        self.sysfs_device = self.get_i2c_sysfs_device(self.addr, driver_required=True)
+
+        try:
+            for entry in self.sysfs_device.path.glob("hwmon/hwmon*"):
+                if entry.is_dir():
+                    attrs = list_sysfs_attributes(entry)
+                    self.sysfs_device.extend_attributes(attrs)
+
+                    debug_attrs_path = sysfs_root().joinpath(
+                        f"kernel/debug/pmbus/{entry.name}"
+                    )
+                    debug_attrs = list_sysfs_attributes(debug_attrs_path)
+                    self.sysfs_device.extend_attributes(debug_attrs)
+        except FileNotFoundError:
+            logger.debug("Expected sysfs attribute not found")
+        except StopIteration:
+            raise HWMonError("Device is not managed by hwmon subsystem")
 
     def probe(self, *args, **kwargs) -> bool:
-        from ekfsm.core import HwModule
+        from ekfsm.core import HWModule
 
-        assert isinstance(self.hw_module, HwModule)
+        if not isinstance(self.hw_module, HWModule):
+            raise ConfigError(f"{self.name}: hw_module must be a HWModule instance")
         # compare the regexp from the board yaml file with the model
         return re.match(self.hw_module.id, self.model()) is not None
 
     # Voltage and Current Interfaces
-    def _conversion(self, in_file: str) -> float:
-        return float(self.hwmon_sysfs.read_attr_utf8(in_file)) / 1000.0
+    def __convert_and_scale(self, attr: str) -> float:
+        return self.sysfs.read_float(attr) / 1000.0
 
     @retry()
     def in1_input(self) -> float:
@@ -135,7 +108,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input voltage in volts
         """
-        return self._conversion("in1_input")
+        return self.__convert_and_scale("in1_input")
 
     @retry()
     def in2_input(self) -> float:
@@ -146,7 +119,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input voltage in volts
         """
-        return self._conversion("in2_input")
+        return self.__convert_and_scale("in2_input")
 
     @retry()
     def curr1_input(self) -> float:
@@ -157,7 +130,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input current in amperes
         """
-        return self._conversion("curr1_input")
+        return self.__convert_and_scale("curr1_input")
 
     @retry()
     def curr2_input(self) -> float:
@@ -168,32 +141,32 @@ class PmBus(Device, ProbeableDevice):
         -------
             Input current in amperes
         """
-        return self._conversion("curr2_input")
+        return self.__convert_and_scale("curr2_input")
 
     # Status Interface
     @retry()
-    def status0_input(self) -> PsuStatus:
+    def status0_input(self) -> PSUStatus:
         """
         Get the status of PSU page 1.
 
         Returns
         -------
-            PSU status as defined in PsuStatus
+            PSU status as defined in PSUStatus
         """
-        status = int(self.hwmon_debugfs.read_attr_utf8("status0_input").strip(), 16)
-        return PsuStatus(status)
+        status = self.sysfs.read_hex("status0_input")
+        return PSUStatus(status)
 
     @retry()
-    def status1_input(self) -> PsuStatus:
+    def status1_input(self) -> PSUStatus:
         """
         Get the status of PSU page 2.
 
         Returns
         -------
-            PSU status as defined in PsuStatus
+            PSU status as defined in PSUStatus
         """
-        status = int(self.hwmon_debugfs.read_attr_utf8("status1_input").strip(), 16)
-        return PsuStatus(status)
+        status = self.sysfs.read_hex("status1_input")
+        return PSUStatus(status)
 
     # Temperature Interface
     @retry()
@@ -205,7 +178,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU temperature in degrees celsius
         """
-        return self._conversion("temp1_input")
+        return self.__convert_and_scale("temp1_input")
 
     # Inventory Interface
     def vendor(self) -> str:
@@ -216,7 +189,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU vendor
         """
-        return self.hwmon_sysfs.read_attr_utf8("vendor").strip()
+        return self.sysfs.read_utf8("vendor")
 
     def model(self) -> str:
         """
@@ -226,7 +199,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU model
         """
-        return self.hwmon_sysfs.read_attr_utf8("model").strip()
+        return self.sysfs.read_utf8("model")
 
     def serial(self) -> str:
         """
@@ -236,7 +209,7 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU serial number
         """
-        return self.hwmon_sysfs.read_attr_utf8("serial").strip()
+        return self.sysfs.read_utf8("serial")
 
     def revision(self) -> str:
         """
@@ -246,4 +219,4 @@ class PmBus(Device, ProbeableDevice):
         -------
             PSU revision
         """
-        return self.hwmon_sysfs.read_attr_utf8("revision").strip()
+        return self.sysfs.read_utf8("revision")

ekfsm/devices/smbios.py

@@ -1,8 +1,13 @@
 from pathlib import Path
-from ekfsm.core.components import HwModule
-from ekfsm.core.sysfs import SysFSDevice, sysfs_root
+
+from ekfsm.core.components import HWModule
+from ekfsm.core.sysfs import SysfsDevice, sysfs_root
+from ekfsm.log import ekfsm_logger
+
 from .generic import Device
 
+logger = ekfsm_logger(__name__)
+
 
 class SMBIOS(Device):
     """
@@ -18,15 +23,23 @@ class SMBIOS(Device):
     def __init__(
         self,
         name: str,
-        parent: HwModule | None = None,
+        parent: HWModule | None = None,
+        children: list["Device"] | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
-        self.sysfs_device: SysFSDevice = SysFSDevice(
-            sysfs_root() / Path("devices/virtual/dmi/id")
-        )
+        logger.debug(f"Initializing SMBIOS device '{name}'")
+
+        try:
+            dmi_path = sysfs_root() / Path("devices/virtual/dmi/id")
+            self.sysfs_device: SysfsDevice | None = SysfsDevice(dmi_path, False)
+            logger.info(f"SMBIOS '{name}' initialized with DMI table at {dmi_path}")
+        except Exception as e:
+            logger.error(f"Failed to initialize SMBIOS '{name}' with DMI table: {e}")
+            raise
 
-        super().__init__(name, parent, None, *args, **kwargs)
+        super().__init__(name, parent, None, abort, *args, **kwargs)
 
     def revision(self) -> str:
         """
@@ -37,4 +50,11 @@ class SMBIOS(Device):
         str
             The board revision.
         """
-        return self.sysfs_device.read_attr_utf8("board_version").strip()
+        logger.debug(f"Reading board revision for SMBIOS '{self.name}'")
+        try:
+            revision = self.sysfs.read_utf8("board_version")
+            logger.debug(f"SMBIOS '{self.name}' board revision: {revision}")
+            return revision
+        except Exception as e:
+            logger.error(f"Failed to read board revision for SMBIOS '{self.name}': {e}")
+            raise

ekfsm/devices/smbus.py

@@ -2,7 +2,7 @@ from abc import ABC, abstractmethod
 from typing import List
 
 
-class SimSmbus(ABC):
+class SimSMBus(ABC):
     @abstractmethod
     def read_word_data(self, cmd: int) -> int:
         pass

ekfsm/devices/thermal_humidity.py

@@ -0,0 +1,80 @@
+from ekfsm.devices.generic import Device
+from ekfsm.devices.io4edge import IO4Edge
+from ekfsm.devices.utils import retry
+from ekfsm.log import ekfsm_logger
+from io4edge_client.analogintypeb import Client
+
+logger = ekfsm_logger(__name__)
+
+
+class ThermalHumidity(Device):
+    """
+    Device class for handling a thermal humidity sensor.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: IO4Edge,
+        children: list[Device] | None = None,
+        abort: bool = False,
+        service_suffix: str | None = None,
+        *args,
+        **kwargs,
+    ):
+        logger.debug(
+            f"Initializing ThermalHumidity sensor '{name}' with parent device {parent.deviceId}"
+        )
+
+        super().__init__(name, parent, children, abort, *args, **kwargs)
+
+        self.name = name
+
+        if service_suffix is not None:
+            self.service_suffix = service_suffix
+            logger.debug(f"Using custom service suffix: {service_suffix}")
+        else:
+            self.service_suffix = name
+            logger.debug(f"Using default service suffix: {name}")
+
+        self.service_addr = f"{parent.deviceId}-{self.service_suffix}"
+        logger.info(
+            f"ThermalHumidity '{name}' configured with service address: {self.service_addr}"
+        )
+
+        try:
+            self.client = Client(self.service_addr, connect=False)
+            logger.debug(
+                f"ThermalHumidity client created for service: {self.service_addr}"
+            )
+        except Exception as e:
+            logger.error(
+                f"Failed to create ThermalHumidity client for {self.service_addr}: {e}"
+            )
+            raise
+
+    @retry()
+    def temperature(self) -> float:
+        """
+        Get the temperature in Celsius.
+
+        Raises
+        ------
+        RuntimeError
+            if the command fails
+        TimeoutError
+            if the command times out
+        """
+        logger.info(f"Reading temperature from ThermalHumidity sensor '{self.name}'")
+        try:
+            temp = self.client.value()
+            logger.info(f"ThermalHumidity '{self.name}' temperature: {temp}°C")
+            return temp
+        except Exception as e:
+            logger.error(
+                f"Failed to read temperature from ThermalHumidity '{self.name}': {e}"
+            )
+            raise
+
+    def __repr__(self):
+        return f"{self.name}; Service Address: {self.service_addr}"

ekfsm/devices/toggles.py

@@ -0,0 +1,90 @@
+from ekfsm.devices.utils import retry
+from io4edge_client.binaryiotypeb import Client
+from ekfsm.devices.generic import Device
+from ekfsm.devices.io4edge import GPIOArray
+from ekfsm.log import ekfsm_logger
+
+logger = ekfsm_logger(__name__)
+
+
+class BinaryToggle(Device):
+    """
+    Device class for handling a binary toggle switch.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: GPIOArray,
+        children: list[Device] | None = None,
+        abort: bool = False,
+        channel_id: int = 0,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(name, parent, children, abort, *args, **kwargs)
+
+        self.channel_id = channel_id
+
+        logger.debug(
+            f"Initializing BinaryToggle '{name}' with parent device {parent.deviceId}"
+        )
+
+        super().__init__(name, parent, children, abort, *args, **kwargs)
+
+        self.name = name
+
+        self.service_addr = parent.service_addr
+
+        logger.info(
+            f"BinaryToggle '{name}' configured with service address: {self.service_addr} on channel {channel_id}"
+        )
+
+        self.client: Client = parent.client
+
+    @retry()
+    def set(self, state: bool):
+        """
+        Set the state of the toggle switch.
+
+        Parameters
+        ----------
+            state
+                state to set. a "true" state turns on the toggle switch, a "false" state turns it off.
+        """
+        logger.info(
+            f"Setting BinaryToggle '{self.name}' on channel {self.channel_id} to state {state}"
+        )
+        self.client.set_output(self.channel_id, state)
+        logger.info(
+            f"BinaryToggle '{self.name}' on channel {self.channel_id} set to state {state}"
+        )
+
+    @retry()
+    def get(self) -> bool:
+        """
+        Get the current state of the toggle switch.
+
+        Returns
+            The current state of the toggle switch.
+        """
+        state = self.client.get_input(self.channel_id)
+        logger.info(
+            f"Retrieved state {state} for BinaryToggle '{self.name}' on channel {self.channel_id}"
+        )
+        return state
+
+    def on(self):
+        """
+        Turn the toggle switch on.
+        """
+        self.set(True)
+
+    def off(self):
+        """
+        Turn the toggle switch off.
+        """
+        self.set(False)
+
+    def __repr__(self):
+        return f"{self.name}; Channel ID: {self.channel_id}"

ekfsm/devices/utils.py

@@ -1,16 +1,60 @@
+from functools import wraps
+from time import sleep
 from crcmod.predefined import Crc
-from typing import Sequence
+from ekfsm.log import ekfsm_logger
 
-
-def compute_int_from_bytes(data: Sequence[int]) -> int:
-    # Combine the bytes into a single integer
-    result = 0
-    for num in data:
-        result = (result << 8) | num
-    return result
+logger = ekfsm_logger(__name__)
 
 
 def get_crc16_xmodem(data: bytes) -> int:
     crc16_xmodem = Crc("xmodem")
     crc16_xmodem.update(data)
     return crc16_xmodem.crcValue
+
+
+def retry(max_attempts=5, delay=0.5):
+    """
+    Retry decorator.
+
+    Decorator that retries a function a number of times before giving up.
+
+    This is useful for functions that may fail due to transient errors.
+
+    Note
+    ----
+    This is needed for certain PMBus commands that may fail due to transient errors
+    because page switching timing is not effectively handled by older kernel versions.
+
+    Important
+    ---------
+    This decorator is _not_ thread-safe across multiple ekfsm processes. Unfortunately,
+    we cannot use fcntl or flock syscalls with files on virtual filesystems like sysfs.
+
+    Parameters
+    ----------
+    max_attempts
+        The maximum number of attempts before giving up.
+    delay
+        The delay in seconds between attempts.
+    """
+
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            attempts = 0
+            while attempts < max_attempts:
+                try:
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    attempts += 1
+                    if attempts == max_attempts:
+                        logger.exception(
+                            f"Failed to execute {func.__name__} after {max_attempts} attempts: {e}"
+                        )
+                        raise e
+                    logger.info(f"Retrying execution of {func.__name__} in {delay}s...")
+                sleep(delay)
+
+        return wrapper
+
+    return decorator

ekfsm/devices/watchdog.py

@@ -0,0 +1,79 @@
+from ekfsm.devices.generic import Device
+from ekfsm.devices.io4edge import IO4Edge
+from ekfsm.devices.utils import retry
+from ekfsm.log import ekfsm_logger
+from io4edge_client.watchdog import Client
+
+logger = ekfsm_logger(__name__)
+
+
+class Watchdog(Device):
+    """
+    Device class for handling an application watchdog.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: IO4Edge,
+        children: list[Device] | None = None,
+        abort: bool = False,
+        service_suffix: str | None = None,
+        *args,
+        **kwargs,
+    ):
+        logger.debug(
+            f"Initializing Watchdog '{name}' with parent device {parent.deviceId}"
+        )
+
+        super().__init__(name, parent, children, abort, *args, **kwargs)
+
+        self.name = name
+
+        if service_suffix is not None:
+            self.service_suffix = service_suffix
+            logger.debug(f"Using custom service suffix: {service_suffix}")
+        else:
+            self.service_suffix = name
+            logger.debug(f"Using default service suffix: {name}")
+
+        self.service_addr = f"{parent.deviceId}-{self.service_suffix}"
+        logger.info(
+            f"Watchdog '{name}' configured with service address: {self.service_addr}"
+        )
+
+        try:
+            self.client = Client(self.service_addr, connect=False)
+            logger.debug(f"Watchdog client created for service: {self.service_addr}")
+        except Exception as e:
+            logger.error(
+                f"Failed to create Watchdog client for {self.service_addr}: {e}"
+            )
+            raise
+
+    @retry()
+    def describe(self):
+        pass
+
+    @retry()
+    def kick(self) -> None:
+        """
+        Kick the watchdog.
+
+        Raises
+        ------
+        RuntimeError
+            if the command fails
+        TimeoutError
+            if the command times out
+        """
+        logger.info(f"Kicking watchdog '{self.name}' on service {self.service_addr}")
+        try:
+            self.client.kick()
+            logger.info(f"Watchdog '{self.name}' kick successful")
+        except Exception as e:
+            logger.error(f"Failed to kick watchdog '{self.name}': {e}")
+            raise
+
+    def __repr__(self):
+        return f"{self.name}; Service Address: {self.service_addr}"