shepherd-core 2023.12.1__py3-none-any.whl → 2024.4.2__py3-none-any.whl

shepherd_core/data_models/testbed/observer.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from datetime import datetime
 from typing import Optional
 
@@ -24,9 +26,9 @@ MACStr = Annotated[
 
 
 class Observer(ShpModel, title="Shepherd-Sheep"):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: SafeStr
     comment: Optional[SafeStr] = None
@@ -63,7 +65,8 @@ class Observer(ShpModel, title="Shepherd-Sheep"):
         has_cape = self.cape is not None
         has_target = (self.target_a is not None) or (self.target_b is not None)
         if not has_cape and has_target:
-            raise ValueError(f"Observer '{self.name}' is faulty -> has targets but no cape")
+            msg = f"Observer '{self.name}' is faulty -> has targets but no cape"
+            raise ValueError(msg)
         return self
 
     def has_target(self, target_id: int) -> bool:
@@ -79,7 +82,8 @@ class Observer(ShpModel, title="Shepherd-Sheep"):
                 return TargetPort.A
             if self.target_b is not None and target_id == self.target_b.id:
                 return TargetPort.B
-        raise ValueError(f"Target-ID {target_id} was not found in Observer '{self.name}'")
+        msg = f"Target-ID {target_id} was not found in Observer '{self.name}'"
+        raise KeyError(msg)
 
     def get_target(self, target_id: int) -> Target:
         if self.has_target(target_id):
@@ -87,4 +91,5 @@ class Observer(ShpModel, title="Shepherd-Sheep"):
                 return self.target_a
             if self.target_b is not None and target_id == self.target_b.id:
                 return self.target_b
-        raise ValueError(f"Target-ID {target_id} was not found in Observer '{self.name}'")
+        msg = f"Target-ID {target_id} was not found in Observer '{self.name}'"
+        raise KeyError(msg)

shepherd_core/data_models/testbed/observer_fixture.yaml

@@ -24,9 +24,9 @@
     name: sheep01
     ip: 192.168.165.201
     mac: 18:62:E4:E4:41:8D
-    room: II56
-    eth_port: J24
-    description: lower mid on west-side
+    room: II70
+    eth_port: B22
+    description: mid-mid in room
     cape:
       name: cape51
     target_a:
@@ -38,9 +38,9 @@
     name: sheep02
     ip: 192.168.165.202
     mac: 18:62:E4:D0:DE:3F
-    room: II57
-    eth_port: J6
-    description: mid on east-side
+    room: II66
+    eth_port: A18
+    description: south-west corner
     cape:
       name: cape52
     target_a:
@@ -52,9 +52,9 @@
     name: sheep03
     ip: 192.168.165.203
     mac: 18:62:E4:D0:9E:6A
-    room: II59
-    eth_port: I14
-    description: north-west-corner
+    room: II69
+    eth_port: B10
+    description: north-east-corner
     cape:
       name: cape63
     target_a:
@@ -66,8 +66,8 @@
     name: sheep04
     ip: 192.168.165.204
     mac: 18:62:E4:D0:61:4D
-    room: II61
-    eth_port: H18
+    room: II72
+    eth_port: C6
     description: mid on east-side
     cape:
       name: cape54
@@ -80,9 +80,9 @@
     name: sheep05
     ip: 192.168.165.205
     mac: 18:62:E4:E3:6E:13
-    room: II62
-    eth_port: H14
-    description: mid on south-side
+    room: II75
+    eth_port: D10
+    description: south-west corner
     cape:
       name: cape55
     target_a:
@@ -125,13 +125,14 @@
     ip: 192.168.165.208
     mac: 18:62:E4:D0:E5:FB
     room: II69
-    eth_port: B10
+    eth_port: TBD
     description: north-east-corner
     cape:
       name: cape58
     target_a:
       name: nRF52_FRAM_016
     created: 2023-09-22 12:12:12
+    active: false  # TODO: cape is broken for now
 - datatype: observer
   parameters:
     id: 9
@@ -168,7 +169,7 @@
     mac: 18:62:E4:E4:0E:5D
     room: II69
     eth_port: B14
-    description: mid on east-side
+    description: lower mid on east-side
     cape:
       name: cape61
     target_a:
@@ -180,9 +181,9 @@
     name: sheep12
     ip: 192.168.165.212
     mac: 18:62:E4:D0:AA:F7
-    room: II59
-    eth_port: I10
-    description: south-west-corner
+    room: II71
+    eth_port: B24
+    description: north-east-corner
     cape:
       name: cape62
     target_a:
@@ -197,7 +198,7 @@
     room: II64C
     eth_port: A4
     description: north-west-corner
-    comment: might temporary be in II70
+    comment:
     cape:
       name: cape60
     target_a:
@@ -211,8 +212,8 @@
     mac: 18:62:E4:E3:89:43
     room: II64B
     eth_port: L24
-    description: north-east-corner in cupboard
-    comment: might temporary be in II70
+    description: north-east-corner in cupboard, elevated
+    comment:
     cape:
       name: cape64
     target_a:

shepherd_core/data_models/testbed/target.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from datetime import datetime
 from typing import Optional
 from typing import Union
@@ -19,9 +21,9 @@ MCUPort = Annotated[int, Field(ge=1, le=2)]
 
 
 class Target(ShpModel, title="Target Node (DuT)"):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     version: NameStr
     description: SafeStr
@@ -36,7 +38,7 @@ class Target(ShpModel, title="Target Node (DuT)"):
     mcu1: Union[MCU, NameStr]
     mcu2: Union[MCU, NameStr, None] = None
 
-    # TODO programming pins per mcu should be here (or better in Cape)
+    # TODO: programming pins per mcu should be here (or better in Cape)
 
     def __str__(self) -> str:
         return self.name

shepherd_core/data_models/testbed/target_fixture.yaml

@@ -16,37 +16,37 @@
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 5
+    id: 10
     name: nRF52_FRAM_002
     comment: Test3 21nA sleep
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 3
+    id: 7
     name: nRF52_FRAM_003
     comment: Test3 21nA sleep
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 2
+    id: 3
     name: nRF52_FRAM_004
     comment: Test3 21nA sleep
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 13
+    id: 11
     name: nRF52_FRAM_005
     comment: Test3 21nA sleep, changed Antenna to lambda/4
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 14
+    id: 12
     name: nRF52_FRAM_006
     comment: Test3 21nA sleep, changed Antenna to lambda/4
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 12
+    id: 8
     name: nRF52_FRAM_007
     comment: msp-programming is failing -> defective, msp removed & changed Antenna to lambda/4
     mcu2: null
@@ -54,7 +54,7 @@
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 8
+    id: 9
     name: nRF52_FRAM_008
     comment: msp-programming is failing -> defective, msp removed & changed Antenna to lambda/4
     mcu2: null
@@ -62,13 +62,13 @@
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 10
+    id: 5
     name: nRF52_FRAM_009
     comment: Test3 21nA sleep
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 11
+    id: 2
     name: nRF52_FRAM_010
     comment: Test3 21nA sleep
 - datatype: target
@@ -107,13 +107,13 @@
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 9
+    id: 666
     name: nRF52_FRAM_016
     comment: Test3 21nA sleep
 - datatype: target
   parameters:
     inherit_from: nRF52_FRAM_001
-    id: 7
+    id: 13
     name: nRF52_FRAM_017
     comment: Test3 21nA sleep, nrf was miss-aligned -> hot air rework
 - datatype: target

shepherd_core/data_models/testbed/testbed.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from datetime import timedelta
 from pathlib import Path
 from typing import List
@@ -18,9 +20,9 @@ from .observer import Observer
 
 
 class Testbed(ShpModel):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
-    id: IdInt  # noqa: A003
+    id: IdInt
     name: NameStr
     description: SafeStr
     comment: Optional[SafeStr] = None
@@ -87,4 +89,5 @@ class Testbed(ShpModel):
                 continue
             if _observer.has_target(target_id):
                 return _observer
-        raise ValueError(f"Target-ID {target_id} was not found in Testbed '{self.name}'")
+        msg = f"Target-ID {target_id} was not found in Testbed '{self.name}'"
+        raise ValueError(msg)

shepherd_core/decoder_waveform/__init__.py

@@ -1,3 +1,5 @@
+"""Module for making data in waveforms accessible by decoding protocols."""
+
 from .uart import Uart
 
 __all__ = ["Uart"]

shepherd_core/decoder_waveform/uart.py

@@ -1,4 +1,7 @@
-"""UART - Decoder - Features:
+"""UART - Decoder.
+
+Features:
+
 - 1 bit Start (LOW)
 - 1 .. **8** .. 64 bit data-frame
 - **1**, 1.5, 2 bit stop (HIGH) - don't care?
@@ -7,16 +10,17 @@
 - **no** inversion
 
 Todo:
-----
-  - detect bitOrder
-  - detect dataframe length
-  - detect parity
+- detect bitOrder
+- detect dataframe length
+- detect parity
 
 More Info:
+
 https://en.wikipedia.org/wiki/Universal_asynchronous_receiver-transmitter
 https://sigrok.org/wiki/Protocol_decoder:Uart
 
 """
+
 from enum import Enum
 from pathlib import Path
 from typing import Optional
@@ -28,19 +32,23 @@ from ..logger import logger
 
 
 class Parity(str, Enum):
+    """Options for parity-property of UART data-frame."""
+
     no = "no"
     even = "odd"
     odd = "even"
 
 
 class BitOrder(str, Enum):
-    msb = "msb"
-    msb_first = "msb"
-    lsb = "lsb"
-    lsb_first = "lsb"
+    """Options for bit-order-property of UART data-frame."""
+
+    msb = msb_first = "msb"
+    lsb = lsb_first = "lsb"
 
 
 class Uart:
+    """Specialized UART decoder."""
+
     def __init__(
         self,
         content: Union[Path, np.ndarray],
@@ -50,10 +58,14 @@ class Uart:
         parity: Optional[Parity] = Parity.no,
         bit_order: Optional[BitOrder] = BitOrder.lsb_first,
     ) -> None:
-        """Provide a file with two columns:
-        - timestamp (seconds with fraction) and signal (can be analog).
-        - class-parameters that are None (above) get auto-detected
-          (some detectors still missing)
+        """Provide a file with two columns: TS & Signal.
+
+        Constraints:
+        - timestamp -> seconds with fraction
+        - signal -> can be analog or digital
+
+        Note: class-parameters that are None (above) get auto-detected
+          (some detectors still missing).
         """
         if isinstance(content, Path):
             self.events_sig: np.ndarray = np.loadtxt(content.as_posix(), delimiter=",", skiprows=1)
@@ -108,7 +120,7 @@ class Uart:
         self.text: Optional[str] = None
 
     def _convert_analog2digital(self, *, invert: bool = False) -> None:
-        """Divide dimension in two, divided by mean-value"""
+        """Divide dimension in two, divided by mean-value."""
         data = self.events_sig[:, 1]
         mean = np.mean(data)
         if invert:
@@ -117,7 +129,7 @@ class Uart:
             self.events_sig[:, 1] = data >= mean
 
     def _filter_redundant_states(self) -> None:
-        """Sum of two sequential states is always 1 (True + False) if alternating"""
+        """Sum of two sequential states is always 1 (True + False) if alternating."""
         data_0 = self.events_sig[:, 1]
         data_1 = np.concatenate([[not data_0[0]], data_0[:-1]])
         data_f = data_0 + data_1
@@ -131,7 +143,7 @@ class Uart:
             )
 
     def _add_duration(self) -> None:
-        """Calculate third column -> duration of state in [baud-ticks]"""
+        """Calculate third column -> duration of state in [baud-ticks]."""
         if self.events_sig.shape[1] > 2:
             logger.warning("Tried to add state-duration, but it seems already present")
             return
@@ -142,7 +154,8 @@ class Uart:
         self.events_sig = np.append(self.events_sig[:-1, :], dur_steps / self.dur_tick, axis=1)
 
     def detect_inversion(self) -> bool:
-        """Analyze bit-state during long pauses (unchanged states)
+        """Analyze bit-state during long pauses (unchanged states).
+
         - pause should be HIGH for non-inverted mode (default)
         - assumes max frame size of 64 bit + x for safety
         """
@@ -156,7 +169,7 @@ class Uart:
         return mean_state < 0.5
 
     def detect_baud_rate(self) -> int:
-        """Analyze the smallest step"""
+        """Analyze the smallest step."""
         events = self.events_sig[:1000, :]  # speedup for large datasets
         dur_steps = events[1:, 0] - events[:-1, 0]
         def_step = np.percentile(dur_steps[dur_steps > 0], 10)
@@ -166,23 +179,29 @@ class Uart:
         return round(1 / mean_tick)
 
     def detect_half_stop(self) -> bool:
-        """Looks into the spacing between time-steps"""
+        """Look into the spacing between time-steps to determine use of half stop."""
         events = self.events_sig[:1000, :]  # speedup for large datasets
         return np.sum((events > 1.333 * self.dur_tick) & (events < 1.667 * self.dur_tick)) > 0
 
     def detect_dataframe_length(self) -> int:
-        """Look after longest pauses
-        - accumulate steps until a state with uneven step-size is found
+        """Try to determine length of dataframe.
+
+        Algo will look for longest pauses & accumulate steps until
+        a state with uneven step-size is found.
         """
