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

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,45 +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,
@@ -87,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
@@ -241,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)]
@@ -316,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),
@@ -329,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

@@ -5,18 +5,18 @@ from datetime import datetime
 from datetime import timedelta
 from typing import Annotated
 from typing import Optional
-from typing import Union
-from uuid import uuid4
 
-from pydantic import UUID4
 from pydantic import Field
 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.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
@@ -24,34 +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: UUID4 ... # TODO: db-migration - temp fix for documentation
-    id: Union[UUID4, int] = Field(default_factory=uuid4)
-    # ⤷ 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: bool = False
 
     # targets
     target_configs: Annotated[list[TargetConfig], Field(min_length=1, max_length=128)]
@@ -59,11 +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:
-        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

@@ -6,15 +6,20 @@ from typing import Annotated
 from typing import Optional
 
 import numpy as np
+from annotated_types import Interval
 from pydantic import Field
 from pydantic import PositiveFloat
 from pydantic import model_validator
 from typing_extensions import Self
 from typing_extensions import deprecated
 
+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.
@@ -23,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:
@@ -105,7 +118,7 @@ STOPBITS_ONE, STOPBITS_ONE_POINT_FIVE, STOPBITS_TWO = (1, 1.5, 2)
 STOPBITS = (STOPBITS_ONE, STOPBITS_ONE_POINT_FIVE, STOPBITS_TWO)
 
 
-class UartTracing(ShpModel, title="Config for UART Tracing"):
+class UartLogging(ShpModel, title="Config for UART Logging"):
     """Configuration for recording UART-Output of the Target Nodes.
 
     Note that the Communication has to be on a specific port that
@@ -132,49 +145,65 @@ class UartTracing(ShpModel, title="Config for UART Tracing"):
         return self
 
 
+GpioInt = Annotated[int, Interval(ge=0, le=17)]
+GpioList = Annotated[list[GpioInt], Field(min_length=1, max_length=18)]
+all_gpio = list(range(18))
+
+
 class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
     """Configuration for recording the GPIO-Output of the Target Nodes.
 
     TODO: postprocessing not implemented ATM
     """
 
-    # initial recording
-    mask: Annotated[int, Field(ge=0, lt=2**10)] = 0b11_1111_1111  # all
-    # ⤷ TODO: custom mask not implemented in PRU, ATM
-    gpios: Optional[Annotated[list[GPIO], Field(min_length=1, max_length=10)]] = None  # = all
-    # ⤷ TODO: list of GPIO to build mask, one of both should be internal / computed field
+    gpios: GpioList = all_gpio
+    """List of GPIO to record.
+
+    This feature allows to remove unwanted pins from recording,
+    i.e. for chatty pins with separate UART Logging enabled.
+    Numbering is based on the Target-Port and its 16x GPIO and two PwrGood-Signals.
+    See doc for nRF_FRAM_Target_v1.3+ to see mapping of target port.
+
+    Example for skipping UART (pin 0 & 1):
+    .gpio = range(2,18)
+
+    Note:
+    - Cape 2.4 (2023) and lower only has 9x GPIO + 1x PwrGood
+    - Cape 2.5 (2025) has first 12 GPIO & both PwrGood
+    - this will be mapped accordingly by the observer
+    """
 
     # time
-    delay: timedelta = timedelta(seconds=0)
+    delay: timedelta = zero_duration
     duration: Optional[timedelta] = None  # till EOF
 
     # post-processing,
     uart_decode: bool = False
-    # TODO: quickfix - uart-log currently done online in userspace
-    # NOTE: gpio-tracing currently shows rather big - but rare - "blind" windows (~1-4us)
+    """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
-    # TODO: add a "discard_gpio" (if only uart is wanted)
 
     @model_validator(mode="after")
     def post_validation(self) -> Self:
-        if self.mask == 0:
-            raise ValueError("Error in config -> tracing enabled but mask is 0")
         if self.delay and self.delay.total_seconds() < 0:
             raise ValueError("Delay can't be negative.")
         if self.duration and self.duration.total_seconds() < 0:
             raise ValueError("Duration can't be negative.")
-        if self.mask != 0b11_1111_1111:  # GpioTracing.mask
-            raise NotImplementedError("Feature GpioTracing.mask reserved for future use.")
-        if self.gpios is not None:
-            raise NotImplementedError("Feature GpioTracing.gpios reserved for future use.")
         if self.uart_decode:
-            raise NotImplementedError(
+            logger.error(
                 "Feature GpioTracing.uart_decode reserved for future use. "
-                "Use UartTracing or manually decode serial with the provided waveform decoder."
+                "Use UartLogging or manually decode serial with the provided waveform decoder."
             )
         return self
 
+    @property
+    def gpio_mask(self) -> int:
+        # valid for cape v2.5
+        mask = 0
+        for gpio in set(self.gpios):
+            mask |= 2**gpio
+        return mask
+
 
 class GpioLevel(str, Enum):
     """Options for setting the gpio-level or state."""
@@ -188,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")
@@ -216,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}
 
@@ -228,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

@@ -18,7 +18,10 @@ from shepherd_core.data_models.testbed.target import Target
 from .observer_features import GpioActuation
 from .observer_features import GpioTracing
 from .observer_features import PowerTracing
-from .observer_features import UartTracing
+from .observer_features import UartLogging
+
+# defaults (pre-init complex types)
+vsrc_neutral = VirtualSourceConfig(name="neutral")
 
 
 class TargetConfig(ShpModel, title="Target Config"):
@@ -26,25 +29,32 @@ class TargetConfig(ShpModel, title="Target Config"):
 
     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
-    uart_tracing: Optional[UartTracing] = None
     gpio_actuation: Optional[GpioActuation] = None
+    uart_logging: Optional[UartLogging] = None
 
     @model_validator(mode="after")
     def post_validation(self) -> Self:

shepherd_core/data_models/task/emulation.py

@@ -13,6 +13,7 @@ from pydantic import Field
 from pydantic import model_validator
 from pydantic import validate_call
 from typing_extensions import Self
+from typing_extensions import deprecated
 
 from shepherd_core.data_models.base.content import IdInt
 from shepherd_core.data_models.base.shepherd import ShpModel
@@ -23,7 +24,8 @@ from shepherd_core.data_models.experiment.observer_features import GpioActuation
 from shepherd_core.data_models.experiment.observer_features import GpioTracing
 from shepherd_core.data_models.experiment.observer_features import PowerTracing
 from shepherd_core.data_models.experiment.observer_features import SystemLogging
-from shepherd_core.data_models.experiment.observer_features import UartTracing
+from shepherd_core.data_models.experiment.observer_features import UartLogging
+from shepherd_core.data_models.experiment.target_config import vsrc_neutral
 from shepherd_core.data_models.testbed import Testbed
 from shepherd_core.data_models.testbed.cape import TargetPort
 from shepherd_core.logger import logger
@@ -48,55 +50,67 @@ class EmulationTask(ShpModel):
 
     # General config
     input_path: Path
-    # ⤷ hdf5 file containing harvesting data
+    """ ⤷ hdf5 file containing harvesting data"""
     output_path: Optional[Path] = None
-    # ⤷ dir- or file-path for storing the recorded data:
-    #   - providing a directory -> file is named emu_timestamp.h5
-    #   - for a complete path the filename is not changed except it exists and
-    #     overwrite is disabled -> emu#num.h5
-    # TODO: should the output-path be mandatory?
+    """ ⤷ dir- or file-path for storing the recorded data:
+
+    - providing a directory -> file is named emu_timestamp.h5
+    - for a complete path the filename is not changed except it exists and
+      overwrite is disabled -> emu#num.h5
+    TODO: should the output-path be mandatory?
+    """
     force_overwrite: bool = False
-    # ⤷ Overwrite existing file
+    """ ⤷ Overwrite existing file"""
     output_compression: Optional[Compression] = Compression.default
-    # ⤷ should be lzf, 1 (gzip level 1) or None (order of recommendation)
+    """ ⤷ should be lzf, 1 (gzip level 1) or None (order of recommendation)"""
     time_start: Optional[datetime] = None
-    # timestamp or unix epoch time, None = ASAP
+    """ timestamp or unix epoch time, None = ASAP"""
     duration: Optional[timedelta] = None
-    # ⤷ Duration of recording in seconds, None = till EOF
-    abort_on_error: bool = False  # TODO: remove, should not exist
+    """ ⤷ Duration of recording in seconds, None = till EOF"""
+    abort_on_error: Annotated[bool, deprecated("has no effect")] = False
 
     # emulation-specific
     use_cal_default: bool = False
-    # ⤷ Use default calibration values, skip loading from EEPROM
+    """ ⤷ Use default calibration values, skip loading from EEPROM"""
 
     enable_io: bool = True
     # TODO: add direction of pins! also it seems error-prone when only setting _tracing
-    # ⤷ Switch the GPIO level converter to targets on/off
-    #   pre-req for sampling gpio / uart,
+    """ ⤷ Switch the GPIO level converter to targets on/off
+
+    pre-req for sampling gpio / uart,
+    """
     io_port: TargetPort = TargetPort.A
-    # ⤷ Either Port A or B that gets connected to IO
+    """ ⤷ Either Port A or B that gets connected to IO"""
     pwr_port: TargetPort = TargetPort.A
-    # ⤷ chosen port will be current-monitored (main, connected to virtual Source),
-    #   the other port is aux
-    voltage_aux: Union[Annotated[float, Field(ge=0, le=4.5)], str] = 0
-    # ⤷ aux_voltage options:
-    #   - 0-4.5 for specific const Voltage (0 V = disabled),
-    #   - "buffer" will output intermediate voltage (storage cap of vsource),
-    #   - "main" will mirror main target voltage
+    """ ⤷ selected port will be current-monitored
 
+    - main channel is nnected to virtual Source
+    - the other port is aux
+    """
+    voltage_aux: Union[Annotated[float, Field(ge=0, le=4.5)], str] = 0
+    """ ⤷ aux_voltage options
+    - 0-4.5 for specific const Voltage (0 V = disabled),
+    - "buffer" will output intermediate voltage (storage cap of vsource),
+    - "main" will mirror main target voltage
+    """
     # sub-elements, could be partly moved to emulation
-    virtual_source: VirtualSourceConfig = VirtualSourceConfig(name="neutral")
-    # ⤷ Use the desired setting for the virtual source,
-    #   provide parameters or name like BQ25570
+    virtual_source: VirtualSourceConfig = vsrc_neutral
+    """ ⤷ Use the desired setting for the virtual source,
+
+    provide parameters or name like BQ25570
+    """
 
     power_tracing: Optional[PowerTracing] = PowerTracing()
     gpio_tracing: Optional[GpioTracing] = GpioTracing()
-    uart_tracing: Optional[UartTracing] = UartTracing()
+    uart_logging: Optional[UartLogging] = UartLogging()
     gpio_actuation: Optional[GpioActuation] = None
     sys_logging: Optional[SystemLogging] = SystemLogging()
 
     verbose: Annotated[int, Field(ge=0, le=4)] = 2
-    # ⤷ 0=Errors, 1=Warnings, 2=Info, 3=Debug, TODO: just bool now, systemwide
+    """ ⤷ 0=Errors, 1=Warnings, 2=Info, 3=Debug,
+
+    TODO: just bool now, systemwide
+    """
 
     @model_validator(mode="before")
     @classmethod
@@ -132,7 +146,7 @@ class EmulationTask(ShpModel):
             raise ValueError("GPIO Actuation not yet implemented!")
 
         io_requested = any(
-            _io is not None for _io in (self.gpio_actuation, self.gpio_tracing, self.uart_tracing)
+            _io is not None for _io in (self.gpio_actuation, self.gpio_tracing, self.uart_logging)
         )
         if self.enable_io and not io_requested:
             logger.warning("Target IO enabled, but no feature requested IO")
@@ -147,7 +161,7 @@ class EmulationTask(ShpModel):
         tgt_cfg = xp.get_target_config(tgt_id)
         io_requested = any(
             _io is not None
-            for _io in (tgt_cfg.gpio_actuation, tgt_cfg.gpio_tracing, tgt_cfg.uart_tracing)
+            for _io in (tgt_cfg.gpio_actuation, tgt_cfg.gpio_tracing, tgt_cfg.uart_logging)
         )
 
         return cls(
@@ -155,14 +169,13 @@ class EmulationTask(ShpModel):
             output_path=root_path / f"emu_{obs.name}.h5",
             time_start=copy.copy(xp.time_start),
             duration=xp.duration,
-            abort_on_error=xp.abort_on_error,
             enable_io=io_requested,
             io_port=obs.get_target_port(tgt_id),
             pwr_port=obs.get_target_port(tgt_id),
             virtual_source=tgt_cfg.virtual_source,
             power_tracing=tgt_cfg.power_tracing,
             gpio_tracing=tgt_cfg.gpio_tracing,
-            uart_tracing=tgt_cfg.uart_tracing,
+            uart_logging=tgt_cfg.uart_logging,
             gpio_actuation=tgt_cfg.gpio_actuation,
             sys_logging=xp.sys_logging,
         )