Merge pull request #38 from basecubedev/maintenance/update-documentation

documentation update

Author: basecubedev

README.md

@@ -337,9 +337,11 @@ When `dashboard.enabled=true`, the EMS starts a local dashboard server:
 http://<ems-host>:8080
 ```
 
-The dashboard shows live flow, device state, rule state, and short-term history
-from local SQLite storage. It is read-only and does not expose EMS control
-endpoints.
+The built-in standalone dashboard has Aggregated, Devices, Control, and Energy
+views. The Energy view includes Today, Yesterday, rolling periods,
+monthly/yearly totals, and Lifetime with since date.
+
+It is read-only and does not expose EMS control endpoints.
 
 More: [docs/dashboard.md](docs/dashboard.md).
 
@@ -351,15 +353,15 @@ Home Assistant can be used for:
 
 - monitoring
 - optional runtime-state helper controls
-- dashboard visualization
+- optional Home Assistant dashboard visualization
 
-Dashboard example:
+Home Assistant dashboard example:
 
 ```text
 homeassistant-dashboard/dashboard.yaml
 ```
 
-Dashboard preview:
+Home Assistant dashboard preview:
 
 ```text
 homeassistant-dashboard/dashboard-preview.jpg
@@ -454,7 +456,7 @@ Safety checks: [docs/safety.md](docs/safety.md).
 | `config.template.json` | Versioned config template |
 | `config.json` | Local config, ignored by Git |
 | `runtime-state.json` | Mutable runtime state, ignored by Git |
-| `homeassistant-dashboard/dashboard.yaml` | HA dashboard example |
+| `homeassistant-dashboard/dashboard.yaml` | Optional HA dashboard example |
 | `homeassistant-dashboard/dashboard-preview.jpg` | HA dashboard preview image |
 | `scripts/check_log_events.py` | Structured log validator |
 | `docs/` | Public documentation |

config.template.json

@@ -85,7 +85,7 @@
     "enabled": true,
     "price_per_kwh": 0.0,
     "currency": "EUR",
-    "max_sample_delta_seconds": 60,
+    "max_sample_delta_seconds": 20,
     "timezone": "Europe/Berlin"
   },
 

dashboard/sqlite_store.py

@@ -10,7 +10,7 @@
     "enabled": True,
     "price_per_kwh": 0.0,
     "currency": "EUR",
-    "max_sample_delta_seconds": 60,
+    "max_sample_delta_seconds": 20,
     "timezone": "Europe/Berlin",
 }
 

docs/configuration-examples.md

@@ -36,18 +36,35 @@ Use this for standalone EMS operation without Home Assistant.
     "max_device_power": 800,
     "deadband": 10,
     "runtime_state_path": "runtime-state.json",
-    "min_output_limit": 30,
-    "loop_interval": 5,
+    "min_output_limit": 35,
+    "loop_interval": 3,
     "redistribute_clamped_power": true,
     "pv_kwp_weighting": true,
     "pv_charge_balance_enabled": true,
-    "pv_charge_balance_deadband_percent": 5,
+    "pv_charge_balance_deadband_percent": 1,
     "pv_charge_balance_full_bias_percent": 15,
-    "pv_charge_balance_strength": 1.0,
+    "pv_charge_balance_strength": 0.7,
     "battery_kwh_weighting": true,
     "soc_reconcile_interval": 10
   },
 
+  "dashboard": {
+    "enabled": true,
+    "host": "0.0.0.0",
+    "port": 8080,
+    "database_path": "data/ems_dashboard.sqlite",
+    "history_hours": 48,
+    "write_interval_seconds": 5
+  },
+
+  "energy_savings": {
+    "enabled": true,
+    "price_per_kwh": 0.0,
+    "currency": "EUR",
+    "max_sample_delta_seconds": 20,
+    "timezone": "Europe/Berlin"
+  },
+
   "winter": {
     "enabled": false,
     "months": [10, 11, 12, 1, 2, 3],
@@ -86,6 +103,10 @@ Change:
 - `shelly.ip`
 - `pv_kwp`
 - `battery_kwh`
+- `dashboard.port` or `dashboard.database_path` only when needed
+- `energy_savings.price_per_kwh`
+- `energy_savings.currency`
+- `energy_savings.timezone` only when you do not want Europe/Berlin calendar days
 
 Run:
 
@@ -97,7 +118,8 @@ python3 -B ems-solarflow-api-control.py --preflight
 ## Example 2: Two Zendure Devices With Home Assistant
 
 Use this when Home Assistant should receive EMS sensors and optionally provide
-runtime helper controls.
+runtime helper controls. The values below intentionally override some
+single-device template values for a two-inverter installation.
 
 ```json
 {
@@ -119,8 +141,8 @@ runtime helper controls.
     "max_total_power": 1600,
     "max_device_power": 800,
     "runtime_state_path": "runtime-state.json",
-    "min_output_limit": 30,
-    "loop_interval": 5
+    "min_output_limit": 35,
+    "loop_interval": 3
   },
 
   "devices": [

docs/control-logic.md

@@ -118,8 +118,8 @@ The hold uses:
 standby_total_w = min_output_limit * active_online_device_count
 ```
 
-With two active devices and `min_output_limit=30`, the global target is held at
-`60W` instead of integrating toward `800W`. Once PV, discharge capability, or
+With two active devices and `min_output_limit=35`, the global target is held at
+`70W` instead of integrating toward `800W`. Once PV, discharge capability, or
 current output is observed again, the normal fast output controller resumes.
 
 ## PV-First Allocation

docs/dashboard.md

@@ -41,19 +41,29 @@ The dashboard section in `config.json` controls startup:
     "enabled": true,
     "price_per_kwh": 0.0,
     "currency": "EUR",
-    "max_sample_delta_seconds": 60
+    "max_sample_delta_seconds": 20,
+    "timezone": "Europe/Berlin"
   }
 }
 ```
 
 `database_path` is relative to the project directory unless an absolute path is
-used. The SQLite store is local and only keeps short-term dashboard history.
-`write_interval_seconds` keeps database writes low even when the EMS loop runs
-with a short interval.
+used. The SQLite database stores short-term live dashboard snapshots and
+telemetry. Those short-term rows are cleaned according to
+`dashboard.history_hours`. `write_interval_seconds` keeps database writes low
+even when the EMS loop runs with a short interval.
 
-Energy statistics are stored in the same SQLite database as daily aggregates.
-They integrate measured inverter AC output over real elapsed time and skip
-intervals longer than `max_sample_delta_seconds`.
+Daily energy statistics are stored in `daily_energy_stats` in the same database.
+They are persistent daily aggregates and are not removed by the short-term
+snapshot/telemetry cleanup.
+
+Energy statistics integrate measured inverter AC output over real elapsed time.
+Intervals above `energy_savings.max_sample_delta_seconds` are skipped and the
+integration baseline is advanced. This avoids false energy jumps after
+restarts, downtime, or longer outages.
+
+`energy_savings.timezone` defines the calendar timezone used for daily
+statistics and period lookups such as Today and Yesterday.
 
 ## API
 
@@ -63,8 +73,27 @@ Live snapshot:
 GET /api/live
 ```
 
