shepherd-core 2024.4.1__py3-none-any.whl → 2024.5.1__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,7 +26,7 @@ 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
     name: NameStr
@@ -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

@@ -0,0 +1,221 @@
+---
+# observer-cape-target-relation: https://github.com/orgua/shepherd_v2_planning/blob/main/doc_testbed/Cape_pre-deployment-tests.xlsx
+# network data: https://github.com/orgua/shepherd_v2_planning/blob/main/doc_testbed/ethernet_MAC_addresses_bbones.ods
+- datatype: observer
+  parameters:
+    id: 0
+    name: sheep0
+    ip: 10.0.0.20
+    mac: 18:00:C0:FF:EE:77
+    room: at-home
+    eth_port: unimatrix_zero_one
+    description: lab / dev
+    longitude: 0
+    latitude: 0
+    cape:
+      name: cape53
+    target_a:
+      name: nRF52_FRAM_018
+    created: 2022-12-12 12:12:12
+    active: false
+- datatype: observer
+  parameters:
+    id: 1
+    name: sheep01
+    ip: 192.168.165.201
+    mac: 18:62:E4:E4:41:8D
+    room: II70
+    eth_port: B22
+    description: mid-mid in room
+    cape:
+      name: cape51
+    target_a:
+      name: nRF52_FRAM_001
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 2
+    name: sheep02
+    ip: 192.168.165.202
+    mac: 18:62:E4:D0:DE:3F
+    room: II66
+    eth_port: A18
+    description: south-west corner
+    cape:
+      name: cape52
+    target_a:
+      name: nRF52_FRAM_002
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 3
+    name: sheep03
+    ip: 192.168.165.203
+    mac: 18:62:E4:D0:9E:6A
+    room: II69
+    eth_port: B10
+    description: north-east-corner
+    cape:
+      name: cape63
+    target_a:
+      name: nRF52_FRAM_003
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 4
+    name: sheep04
+    ip: 192.168.165.204
+    mac: 18:62:E4:D0:61:4D
+    room: II72
+    eth_port: C6
+    description: mid on east-side
+    cape:
+      name: cape54
+    target_a:
+      name: nRF52_FRAM_004
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 5
+    name: sheep05
+    ip: 192.168.165.205
+    mac: 18:62:E4:E3:6E:13
+    room: II75
+    eth_port: D10
+    description: south-west corner
+    cape:
+      name: cape55
+    target_a:
+      name: nRF52_FRAM_011
+    target_b:
+      name: target_nRF52_01  # ONLY VIRTUAL - for unittests
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 6
+    name: sheep06
+    ip: 192.168.165.206
+    mac: 18:62:E4:D0:AF:0B
+    room: II64
+    eth_port: L14
+    description: mid on north-side
+    cape:
+      name: cape56
+    target_a:
+      name: nRF52_FRAM_017  # TODO: not validated
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 7
+    name: sheep07
+    ip: 192.168.165.207
+    mac: 18:62:E4:E4:39:D7
+    room: II66
+    eth_port: A20
+    description: north-west-corner
+    cape:
+      name: cape57
+    target_a:
+      name: nRF52_FRAM_008
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 8
+    name: sheep08
+    ip: 192.168.165.208
+    mac: 18:62:E4:D0:E5:FB
+    room: II69
+    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
+    name: sheep09
+    ip: 192.168.165.209
+    mac: 18:62:E4:D0:D4:A9
+    room: II71
+    eth_port: C4
+    description: south-east-corner
+    cape:
+      name: cape65
+    target_a:
+      name: nRF52_FRAM_009  # TODO: not validated
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 10
+    name: sheep10
+    ip: 192.168.165.210
+    mac: 18:62:E4:E4:24:C5
+    room: II74
+    eth_port: C20
+    description: upper mid on east-side
+    cape:
+      name: cape59
+    target_a:
+      name: nRF52_FRAM_010
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 11
+    name: sheep11
+    ip: 192.168.165.211
+    mac: 18:62:E4:E4:0E:5D
+    room: II69
+    eth_port: B14
+    description: lower mid on east-side
+    cape:
+      name: cape61
+    target_a:
+      name: nRF52_FRAM_007
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 12
+    name: sheep12
+    ip: 192.168.165.212
+    mac: 18:62:E4:D0:AA:F7
+    room: II71
+    eth_port: B24
+    description: north-east-corner
+    cape:
+      name: cape62
+    target_a:
+      name: nRF52_FRAM_014
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 13
+    name: sheep13
+    ip: 192.168.165.213
+    mac: 18:62:E4:D0:D7:70
+    room: II64C
+    eth_port: A4
+    description: north-west-corner
+    comment:
+    cape:
+      name: cape60
+    target_a:
+      name: nRF52_FRAM_005
+    created: 2023-09-22 12:12:12
+- datatype: observer
+  parameters:
+    id: 14
+    name: sheep14
+    ip: 192.168.165.214
+    mac: 18:62:E4:E3:89:43
+    room: II64B
+    eth_port: L24
+    description: north-east-corner in cupboard, elevated
+    comment:
+    cape:
+      name: cape64
+    target_a:
+      name: nRF52_FRAM_006
+    created: 2023-09-22 12:12:12

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,7 +21,7 @@ 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
     name: NameStr
