{"id":17856815,"url":"https://github.com/peterbrain/boilr","last_synced_at":"2025-07-29T15:39:18.767Z","repository":{"id":50161570,"uuid":"298450212","full_name":"PeterBrain/boilr","owner":"PeterBrain","description":"Optimizes water heating by combining a Fronius photovoltaic (PV) inverter with a Raspberry Pi, making optimal use of excess solar energy. The system avoids low-compensation grid exports by redirecting surplus power to heat water instead.","archived":false,"fork":false,"pushed_at":"2024-10-21T16:46:49.000Z","size":1816,"stargazers_count":10,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-10-22T05:42:23.992Z","etag":null,"topics":["api","boiler","docker","docker-compose","docker-container","fronius","fronius-inverter","fronius-solar-api","mqtt","mqtt-client","ohmpilot","pv","python","python3","raspberry-pi","raspberrypi","solar","solar-energy","waterheater"],"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/PeterBrain.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}},"created_at":"2020-09-25T02:46:11.000Z","updated_at":"2024-10-19T20:48:12.000Z","dependencies_parsed_at":"2023-10-13T16:01:16.294Z","dependency_job_id":"a2faad16-94f3-491d-814b-02c087f9112f","html_url":"https://github.com/PeterBrain/boilr","commit_stats":{"total_commits":58,"total_committers":3,"mean_commits":"19.333333333333332","dds":0.08620689655172409,"last_synced_commit":"b1e00f6fe52f06ddeb48e08a2695df1eddb00abf"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterBrain%2Fboilr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterBrain%2Fboilr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterBrain%2Fboilr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PeterBrain%2Fboilr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PeterBrain","download_url":"https://codeload.github.com/PeterBrain/boilr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244630081,"owners_count":20484309,"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":["api","boiler","docker","docker-compose","docker-container","fronius","fronius-inverter","fronius-solar-api","mqtt","mqtt-client","ohmpilot","pv","python","python3","raspberry-pi","raspberrypi","solar","solar-energy","waterheater"],"created_at":"2024-10-28T03:09:26.062Z","updated_at":"2025-03-20T14:30:58.100Z","avatar_url":"https://github.com/PeterBrain.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Boilr\n\n[![latest release][github-release-shield]][github-release-link]\n[![coverage][codecov-shield]][codecov-coverage]\n\nWater boiler automation with a Fronius pv inverter on a Raspberry Pi.\n\nThe objective was to harness the surplus generated by the PV system and enhance daytime self-consumption through water heating. This approach not only reduces the energy fed back to the grid but also curtails the need for heating resources like pellets, oil, or other fuels.\n\n![sufficiency over one day][fronius-dashboard-graph]\nThe yellow area illustrates the self-consumed energy after using Boilr (this program) to increase self-sufficiency. The blue line is the overall energy consumption. The gray region represents the surplus energy directed into the grid. The green line corresponds to the battery charge level, depicted as a percentage, while the green segment represents the surplus energy channeled into the battery.\n\n![self-sufficiency example][fronius-dashboard]\nHere, it's evident that all the energy generated by the PV system serves either to charge the battery or for direct consumption (inclusive of electrical devices and the water heater's heating element).\n\n## Features\n\n- Heat water with surplus power from PV\n- Active date \u0026 time spans\n- MQTT contactor status\n- Operating modes\n  - Interactive\n  - Daemon\n- Manual contactor override\n\n## Setup\n\nRefer to this for setup instructions: [Setup.md][setup]\n\nCheck out this [Sample configuration][config-reference] for reference.\n\n## Usage\n\nStarting service:\n\n```bash\nboilr start\n```\n\nStopping service:\n\n```bash\nboilr stop\n```\n\nRun verbosely in command line with custom config path:\n\n```bash\nboilr -c ./config.yaml -v run\n```\n\nComplete guide (boilr -h):\n\n```bash\nusage: boilr [-h] [-c CONFIG] [-v] {start,stop,status,restart,run,manual} ...\n\nWater boiler automation with a Fronius pv inverter on a Raspberry Pi.\n\noptions:\n  -h, --help            show this help message and exit\n  -c CONFIG, --config CONFIG\n                        Path to the configuration file. (default: None)\n  -v, --verbose         Increase verbosity (default: False)\n\ncommands:\n  Choose between the following positional arguments\n\n  {start,stop,status,restart,run,manual}\n    start               Start boilr service\n    stop                Stop boilr service\n    status              Show the status of boilr service\n    restart             Restart boilr service\n    run                 Start boilr in command-line\n    manual              Manually override contactor\n\nAdditional hardware required. Please check:\nhttps://github.com/PeterBrain/boilr\n```\n\n\u003e [!IMPORTANT]\n\u003e In all operating modes Boilr needs permission to create a file in /var/log. If you run boilr as a daemon it needs permission to create a file in /var/run. Pytest needs write permission to /var/log too.\n\n## Requirements\n\nCheck out [Requirements][requirements] for more details.\n\n## Weaknesses\n\nThe existing design exhibits a significant limitation: in contrast to Ohmpilot[^1], a comparable Fronius product that boasts notably higher efficiency due to its use of PWM (Pulse Width Modulation), my setup operates solely in two states. It's either fully activated, providing maximum power to the heating coil, or completely deactivated. The optimal efficiency advantage is sacrificed on days when PV production falls just short of meeting both the household's current consumption and the water heating requirements.\n\n## Additional resources\n\n- Fronius official API documentation: [Documentation - Fronius Solar API V1][fronius-api-documentation]\n- Postman request collection: [Postman Collection - Fronius Solar API V1][fronius-api-collection]\n\n[^1]: \u003chttps://www.fronius.com/en/solar-energy/installers-partners/infocentre/news-row/ohmpilot-hot-water-with-solar-energy\u003e and \u003chttps://www.fronius.com/~/downloads/Solar%20Energy/Brochures/SE_BRO_Fronius_Ohmpilot_B2C_EN_MEACA.pdf\u003e\n\n\n[github-release-link]: https://github.com/peterbrain/boilr/releases\n[github-release-shield]: https://img.shields.io/github/v/release/peterbrain/boilr\n[codecov-coverage]: https://codecov.io/gh/PeterBrain/boilr\n[codecov-shield]: https://codecov.io/gh/PeterBrain/boilr/graph/badge.svg?token=NQDML8H7QA\n\n[fronius-dashboard-graph]: ./docs/sufficiency.jpg\n[fronius-dashboard]: ./docs/fronius.jpg\n\n[setup]: ./docs/Setup.md\n[requirements]: ./docs/Requirements.md\n[config-reference]: ./config.yaml\n\n[fronius-api-documentation]: https://www.fronius.com/~/downloads/Solar%20Energy/Operating%20Instructions/42%2C0410%2C2012.pdf\n[fronius-api-collection]: https://www.getpostman.com/collections/27c663306206d7fbf502\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterbrain%2Fboilr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterbrain%2Fboilr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterbrain%2Fboilr/lists"}