-The live snapshot includes `energy_stats` with today, rolling windows, best
-day, current-year monthly totals, yearly totals, and lifetime totals.
+The live snapshot includes `energy_stats` with:
+
+```text
+energy_stats.enabled
+energy_stats.currency
+energy_stats.price_per_kwh
+energy_stats.today
+energy_stats.yesterday
+energy_stats.last_7_days
+energy_stats.last_4_weeks
+energy_stats.last_12_months
+energy_stats.best_day
+energy_stats.monthly_current_year
+energy_stats.yearly
+energy_stats.lifetime
+energy_stats.lifetime.since_date
+```
+
+`lifetime.since_date` is the first date in `daily_energy_stats` with
+`sample_count > 0`. It is day-accurate and uses the stored local statistics
+date, not the current runtime timestamp.
 
 Energy statistics only:
 

docs/home-assistant.md

@@ -6,6 +6,10 @@ The EMS can run standalone with `config.json` and `runtime-state.json`.
 The template default keeps Home Assistant disabled with `ha.enabled=false` and
 `ha.control_enabled=false`.
 
+This page documents the optional Home Assistant integration and the optional HA
+dashboard example. The built-in standalone read-only dashboard is documented in
+`docs/dashboard.md`.
+
 ## Roles
 
 Home Assistant has two independent roles:
@@ -155,22 +159,23 @@ sensor.ems_solarflow_wr1_winter_min_soc_target
 sensor.ems_solarflow_wr1_winter_estimated_ramp_days
 ```
 
-## Dashboard
+## Home Assistant Dashboard Example
 
-The repository contains a dashboard example:
+The repository contains an optional Home Assistant dashboard example:
 
 ```text
 homeassistant-dashboard/dashboard.yaml
 ```
 
-Dashboard preview:
+Home Assistant dashboard preview:
 
 ```text
 homeassistant-dashboard/dashboard-preview.jpg
 ```
 
 It includes EMS control, runtime device control, winter status, device state,
-battery status, PV details, and power-flow visualization.
+battery status, PV details, and power-flow visualization. This is separate from
+the built-in standalone dashboard documented in `docs/dashboard.md`.
 
 Troubleshooting stale, unavailable, or ignored HA values:
 [troubleshooting.md](troubleshooting.md).

docs/quickstart.md

@@ -150,8 +150,8 @@ The template already uses this live-control-ready system policy:
     "reconcile_ac_mode_on_start": true,
     "reconcile_smart_mode": true,
     "max_total_power": 800,
-    "loop_interval": 5,
-    "min_output_limit": 0
+    "loop_interval": 3,
+    "min_output_limit": 35
   }
 }
 ```

docs/runtime-state.md

@@ -20,8 +20,8 @@ Example:
   "system": {
     "enabled": true,
     "max_total_power": 800,
-    "loop_interval": 5,
-    "min_output_limit": 30
+    "loop_interval": 3,
+    "min_output_limit": 35
   },
   "ha": {
     "enabled": false,
@@ -56,9 +56,10 @@ Example:
 | `loop_interval` | Runtime loop interval |
 | `min_output_limit` | Runtime guard against very low enabled `outputLimit` writes |
 
-`min_output_limit=30` is useful on installations where `outputLimit=0` behaves
-like a stop, idle, or sleep state. The guard is applied before deadband handling
-and only while EMS control is enabled.
+`min_output_limit=35` is the current template default and is useful on
+installations where `outputLimit=0` behaves like a stop, idle, or sleep state.
+The guard is applied before deadband handling and only while EMS control is
+enabled.
 
 The same value is also used as the standby/wakeup `outputLimit` for strict
 night/minSoc idle. When all active online devices report exactly no PV, no

docs/troubleshooting.md

@@ -84,7 +84,7 @@ Important runtime fields:
     "enabled": true,
     "max_total_power": 800,
     "loop_interval": 2,
-    "min_output_limit": 30
+    "min_output_limit": 35
   },
   "ha": {
     "enabled": false,
@@ -406,7 +406,7 @@ Check:
 ```json
 {
   "system": {
-    "min_output_limit": 30
+    "min_output_limit": 35
   }
 }
 ```