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

ekfsm/devices/ekf_ccu_uc.py

@@ -1,12 +1,15 @@
-from .generic import Device
-from smbus2 import SMBus
+import struct
 from enum import Enum
-from typing import Tuple
+from typing import Any, Tuple
+
+from smbus2 import SMBus
+
 from ekfsm.core.components import SysTree
+
 from ..exceptions import AcquisitionError
 from ..lock import Locker
+from .generic import Device
 from .imu import ImuSample
-import struct
 
 
 class CcuCommands(Enum):
@@ -37,10 +40,13 @@ class EKFCcuUc(Device):
         self,
         name: str,
         parent: SysTree | None,
+        children: list["Device"] | None = None,
+        abort: bool = False,
+        debug: Any = None,  # XXX: What is this?
         *args,
         **kwargs,
     ):
-        super().__init__(name, parent, None, *args, **kwargs)
+        super().__init__(name, parent, None, abort, *args, **kwargs)
         self._i2c_addr = self.get_i2c_chip_addr()
         self._i2c_bus = self.get_i2c_bus_number()
         self._smbus = SMBus(self._i2c_bus)
@@ -54,7 +60,10 @@ class EKFCcuUc(Device):
     def temperature(self) -> float:
         """
         Get the temperature from the CCU thermal/humidity sensor.
-        The temperature is read once per second.
+
+        Note
+        ----
+        The CCU reads the temperature once per second.
 
         Returns
         -------
@@ -66,10 +75,7 @@ class EKFCcuUc(Device):
         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
-        )
+        return self._get_signed_word_data(CcuCommands.CCU_TEMPERATURE.value, "temperature") / 10.0
 
     def humidity(self) -> float:
         """
@@ -86,10 +92,7 @@ class EKFCcuUc(Device):
         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
-        )
+        return self._get_signed_word_data(CcuCommands.CCU_HUMIDITY.value, "humidity") / 10.0
 
     def vin_voltage(self) -> float:
         """
@@ -106,15 +109,14 @@ class EKFCcuUc(Device):
         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
-        )
+        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}")
+            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]:
@@ -128,9 +130,16 @@ class EKFCcuUc(Device):
 
         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:
+        desired: float
+            The desired speed.
+        actual: float
+            The actual speed.
+        diag: int
+            The diagnostic value.
+
+        Note
+        ----
+        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
@@ -161,9 +170,7 @@ class EKFCcuUc(Device):
         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)
-        )
+        self._smbus.write_block_data(self._i2c_addr, CcuCommands.PUSH_TEMPERATURE.value, list(data))
 
     def imu_sample(self) -> Tuple[ImuSample | None, bool]:
         """
@@ -184,19 +191,17 @@ class EKFCcuUc(Device):
 
         Returns
         -------
-        Tuple[ImuSample | None, bool]
-            The IMU sample (or None) and a flag indicating if more samples are available in the FIFO.
+        imu_data: ImuSample | None
+            The IMU sample, or None if no sample is available.
+        more_samples: bool
+            True if more samples are available in the FIFO, False otherwise.
         """
         more_samples = False
-        _data = self._smbus.read_block_data(
-            self._i2c_addr, CcuCommands.IMU_SAMPLES.value
-        )
+        _data = self._smbus.read_block_data(self._i2c_addr, CcuCommands.IMU_SAMPLES.value)
         data = bytes(_data)
         if len(data) < 14:
             return None, False  # No data available
-        diag, fsr, acc_x, acc_y, acc_z, gyro_x, gyro_y, gyro_z = struct.unpack(
-            "<BBhhhhhh", data
-        )
+        diag, fsr, acc_x, acc_y, acc_z, gyro_x, gyro_y, gyro_z = struct.unpack("<BBhhhhhh", data)
         imu_data = ImuSample(
             [
                 self._scale_imu_accel(acc_x, fsr),
@@ -257,18 +262,16 @@ class EKFCcuUc(Device):
 
         Returns
         -------
-        Tuple[str, str]
-            The firmware title and version.
+        title: str
+            The firmware title.
+        version: str
+            The firmware version.
         """
-        title = bytes(
-            self._smbus.read_block_data(
-                self._i2c_addr, CcuCommands.IDENTIFY_FIRMWARE_TITLE.value
-            )
-        ).decode("utf-8")
+        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
-            )
+            self._smbus.read_block_data(self._i2c_addr, CcuCommands.IDENTIFY_FIRMWARE_VERSION.value)
         ).decode("utf-8")
         return title, version
 
@@ -293,27 +296,37 @@ class EKFCcuUc(Device):
         progress_callback
             A callback function that is called with the current progress in bytes.
 
+        Example
+        -------
+        >>> from ekfsm.devices import EkfCcuUc
+        >>> ccu = EkfCcuUc("ccu")
+        >>> firmware = open("fw-ccu-1.0.0.bin", "rb").read()
+        >>> # Load firmware with progress callback
+        >>> ccu.load_firmware(firmware, progress_callback=lambda x: print(f"Progress: {x} bytes"))
         """
         with Locker(self.name + "-load_firmware").lock():
             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)
-        )
+
+        self._smbus.write_block_data(self._i2c_addr, CcuCommands.LOAD_FIRMWARE_CHUNK.value, list(data))
 
     def get_parameterset(self) -> str:
         """
@@ -371,6 +384,7 @@ class EKFCcuUc(Device):
         with Locker(self.name + "-parameterset").lock():
             json = b""
             begin = True
+
             while True:
                 chunk = self._get_parameterset_chunk(begin)
                 if len(chunk) < 32:
@@ -380,16 +394,13 @@ class EKFCcuUc(Device):
                     chunk = chunk[:-1]
                 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
-            ),
+            (CcuCommands.GET_PARAMETERSET_BEGIN.value if begin else CcuCommands.GET_PARAMETERSET_FOLLOW.value),
         )
         return bytes(data)
 
@@ -412,6 +423,8 @@ class EKFCcuUc(Device):
         This would load a parameterset with just one parameter, the default fan speed. All other parameters will
         be set to their default values.
 
+        Important
+        ---------
         In order to apply the parameterset, the CCU must be restarted.
 
         Parameters
@@ -419,11 +432,20 @@ class EKFCcuUc(Device):
         _cfg
             The parameterset in JSON format.
 
+        Example
+        -------
+        >>> from ekfsm.devices import EkfCcuUc
+        >>> ccu = EkfCcuUc("ccu")
+        >>> # Load parameterset
+        >>> ccu.load_parameterset('{"version": "1.0.0", "parameters": {"fan-defrpm": "6000"}}')
+        >>> # Restart CCU to apply parameterset
+        >>> ccu.restart()
         """
         with Locker(self.name + "-parameterset").lock():
             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)
@@ -433,11 +455,11 @@ class EKFCcuUc(Device):
     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)
-        )
+
+        self._smbus.write_block_data(self._i2c_addr, CcuCommands.LOAD_PARAMETERSET.value, list(data))
 
     def restart(self) -> None:
         """

ekfsm/devices/ekf_sur_led.py

@@ -1,5 +1,7 @@
-from .gpio import GPIOExpander
 from ekfsm.core.components import SysTree
+from ekfsm.devices.generic import Device
+
+from .gpio import GPIOExpander
 
 
 class EKFSurLed(GPIOExpander):
@@ -11,10 +13,12 @@ class EKFSurLed(GPIOExpander):
         self,
         name: str,
         parent: SysTree | None,
+        children: list["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 (