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

shepherd_core/data_models/__init__.py

@@ -31,6 +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 UartLogging
 from .experiment.target_config import TargetConfig
 
 __all__ = [
@@ -54,6 +55,7 @@ __all__ = [
     "ShpModel",
     "SystemLogging",
     "TargetConfig",
+    "UartLogging",
     "VirtualHarvesterConfig",
     "VirtualSourceConfig",
     "Wrapper",

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/content/_external_fixtures.yaml

@@ -1,7 +1,7 @@
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.488609+02:00
+  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
@@ -22,9 +22,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.497654+02:00
+  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
@@ -45,9 +45,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.506739+02:00
+  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
@@ -68,9 +68,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.515790+02:00
+  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
@@ -91,9 +91,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.524761+02:00
+  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
@@ -114,9 +114,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.533513+02:00
+  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
@@ -137,9 +137,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.542278+02:00
+  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
@@ -160,9 +160,9 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2024-02-25 12:45:58.550974+02:00
+  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
@@ -183,7 +183,7 @@
     indoor: true
     location: Lab-VSrc
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.568363+02:00
+  created: 2025-05-12 17:28:39.825659+02:00
   parameters:
     id: 3000
     name: msp430_deep_sleep
@@ -198,10 +198,10 @@
     mcu:
       id: 1002
       name: MSP430FR
-      description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+      description: 16MHz Ultra-Low-Pwr MCU with 256 KB FRAM
       comment: null
       platform: MSP430
-      core: MSP430FR5962
+      core: MSP430FR5994
       prog_protocol: SBW
       prog_voltage: 3.0
       prog_datarate: 500000
@@ -211,7 +211,7 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.578594+02:00
+  created: 2025-05-12 17:28:39.834276+02:00
   parameters:
     id: 3001
     name: msp430_spi_fram
@@ -226,10 +226,10 @@
     mcu:
       id: 1002
       name: MSP430FR
-      description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+      description: 16MHz Ultra-Low-Pwr MCU with 256 KB FRAM
       comment: null
       platform: MSP430
-      core: MSP430FR5962
+      core: MSP430FR5994
       prog_protocol: SBW
       prog_voltage: 3.0
       prog_datarate: 500000
@@ -239,7 +239,7 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.589223+02:00
+  created: 2025-05-12 17:28:39.842993+02:00
   parameters:
     id: 3002
     name: msp430_testable
@@ -254,10 +254,10 @@
     mcu:
       id: 1002
       name: MSP430FR
-      description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+      description: 16MHz Ultra-Low-Pwr MCU with 256 KB FRAM
       comment: null
       platform: MSP430
-      core: MSP430FR5962
+      core: MSP430FR5994
       prog_protocol: SBW
       prog_voltage: 3.0
       prog_datarate: 500000
@@ -267,9 +267,9 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.599274+02:00
+  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
@@ -282,20 +282,20 @@
     mcu:
       id: 1001
       name: nRF52
-      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      description: MCU with RF, 802.15.4, Bluetooth v5.0, 2.4GHz
       comment: null
       platform: nRF52
       core: nRF52840
       prog_protocol: SWD
       prog_voltage: 3.0
       prog_datarate: 500000
-      fw_name_default: nrf52_demo_rf
+      fw_name_default: nrf52_deep_sleep
     data: /var/shepherd/content/fw/nes_lab/nrf52_deep_sleep/build.elf
     data_type: path_elf
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.609313+02:00
+  created: 2025-05-12 17:28:39.859962+02:00
   parameters:
     id: 2000
     name: nrf52_demo_rf
@@ -310,22 +310,22 @@
     mcu:
       id: 1001
       name: nRF52
-      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      description: MCU with RF, 802.15.4, Bluetooth v5.0, 2.4GHz
       comment: null
       platform: nRF52
       core: nRF52840
       prog_protocol: SWD
       prog_voltage: 3.0
       prog_datarate: 500000
-      fw_name_default: nrf52_demo_rf
+      fw_name_default: nrf52_deep_sleep
     data: /var/shepherd/content/fw/nes_lab/nrf52_demo_rf/build.elf
     data_type: path_elf
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.619155+02:00
+  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
@@ -339,22 +339,22 @@
     mcu:
       id: 1001
       name: nRF52
-      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      description: MCU with RF, 802.15.4, Bluetooth v5.0, 2.4GHz
       comment: null
       platform: nRF52
       core: nRF52840
       prog_protocol: SWD
       prog_voltage: 3.0
       prog_datarate: 500000
-      fw_name_default: nrf52_demo_rf
+      fw_name_default: nrf52_deep_sleep
     data: /var/shepherd/content/fw/nes_lab/nrf52_rf_survey/build.elf
     data_type: path_elf
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.628815+02:00
+  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
@@ -367,20 +367,20 @@
     mcu:
       id: 1001
       name: nRF52
-      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      description: MCU with RF, 802.15.4, Bluetooth v5.0, 2.4GHz
       comment: null
       platform: nRF52
       core: nRF52840
       prog_protocol: SWD
       prog_voltage: 3.0
       prog_datarate: 500000
-      fw_name_default: nrf52_demo_rf
+      fw_name_default: nrf52_deep_sleep
     data: /var/shepherd/content/fw/nes_lab/nrf52_rf_test/build.elf
     data_type: path_elf
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2024-02-25 12:45:58.638812+02:00
+  created: 2025-05-12 17:28:39.885271+02:00
   parameters:
     id: 2002
     name: nrf52_testable
@@ -396,14 +396,14 @@
     mcu:
       id: 1001
       name: nRF52
-      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      description: MCU with RF, 802.15.4, Bluetooth v5.0, 2.4GHz
       comment: null
       platform: nRF52
       core: nRF52840
       prog_protocol: SWD
       prog_voltage: 3.0
       prog_datarate: 500000
-      fw_name_default: nrf52_demo_rf
+      fw_name_default: nrf52_deep_sleep
     data: /var/shepherd/content/fw/nes_lab/nrf52_testable/build.elf
     data_type: path_elf
     data_hash: null

shepherd_core/data_models/content/energy_environment.py

@@ -15,8 +15,8 @@ from shepherd_core.testbed_client import tb_client
 class EnergyDType(str, Enum):
     """Data-Type-Options for energy environments."""
 
-    ivsample = ivsamples = "ivsample"
-    ivcurve = ivcurves = ivsurface = "ivcurve"
+    ivtrace = ivsample = ivsamples = "ivsample"
+    ivsurface = ivcurve = ivcurves = "ivcurve"
     isc_voc = "isc_voc"
 
 

shepherd_core/data_models/content/virtual_harvester.py

@@ -24,53 +24,282 @@ class AlgorithmDType(str, Enum):
     """Options for choosing a harvesting algorithm."""
 
     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"
-    ivcurve = ivcurves = ("ivcurve",)
+    """
+    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 ivsample-stream.
+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/data_models/content/virtual_harvester_fixture.yaml

@@ -21,7 +21,7 @@
   parameters:
     id: 1100
     name: ivcurve
-    description: Postpone harvesting by sampling ivcurves (voltage stepped as sawtooth-wave)
+    description: Postpone harvesting by sampling ivsurface / curves (voltage stepped as sawtooth-wave)
     comment: ~110 Hz, Between 50 & 60 Hz line-frequency to avoid standing waves
     inherit_from: neutral
     algorithm: ivcurve
@@ -36,7 +36,7 @@
 - datatype: VirtualHarvesterConfig
   parameters:
     id: 1101
-    name: ivcurves  # synonym
+    name: ivsurface  # synonym
     inherit_from: ivcurve
 
 - datatype: VirtualHarvesterConfig