shepherd-core 2024.4.1__py3-none-any.whl → 2024.5.1__py3-none-any.whl

shepherd_core/data_models/readme.md

@@ -0,0 +1,88 @@
+## Datastructure
+
+### experiment-structure
+
+- basics
+- scheduling
+- **SystemLogger**
+- ~~AuxPort~~
+- TargetConfigs
+  - Programming
+  - PowerTracer
+  - GpioTracer
+  - GpioActuator
+  - vSrc
+    - vHarvester
+    - [vConverter]
+
+## TODO
+
+- establish internal variables ``_var``
+- descriptions to parameters (docstring on sub-models)
+- @kai
+  - firmwares
+  - programmer-ports determine IC
+    - memory read - family-code, or write factory
+  - when tracing v_intermediate, also this current, or output?
+- ``objcopy -O ihex input.elf output.hex``
+  - ``-S`` will strip useless sections
+  - ``-I ihex -O elf32-littlearm`` for reversal is also possible
+    - TODO: try to find ``objdump -t [elf_file] | grep SHEPHERD_NODE_ID``
+
+- title in class might be rubbish
+
+- Warn about tricky syntax
+  - defining sub-data-models in an experiment in python:
+    - experiments-default: don't mention argument in init
+    - trace-default: init trace with empty argument list
+    - disable: init with "None"
+  - defining experiment in yaml:
+    - experiment-default: don't mention it
+    - trace-default: NOT POSSIBLE, right?
+    - disable: init with "null" OR just mention parameter but keep it empty
+
+### add documentation after creation ⇾ avoid Field()
+
+- these do not work
+
+```Python
+from pydantic import Field
+from shepherd_core.data_models import ShpModel
+
+class Experiment(ShpModel, title="Config of an Experiment"):
+    def __init__(self):  # test to add doc after creation ⇾ to avoid Field()
+        super().__init__()
+        self.Config.fields["output_path"].description = "test description"
+    class Config:
+        fields: dict[str, Field] = {}
+        fields["output_path"] = Field(description="test description")
+```
+
+### simplify init of pydantic-class
+
+What I want: init a fixture-class with Class("name") or Class(ID) instead of Class(name="name")
+
+What does not work:
+
+```Python
+from pathlib import Path
+from typing import Union
+from pydantic import root_validator
+from shepherd_core.data_models import Fixture
+from shepherd_core.data_models import ShpModel
+
+fixtures = Fixture(Path("fix.yaml"), "testbed.target")
+
+
+class Target(ShpModel, title="Target Node (DuT)"):
+  @root_validator(pre=True)
+  def query_database(cls, values: Union[dict, str, int]):
+    values = fixtures.try_completing_model(values)
+    values, chain = fixtures.try_inheritance(values)
+    return values
+```
+
+what might work:
+
+- writing a custom __init__() and putting lookup() there
+- wait for V2

shepherd_core/data_models/task/__init__.py

@@ -1,3 +1,8 @@
+"""Module for task-related data-modules.
+
+These models import externally from all other model-modules!
+"""
+
 from pathlib import Path
 from typing import List
 from typing import Optional
