ekfsm 0.12.0.post1__py3-none-any.whl → 0.13.0a168.post1__py3-none-any.whl

ekfsm/devices/pmbus.py

@@ -1,18 +1,100 @@
+from enum import IntFlag
 from pathlib import Path
 
-from ekfsm.core.components import SystemComponent
+from ekfsm.core.components import SysTree
 
-from ..core.sysfs import SysFSDevice
+from ..core.sysfs import SysFSDevice, sysfs_root
 
 from .generic import Device
 from ..core.probe import ProbeableDevice
 
+from time import sleep
+from functools import wraps
+from ekfsm.log import ekfsm_logger
+from threading import Lock
+
+__all__ = ["PsuStatus", "PmBus", "retry"]
+
+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):
+    """
+    Represents the status of a PSU according to STATUS_BYTE register.
+
+    See Also
+    --------
+    `PMBus Power System Management Protocol Specification - Part II - Revision 1.4, Fig. 60 <https://pmbus.org/>`_
+    """
+
+    OUTPUT_OVERVOLTAGE = 0x20
+    OUTPUT_OVERCURRENT = 0x10
+    INPUT_UNDERVOLTAGE = 0x08
+    TEMP_ANORMALY = 0x04
+    COMMUNICATION_ERROR = 0x02
+    ERROR = 0x01
+    OK = 0x00
+
 
 class PmBus(Device, ProbeableDevice):
+
     def __init__(
         self,
         name: str,
-        parent: SystemComponent | None = None,
+        parent: SysTree | None = None,
         children: list[Device] | None = None,
         *args,
         **kwargs,
@@ -23,43 +105,143 @@ class PmBus(Device, ProbeableDevice):
 
         files = list(Path(self.sysfs_device.path).rglob("hwmon/*/in1_input"))
         if len(files) == 0:
-            raise FileNotFoundError("No HWMON entries found")
+            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)
+
     def probe(self, *args, **kwargs) -> bool:
         from ekfsm.core import HwModule
 
-        assert isinstance(self.root, HwModule)
-        return self.root.id == self.model()
+        assert isinstance(self.hw_module, HwModule)
+        return self.hw_module.id == self.model()
 
     # Voltage and Current Interfaces
-    def _in_conversion(self, in_file: str) -> float:
-        return float(self.hwmon_sysfs.read_attr_utf8(in_file)) / 1000.0
-
-    def _current_conversion(self, in_file: str) -> float:
+    def _conversion(self, in_file: str) -> float:
         return float(self.hwmon_sysfs.read_attr_utf8(in_file)) / 1000.0
 
+    @retry()
     def in1_input(self) -> float:
-        return self._in_conversion("in1_input")
+        """
+        Get input voltage of PSU page 1.
 
+        Returns
+        -------
+            Input voltage in volts
+        """
+        return self._conversion("in1_input")
+
+    @retry()
     def in2_input(self) -> float:
-        return self._in_conversion("in2_input")
+        """
+        Get input voltage of PSU page 2.
+
+        Returns
+        -------
+            Input voltage in volts
+        """
+        return self._conversion("in2_input")
 
+    @retry()
     def curr1_input(self) -> float:
-        return self._current_conversion("curr1_input")
+        """
+        Get input current of PSU page 1.
 
+        Returns
+        -------
+            Input current in amperes
+        """
+        return self._conversion("curr1_input")
+
+    @retry()
     def curr2_input(self) -> float:
-        return self._current_conversion("curr2_input")
+        """
+        Get input current of PSU page 2.
+
+        Returns
+        -------
+            Input current in amperes
+        """
+        return self._conversion("curr2_input")
+
+    # Status Interface
+    @retry()
+    def status0_input(self) -> PsuStatus:
+        """
+        Get the status of PSU page 1.
+
+        Returns
+        -------
+            PSU status as defined in PsuStatus
+        """
+        status = int(self.hwmon_debugfs.read_attr_utf8("status0_input").strip(), 16)
+        return PsuStatus(status)
+
+    @retry()
+    def status1_input(self) -> PsuStatus:
+        """
+        Get the status of PSU page 2.
+
+        Returns
+        -------
+            PSU status as defined in PsuStatus
+        """
+        status = int(self.hwmon_debugfs.read_attr_utf8("status1_input").strip(), 16)
+        return PsuStatus(status)
+
+    # Temperature Interface
+    @retry()
+    def temp1_input(self) -> float:
+        """
+        Get the PSU temperature.
+
+        Returns
+        -------
+            PSU temperature in degrees celsius
+        """
+        return self._conversion("temp1_input")
 
     # Inventory Interface
     def vendor(self) -> str:
