shepherd-core 2024.8.2__tar.gz → 2024.9.1__tar.gz

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: shepherd_core
-Version: 2024.8.2
+Version: 2024.9.1
 Summary: Programming- and CLI-Interface for the h5-dataformat of the Shepherd-Testbed
 Author-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
 Maintainer-email: Ingmar Splitt <ingmar.splitt@tu-dresden.de>
@@ -23,6 +23,7 @@ Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Natural Language :: English
@@ -119,11 +120,11 @@ These pydantic data-models are used throughout all shepherd interfaces. Users ca
 
 ## Compatibility
 
-| OS      |   PyVersion  | Comment                                    |
-|---------|--------------|--------------------------------------------|
-| Ubuntu  | 3.8 - 3.12   |                                            |
-| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
-| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+| OS      | PyVersion  | Comment                                    |
+|---------|------------|--------------------------------------------|
+| Ubuntu  | 3.8 - 3.13 |                                            |
+| Windows | 3.8 - 3.13 | no support for elf and hex-conversions yet |
+| MacOS   | 3.8 - 3.13 | hex-conversion missing                     |
 
 Notes:
 - hex-conversion needs a working and accessible objcopy
@@ -147,7 +148,7 @@ For bleeding-edge-features or dev-work it is possible to install directly from G
 ```Shell
 pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U
 # and on sheep with newer debian
-pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U --break-system-packages
+sudo pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U --break-system-packages
 ```
 
 If you are working with ``.elf``-files (embedding into experiments) you make "objcopy" accessible to python. In Ubuntu, you can either install ``build-essential`` or ``binutils-$ARCH`` with arch being ``msp430`` or ``arm-none-eabi`` for the nRF52.

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/README.md

@@ -63,11 +63,11 @@ These pydantic data-models are used throughout all shepherd interfaces. Users ca
 
 ## Compatibility
 
-| OS      |   PyVersion  | Comment                                    |
-|---------|--------------|--------------------------------------------|
-| Ubuntu  | 3.8 - 3.12   |                                            |
-| Windows | 3.8 - 3.12   | no support for elf and hex-conversions yet |
-| MacOS   | 3.8 - 3.12   | hex-conversion missing                     |
+| OS      | PyVersion  | Comment                                    |
+|---------|------------|--------------------------------------------|
+| Ubuntu  | 3.8 - 3.13 |                                            |
+| Windows | 3.8 - 3.13 | no support for elf and hex-conversions yet |
+| MacOS   | 3.8 - 3.13 | hex-conversion missing                     |
 
 Notes:
 - hex-conversion needs a working and accessible objcopy
@@ -91,7 +91,7 @@ For bleeding-edge-features or dev-work it is possible to install directly from G
 ```Shell
 pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U
 # and on sheep with newer debian
-pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U --break-system-packages
+sudo pip install git+https://github.com/orgua/shepherd-datalib.git@dev#subdirectory=shepherd_core -U --break-system-packages
 ```
 
 If you are working with ``.elf``-files (embedding into experiments) you make "objcopy" accessible to python. In Ubuntu, you can either install ``build-essential`` or ``binutils-$ARCH`` with arch being ``msp430`` or ``arm-none-eabi`` for the nRF52.

shepherd_core-2024.9.1/examples/simulate_vsource.py

