{"id":13735454,"url":"https://github.com/oncleben31/ha-pool_pump","last_synced_at":"2025-07-10T17:02:38.216Z","repository":{"id":37428295,"uuid":"258807132","full_name":"oncleben31/ha-pool_pump","owner":"oncleben31","description":"🏊💻Pool pump manager for Home Assistant","archived":false,"fork":false,"pushed_at":"2022-05-02T21:47:58.000Z","size":197,"stargazers_count":56,"open_issues_count":10,"forks_count":19,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2025-06-09T05:46:02.552Z","etag":null,"topics":["custom-component","hacktoberfest","hacs","home-assistant","home-automation","pool-pump","swimming-pool"],"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/oncleben31.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-25T15:18:38.000Z","updated_at":"2025-05-19T04:20:35.000Z","dependencies_parsed_at":"2022-08-18T23:41:21.766Z","dependency_job_id":null,"html_url":"https://github.com/oncleben31/ha-pool_pump","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":"ludeeus/integration_blueprint","purl":"pkg:github/oncleben31/ha-pool_pump","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncleben31%2Fha-pool_pump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncleben31%2Fha-pool_pump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncleben31%2Fha-pool_pump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncleben31%2Fha-pool_pump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oncleben31","download_url":"https://codeload.github.com/oncleben31/ha-pool_pump/tar.gz/refs/heads/dev","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oncleben31%2Fha-pool_pump/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264613344,"owners_count":23637339,"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":["custom-component","hacktoberfest","hacs","home-assistant","home-automation","pool-pump","swimming-pool"],"created_at":"2024-08-03T03:01:07.037Z","updated_at":"2025-07-10T17:02:38.163Z","avatar_url":"https://github.com/oncleben31.png","language":"Python","funding_links":[],"categories":["Modules tiers utiles pour (ou par) des utilisateurs francophones"],"sub_categories":["Intégrations Personnalisées (Custom Components)"],"readme":"# Pool Pump Manager\r\n\r\n[![GitHub Release][releases-shield]][releases]\r\n[![GitHub Activity][commits-shield]][commits]\r\n[![License][license-shield]](LICENSE)\r\n\r\n[![hacs][hacsbadge]][hacs]\r\n\r\n[![Discord][discord-shield]][discord]\r\n[![Discord francophone][discord-fr-shield]][discord-fr]\r\n[![Community Forum][forum-shield]][forum]\r\n\r\n_Component developed by using the amazing development template [blueprint][blueprint]._\r\n\r\nThis custom component for Home Assistant can be used to automatically control\r\na pool pump that is turned on/off by a switch that Home Assistant can control.\r\n\r\nThis component is based on the work of [@exxamalte](https://github.com/exxamalte/home-assistant-customisations/tree/master/pool-pump).\r\n\r\nOn top of the original version by @exxamalte, this version can be installed by HACS\r\nand you can use the [blueprint][blueprint] feature to quickly fork this repo and\r\nhave a working development environment in a container.\r\n\r\nI will adapt it to my needs. At completion this plugin will compute the filtering\r\nschedule taking into account the pool water temperature.\r\n\r\n## Minimum requirements\r\n\r\n* A switch supported in Home Assistant that can turn on/off power to your\r\n  pool pump.\r\n\r\n## Features\r\n\r\n* Compute the total duration according to the pool water temperature.\r\n* Can control any switch (or other entity) that supports being turned on/off.\r\n* Support for distinguishing three different switch modes:\r\n    * Auto: Turn switch on/off automatically based on rules and configuration.\r\n    * On: Turn switch on.\r\n    * Off: Turn switch off.\r\n* Splits the total target duration into two runs around the solar noon.\r\n1/3 before ans 2/3 after to allow filtering during the hottest part of the day.\r\n* You can add a customizable break between the two runs.\r\n* Initializes an entity (`pool_pump.schedule`) that shows the current or next\r\n  run of the pool pump.\r\n* Optional: Support for a water level sensor to specify an entity that indicates if the\r\n  pool has reached a critical water level in which case the pool pump should\r\n  not run at all.\r\n\r\n## Installation\r\n\r\n### HACS installation\r\n\r\n1. Install [HACS](https://hacs.xyz/). That way you get updates automatically.\r\n2. Add this Github repository as custom repository in HACS settings.\r\n3. search and install \"Pool Pump Manger\" in HACS and click `install`.\r\n4. Modify your `configuration.yaml` as explain below.\r\n5. Restart Home Assistant.\r\n\r\n### Manual installation\r\n\r\n1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`).\r\n2. If you do not have a `custom_components` directory (folder) there, you need to create it.\r\n3. In the `custom_components` directory (folder) create a new folder called `pool_pump`.\r\n4. Download _all_ the files from the `custom_components/pool_pump/` directory (folder) in this repository.\r\n5. Place the files you downloaded in the new directory (folder) you created.\r\n6. Modify your `configuration.yaml` as explain below\r\n7. Restart Home Assistant\r\n\r\n## Configuration\r\n\r\nIn the following examples we are assuming that you have a switch that is\r\nconnected to your pool pump and can turn that on/off already. That switch\r\nis already integrated into Home Assistant with entity id `switch.pool_pump_switch`.\r\n\r\n### Tri-state switch\r\n\r\nThe following configuration wraps the switch into a tri-state switch which\r\nsupports 3 modes - Auto, On, Off.\r\nThe automation are required to translate each state into an action on the\r\nactual switch connected to the pool pump.\r\n\r\nThe last two automation are the ones that actually checks the pool pump state.\r\nThe first is triggered at regular intervals (5 minutes) from shortly before\r\nsunrise to shortly after sunset. And the second automation is triggered by\r\ncertain events - the start of Home Assistant, immediately when you put the pool\r\npump into 'Auto' mode, and whenever several key levers and sensors change.\r\n\r\n```yaml\r\ninput_select:\r\n  pool_pump_mode:\r\n    name: Pool Pump mode\r\n    options:\r\n      - 'Auto'\r\n      - 'On'\r\n      - 'Off'\r\n    initial: 'Auto'\r\n    icon: mdi:water-pump\r\n\r\nautomation:\r\n  - alias: 'Pool Pump On'\r\n    trigger:\r\n      - platform: state\r\n        entity_id: input_select.pool_pump_mode\r\n        to: 'On'\r\n    action:\r\n      service: homeassistant.turn_on\r\n      entity_id: switch.pool_pump_switch\r\n\r\n  - alias: 'Pool Pump Off'\r\n    trigger:\r\n      - platform: state\r\n        entity_id: input_select.pool_pump_mode\r\n        to: 'Off'\r\n    action:\r\n      service: homeassistant.turn_off\r\n      entity_id: switch.pool_pump_switch\r\n\r\n  - alias: 'Check Pool Pump Periodically'\r\n    trigger:\r\n      - platform: time_pattern\r\n        minutes: '/5'\r\n        seconds: 00\r\n    action:\r\n      service: pool_pump.check\r\n\r\n  - alias: 'Check Pool Pump on Event'\r\n    trigger:\r\n      - platform: homeassistant\r\n        event: start\r\n      - platform: state\r\n        entity_id:\r\n          - sensor.pool_water_temperature\r\n          - input_select.pool_pump_mode\r\n          - binary_sensor.pool_water_level_critical\r\n    action:\r\n      service: pool_pump.check\r\n```\r\n\r\n### Number of hours to run the pool pump\r\n\r\nThe total duration of the pool pump is computed using the pool water temperature.\r\nYou can use a sensor (like in the example below: `sensor.pool_water_temperature`) or you can\r\nuse an `input_number` replacing the sensor to manually set the water temperature .\r\n\r\nCurrently this integration is using an Abacus algorithm. You can go to [py_pool_pump](https://github.com/oncleben31/pypool-pump)\r\nfor detailed information.\r\n\r\n### Critical Water Level\r\n\r\nIf the pool pump is fed through a skimmer then there is typically a minimum\r\nwater level under which the pool pump does not receive enough water anymore\r\nand starts pulling in air which is not ideal.\r\n\r\nThe Pool Pump manager supports specifying an entity id using parameter\r\n`water_level_critical_entity_id`. If that entity is `on` the pool pump will\r\nnot turn on, and if it is `off` then the manager will just follow its time/sun\r\nbased algorithm to turn the pool pump on or off.\r\n\r\nSetting thin entity dedicated to critical water level is optional.\r\n\r\n### Pool Pump integration configuration\r\n\r\nThe pool pump component needs all the above entities as input to be able to\r\nmake the right decision and turn the pool pump on or off automatically.\r\n\r\n```yaml\r\npool_pump:\r\n  switch_entity_id: switch.pool_pump_switch\r\n  pool_pump_mode_entity_id: input_select.pool_pump_mode\r\n  pool_temperature_entity_id: sensor.pool_water_temperature\r\n  # optional:\r\n  water_level_critical_entity_id: binary_sensor.pool_water_level_critical\r\n  schedule_break_in_hours: 1.0\r\n```\r\n\r\nDefault value for `schedule_break_in_hours` is 0 hours.\r\n\r\n## Contributions are welcome!\r\n\r\nIf you want to contribute to this please read the [Contribution guidelines](CONTRIBUTING.md)\r\n\r\n***\r\n\r\n[blueprint]: https://github.com/custom-components/blueprint\r\n[commits-shield]: https://img.shields.io/github/commit-activity/y/oncleben31/ha-pool_pump.svg?style=for-the-badge\r\n[commits]: https://github.com/oncleben31/ha-pool_pump/commits/master\r\n[hacs]: https://github.com/custom-components/hacs\r\n[hacsbadge]: https://img.shields.io/badge/HACS-Custom-orange.svg?style=for-the-badge\r\n[discord]: https://discord.gg/Qa5fW2R\r\n[discord-fr]: https://discord.gg/JeTFJzE$\r\n[discord-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge\u0026label=HA%20Discord\r\n[discord-fr-shield]: https://img.shields.io/discord/542746125292273674?style=for-the-badge\u0026label=Discord%20francophone\r\n[forum-shield]: https://img.shields.io/badge/community-forum-brightgreen.svg?style=for-the-badge\r\n[forum]: https://community.home-assistant.io/\r\n[license-shield]: https://img.shields.io/github/license/custom-components/blueprint.svg?style=for-the-badge\r\n[releases-shield]: https://img.shields.io/github/release/oncleben31/ha-pool_pump.svg?style=for-the-badge\r\n[releases]: https://github.com/oncleben31/ha-pool_pump/releases\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foncleben31%2Fha-pool_pump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foncleben31%2Fha-pool_pump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foncleben31%2Fha-pool_pump/lists"}