+        """
+        Get the vendor of the PSU.
+
+        Returns
+        -------
+            PSU vendor
+        """
         return self.hwmon_sysfs.read_attr_utf8("vendor").strip()
 
     def model(self) -> str:
+        """
+        Get the model of the PSU.
+
+        Returns
+        -------
+            PSU model
+        """
         return self.hwmon_sysfs.read_attr_utf8("model").strip()
 
     def serial(self) -> str:
+        """
+        Get the serial number of the PSU.
+
+        Returns
+        -------
+            PSU serial number
+        """
         return self.hwmon_sysfs.read_attr_utf8("serial").strip()
 
     def revision(self) -> str:
+        """
+        Get the revision of the PSU.
+
+        Returns
+        -------
+            PSU revision
+        """
         return self.hwmon_sysfs.read_attr_utf8("revision").strip()

ekfsm/devices/smbios.py

@@ -1,6 +1,6 @@
 from pathlib import Path
 from ekfsm.core.components import HwModule
-from ekfsm.core.sysfs import SysFSDevice, SYSFS_ROOT
+from ekfsm.core.sysfs import SysFSDevice, sysfs_root
 from .generic import Device
 
 
@@ -22,7 +22,9 @@ class SMBIOS(Device):
         *args,
         **kwargs,
     ):
-        self.sysfs_device: SysFSDevice = SysFSDevice(SYSFS_ROOT / Path("devices/virtual/dmi/id"))
+        self.sysfs_device: SysFSDevice = SysFSDevice(
+            sysfs_root() / Path("devices/virtual/dmi/id")
+        )
 
         super().__init__(name, parent, None, *args, **kwargs)
 

ekfsm/devices/smbus.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from typing import List
+
+
+class SimSmbus(ABC):
+    @abstractmethod
+    def read_word_data(self, cmd: int) -> int:
+        pass
+
+    @abstractmethod
+    def read_block_data(self, cmd: int) -> List[int]:
+        pass
+
+    @abstractmethod
+    def write_block_data(self, cmd: int, data: List[int]):
+        pass
+
+    @abstractmethod
+    def write_byte(self, cmd: int):
+        pass
+
+    @abstractmethod
+    def write_word_data(self, cmd: int, data: int):
+        pass

ekfsm/simctrl.py

@@ -1,42 +1,20 @@
-from abc import ABC, abstractmethod
 import socket
 import struct
 from unittest.mock import patch
 from pathlib import Path
 
+from ekfsm.devices.smbus import SimSmbus
 from ekfsm.devices.gpio import EKFIdSimGpio
 from ekfsm.devices.gpio import SimGpio
 from .core.sysfs import set_sysfs_root
-from .core.components import SystemComponent
+from .core.components import SysTree
 
 from .devices import GPIO
 from typing import List
 from smbus2 import SMBus
 
-GPIO_SIM_MAPPING = {}
-SMBUS_SIM_MAPPING = {}
-
-
-class SimSmbus(ABC):
-    @abstractmethod
-    def read_word_data(self, cmd: int) -> int:
-        pass
-
-    @abstractmethod
-    def read_block_data(self, cmd: int) -> List[int]:
-        pass
-
-    @abstractmethod
-    def write_block_data(self, cmd: int, data: List[int]):
-        pass
-
-    @abstractmethod
-    def write_byte(self, cmd: int):
-        pass
-
-    @abstractmethod
-    def write_word_data(self, cmd: int, data: int):
-        pass
+GPIO_SIM_MAPPING: dict[str, SimGpio] = {}
+SMBUS_SIM_MAPPING: dict[str, SimSmbus] = {}
 
 
 def register_gpio_sim(major: int, minor: int, sim_gpio: SimGpio) -> None:
@@ -72,7 +50,7 @@ class GpioSimulator(GPIO):
     def __init__(
         self,
         name: str,
-        parent: SystemComponent | None = None,
+        parent: SysTree | None = None,
         *args,
         **kwargs,
     ):
