shepherd-core 2023.12.1__py3-none-any.whl → 2024.4.2__py3-none-any.whl

shepherd_core/data_models/content/_external_fixtures.yaml

@@ -1,11 +1,12 @@
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.779899
+  created: 2024-02-25 12:45:58.488609+02:00
   parameters:
     id: 2639560972524229652
     name: eenv_static_2000mV_10mA_3600s
     description: Artificial static Energy Environment, 2000mV, 10mA, 3600s
     comment: null
     created: 2023-09-27 19:27:02.177941
+    updated_last: 2024-02-25 11:32:34.140144
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -21,13 +22,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.783398
+  created: 2024-02-25 12:45:58.497654+02:00
   parameters:
     id: 9823394105967169626
     name: eenv_static_2000mV_1mA_3600s
     description: Artificial static Energy Environment, 2000mV, 1mA, 3600s
     comment: null
     created: 2023-09-27 19:28:37.291941
+    updated_last: 2024-02-25 11:33:54.292910
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -43,13 +45,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.786899
+  created: 2024-02-25 12:45:58.506739+02:00
   parameters:
     id: 3900615675169501222
     name: eenv_static_2000mV_50mA_3600s
     description: Artificial static Energy Environment, 2000mV, 50mA, 3600s
     comment: null
     created: 2023-09-27 19:26:18.621440
+    updated_last: 2024-02-25 11:31:53.183281
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -65,13 +68,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.790399
+  created: 2024-02-25 12:45:58.515790+02:00
   parameters:
     id: 14796673729431137386
     name: eenv_static_2000mV_5mA_3600s
     description: Artificial static Energy Environment, 2000mV, 5mA, 3600s
     comment: null
     created: 2023-09-27 19:27:48.976440
+    updated_last: 2024-02-25 11:33:15.250555
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -87,13 +91,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.793899
+  created: 2024-02-25 12:45:58.524761+02:00
   parameters:
     id: 6648482606607441403
     name: eenv_static_3000mV_10mA_3600s
     description: Artificial static Energy Environment, 3000mV, 10mA, 3600s
     comment: null
     created: 2023-09-27 19:24:02.885439
+    updated_last: 2024-02-25 11:29:52.671833
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -109,13 +114,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.796898
+  created: 2024-02-25 12:45:58.533513+02:00
   parameters:
     id: 13566000951043177991
     name: eenv_static_3000mV_1mA_3600s
     description: Artificial static Energy Environment, 3000mV, 1mA, 3600s
     comment: null
     created: 2023-09-27 19:25:32.729442
+    updated_last: 2024-02-25 11:31:12.003732
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -131,13 +137,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.800400
+  created: 2024-02-25 12:45:58.542278+02:00
   parameters:
     id: 7977778327156610158
     name: eenv_static_3000mV_50mA_3600s
     description: Artificial static Energy Environment, 3000mV, 50mA, 3600s
     comment: null
     created: 2023-09-27 19:23:18.980940
+    updated_last: 2024-02-25 11:29:12.185905
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -153,13 +160,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: EnergyEnvironment
-  created: 2023-09-27 19:51:44.803899
+  created: 2024-02-25 12:45:58.550974+02:00
   parameters:
     id: 4900162978999238419
     name: eenv_static_3000mV_5mA_3600s
     description: Artificial static Energy Environment, 3000mV, 5mA, 3600s
     comment: null
     created: 2023-09-27 19:24:47.092941
+    updated_last: 2024-02-25 11:30:33.170119
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -175,13 +183,14 @@
     indoor: true
     location: Lab-VSrc
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.816899
+  created: 2024-02-25 12:45:58.568363+02:00
   parameters:
     id: 3000
     name: msp430_deep_sleep
     description: practically turned off MCU with the lowest possible consumption
     comment: null
     created: 2022-12-12 12:12:12
+    updated_last: 2024-02-25 11:45:58.563335
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -202,13 +211,14 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.820399
+  created: 2024-02-25 12:45:58.578594+02:00
   parameters:
     id: 3001
     name: msp430_spi_fram
     description: riotee implementation to use MSP as a flash storage
     comment: null
     created: 2022-12-12 12:12:12
