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

ekfsm/devices/generic.py

@@ -1,12 +1,14 @@
-from typing import TYPE_CHECKING
+from pathlib import Path
+from typing import TYPE_CHECKING, Callable
+
 from munch import Munch
+
 from ekfsm.core.components import SysTree
-from ekfsm.core.sysfs import SysFSDevice, sysfs_root
-from ekfsm.exceptions import ConfigError
-from pathlib import Path
+from ekfsm.core.sysfs import SysfsDevice, sysfs_root
+from ekfsm.exceptions import ConfigError, SysFSError, UnsupportedModeError
 
 if TYPE_CHECKING:
-    from ekfsm.core.components import HwModule
+    from ekfsm.core.components import HWModule
 
 
 class Device(SysTree):
@@ -26,26 +28,25 @@ class Device(SysTree):
         super().__init__(name, abort=abort)
         self.parent = parent
         self.device_args = kwargs
-        self.logger.debug(f"Device: {name} {kwargs}")
 
         if children:
             self.children = children
 
-        # needs to be set during init because root will be changed after tree is complete
-        self.hw_module = self.root
+        # Needs to be set during init because root will be changed after tree is complete
+        self.hw_module = self.root  # pyright: ignore[reportAttributeAccessIssue]
 
-        # i2c initialization
+        # I2C initialization
         if not hasattr(self, "sysfs_device") or self.sysfs_device is None:
-            self.sysfs_device: SysFSDevice | None = None
+            self.sysfs_device: SysfsDevice | None = None
 
-        # post init
+        # Post-initialization steps
         self._provides_attrs = kwargs.get("provides", {})
-        self.provides = self.__post_init__(Munch(self._provides_attrs))
+        self.provides = self.__post_init__(Munch(self._provides_attrs), abort)
 
-    def __post_init__(self, provides: Munch) -> Munch:
+    def __post_init__(self, provides: Munch, abort) -> Munch:
         for key, fields in provides.items():
             if isinstance(fields, dict):
-                provides[key] = self.__post_init__(Munch(fields))
+                provides[key] = self.__post_init__(Munch(fields), abort)
             elif isinstance(fields, list | str):
                 provides[key] = Munch()
 
@@ -53,59 +54,182 @@ class Device(SysTree):
                     fields = [fields]
 
                 while fields:
-                    iface = fields.pop()
-                    if isinstance(iface, dict):
-                        name = list(iface.keys())[0]
+                    interface = fields.pop()
+
+                    # TODO: Check if this is superfluous after schema validation
+                    if isinstance(interface, dict):
+                        name = list(interface.keys())[0]
+
                         try:
-                            func = list(iface.values())[0]
+                            func = list(interface.values())[0]
                         except IndexError:
                             raise ConfigError(
                                 f"{self.name}: No function given for interface {name}."
                             )
+
                         if not hasattr(self, func):
-                            raise NotImplementedError(
-                                f"{self.name}: Function {func} for interface {name} not implemented."
-                            )
+                            if abort:
+                                raise NotImplementedError(
+                                    f"{self.name}: Function {func} for interface {name} not implemented."
+                                )
+                            continue
+
                         provides[key].update({name: getattr(self, func)})
                     else:
-                        if not hasattr(self, iface):
-                            raise NotImplementedError(
-                                f"{self.name}: Function {iface} for provider {key} not implemented."
-                            )
-                        provides[key].update({iface: getattr(self, iface)})
+                        if not hasattr(self, interface):
+                            if abort:
+                                raise NotImplementedError(
+                                    f"{self.name}: Function {interface} for provider {key} not implemented."
+                                )
+                            continue
+
+                        provides[key].update({interface: getattr(self, interface)})
 
         return provides
 
