{"id":50445286,"url":"https://github.com/tonikelope/multimetreitor","last_synced_at":"2026-05-31T21:02:40.780Z","repository":{"id":361466827,"uuid":"1254530596","full_name":"tonikelope/multimetreitor","owner":"tonikelope","description":"ESP8266 + PZEM-004T home energy monitor: real-time V/A/W/kWh/Hz/PF over MQTT, thermal ICP trip model, configurable alerts, 16x2 LCD, web panel, OTA, NTP and a Rainmeter desktop skin.","archived":false,"fork":false,"pushed_at":"2026-05-30T19:29:22.000Z","size":1467,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-30T20:14:47.010Z","etag":null,"topics":["arduino","energy-monitor","esp8266","home-automation","iot","mqtt","nodemcu","ota","power-meter","pzem-004t","rainmeter","smart-home"],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tonikelope.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":"2026-05-30T17:24:33.000Z","updated_at":"2026-05-30T19:29:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tonikelope/multimetreitor","commit_stats":null,"previous_names":["tonikelope/multimetreitor"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/tonikelope/multimetreitor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonikelope%2Fmultimetreitor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonikelope%2Fmultimetreitor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonikelope%2Fmultimetreitor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonikelope%2Fmultimetreitor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tonikelope","download_url":"https://codeload.github.com/tonikelope/multimetreitor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tonikelope%2Fmultimetreitor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33748607,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"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":["arduino","energy-monitor","esp8266","home-automation","iot","mqtt","nodemcu","ota","power-meter","pzem-004t","rainmeter","smart-home"],"created_at":"2026-05-31T21:02:35.219Z","updated_at":"2026-05-31T21:02:40.769Z","avatar_url":"https://github.com/tonikelope.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ MULTIMETREITOR\n\nHome electrical consumption monitor based on the **ESP8266** and the **PZEM-004T v3.0** energy meter. It measures the voltage, current, power, energy, frequency and power factor of your mains installation, shows them on an LCD display and publishes them over **MQTT**. It also includes a **thermal model of the ICP** (the main circuit breaker / power-control switch used in Spain) that warns you *before* the utility cuts your power for drawing too much.\n\nIt ships with a **web configuration panel** served by the device itself and a **Rainmeter skin** to display the metrics on the Windows desktop.\n\n---\n\n## ✨ Features\n\n- 📊 **Real-time measurement** via the PZEM-004T v3: voltage (V), current (A), power (W), energy (kWh), frequency (Hz) and power factor.\n- 🔥 **ICP thermal model**: simulates the trip curve of a thermal-magnetic breaker using logarithmic interpolation and a configurable cooldown. Warns when the accumulated \"thermal load\" approaches the trip point (0–100 %).\n- 🚨 **Configurable alerts**: ICP, overvoltage, undervoltage and consumption (by amperes or watts), with an optional **buzzer**.\n- 🖥️ **16×2 I2C LCD** with metrics selectable through a bitmask plus WiFi/MQTT status indicators.\n- 🌐 **Responsive web panel** (HTML embedded in `PROGMEM`) to configure everything without recompiling.\n- 🌍 **Bilingual UI (Spanish / English)** in both the web panel and the Rainmeter skin, with a one-click toggle. Default is Spanish.\n- 📡 **MQTT publishing** with a unified JSON payload and *retained* messages.\n- 🗓️ **Monthly consumption history** (24 months) with automatic energy reset on month change, persisted to EEPROM.\n- 🕐 **NTP synchronization** with the Spanish mainland timezone (CET/CEST with automatic DST changes).\n- 🔄 **OTA updates** (Over-The-Air), password protected.\n- 💾 **EEPROM persistence** with integrity validation (magic + version) and wear protection (1-hour write cooldown for automatic tasks).\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/web_ui_en_mobile.png\" alt=\"MULTIMETREITOR web configuration panel (mobile, English)\" width=\"300\"\u003e\n  \u003cbr\u003e\n  \u003cem\u003eWeb configuration panel — mobile view (English)\u003c/em\u003e\n\u003c/div\u003e\n\n---\n\n## 🔌 Hardware\n\n| Component             | Detail                                    |\n|-----------------------|-------------------------------------------|\n| MCU                   | ESP8266 (NodeMCU / Wemos D1 mini)         |\n| Meter                 | PZEM-004T v3.0 (UART)                      |\n| Display               | 16×2 LCD with I2C backpack (address `0x27`) |\n| Alarm                 | Active buzzer                             |\n\n### Wiring (pins)\n\n| Signal            | ESP8266 pin | Notes                          |\n|-------------------|-------------|--------------------------------|\n| PZEM RX           | `D6`        | `SoftwareSerial` RX            |\n| PZEM TX           | `D5`        | `SoftwareSerial` TX            |\n| LCD SDA / SCL     | `D2` / `D1` | Default I2C (`Wire`)           |\n| Buzzer            | `D7`        | Digital output                 |\n\n![Wiring diagram](docs/multimetreitor_wiring.png)\n\n---\n\n## 🧩 Firmware architecture\n\n![Firmware architecture](docs/multimetreitor_architecture.png)\n\n**Monolithic** firmware (`multimetreitor.ino`) organized into functional blocks:\n\n- **Config / EEPROM** — `struct AppConfig` serialized to EEPROM with validation and default values.\n- **WiFi / OTA / NTP** — connection with retries, OTA and time sync via a POSIX TZ string.\n- **MQTT** — publishes state, log and status; recovers the ICP state at boot (reads the *retained* message from its own topic).\n- **ICP model** (`computeICP`) — integrates the thermal load based on the I/Iₙ ratio using a 7-segment logarithmically interpolated curve.\n- **Alerts** (`evaluateAlerts`) — priority: ICP → overvoltage → undervoltage → consumption.\n- **LCD** (`composeLCDLines`) — composes two 16-character lines with the active metrics.\n- **Web server** — configuration panel + JSON endpoints.\n- **History** — monthly consumption management and month-change handling.\n\n### MQTT topics\n\n| Topic                          | Direction  | Content                                    |\n|--------------------------------|------------|--------------------------------------------|\n| `electricidad/casa/estado`     | publish    | JSON with all metrics (*retained*)         |\n| `electricidad/casa/icp`        | subscribe  | ICP state recovery at boot                 |\n| `multimetreitor/status`        | publish    | `online` (*retained*)                      |\n| `multimetreitor/serial`        | publish    | Serial-port log                            |\n\n**Example state payload:**\n\n```json\n{\n  \"voltaje\": \"230.5V\",\n  \"corriente\": \"12.34A\",\n  \"potencia\": \"2840W\",\n  \"energia\": \"123.45kWh\",\n  \"factor_potencia\": \"0.95\",\n  \"frecuencia\": \"50.0Hz\",\n  \"icp\": \"62%\",\n  \"timestamp\": 1700000000\n}\n```\n\n\u003e ℹ️ The JSON keys are in Spanish (`voltaje`, `corriente`, …) because they are the published data contract consumed by the Rainmeter skin.\n\n---\n\n## 🖥️ Rainmeter skin\n\n`Rainmeter/Multimetreitor/` contains a skin that displays the MULTIMETREITOR metrics directly on the Windows desktop, consuming the data over MQTT.\n\n**Skin features:**\n\n- Reads from the MQTT broker through Rainmeter's **[MqttClient](https://github.com/anschnapp/MqttPlugin)** plugin and parses the JSON published by the firmware.\n- Shows: **Voltage, Frequency, Current, ICP (progress bar), Power, Power Factor and monthly Consumption**.\n- **Visual warnings**: red background on *Current* when it exceeds 30 A, and an ICP bar proportional to the thermal load (width = `ICP × 2.5`).\n- Automatically fixes locale decimals (comma → dot) and the connection status for internal calculations (`Substitute`).\n- Includes optional support for a **water heater** (`calentador_estado`, `calentador_corriente`) that lights up red when it is off.\n- **Bilingual labels (ES/EN)** — click the language button (top-right of the skin) to switch; the choice is saved in the `Language` variable (see [Languages](#-languages-es--en)).\n\n### Installing the skin\n\n1. Install [Rainmeter](https://www.rainmeter.net/).\n2. Install the **MqttClient** plugin (copy the `.dll` into `Rainmeter/Plugins`).\n3. Copy the `Rainmeter/Multimetreitor` folder into `Documents/Rainmeter/Skins/`.\n4. Edit the `[Variables]` section of the `.ini` and set:\n   - `MQTT_BROKER` → your MQTT broker IP.\n   - `MQTT_TOPIC` → the firmware's state topic (`electricidad/casa/estado`).\n5. Load the skin from Rainmeter (*Refresh all* / *Manage*).\n\n\u003e ℹ️ By default the `.ini` ships with `MQTT_TOPIC=rainmeter/multimetreitor`; change it to the topic the firmware actually publishes (`electricidad/casa/estado`) or adapt the topic on the device.\n\n---\n\n## 🌍 Languages (ES / EN)\n\nBoth UIs are bilingual and **default to Spanish**. Only the labels/UI text are translated — the metric values and units (V, A, W…) are language-neutral.\n\n### Web panel\n- Click the **`EN` / `ES` button** at the top-right of the page to switch language instantly (client-side, no reload).\n- The choice is remembered per browser via `localStorage` (`mmt_lang`).\n- To add or tweak strings, edit the `I18N = { es: {…}, en: {…} }` dictionary in the embedded `\u003cscript\u003e` of `multimetreitor.ino`. Translatable elements are marked with `data-i18n=\"key\"`.\n\n### Rainmeter skin\n- Click the **language button** at the top-right of the skin to toggle ES ⇄ EN. The choice is persisted to the `Language` variable in the `.ini` (`!WriteKeyValue` + `!Refresh`).\n- This uses Rainmeter's standard localization pattern: a `Language` variable in `[Variables]` plus `@Include=#@#Lang_#Language#.inc`.\n- Translations live in `Rainmeter/Multimetreitor/@Resources/Lang_ES.inc` and `Lang_EN.inc`. To change the default, set `Language=ES` (or `EN`) in `[Variables]`.\n\n---\n\n## 🛠️ Build and flash\n\n**Requirements (Arduino IDE / arduino-cli):**\n\n- **ESP8266** Arduino core.\n- Libraries: `PubSubClient`, `LiquidCrystal_I2C`, `PZEM004Tv30`, `ArduinoJson`, `ESP8266WebServer`, `ArduinoOTA`, `EspSoftwareSerial`.\n\n**Steps:**\n\n1. **Create your `secrets.h`** (see below) with your WiFi credentials.\n2. Open `multimetreitor.ino` in the Arduino IDE.\n3. Select the matching ESP8266 board.\n4. Adjust the static IP / network configuration in `multimetreitor.ino` if needed.\n5. Upload over USB the first time; afterwards you can update over **OTA** (hostname `multimetreitor-ota`).\n\n### 🔐 Credentials (`secrets.h`)\n\nWiFi credentials are kept **out of the source tree** in a `secrets.h` file that is git-ignored, so they are never committed. The repo ships a template, `secrets.h.example`.\n\nTo configure after cloning:\n\n```bash\ncp secrets.h.example secrets.h\n```\n\nThen edit `secrets.h` with your own values:\n\n```cpp\n#define WIFI_SSID      \"YOUR_WIFI_SSID\"\n#define WIFI_PASSWORD  \"YOUR_WIFI_PASSWORD\"\n```\n\n`multimetreitor.ino` includes it via `#include \"secrets.h\"` and uses `WIFI_SSID` / `WIFI_PASSWORD`. The WiFi password is also reused as the OTA password.\n\n\u003e ℹ️ The static IP (`192.168.1.24`), gateway and hostnames are configured directly in `multimetreitor.ino` — adjust them to your network.\n\n---\n\n## 🏠 Network note\n\nMULTIMETREITOR is designed as a **local home-network appliance**: the web panel keeps things fast and simple and is meant to live inside your own trusted Wi‑Fi. As such, **run it on a secure/trusted network and don't expose it directly to the Internet** (no port-forwarding) — that's the intended setup. For multi-user or untrusted environments you can add HTTP Basic Auth to the control endpoints.\n\n---\n\n## 📝 License\n\nLicensed under the **GNU General Public License v3.0** — see [LICENSE](LICENSE).\n\nCopyright © tonikelope\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonikelope%2Fmultimetreitor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftonikelope%2Fmultimetreitor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftonikelope%2Fmultimetreitor/lists"}