shepherd-core 2025.5.2__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/__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/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/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/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/_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/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
@@ -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")
@@ -134,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)
@@ -224,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(
@@ -288,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,
         )