@@ -0,0 +1,72 @@
+"""Demonstrate behavior of Virtual Source Algorithms.
+
+The emulation recreates an observer-cape, the virtual Source and a virtual target
+- input = hdf5-file with a harvest-recording
+- output = hdf5-file
+- config is currently hardcoded, but it could be an emulation-task
+- target is currently a simple resistor
+
+The output file can be analyzed and plotted with shepherds tool suite.
+
+Output:
+E_out = 220.001 mWs -> direct (no current-limit)
+E_out = 13.142 mWs -> diode+capacitor
+E_out = 13.066 mWs -> diode+resistor+capacitor
+E_out = 15.045 mWs -> BQ25504
+E_out = 14.962 mWs -> BQ25504s
+E_out = 14.397 mWs -> BQ25570
+E_out = 14.232 mWs -> BQ25570s
+
+"""
+
+from pathlib import Path
+
+from shepherd_core.data_models import VirtualSourceConfig
+from shepherd_core.vsource import ResistiveTarget
+from shepherd_core.vsource import simulate_source
+from shepherd_data import Reader
+
+# config simulation
+file_input = Path(__file__).parent / "jogging_ivcurve.h5"
+
+src_list = [
+    "direct",
+    "diode+capacitor",
+    "diode+resistor+capacitor",
+    "BQ25504",
+    "BQ25504s",
+    "BQ25570",
+    "BQ25570s",
+]
+tgt = ResistiveTarget(R_Ohm=1_000, controlled=True)
+save_files = True
+
+for src_name in src_list:
+    file_output = (
+        file_input.with_name(file_input.stem + "_emu_" + src_name + file_input.suffix)
+        if save_files
+        else None
+    )
+
+    e_out_Ws = simulate_source(
+        config=VirtualSourceConfig(
+            name=src_name,
+            C_output_uF=0,
+            V_intermediate_enable_threshold_mV=1,
+            V_intermediate_disable_threshold_mV=0,
+            # jogging-dataset has max VOC of ~1.6 V -> lower set-point for non-boost
+            C_intermediate_uF=100 if "direct" not in src_name else 0,
+            V_pwr_good_enable_threshold_mV=1300 if "dio" in src_name else 2800,
+            V_pwr_good_disable_threshold_mV=1000 if "dio" in src_name else 2400,
+            V_input_drop_mV=150 if "dio" in src_name else 0,
+        ),
+        target=tgt,
+        path_input=file_input,
+        path_output=file_output,
+        monitor_internals=True,
+    )
+    print(f"E_out = {e_out_Ws * 1e3:.3f} mWs -> {src_name}")
+
+    with Reader(file_output, verbose=False) as reader:
+        reader.plot_to_file()
+        reader.plot_to_file(start_s=1, end_s=1.1)

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/pyproject.toml

@@ -19,6 +19,7 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
     "Natural Language :: English",
@@ -30,7 +31,7 @@ dependencies = [
     "numpy",
     "pyYAML",
     "chromalog",
-    "pydantic[email]>2.0.0",
+    "pydantic[email]>2.0.0",  # not compatible with prior versions
     "tqdm",
     "intelhex",
     "requests",

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/data_models/content/energy_environment.py

@@ -34,6 +34,9 @@ class EnergyEnvironment(ContentModel):
     valid: bool = False
 
     # TODO: scale up/down voltage/current
+    # TODO: multiple files for one env
+    # TODO: mean power as energy/duration
+    # TODO: harvester, transducer
 
     # additional descriptive metadata, TODO: these are very solar-centered -> generalize
     light_source: Optional[str] = None

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/data_models/content/virtual_harvester.py

@@ -21,6 +21,7 @@ from .energy_environment import EnergyDType
 class AlgorithmDType(str, Enum):
     """Options for choosing a harvesting algorithm."""
 
+    direct = disable = neutral = "neutral"
     isc_voc = "isc_voc"
     ivcurve = ivcurves = ("ivcurve",)
     constant = cv = "cv"
@@ -62,6 +63,9 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
     # ⤷ of (open voltage) measurement
     rising: bool = True
     # ⤷ direction of sawtooth
+    enable_linear_extrapolation: bool = True
+    # ⤷ improves slow cv-algo that is base of most ivcurve-harvesters
+    #   (update-freq dependent on window-size)
 
     # Underlying recorder
     wait_cycles: Annotated[int, Field(ge=0, le=100)] = 1
@@ -107,7 +111,7 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
         return self
 
     def calc_hrv_mode(self, *, for_emu: bool) -> int:
-        return 1 * int(for_emu) + 2 * self.rising
+        return 1 * int(for_emu) + 2 * self.rising + 4 * self.enable_linear_extrapolation
 
     def calc_algorithm_num(self, *, for_emu: bool) -> int:
         num = algo_to_num.get(self.algorithm)
@@ -117,7 +121,7 @@ class VirtualHarvesterConfig(ContentModel, title="Config for the Harvester"):
                 f"current usage = {self.algorithm}"
             )
             raise ValueError(msg)
-        if num < algo_to_num["isc_voc"]:
+        if not for_emu and num < algo_to_num["isc_voc"]:
             msg = (
                 f"[{self.name}] Select valid harvest-algorithm for harvester, "
                 f"current usage = {self.algorithm}"
@@ -177,7 +181,7 @@ u32 = Annotated[int, Field(ge=0, lt=2**32)]
 
 # Currently implemented harvesters
 # NOTE: numbers have meaning and will be tested ->
-# - harvesting on "neutral" is not possible
+# - harvesting on "neutral" is not possible - direct pass-through
 # - emulation with "ivcurve" or lower is also resulting in Error
 # - "_opt" has its own algo for emulation, but is only a fast mppt_po for harvesting
 algo_to_num = {
@@ -192,6 +196,7 @@ algo_to_num = {
 }
 
 algo_to_dtype = {
+    "neutral": EnergyDType.ivsample,
     "isc_voc": EnergyDType.isc_voc,
     "ivcurve": EnergyDType.ivcurve,
     "cv": EnergyDType.ivsample,

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/data_models/content/virtual_harvester_fixture.yaml

@@ -3,10 +3,13 @@
 # - look into the implementation to see which parameters are used
 # - base for neutral fallback values if provided yml is sparse
 # - -> it is encouraged to omit redundant parameters in your own implementation
+# - general rule: 0<id<2000 harvest from transducers, 2000<=id harvest from ivcurve
+
 - datatype: VirtualHarvesterConfig
   parameters:
     id: 1000
     name: neutral
+    enable_linear_extrapolation: true
     owner: Ingmar
     group: NES Lab
     visible2group: true
@@ -16,7 +19,7 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1010
+    id: 1100
     name: ivcurve
     description: Postpone harvesting by sampling ivcurves (voltage stepped as sawtooth-wave)
     comment: ~110 Hz, Between 50 & 60 Hz line-frequency to avoid standing waves
@@ -32,19 +35,19 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1011
+    id: 1101
     name: ivcurves  # synonym
     inherit_from: ivcurve
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1013
+    id: 1103
     name: iv110 # synonym
     inherit_from: ivcurve
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1012
+    id: 1102
     name: iv1000
     comment: Name relates to curves per second
     inherit_from: ivcurve
@@ -53,7 +56,7 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1020
+    id: 1200
     name: isc_voc
     description: Postpone harvesting by sampling short circuit current & open circuit voltage
     inherit_from: neutral
@@ -62,7 +65,7 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1030
+    id: 2100
     name: cv20
     description: Harvesting with constant Voltage
     inherit_from: neutral
@@ -71,28 +74,28 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1031
+    id: 2101
     name: cv24
     inherit_from: cv20
     voltage_mV: 2400
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1032
+    id: 2102
     name: cv33
     inherit_from: cv20
     voltage_mV: 3300
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1032
+    id: 2102
     name: cv10
     inherit_from: cv20
     voltage_mV: 1000
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1040
+    id: 2200
     name: mppt_voc
     description: MPPT based on open circuit voltage for solar
     inherit_from: neutral
@@ -104,7 +107,7 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1041
+    id: 2201
     name: mppt_bq
     description: MPPT of TI BQ-Converters for solar
     inherit_from: mppt_voc
@@ -114,7 +117,7 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1042
+    id: 2202
     name: mppt_bqt
     description: MPPT of TI BQ-Converters for thermoelectric
     inherit_from: mppt_voc
@@ -124,19 +127,19 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1043
+    id: 2203
     name: mppt_bq_solar # explicit naming
     inherit_from: mppt_bq
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1044
+    id: 2204
     name: mppt_bq_thermoelectric # explicit naming
     inherit_from: mppt_bqt
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1045
+    id: 2205
     name: mppt_po
     description: MPPT based on perturb & observe algorithm
     inherit_from: neutral
@@ -148,10 +151,18 @@
 
 - datatype: VirtualHarvesterConfig
   parameters:
-    id: 1046
+    id: 2206
     name: mppt_opt
     description: Power-Optimum with very fast PO-Variant (harvesting) or special max-pwr-picker (emulator / ivcurve)
     inherit_from: mppt_po
     algorithm: mppt_opt
     voltage_step_mV: 1
     interval_ms: 0.01
+
+- datatype: VirtualHarvesterConfig
+  parameters:
+    id: 3000
+    name: direct
+    description: Disables harvesting, even for ivcurve-input
+    inherit_from: neutral
+    algorithm: neutral

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/data_models/content/virtual_source.py

@@ -12,6 +12,7 @@ from ...logger import logger
 from ...testbed_client import tb_client
 from ..base.content import ContentModel
 from ..base.shepherd import ShpModel
+from .energy_environment import EnergyDType
 from .virtual_harvester import HarvesterPRUConfig
 from .virtual_harvester import VirtualHarvesterConfig
 
@@ -42,6 +43,8 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
     # ⤷ if false -> v_intermediate = v_input, output-switch-hysteresis is still usable
     enable_buck: bool = False
     # ⤷ if false -> v_output = v_intermediate
+    enable_feedback_to_hrv: bool = False
+    # src can control a cv-harvester for ivcurve
 
     interval_startup_delay_drain_ms: Annotated[float, Field(ge=0, le=10_000)] = 0
 
@@ -200,7 +203,7 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
             values["V_disable_output_threshold_mV"] = self.V_intermediate_disable_threshold_mV
         return values
 
-    def calc_converter_mode(self, *, log_intermediate_node: bool) -> int:
+    def calc_converter_mode(self, dtype_in: EnergyDType, *, log_intermediate_node: bool) -> int:
         """Assembles bitmask from discrete values.
 
         log_intermediate_node: record / log virtual intermediate (cap-)voltage and
@@ -208,11 +211,25 @@ class VirtualSourceConfig(ContentModel, title="Config for the virtual Source"):
         """
         enable_storage = self.C_intermediate_uF > 0
         enable_boost = self.enable_boost and enable_storage
+        if enable_boost != self.enable_boost:
+            logger.warning("VSrc - boost was disabled due to missing storage capacitor!")
+        enable_feedback = (
+            self.enable_feedback_to_hrv
+            and enable_storage
+            and not enable_boost
+            and dtype_in == EnergyDType.ivcurve
+        )
+        if enable_feedback != self.enable_feedback_to_hrv:
+            reason = "enabled boost, " if enable_boost else ""
+            reason += "" if dtype_in == EnergyDType.ivcurve else "input not ivcurve, "
+            reason += "" if enable_storage else "no storage capacitor"
+            logger.warning("VSRC - feedback to harvester was disabled! Reasons: %s", reason)
         return (
             1 * int(enable_storage)
             + 2 * int(enable_boost)
             + 4 * int(self.enable_buck)
             + 8 * int(log_intermediate_node)
+            + 16 * int(enable_feedback)
         )
 
     def calc_cap_constant_us_per_nF_n28(self) -> int:
@@ -285,13 +302,16 @@ class ConverterPRUConfig(ShpModel):
     def from_vsrc(
         cls,
         data: VirtualSourceConfig,
+        dtype_in: EnergyDType = EnergyDType.ivsample,
         *,
         log_intermediate_node: bool = False,
     ) -> Self:
         states = data.calc_internal_states()
         return cls(
             # General
-            converter_mode=data.calc_converter_mode(log_intermediate_node=log_intermediate_node),
+            converter_mode=data.calc_converter_mode(
+                dtype_in, log_intermediate_node=log_intermediate_node
+            ),
             interval_startup_delay_drain_n=round(
                 data.interval_startup_delay_drain_ms * samplerate_sps_default * 1e-3
             ),

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/data_models/content/virtual_source_fixture.yaml

@@ -11,6 +11,7 @@
     # General Config
     enable_boost: false # if false -> v_intermediate = v_input, output-switch-hysteresis is still usable
     enable_buck: false # if false -> v_output = v_intermediate
+    enable_feedback_to_hrv: false  # src can control a cv-harvester for ivcurve
 
     interval_startup_delay_drain_ms: 0
 
@@ -26,18 +27,21 @@
     V_intermediate_init_mV: 3000 # allow a proper / fast startup
     I_intermediate_leak_nA: 0.0
 
+    # Output-Switch with comparator and hysteresis
     V_intermediate_enable_threshold_mV: 1 # -> target gets connected (hysteresis-combo with next value)
     V_intermediate_disable_threshold_mV: 0 # -> target gets disconnected
     interval_check_thresholds_ms: 0.0  # some BQs check every 64 ms if output should be disconnected
 
+    # Power-Good signal from comparator and hysteresis
     V_pwr_good_enable_threshold_mV: 2800 # target is informed by pwr-good on output-pin (hysteresis) -> for intermediate voltage
     V_pwr_good_disable_threshold_mV: 2200
     immediate_pwr_good_signal: true  # 1: activate instant schmitt-trigger, 0: stay in interval for checking thresholds
 
-    C_output_uF: 1.0   # final (always last) stage to compensate undetectable current spikes when enabling power for target
+    C_output_uF: 1.0   # final (always last) stage to compensate transient current spikes when enabling power for target
 
     # Extra
     V_output_log_gpio_threshold_mV: 1400  # min voltage needed to enable recording changes in gpio-bank
+    # TODO: actually disable gpio below that
 
     # Boost Converter
     V_input_boost_threshold_mV: 0.0 # min input-voltage for the boost converter to work
@@ -81,6 +85,8 @@
     id: 1010
     name: direct
     inherit_from: neutral
+    harvester:
+      name: direct  # even disables harvesting of ivcurve
     # Note: current input has no influence
 
 - datatype: VirtualSourceConfig
@@ -90,7 +96,12 @@
     description: Simple Converter based on diode and buffer capacitor
     inherit_from: neutral
     V_input_drop_mV: 300  # simulate input-diode
-    C_intermediate_uF: 10  # primary storage-Cap
+    C_intermediate_uF: 47  # primary storage-Cap
+    harvester:
+      name: cv20
+    enable_feedback_to_hrv: true  # src can control a cv-harvester for ivcurve
+    V_intermediate_enable_threshold_mV: 2000
+    V_intermediate_disable_threshold_mV: 1800  # nRF draw ~0.5 mA below that point
 
 - datatype: VirtualSourceConfig
   parameters:
@@ -230,3 +241,5 @@
     id: 1033
     name: default
     inherit_from: BQ25570s
+
+# TODO: add some generic boost-converters with mppt_po, _voc and more

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/data_models/task/emulation.py

@@ -33,7 +33,8 @@ class Compression(str, Enum):
     lzf = default = "lzf"  # not native hdf5
     gzip1 = gzip = 1  # higher compr & load
     null = None
-    # NOTE: changed to lzf as BBB needs every straw it can get
+    # NOTE: lzf & external file-compression (xz or zstd) work better than gzip
+    #       -> even with additional compression
 
 
 compressions_allowed: list = [None, "lzf", 1]

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/reader.py

@@ -76,7 +76,7 @@ class Reader:
 
         if not hasattr(self, "samplerate_sps"):
             self.samplerate_sps: int = samplerate_sps_default
-        self.sample_interval_ns: int = int(10**9 // self.samplerate_sps)
+        self.sample_interval_ns: int = round(10**9 // self.samplerate_sps)
         self.sample_interval_s: float = 1 / self.samplerate_sps
 
         self.max_elements: int = 40 * self.samplerate_sps
@@ -177,8 +177,8 @@ class Reader:
             # this assumes iso-chronous sampling
             duration_s = self._cal.time.raw_to_si(duration_raw)
             self.sample_interval_s = duration_s / sample_count
-            self.sample_interval_ns = int(10**9 * self.sample_interval_s)
-            self.samplerate_sps = max(int((sample_count - 1) / duration_s), 1)
+            self.sample_interval_ns = round(10**9 * self.sample_interval_s)
+            self.samplerate_sps = max(round((sample_count - 1) / duration_s), 1)
         self.runtime_s = round(self.ds_voltage.shape[0] / self.samplerate_sps, 1)
         self.buffers_n = int(self.ds_voltage.shape[0] // self.samples_per_buffer)
         if isinstance(self.file_path, Path):

{shepherd_core-2024.8.2 → shepherd_core-2024.9.1}/shepherd_core/version.py

@@ -1,3 +1,3 @@
 """Separated string avoids circular imports."""
 
-version: str = "2024.8.2"
+version: str = "2024.9.1"