# Dataset README

## Project Title
Millimeter-Scale Lagrangian Sensor Spheres for Local State Monitoring in SMART Reactors: Towards Energy-Autonomous Operation

## Related Publication
This snapshot accompanies the manuscript:

`Millimeter-Scale Lagrangian Sensor Spheres for Local State Monitoring in SMART Reactors: Towards Energy-Autonomous Operation`

## Related Software
The script used to determine trajectories is archived separately on Zenodo:

doi:10.5281/zenodo.21066484

## Principal Investigators / Authors

Anton Geläschus \
Hamburg University of Technology \
ORCID: 0000-0003-1904-2473

Lukas Rennpferdt \
Hamburg University of Technology

Vamika Rathi \
Hamburg University of Technology \
ORCID: 0009-0004-6061-3850

Mohammad Daniyal Hussain \
Hamburg University of Technology

Daniel Ruprecht \
Hamburg University of Technology \
ORCID: 0000-0003-1904-2473

Khiem Hoc Trieu \
Hamburg University of Technology \
ORCID: 0000-0002-6102-4132

## Funding Acknowledgement
This data set was generated as part of the DFG-funded project CRC 1615: SMART Reactors for Future Process Engineering (DFG Project Number: 503850735).

## 1. General Information

### Data Set Title
Data for "Millimeter-Scale Lagrangian Sensor Spheres for Local State Monitoring in SMART Reactors: Towards Energy-Autonomous Operation"

### Short Description
This TORE snapshot contains measurement data, plotting and conversion scripts, PCB documentation, and firmware source files related to the above manuscript. Data and scripts are separated into `01_Data` and `02_Scripts`; both use the same experiment subfolders after extraction so that each script group can be matched directly to its input data.


### Date of Data Collection
The contained material spans multiple acquisition and processing steps generated before snapshot creation. The snapshot itself was created on `2026-03-31` and reorganized for TORE submission on `2026-06-29`.

### Geographical Coverage
Hamburg-Harburg, Germany

### Keywords
SMART Reactors, Lagrangian sensor spheres, energy harvesting, RF harvesting, power transmission, measurement data, PCB documentation, reproducible plotting

## 2. Methodological Information

### Data Collection and Processing
The snapshot contains experimentally generated electrical measurement data and supporting scripts used to process and visualize selected results:

- Oscilloscope CSV exports from a PicoScope 5000 Series and Nordic Semiconductor Power Profiler Kit 2 (PPK2) current traces for hardware power-transmission analysis.
- Excel workbooks and CSV exports for RF-harvesting analysis.
- Python scripts that process raw or semi-processed measurement files and regenerate manuscript-supporting plots or intermediate `.dat` and `.tex` exports.
- PCB bill-of-material, schematic, and layout documentation for two hardware revisions.
- Firmware source files and build configuration for the sensor-sphere firmware.

Processing was performed with Python-based plotting workflows. In the current snapshot, scripts are packaged separately from data but retain the same subfolder names. The default script paths have been adjusted to read from the matching `01_Data` subfolder after the archives are extracted side by side.

### Experimental Design / Study Context
The archived files support figure generation and result inspection for a millimeter-scale Lagrangian sensor platform intended for local state monitoring in SMART reactors, with emphasis on energy-related subsystems. The included data blocks cover:

- Hardware power transmission, including aligned scope and current traces.
- RF harvesting behavior under different tilt, transmission, load, and medium conditions.
- PCB documentation for the sensor-sphere hardware.
- Firmware sources for the embedded sensor-sphere implementation.

### Data Validation and Quality Assurance
Quality assurance in this snapshot is based on consistency between raw measurement exports, processed intermediate files, and the provided plotting scripts. Several data folders include both source data and rendered or derived plotting inputs, allowing regeneration and visual cross-checking of results. This README describes only materials present in the current snapshot.

## 3. Data and File Overview

### List of Files and Structure

| File / Folder | Description | Format | Notes |
| --- | --- | --- | --- |
| `01_Data/` | Unpacked copy of the measurement data and derived plotting data | `.csv`, `.xlsx`, `.dat`, `.tex` | Data are grouped by experiment block. |
| `01_Data.zip` | Packaged copy of `01_Data/` for TORE upload | `.zip` | Contains the same `01_Data/` folder structure. |
| `02_Scripts.zip` | Python scripts for conversion, plotting, and derived data generation | `.zip`, `.py` | Contains `02_Scripts/` with the same experiment subfolders as `01_Data/`. |
| `03_Hardware.zip` | PCB documentation for hardware revisions V1 and V2 | `.zip`, `.xlsx`, `.pdf` | Contains BOM, schematic, and layout files. |
| `04_Firmware.zip` | Firmware source files and build configuration | `.zip`, `.c`, `.h`, `Makefile`, `.mk`, `.ld` | Contains `04_Firmware/`. |
| `License.md` | License allocation for data, scripts, firmware, and PCB material | `.md` | See Section 4. |


Inside `01_Data/` and `02_Scripts.zip`:

| Subfolder | Data files | Script files | Description |
| --- | --- | --- | --- |
| `Hardware_Power_Transmission/` | `20260325.csv`, `ppk-20260326T140146.csv`, `power_transmission_aligned*.dat`, `power_transmission_aligned.tex`, `ppk_20260326_window_analysis.*` | `plot_power_transmission_alignment.py`, `plot_ppk_20260326_windows.py` | Power-transmission and PPK2 trace analysis. |
| `RF_Harvesting/` | `mini_coil_readings.xlsx`, `mini_coil_readings.csv`, `power_rfid.xlsx`, `power_rfid.csv` | `convert_rf_harvesting_workbooks_to_csv.py`, `plot_rf_harvesting_results.py`, `plot_rf_harvesting_results_from_csv.py` | RF-harvesting source tables, CSV conversion, and plotting. |

Inside `03_Hardware.zip`:

| File group | Description |
| --- | --- |
| `V1_BOM.xlsx`, `V1_Schematic.pdf`, `V1_Layout.pdf` | PCB bill of materials, schematic, and layout for revision V1. |
| `V2_BOM.xlsx`, `V2_Schematic.pdf`, `V2_Layout.pdf` | PCB bill of materials, schematic, and layout for revision V2. |

Inside `04_Firmware.zip`:

| File group | Description |
| --- | --- |
| `*.c`, `*.h` | Firmware source and header files for sensors, setup, communication, and optical data transmission. |
| `Makefile`, `project.mk`, `lp.ld` | Build configuration and linker script. |
| `README.md` | Firmware-specific notes. |

### File Naming Convention
File names generally follow descriptive, workflow-oriented naming:

- Date-based measurement exports such as `20260325.csv` or `ppk-20260326T140146.csv`.
- Plotting scripts prefixed with `plot_...`.
- Conversion scripts prefixed with `convert_...`.
- Derived pgfplots or intermediate exports using suffixes such as `_aligned`, `_window_analysis`, or `.dat`.
- RF-harvesting source tables named after experiment groups, for example `mini_coil_readings.xlsx` and `power_rfid.xlsx`.
- PCB files grouped by hardware revision prefix, for example `V1_...` and `V2_...`.
- Firmware files follow embedded C naming conventions and include source/header pairs such as `ICM20948_Driver.c` and `ICM20948_Driver.h`.

### Number of Records / Observations
The snapshot contains multiple heterogeneous measurement files rather than a single rectangular table. Record counts vary by file and experiment. Users should inspect the relevant CSV, XLSX, or generated `.dat` file for per-experiment row counts.

## 4. Access and Licensing Information

### Repository and Persistent Identifier
This snapshot is prepared for dataset submission via TORE.

Reserved TORE DOI: https://doi.org/10.15480/882.16934

### License for Use
Licensing is assigned by material type:

- `01_Data/`: Public Domain Mark 1.0 for pure measurement and sensor-output data.
- Dataset-level documentation and metadata: Creative Commons Attribution 4.0 International (`CC-BY-4.0`).
- `02_Scripts/`: MIT License.
- `04_Firmware/`: MIT License.
- `03_Hardware/`: CERN Open Hardware Licence Version 2 - Permissive (`CERN-OHL-P-2.0`).

See `License.md` for the license allocation and links to the corresponding license texts.

### Access Restrictions
This snapshot appears intended for open dataset submission. Any embargo or repository-side access restriction should be declared during final deposit if needed.

### Text for Citation
A. Geläschus, L. Rennpferdt, V. Rathi, M. D. Hussain, D. Ruprecht, and H. K. Trieu, "Data for Millimeter-Scale Lagrangian Sensor Spheres for Local State Monitoring in SMART Reactors: Towards Energy-Autonomous Operation," TORE, 2026. https://doi.org/10.15480/882.16934

## 5. Reproducibility and Software Dependencies

### Software Required
The included processing workflows indicate the following practical dependencies:

- Python 3.x.
- Standard scientific Python packages used by the plotting scripts, notably `numpy` and `matplotlib`.
- Ability to read `.csv`, `.xlsx`, `.dat`, `.tex`, `.pdf`, and `.md` files.

### Scripts and Workflow
The executable plotting and conversion scripts are packaged in `02_Scripts.zip`. After extracting `01_Data.zip` and `02_Scripts.zip` side by side, the scripts read from the corresponding subfolder in `01_Data` by default. Examples:

- `02_Scripts/Hardware_Power_Transmission/plot_power_transmission_alignment.py`
- `02_Scripts/Hardware_Power_Transmission/plot_ppk_20260326_windows.py`
- `02_Scripts/RF_Harvesting/convert_rf_harvesting_workbooks_to_csv.py`
- `02_Scripts/RF_Harvesting/plot_rf_harvesting_results.py`
- `02_Scripts/RF_Harvesting/plot_rf_harvesting_results_from_csv.py`

The scripts also expose command-line arguments for alternative input or output paths.

Firmware source files are packaged in `04_Firmware.zip`. Build details are provided by the included firmware `README.md`, `Makefile`, `project.mk`, and linker script.

The trajectory-determination script used in the wider analysis workflow is stored separately on Zenodo under doi:10.5281/zenodo.21066484.

### Reproducibility Notes
Reproducibility is strongest for the included figure groups where both input tables and plotting scripts are present:

- `Hardware_Power_Transmission` contains raw or semi-raw trace exports together with scripts that generate aligned outputs and window analyses.
- `RF_Harvesting` contains both the original Excel workbooks and matching CSV exports, along with scripts for reproducing plots from either source format.

This README describes only the files available in the current snapshot and does not assume the presence of external project folders.

## 6. Ethical and Legal Aspects

### Data Protection
No personal or participant-related data are evident in the inspected snapshot contents. The material consists of engineering measurement data, scripts, PCB documentation, and firmware source files.

### Consent Statement
Not applicable based on the currently included materials.

## 7. Versioning and Updates

### Version Number
`v1.1-snapshot`

### Date of Release
`2026-03-31`

### Change Log
- `2026-03-31`: Submission-side TORE snapshot created.
- `2026-04-14`: README restructured in Markdown following the dataset-submission template; RF-harvesting CSV exports and CSV-based plotting support added locally.
- `2026-06-29`: Data, scripts, hardware documentation, and firmware separated into `01_Data`, `02_Scripts`, `03_Hardware`, and `04_Firmware` packages; obsolete software placeholder removed; license allocation updated.

## 8. Contact Information

### Corresponding Author
Anton Geläschus \
Hamburg University of Technology \
ORCID: 0000-0003-1904-2473