+    @property
+    def sysfs(self):
+        """
+        Access sysfs device for device
+
+        Returns
+        -------
+        Sysfs device for device
+
+        Raises
+        ------
+        SysFSError
+            If the SysFSDevice does not exist
+        """
+        if self.sysfs_device is None:
+            raise SysFSError(f"No sysfs device attached to device {self.name}")
+
+        return self.sysfs_device
+
+    def read_attr(self, attr: str, mode: str = "utf", strip: bool = True):
+        match mode:
+            case "utf":
+                return self.sysfs.read_utf8(attr, strip)
+            case "bytes":
+                return self.sysfs.read_bytes(attr)
+            case "float":
+                return self.sysfs.read_float(attr)
+            case "int":
+                return self.sysfs.read_int(attr)
+            case "hex":
+                return self.sysfs.read_hex(attr)
+            case _:
+                raise UnsupportedModeError(f"Mode {mode} is not supported")
+
+    def read_attr_or_default(
+        self, attr: str, mode: str = "utf", strip: bool = True, default=None
+    ):
+        try:
+            return self.read_attr(attr, mode, strip)
+        except UnsupportedModeError:
+            raise
+        except Exception:
+            if default is not None:
+                return default
+            return None
+
+    def read_sysfs_bytes(self, attr) -> bytes:
+        if len(attr) <= 0:
+            raise SysFSError("sysfs attribute name too short")
+
+        return self.sysfs.read_bytes(attr)
+
     def read_sysfs_attr_bytes(self, attr: str) -> bytes | None:
-        if self.sysfs_device and len(attr) != 0:
+        """
+        Read a sysfs attribute as bytes.
+
+        Parameters
+        ----------
+        attr
+            The sysfs attribute to read.
+
+        Returns
+        -------
+        content: bytes
+            The contents of the sysfs attribute as bytes.
+        None:
+            If the sysfs device is not set or the attribute does not exist.
+        """
+        if (
+            self.sysfs_device is not None
+            and len(attr) != 0
+            and attr in [x.name for x in self.sysfs_device.attributes]
+        ):
             return self.sysfs_device.read_attr_bytes(attr)
         return None
 
     def read_sysfs_attr_utf8(self, attr: str) -> str | None:
-        if self.sysfs_device and len(attr) != 0:
-            return self.sysfs_device.read_attr_utf8(attr)
-        return None
+        """
+        Read a sysfs attribute as UTF-8 string.
+
+        Parameters
+        ----------
+        attr
+            The sysfs attribute to read.
+
+        Returns
+        -------
+        content: str
+            The contents of the sysfs attribute as UTF-8 string.
+        None:
+            If the sysfs device is not set or the attribute does not exist.
+        """
+        try:
+            return self.sysfs.read_utf8(attr)
+        except Exception:
+            return None
 
     def write_sysfs_attr(self, attr: str, data: str | bytes) -> None:
+        """
+        Write data to a sysfs attribute.
+
+        Parameters
+        ----------
+        attr
+            The sysfs attribute to write to.
+        data
+            The data to write to the sysfs attribute.
+        """
         if self.sysfs_device and len(attr) != 0:
             return self.sysfs_device.write_attr(attr, data)
         return None
 
     @property
-    def hw_module(self) -> "HwModule":
-        from ekfsm.core.components import HwModule
+    def hw_module(self) -> "HWModule":
+        """
+        Get or set the HWModule instance that this device belongs to.
+
+        Parameters
+        ----------
+        hw_module: optional
+            The HWModule instance to set.
+
+        Returns
+        -------
+        HWModule
+            The HWModule instance that this device belongs to.
+        None
+            If used as a setter.
+        """
+        from ekfsm.core.components import HWModule
 
-        if isinstance(self._hw_module, HwModule):
+        if isinstance(self._hw_module, HWModule):
             return self._hw_module
         else:
-            raise RuntimeError("Device is not a child of HwModule")
+            raise RuntimeError("Device is not a child of HWModule")
 
     @hw_module.setter
-    def hw_module(self, hw_module: "HwModule") -> None:
+    def hw_module(self, hw_module: "HWModule") -> None:
         self._hw_module = hw_module
 
     def get_i2c_chip_addr(self) -> int:
-        assert self.parent is not None
+        if self.parent is None:
+            raise ConfigError(f"{self.name}: Device must have a parent to get I2C chip address")
 
         chip_addr = self.device_args.get("addr")
         if chip_addr is None:
@@ -139,21 +263,27 @@ class Device(SysTree):
 
         return chip_addr
 
-    def get_i2c_sysfs_device(self, addr: int) -> SysFSDevice:
-        from ekfsm.core.components import HwModule
+    def get_i2c_sysfs_device(
+        self, addr: int, driver_required=True, find_driver: Callable | None = None
+    ) -> SysfsDevice:
+        from ekfsm.core.components import HWModule
 
         parent = self.parent
-        assert parent is not None
+        if parent is None:
+            raise ConfigError(f"{self.name}: Device must have a parent to get I2C sysfs device")
 
-        # if parent is a HwModule, we can get the i2c bus from the master device
-        if isinstance(parent, HwModule):
-            i2c_bus_path = self._master_i2c_bus()
+        # If parent is a HWModule, we can get the i2c bus from the master device
+        # XXX: Does this still hold true after refactoring?
+        if isinstance(parent, HWModule):
+            i2c_bus_path = self.__master_i2c_bus()
         else:
             # otherwise the parent must be a MuxChannel
             from ekfsm.devices.mux import MuxChannel
 
-            assert isinstance(parent, MuxChannel)
-            assert parent.sysfs_device is not None
+            if not isinstance(parent, MuxChannel):
+                raise ConfigError(f"{self.name}: Parent must be MuxChannel when not a HWModule")
+            if parent.sysfs_device is None:
+                raise ConfigError(f"{self.name}: Parent MuxChannel must have a sysfs_device")
             i2c_bus_path = parent.sysfs_device.path
 
         # search for device with addr
@@ -163,29 +293,34 @@ class Device(SysTree):
                 and not (entry / "new_device").exists()  # skip bus entries
                 and (entry / "name").exists()
             ):
-                # for PRP devices, address is contained in firmware_node/description
+                # PRP devices unfortunately do not readily expose the underlying I2C address of the device like
+                # regular I2C devices that follow the `${I2C_BUS}-${ADDR}` pattern. To address this issue, we
+                # initialize the ACPI _STR object for each PRP device with the necessary information, which is
+                # accessible in the `${DEVICE_SYSFS_PATH}/firmware_node/description` file.
                 if (entry / "firmware_node").exists() and (
                     entry / "firmware_node" / "description"
                 ).exists():
                     description = (
                         (entry / "firmware_node/description").read_text().strip()
                     )
-                    got_addr = int(description.split(" - ")[0], 16)
-                    if got_addr == addr:
-                        return SysFSDevice(entry)
+                    acpi_addr = int(description.split(" - ")[0], 16)
+
+                    if acpi_addr == addr:
+                        return SysfsDevice(entry, driver_required, find_driver)
 
-                # for non-PRP devices, address is contained in the directory name (e.g. 2-0018)
+                # For regular non-PRP devices, the address is contained in the directory name (e.g. 2-0018).
                 else:
-                    got_addr = int(entry.name.split("-")[1], 16)
-                    if got_addr == addr:
-                        return SysFSDevice(entry)
+                    acpi_addr = int(entry.name.split("-")[1], 16)
+
+                    if acpi_addr == addr:
+                        return SysfsDevice(entry, driver_required, find_driver)
 
         raise FileNotFoundError(
             f"Device with address 0x{addr:x} not found in {i2c_bus_path}"
         )
 
     @staticmethod
