shepherd-core 2025.5.3__py3-none-any.whl → 2025.6.1__py3-none-any.whl

shepherd_core/commons.py

@@ -1,8 +1,6 @@
 """Container for commonly shared constants."""
 
-SAMPLERATE_SPS_DEFAULT: int = 100_000
+from .config import config
 
-UID_NAME: str = "SHEPHERD_NODE_ID"
-UID_SIZE: int = 2
-
-TESTBED_SERVER_URI: str = "http://127.0.0.1:8000/shepherd"
+# TODO: deprecated - replace with config in subprojects and then remove here
+SAMPLERATE_SPS_DEFAULT: int = config.SAMPLERATE_SPS

shepherd_core/config.py

@@ -0,0 +1,34 @@
+"""Container for a common configuration.
+
+This can be adapted by the user by importing 'config' and changing its variables.
+"""
+
+from pydantic import BaseModel
+from pydantic import HttpUrl
+
+
+class ConfigDefault(BaseModel):
+    """Container for a common configuration."""
+
+    __slots__ = ()
+
+    TESTBED: str = "shepherd_tud_nes"
+    """name of the testbed to validate against - if enabled - see switch below"""
+    VALIDATE_INFRA: bool = True
+    """switch to turn on / off deep validation of data models also considering the current
+    layout & infrastructure of the testbed.
+    """
+
+    SAMPLERATE_SPS: int = 100_000
+    """Rate of IV-Recording of the testbed."""
+
+    UID_NAME: str = "SHEPHERD_NODE_ID"
+    """Variable name to patch in ELF-file"""
+    UID_SIZE: int = 2
+    """Variable size in Byte"""
+
+    TESTBED_SERVER: HttpUrl = "https://shepherd.cfaed.tu-dresden.de:8000/"
+    """Server that holds up to date testbed fixtures"""
+
+
+config = ConfigDefault()

shepherd_core/data_models/base/calibration.py

@@ -95,14 +95,19 @@ cal_hrv_legacy = {  # legacy translator
     "adc_voltage": "adc_V_Sense",  # datalog voltage
 }
 
+# defaults (pre-init complex types)
+cal_pair_dac_V = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
+cal_pair_adc_V = CalibrationPair.from_fn(adc_voltage_to_raw, unit="V")
+cal_pair_adc_C = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
+
 
 class CalibrationHarvester(ShpModel):
     """Container for all calibration-pairs for that device."""
 
-    dac_V_Hrv: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    dac_V_Sim: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    adc_V_Sense: CalibrationPair = CalibrationPair.from_fn(adc_voltage_to_raw, unit="V")
-    adc_C_Hrv: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
+    dac_V_Hrv: CalibrationPair = cal_pair_dac_V
+    dac_V_Sim: CalibrationPair = cal_pair_dac_V
+    adc_V_Sense: CalibrationPair = cal_pair_adc_V
+    adc_C_Hrv: CalibrationPair = cal_pair_adc_C
 
     def export_for_sysfs(self) -> dict:
         """Convert and write the essential data.
@@ -143,10 +148,10 @@ class CalibrationEmulator(ShpModel):
     Differentiates between both target-ports A/B.
     """
 
