{"id":24642492,"url":"https://github.com/domectrl/ha-pid_thermostat","last_synced_at":"2025-03-20T13:34:08.367Z","repository":{"id":200011059,"uuid":"704213264","full_name":"domectrl/ha-pid_thermostat","owner":"domectrl","description":"PID thermostat for homeassitant","archived":false,"fork":false,"pushed_at":"2025-01-25T09:21:21.000Z","size":110,"stargazers_count":0,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-25T09:25:36.036Z","etag":null,"topics":["hacs","hacs-integration","homeassistant","pid","pid-controller","thermostat"],"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-10-12T19:24:02.000Z","updated_at":"2025-01-25T09:20:25.000Z","dependencies_parsed_at":"2023-12-31T03:43:40.421Z","dependency_job_id":"77142f97-ee2d-4418-bb56-856e002bc1b4","html_url":"https://github.com/domectrl/ha-pid_thermostat","commit_stats":{"total_commits":11,"total_committers":2,"mean_commits":5.5,"dds":"0.18181818181818177","last_synced_commit":"38e8113ca834ada1c9434d61908ee1a099d709f8"},"previous_names":["antonverburg/ha-pid_thermostat","domectrl/ha-pid_thermostat"],"tags_count":2,"template":false,"template_full_name":"ludeeus/integration_blueprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_thermostat","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_thermostat/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_thermostat/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/domectrl%2Fha-pid_thermostat/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/domectrl","download_url":"https://codeload.github.com/domectrl/ha-pid_thermostat/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244619447,"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-controller","thermostat"],"created_at":"2025-01-25T13:11:56.434Z","updated_at":"2025-03-20T13:34:08.341Z","avatar_url":"https://github.com/domectrl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PID Thermostat 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 regulated thermostat. \r\n\r\nIt uses a sensor and a number entity connected to a heater or air conditioning. A typical method to create a number to control a heater or cooler could be to use the [slow_pwm number integration][slow_pwm]. When in heater mode, if the measured temperature is cooler than the target temperature, the heater will be regulated until the required temperature is reached. When in air conditioning mode, if the measured temperature is hotter than the target temperature, the air conditioning will be regulated until the required temperature is reached. One PID Thermostat entity can only control one number output. If you need to activate two numbers (one for a heater and one for an air conditioner), you will need two PID Thermostat entities. The value for the output number entity will be calculated using the [Proportional–Integral–Derivative algorithm (PID)](https://en.wikipedia.org/wiki/PID_controller). The 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. Setting 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. In short, you should make the following steps:\r\n- For kp, start with 100; if your thermostat deviates by 1 °C, you might want the heater to turn on for 100%. If required, gradually make it bigger if you see that the direct reaction of the controller is too low.\r\n- For ki, keep this number to 0 until kp is set. Then, start with a small number (0.1). If you see that the reaction over time is only slowly rising, 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 thermostat code is shared with the [PID controller][pid_controller]. As an output for the thermostat, 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`climate` | This platform can be used to control a number entity output to regulate a temperature to a specific setpoint. The value of the climate entity is the setpoint. As a sensor, any temperature sensor entity can be used.\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_thermostat\r\n2. Select `PID Thermostat` 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_thermostat`.\r\n1. Download _all_ the files from the `custom_components/pid_thermostat/` 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 Thermostat\"\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\nclimate:\r\n  - platform: pid_thermostat\r\n    name: Kitchen thermostat\r\n    heater: number.floor_heater\r\n    sensor: sensor.kitchen_temperature\r\n```\r\n\r\n### Configuration parameters\r\n- name: Name of the PID thermostat.\r\n  \u003e required: true | type: string\r\n- heater: Heater- or cooler device entity. Must be a number device. Typically, the [slow_pwm number entity][slow_pwm] can be used to create a number controlling a binary switch. The output will be limited to the minimum and maximum value of this number.\r\n  \u003e required: true | type: string\r\n- sensor: Temperature sensor entity, used for input signal.\r\n  \u003e required: true | type: string\r\n- kp: Proportional gain factor, directly gaining the error to compensate the fault (Kp).\r\n  \u003e required: false | default: 100.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- ac_mode: Thermostat mode. Select if the thermostat should be a cooler or a heater.\r\n  \u003e required: false | default: 'heat' | type: string `('heat' or 'cool')`\r\n- min_temp: Minimal temperature setpoint in °C.\r\n  \u003e required: false | default: 7 | type: float\r\n- max_temp: Maximal temperature setpoint in °C.\r\n  \u003e required: false | default: 35 | type: float\r\n- cycle_time: Cycle time for the PID controller loop.\r\n  \u003e required: false | default: \"{'seconds': 30}\" | type: time_period\r\n- target_temp: Target temperature on startup.\r\n  \u003e required: false | default: 19 | type: float\r\n- initial_hvac_mode: Initial HVAC mode. \r\n  \u003e required: false | default: 'off' | type: string `('off', 'heat' or 'cool')`\r\n- away_temp: Preset 'Away' temperature. Preset will only be available in the thermostat when set here.\r\n  \u003e required: false | default: not set | type: float\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\nclimate:\r\n  - platform: pid_thermostat\r\n    name: Kitchen thermostat\r\n    heater: number.floor_heater\r\n    sensor: sensor.kitchen_temperature\r\n    kp: 100.0\r\n    ki: 0.5\r\n    kd: 0.01\r\n    ac_mode: heat\r\n    min_temp: 10\r\n    max_temp: 25\r\n    cycle_time: {'hours':0, 'minutes':0, 'seconds': 30}\r\n    target_temp: 21\r\n    initial_hvac_mode: heat\r\n    away_temp: 15\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_controller]: https://github.com/antonverburg/ha_pid_controller\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomectrl%2Fha-pid_thermostat","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdomectrl%2Fha-pid_thermostat","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdomectrl%2Fha-pid_thermostat/lists"}