ekfsm 0.11.0b1.post3__py3-none-any.whl

ekfsm/devices/ekf_ccu_uc.py

@@ -0,0 +1,390 @@
+from .generic import Device
+from smbus2 import SMBus
+from enum import Enum
+from typing import Tuple
+from ekfsm.core.components import SystemComponent
+from ..exceptions import AcquisitionError
+import struct
+
+
+class CcuCommands(Enum):
+    NOP = 0x01
+    IMU_SAMPLES = 0x10
+    FAN_STATUS = 0x11
+    VIN_VOLTAGE = 0x12
+    CCU_TEMPERATURE = 0x13
+    CCU_HUMIDITY = 0x14
+    PUSH_TEMPERATURE = 0x15
+    SW_SHUTDOWN = 0x16
+    WD_TRIGGER = 0x17
+    IDENTIFY_FIRMWARE_TITLE = 0x80
+    IDENTIFY_FIRMWARE_VERSION = 0x81
+    LOAD_FIRMWARE_CHUNK = 0x82
+    LOAD_PARAMETERSET = 0x83
+    GET_PARAMETERSET_BEGIN = 0x84
+    GET_PARAMETERSET_FOLLOW = 0x85
+    RESTART = 0x8F
+
+
+class EKFCcuUc(Device):
+    """
+    A class to communicate with I2C microcontroller on the EKF CCU.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: SystemComponent | None,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(name, parent, None, *args, **kwargs)
+        self._i2c_addr = self.get_i2c_chip_addr()
+        self._i2c_bus = self.get_i2c_bus_number()
+        self._smbus = SMBus(self._i2c_bus)
+
+    def __str__(self) -> str:
+        return (
+            f"EKFCCU - I2C Bus/Address: {self._i2c_bus}/{hex(self._i2c_addr)}; "
+            f"sysfs_path: {self.sysfs_device.path if self.sysfs_device else ''}"
+        )
+
+    def temperature(self) -> float:
+        """
+        Get the temperature from the CCU thermal/humidity sensor.
+        The temperature is read once per second.
+
+        Returns
+        -------
+        float
+            The temperature in degrees Celsius.
+
+        Raises
+        ------
+        AcquisitionError
+            If the temperature cannot be read, for example, because the sensor is not working.
+        """
+        return (
+            self._get_signed_word_data(CcuCommands.CCU_TEMPERATURE.value, "temperature")
+            / 10.0
+        )
+
+    def humidity(self) -> float:
+        """
+        Get the relative humidity from the CCU thermal/humidity sensor.
+        The humidity is read once per second.
+
+        Returns
+        -------
+        float
+            The relative humidity in percent.
+
+        Raises
+        ------
+        AcquisitionError
+            If the humidity cannot be read, for example, because the sensor is not working.
+        """
+        return (
+            self._get_signed_word_data(CcuCommands.CCU_HUMIDITY.value, "humidity")
+            / 10.0
+        )
+
+    def vin_voltage(self) -> float:
+        """
+        Get the system input voltage from the CCU (the pimary voltage of the PSU).
+        The voltage is read every 100ms.
+
+        Returns
+        -------
+        float
+            The system input voltage in volts.
+
+        Raises
+        ------
+        AcquisitionError
+            If the voltage cannot be read, for example, because the ADC is not working.
+        """
+        return (
+            self._get_signed_word_data(CcuCommands.VIN_VOLTAGE.value, "VIN voltage")
+            / 10.0
+        )
+
+    def _get_signed_word_data(self, cmd: int, what: str) -> int:
+        v = self._smbus.read_word_data(self._i2c_addr, cmd)
+        if v == 0x8000:
+            raise AcquisitionError(f"cannot read {what}")
+        return struct.unpack("<h", struct.pack("<H", v))[0]
+
+    def fan_status(self, fan: int) -> Tuple[float, float, int]:
+        """
+        Get the status of a fan.
+
+        Parameters
+        ----------
+        fan
+            The fan number (0-2).
+
+        Returns
+        -------
+        Tuple[float, float, int]
+            The desired speed, the actual speed, and the diagnostic value.
+            The diagnostic value is a bitfield with the following meaning:
+
+            - bit 0: 0 = fan status is invalid, 1 = fan status is valid
+            - bit 1: 0 = no error detected, 1 = fan is stuck
+        """
+        data = self._smbus.read_block_data(self._i2c_addr, CcuCommands.FAN_STATUS.value)
+        _data = bytes(data)
+        desired, actual, diag = struct.unpack("<HHB", _data[fan * 5 : fan * 5 + 5])
+        return desired, actual, diag
+
+    def push_temperature(self, fan: int, temp: float) -> None:
+        """
+        Tell FAN controller the external temperature, usually the CPU temperature.
+
+        Parameters
+        ----------
+        fan
+            The fan number (0-2), or -1 to set the external temperature of all fans.
+
+        temp
+            The external temperature in degrees Celsius.
+
+        Important
+        ---------
+        If push_temperature is no more called for a certain time (configurable with `fan-push-tout` parameter),
+        the fan controller will fallback to it's default fan speed (configurable with the `fan-defrpm` parameter).
+
+        """
+        if fan == -1:
+            fan = 0xFF
+        data = struct.pack("<Bh", fan, int(temp * 10))
+        self._smbus.write_block_data(
+            self._i2c_addr, CcuCommands.PUSH_TEMPERATURE.value, list(data)
+        )
+
+    def sw_shutdown(self) -> None:
+        """
+        Tell CCU that the system is going to shutdown.
+        This cause the CCU's system state controller to enter shutdown state and power off the system after a certain time
+        (parameter `shutdn-delay`).
+
+        """
+        self._smbus.write_byte(self._i2c_addr, CcuCommands.SW_SHUTDOWN.value)
+
+    def wd_trigger(self) -> None:
+        """
+        Trigger the CCU's application watchdog.
+        This will reset the watchdog timer.
+
+        The CCU watchdog is only enabled when the parameter `wd-tout` is set to a value greater than 0. Triggering
+        the watchdog when the timeout is 0 will have no effect.
+
+        If the watchdog is not reset within the timeout, the CCU will power cycle the system.
+        """
+        self._smbus.write_byte(self._i2c_addr, CcuCommands.WD_TRIGGER.value)
+
+    #
+    # Management commands
+    #
+    def identify_firmware(self) -> Tuple[str, str]:
+        """
+        Get the firmware title and version of the CCU.
+
+        Returns
+        -------
+        Tuple[str, str]
+            The firmware title and version.
+        """
+        title = bytes(
+            self._smbus.read_block_data(
+                self._i2c_addr, CcuCommands.IDENTIFY_FIRMWARE_TITLE.value
+            )
+        ).decode("utf-8")
+        version = bytes(
+            self._smbus.read_block_data(
+                self._i2c_addr, CcuCommands.IDENTIFY_FIRMWARE_VERSION.value
+            )
+        ).decode("utf-8")
+        return title, version
+
+    def load_firmware(self, firmware: bytes, progress_callback=None) -> None:
+        """
+        Load firmware into the CCU.
+
+        The firmware must be the binary firmware file containing the application partition,
+        typically named `fw-ccu-mm-default.bin`,
+        where `mm` is the major version of the CCU hardware.
+
+        The download can take several minutes, that is why a progress callback can be provided.
+
+        When the download is complete and successful, the CCU will restart. To check if the firmware was loaded successfully,
+        call :meth:`identify_firmware()` after the restart.
+
+        Parameters
+        ----------
+        firmware
+            The firmware binary data.
+
+        progress_callback
+            A callback function that is called with the current progress in bytes.
+
+        Warning
+        ---------
+        Do not call this method at the same time from multiple threads or processes.
+
+        """
+        offset = 0
+        max_chunk_len = 28
+        while len(firmware) > 0:
+            chunk, firmware = firmware[:max_chunk_len], firmware[max_chunk_len:]
+            self._load_firmware_chunk(offset, len(firmware) == 0, chunk)
+            offset += len(chunk)
+            if len(firmware) != 0:
+                self._nop()
+            if progress_callback is not None:
+                progress_callback(offset)
+
+    def _load_firmware_chunk(self, offset: int, is_last: bool, data: bytes) -> None:
+        if is_last:
+            offset |= 0x80000000
+        hdr = struct.pack("<I", offset)
+        data = hdr + data
+        self._smbus.write_block_data(
+            self._i2c_addr, CcuCommands.LOAD_FIRMWARE_CHUNK.value, list(data)
+        )
+
+    def get_parameterset(self) -> str:
+        """
+        Get the CCU parameterset in JSON format.
+
+        A typical parameterset looks like this:
+
+        .. code-block:: json
+
+            {
+                "version":      "factory",
+                "parameters":   {
+                        "num-fans":     "2",
+                        "fan-temp2rpm": "25:2800;50:5000;100:6700",
+                        "fan-rpm2duty": "2800:55;5000:88;6700:100",
+                        "fan-defrpm":   "5500",
+                        "fan-ppr":      "2",
+                        "fan-push-tout":        "4000",
+                        "pon-min-temp": "-25",
+                        "pon-max-temp": "70",
+                        "shutdn-delay": "120",
+                        "wd-tout":      "0",
+                        "pwrcycle-time":        "10"
+                },
+                "unsupported_parameters":       [],
+                "missing_parameters":   ["num-fans", "fan-temp2rpm", "fan-rpm2duty", "fan-defrpm", "fan-ppr", \
+                    "fan-push-tout", "pon-min-temp", "pon-max-temp", "shutdn-delay", "wd-tout", "pwrcycle-time"],
+                "invalid_parameters":   [],
+                "reboot_required":      false
+            }
+
+        `version` is the version of the parameterset. If no parameterset has been loaded by the user, the version is `factory`,
+        otherwise it is the version of the loaded parameterset.
+
+        `parameters` contains the current values of all parameters of the parameterset.
+
+        `unsupported_parameters` contains the names of parameters that might have been downloaded, but
+        are not supported by the CCU firmware.
+
+        `missing_parameters` contains the names of parameters that have not been downloaded yet. Those parameters will
+        have their default values.
+
+        `invalid_parameters` contains the names of parameters that have been downloaded, but have invalid values.
+        Those parameters will have their default values.
+
+        `reboot_required` is a flag that indicates if a reboot is required to apply the parameterset.
+
+
+        Returns
+        -------
+        str
+            The parameterset in JSON format.
+
+        Warning
+        ---------
+        Do not call this method at the same time from multiple threads or processes.
+        """
+        json = b""
+        begin = True
+        while True:
+            chunk = self._get_parameterset_chunk(begin)
+            if len(chunk) < 32:
+                break
+            json += chunk
+            begin = False
+        return json.decode("utf-8")
+
+    def _get_parameterset_chunk(self, begin: bool) -> bytes:
+        data = self._smbus.read_block_data(
+            self._i2c_addr,
+            (
+                CcuCommands.GET_PARAMETERSET_BEGIN.value
+                if begin
+                else CcuCommands.GET_PARAMETERSET_FOLLOW.value
+            ),
+        )
+        return bytes(data)
+
+    def load_parameterset(self, _cfg: str) -> None:
+        """
+        Load a parameterset into the CCU.
+
+        The parameterset must be a JSON string containing the parameterset, for example:
+
+        .. code-block:: json
+
+            {
+                "version": "1.0.0",
+                "parameters":   {
+                    "fan-defrpm": "6000"
+                }
+            }
+
+
+        This would load a parameterset with just one parameter, the default fan speed. All other parameters will
+        be set to their default values.
+
+        In order to apply the parameterset, the CCU must be restarted.
+
+        Parameters
+        ----------
+        _cfg
+            The parameterset in JSON format.
+
+        Warning
+        ---------
+        Do not call this method at the same time from multiple threads or processes.
+
+        """
+        cfg = _cfg.encode("utf-8")
+        offset = 0
+        max_chunk_len = 28
+        while len(cfg) > 0:
+            chunk, cfg = cfg[:max_chunk_len], cfg[max_chunk_len:]
+            self._load_parameterset_chunk(offset, len(cfg) == 0, chunk)
+            offset += len(chunk)
+            self._nop()
+
+    def _load_parameterset_chunk(self, offset: int, is_last: bool, data: bytes) -> None:
+        if is_last:
+            offset |= 0x80000000
+        hdr = struct.pack("<I", offset)
+        data = hdr + data
+        self._smbus.write_block_data(
+            self._i2c_addr, CcuCommands.LOAD_PARAMETERSET.value, list(data)
+        )
+
+    def restart(self) -> None:
+        """
+        Restart the CCU.
+        """
+        self._smbus.write_byte(self._i2c_addr, CcuCommands.RESTART.value)
+
+    def _nop(self) -> None:
+        self._smbus.read_word_data(self._i2c_addr, CcuCommands.NOP.value)

ekfsm/devices/ekf_sur_led.py

@@ -0,0 +1,67 @@
+from .gpio import GPIOExpander
+from ekfsm.core.components import SystemComponent
+
+
+class EKFSurLed(GPIOExpander):
+    """
+    A class to represent the EKF-SUR-LED devices.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: SystemComponent | None,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(name, parent, None, *args, **kwargs)
+
+    def __str__(self) -> str:
+        return (
+            f"EKFSurLed - GPIO Number: {self.number}; "
+            f"sysfs_path: {self.sysfs_device.path if self.sysfs_device else ''}"
+        )
+
+    def set(self, led: int, color: str):
+        """
+        Set the color of a LED.
+
+        Parameters
+        ----------
+        led : int
+            The LED number (0 or 1).
+        color : str
+            The color of the LED.
+            Possible values: "off", "red", "blue", "green", "yellow", "purple", "cyan", "white"
+        """
+        # 3-color LEDs,
+        # 0: Red
+        # 1: Blue
+        # 2: Green
+
+        if color == "off":
+            state = [False, False, False]
+        elif color == "red":
+            state = [True, False, False]
+        elif color == "blue":
+            state = [False, True, False]
+        elif color == "green":
+            state = [False, False, True]
+        elif color == "yellow":
+            state = [True, True, False]
+        elif color == "purple":
+            state = [True, False, True]
+        elif color == "cyan":
+            state = [False, True, True]
+        elif color == "white":
+            state = [True, True, True]
+        else:
+            raise ValueError(f"Invalid color: {color}")
+
+        if led < 0 or led > 1:
+            raise ValueError(f"Invalid led number: {led}")
+
+        for i in range(3):
+            self.set_direction(i + 4 * led, True)
+            # Active low
+            self.set_pin(i + 4 * led, False if state[i] else True)