@@ -33,7 +38,9 @@ __all__ = [
 
 
 def prepare_task(config: Union[ShpModel, Path, str], observer: Optional[str] = None) -> Wrapper:
-    """- Opens file (from Path or str of Path)
+    """Open file and extract tasks.
+
+    - Open file (from Path or str of Path)
     - wraps task-model
     - and if it's an TestbedTasks it will extract the correct ObserverTask
     """
@@ -50,7 +57,7 @@ def prepare_task(config: Union[ShpModel, Path, str], observer: Optional[str] = N
             parameters=config.model_dump(),
         )
     else:
-        raise ValueError("had unknown input: %s", type(config))
+        raise TypeError("had unknown input: %s", type(config))
 
     if shp_wrap.datatype == TestbedTasks.__name__:
         if observer is None:
@@ -72,7 +79,7 @@ def prepare_task(config: Union[ShpModel, Path, str], observer: Optional[str] = N
 
 
 def extract_tasks(shp_wrap: Wrapper, *, no_task_sets: bool = True) -> List[ShpModel]:
-    """ """
+    """Make the individual task-sets usable for each observer."""
     if shp_wrap.datatype == ObserverTasks.__name__:
         obt = ObserverTasks(**shp_wrap.parameters)
         content = obt.get_tasks()

shepherd_core/data_models/task/emulation.py

@@ -1,3 +1,5 @@
+"""Configuration for the Observer in Emulation-Mode."""
+
 import copy
 from datetime import datetime
 from datetime import timedelta
@@ -26,10 +28,10 @@ from ..testbed.cape import TargetPort
 
 
 class Compression(str, Enum):
-    lzf = "lzf"  # not native hdf5
-    gzip1 = 1  # higher compr & load
-    gzip = 1
-    default = "lzf"
+    """Options for choosing a dataset-compression."""
+
+    lzf = default = "lzf"  # not native hdf5
+    gzip1 = gzip = 1  # higher compr & load
     null = None
     # NOTE: changed to lzf as BBB needs every straw it can get
 
@@ -39,7 +41,7 @@ c_translate = {"lzf": "lzf", "1": 1, "None": None, None: None}
 
 
 class EmulationTask(ShpModel):
-    """Configuration for the Observer in Emulation-Mode"""
+    """Configuration for the Observer in Emulation-Mode."""
 
     # General config
     input_path: Path
@@ -58,7 +60,7 @@ class EmulationTask(ShpModel):
     # timestamp or unix epoch time, None = ASAP
     duration: Optional[timedelta] = None
     # ⤷ Duration of recording in seconds, None = till EOF
-    abort_on_error: bool = False
+    abort_on_error: bool = False  # TODO: remove, should not exist
 
     # emulation-specific
     use_cal_default: bool = False
@@ -111,10 +113,11 @@ class EmulationTask(ShpModel):
         has_time = self.time_start is not None
         time_now = datetime.now().astimezone()
         if has_time and self.time_start < time_now:
-            raise ValueError(
+            msg = (
                 "Start-Time for Emulation can't be in the past "
                 f"('{self.time_start}' vs '{time_now}'."
             )
+            raise ValueError(msg)
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Task-Duration can't be negative.")
         if isinstance(self.voltage_aux, str) and self.voltage_aux not in {

shepherd_core/data_models/task/firmware_mod.py

@@ -1,3 +1,5 @@
+"""Config for Task that adds the custom ID to the firmware & stores it into a file."""
+
 import copy
 from pathlib import Path
 from typing import Optional
@@ -24,7 +26,7 @@ from ..testbed.target import MCUPort
 
 
 class FirmwareModTask(ShpModel):
-    """Config for Task that adds the custom ID to the firmware & stores it into a file"""
+    """Config for Task that adds the custom ID to the firmware & stores it into a file."""
 
     data: Union[FirmwareStr, Path]
     data_type: FirmwareDType
@@ -79,7 +81,7 @@ class FirmwareModTask(ShpModel):
         **kwargs: Unpack[TypedDict],
     ) -> Self:
         if not isinstance(fw, Firmware):
-            raise ValueError("fw-argument must be of type Firmware")
+            raise TypeError("fw-argument must be of type Firmware")
         kwargs["data"] = fw.data
         kwargs["data_type"] = fw.data_type
         fw.compare_hash()

shepherd_core/data_models/task/harvest.py

@@ -1,3 +1,5 @@
+"""Config for the Observer in Harvest-Mode to record IV data from a harvesting-source."""
+
 from datetime import datetime
 from datetime import timedelta
 from pathlib import Path
@@ -17,9 +19,7 @@ from .emulation import Compression
 
 
 class HarvestTask(ShpModel):
-    """Configuration for the Observer in Harvest-Mode
-    Record IV data from a harvest-source
-    """
+    """Config for the Observer in Harvest-Mode to record IV data from a harvesting-source."""
 
     # General config
     output_path: Path
@@ -73,10 +73,11 @@ class HarvestTask(ShpModel):
         has_time = self.time_start is not None
         time_now = datetime.now().astimezone()
         if has_time and self.time_start < time_now:
-            raise ValueError(
+            msg = (
                 "Start-Time for Emulation can't be in the past "
                 f"('{self.time_start}' vs '{time_now}'."
             )
+            raise ValueError(msg)
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Task-Duration can't be negative.")
         return self

shepherd_core/data_models/task/observer_tasks.py

@@ -1,3 +1,5 @@
+"""Collection of tasks for selected observer included in experiment."""
+
 from datetime import datetime
 from datetime import timedelta
 from pathlib import Path
@@ -18,7 +20,7 @@ from .programming import ProgrammingTask
 
 
 class ObserverTasks(ShpModel):
-    """Collection of tasks for selected observer included in experiment"""
+    """Collection of tasks for selected observer included in experiment."""
 
     observer: NameStr
     owner_id: Optional[IdInt]  # TODO: set to optional for now, shouldn't be

shepherd_core/data_models/task/programming.py

@@ -1,3 +1,5 @@
+"""Config for a Task programming the selected target."""
+
 import copy
 from pathlib import Path
 from typing import Optional
@@ -21,7 +23,7 @@ from ..testbed.testbed import Testbed
 
 
 class ProgrammingTask(ShpModel):
-    """Config for Task programming the target selected"""
+    """Config for a Task programming the selected target."""
 
     firmware_file: Path
     target_port: TargetPort = TargetPort.A

shepherd_core/data_models/task/testbed_tasks.py

@@ -1,3 +1,5 @@
+"""Collection of tasks for all observers included in experiment."""
+
 from typing import List
 from typing import Optional
 
@@ -15,7 +17,7 @@ from .observer_tasks import ObserverTasks
 
 
 class TestbedTasks(ShpModel):
-    """Collection of tasks for all observers included in experiment"""
+    """Collection of tasks for all observers included in experiment."""
 
     name: NameStr
     observer_tasks: Annotated[List[ObserverTasks], Field(min_length=1, max_length=128)]

shepherd_core/data_models/testbed/__init__.py

@@ -1,3 +1,8 @@
+"""Module for testbed-related data-models.
+
+These models import externally from: /base
+"""
+
 from .cape import Cape
 from .cape import TargetPort
 from .gpio import GPIO
@@ -10,8 +15,6 @@ from .target import IdInt16
 from .target import Target
 from .testbed import Testbed
 
-# these models import externally from: /base
-
 __all__ = [
     "Testbed",
     "Observer",

shepherd_core/data_models/testbed/cape.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from datetime import date
 from datetime import datetime
 from enum import Enum
@@ -15,14 +17,14 @@ from ..base.shepherd import ShpModel
 
 
 class TargetPort(str, Enum):
-    A = "A"
-    B = "B"
-    a = "A"
-    b = "B"
+    """Options for choosing a target-port."""
+
+    A = a = "A"
+    B = b = "B"
 
 
 class Cape(ShpModel, title="Shepherd-Cape"):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
     id: IdInt
     name: NameStr

shepherd_core/data_models/testbed/cape_fixture.yaml

@@ -0,0 +1,94 @@
+---
+
+# more human-readable test-protocol @
+# https://github.com/orgua/shepherd_v2_planning/blob/main/doc_testbed/Cape_pre-deployment-tests.xlsx
+- datatype: cape
+  parameters:
+    id: 1270051
+    name: cape51
+    version: v2.4b
+    description: full version with Hrv & Emu, modded gpio,emu,hrv
+    created: 2022-10-07
+    calibrated: 2023-09-21
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270052
+    name: cape52
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270053
+    name: cape53
+    description: full version with Hrv & Emu, partially modded
+    comment: 1st Lab Prototype, burned VReg -> currently defective
+    active: false
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270054
+    name: cape54
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270055
+    name: cape55
+    comment: Target-Port B, C-Meas failed on first Cal
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270056
+    name: cape56
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270057
+    name: cape57
+    comment: 2nd Lab Prototype, has stackable headers
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270058
+    name: cape58
+    comment: has shields on emu & hrv-circuits -> no effect on RF-Performance
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270059
+    name: cape59
+    comment: only 220u/440uF on 5V
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270060
+    name: cape60
+    comment: 3rd Lab Prototype
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270061
+    name: cape61
+    comment: only 220u/440uF on 5V
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270062
+    name: cape62
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270063
+    name: cape63
+    comment: only 220u/440uF on 5V
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270064
+    name: cape64
+    comment: only 220u/440uF on 5V, had 6x74LVC2T45GT flippend (U11,12,23,24,27,28) - hot air repair
+- datatype: cape
+  parameters:
+    inherit_from: cape51
+    id: 1270065
+    name: cape65
+    comment: only 220u/440uF on 5V

shepherd_core/data_models/testbed/gpio.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from enum import Enum
 from typing import Optional
 
@@ -15,16 +17,15 @@ from ..base.shepherd import ShpModel
 
 
 class Direction(str, Enum):
-    Input = "IN"
-    IN = "IN"
-    Output = "OUT"
-    OUT = "OUT"
-    Bidirectional = "IO"
-    IO = "IO"
+    """Options for pin-direction."""
+
+    Input = IN = "IN"
+    Output = OUT = "OUT"
+    Bidirectional = IO = "IO"
 
 
 class GPIO(ShpModel, title="GPIO of Observer Node"):
-    """meta-data representation of a testbed-component"""
+    """meta-data representation of a testbed-component."""
 
     id: IdInt
     name: NameStr
@@ -54,10 +55,11 @@ class GPIO(ShpModel, title="GPIO of Observer Node"):
         no_pru = (self.reg_pru is None) or (self.pin_pru is None)
         no_sys = (self.reg_sys is None) or (self.pin_sys is None)
         if no_pru and no_sys:
-            raise ValueError(
+            msg = (
                 "GPIO-Instance is faulty -> "
                 f"it needs to use pru or sys, content: {self.model_dump()}"
             )
+            raise ValueError(msg)
         return self
 
     def user_controllable(self) -> bool:

shepherd_core/data_models/testbed/gpio_fixture.yaml

@@ -0,0 +1,166 @@
+--- # add with >>> python manage.py loaddata <fixturename>
+# cape v2.4
+- datatype: gpio
+  parameters:
+    id: 1000
+    name: GPIO0
+    # description:
+    # comment:
+    direction: IO
+    dir_switch: DIR1
+    reg_pru: r31_00
+    pin_pru: P8_45
+    reg_sys: 26
+    pin_sys: P8_14
+- datatype: gpio
+  parameters:
+    id: 1001
+    name: GPIO1
+    direction: IO
+    dir_switch: DIR1
+    reg_pru: r31_01
+    pin_pru: P8_46
+    reg_sys: 27
+    pin_sys: P8_17
+- datatype: gpio
+  parameters:
+    id: 1002
+    name: GPIO2
+    direction: IO
+    dir_switch: DIR1
+    reg_pru: r31_02
+    pin_pru: P8_43
+    reg_sys: 46
+    pin_sys: P8_16
+- datatype: gpio
+  parameters:
+    id: 1003
+    name: GPIO3
+    direction: IO
+    dir_switch: DIR1
+    reg_pru: r31_03
+    pin_pru: P8_44
+    reg_sys: 47
+    pin_sys: P8_15
+- datatype: gpio
+  parameters:
+    id: 1004
+    name: GPIO4
+    direction: IN
+    reg_pru: r31_04
+    pin_pru: P8_41
+    reg_sys: 61
+    pin_sys: P8_26
+- datatype: gpio
+  parameters:
+    id: 1005
+    name: GPIO5
+    direction: IN
+    reg_pru: r31_05
+    pin_pru: P8_42
+    reg_sys: 80
+    pin_sys: P8_36
+- datatype: gpio
+  parameters:
+    id: 1006
+    name: GPIO6
+    direction: IN
+    reg_pru: r31_06
+    pin_pru: P8_39
+    reg_sys: 81
+    pin_sys: P8_34
+- datatype: gpio
+  parameters:
+    id: 1007
+    name: GPIO7
+    description: alias UART_RX
+    direction: IN
+    reg_pru: r31_07
+    pin_pru: P8_40
+    reg_sys: 14
+    pin_sys: P9_26
+- datatype: gpio
+  parameters:
+    id: 1008
+    name: GPIO8
+    description: alias UART_TX
+    direction: IO
+    dir_switch: DIR2
+    reg_pru: r31_08
+    pin_pru: P8_27
+    reg_sys: 15
+    pin_sys: P9_24
+- datatype: gpio
+  parameters:
+    id: 1009
+    name: BAT_OK
+    description: signal from vSource (PRU) to target
+    direction: OUT
+    reg_pru: r30_09
+    pin_pru: P8_29
+- datatype: gpio
+  parameters:
+    id: 2000
+    name: PRG1_CLK
+    description: alias JTAG_TCK
+    direction: OUT
+    reg_sys: 5
+    pin_sys: P9_17
+- datatype: gpio
+  parameters:
+    id: 2001
+    name: PRG1_IO
+    description: alias JTAG_TDI
+    direction: IO
+    dir_switch: PDIR1
+    reg_sys: 4
+    pin_sys: P9_18
+- datatype: gpio
+  parameters:
+    id: 2010
+    name: PRG2_CLK
+    description: alias JTAG_TDO
+    direction: OUT
+    reg_sys: 8
+    pin_sys: P8_35
+- datatype: gpio
+  parameters:
+    id: 2011
+    name: PRG2_IO
+    description: alias JTAG_TMS
+    direction: IO
+    dir_switch: PDIR2
+    reg_sys: 9
+    pin_sys: P8_33
+- datatype: gpio
+  parameters:
+    id: 3000
+    name: DIR1
+    description: changes direction of GPIO[0:3]
+    direction: OUT
+    reg_sys: 78
+    pin_sys: P8_37
+- datatype: gpio
+  parameters:
+    id: 3001
+    name: DIR2
+    description: changes direction of GPIO8
+    direction: OUT
+    reg_sys: 79
+    pin_sys: P8_38
+- datatype: gpio
+  parameters:
+    id: 3002
+    name: PDIR1
+    description: changes direction PRG1_IO
+    direction: OUT
+    reg_sys: 10
+    pin_sys: P8_31
+- datatype: gpio
+  parameters:
+    id: 3003
+    name: PDIR2
+    description: changes direction PRG2_IO
+    direction: OUT
+    reg_sys: 11
+    pin_sys: P8_32

shepherd_core/data_models/testbed/mcu.py

@@ -1,3 +1,5 @@
+"""meta-data representation of a testbed-component (physical object)."""
+
 from enum import Enum
 from typing import Optional
 
@@ -13,18 +15,16 @@ from ..base.shepherd import ShpModel
 
 
 class ProgrammerProtocol(str, Enum):
-    SWD = "SWD"
-    swd = "SWD"
-    SBW = "SBW"
-    sbw = "SBW"
-    JTAG = "JTAG"
-    jtag = "JTAG"
-    UART = "UART"
-    uart = "UART"
+    """Options regarding the programming-protocol."""
+
+    SWD = swd = "SWD"
+    SBW = sbw = "SBW"
+    JTAG = jtag = "JTAG"
+    UART = uart = "UART"
 
 
 class MCU(ShpModel, title="Microcontroller of the Target Node"):
-    """meta-data representation of a testbed-component (physical object)"""
+    """meta-data representation of a testbed-component (physical object)."""
 
     id: IdInt
     name: NameStr

shepherd_core/data_models/testbed/mcu_fixture.yaml

@@ -0,0 +1,19 @@
+--- # add with >>> python manage.py loaddata <fixturename>
+- datatype: mcu
+  parameters:
+    id: 1001
+    name: nRF52
+    description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+    platform: nRF52
+    core: nRF52840
+    prog_protocol: SWD
+    fw_name_default: nrf52_demo_rf
+- datatype: mcu
+  parameters:
+    id: 1002
+    name: MSP430FR
+    description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+    platform: MSP430
+    core: MSP430FR5962
+    prog_protocol: SBW
+    fw_name_default: msp430_deep_sleep