+    updated_last: 2024-02-25 11:45:58.573327
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -229,13 +239,14 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.823899
+  created: 2024-02-25 12:45:58.589223+02:00
   parameters:
     id: 3002
     name: msp430_testable
     description: switches on all shared gpio one by one (verification after assembly)
     comment: null
     created: 2022-12-12 12:12:12
+    updated_last: 2024-02-25 11:45:58.583701
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -256,13 +267,14 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.827399
+  created: 2024-02-25 12:45:58.599274+02:00
   parameters:
     id: 7163917825449888392
     name: nrf52_deep_sleep
     description: practically turned off MCU with the lowest possible consumption
     comment: null
     created: 2023-09-13 21:01:52.815691
+    updated_last: 2024-02-25 11:45:58.594236
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -283,13 +295,14 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.831400
+  created: 2024-02-25 12:45:58.609313+02:00
   parameters:
     id: 2000
     name: nrf52_demo_rf
     description: A simple demo that sends BLE packets when energy budget allows it
     comment: null
     created: 2022-12-12 12:12:12
+    updated_last: 2024-02-25 11:45:58.604324
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -310,7 +323,7 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.834899
+  created: 2024-02-25 12:45:58.619155+02:00
   parameters:
     id: 3174430733058172825
     name: nrf52_rf_survey
@@ -318,6 +331,7 @@
       P_TX, loops until stopped
     comment: null
     created: 2023-09-13 21:01:53.308666
+    updated_last: 2024-02-25 11:45:58.614199
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -338,13 +352,14 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.838398
+  created: 2024-02-25 12:45:58.628815+02:00
   parameters:
     id: 16381936580724580968
     name: nrf52_rf_test
     description: sends out 1 BLE-Packet per second (verify with an app like 'RaMBLE')
     comment: null
     created: 2023-09-13 21:01:53.575861
+    updated_last: 2024-02-25 11:45:58.623974
     owner: Ingmar
     group: NES_Lab
     visible2group: true
@@ -365,7 +380,7 @@
     data_hash: null
     data_local: false
 - datatype: Firmware
-  created: 2023-09-27 19:51:44.841899
+  created: 2024-02-25 12:45:58.638812+02:00
   parameters:
     id: 2002
     name: nrf52_testable
@@ -373,6 +388,7 @@
       assembly)
     comment: null
     created: 2022-12-12 12:12:12
+    updated_last: 2024-02-25 11:45:58.633957
     owner: Ingmar
     group: NES_Lab
     visible2group: true

shepherd_core/data_models/content/energy_environment.py

@@ -1,3 +1,5 @@
+"""Data-model for recorded eEnvs."""
+
 from enum import Enum
 from pathlib import Path
 from typing import Optional
@@ -10,15 +12,15 @@ from ..base.content import ContentModel
 
 
 class EnergyDType(str, Enum):
-    ivsample = "ivsample"
-    ivsamples = "ivsample"
-    ivcurve = "ivcurve"
-    ivcurves = "ivcurve"
+    """Data-Type-Options for energy environments."""
+
+    ivsample = ivsamples = "ivsample"
+    ivcurve = ivcurves = ivsurface = "ivcurve"
     isc_voc = "isc_voc"
 
 
 class EnergyEnvironment(ContentModel):
-    """Recording of meta-data representation of a testbed-component"""
+    """Recording of meta-data representation of a testbed-component."""
 
     # General Metadata & Ownership -> ContentModel
 

shepherd_core/data_models/content/energy_environment_fixture.yaml

@@ -14,6 +14,7 @@
     visible2group: true
     visible2all: true
     created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12
 
 - datatype: EnergyEnvironment
   parameters:
@@ -31,6 +32,7 @@
     visible2group: true
     visible2all: true
     created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12
 
 - datatype: EnergyEnvironment
   parameters:
@@ -48,3 +50,4 @@
     visible2group: true
     visible2all: true
     created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12

shepherd_core/data_models/content/firmware.py

@@ -1,3 +1,8 @@
+"""Handling firmware for targets.
+
+TODO: should be more generalized - currently only supports msp & nRF
+"""
+
 from pathlib import Path
 from typing import Optional
 from typing import TypedDict