-    def _master_i2c_get_config(master: "HwModule") -> dict:
+    def __master_i2c_get_config(master: "HWModule") -> dict:
         if (
             master.config.get("bus_masters") is not None
             and master.config["bus_masters"].get("i2c") is not None
@@ -194,12 +329,13 @@ class Device(SysTree):
         else:
             raise ConfigError("Master definition incomplete")
 
-    def _master_i2c_bus(self) -> Path:
+    def __master_i2c_bus(self) -> Path:
         if self.hw_module.is_master:
             # we are the master
             master = self.hw_module
             master_key = "MASTER_LOCAL_DEFAULT"
             override_master_key = self.device_args.get("i2c_master", None)
+
             if override_master_key is not None:
                 master_key = override_master_key
         else:
@@ -212,18 +348,20 @@ class Device(SysTree):
             master = self.hw_module.slot.master
             master_key = self.hw_module.slot.slot_type.name
 
-        i2c_masters = self._master_i2c_get_config(master)
+        i2c_masters = self.__master_i2c_get_config(master)
 
         if i2c_masters.get(master_key) is not None:
             dir = sysfs_root() / Path(i2c_masters[master_key])
             bus_dirs = list(dir.glob("i2c-*"))
+
             if len(bus_dirs) == 1:
                 return bus_dirs[0]
             elif len(bus_dirs) > 1:
-                raise ConfigError(f"Multiple master i2c buses found for {master_key}")
-            raise ConfigError(f"No master i2c bus found for {master_key}")
+                raise ConfigError(f"Multiple master I2C buses found for {master_key}")
+
+            raise ConfigError(f"No master I2C bus found for {master_key}")
         else:
-            raise ConfigError(f"Master i2c bus not found for {master_key}")
+            raise ConfigError(f"Master I2C bus not found for {master_key}")
 
     def get_i2c_bus_number(self) -> int:
         """
@@ -240,11 +378,14 @@ class Device(SysTree):
             parent_path = self.parent.sysfs_device.path
         else:
             parent_path = self.sysfs_device.path.parent
+
         if parent_path.is_symlink():
             parent_path = parent_path.readlink()
+
         bus_number = parent_path.name.split("-")[1]
+
         return int(bus_number)
 
     def __repr__(self) -> str:
         sysfs_path = getattr(self.sysfs_device, "path", "")
-        return f"{self.name}; sysfs_path: {sysfs_path}"
+        return f"{self.name}; Path: {sysfs_path}"

ekfsm/devices/gpio.py

@@ -1,19 +1,19 @@
-from abc import ABC, abstractmethod
 import os
 import re
+from abc import ABC, abstractmethod
 from pathlib import Path
 
 import gpiod
-from gpiod.chip import LineSettings
 from gpiod.line import Direction, Value
+from gpiod.line_settings import LineSettings
 from more_itertools import first_true
 
 from ekfsm.core.components import SysTree
-from ekfsm.exceptions import GPIOError
+from ekfsm.exceptions import ConfigError, GPIOError
 from ekfsm.log import ekfsm_logger
 
-from .generic import Device
 from ..core.probe import ProbeableDevice
+from .generic import Device
 
 gpio_pat = re.compile(r"gpiochip\d+")
 
@@ -24,7 +24,13 @@ def get_gpio_major_minor(path: Path) -> tuple[int, int]:
             dev = d / "dev"
             if dev.exists():
                 content = dev.read_text().strip()
-                major, minor = map(int, content.split(":"))
+                try:
+                    major, minor = map(int, content.split(":"))
+                except Exception as e:
+                    raise GPIOError(
+                        GPIOError.ErrorType.NO_MAJOR_MINOR,
+                        f"No minor/major number found for GPIO device at {path}",
+                    ) from e
                 return major, minor
 
     raise GPIOError(
@@ -51,11 +57,12 @@ def find_gpio_dev_with_major_minor(major: int, minor: int) -> Path | None:
 
 
 class GPIO(Device):
-
     def __init__(
         self,
         name: str,
         parent: SysTree | None = None,
+        children: Device | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
@@ -63,6 +70,7 @@ class GPIO(Device):
             name,
             parent,
             None,
+            abort,
             *args,
             **kwargs,
         )
@@ -70,23 +78,18 @@ class GPIO(Device):
         major, minor = self._find_gpio_dev(parent, *args, **kwargs)
         self.gpio = find_gpio_dev_with_major_minor(major, minor)
 
-        assert self.gpio is not None
+        if self.gpio is None:
+            raise GPIOError(GPIOError.ErrorType.NO_MATCHING_DEVICE, f"{self.name}: GPIO device not found")
         match = re.search(r"\d+", self.gpio.name)
-        if match:
-            self.number: int = int(match.group().strip())
-        else:
-            raise GPIOError(
-                GPIOError.ErrorType.NO_MATCHING_DEVICE, "Failed to find matching device"
-            )
+
+        if not match:
+            raise GPIOError(GPIOError.ErrorType.NO_MATCHING_DEVICE, "Failed to find matching device")
+
+        self.number: int = int(match.group().strip())
 
         self.init_dev()
 
-    def _find_gpio_dev(
-        self,
-        parent: SysTree | None = None,
-        *args,
-        **kwargs,
-    ) -> tuple[int, int]:
+    def _find_gpio_dev(self, parent: SysTree | None = None, *args, **kwargs) -> tuple[int, int]:
         self.addr = self.get_i2c_chip_addr()
         self.logger.debug(f"GPIO: {self.addr}")
         self.sysfs_device = self.get_i2c_sysfs_device(self.addr)
@@ -97,9 +100,13 @@ class GPIO(Device):
             try:
                 self.dev = gpiod.Chip(str(self.gpio))
                 self.initialized = True
+                return
             except FileNotFoundError:
+                self.initialized = False
                 raise FileNotFoundError(f"{self.gpio} does not exist")
 
+        self.initialized = False
+
     def num_lines(self) -> int:
         """
         Get number of GPIO lines available on the device.
@@ -153,9 +160,7 @@ class GPIO(Device):
                 default=None,
             )
         ) is not None:
-            raise GPIOError(
-                GPIOError.ErrorType.INVALID_PIN, f"GPIO {invalid_pin} is invalid."
-            )
+            raise GPIOError(GPIOError.ErrorType.INVALID_PIN, f"GPIO {invalid_pin} is invalid.")
 
     def set_direction(self, pin: int, direction: bool) -> None:
         """
@@ -187,10 +192,12 @@ class GPIOExpander(GPIO):
         self,
         name: str,
         parent: SysTree | None,
+        children: Device | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
-        super().__init__(name, parent, None, *args, **kwargs)
+        super().__init__(name, parent, None, abort, *args, **kwargs)
 
     def __str__(self) -> str:
         return (
@@ -204,15 +211,18 @@ class EKFIdentificationIOExpander(GPIOExpander, ProbeableDevice):
         self,
         name: str,
         parent: SysTree | None,
+        children: Device | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
-        super().__init__(name, parent, None, *args, **kwargs)
+        super().__init__(name, parent, None, abort, *args, **kwargs)
 
     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")
         id, _ = self.read_board_id_rev()
         self.logger.debug(f"Probing EKFIdentificationIOExpander: {id}")
 
@@ -245,7 +255,7 @@ class EKFIdentificationIOExpander(GPIOExpander, ProbeableDevice):
         )
 
     def revision(self) -> str:
-        id, rev = self.read_board_id_rev()
+        _, rev = self.read_board_id_rev()
         return str(rev)
 
     def read_id_gpio_inputs(self) -> int:

ekfsm/devices/iio.py

@@ -1,7 +1,9 @@
-from .generic import SysFSDevice
+from ekfsm.exceptions import ConversionError, SysFSError
 
+from .generic import SysfsDevice
 
-def iio_get_in_value(dev: SysFSDevice, attrset: str) -> float:
+
+def iio_get_in_value(dev: SysfsDevice, attrset: str) -> float:
     """
     Calculate a value from an IIO in_* attribute set, using the _raw, _scale and _offset attributes (if present).
     Typical name of attrset are "in_temp" or "in_voltage0".
@@ -26,33 +28,15 @@ def iio_get_in_value(dev: SysFSDevice, attrset: str) -> float:
         if the neiter _input nor _raw attribute is found
 
     """
-    # check if _input exists
-    try:
-        content = dev.read_attr_utf8(f"{attrset}_input")
-        return float(content)
-    except StopIteration:
-        pass
-
-    # check if _raw exists
     try:
-        content = dev.read_attr_utf8(f"{attrset}_raw")
-    except StopIteration:
-        raise FileNotFoundError(f"{attrset}_raw not found")
-
-    raw = float(content)
-
-    # use offset if present
-    try:
-        content = dev.read_attr_utf8(f"{attrset}_offset")
-        raw += float(content)
-    except StopIteration:
-        pass
-
-    # use scale if present
-    try:
-        content = dev.read_attr_utf8(f"{attrset}_scale")
-        raw *= float(content)
-    except StopIteration:
-        pass
-
-    return raw
+        content = dev.read_float(f"{attrset}_input")
+    except (SysFSError, ConversionError):
+        try:
+            raw = dev.read_float(f"{attrset}_raw")
+            offset = dev.read_float(f"{attrset}_offset")
+            scale = dev.read_float(f"{attrset}_scale")
+            content = (raw + offset) * scale
+        except (SysFSError, ConversionError) as e:
+            raise FileNotFoundError from e
+
+    return content

ekfsm/devices/iio_thermal_humidity.py

@@ -1,10 +1,8 @@
-from pathlib import Path
-
 from ekfsm.core.components import SysTree
 from ekfsm.log import ekfsm_logger
+from ekfsm.utils import next_or_raise
 
-from ..core.sysfs import SysFSDevice
-
+from ..core.sysfs import list_sysfs_attributes
 from .generic import Device
 from .iio import iio_get_in_value
 
@@ -13,6 +11,14 @@ class IIOThermalHumidity(Device):
     """
     Device for IIO thermal and/or humidity sensors.
 
+    Parameters
+    ----------
+    name
+        The name of the device.
+    parent
+        The parent device of the IIOThermalHumidity device. If None, no parent is created.
+    children
+        The children of the IIOThermalHumidity device. If None, no children are created.
     """
 
     def __init__(
@@ -20,22 +26,23 @@ class IIOThermalHumidity(Device):
         name: str,
         parent: SysTree | None = None,
         children: list[Device] | None = None,
+        abort: bool = False,
         *args,
         **kwargs,
     ):
         self.logger = ekfsm_logger("IIOThermalHumidity:" + name)
-        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)
+        self.sysfs_device = self.get_i2c_sysfs_device(self.addr, False)
+
+        # TODO: We can just search the attributes directly
+        iio_dir = self.sysfs.path.glob("iio:device*")
+        attrs = next_or_raise(iio_dir, FileNotFoundError("IIO entry not found"))
 
-        dir = list(Path(self.sysfs_device.path).glob("iio:device*"))
-        if len(dir) == 0:
-            raise FileNotFoundError("iio entry not found")
-        self.iio_sysfs = SysFSDevice(dir[0])
-        self.logger.debug(f"iio: {self.iio_sysfs.path}")
+        self.sysfs_device.extend_attributes(list_sysfs_attributes(attrs))
 
     def temperature(self) -> float:
-        return iio_get_in_value(self.iio_sysfs, "in_temp") / 1000.0
+        return iio_get_in_value(self.sysfs, "in_temp") / 1000.0
 
     def humidity(self) -> float:
-        return iio_get_in_value(self.iio_sysfs, "in_humidityrelative") / 1000.0
+        return iio_get_in_value(self.sysfs, "in_humidityrelative") / 1000.0