@@ -191,13 +169,16 @@ def enable_smbus_simulation():
         pm.start()
 
 
-def enable_simulation(sysfs_path: Path):
+def enable_simulation(sysfs_path: Path | str) -> None:
     global GPIO_SIM_MAPPING
     GPIO_SIM_MAPPING = {}
 
     global SMBUS_SIM_MAPPING
     SMBUS_SIM_MAPPING = {}
 
+    if isinstance(sysfs_path, str):
+        sysfs_path = Path(sysfs_path)
+
     set_sysfs_root(sysfs_path)
     enable_gpio_simulation()
     enable_smbus_simulation()

ekfsm/system.py

@@ -2,6 +2,7 @@ from typing import Tuple, Any, Generator
 from pathlib import Path
 from munch import Munch, munchify
 
+from ekfsm.core.components import SysTree
 import yaml
 
 from .core.slots import Slot, SlotType
@@ -46,7 +47,7 @@ def all_board_cfg_files() -> Generator[Path, None, None]:
             yield item
 
 
-class System:
+class System(SysTree):
     """
     A System represents a CPCI system.
 
@@ -94,21 +95,26 @@ class System:
     >>>    print(b.name + b.slot.name) # Print the name of the board and the slot it is in
     """
 
-    def __init__(self, config: Path) -> None:
+    def __init__(self, config: Path, abort: bool = False) -> None:
         """
         Parameters
         ----------
         config
             Path to the config that specifies the system and how the slots are filled.
         """
+        self.config_path = config
+        self.config = load_config(str(self.config_path))
+        self.name = self.config.system_config.name
+
+        super().__init__(self.name, abort=abort)
+
         self.logger = ekfsm_logger(__name__)
         self._init_system(config)
         self._init_slot_attrs()
+        self._aggregate_provider_functions()
+        self.children = self.boards
 
     def _init_system(self, config: Path):
-        self.config_path = config
-        self.config = load_config(str(self.config_path))
-        self.name = self.config.system_config.name
         self.slots: Slots = Slots()
         self.boards: list[HwModule] = []
 
@@ -136,6 +142,18 @@ class System:
         for board in self.boards:
             setattr(self, board.instance_name.lower(), board)
 
+    def _aggregate_provider_functions(self):
+        if hasattr(self.config.system_config, "aggregates"):
+            agg = self.config.system_config.aggregates
+            if agg is not None:
+                for key, value in agg.items():
+                    prv = Munch()
+                    for board in self.boards:
+                        if hasattr(board, key):
+                            prv.update({value: getattr(board, key)})
+                    if value in prv.keys():
+                        setattr(self, value, prv[value])
+
     def reload(self):
         """
         Reload the current system configuration.
@@ -144,7 +162,7 @@ class System:
         ---------
         This will rebuild all system objects and reinitialize the system tree.
         """
-        self._init_system(self.config_path)
+        self.__init__(self.config_path)
 
     def _create_master(self) -> Tuple[HwModule | None, int]:
         for i, slot in enumerate(self.config.system_config.slots):
@@ -190,10 +208,16 @@ class System:
                 hwmod = self._create_hwmodule_from_cfg_file(slot, board_name, path)
 
             except Exception as e:
-                self.logger.error(
-                    f"failed to create desired hwmodule {board_type} (as {board_name}): {e}. Leaving slot empty!"
-                )
-                return None, slot
+                if self.abort:
+                    self.logger.error(
+                        f"failed to create desired hwmodule {board_type} (as {board_name}): {e}. Aborting!"
+                    )
+                    raise e
+                else:
+                    self.logger.error(
+                        f"failed to create desired hwmodule {board_type} (as {board_name}): {e}. Leaving slot empty!"
+                    )
+                    return None, slot
 
             # try to probe desired board type
             if hwmod.probe():
@@ -211,6 +235,7 @@ class System:
                 hwmod = self._create_hwmodule_from_cfg_file(slot, board_name, path)
             except ConfigError:
                 # slot type not matching, ignore
+                # ??? should we log this?
                 continue
             except Exception as e:
                 self.logger.debug(
@@ -274,7 +299,15 @@ class System:
                     f"Slot type mismatch for slot {slot.name}: {cfg.slot_type} != {slot.slot_type}"
                 )
 
-            return HwModule(instance_name=board_name, config=yaml_data, slot=slot)
+            hwmod = HwModule(
+                instance_name=board_name,
+                config=yaml_data,
+                slot=slot,
+                abort=self.abort,
+                parent=self,
+            )
+
+            return hwmod
 
     def get_module_in_slot(self, idx: int) -> HwModule | None:
         return next(
@@ -316,11 +349,5 @@ class System:
             f"'{type(self).__name__}' object has no board with name '{name}'"
         )
 
-    def __str__(self) -> str:
-        output = ""
-        for b in self.boards:
-            output += b._render_tree()
-        return output
-
-    def print(self) -> None:
-        print(self)
+    def __repr__(self):
+        return f"System (name={self.name})"

ekfsm-0.13.0a168.post1.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: ekfsm
+Version: 0.13.0a168.post1
+Summary: The EKF System Management Library (ekfsm) is a sensor monitoring suite for Compact PCI Serial devices.
+Author-email: Klaus Popp <klaus.popp@ci4rail.com>, Jan Jansen <jan@ekf.de>, Felix Päßler <fp@ekf.de>
+Requires-Python: >=3.10
+Requires-Dist: anytree
+Requires-Dist: click>=8.0.1
+Requires-Dist: crcmod
+Requires-Dist: gpiod>=2.1.0
+Requires-Dist: hexdump
+Requires-Dist: more-itertools
+Requires-Dist: munch
+Requires-Dist: smbus2
+Requires-Dist: types-pyyaml>=6.0.12.20241230
+Requires-Dist: yamale
+Description-Content-Type: text/markdown
+
+# ekfsm - EKF system management library
+
+Provides a python library framework for access to system management functions on Linux based modular hardware systems,
+such as CompactPCI-Serial systems.
+
+## Features
+
+- System configuration via YAML configuration file
+- Obtain inventory information of the system and its components
+- Obtain sensor information, such as temperature, humidity, voltage, current, accelerometer, gyroscope, etc.
+- Write and read EEPROM contents
+- Access to system level functions, such as system LEDs, system fan, system power supply, etc.
+- Supports simulation mode for development and testing
+- Probing of desired boards in configured slots
+
+## Requirements
+
+Prior to the use of I2C, PMBus or GPIO devices using the API, those devices have to be initialised by ACPI or manual device setup.
+
+### Example
+
+In order to initialize an EEPROM of type AT24 behind a Mux channel 0, manualy add the device:
+
+```bash
+cd /sys/bus/i2c/devices/0-0074/channel-0/
+echo 24c02 0x55 >new_device
+```
+
+Now we can access the EEPROM contents:
+
+```bash
+hd 8-0055/eeprom
+00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
+*
+00000100
+```
+
+
+## Installation
+
+To install the package via pip, you have to use a virtual environment to ensure full operabilty.
+*Note: CLI entrypoint script won't work if installed in the system store!*
+
+### Prepare virtual environment
+
+First, name, create and activate your virtual environment (here `myvenv`):
+
+```bash
+$ python -m venv myvenv
+$ source myvenv/bin/activate
+```
+
+### Package install
+
+Now install the ekfsm package and all dependencies from the [project pypi registry](https://gitlab.ekf.com/libs/apis/ekfsm/-/packages):
+
+```bash
+(myvenv) $ pip install ekfsm --index-url https://gitlab.ekf.com/api/v4/projects/407/packages/pypi/simple
+Looking in indexes: https://gitlab.ekf.com/api/v4/projects/407/packages/pypi/simple
+Collecting ekfsm
+  Downloading https://gitlab.ekf.com/api/v4/projects/407/packages/pypi/files/e400ee46de9346c086ce708675977cc6ab080c8c016d360970c82d1c436f7c89/ekfsm-0.12.0-py3-none-any.whl (43 kB)
+Collecting anytree (from ekfsm)
+  Using cached anytree-2.12.1-py3-none-any.whl.metadata (8.1 kB)
+Collecting click>=8.0.1 (from ekfsm)
+  Using cached click-8.1.8-py3-none-any.whl.metadata (2.3 kB)
+Collecting crcmod (from ekfsm)
+  Using cached crcmod-1.7-cp312-cp312-linux_x86_64.whl
+Collecting gpiod>=2.1.0 (from ekfsm)
+  Using cached gpiod-2.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (4.1 kB)
+Collecting hexdump (from ekfsm)
+  Using cached hexdump-3.3-py3-none-any.whl
+Collecting more-itertools (from ekfsm)
+  Using cached more_itertools-10.6.0-py3-none-any.whl.metadata (37 kB)
+Collecting munch (from ekfsm)
+  Using cached munch-4.0.0-py2.py3-none-any.whl.metadata (5.9 kB)
+Collecting smbus2 (from ekfsm)
+  Using cached smbus2-0.5.0-py2.py3-none-any.whl.metadata (6.9 kB)
+Collecting types-pyyaml>=6.0.12.20241230 (from ekfsm)
+  Using cached types_PyYAML-6.0.12.20241230-py3-none-any.whl.metadata (1.8 kB)
+Collecting yamale (from ekfsm)
+  Using cached yamale-6.0.0-py3-none-any.whl.metadata (22 kB)
+Collecting six (from anytree->ekfsm)
+  Using cached six-1.17.0-py2.py3-none-any.whl.metadata (1.7 kB)
+Collecting pyyaml (from yamale->ekfsm)
+  Using cached PyYAML-6.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (2.1 kB)
+Using cached click-8.1.8-py3-none-any.whl (98 kB)
+Using cached gpiod-2.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (103 kB)
+Using cached types_PyYAML-6.0.12.20241230-py3-none-any.whl (20 kB)
+Using cached anytree-2.12.1-py3-none-any.whl (44 kB)
+Using cached more_itertools-10.6.0-py3-none-any.whl (63 kB)
+Using cached munch-4.0.0-py2.py3-none-any.whl (9.9 kB)
+Using cached smbus2-0.5.0-py2.py3-none-any.whl (11 kB)
+Using cached yamale-6.0.0-py3-none-any.whl (57 kB)
+Using cached PyYAML-6.0.2-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (767 kB)
+Using cached six-1.17.0-py2.py3-none-any.whl (11 kB)
+Installing collected packages: smbus2, hexdump, crcmod, types-pyyaml, six, pyyaml, munch, more-itertools, gpiod, click, yamale, anytree, ekfsm
+Successfully installed anytree-2.12.1 click-8.1.8 crcmod-1.7 ekfsm-0.12.0 gpiod-2.3.0 hexdump-3.3 more-itertools-10.6.0 munch-4.0.0 pyyaml-6.0.2 six-1.17.0 smbus2-0.5.0 types-pyyaml-6.0.12.20241230 yamale-6.0.0
+```
+
+## Example Usage Scenario
+
+To use the library for a desired system, it must be configured in a system config yaml file:
+
+```yaml
+# Example config
+system_config:
+  name: "Simple System"
+  slots:
+    - name: SYSTEM_SLOT
+      slot_type: CPCI_S0_SYS
+      desired_hwmodule_type: EKF SC9-Toccata
+      desired_hwmodule_name: CPU
+      attributes:
+        is_master: true
+    - name: SLOT1
+      slot_type: CPCI_S0_PER
+      desired_hwmodule_type: EKF SRF-SUR
+      desired_hwmodule_name: SER
+      attributes:
+        slot_coding: 0x1
+```
+
+### API
+
+If you want to access the LEDs on the EKF SUR-UART, you can do the following:
+```python
+import ekfsm
+
+system = ekfsm.System("system.yaml")
+
+# alternative ways to get the SUR HwModule
+sur = system["SER"]    # by using the hwmodule name as key
+sur = system.ser       # by using the hwmodule name as attribute
+sur = system.slots["SLOT1"].hwmodule  # by using the slot name as key
+sur = system.slots.slot1.hwmodule  # by using the slot name as attribute
+
+# accessing the LED device
+sur.led_a.set(0,"purple")  # set the color of the LED to purple
+```
+
+For further infos on all API aspects, please see the [API Reference](https://ekfsm.readthedocs.io/en/main/reference/index.html).
+
+### CLI
+
+Upon activation of a venv provided with the ekfsm library, an entry point script `ekfsm-cli` is exported in the current shell.
+
+See `ekfsm-cli -h` for a help on the usage.
+
+
+## Resources
+
+[Documentation](https://ekfsm.readthedocs.io/en/main/)
+
+[Source Code](https://gitlab.ekf.com/libs/apis/ekfsm)
+
+[Developer Wiki](https://gitlab.ekf.com/libs/apis/ekfsm/-/wikis/home)