Skip to content

Latest commit

 

History

History
249 lines (176 loc) · 12 KB

README.md

File metadata and controls

249 lines (176 loc) · 12 KB
Raw

Smart Thermostat with auto Heat/Cool mode, PID control and PWM (Home Assistant component)

Thermostat was designed to control different kind of entities (not only switchable like in generic_thermostat).

Supported domains and modes for heaters and coolers:

  • switch, input_boolean - Basic on/off like generic_thermostat or PWM mode.
  • climate - PID regulator.
  • number, input_number - PID regulator (additional switch is required).

Current features:

  • Support multiply heaters/coolers.
  • Supports heat_cool mode.
  • Supports away mode.
  • Supports invert logic of the heater/cooler.
  • Protection if target sensor does not report values for period of time (sensor_stale_duration).

Installation (via HACS)

This is recommended way, which will handle one-click upgrade in HACS.

  1. Install hacs if it is not installed.
  2. Open HACS -> Integrations. Click 3 dots in the upper right corner.
  3. Click Custom repositories.
  4. Add https://github.com/jethome-ru/hassio-component-smart-thermostat repository.
  5. Find Smart Thermostat with auto Heat/Cool modes and PID control support and click install button.

Installation (Manual)

NOTE: This is not recommended way, because you will need to upgrade component manually.

  1. Copy /custom_components/smart_thermostat to your <config_dir>/custom_components/ directory.

    • On HassIO the final location will be /config/custom_components/smart_thermostat.
    • On Supervised the final location will be /usr/share/hassio/homeassistant/custom_components/smart_thermostat.
    • NOTE: You will need to create the custom_components folder if it does not exist.

  2. Restart Home Assistant Core.

Minimal working config example

climate:
  - platform: smart_thermostat    
    name: kitchen_thermostat
    target_sensor: sensor.kitchen_temperature
    min_temp: 15
    max_temp: 28
    precision: 0.1    
    heater:
      - entity_id: climate.kitchen_thermostat_heating_floor
        pid_params: 1.3, 0.5, 0.2
      - entity_id: input_number.kitchen_custom_ajustable_heater_regulator
        switch_entity_id: input_boolean.kitchen_custom_ajustable_heater_regulator_switch
        pid_params: 1.3, 0.5, 0.2
    cooler: switch.kitchen_on_off_cooler

Glossary

  • target_temp - Climate target temperature, can be changed in UI. Initial can be set via target_temp config option.
  • cur_temp - Current sensor temperature. Will be reported by target_sensor entity.
  • CONFIG.xxx - Reference to the config option.
  • CONFIG.CONTROLLER.xxx - Reference to the config controller option (heater/cooler).

Common config options

  • name (Required) - Climate entity name
  • unique_id (Optional) - Climate entity unique_id
  • cooler (Optional) - String, Array or Map of the coolers.
  • heater (Optional) - String, Array or Map of the heaters.
  • target_sensor (Required) - Target temperature sensor
  • sensor_stale_duration (Optional) - Thermostat will stop all controllers if no data received from sensor during this period.
  • min_temp (Optional, default=7) - Set minimum set point available.
  • max_temp (Optional, default=35) - Set maximum set point available.
  • away_temp (Optional) - Temperature used by the away mode. If this is not specified, the preset mode feature will not be available.
  • target_temp (Optional) - Initial target temperature.
  • heat_cool_disabled (Optional, default=false) - Disable heat_cool mode.
  • heat_cool_cold_tolerance (Optional, default=0.3) - Cold tolerance for turning on heater controllers. Used only in heat_cool mode.
  • heat_cool_hot_tolerance (Optional, default=0.3) - Hot tolerance for turning on cooler controllers. Used only in heat_cool mode.
  • initial_hvac_mode (Optional) - Initial HVAC mode.
  • precision (Optional) - Precision for this device. Supported values are 0.1, 0.5 and 1.0. Default: 0.1 for Celsius and 1.0 for Fahrenheit.

NOTE: at least one of heater or cooler is required.

Common behavior

Initial HVAC mode can be set via initial_hvac_mode config option.

Thermostat behavior will depend on active HVAC mode. HVAC mode can be set in UI.

NOTE: Smart thermostat will always take full control of the heaters/coolers. So it will turn them on/off back if you change their states manually

HVAC_MODE = heat

NOTE: available if at least one CONFIG.heater was defined.

  • All heater controllers will be turned on. Specific behavior of each heater will depend on the controller type.
  • All cooler controllers will be turned off.

HVAC_MODE = cool

NOTE: available if at least one CONFIG.coller was defined.

  • All cooler controllers will be turned on. Specific behavior of each cooler will depend on the controller type.
  • All heater controllers will be turned off.

HVAC_MODE = heat_cool

NOTE: available if at least one CONFIG.heater and at least one CONFIG.cooler were defined.

  • If cur_temp >= target_temp + CONFIG.heat_cool_hot_tolerance

    • All cooler controllers will be turned on.
    • All heater controllers will be turned off.
    • Specific behavior of each heater/cooler will depend on the controller type.

  • If cur_temp <= target_temp - CONFIG.heat_cool_cold_tolerance

    • All heater controllers will be turned on.
    • All cooler controllers will be turned off.
    • Specific behavior of each heater/cooler will depend on the controller type.

NOTE: turning on controller DOES NOT MEANS turning on CONFIG.CONTROLLER.enitity_id inside controller. Controller behavior depends on the specific controller logic and described below for each controller.

Controllers