@@ -45,7 +50,7 @@ FirmwareStr = Annotated[str, StringConstraints(min_length=3, max_length=8_000_00
 
 
 class Firmware(ContentModel, title="Firmware of Target"):
-    """meta-data representation of a data-component"""
+    """meta-data representation of a data-component."""
 
     # General Metadata & Ownership -> ContentModel
 
@@ -91,9 +96,10 @@ class Firmware(ContentModel, title="Firmware of Target"):
         embed: bool = True,
         **kwargs: Unpack[TypedDict],
     ) -> Self:
-        """Embeds firmware and tries to fill parameters
+        """Embeds firmware and tries to fill parameters.
+
         ELF -> mcu und data_type are deducted
-        HEX -> must supply mcu manually
+        HEX -> must supply mcu manually.
         """
         # TODO: use new determine_type() & determine_arch() and also allow to not embed
         kwargs["data_hash"] = fw_tools.file_to_hash(file)
@@ -113,7 +119,7 @@ class Firmware(ContentModel, title="Firmware of Target"):
             elif fw_tools.is_hex_nrf52(file):
                 arch = "nrf52"
             else:
-                raise ValueError("File is not a HEX for the Testbed")
+                raise ValueError("File is not a suitable HEX for the Testbed")
             if "mcu" not in kwargs:
                 kwargs["mcu"] = arch_to_mcu[arch]
 
@@ -150,7 +156,8 @@ class Firmware(ContentModel, title="Firmware of Target"):
 
     @validate_call
     def extract_firmware(self, file: Path) -> Path:
-        """Stores embedded data in file
+        """Store embedded fw-data in file.
+
         - file-suffix is derived from data-type and adapted
         - if provided path is a directory, the firmware-name is used
         """

shepherd_core/data_models/content/firmware_datatype.py

@@ -1,7 +1,14 @@
+"""Separated data-type.
+
+Done due to cyclic inheritance.
+"""
+
 from enum import Enum
 
 
 class FirmwareDType(str, Enum):
+    """Options for firmware-types."""
+
     base64_hex = "hex"
     base64_elf = "elf"
     path_hex = "path_hex"

shepherd_core/data_models/content/virtual_harvester.py

@@ -1,3 +1,5 @@
+"""Generalized energy harvester data models."""
+
 from enum import Enum
 from typing import Optional
 from typing import Tuple
@@ -17,22 +19,22 @@ from .energy_environment import EnergyDType
 
 
 class AlgorithmDType(str, Enum):
+    """Options for choosing a harvesting algorithm."""
+
     isc_voc = "isc_voc"
-    ivcurve = ("ivcurve",)
-    ivcurves = ("ivcurve",)
-    cv = "cv"
-    constant = "cv"
+    ivcurve = ivcurves = ("ivcurve",)
+    constant = cv = "cv"
     # ci .. constant current -> is this desired?
     mppt_voc = "mppt_voc"
-    mppt_po = "mppt_po"
-    perturb_observe = "mppt_po"
-    mppt_opt = "mppt_opt"
-    optimal = "mppt_opt"
+    mppt_po = perturb_observe = "mppt_po"
+    mppt_opt = optimal = "mppt_opt"
 
 
 class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
-    """A Harvester is needed when the file-based energy environment
-    of the virtual source is not already supplied as ivsample
+    """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.
     """
 
     # General Metadata & Ownership -> ContentModel
@@ -76,7 +78,7 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
         logger.debug("VHrv-Inheritances: %s", chain)
 
         # post corrections -> should be in separate validator
-        cal = CalibrationHarvester()  # todo: as argument?
+        cal = CalibrationHarvester()  # TODO: as argument?
         c_limit = values.get("current_limit_uA", 50_000)  # cls.current_limit_uA)
         values["current_limit_uA"] = max(10**6 * cal.adc_C_Hrv.raw_to_si(4), c_limit)
 
@@ -110,19 +112,21 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
     def calc_algorithm_num(self, *, for_emu: bool) -> int:
         num = algo_to_num.get(self.algorithm)
         if for_emu and self.get_datatype() != EnergyDType.ivsample:
-            raise ValueError(
+            msg = (
                 f"[{self.name}] Select valid harvest-algorithm for emulator, "
-                f"current usage = {self.algorithm}",
+                f"current usage = {self.algorithm}"
             )
+            raise ValueError(msg)
         if num < algo_to_num["isc_voc"]:
-            raise ValueError(
+            msg = (
                 f"[{self.name}] Select valid harvest-algorithm for harvester, "
-                f"current usage = {self.algorithm}",
+                f"current usage = {self.algorithm}"
             )
+            raise ValueError(msg)
         return num
 
     def calc_timings_ms(self, *, for_emu: bool) -> Tuple[float, float]:
-        """factor-in model-internal timing-constraints"""
+        """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
         if for_emu:
@@ -155,7 +159,7 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
             if dtype_in == EnergyDType.ivsample:
                 return 0
             # isc_voc: 2 * (1 + wait_cycles), noqa
-            raise ValueError("Not Implemented")
+            raise NotImplementedError
 
         # only used by ivcurve algo (in ADC-Mode)
         return self.samples_n
@@ -191,11 +195,12 @@ algo_to_dtype = {
 
 
 class HarvesterPRUConfig(ShpModel):
-    """Map settings-list to internal state-vars struct HarvesterConfig
+    """Map settings-list to internal state-vars struct HarvesterConfig for PRU.
+
     NOTE:
       - yaml is based on si-units like nA, mV, ms, uF
       - c-code and py-copy is using nA, uV, ns, nF, fW, raw
-      - ordering is intentional and in sync with shepherd/commons.h
+      - ordering is intentional and in sync with shepherd/commons.h.
     """
 
     algorithm: u32
@@ -228,7 +233,7 @@ class HarvesterPRUConfig(ShpModel):
         if isinstance(dtype_in, str):
             dtype_in = EnergyDType[dtype_in]
         if for_emu and dtype_in not in {EnergyDType.ivsample, EnergyDType.ivcurve}:
-            raise ValueError("Not Implemented")
+            raise NotImplementedError
         # TODO: use dtype properly in shepherd
         interval_ms, duration_ms = data.calc_timings_ms(for_emu=for_emu)
         return cls(

shepherd_core/data_models/content/virtual_harvester_fixture.yaml

@@ -12,6 +12,7 @@
     visible2group: true
     visible2all: true
     created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12
 
 - datatype: VirtualHarvesterConfig
   parameters:

shepherd_core/data_models/content/virtual_source.py

@@ -1,3 +1,5 @@
+"""Generalized virtual source data models."""
+
 from typing import List
 
 from pydantic import Field
@@ -8,8 +10,8 @@ from typing_extensions import Self
 from ...commons import samplerate_sps_default
 from ...logger import logger
 from ...testbed_client import tb_client
-from .. import ShpModel
 from ..base.content import ContentModel
+from ..base.shepherd import ShpModel
 from .virtual_harvester import HarvesterPRUConfig
 from .virtual_harvester import VirtualHarvesterConfig
 
@@ -21,16 +23,19 @@ LUT2D = Annotated[List[LUT1D], Field(min_length=LUT_SIZE, max_length=LUT_SIZE)]
 
 
 class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
-    """The virtual Source uses the energy environment (file)
-    for supplying the Target Node during the experiment.
-    If not already done, the energy will be harvested and then converted.
+    """The vSrc uses the energy environment (file) for supplying the Target Node.
+
+    If not already done, the energy will be harvested and
+    then converted during the experiment.
+
     The converter-stage is software defined and offers:
-      buck-boost-combinations,
-      a simple diode + resistor and
-      an intermediate buffer capacitor.
-      TODO: I,V,R should be in regular unit (V, A, Ohm)
+    - buck-boost-combinations,
+    - a simple diode + resistor and
+    - an intermediate buffer capacitor.
     """
 
+    # TODO: I,V,R should be in regular unit (V, A, Ohm)
+
     # General Metadata & Ownership -> ContentModel
 
     enable_boost: bool = False
@@ -116,21 +121,30 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         return self
 
     def calc_internal_states(self) -> dict:
-        """Compensate for (hard to detect) current-surge of real capacitors
-        when converter gets turned on -> this can be const value, because
-        the converter always turns on with "V_storage_enable_threshold_uV"
+        """Update the model-states for the capacitor and other elements.
+
+        This also compensates for current-surge of real capacitors
+        when the converter gets turned on:
+
+        - surges are hard to detect & record
+        - this can be const value, because
+        - the converter always turns on with "V_storage_enable_threshold_uV".
+
         TODO: currently neglecting delay after disabling converter, boost
         only has simpler formula, second enabling when V_Cap >= V_out
 
         Math behind this calculation:
-        Energy-Change Storage Cap   ->  E_new = E_old - E_output
-        with Energy of a Cap 	    -> 	E_x = C_x * V_x^2 / 2
-        combine formulas 		    ->
-                    C_store * V_store_new^2 / 2 = C_store * V_store_old^2 / 2 - C_out * V_out^2 / 2
-        convert formula to V_new 	->	V_store_new^2 = V_store_old^2 - (C_out / C_store) * V_out^2
-        convert into dV	 	        ->	dV = V_store_new - V_store_old
-        in case of V_cap = V_out 	-> 	dV = V_store_old * (sqrt(1 - C_out / C_store) - 1)
-        -> dV values will be reversed (negated), because dV is always negative (Voltage drop)
+
+        - Energy-Change Storage Cap ->  E_new = E_old - E_output
+        - with Energy of a Cap 	    -> 	E_x = C_x * V_x^2 / 2
+        - combine formulas 		    ->  C_store * V_store_new^2 / 2 =
+          C_store * V_store_old^2 / 2 - C_out * V_out^2 / 2
+        - convert formula to V_new 	->	V_store_new^2 =
+          V_store_old^2 - (C_out / C_store) * V_out^2
+        - convert into dV	 	        ->	dV = V_store_new - V_store_old
+        - in case of V_cap = V_out 	-> 	dV = V_store_old * (sqrt(1 - C_out / C_store) - 1)
+
+        Note: dV values will be reversed (negated), because dV is always negative (Voltage drop)
         """
         values = {}
         if self.C_intermediate_uF > 0 and self.C_output_uF > 0:
@@ -185,9 +199,10 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         return values
 
     def calc_converter_mode(self, *, log_intermediate_node: bool) -> int:
-        """Assembles bitmask from discrete values
+        """Assembles bitmask from discrete values.
+
         log_intermediate_node: record / log virtual intermediate (cap-)voltage and
-                            -current (out) instead of output-voltage and -current
+        -current (out) instead of output-voltage and -current
         """
         enable_storage = self.C_intermediate_uF > 0
         enable_boost = self.enable_boost and enable_storage
@@ -199,7 +214,8 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         )
 
     def calc_cap_constant_us_per_nF_n28(self) -> int:
-        """Calc constant to convert capacitor-current to Voltage-delta
+        """Calc constant to convert capacitor-current to Voltage-delta.
+
         dV[uV] = constant[us/nF] * current[nA] = constant[us*V/nAs] * current[nA]
         """
         C_cap_uF = max(self.C_intermediate_uF, 0.001)
@@ -219,7 +235,8 @@ lut_o = Annotated[List[u32], Field(min_length=LUT_SIZE, max_length=LUT_SIZE)]
 
 
 class ConverterPRUConfig(ShpModel):
-    """Map settings-list to internal state-vars struct ConverterConfig
+    """Map settings-list to internal state-vars struct ConverterConfig.
+
     NOTE:
       - yaml is based on si-units like nA, mV, ms, uF
       - c-code and py-copy is using nA, uV, ns, nF, fW, raw

shepherd_core/data_models/content/virtual_source_fixture.yaml

@@ -72,6 +72,7 @@
     visible2group: true
     visible2all: true
     created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12
 
 - datatype: VirtualSourceConfig
   parameters:

shepherd_core/data_models/experiment/__init__.py

@@ -1,4 +1,8 @@
-from ..testbed.cape import TargetPort
+"""Module for experiment related data-models.
+
+These models import externally from: /base, /content, /testbed.
+"""
+
 from .experiment import Experiment
 from .observer_features import GpioActuation
 from .observer_features import GpioEvent
@@ -8,8 +12,6 @@ from .observer_features import PowerTracing
 from .observer_features import SystemLogging
 from .target_config import TargetConfig
 
-# these models import externally from: /base, /content, /testbed
-
 __all__ = [
     "Experiment",
     "TargetConfig",
@@ -21,5 +23,4 @@ __all__ = [
     "SystemLogging",
     # Enums
     "GpioLevel",
-    "TargetPort",
 ]