-    dac_V_A: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    dac_V_B: CalibrationPair = CalibrationPair.from_fn(dac_voltage_to_raw, unit="V")
-    adc_C_A: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
-    adc_C_B: CalibrationPair = CalibrationPair.from_fn(adc_current_to_raw, unit="A")
+    dac_V_A: CalibrationPair = cal_pair_dac_V
+    dac_V_B: CalibrationPair = cal_pair_dac_V
+    adc_C_A: CalibrationPair = cal_pair_adc_C
+    adc_C_B: CalibrationPair = cal_pair_adc_C
 
     def export_for_sysfs(self) -> dict:
         """Convert and write the essential data.

shepherd_core/data_models/base/wrapper.py

@@ -17,11 +17,11 @@ class Wrapper(BaseModel):
     """Generalized web- & file-interface for all models with dynamic typecasting."""
 
     datatype: str
-    # ⤷ model-name
+    """ ⤷ model-name"""
     comment: Optional[SafeStrClone] = None
     created: Optional[datetime] = None
-    # ⤷ Optional metadata
+    """ ⤷ Optional metadata"""
     lib_ver: Optional[str] = version
-    # ⤷ for debug-purposes and later comp-checks
+    """ ⤷ for debug-purposes and later compatibility-checks"""
     parameters: dict
-    # ⤷ ShpModel
+    """ ⤷ ShpModel"""

shepherd_core/data_models/content/energy_environment.py

@@ -28,7 +28,7 @@ class EnergyEnvironment(ContentModel):
     data_path: Path
     data_type: EnergyDType
     data_local: bool = True
-    # ⤷ signals that file has to be copied to testbed
+    """ ⤷ signals that file has to be copied to testbed"""
 
     duration: PositiveFloat
     energy_Ws: PositiveFloat

shepherd_core/data_models/content/firmware.py

@@ -62,7 +62,7 @@ class Firmware(ContentModel, title="Firmware of Target"):
     data_type: FirmwareDType
     data_hash: Optional[str] = None
     data_local: bool = True
-    # ⤷ signals that file has to be copied to testbed
+    """ ⤷ signals that file has to be copied to testbed"""
 
     @model_validator(mode="before")
     @classmethod
@@ -125,12 +125,17 @@ class Firmware(ContentModel, title="Firmware of Target"):
             if "mcu" not in kwargs:
                 kwargs["mcu"] = arch_to_mcu[arch]
 
+        # verification of ELF - warn if something is off
+        # -> adds ARCH if it is able to derive
         if kwargs["data_type"] == FirmwareDType.base64_elf:
             arch = fw_tools.read_arch(file)
-            if "msp430" in arch and not fw_tools.is_elf_msp430(file):
-                raise ValueError("File is not a ELF for msp430")
-            if ("nrf52" in arch or "arm" in arch) and not fw_tools.is_elf_nrf52(file):
-                raise ValueError("File is not a ELF for nRF52")
+            try:
+                if "msp430" in arch and not fw_tools.is_elf_msp430(file):
+                    raise ValueError("File is not a ELF for msp430")
+                if ("nrf52" in arch or "arm" in arch) and not fw_tools.is_elf_nrf52(file):
+                    raise ValueError("File is not a ELF for nRF52")
+            except RuntimeError:
+                logger.warning("ObjCopy not found -> Arch of Firmware can't be verified")
             logger.debug("ELF-File '%s' has arch: %s", file.name, arch)
             if "mcu" not in kwargs:
                 kwargs["mcu"] = arch_to_mcu[arch]

shepherd_core/data_models/content/virtual_harvester.py

@@ -10,7 +10,7 @@ from pydantic import Field
 from pydantic import model_validator
 from typing_extensions import Self
 
-from shepherd_core.commons import SAMPLERATE_SPS_DEFAULT
+from shepherd_core.config import config
 from shepherd_core.data_models.base.calibration import CalibrationHarvester
 from shepherd_core.data_models.base.content import ContentModel
 from shepherd_core.data_models.base.shepherd import ShpModel
@@ -363,9 +363,9 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
     def calc_timings_ms(self, *, for_emu: bool) -> tuple[float, float]:
         """factor-in model-internal timing-constraints."""
         window_length = self.samples_n * (1 + self.wait_cycles)
-        time_min_ms = (1 + self.wait_cycles) * 1_000 / SAMPLERATE_SPS_DEFAULT
+        time_min_ms = (1 + self.wait_cycles) * 1_000 / config.SAMPLERATE_SPS
         if for_emu:
-            window_ms = window_length * 1_000 / SAMPLERATE_SPS_DEFAULT
+            window_ms = window_length * 1_000 / config.SAMPLERATE_SPS
             time_min_ms = max(time_min_ms, window_ms)
 
         interval_ms = min(max(self.interval_ms, time_min_ms), 1_000_000)
@@ -453,16 +453,16 @@ class HarvesterPRUConfig(ShpModel):
     voltage_min_uV: u32
     voltage_max_uV: u32
     voltage_step_uV: u32
-    # ⤷ for window-based algo like ivcurve
+    """ ⤷ for window-based algo like ivcurve"""
     current_limit_nA: u32
-    # ⤷ lower bound to detect zero current
+    """ ⤷ lower bound to detect zero current"""
     setpoint_n8: u32
     interval_n: u32
-    # ⤷ between measurements
+    """ ⤷ between measurements"""
     duration_n: u32
-    # ⤷ of measurement
+    """ ⤷ of measurement"""
     wait_cycles_n: u32
-    # ⤷ for DAC to settle
+    """ ⤷ for DAC to settle"""
 
     @classmethod
     def from_vhrv(
@@ -517,7 +517,7 @@ class HarvesterPRUConfig(ShpModel):
             voltage_step_uV=round(voltage_step_mV * 10**3),
             current_limit_nA=round(data.current_limit_uA * 10**3),
             setpoint_n8=round(min(255, data.setpoint_n * 2**8)),
-            interval_n=round(interval_ms * SAMPLERATE_SPS_DEFAULT * 1e-3),
-            duration_n=round(duration_ms * SAMPLERATE_SPS_DEFAULT * 1e-3),
+            interval_n=round(interval_ms * config.SAMPLERATE_SPS * 1e-3),
+            duration_n=round(duration_ms * config.SAMPLERATE_SPS * 1e-3),
             wait_cycles_n=data.wait_cycles,
         )

shepherd_core/data_models/content/virtual_source.py

@@ -7,7 +7,7 @@ from pydantic import Field
 from pydantic import model_validator
 from typing_extensions import Self
 
-from shepherd_core.commons import SAMPLERATE_SPS_DEFAULT
+from shepherd_core.config import config
 from shepherd_core.data_models.base.content import ContentModel
 from shepherd_core.data_models.base.shepherd import ShpModel
 from shepherd_core.logger import logger
@@ -23,6 +23,9 @@ NormedNum = Annotated[float, Field(ge=0.0, le=1.0)]
 LUT1D = Annotated[list[NormedNum], Field(min_length=LUT_SIZE, max_length=LUT_SIZE)]
 LUT2D = Annotated[list[LUT1D], Field(min_length=LUT_SIZE, max_length=LUT_SIZE)]
 
+# defaults (pre-init complex types for improved perf) TODO: is documentation still fine?
+vhrv_mppt_opt = VirtualHarvesterConfig(name="mppt_opt")
+
 
 class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     """The vSrc uses the energy environment (file) for supplying the Target Node.
@@ -41,46 +44,48 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     # General Metadata & Ownership -> ContentModel
 
     enable_boost: bool = False
-    # ⤷ if false -> v_intermediate = v_input, output-switch-hysteresis is still usable
+    """ ⤷ if false -> v_intermediate = v_input, output-switch-hysteresis is still usable"""
     enable_buck: bool = False
-    # ⤷ if false -> v_output = v_intermediate
+    """ ⤷ if false -> v_output = v_intermediate"""
     enable_feedback_to_hrv: bool = False
-    # src can control a cv-harvester for ivcurve
+    """ src can control a cv-harvester for ivcurve"""
 
     interval_startup_delay_drain_ms: Annotated[float, Field(ge=0, le=10_000)] = 0
 
-    harvester: VirtualHarvesterConfig = VirtualHarvesterConfig(name="mppt_opt")
+    harvester: VirtualHarvesterConfig = vhrv_mppt_opt
 
     V_input_max_mV: Annotated[float, Field(ge=0, le=10_000)] = 10_000
     I_input_max_mA: Annotated[float, Field(ge=0, le=4.29e3)] = 4_200
     V_input_drop_mV: Annotated[float, Field(ge=0, le=4.29e6)] = 0
-    # ⤷ simulate input-diode
+    """ ⤷ simulate input-diode"""
     R_input_mOhm: Annotated[float, Field(ge=0, le=4.29e6)] = 0
-    # ⤷ resistance only active with disabled boost, range [1 mOhm; 1MOhm]
+    """ ⤷ resistance only active with disabled boost, range [1 mOhm; 1MOhm]"""
 
     # primary storage-Cap
     C_intermediate_uF: Annotated[float, Field(ge=0, le=100_000)] = 0
     V_intermediate_init_mV: Annotated[float, Field(ge=0, le=10_000)] = 3_000
-    # ⤷ allow a proper / fast startup
+    """ ⤷ allow a proper / fast startup"""
     I_intermediate_leak_nA: Annotated[float, Field(ge=0, le=4.29e9)] = 0
 
     V_intermediate_enable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 1
-    # ⤷ target gets connected (hysteresis-combo with next value)
+    """ ⤷ target gets connected (hysteresis-combo with next value)"""
     V_intermediate_disable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 0
-    # ⤷ target gets disconnected
+    """ ⤷ target gets disconnected"""
     interval_check_thresholds_ms: Annotated[float, Field(ge=0, le=4.29e3)] = 0
-    # ⤷ some ICs (BQ) check every 64 ms if output should be disconnected
+    """ ⤷ some ICs (BQ) check every 64 ms if output should be disconnected"""
     # TODO: add intervals for input-disable, output-disable & power-good-signal
 
     # pwr-good: target is informed on output-pin (hysteresis) -> for intermediate voltage
     V_pwr_good_enable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 2_800
     V_pwr_good_disable_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 2200
     immediate_pwr_good_signal: bool = True
-    # ⤷ 1: activate instant schmitt-trigger, 0: stay in interval for checking thresholds
+    """ ⤷ 1: activate instant schmitt-trigger, 0: stay in interval for checking thresholds"""
 
-    # final (always last) stage to compensate undetectable current spikes
-    # when enabling power for target
     C_output_uF: Annotated[float, Field(ge=0, le=4.29e6)] = 1.0
+    """
+    final (always last) stage to compensate undetectable current spikes when
+    enabling power for target
+    """
     # TODO: C_output is handled internally as delta-V, but should be a I_transient
     #       that makes it visible in simulation as additional i_out_drain
     # TODO: potential weakness, ACD lowpass is capturing transient,
@@ -88,32 +93,35 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
 
     # Extra
     V_output_log_gpio_threshold_mV: Annotated[float, Field(ge=0, le=4.29e6)] = 1_400
-    # ⤷ min voltage needed to enable recording changes in gpio-bank
+    """ ⤷ min voltage needed to enable recording changes in gpio-bank"""
 
     # Boost Converter
     V_input_boost_threshold_mV: Annotated[float, Field(ge=0, le=10_000)] = 0
-    # ⤷ min input-voltage for the boost converter to work
+    """ ⤷ min input-voltage for the boost converter to work"""
     V_intermediate_max_mV: Annotated[float, Field(ge=0, le=10_000)] = 10_000
-    # ⤷ boost converter shuts off
+    """ ⤷ boost converter shuts off"""
 
     LUT_input_efficiency: LUT2D = 12 * [12 * [1.00]]
-    # ⤷ rows are current -> first row a[V=0][:]
-    # input-LUT[12][12] depending on array[inp_voltage][log(inp_current)],
-    # influence of cap-voltage is not implemented
+    """ ⤷ rows are current -> first row a[V=0][:]
+
+    input-LUT[12][12] depending on array[inp_voltage][log(inp_current)],
+    influence of cap-voltage is not implemented
+    """
+
     LUT_input_V_min_log2_uV: Annotated[int, Field(ge=0, le=20)] = 0
-    # ⤷ 2^7 = 128 uV -> LUT[0][:] is for inputs < 128 uV
+    """ ⤷ i.e. 2^7 = 128 uV -> LUT[0][:] is for inputs < 128 uV"""
     LUT_input_I_min_log2_nA: Annotated[int, Field(ge=1, le=20)] = 1
-    # ⤷ 2^8 = 256 nA -> LUT[:][0] is for inputs < 256 nA
+    """ ⤷ i.e. 2^8 = 256 nA -> LUT[:][0] is for inputs < 256 nA"""
 
     # Buck Converter
     V_output_mV: Annotated[float, Field(ge=0, le=5_000)] = 2_400
     V_buck_drop_mV: Annotated[float, Field(ge=0, le=5_000)] = 0
-    # ⤷ simulate LDO / diode min voltage differential or output-diode
+    """ ⤷ simulate LDO / diode min voltage differential or output-diode"""
 
     LUT_output_efficiency: LUT1D = 12 * [1.00]
-    # ⤷ array[12] depending on output_current
+    """ ⤷ array[12] depending on output_current"""
     LUT_output_I_min_log2_nA: Annotated[int, Field(ge=1, le=20)] = 1
-    # ⤷ 2^8 = 256 nA -> LUT[0] is for inputs < 256 nA, see notes on LUT_input for explanation
+    """ ⤷ 2^8 = 256 nA -> LUT[0] is for inputs < 256 nA, see notes on LUT_input for explanation"""
 
     @model_validator(mode="before")
     @classmethod
