{"id":31581464,"url":"https://github.com/chaffybird56/home-energymonitor","last_synced_at":"2025-10-05T21:58:39.475Z","repository":{"id":317273143,"uuid":"1066718748","full_name":"chaffybird56/Home-EnergyMonitor","owner":"chaffybird56","description":"Real-time home energy data tracker. Monitor, log, and visualize power usage.","archived":false,"fork":false,"pushed_at":"2025-09-29T22:09:15.000Z","size":34,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-29T23:38:20.611Z","etag":null,"topics":["energy-monitor","flask","mqtt","power-consumption","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chaffybird56.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-29T21:35:16.000Z","updated_at":"2025-09-29T22:09:18.000Z","dependencies_parsed_at":"2025-09-29T23:38:22.736Z","dependency_job_id":null,"html_url":"https://github.com/chaffybird56/Home-EnergyMonitor","commit_stats":null,"previous_names":["chaffybird56/home-energymonitor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/chaffybird56/Home-EnergyMonitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaffybird56%2FHome-EnergyMonitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaffybird56%2FHome-EnergyMonitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaffybird56%2FHome-EnergyMonitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaffybird56%2FHome-EnergyMonitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chaffybird56","download_url":"https://codeload.github.com/chaffybird56/Home-EnergyMonitor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chaffybird56%2FHome-EnergyMonitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526224,"owners_count":26001326,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["energy-monitor","flask","mqtt","power-consumption","python"],"created_at":"2025-10-05T21:58:37.455Z","updated_at":"2025-10-05T21:58:39.465Z","avatar_url":"https://github.com/chaffybird56.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🏠⚡ Home Energy Monitoring Dashboard\n\nA practical, demo‑ready system for **collecting smart‑meter telemetry** and turning it into **clear operational insights**:\n- Track **MV/LV feeder load** and **peak‑demand trends** for retrofit planning.\n- Catch **data gaps** or suspicious values with **data‑quality checks** and **alarms**.\n- Roll up **daily energy (kWh)**, **peak kW**, and **min voltage** for maintenance/outage coordination.\n\nThis repo includes everything to run locally with **Docker** (broker + app) plus a **data simulator**\n\n---\n\n## 📸 Screenshots\n\n- **Feeder Load — last 24h (kW)**  \n\u003cimg width=\"600\" height=\"500\" alt=\"SCR-20250929-pviq\" src=\"https://github.com/user-attachments/assets/9c723d47-250c-4d78-8b65-8ead9b0d1b82\" /\u003e\n\n- **Average Voltage across meters (V)**  \n\u003cimg width=\"600\" height=\"500\" alt=\"SCR-20250929-pvji\" src=\"https://github.com/user-attachments/assets/a4b089dd-ea04-457e-b93a-cf604be50817\" /\u003e\n\n- **Terminal — simulated meter publishes**  \n\u003cimg width=\"600\" height=\"500\" alt=\"SCR-20250929-psvj\" src=\"https://github.com/user-attachments/assets/7125da87-caa9-479a-a940-0cae6b597895\" /\u003e\n\n---\n\n## ✨ What’s inside (features)\n\n- **MQTT ingest** (Paho) subscribing to `utility/meter/+/reading` and persisting to SQLite.\n- **Dashboard** (Flask + Chart.js):  \n  - Feeder **kW** (last 24 h) with peak badge  \n  - **Average voltage** across meters (last 24 h)  \n  - **Daily kWh** bars (last 14 days)\n- **Daily summaries** (APScheduler): kWh, peak kW + timestamp, min voltage, % missing.\n- **Data quality checks** (pandas resampling): hourly missing‑data flagging.\n- **Configurable alarms** (`config/alarms.yml`) e.g., peak‑kW threshold, data‑gap minutes.\n- **Portable dev setup**: one `docker compose up --build`.\n- **Simulator** for reproducible screenshots and testing.\n- **Extensible**: SQLAlchemy models; easy swap to Postgres; room for SSE/WebSockets.\n\n---\n\n## 🧱 Architecture\n\n```\nMeters/Simulator → MQTT (Mosquitto)\n        ↓\n   Flask (Paho subscriber) → SQLite (SQLAlchemy)\n        ↓\nAPScheduler (daily rollups \u0026 alarm scans)\n        ↓\n Flask JSON API → Chart.js dashboard\n```\n\n**Topic \u0026 payload**\n```\nutility/meter/{meter_id}/reading\n{\n  \"ts\": \"ISO8601\",\n  \"kw\": \u003cfloat\u003e, \"kvar\": \u003cfloat\u003e,\n  \"volts\": \u003cfloat\u003e, \"hertz\": \u003cfloat\u003e,\n  \"voltage_level\": \"MV\"|\"LV\",\n  \"feeder\": \"FDR-12\"\n}\n```\n\n---\n\n## 🚀 End‑to‑end setup (Mac/Windows/Linux)\n\n### 0) Prereqs (once)\n- **Docker Desktop** (starts Docker Engine + Compose v2)\n- **Python 3.11+** (for the simulator)\n\n### 1) Get the project\n- **Option A (ZIP in releases)**: Unzip and `cd` into the folder; ensure you can see `.env.example`.\n- **Option B (clone)**:\n  ```bash\n  git clone https://github.com/yourname/home-energy-monitor.git\n  cd home-energy-monitor\n  ```\n\n### 2) Prepare env/config\n```bash\n# If present:\ncp .env.example .env\n\n# If not present, create .env:\ncat \u003e .env \u003c\u003c'EOF'\nFLASK_ENV=development\nFLASK_APP=app\nSECRET_KEY=dev-change-me\nDATABASE_URL=sqlite:///energy.db\nMQTT_BROKER_HOST=broker\nMQTT_BROKER_PORT=1883\nMQTT_TOPICS=utility/meter/+/reading\nTIMEZONE=America/Toronto\nEOF\n```\n\n(Optional) Adjust thresholds/time in `config/alarms.yml` and `config/app.example.yml`.\n\n### 3) Start services (Docker)\n```bash\ndocker compose up --build\n```\n- Broker (**Mosquitto**) on `localhost:1883`\n- Web app (Flask) on `http://localhost:5000`\n\n\u003e Leave this terminal open to see logs.\n\n### 4) Start the **data simulator** (new terminal)\n```bash\npython3 -m venv .venv \u0026\u0026 . .venv/bin/activate\npip install -r requirements.txt\nexport MQTT_BROKER_HOST=localhost MQTT_BROKER_PORT=1883\npython simulator/publisher.py\n```\nYou’ll see lines like:\n```\n-\u003e utility/meter/MTR-1001/reading {\"ts\":\"...\",\"kw\":...,\"volts\":...}\n```\n\n### 5) Open the dashboard\n- Navigate to **http://localhost:5000**\n- You should see feeder **kW** and **Voltage** charts filling within seconds.\n- Let it run a bit to populate the **Daily kWh** bars.\n\n### 6) (Optional) Verify MQTT messages\n```bash\ndocker exec -it hem-mosquitto sh -c \"mosquitto_sub -h localhost -t 'utility/meter/#' -v | head -n 10\"\n```\n\n---\n\n## 🧪 Tests\n```bash\npytest -q\n```\n\n---\n\n## 🛠️ Configuration notes\n\n- **Daily rollups schedule**: `rollups.daily_time` (local timezone)  \n- **Data quality**: `quality.max_missing_percent_per_hour`  \n- **Alarm rules**: `config/alarms.yml` (metric, comparator, threshold, window)\n\n---\n\n## 🧭 Troubleshooting\n\n- **“.env.example: No such file or directory”**  \n  Ensure you’re in the correct folder (`pwd`; `ls -la`). If missing, create `.env` using the block in step **2**.\n\n- **Charts are empty**  \n  Simulator might not be running—or broker not reachable. Start the simulator (step **4**). Check the `web` service logs in the `docker compose` terminal for MQTT connection status.\n\n- **Compose not found**  \n  Use `docker compose` (space), not `docker-compose`. Verify with `docker compose version`.\n\n---\n\n## 🔮 Potential future enhancements\n\n- Live streaming (WebSockets/SSE) and real‑time peak markers  \n- Postgres + Alembic migrations; retention policies  \n- Per‑feeder/zone filters, meter list \u0026 drill‑downs  \n- Export endpoints (CSV/Parquet) and API tokens  \n- Alarm delivery channels (email/Slack/webhooks) and acknowledge UI  \n- IEC 61850/DNP3 gateways; AMI head‑end adapters  \n- Role‑based access, dashboards per site\n\n---\n\n## 📚 Tech references (quick)\n- Flask application factory \u0026 blueprints  \n- Eclipse Paho MQTT client (Python)  \n- APScheduler BackgroundScheduler  \n- Chart.js getting started  \n- pandas `DataFrame.resample()`  \n- Docker Desktop / Docker Compose v2  \n- Eclipse Mosquitto broker (official image)\n\n*(See repository Wiki for links.)*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaffybird56%2Fhome-energymonitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchaffybird56%2Fhome-energymonitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchaffybird56%2Fhome-energymonitor/lists"}