shepherd-core 2024.4.1__py3-none-any.whl → 2024.5.1__py3-none-any.whl

shepherd_core/data_models/content/_external_fixtures.yaml

@@ -0,0 +1,410 @@
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_2000mV_10mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 72.00000003599966
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_2000mV_1mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 7.200000003599944
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_2000mV_50mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 360.00000018000185
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_2000mV_5mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 36.00000001799983
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_3000mV_10mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 107.999999999999
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_3000mV_1mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 10.799999999999885
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_3000mV_50mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 539.9999999999999
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: EnergyEnvironment
+  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
+    visible2all: true
+    data_path: /var/shepherd/content/eenv/nes_lab/eenv_static_3000mV_5mA_3600s.h5
+    data_type: ivsample
+    data_local: false
+    duration: 3600.0
+    energy_Ws: 53.9999999999995
+    valid: true
+    light_source: null
+    weather_conditions: null
+    indoor: true
+    location: Lab-VSrc
+- datatype: Firmware
+  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
+    visible2all: true
+    mcu:
+      id: 1002
+      name: MSP430FR
+      description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+      comment: null
+      platform: MSP430
+      core: MSP430FR5962
+      prog_protocol: SBW
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: msp430_deep_sleep
+    data: /var/shepherd/content/fw/nes_lab/msp430_deep_sleep/build.elf
+    data_type: path_elf
+    data_hash: null
+    data_local: false
+- datatype: Firmware
+  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
+    visible2all: true
+    mcu:
+      id: 1002
+      name: MSP430FR
+      description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+      comment: null
+      platform: MSP430
+      core: MSP430FR5962
+      prog_protocol: SBW
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: msp430_deep_sleep
+    data: /var/shepherd/content/fw/nes_lab/msp430_spi_fram/build.elf
+    data_type: path_elf
+    data_hash: null
+    data_local: false
+- datatype: Firmware
+  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
+    visible2all: true
+    mcu:
+      id: 1002
+      name: MSP430FR
+      description: 16MHz Ultra-Low-Pwr MCU with 128 KB FRAM
+      comment: null
+      platform: MSP430
+      core: MSP430FR5962
+      prog_protocol: SBW
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: msp430_deep_sleep
+    data: /var/shepherd/content/fw/nes_lab/msp430_testable/build.elf
+    data_type: path_elf
+    data_hash: null
+    data_local: false
+- datatype: Firmware
+  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
+    visible2all: true
+    mcu:
+      id: 1001
+      name: nRF52
+      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      comment: null
+      platform: nRF52
+      core: nRF52840
+      prog_protocol: SWD
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: nrf52_demo_rf
+    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
+  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
+    visible2all: true
+    mcu:
+      id: 1001
+      name: nRF52
+      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      comment: null
+      platform: nRF52
+      core: nRF52840
+      prog_protocol: SWD
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: nrf52_demo_rf
+    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
+  parameters:
+    id: 3174430733058172825
+    name: nrf52_rf_survey
+    description: Link Matrix Generator - TX-Unit - sends packet with every possible
+      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
+    visible2all: true
+    mcu:
+      id: 1001
+      name: nRF52
+      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      comment: null
+      platform: nRF52
+      core: nRF52840
+      prog_protocol: SWD
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: nrf52_demo_rf
+    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
+  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
+    visible2all: true
+    mcu:
+      id: 1001
+      name: nRF52
+      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      comment: null
+      platform: nRF52
+      core: nRF52840
+      prog_protocol: SWD
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: nrf52_demo_rf
+    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
+  parameters:
+    id: 2002
+    name: nrf52_testable
+    description: watches all gpio and reports with UART messages (verification after
+      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
+    visible2all: true
+    mcu:
+      id: 1001
+      name: nRF52
+      description: Panasonic PAN1780, ENW-89854A1KF, Bluetooth 5 Low Energy Module
+      comment: null
+      platform: nRF52
+      core: nRF52840
+      prog_protocol: SWD
+      prog_voltage: 3.0
+      prog_datarate: 500000
+      fw_name_default: nrf52_demo_rf
+    data: /var/shepherd/content/fw/nes_lab/nrf52_testable/build.elf
+    data_type: path_elf
+    data_hash: null
+    data_local: false

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"  # a stream could also be called iv-surface
+    """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

@@ -0,0 +1,53 @@
+- datatype: EnergyEnvironment
+  parameters:
+    id: 1001
+    name: SolarSunny
+    description: MOCKUP! Sunny Day with 4 sq-cm Solar Cell
+    data_path: eenv/group/user/solar_4h_new.h5
+    data_type: ivsample
+    duration: 14400
+    energy_Ws: 0.5
+    valid: true
+
+    owner: Ingmar
+    group: NES Lab
+    visible2group: true
+    visible2all: true
+    created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12
+
+- datatype: EnergyEnvironment
+  parameters:
+    id: 1002
+    name: ThermoelectricWashingMachine
+    description: MOCKUP! Energy harvested from side of machine during washing  & tumbling
+    data_path: eenv/group/user/thermoelectric_1h_wash.h5
+    data_type: ivcurve
+    duration: 3600
+    energy_Ws: 0.1
+    valid: true
+
+    owner: Ingmar
+    group: NES Lab
+    visible2group: true
+    visible2all: true
+    created: 2022-12-12 12:12:12
+    updated_last: 2022-12-12 12:12:12
+
+- datatype: EnergyEnvironment
+  parameters:
+    id: 666
+    name: nuclear
+    description: MOCKUP! Energy harvested
+    data_path: eenv/group/user/thermoelectric_1h_wash.h5
+    data_type: ivcurve
+    duration: 3600
+    energy_Ws: 0.1
+    valid: false
+
+    owner: Ingmar
+    group: NES Lab
+    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
@@ -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(