@@ -242,7 +250,7 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         dV[uV] = constant[us/nF] * current[nA] = constant[us*V/nAs] * current[nA]
         """
         C_cap_uF = max(self.C_intermediate_uF, 0.001)
-        return int((10**3 * (2**28)) // (C_cap_uF * SAMPLERATE_SPS_DEFAULT))
+        return int((10**3 * (2**28)) // (C_cap_uF * config.SAMPLERATE_SPS))
 
 
 u32 = Annotated[int, Field(ge=0, lt=2**32)]
@@ -317,7 +325,7 @@ class ConverterPRUConfig(ShpModel):
                 dtype_in, log_intermediate_node=log_intermediate_node
             ),
             interval_startup_delay_drain_n=round(
-                data.interval_startup_delay_drain_ms * SAMPLERATE_SPS_DEFAULT * 1e-3
+                data.interval_startup_delay_drain_ms * config.SAMPLERATE_SPS * 1e-3
             ),
             V_input_max_uV=round(data.V_input_max_mV * 1e3),
             I_input_max_nA=round(data.I_input_max_mA * 1e6),
@@ -330,7 +338,7 @@ class ConverterPRUConfig(ShpModel):
             V_disable_output_threshold_uV=round(states["V_disable_output_threshold_mV"] * 1e3),
             dV_enable_output_uV=round(states["dV_enable_output_mV"] * 1e3),
             interval_check_thresholds_n=round(
-                data.interval_check_thresholds_ms * SAMPLERATE_SPS_DEFAULT * 1e-3
+                data.interval_check_thresholds_ms * config.SAMPLERATE_SPS * 1e-3
             ),
             V_pwr_good_enable_threshold_uV=round(data.V_pwr_good_enable_threshold_mV * 1e3),
             V_pwr_good_disable_threshold_uV=round(data.V_pwr_good_disable_threshold_mV * 1e3),

shepherd_core/data_models/content/virtual_source_fixture.yaml

@@ -1,6 +1,6 @@
 # info:
 # - compendium of all parameters & description
-# - base for neutral fallback values if provided yml is sparse
+# - base for neutral fallback values if provided yaml is sparse
 # - -> it is encouraged to omit redundant parameters
 ---
 - datatype: VirtualSourceConfig

shepherd_core/data_models/experiment/experiment.py

@@ -11,11 +11,12 @@ from pydantic import model_validator
 from typing_extensions import Self
 from typing_extensions import deprecated
 
+from shepherd_core.config import config
 from shepherd_core.data_models.base.content import IdInt
 from shepherd_core.data_models.base.content import NameStr
 from shepherd_core.data_models.base.content import SafeStr
-from shepherd_core.data_models.base.content import id_default
 from shepherd_core.data_models.base.shepherd import ShpModel
+from shepherd_core.data_models.base.timezone import local_now
 from shepherd_core.data_models.testbed.target import Target
 from shepherd_core.data_models.testbed.testbed import Testbed
 from shepherd_core.version import version
@@ -23,33 +24,28 @@ from shepherd_core.version import version
 from .observer_features import SystemLogging
 from .target_config import TargetConfig
 
+# defaults (pre-init complex types)
+sys_log_all = SystemLogging()  # = all active
+
 
 class Experiment(ShpModel, title="Config of an Experiment"):
     """Config for experiments on the testbed emulating energy environments for target nodes."""
 
     # General Properties
-    id: int = Field(description="Unique ID", default_factory=id_default)
-    # ⤷ TODO: automatic ID is problematic for identification by hash
-
     name: NameStr
     description: Annotated[
         Optional[SafeStr], Field(description="Required for public instances")
     ] = None
     comment: Optional[SafeStr] = None
-    created: datetime = Field(default_factory=datetime.now)
-
-    # Ownership & Access
-    owner_id: Optional[IdInt] = None
 
     # feedback
-    email_results: bool = False
+    email_results: bool = True
 
-    sys_logging: SystemLogging = SystemLogging()  # = all active
+    sys_logging: SystemLogging = sys_log_all
 
     # schedule
     time_start: Optional[datetime] = None  # = ASAP
     duration: Optional[timedelta] = None  # = till EOF
-    abort_on_error: Annotated[bool, deprecated("has no effect")] = False
 
     # targets
     target_configs: Annotated[list[TargetConfig], Field(min_length=1, max_length=128)]
@@ -57,13 +53,16 @@ class Experiment(ShpModel, title="Config of an Experiment"):
     # debug
     lib_ver: Optional[str] = version
 
+    # deprecated fields, TODO: remove before public release
+    id: Annotated[Optional[int], deprecated("not needed")] = None
+    created: Annotated[Optional[datetime], deprecated("not needed")] = None
+    abort_on_error: Annotated[bool, deprecated("has no effect")] = False
+    owner_id: Annotated[Optional[IdInt], deprecated("not needed")] = None
+
     @model_validator(mode="after")
     def post_validation(self) -> Self:
-        # TODO: only do deep validation with active connection to TB-client
-        #       or with cached fixtures
-        testbed = Testbed()  # this will query the first (and only) entry of client
+        self._validate_observers(self.target_configs)
         self._validate_targets(self.target_configs)
-        self._validate_observers(self.target_configs, testbed)
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Duration of experiment can't be negative.")
         return self
@@ -75,8 +74,9 @@ class Experiment(ShpModel, title="Config of an Experiment"):
         for _config in configs:
             for _id in _config.target_IDs:
                 target_ids.append(_id)
-                Target(id=_id)
-                # ⤷ this can raise exception for non-existing targets
+                if config.VALIDATE_INFRA:
+                    Target(id=_id)
+                    # ⤷ this can raise exception for non-existing targets
             if _config.custom_IDs is not None:
                 custom_ids = custom_ids + _config.custom_IDs[: len(_config.target_IDs)]
             else:
@@ -87,7 +87,10 @@ class Experiment(ShpModel, title="Config of an Experiment"):
             raise ValueError("Custom Target-ID are faulty (some form of id-collisions)!")
 
     @staticmethod
-    def _validate_observers(configs: Iterable[TargetConfig], testbed: Testbed) -> None:
+    def _validate_observers(configs: Iterable[TargetConfig]) -> None:
+        if not config.VALIDATE_INFRA:
+            return
+        testbed = Testbed()
         target_ids = [_id for _config in configs for _id in _config.target_IDs]
         obs_ids = [testbed.get_observer(_id).id for _id in target_ids]
         if len(target_ids) > len(set(obs_ids)):
@@ -105,3 +108,10 @@ class Experiment(ShpModel, title="Config of an Experiment"):
         # gets already caught in target_config - but keep:
         msg = f"Target-ID {target_id} was not found in Experiment '{self.name}'"
         raise ValueError(msg)
+
+    def folder_name(self, custom_date: Optional[datetime] = None) -> str:
+        date = custom_date if custom_date is not None else self.time_start
+        timestamp = local_now() if date is None else date
+        timestrng = timestamp.strftime("%Y-%m-%d_%H-%M-%S")
+        # ⤷ closest to ISO 8601, avoids ":"
+        return f"{timestrng}_{self.name.replace(' ', '_')}"

shepherd_core/data_models/experiment/observer_features.py

@@ -17,6 +17,9 @@ from shepherd_core import logger
 from shepherd_core.data_models.base.shepherd import ShpModel
 from shepherd_core.data_models.testbed.gpio import GPIO
 
+# defaults (pre-init complex types)
+zero_duration = timedelta(seconds=0)
+
 
 class PowerTracing(ShpModel, title="Config for Power-Tracing"):
     """Configuration for recording the Power-Consumption of the Target Nodes.
@@ -25,19 +28,27 @@ class PowerTracing(ShpModel, title="Config for Power-Tracing"):
     """
 
     intermediate_voltage: bool = False
-    # ⤷ for EMU: record storage capacitor instead of output (good for V_out = const)
-    #            this also includes current!
-
+    """
+    ⤷ for EMU: record storage capacitor instead of output (good for V_out = const)
+               this also includes current!
+    """
     # time
-    delay: timedelta = timedelta(seconds=0)
+    delay: timedelta = zero_duration
+    """start recording after experiment started"""
     duration: Optional[timedelta] = None  # till EOF
+    """duration of recording after delay starts the process.
+
+    default is None, recording till EOF"""
 
     # post-processing
     calculate_power: bool = False
-    samplerate: Annotated[int, Field(ge=10, le=100_000)] = 100_000  # down-sample
+    """ ⤷ reduce file-size by calculating power -> not implemented ATM"""
+    samplerate: Annotated[int, Field(ge=10, le=100_000)] = 100_000
+    """ ⤷ reduce file-size by down-sampling -> not implemented ATM"""
     discard_current: bool = False
+    """ ⤷ reduce file-size by omitting current -> not implemented ATM"""
     discard_voltage: bool = False
-    # ⤷ reduce file-size by omitting current / voltage
+    """ ⤷ reduce file-size by omitting voltage -> not implemented ATM"""
 
     @model_validator(mode="after")
     def post_validation(self) -> Self:
@@ -163,11 +174,12 @@ class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
     """
 
     # time
-    delay: timedelta = timedelta(seconds=0)
+    delay: timedelta = zero_duration
     duration: Optional[timedelta] = None  # till EOF
 
     # post-processing,
     uart_decode: bool = False
+    """Automatic decoding from gpio-trace not implemented ATM."""
     uart_pin: GPIO = GPIO(name="GPIO8")
     uart_baudrate: Annotated[int, Field(ge=2_400, le=1_152_000)] = 115_200
 
@@ -205,12 +217,14 @@ class GpioEvent(ShpModel, title="Config for a GPIO-Event"):
     """Configuration for a single GPIO-Event (Actuation)."""
 
     delay: PositiveFloat
-    # ⤷ from start_time
-    # ⤷ resolution 10 us (guaranteed, but finer steps are possible)
+    """ ⤷ from start_time
+
+    - resolution 10 us (guaranteed, but finer steps are possible)
+    """
     gpio: GPIO
     level: GpioLevel
     period: Annotated[float, Field(ge=10e-6)] = 1
-    # ⤷ time base of periodicity in s
+    """ ⤷ time base of periodicity in s"""
     count: Annotated[int, Field(ge=1, le=4096)] = 1
 
     @model_validator(mode="after")
@@ -233,6 +247,11 @@ class GpioActuation(ShpModel, title="Config for GPIO-Actuation"):
 
     events: Annotated[list[GpioEvent], Field(min_length=1, max_length=1024)]
 
+    @model_validator(mode="after")
+    def post_validation(self) -> Self:
+        msg = "not implemented ATM"
+        raise ValueError(msg)
+
     def get_gpios(self) -> set:
         return {_ev.gpio for _ev in self.events}
 
@@ -245,7 +264,7 @@ class SystemLogging(ShpModel, title="Config for System-Logging"):
     sheep: bool = True
     sys_util: bool = True
 
-    # TODO: remove lines below in 2026
+    # deprecated, TODO: remove lines below before public release
     dmesg: Annotated[bool, deprecated("for sheep v0.9.0+, use 'kernel' instead")] = True
     ptp: Annotated[bool, deprecated("for sheep v0.9.0+, use 'time_sync' instead")] = True
     shepherd: Annotated[bool, deprecated("for sheep v0.9.0+, use 'sheep' instead")] = True

shepherd_core/data_models/experiment/target_config.py

@@ -20,26 +20,36 @@ from .observer_features import GpioTracing
 from .observer_features import PowerTracing
 from .observer_features import UartLogging
 
+# defaults (pre-init complex types)
+vsrc_neutral = VirtualSourceConfig(name="neutral")
+
 
 class TargetConfig(ShpModel, title="Target Config"):
     """Configuration related to Target Nodes (DuT)."""
 
     target_IDs: Annotated[list[IdInt], Field(min_length=1, max_length=128)]
     custom_IDs: Optional[Annotated[list[IdInt16], Field(min_length=1, max_length=128)]] = None
-    # ⤷ will replace 'const uint16_t SHEPHERD_NODE_ID' in firmware
-    #   if no custom ID is provided, the original ID of target is used
+    """ ⤷ custom ID will replace 'const uint16_t SHEPHERD_NODE_ID' in firmware.
+
+    if no custom ID is provided, the original ID of target is used
+    """
 
-    energy_env: EnergyEnvironment  # alias: input
-    virtual_source: VirtualSourceConfig = VirtualSourceConfig(name="neutral")
+    energy_env: EnergyEnvironment
+    """ input for the virtual source """
+    virtual_source: VirtualSourceConfig = vsrc_neutral
     target_delays: Optional[
         Annotated[list[Annotated[int, Field(ge=0)]], Field(min_length=1, max_length=128)]
     ] = None
-    # ⤷ individual starting times -> allows to use the same environment
-    # TODO: delays not used ATM
+    """ ⤷ individual starting times
+
+    - allows to use the same environment
+    - not implemented ATM
+    """
 
     firmware1: Firmware
+    """ ⤷ omitted FW gets set to neutral deep-sleep"""
     firmware2: Optional[Firmware] = None
-    # ⤷ omitted FW gets set to neutral deep-sleep
+    """ ⤷ omitted FW gets set to neutral deep-sleep"""
 
     power_tracing: Optional[PowerTracing] = None
     gpio_tracing: Optional[GpioTracing] = None