ekfsm/devices/generic.py

@@ -0,0 +1,245 @@
+from typing import TYPE_CHECKING
+from munch import Munch
+from ekfsm.core.components import SystemComponent
+from ekfsm.core.sysfs import SysFSDevice, sysfs_root
+from ekfsm.exceptions import ConfigError
+from pathlib import Path
+
+if TYPE_CHECKING:
+    from ekfsm.core.components import HwModule
+
+
+class Device(SystemComponent):
+    """
+    A generic device.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        parent: SystemComponent | None = None,
+        children: list["Device"] | None = None,
+        *args,
+        **kwargs
+    ):
+        super().__init__(name)
+        self.parent = parent
+        self.device_args = kwargs
+        self.logger.debug(f"Device: {name} {kwargs}")
+
+        if children:
+            self.children = children
+
+        if not hasattr(self, "sysfs_device"):
+            self.sysfs_device: SysFSDevice | None = None
+
+        self._provides_attrs = kwargs.get("provides", {})
+
+        self.provides = self.__post_init__(Munch(self._provides_attrs))
+
+    def __post_init__(self, provides: Munch) -> Munch:
+        return self.__init_dynamic_attrs__(provides)
+
+    def __init_dynamic_attrs__(self, provides: Munch) -> Munch:
+
+        for key, fields in provides.items():
+            if isinstance(fields, dict):
+                provides[key] = self.__init_dynamic_attrs__(Munch(fields))
+            elif isinstance(fields, list | str):
+                provides[key] = Munch()
+
+                if isinstance(fields, str):
+                    fields = [fields]
+
+                while fields:
+                    iface = fields.pop()
+                    if isinstance(iface, dict):
+                        name = list(iface.keys())[0]
+                        try:
+                            func = list(iface.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."
+                            )
+                        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)})
+
+        return provides
+
+    def read_sysfs_attr_bytes(self, attr: str) -> bytes | None:
+        if self.sysfs_device and len(attr) != 0:
+            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
+
+    def write_sysfs_attr(self, attr: str, data: str | bytes) -> None:
+        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
+
+        if isinstance(self.root, HwModule):
+            return self.root
+        else:
+            raise RuntimeError("Device is not a child of HwModule")
+
+    def get_i2c_chip_addr(self) -> int:
+        assert self.parent is not None
+
+        chip_addr = self.device_args.get("addr")
+        if chip_addr is None:
+            raise ConfigError(
+                f"{self.name}: Chip address not provided in board definition"
+            )
+
+        if not hasattr(self.parent, "sysfs_device") or self.parent.sysfs_device is None:
+            # our device is the top level device of the slot
+            # compute chip address from board yaml and slot attributes
+            slot_attributes = self.hw_module.slot.attributes
+
+            if slot_attributes is None:
+                raise ConfigError(
+                    f"{self.name}: Slot attributes not provided in system configuration"
+                )
+
+            if not self.hw_module.is_master:
+                # slot coding is only used for non-master devices
+                if not hasattr(slot_attributes, "slot_coding"):
+                    raise ConfigError(
+                        f"{self.name}: Slot coding not provided in slot attributes"
+                    )
+
+                slot_coding_mask = 0xFF
+
+                if hasattr(slot_attributes, "slot_coding_mask"):
+                    slot_coding_mask = slot_attributes.slot_coding_mask
+
+                chip_addr |= slot_attributes.slot_coding & slot_coding_mask
+
+        return chip_addr
+
+    def get_i2c_sysfs_device(self, addr: int) -> SysFSDevice:
+        from ekfsm.core.components import HwModule
+
+        parent = self.parent
+        assert parent is not None
+
+        # 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()
+        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
+            i2c_bus_path = parent.sysfs_device.path
+
+        # search for device with addr
+        for entry in i2c_bus_path.iterdir():
+            if (
+                entry.is_dir()
+                and not (entry / "new_device").exists()  # skip bus entries
+                and (entry / "name").exists()
+            ):
+                # for PRP devices, address is contained in firmware_node/description
+                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)
+
+                # for non-PRP devices, 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)
+
+        raise FileNotFoundError(
+            f"Device with address 0x{addr:x} not found in {i2c_bus_path}"
+        )
+
+    @staticmethod
+    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
+        ):
+            return master.config["bus_masters"]["i2c"]
+        else:
+            raise ConfigError("Master definition incomplete")
+
+    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:
+            # another board is the master
+            if self.hw_module.slot.master is None:
+                raise ConfigError(
+                    f"{self.name}: Master board not found in slot attributes"
+                )
+
+            master = self.hw_module.slot.master
+            master_key = self.hw_module.slot.slot_type.name
+
+        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}")
+        else:
+            raise ConfigError(f"Master i2c bus not found for {master_key}")
+
+    def get_i2c_bus_number(self) -> int:
+        """
+        Get the I2C bus number of the device. Works for devices that do not have a sysfs_device attribute.
+        """
+        from ekfsm.devices.mux import MuxChannel
+
+        if isinstance(self, MuxChannel):
+            raise RuntimeError(f"{self.name}: MuxChannel does not have a bus number")
+
+        if self.sysfs_device is None:
+            if self.parent is None:
+                raise RuntimeError(f"{self.name}: Must have a parent to get bus number")
+            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}"