1 files changed, 85 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..85491d6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,85 @@
+# tasmota-dash
+
+Aggregates five [Tasmota](https://tasmota.github.io/docs/) smart plugs into a
+[Homepage](https://gethomepage.dev) dashboard: live power, per-day and
+lifetime energy, and what it costs in euro.
+
+Homepage's `customapi` widget can render JSON but cannot do arithmetic, so
+this proxy sits between the plugs and the dashboard, applies the tariff, sums
+across plugs and records a daily history that the plugs themselves do not keep.
+
+Stdlib Python, no dependencies, one file.
+
+## Features
+
+- Per-plug and aggregate readings on one endpoint each
+- Cost in euro at two tariffs: marginal (consumption quota) and all-in (total bill / total kWh)
+- Daily kWh history in SQLite, with rolling 7 and 30 day figures
+- A bar-chart page for the last 30 days
+- An offline plug is reported, not silently counted as zero
+
+## Endpoints
+
+| Path | Returns |
+|---|---|
+| `/<name>` | One plug: power, today/yesterday/lifetime kWh, cost |
+| `/total` | Sum across plugs, plus rolling 7/30 day figures |
+| `/history` | Per-day kWh, last 30 days, JSON |
+| `/graph` | HTML bar chart of the last 30 days |
+| `/` | Plug list and available paths |
+
+## Install
+
+Runs on the machine hosting Homepage, listening on `127.0.0.1:8099`.
+
+```bash
+install -Dm755 tasmota_proxy.py /opt/tasmota-proxy/tasmota_proxy.py
+install -Dm644 tasmota-proxy.service /etc/systemd/system/tasmota-proxy.service
+# edit the unit: plug addresses and tariff rates
+systemctl daemon-reload && systemctl enable --now tasmota-proxy
+curl -s localhost:8099/total
+```
+
+Then merge `homepage-services.yaml` into Homepage's `services.yaml` and the
+`layout:` block from `homepage-settings.yaml` into its `settings.yaml`, and
+restart Homepage.
+
+## Configuration
+
+Environment variables, set in the unit file:
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `TASMOTA_PLUGS` | five LAN addresses | `name=host,name=host,...` — also defines the URL paths |
+| `PORT` | `8099` | Listen port, bound to localhost |
+| `RATE_MARGINAL` | `0.17598` | €/kWh, consumption quota only |
+| `RATE_ALLIN` | `0.2754` | €/kWh, total bill divided by total kWh |
+| `HISTORY_DB` | `/var/lib/tasmota-proxy/history.db` | Daily history |
+
+## History
+
+Tasmota keeps only today, yesterday and a lifetime total. Each poll records
+yesterday's finished kWh per plug, keyed by day so repeated polls overwrite
+rather than accumulate. History therefore starts from first run, and only
+covers days the proxy was running for. Today is excluded from rolling sums
+because it is unfinished.
+
+## Tests
+
+```bash
+python3 test_proxy.py
+```
+
+Fakes the plugs, so it needs no LAN access. Prints `ok`.
+
+## License
+
+GPLv2. See [LICENSE](LICENSE).
+
+## Development Approach
+
+This project is developed using AI-assisted tools. Code is generated with the help of AI based on human-provided specifications, design decisions, and iterative feedback.
+
+All contributions are reviewed, tested, and curated by the maintainer before being included in the codebase. AI is used as a productivity and exploration tool, while human oversight remains central to all decisions.
+
+The goal is to combine the flexibility of AI-assisted development with standard open-source practices such as transparency, review, and accountability.