+        raise NotImplementedError
 
     def get_symbols(self, *, force_redo: bool = False) -> np.ndarray:
-        """Ways to detect EOF:
+        """Extract symbols from events.
+
+        Ways to detect EOF:
         - long pause on HIGH
         - off_tick pause on high
         - bit_pos > max
+
         # TODO:
             - slowest FN -> speedup with numba or parallelization?
-            - dset could be divided (long pauses) and threaded for speedup
+            - dset could be divided (long pauses) and threaded for speedup.
         """
         if force_redo:
             self.events_symbols = None
@@ -234,7 +253,7 @@ class Uart:
         return self.events_symbols
 
     def get_lines(self, *, force_redo: bool = False) -> np.ndarray:
-        """Timestamped symbols to line, cut at \r, \r\n or \n"""
+        r"""Timestamped symbols to line, cut at \r, \r\n or \n."""
         if force_redo:
             self.events_lines = None
         if self.events_lines is not None:
@@ -266,7 +285,7 @@ class Uart:
         return self.events_lines
 
     def get_text(self, *, force_redo: bool = False) -> str:
-        """Remove timestamps and just return the whole string"""
+        """Remove timestamps and just return the whole string."""
         if force_redo:
             self.text = None
         if self.text is not None:

shepherd_core/fw_tools/__init__.py

@@ -1,3 +1,5 @@
+"""Helper-functions for handling firmware around the testbed."""
+
 from typing import Any
 
 try:

shepherd_core/fw_tools/converter.py

@@ -1,3 +1,5 @@
+"""Content-Converters for firmwares."""
+
 import base64
 import hashlib
 import shutil
@@ -15,21 +17,25 @@ from .validation import is_hex
 
 @validate_call
 def firmware_to_hex(file_path: Path) -> Path:
-    """Generic converter that handles ELF & HEX"""
+    """Convert ELF-Files to HEX.
+
+    Generic converter that handles ELF & HEX.
+    """
     if not file_path.is_file():
-        raise ValueError("Fn needs an existing file as input")
+        raise FileNotFoundError("Fn needs an existing file as input")
     if is_elf(file_path):
         return elf_to_hex(file_path)
     if is_hex(file_path):
         return file_path
-    raise ValueError("FW2Hex: unknown file '%s', it should be ELF or HEX", file_path.name)
+    raise FileNotFoundError("FW2Hex: unknown file '%s', it should be ELF or HEX", file_path.name)
 
 
 @validate_call
 def file_to_base64(file_path: Path) -> str:
-    """Compress and encode content of file
+    """Compress and encode content of file.
+
     - base64 adds ~33 % overhead
-    - zstd compression ~ 1:3
+    - zstd compression reduces to ~ 1:3
     """
     if not file_path.is_file():
         raise ValueError("Fn needs an existing file as input")
@@ -41,9 +47,10 @@ def file_to_base64(file_path: Path) -> str:
 
 @validate_call
 def base64_to_file(content: str, file_path: Path) -> None:
-    """DeCompress and decode Content of file
+    """DeCompress and decode Content of file.
+
     - base64 adds ~33 % overhead
-    - zstd compression ~ 1:3
+    - zstd compression reduces to ~ 1:3
     """
     file_cmpress = base64.b64decode(content)
     file_content = zstd.ZstdDecompressor().decompress(file_cmpress)
@@ -55,6 +62,7 @@ def base64_to_file(content: str, file_path: Path) -> None:
 
 @validate_call
 def file_to_hash(file_path: Path) -> str:
+    """Convert file-content to hash-value."""
     if not file_path.is_file():
         raise ValueError("Fn needs an existing file as input")
     with file_path.resolve().open("rb") as file:
@@ -64,6 +72,7 @@ def file_to_hash(file_path: Path) -> str:
 
 @validate_call
 def base64_to_hash(content: str) -> str:
+    """Convert base64-content to hash-value."""
     file_cmpress = base64.b64decode(content)
     file_content = zstd.ZstdDecompressor().decompress(file_cmpress)
     return hashlib.sha3_224(file_content).hexdigest()
@@ -71,8 +80,10 @@ def base64_to_hash(content: str) -> str:
 
 @validate_call
 def extract_firmware(data: Union[str, Path], data_type: FirmwareDType, file_path: Path) -> Path:
-    """- base64-string will be transformed into file
-    - if data is a path the file will be copied to the destination
+    """Make embedded firmware-data usable in filesystem.
+
+    - base64-string will be transformed to file
+    - if data is a path the file will be copied to the destination.
     """
     if data_type == FirmwareDType.base64_elf:
         file = file_path.with_suffix(".elf")