Specific controller will be created for each heater/cooler config option based on CONFIG.CONTROLLER.enitity_id domain.

Switch controller (ON/OFF)

Domains: switch,input_boolean

Config options

  • entity_id (Required) - Target entity ID.
  • inverted (Optional, default=false) - Need to invert entity_id logic.
  • keep_alive (Optional) - Send keep-alive interval. Use with heaters, coolers, A/C units that shut off if they don’t receive a signal from their remote for a while.
  • min_cycle_duration (Optional, default=null) - Minimal cycle duration. Used to protect from on/off cycling.
  • cold_tolerance (Optional, default=0.3) - Cold tolerance.
  • hot_tolerance (Optional, default=0.3) - Hot tolerance.

Behavior

  • Turn on entity_id if cur_temp <= target_temp - cold_tolerance (heater) or cur_temp >= target_temp + self._hot_tolerance (cooler)
  • No entity_id changes will be performed if config min_cycle_duration was set and enough time was not passed since last switch.
  • Behavior on/off will be inverted if inverted config option was set to true

PWM Switch PID controller

Domains: switch,input_boolean.

See General PID explanation how to tune PID parameters.

  • Internal PID limits are integers, defined as constants PWM_SWITCH_MIN_VALUE and PWM_SWITCH_MAX_VALUE (0, 100). So, you must use this limits when tuning pid_params terms.

Config options

  • entity_id (Required) - Target entity ID.
  • inverted (Optional, default=false) - Need to invert entity_id logic.
  • keep_alive (Optional) - Send keep-alive interval. Use with heaters, coolers, A/C units that shut off if they don’t receive a signal from their remote for a while.
  • pid_params (Required) - PID params comma-separated string or array in the format Kp, Ki, Kd (Always positive, will be inverted internally for cool mode).
  • pid_sample_period (Optional) - PID constant sample time period.
  • pwm_period (Required) - PWM period. Switch will be turned on and turned off according internal PID output once in this period.

Behavior

  • PID output will be calculated internally based on provided pid_params.
  • pwm_period will be separated to two parts: ON and OFF. Each part duration will depend on PID output.
  • PWM on/off need will be checked every pwm_period/100 time but not often than each 1 second. (PWM_SWITCH_MAX_VALUE internal const variable)
  • Behavior on/off will be inverted if inverted config option was set to true.
  • It is keep on/off state duration before Home Assistant restart. Last change time is saved in thermostat state attributes.

NOTE: This mode will be set if entity domain is one of the listed above and pid_params config entry is present.

Climate controller (PID mode supported)

Domains: climate

See General PID explanation how to tune PID parameters.

Config options

  • entity_id (Required) - Target entity ID.
  • inverted (Optional, default=false) - Need to invert entity_id logic.
  • keep_alive (Optional) - Send keep-alive interval. Use with heaters, coolers, A/C units that shut off if they don’t receive a signal from their remote for a while.
  • pid_params (Required) - PID params comma-separated string or array in the format Kp, Ki, Kd (Always positive, will be inverted internally for cool mode).
  • pid_sample_period (Optional) - PID constant sample time period.
  • min (Optional) - Minimum temperature which can be set. Attribute min_temp from entity_id will be used if not specified.
  • max (Optional) - Maximum temperature which can be set. Attribute max_temp from entity_id will be used if not specified.

Behavior

  • Climate entity_id will be turned on when controller is active.
  • Climate entity_id will be turned off when controller is not active.
  • Climate entity_id temperature will be adjusted every pid_sample_period it is provided, or on every CONFIF.target_sensor update if pid_sample_period is not provided.
  • pid_params will be inverted if inverted was set to true

Number + Switch controller (PID mode supported)

Domains: number,input_number

See General PID explanation how to tune PID parameters.

Config options

  • entity_id (Required) - Target entity ID.
  • inverted (Optional, default=false) - Need to invert entity_id logic.
  • keep_alive (Optional) - Send keep-alive interval. Use with heaters, coolers, A/C units that shut off if they don’t receive a signal from their remote for a while.
  • pid_params (Required) - PID params comma-separated string or array in the format Kp, Ki, Kd (Always positive, will be inverted internally for cool mode).
  • pid_sample_period (Optional) - PID constant sample time period.
  • min (Optional) - Minimum temperature which can be set. Attribute min from entity_id will be used if not specified.
  • max (Optional) - Maximum temperature which can be set. Attribute max from entity_id will be used if not specified.
  • switch_entity_id (Required) - Switch entity which belongs to switch,input_boolean domains.
  • switch_inverted (Optional, default=false) - Is switch_entity_id inverted?

Behavior

  • Switch switch_entity_id will be turned on when controller is active.
  • Switch switch_entity_id will be turned off when controller is not active.
  • Number entity_id temperature will be adjusted every pid_sample_period it is provided, or on every CONFIF.target_sensor update if pid_sample_period is not provided.
  • pid_params will be inverted if inverted was set to true
  • switch_entity_id behavior will be inverted if switch_inverted was set to true

Reporting an Issue

  1. Setup your logger to print debug messages for this component using:
logger:
  default: info
  logs:
    custom_components.smart_thermostat: debug
  1. Restart HA
  2. Verify you're still having the issue
  3. File an issue in this GitHub Repository containing your HA log (Developer section > Info > Load Full Home Assistant Log)
    • You can paste your log file at pastebin https://pastebin.com/ and submit a link.
    • Please include details about your setup (Pi, NUC, etc, docker?, HassOS?)
    • The log file can also be found at /<config_dir>/home-assistant.log