{"id":16237662,"url":"https://github.com/vortigont/espem","last_synced_at":"2025-07-03T03:04:13.254Z","repository":{"id":45709292,"uuid":"87740902","full_name":"vortigont/espem","owner":"vortigont","description":"Energy monitor with dashboard/metrics collector based on ESP32 controller and PeaceFair PZEM-004T/PZEM-004Tv30 Power Meter","archived":false,"fork":false,"pushed_at":"2025-02-14T04:24:24.000Z","size":2459,"stargazers_count":73,"open_issues_count":3,"forks_count":19,"subscribers_count":10,"default_branch":"master","last_synced_at":"2025-07-03T03:04:10.044Z","etag":null,"topics":["dashboard","energy-monitor","energymeter","esp32","esp8266","iot","monitor","monitoring","powermeter","pzem-004t","pzem-004tv30","pzem-016"],"latest_commit_sha":null,"homepage":"","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/vortigont.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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}},"created_at":"2017-04-09T21:42:24.000Z","updated_at":"2025-05-12T12:47:44.000Z","dependencies_parsed_at":"2023-12-09T15:23:48.108Z","dependency_job_id":"d6b3bc93-e075-4517-90d6-fb81c9219fd5","html_url":"https://github.com/vortigont/espem","commit_stats":{"total_commits":120,"total_committers":1,"mean_commits":120.0,"dds":0.0,"last_synced_commit":"77b1f60f5f1cbffee74b8e07780a1aa7f01733b7"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/vortigont/espem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vortigont%2Fespem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vortigont%2Fespem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vortigont%2Fespem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vortigont%2Fespem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vortigont","download_url":"https://codeload.github.com/vortigont/espem/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vortigont%2Fespem/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263250596,"owners_count":23437288,"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","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":["dashboard","energy-monitor","energymeter","esp32","esp8266","iot","monitor","monitoring","powermeter","pzem-004t","pzem-004tv30","pzem-016"],"created_at":"2024-10-10T13:36:31.782Z","updated_at":"2025-07-03T03:04:13.226Z","avatar_url":"https://github.com/vortigont.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"__[BUILD](/docs/BUILD.md) | [USAGE](/docs/USAGE.md) | [CHANGELOG](/CHANGELOG.md)__ | [![PlatformIO CI](https://github.com/vortigont/espem/actions/workflows/pio_build.yml/badge.svg)](https://github.com/vortigont/espem/actions/workflows/pio_build.yml)\n## Energy monitor based on ESP32 controller and Peacefair PZEM-004Tv30 Power Meter\n\nA code for ESP32 controller and a set of web-tools to gather, analyse, monitor and view stat and graphs\nfor [Peacefair](https://peacefair.aliexpress.com/store/1773456/) PZEM-004Tv30 PowerMeter.\n\n\n## Features\n- WebUI via self-hosted HTTP/WebSocket server\n- Real-time gauges and power charts\n- MQTT publishing metrics data in json format\n- 3 level Tiered TimeSeries metrics collector in controller's memory pool\n- data/metrics export via json\n- compressed OTA updating via [esp32-flashz](https://github.com/vortigont/esp32-flashz) lib\n- espem could be build to run via DummyPZEM emulator for prototyping and firmware testing without connecting to a real PZEM device\n\n## ESPEM WebUI Dashboard\n\n\u003cimg src=\"/examples/espemembui.png\" alt=\"espem ui\" width=\"50%\"/\u003e\n\n## ESPEM on Mobile phone\n\n|  \u003cimg src=\"/examples/mobile02_res.webp\" alt=\"espem mobile ui\" width=\"30%\"/\u003e | \u003cimg src=\"/examples/mobile03_res.webp\" alt=\"espem mobile ui\" width=\"30%\"/\u003e  |  \u003cimg src=\"/examples/mobile04_res.webp\" alt=\"espem mobile ui\" width=\"30%\"/\u003e | \u003cimg src=\"/examples/mobile05_res.webp\" alt=\"espem mobile ui\" width=\"30%\"/\u003e |\n\n\nTo find EspEM in your WiFi network you can use [mDNS Discovey](https://play.google.com/store/apps/details?id=com.mdns_discovery.app\u0026hl=ja\u0026gl=US) app for Android or any other that can work with mDNS or `Bonjour` for iPhone.\nJust find `http` enabled service in the app and open with a browser.\n\n\n## MQTT\nMQTT server publishing and connection could be configured via \"Settings\" - \"MQTT\". \nIt will publish pzem metrics to topic `~/pub/pzem/jmetrics` on each update cycle. Where `~` is topic prefix, default is `EmbUI/[DeviceID]/`.\n\nMessage structure is a dictionary with PZEM metrics in an integer format in a way PZEM sends it via MODBUS.\n`[{\"stale\":false,\"age\":999,\"U\":2180,\"I\":503,\"P\":778,\"W\":560,\"Pf\":71,\"freq\":505}]`\n\nI.e. \u003cbr\u003e\n`U` - denoted voltage in decivolts\u003cbr\u003e\n`I` - current im mA\u003cbr\u003e\n`P` - power in deciwatts\u003cbr\u003e\n`W` - energy in Wh\u003cbr\u003e\n`Pg` - power factor in percents\u003cbr\u003e\n`freq` - is frequency in dHz\u003cbr\u003e\n`stale` - denotes if data is stale, i.e. has not been updated recently\u003cbr\u003e\n`age` - data age in ms\u003cbr\u003e\n\n\u003cimg src=\"/examples/mqtt.png\" alt=\"espem mqtt\" width=\"75%\"/\u003e\n\n## Tiered TimeSeries data Sampling\nController will keep a history of previous data received from PZEM in it's memory in a tiered memory pool. It is commonly used for time series data where the longer the data age then less frequent is sampling rate of the data to keep. All data resides in volatale `memory`, so it will be lost on power cycle or reset. \nBy default there are 3 levels of TimeSeries in a pool\n\n\n\n| Level | Samples count | Sampling interval | Time range          |\n| ----- | ------------- | ----------------- | ------------------- |\n| L1    | 900           | 1 sec             | 15 min              |\n| L2    | 1000          | 15 sec            | 250 min (abt 4 hrs) |\n| L3    | 1000          | 300 sec           | ~83 hrs            |\n\nNumber of samples and interval could be adjusted per each level via \"Espem setup\" - \"TimeSeries collector\" configuration.\n\n#### ESPEM TS Options\n\n\u003cimg src=\"/examples/ts_setup.png\" alt=\"espem ts opts\" width=\"75%\"/\u003e\n\n\n\n#### Averaging\nFor levels with sampling interval more that 1 second an averaging function is used to calculate mean value between intervals. I.e. if sampling interval is set to 60 sec and you power level was about 5 watt for 55 seconds and became 100 watts for the last 5 sec when sampling was taken, then resulting power value would be slightly over 5 watts, but not 100 W.\n\n#### Memory consumption\n1000 samples takes about 25 KiB of RAM memory (one sample takes 28 bytes), so plan you pool accordingly. If your board has SPI-RAM then you can have a huge pool worth monthes of data to be kept :)\n\n#### Data export\nTimeSeries Data could be exported in json format per each tier level\n\nTier 1 URL - [http://espem/samples.json?tsid=1](http://espem/samples.json?tsid=1)\u003cbr\u003e\nTier 2 URL - [http://espem/samples.json?tsid=2](http://espem/samples.json?tsid=2)\u003cbr\u003e\nTier 3 URL - [http://espem/samples.json?tsid=3](http://espem/samples.json?tsid=3)\u003cbr\u003e\n\nAn example of exported data:\n```\n[\n    {\"t\":1701876803000,\"U\":216.60,\"I\":0.51,\"P\":88,\"W\":7,\"hz\":49.7,\"pF\":0.79},\n    {\"t\":1701877103000,\"U\":225.00,\"I\":0.52,\"P\":90,\"W\":14,\"hz\":50.1,\"pF\":0.77}\n]\n```\nwhere:\u003cbr\u003e\n`t` - is a unix timestamp in milliseconds (prefered for js processing)\nother keys are PZEM metrics in float format\n\n\n## Legacy v2.x version\nAn older ESPEM version 2 was based on 3rd party lib. It's code still available under [2.x branch](https://github.com/vortigont/espem/tree/v2).\nESPEM Ver 3 switched to it's own library [pzem-edl](https://github.com/vortigont/pzem-edl). I wrote this lib to overcome limitations of the classic [olehs](https://github.com/olehs/PZEM004T)'s and [mandulaj](https://github.com/mandulaj/PZEM-004T-v30)'s libs. Being versatile those libs provided only basic functions talking to PZEM's using Arduino's blocking IO via serial port. New lib uses event-driven approach and provides extendable design API for multiple PZEM communication over single port.\n\n### Feature comparison\n|                      | [Version 2.x](https://github.com/vortigont/espem/tree/v2) | Version 3.0       |\n| -------------------- | --------------------------------------------------------- | ----------------- |\n| ESP8266              | YES                                                       | NO                |\n| ESP32                | YES                                                       | YES               |\n| PZEM004v30           | YES                                                       | YES               |\n| old PZEMv30          | YES                                                       | NO       |\n| Time Series Charts   | YES (Basic)                                               | YES (extendable)  |\n| TS in PSRAM          | NO                                                        | YES               |\n\n\n\n### Additional tools\nUnder /www there is a set of php/sql scripts that could be hosted undel LAMP to gather and calculate stats over long-term periods. Little bit outdated but still usable.\nNo need for any cloud services, spyware etc... just a raspberry/orangepi running web-server with sqlite/mysql DB. It's possible to collect data from any number of PZEM monitors and store it in the DB for a long-term stats or get a PowerChart sampled data from the espem itself.\n\n_*An example of exernal daily stats dashboard*_\n\n![espem gauges](/examples/webstat/gauges.th.png)\n\n\n### Power chart with sampled data\n\n![espem sampled data](/examples/webstat/sampleschart01.th.png)\n\n\n\n#### License\n\nThis code is available under the GPLv3 license\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvortigont%2Fespem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvortigont%2Fespem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvortigont%2Fespem/lists"}