@@ -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

@@ -0,0 +1,137 @@
+---
+# more human-readable test-protocol @
+# https://github.com/orgua/shepherd_v2_planning/blob/main/doc_testbed/Target_pre-deployment-tests.xlsx
+- datatype: target
+  parameters:
+    id: 6  # Outer ID - selected by user - can be rearranged
+    name: nRF52_FRAM_001  # inner ID - used to link all parts together
+    version: v1.0
+    description: nRF52 as MCU + Radio, MSP430FR as SPI-FRAM or additional MCU
+    comment: Test3 21nA sleep, msp-programming was flaky before -> monitor!
+    created: 2023-04-12
+    mcu1:
+      name: nRF52
+    mcu2:
+      name: MSP430FR
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 10
+    name: nRF52_FRAM_002
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 7
+    name: nRF52_FRAM_003
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 3
+    name: nRF52_FRAM_004
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 11
+    name: nRF52_FRAM_005
+    comment: Test3 21nA sleep, changed Antenna to lambda/4
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 12
+    name: nRF52_FRAM_006
+    comment: Test3 21nA sleep, changed Antenna to lambda/4
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 8
+    name: nRF52_FRAM_007
+    comment: msp-programming is failing -> defective, msp removed & changed Antenna to lambda/4
+    mcu2: null
+    active: true
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 9
+    name: nRF52_FRAM_008
+    comment: msp-programming is failing -> defective, msp removed & changed Antenna to lambda/4
+    mcu2: null
+    active: true
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 5
+    name: nRF52_FRAM_009
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 2
+    name: nRF52_FRAM_010
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 1
+    name: nRF52_FRAM_011
+    comment: Test3 21nA sleep, changed Antenna to lambda/4
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 1312
+    name: nRF52_FRAM_012
+    comment: msp-programming is failing -> defective, Antenna-Port destroyed
+    active: false
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 1313
+    name: nRF52_FRAM_013
+    comment: Test3 15nA sleep, Test1 fails - several cleanings -> defective
+    active: false
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 4
+    name: nRF52_FRAM_014
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 1315
+    name: nRF52_FRAM_015
+    comment: Test3 19nA sleep, Test1 fails - several cleanings - gpio error on nrf-side -> defective
+    active: false
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 666
+    name: nRF52_FRAM_016
+    comment: Test3 21nA sleep
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 13
+    name: nRF52_FRAM_017
+    comment: Test3 21nA sleep, nrf was miss-aligned -> hot air rework
+- datatype: target
+  parameters:
+    inherit_from: nRF52_FRAM_001
+    id: 18
+    name: nRF52_FRAM_018
+    comment: Test3 21nA sleep, nrf was miss-aligned -> hot air rework
+    description: LabPrototype
+
+- datatype: target
+  parameters:
+    id: 1001
+    name: target_nRF52_01
+    version: v2.1r0
+    description: single target PCB, v2.1r0
+    comment: ONLY VIRTUAL - NOT REAL
+    mcu1:
+      name: nRF52
+    mcu2: null
+    created: 2022-12-12 12:12:12

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,7 +20,7 @@ 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
     name: NameStr
@@ -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/data_models/testbed/testbed_fixture.yaml

@@ -0,0 +1,25 @@
+- datatype: testbed
+  parameters:
+    id: 1337
+    name: shepherd_tud_nes
+    description: "Shepherd Testbed of the NES Lab Group at TU Dresden, Germany"
+    shared_storage: true
+    data_on_server: /var/shepherd/
+    data_on_observer: /var/shepherd/
+    # ./content as read-only for the sheep, shared with server
+    # ./experiments on the sheep map to ./experiments/sheep##/ on the server
+    observers:
+      - name: sheep01
+      - name: sheep02
+      - name: sheep03
+      - name: sheep04
+      - name: sheep05
+      - name: sheep06
+      - name: sheep07
+      - name: sheep08
+      - name: sheep09
+      - name: sheep10
+      - name: sheep11
+      - name: sheep12
+      - name: sheep13
+      - name: sheep14

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,12 +10,12 @@
 - **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
 
@@ -29,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],
@@ -51,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)
@@ -109,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:
@@ -118,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
@@ -132,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
@@ -143,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
         """
@@ -157,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)
@@ -167,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
@@ -235,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:
@@ -267,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: