Update README.md

Author: SculptTechProject

README.md

@@ -5,7 +5,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 A lightweight generator of dummy sensor data for IoT and ML testing.
-Provides a simple Python API and CLI, supports running multiple sensors in parallel and splitting output streams into files.
+Provides a simple Python API and CLI, supports running multiple sensors in parallel, photovoltaic domain sensors, and splitting output streams into files.
+
+---
 
 ## Installation
 
@@ -15,6 +17,8 @@ From PyPI (recommended):
 pip install dummysensors
 ```
 
+---
+
 ## Quick Start (API)
 
 ```python
@@ -28,9 +32,11 @@ print(temp.read())            # e.g. 21.3
 print(vib.read(t_s=0.123))    # sinusoidal signal with noise
 ```
 
-## Config file
+---
+
+## Config file (YAML)
 
-Instead of passing long `--spec` strings, you can define your setup in a YAML file.  
+Instead of passing long `--spec` strings, you can define your setup in a YAML file.
 By default, `dummy-sensors run --config config.sensors.yaml` will look for a file named `config.sensors.yaml` in the current directory.
 
 ### Example `config.sensors.yaml`
@@ -55,6 +61,29 @@ devices:
         count: 1
       - kind: vibration
         count: 1
+  - id: plant-1
+    sensors:
+      - kind: irradiance
+        count: 1
+        params: {peak: 900.0, day_period_s: 10.0, sunrise: 0.0, sunset: 10.0}
+      - kind: pv_power
+        count: 1
+        params: {stc_kw: 5.0, inverter_eff: 0.95, p_kw_max: 4.8}
+      - kind: load
+        count: 1
+        params: {base_kw: 0.3, morning_kw: 0.8, evening_kw: 1.2}
+      - kind: soc
+        count: 1
+        params: {capacity_kwh: 10.0, soc0: 50.0}
+```
+
+Run with:
+
+```bash
+dummy-sensors run --config config.sensors.yaml
+```
+
+---
 
 ## Quick Start (CLI)
 
@@ -76,20 +105,10 @@ dummy-sensors run \
   --out "*=stdout"
 ```
 
->👉 Check out a full demo with live plotting and JSONL logging here:  
-[dummysensors demo (ds-test)](https://github.com/SculptTechProject/ds-test)
+> 👉 Check out a full demo with live plotting and JSONL logging here:
+> [dummysensors demo (ds-test)](https://github.com/SculptTechProject/ds-test)
 
-Each record is a JSON line:
-
-```json
-{
-  "ts_ms": 1234,
-  "device_id": "engine-A",
-  "sensor_id": "temp-0",
-  "type": "temp",
-  "value": 21.04
-}
-```
+---
 
 ## `--spec` format
 
@@ -101,36 +120,60 @@ device=<ID>: <type>*<count>[, <type>*<count> ...] ; device=<ID2>: ...
 
 Examples:
 
-- `device=A: temp*3` — device A with three temperature sensors
-- `device=eng: temp*1,vibration*2; device=room: temp*2`
+* `device=A: temp*3` — device A with three temperature sensors
+* `device=eng: temp*1,vibration*2; device=room: temp*2`
 
-> As of `v0.2`, supported sensor types: `temp`, `vibration`.  
+> As of `v0.3`, supported sensor types:
+> `temp`, `vibration`, `irradiance`, `pv_power`, `load`, `soc`.
 > You can define setups either with `--spec` (quick inline config) or using a YAML file (`--config config.sensors.yaml`) for more complex scenarios.
 
+---
+
 ## Python API
 
 ### `TemperatureSensor`
 
-- Parameters: `min_val=15.0`, `max_val=30.0`, `noise=0.5`, `period_s=86400`
-- Methods:
-  - `read(t_s: float | None = None) -> float` — one sample (random within range + Gaussian noise)
+* Parameters: `min_val=15.0`, `max_val=30.0`, `noise=0.5`, `period_s=86400`
+* Methods: `read(t_s: float | None = None) -> float`
 
 ### `VibrationSensor`
 
-- Parameters: `base_hz=50.0`, `amp=1.0`, `noise=0.1`, `spike_prob=0.0`
-- Methods:
-  - `read(t_s: float | None = None) -> float` — sinusoidal signal at `base_hz` + noise
+* Parameters: `base_hz=50.0`, `amp=1.0`, `noise=0.1`, `spike_prob=0.0`
+* Methods: `read(t_s: float | None = None) -> float`
+
+### `IrradianceSensor`
+
+* Simulates solar irradiance with day/night cycle.
+* Parameters: `peak`, `day_period_s`, `sunrise`, `sunset`
+
+### `PVPowerSensor`
+
+* Converts irradiance into PV output.
+* Parameters: `stc_kw`, `inverter_eff`, `p_kw_max`
+
+### `LoadSensor`
+
+* Simulates household/plant consumption profile.
+* Parameters: `base_kw`, `morning_kw`, `evening_kw`, `day_period_s`
+
+### `BatterySoCSensor`
+
+* Integrates charge/discharge depending on PV vs load.
+* Parameters: `capacity_kwh`, `soc0`
 
 ### Sensor Registry
 
-- `dummysensors.registry.SENSOR_REGISTRY` — maps string `kind` → class
-- `dummysensors.registry.make_sensor(kind: str, **params)`
+* `dummysensors.registry.SENSOR_REGISTRY` — maps string `kind` → class
+* `dummysensors.registry.make_sensor(kind: str, **params)`
 
 ### Orchestrator
 
-- `dummysensors.orchestrator.run_stream(spec_str, rate_hz, duration_s, total_count, writer_for_type)`
-  - Creates instances based on `spec_str`, emits samples at `rate_hz`.
-  - `writer_for_type` is a dict `type → callable(sample_dict)`. `*` = default writer.
+* `dummysensors.orchestrator.run_stream(...)`
+
+  * Creates instances based on `spec_str` or `config`, respects **priority** and **per-sensor rate\_hz**.
+  * `writer_for_type` is a dict `type → callable(sample_dict)`. `*` = default writer.
+
+---
 
 ## Output Format
 
@@ -146,26 +189,18 @@ JSON Lines (one record per line):
 }
 ```
 
-> Planned: CSV, Kafka, Redis Stream, WebSocket.
-
-## Makefile
+Also supported: **CSV**. Planned: Kafka, Redis Stream, WebSocket.
 
-For convenience, run with `make`:
+---
 
-```make
-make venv        # create .venv and upgrade pip
-make install     # pip install -e .
-make test        # pytest
-make demo        # generate demo data into demo_out/
-make clean       # cleanup build and cache
-```
+## Roadmap
 
-After `make demo`, check the files:
+* `v0.2` ✅ — CSV writer, partitioning, YAML config
+* `v0.3` ✅ — Smart photovoltaic sensors (`irradiance`, `pv_power`, `load`, `soc`), per-sensor `rate_hz`, priority-based orchestration
+* `v0.4` 🚧 — AnomalyInjector (spike, dropout, drift), new sensors (`humidity`, `rpm`, `battery_voltage`, `gps`, `accel-3axis`)
+* `v0.5` 🚧 — Outputs: Kafka, Redis Stream, WebSocket live preview
 
-```bash
-head -n 3 demo_out/temp.jsonl
-head -n 3 demo_out/vibration.jsonl
-```
+---
 
 ## Development
 
@@ -176,38 +211,11 @@ pip install -e .
 pip install -r requirements.txt
 ```
 
-- Project layout: **src-layout**
-- Tests: `pytest -q`
-- Lint/format: `ruff check src tests` and `ruff format`
-
-Pull Requests welcome. Guidelines:
-
-- Simple sensor classes
-- No heavy runtime dependencies
-- Test each public feature
-
-## Example Demo
-
-- A complete example using `dummysensors` for live plotting and JSONL logging is available in the [ds-test repository](https://github.com/SculptTechProject/ds-test).
-
-## Roadmap
+* Project layout: **src-layout**
+* Tests: `pytest -q`
+* Lint/format: `ruff check src tests` and `ruff format`
 
-- `v0.2` ✅
-  - CSV writer
-  - `partition_by=device`
-  - YAML config (`--config config.yaml`)
-- `v0.3`
-  - AnomalyInjector (spike, dropout, drift)
-  - New sensors: `humidity`, `rpm`, `battery_voltage`, `gps (trajectory)`, `accel 3-axis`
-- `v0.4`
-  - Outputs: Kafka, Redis Stream
-  - Live preview (WebSocket demo)
-
-## Versioning and Publishing
-
-- Semantic versioning with tags `vX.Y.Z`.
-- ​**CI**​: `.github/workflows/ci.yml` (lint + tests + build).
-- ​**Publish**​: `.github/workflows/publish.yml` (Trusted Publishing to PyPI on release).
+---
 
 ## License