{"id":24642489,"url":"https://github.com/domectrl/ha-pid_controller","last_synced_at":"2025-03-20T13:34:07.692Z","repository":{"id":192024007,"uuid":"685858084","full_name":"domectrl/ha-pid_controller","owner":"domectrl","description":"PID controller integration for HomeAssitant","archived":false,"fork":false,"pushed_at":"2025-01-25T08:36:21.000Z","size":137,"stargazers_count":1,"open_issues_count":6,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-25T09:23:31.829Z","etag":null,"topics":["hacs","hacs-integration","homeassistant","pid","pid-control","pid-controller"],"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/domectrl.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-01T07:06:23.000Z","updated_at":"2025-01-25T08:36:25.000Z","dependencies_parsed_at":"2023-09-02T05:45:38.247Z","dependency_job_id":"b32d8835-bc62-47ca-96d0-ffdee85c662d","html_url":"https://github.com/domectrl/ha-pid_controller","commit_stats":{"total_commits":25,"total_committers":2,"mean_commits":12.5,"dds":"0.31999999999999995","last_synced_commit":"57d50f9481299058fa7b3b48b610e9eef1efa8b5"},"previous_names":["antonverburg/ha-pid_controller","domectrl/ha-pid_controller"],"tags_count":5,"template":false,"template_full_name":"ludeeus/integration_blueprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/domectrl","download_url":"https://codeload.github.com/domectrl/ha-pid_controller/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244619444,"owners_count":20482416,"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":["hacs","hacs-integration","homeassistant","pid","pid-control","pid-controller"],"created_at":"2025-01-25T13:11:55.784Z","updated_at":"2025-03-20T13:34:07.669Z","avatar_url":"https://github.com/domectrl.png","language":"Python","readme":"# PID Controller integration\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![Project Maintenance][maintenance-shield]\r\n\r\n[![Discord][discord-shield]][discord]\r\n[![Community Forum][forum-shield]][forum]\r\n\r\nThis integration contains a PID regulator. The value for an output number entity will be calculated using the [Proportional–Integral–Derivative algorithm (PID)](https://en.wikipedia.org/wiki/PID_controller). \r\n\r\nThe implementation of the PID controller contains bumpless operation, and is prevented against integral windup by clipping of the output value to the minimum and maximum of the corresponding output number entity.\r\n\r\nThis controller is typically useful in regulated systems. For example to regulate the speed of a water pump in a heat collector to keep the temperature difference between the outgoing and incomming water stream on a certain level, so that the heat collector will perform optimally.\r\n\r\nSetting up the optimal parameters for a PID controller can be a tough job. Depending on your particular job, you might already know more or less what the parameters should be. If required, you could use [manual tuning](https://en.wikipedia.org/wiki/PID_controller#Manual_tuning) to find optimal parameters. A small summary for PID tuning:\r\n- For kp, start with a small number (1) and gradually make it bigger if you see that the direct reaction of the controller is too low. Increase the kp, until the output oscillates, then set it to half of this value.\r\n- For ki, keep this number to 0 until kp is set. Then, start with a very small number (0.01). If you see that the reaction over time is only slowly rising, then increase it, until the controller regulates to the setpoint in a reasonable amount of time.\r\n- For kd, keep this number to 0 until kp and ki are set. Now, you can use the kd to prevent the regulator from overshooting. Only increase in small steps.\r\n\r\nThe PID controller code is shared with the [PID thermostat][pid_thermostat]. As an output for the controller, the [Slow PWM][slow_pwm] number can be used.\r\n\r\n**This integration will set up the following platforms.**\r\n\r\nPlatform | Description\r\n-- | --\r\n`number` | This platform can be used to control a number entity output to regulate a sensor value to a specific setpoint. The value of the controlker entity is the setpoint. As a sensor, any numerical sensor entity can be used. If two sensors are configured, the PID controller will act as a differential controller, using the difference between the two sensor values as input signal.\r\n\r\n\r\n## Installation\r\n\r\n### HACS (Preferred)\r\n1. [Add](http://homeassistant.local:8123/hacs/integrations) the custom integration repository: https://github.com/antonverburg/ha-pid_controller\r\n2. Select `PID Controller` in the Integration tab and click `download`\r\n3. Restart Home Assistant\r\n4. Done!\r\n\r\n### Manual\r\n1. Using the tool of choice open the directory (folder) for your HA configuration (where you find `configuration.yaml`).\r\n1. If you do not have a `custom_components` directory (folder) there, you need to create it.\r\n1. In the `custom_components` directory (folder) create a new folder called `pid_controller`.\r\n1. Download _all_ the files from the `custom_components/pid_controller/` directory (folder) in this repository.\r\n1. Place the files you downloaded in the new directory (folder) you created.\r\n1. Restart Home Assistant\r\n\r\n## Configuration via user interface:\r\n* In the user interface go to \"Configuration\" -\u003e \"Integrations\" click \"+\" and search for \"PID Controller\"\r\n* For a description of the configuration parameters, see [Configuration parameters](#configuration-parameters)\r\n\r\n## YAML Configuration\r\n\r\nAlternatlively, this integration can be configured and set up manually via YAML\r\ninstead. To enable the Integration sensor in your installation, add the\r\nfollowing to your `configuration.yaml` file:\r\n\r\n```yaml\r\n# Example configuration.yaml entry\r\nnumber:\r\n  - platform: pid_controller\r\n    name: PID regulator for heat collector\r\n    input1: sensor.water_temperature\r\n    output: number.pwm_pump\r\n```\r\n\r\n### Configuration parameters\r\n- name: Name of the PID controller.\r\n  \u003e required: true | type: string\r\n- output: `entity_id` for the output value. Must be a number device. The output will be limited to the minimum and maximum value of this number.\r\n  \u003e required: true | type: string\r\n- input1: `entity_id` for input sensor. Must be a numerical sensor.\r\n  \u003e required: true | type: string\r\n- input2: Optional secondary input sensor. If selected, the controller will work in differential mode.\r\n  \u003e required: false default: `(left empty)`| type: string\r\n- kp: Proportional gain factor, directly gaining the error to compensate the fault (Kp).\r\n  \u003e required: false | default: 1.0 | type: float\r\n- ki: Integration factor, reducing the offset fault over time (Ki).\r\n  \u003e required: false | default: 0.1 | type: float\r\n- kd: Differential factor, damping the overshoot (Kd).\r\n  \u003e required: false | default: 0.0 | type: float\r\n- direction: Regulation direction. When 'direct', the output will increase to decrease fault. When 'reverse', the output will decrease to decrease fault.\r\n  \u003e required: false | default: direct | type: string `('direct' or 'reverse')`\r\n- minimum: Minimal value of the pid_controller number setpoint.\r\n  \u003e required: false | default: 0 | type: float\r\n- maximum: Maximal value of the pid_controller number setpoint.\r\n  \u003e required: false | default: 100 | type: float\r\n- cycle_time: Cycle time for the controller loop.\r\n  \u003e required: false | default: 00:30:00 | type: time_period\r\n- step: Step value. Smallest value `0.001`.\r\n  \u003e required: false | type: float | default: 1\r\n- mode: Control how the number should be displayed in the UI. Can be set to `box` or `slider` to force a display mode.\r\n  \u003e required: false | type: string | default: '\"auto\"'\r\n- unique_id: Unique id to be able to configure the entity in the UI.\r\n  \u003e required: false | type: string\r\n\r\n### Full configuration example\r\n\r\n```yaml\r\nnumber:\r\n  - platform: pid_controller\r\n    name: PID regulator for heat collector\r\n    input1: sensor.water_temperature_in\r\n    input2: sensor.water_temperature_in\r\n    output: number.pwm_pump\r\n    kp: 2.0\r\n    ki: 0.5\r\n    kd: 0.01\r\n    direction: reverse\r\n    minimum: 10\r\n    maximum: 200\r\n    cycle_time:  {'hours':0, 'minutes':01, 'seconds': 00}\r\n    step: 3\r\n    mode: \"auto\"\r\n    unique_id: \"MyUniqueID_1234\"\r\n```\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[commits-shield]: https://img.shields.io/github/commit-activity/y/antonverburg/ha-pid_controller.svg?style=for-the-badge\r\n[commits]: https://github.com/antonverburg/ha-pid_controller/commits/main\r\n[hacs]: https://hacs.xyz/\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-shield]: https://img.shields.io/discord/330944238910963714.svg?style=for-the-badge\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/antonverburg/ha-pid_controller.svg?style=for-the-badge\r\n[maintenance-shield]: https://img.shields.io/badge/maintainer-antonverburg-blue.svg?style=for-the-badge\r\n[releases-shield]: https://img.shields.io/github/release/antonverburg/ha-pid_controller.svg?style=for-the-badge\r\n[releases]: https://github.com/antonverburg/ha-pid_controller/releases\r\n[slow_pwm]: https://github.com/antonverburg/ha-slow_pwm\r\n[pid_thermostat]: https://github.com/antonverburg/ha_pid_thermostat\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomectrl%2Fha-pid_controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdomectrl%2Fha-pid_controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomectrl%2Fha-pid_controller/lists"}