shepherd_core/fw_tools/converter_elf.py

@@ -1,3 +1,5 @@
+"""Converter for ELF-files."""
+
 import subprocess
 from pathlib import Path
 from typing import Optional
@@ -9,6 +11,7 @@ from pydantic import validate_call
 
 @validate_call
 def elf_to_hex(file_elf: Path, file_hex: Optional[Path] = None) -> Path:
+    """Convert ELF to hex file using objcopy."""
     if not file_elf.is_file():
         raise ValueError("Fn needs an existing file as input")
     if not file_hex:

shepherd_core/fw_tools/patcher.py

@@ -1,3 +1,5 @@
+"""Read and modify symbols in ELF-files."""
+
 from pathlib import Path
 from typing import Optional
 
@@ -22,6 +24,7 @@ except ImportError as e:
 
 @validate_call
 def find_symbol(file_elf: Path, symbol: str) -> bool:
+    """Find a symbol in the ELF file."""
     if symbol is None or not is_elf(file_elf):
         return False
     if ELF is None:
@@ -47,7 +50,10 @@ def find_symbol(file_elf: Path, symbol: str) -> bool:
 
 @validate_call
 def read_symbol(file_elf: Path, symbol: str, length: int = uid_len_default) -> Optional[int]:
-    """Interpreted as int"""
+    """Read value of symbol in ELF-File.
+
+    Will be interpreted as int.
+    """
     if not find_symbol(file_elf, symbol):
         return None
     if ELF is None:
@@ -60,10 +66,12 @@ def read_symbol(file_elf: Path, symbol: str, length: int = uid_len_default) -> O
 
 
 def read_uid(file_elf: Path) -> Optional[int]:
+    """Read value of UID-symbol for shepherd testbed."""
     return read_symbol(file_elf, symbol=uid_str_default, length=uid_len_default)
 
 
 def read_arch(file_elf: Path) -> Optional[str]:
+    """Determine chip-architecture from elf-metadata."""
     if not is_elf(file_elf):
         return None
     if ELF is None:
@@ -83,9 +91,12 @@ def modify_symbol_value(
     *,
     overwrite: bool = False,
 ) -> Optional[Path]:
-    """Replaces value of symbol in ELF-File, hardcoded for uint16_t (2 byte)
-    testbed uses FN to patch firmware with custom target-ID
-    NOTE: can overwrite provided file
+    """Replace value of uint16-symbol in ELF-File.
+
+    Hardcoded for uint16_t (2 byte).
+    The testbed uses this to patch firmware with custom target-ID.
+
+    NOTE: can overwrite provided file.
 
     """
     if not find_symbol(file_elf, symbol):
@@ -121,4 +132,5 @@ def modify_symbol_value(
 
 
 def modify_uid(file_elf: Path, value: int) -> Optional[Path]:
+    """Replace value of UID-symbol for shepherd testbed."""
     return modify_symbol_value(file_elf, symbol=uid_str_default, value=value, overwrite=True)