shepherd-core 2025.5.2__tar.gz → 2025.5.3__tar.gz

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shepherd_core
-Version: 2025.5.2
+Version: 2025.5.3
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
 Author-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
 Maintainer-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/examples/experiment_generic_var1.py

@@ -48,7 +48,7 @@ xp = sm.Experiment(
             ),
             power_tracing=None,
             gpio_tracing=sm.GpioTracing(),
-            uart_tracing=sm.UartTracing(baudrate=115_200),
+            uart_logging=sm.UartLogging(baudrate=115_200),
         ),
     ],
 )

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/__init__.py

@@ -31,7 +31,7 @@ from .experiment.observer_features import GpioLevel
 from .experiment.observer_features import GpioTracing
 from .experiment.observer_features import PowerTracing
 from .experiment.observer_features import SystemLogging
-from .experiment.observer_features import UartTracing
+from .experiment.observer_features import UartLogging
 from .experiment.target_config import TargetConfig
 
 __all__ = [
@@ -55,7 +55,7 @@ __all__ = [
     "ShpModel",
     "SystemLogging",
     "TargetConfig",
-    "UartTracing",
+    "UartLogging",
     "VirtualHarvesterConfig",
     "VirtualSourceConfig",
     "Wrapper",

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/base/content.py

@@ -1,21 +1,16 @@
 """Base-Model for all content."""
 
-import hashlib
 from datetime import datetime
 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 StringConstraints
 from pydantic import model_validator
 from typing_extensions import Self
-from typing_extensions import deprecated
 
 from .shepherd import ShpModel
-from .timezone import local_now
 
 # constr -> to_lower=True, max_length=16, regex=r"^[\w]+$"
 # ⤷ Regex = AlphaNum
@@ -26,24 +21,20 @@ SafeStr = Annotated[str, StringConstraints(pattern=r"^[ -~]+$")]
 # ⤷ Regex = All Printable ASCII-Characters with Space
 
 
-@deprecated("use UUID4 instead")
 def id_default() -> int:
     """Generate a unique ID - usable as default value.
 
-    Note: IdInt has space for 128 bit, so 128/4 = 32 hex-chars
+    Note: IdInt in mongoDB can currently handle 8 bytes (16 hex-values)
     """
-    time_stamp = str(local_now()).encode("utf-8")
-    time_hash = hashlib.sha3_224(time_stamp).hexdigest()[-32:]
-    return int(time_hash, 16)
+    return int(uuid4().hex[-15:], 16)
 
 
 class ContentModel(ShpModel):
     """Base-Model for content with generalized properties."""
 
-    # id: UUID4 = Field(  # TODO: db-migration - temp fix for documentation
-    id: Union[UUID4, int] = Field(
+    id: int = Field(
         description="Unique ID",
-        default_factory=uuid4,
+        default_factory=id_default,
     )
     name: NameStr
     description: Annotated[Optional[SafeStr], Field(description="Required when public")] = None

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/content/_external_fixtures.yaml

@@ -1,7 +1,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.756999+02:00
   parameters:
-    id: 2639560972524229652
+    id: 263956097252422
     name: eenv_static_2000mV_10mA_3600s
     description: Artificial static Energy Environment, 2000mV, 10mA, 3600s
     comment: null
@@ -24,7 +24,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.764595+02:00
   parameters:
-    id: 9823394105967169626
+    id: 98233941059
     name: eenv_static_2000mV_1mA_3600s
     description: Artificial static Energy Environment, 2000mV, 1mA, 3600s
     comment: null
@@ -47,7 +47,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.772144+02:00
   parameters:
-    id: 3900615675169501222
+    id: 39006156751
     name: eenv_static_2000mV_50mA_3600s
     description: Artificial static Energy Environment, 2000mV, 50mA, 3600s
     comment: null
@@ -70,7 +70,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.779737+02:00
   parameters:
-    id: 14796673729431137386
+    id: 1479667372943113
     name: eenv_static_2000mV_5mA_3600s
     description: Artificial static Energy Environment, 2000mV, 5mA, 3600s
     comment: null
@@ -93,7 +93,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.787329+02:00
   parameters:
-    id: 6648482606607441403
+    id: 664848260660744
     name: eenv_static_3000mV_10mA_3600s
     description: Artificial static Energy Environment, 3000mV, 10mA, 3600s
     comment: null
@@ -116,7 +116,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.794922+02:00
   parameters:
-    id: 13566000951043177991
+    id: 1356600095104317
     name: eenv_static_3000mV_1mA_3600s
     description: Artificial static Energy Environment, 3000mV, 1mA, 3600s
     comment: null
@@ -139,7 +139,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.802410+02:00
   parameters:
-    id: 7977778327156610158
+    id: 797777832715661
     name: eenv_static_3000mV_50mA_3600s
     description: Artificial static Energy Environment, 3000mV, 50mA, 3600s
     comment: null
@@ -162,7 +162,7 @@
 - datatype: EnergyEnvironment
   created: 2025-05-12 17:28:39.810147+02:00
   parameters:
-    id: 4900162978999238419
+    id: 490016297899923
     name: eenv_static_3000mV_5mA_3600s
     description: Artificial static Energy Environment, 3000mV, 5mA, 3600s
     comment: null
@@ -269,7 +269,7 @@
 - datatype: Firmware
   created: 2025-05-12 17:28:39.851412+02:00
   parameters:
-    id: 7163917825449888392
+    id: 716391782544988
     name: nrf52_deep_sleep
     description: practically turned off MCU with the lowest possible consumption
     comment: null
@@ -325,7 +325,7 @@
 - datatype: Firmware
   created: 2025-05-12 17:28:39.868340+02:00
   parameters:
-    id: 3174430733058172825
+    id: 317443073305817
     name: nrf52_rf_survey
     description: Link Matrix Generator - TX-Unit - sends packet with every possible
       P_TX, loops until stopped
@@ -354,7 +354,7 @@
 - datatype: Firmware
   created: 2025-05-12 17:28:39.876819+02:00
   parameters:
-    id: 16381936580724580968
+    id: 1638193658072458
     name: nrf52_rf_test
     description: sends out 1 BLE-Packet per second (verify with an app like 'RaMBLE')
     comment: null

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/content/virtual_harvester.py

@@ -23,54 +23,283 @@ from .energy_environment import EnergyDType
 class AlgorithmDType(str, Enum):
     """Options for choosing a harvesting algorithm."""
 
-    direct = disable = neutral = "neutral"  # for just using IVTrace / samples
-    isc_voc = "isc_voc"  # only recordable ATM
+    direct = disable = neutral = "neutral"
+    """
+    Reads an energy environment as is without selecting a harvesting
+    voltage.
+
+    Used to play "constant-power" energy environments or simple
+    "on-off-patterns". Generally, not useful for virtual source
+    emulation.
+
+    Not applicable to real harvesting, only emulation with IVTrace / samples.
+    """
+
+    isc_voc = "isc_voc"
+    """
+    Short Circuit Current, Open Circuit Voltage.
+
+    This is not relevant for emulation, but used to configure recording of
+    energy environments.
+
+    This mode samples the two extremes of an IV curve, which may be
+    interesting to characterize a transducer/energy environment.
+
+    Not applicable to emulation - only recordable during harvest-recording ATM.
+    """
+
     ivcurve = ivcurves = ivsurface = "ivcurve"
+    """
+    Used during harvesting to record the full IV surface.
+
+    When configuring the energy environment recording, this algorithm
+    records the IV surface by repeatedly recording voltage and current
+    while ramping the voltage.
+
+    Cannot be used as output of emulation.
+    """
+
     constant = cv = "cv"
+    """
+    Harvest energy at a fixed predefined voltage ('voltage_mV').
+
+    For harvesting, this records the IV samples at the specified voltage.
+    For emulation, this virtually harvests the IV surface at the specified voltage.
+
+    In addition to constant voltage harvesting, this can be used together
+    with the 'feedback_to_hrv' flag to implement a "Capacitor and Diode"
+    topology, where the harvesting voltage depends dynamically on the
+    capacitor voltage.
+    """
+
     # ci .. constant current -> is this desired?
+
     mppt_voc = "mppt_voc"
+    """
+    Emulate a harvester with maximum power point (MPP) tracking based on
+    open circuit voltage measurements.
+
+    This MPPT heuristic estimates the MPP as a constant ratio of the open
+    circuit voltage.
+
+    Used in conjunction with 'setpoint_n', 'interval_ms', and 'duration_ms'.
+    """
+
     mppt_po = perturb_observe = "mppt_po"
+    """
+    Emulate a harvester with perturb and observe maximum power point
+    tracking.
+
+    This MPPT heuristic adjusts the harvesting voltage by small amounts and
+    checks if the power increases. Eventually, the tracking changes the
+    direction of adjustments and oscillates around the MPP.
+    """
+
     mppt_opt = optimal = "mppt_opt"
+    """
+    A theoretical harvester that identifies the MPP by reading it from the
+    IV curve during emulation.
 
+    Note that this is not possible for real-world harvesting as the system would
+    not know the entire IV curve. In that case a very fast and detailed mppt_po is
+    used.
+    """
 
-class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
-    """A vHrv makes a source-characterization (i.e. ivcurve) usable for the vSrc.
 
-    Mostly used when the file-based energy environment of the virtual source
-    is not already supplied as pre-harvested ivtrace.
+class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
+    """The virtual harvester configuration characterizes usage of an energy environment.
+
+    It is used to both harvesting during emulation and to record
+    energy environments (sometimes referred to as "harvesting traces").
+
+    For emulation:
+
+    The virtual harvester configuration describes how energy from a recorded
+    energy environment is harvested. Typically, the energy environment provides
+    an IV-surface, which is a continuous function in three dimensions: voltage,
+    current, and time. Based on this surface, the emulation can derive the
+    available IV-curve at each point in time. The harvester looks up the current
+    that is available (according to the energy environment) from a given
+    harvesting voltage. The harvesting voltage may be dynamically chosen by the
+    harvester based on the implemented harvesting algorithm, which models
+    different real-world harvesters. For example, a maximum power point tracking
+    harvester may choose a harvesting voltage as a ratio of the open circuit
+    voltage available from the energy environment (or transducer in practice).
+
+    The energy environments are encoded not as a three-dimensional function, but
+    as IV tuples over time (sampled at a constant frequency). This originates
+    from the technical implementation when recording the IV-surface, where the
+    recorder provides the IV-curve by measuring the current for a given voltage
+    and ramping the voltage from minimal to maximum.
+
+    For harvest-recordings:
+
+    An energy environment is fully described by the IV surface, which are IV
+    curves over time. Shepherd approximates this by sampling the current at
+    equidistant steps of a voltage ramp. The VirtualHarvesterConfig is also used
+    to parameterize the recording process, typically, it should be configured to
+    record a full IV surface, as this contains the full information of the energy
+    environment. The postponed harvesting is then performed during emulation.
+
+    However, it is also possible to record a "pre-harvested" energy environment
+    by performing the harvesting during recording. This results in a recording
+    containing IV samples over time that represent the harvesting voltage
+    (chosen by the virtual harvester during recording) and the current available
+    from the energy environment for that voltage. Together, these represent the
+    power available for harvesting at the time, and during emulation, this power
+    can be converted by the input stage (boost converter) to charge the energy
+    storage.
     """
 
     # General Metadata & Ownership -> ContentModel
 
     algorithm: AlgorithmDType
-    # ⤷ used to harvest energy
+    """The algorithm determines how the harvester chooses the harvesting voltage.
+    """
 
     samples_n: Annotated[int, Field(ge=8, le=2_000)] = 8
-    # ⤷ for & of ivcurve (and more?`)
+    """How many IV samples are measured for one IV curve.
+
+    The curve is recorded by measuring the el. current available from the
+    transducer at equidistant voltage intervals. These voltages are
+    probed by ramping between `voltage_min_mV` and `voltage_max_mV` at
+    `samples_n` points equally distributed over the voltage range. After
+    setting the voltage, the recorder waits for a short period - allowing
+    the analog frontend and transducer to settle - before recording the
+    harvesting current. This wait duration is influenced by
+    `wait_cycles`.
+
+    Selecting all these parameters is a tradeoff between accuracy of the IV
+    curve (density of IV samples) and measurement duration, hence the time
+    accuracy (density of points) of the IV-surface.
+
+    Only applicable to recording, not used in emulation.
+
+    Used together with `voltage_min_mV`, `voltage_max_mV`, `rising`, and
+    `wait_cycles`.
+    """
 
     voltage_mV: Annotated[float, Field(ge=0, le=5_000)] = 2_500
-    # ⤷ starting-point for some algorithms (mppt_po)
+    """The harvesting voltage for constant voltage harvesting.
+
+    Additionally, for Perturb-and-Observe MPPT, this defines the voltage at
+    startup.
+    """
+
     voltage_min_mV: Annotated[float, Field(ge=0, le=5_000)] = 0
+    """Minimum voltage recorded for the IV curve.
+
+    See `samples_n` for further details.
+
+    In emulation, this can be used to "block" parts of the recorded IV curve
+    and not utilize them in the virtual source. However, this is generally
+    discouraged as it can result in discontinuities in the curve and is not
+    well tested.
+    For emulation, this value ideally corresponds to the value of the
+    recorded energy environment.
+    """
+
     voltage_max_mV: Annotated[float, Field(ge=0, le=5_000)] = 5_000
+    """Maximum voltage sampled for the curve.
+
+    See `voltage_min_mV` and `samples_n`.
+    """
+
     current_limit_uA: Annotated[float, Field(ge=1, le=50_000)] = 50_000
-    # ⤷ allows to keep trajectory in special region (or constant current tracking)
-    # ⤷ boundary for detecting open circuit in emulated version (working on IV-Curves)
+    """
+    For MPPT VOC, the open circuit voltage is identified as the el. current
+    crosses below this threshold.
+
+    During recording it allows to keep trajectory in special region
+    (constant current tracking).
+    """
+
     voltage_step_mV: Optional[Annotated[float, Field(ge=1, le=1_000_000)]] = None
+    """The difference between two adjacent voltage samples.
+
+    This value is implicitly derived from the other ramp parameters:
+    (voltage_max_mV - voltage_min_mV) / (samples_n - 1)
+    """
 
     setpoint_n: Annotated[float, Field(ge=0, le=1.0)] = 0.70
-    # ⤷ ie. for mppt_voc
+    """
+    The "Open Circuit Voltage Maximum Power Point Tracker" estimates the MPP
+    by taking a constant fraction defined by this parameter of the open
+    circuit voltage. For example, if the IV curve shows an open circuit
+    voltage of 2V and the setpoint is 0.75, then the harvester selects
+    1.5 volts as the harvesting voltage.
+
+    This value is only relevant when 'algorithm == mppt_voc'.
+    """
+
     interval_ms: Annotated[float, Field(ge=0.01, le=1_000_000)] = 100
-    # ⤷ between start of measurements (ie. V_OC)
+    """The MPP is repeatedly estimated at fixed intervals defined by this duration.
+
+    Note that the energy environment can still change in between MPP
+    estimations, but the harvesting voltage is not updated in between.
+
+    This value is relevant for all MPP algorithms.
+    For Perturb and Observe, this value is the wait interval between steps.
+
+    When an energy environment is recorded with `mppt_opt`, the optimal
+    harvester is approximated with a very fast Perturb-Observe algorithm,
+    where this interval should be set to a very small value.
+    When emulating with `mppt_opt`, this value is not relevant as the
+    emulation simply picks the maximum power point from the IV-curve.
+    """
+
     duration_ms: Annotated[float, Field(ge=0.01, le=1_000_000)] = 0.1
-    # ⤷ of (open voltage) measurement
+    """The duration of MPP sampling.
+
+    While performing an MPP sampling every 'interval_ms', the input is
+    disconnected to accurately measure the open circuit voltage.
+
+    This value is only relevant for `mppt_voc`.
+    """
+
     rising: bool = True
-    # ⤷ direction of sawtooth
+    """Ramp direction for sampling the IV curve.
+
+    When set to true, sampling starts at the minimum voltage and ramps up to
+    the maximum.
+
+    See `samples_n` for further details.
+    Not relevant for emulation.
+    """
+
     enable_linear_extrapolation: bool = True
-    # ⤷ improves slow cv-algo that is base of most ivcurve-harvesters
-    #   (update-freq dependent on window-size)
+    """
+    Because the IV curve is not stored fully in PRU memory but streamed
+    sequentially to the PRU, looking up any IV value at any time is not
+    possible. However, because the precision of the emulation degrades
+    until the relevant IV sample passes by, it can extrapolate the available data
+    to estimate the required IV sample.
+
+    Enabling extrapolation can yield a better numeric simulation, especially
+    if the harvesting voltage changes rapidly or the IV surface is steep in
+    relevant regions. For example, when emulating a capacitor diode
+    setup and the current falls at high voltages.
+
+    This value is only relevant for emulation.
+    """
 
     # Underlying recorder
     wait_cycles: Annotated[int, Field(ge=0, le=100)] = 1
+    """
+    The wait duration to let the analog frontend settle before taking a
+    measurement.
+
+    When recording the energy environment, the voltage is set by the
+    digital-to-analog-converter. This parameter delays the current
+    measurement performed by the analog-to-digital converter to allow the
+    harvesting transducer to settle at the defined voltage.
+
+    When recording with `IscVoc`, wait cycles should be added as the analog
+    changes are more significant.
+
+    Not relevant for emulation.
+    """
+
     # ⤷ first cycle: ADC-Sampling & DAC-Writing, further steps: waiting
 
     @model_validator(mode="before")

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/content/virtual_source.py

@@ -70,6 +70,7 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     # ⤷ 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
+    # 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

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/experiment/experiment.py

@@ -5,17 +5,16 @@ 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.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.testbed.target import Target
 from shepherd_core.data_models.testbed.testbed import Testbed
@@ -29,8 +28,7 @@ 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)
+    id: int = Field(description="Unique ID", default_factory=id_default)
     # ⤷ TODO: automatic ID is problematic for identification by hash
 
     name: NameStr
@@ -51,7 +49,7 @@ class Experiment(ShpModel, title="Config of an Experiment"):
     # schedule
     time_start: Optional[datetime] = None  # = ASAP
     duration: Optional[timedelta] = None  # = till EOF
-    abort_on_error: bool = False
+    abort_on_error: Annotated[bool, deprecated("has no effect")] = False
 
     # targets
     target_configs: Annotated[list[TargetConfig], Field(min_length=1, max_length=128)]
@@ -61,6 +59,8 @@ class Experiment(ShpModel, title="Config of an Experiment"):
 
     @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_targets(self.target_configs)
         self._validate_observers(self.target_configs, testbed)

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/experiment/observer_features.py

@@ -6,12 +6,14 @@ 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
 
@@ -105,7 +107,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,17 +134,33 @@ 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)
@@ -150,31 +168,30 @@ class GpioTracing(ShpModel, title="Config for GPIO-Tracing"):
 
     # 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)
     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."""

{shepherd_core-2025.5.2 → shepherd_core-2025.5.3}/shepherd_core/data_models/experiment/target_config.py

@@ -18,7 +18,7 @@ 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
 
 
 class TargetConfig(ShpModel, title="Target Config"):
@@ -43,8 +43,8 @@ class TargetConfig(ShpModel, title="Target Config"):
 
     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: