HASmartThermostat

The thermostat uses a PID (Proportional-Integral-Derivative) controller to manage temperature via Pulse Width Modulation (PWM). The PID output determines how long the heater stays ON during a PWM period.

Tuning the Gains:

• Kp (Proportional): Adjusts reaction to the current error. Higher values increase the rise time (faster response).
• Ki (Integral): Compensates for residual error over time. If the temperature settles below the set point, increase Ki. If it settles above, decrease Ki.
• Kd (Derivative): Compensates for system inertia. It limits overshoot by decreasing PWM if the temperature rises too quickly.

Outdoor Temperature Compensation

If an outdoor temperature sensor is provided and ke (external gain) is set, the system adds an external component E to the output: E = Ke * (target_temp - outdoor_temp) For well-insulated buildings, a Ke of 0.6 is recommended.

The hasmartthermostat component is configured via Home Assistant parameters. Below are the key configuration options:

Required Parameters

• heater: entity_id for heater control. Can be a single entity or a list of toggle devices (switch, input_boolean), lights, or valves (light, number, input_number). If using a valve or light, set pwm to 0.
• target_sensor: entity_id for a temperature sensor. The sensor's state must be a temperature.
• keep_alive: Update interval for the PWM pulse width. Can be a float in seconds or a time string (hh:mm:ss).

PID Control Parameters

• kp: Proportional (p) control value (float, default 100).
• ki: Integral (i) control value (float, default 0).
• kd: Derivative (d) control value (float, default 0).
• ke: Outdoor temperature compensation gain (e) control value (float, default 0).
• Note: Changing PID values in the configuration does not update a running thermostat. Use the smart_thermostat.set_pid_gain service to update them dynamically.

PWM and Cycle Settings

• pwm: Period of the pulse width modulation. Can be float in seconds or hh:mm:ss (default 15mn). Set to 0 when using entities with direct 0/100% input (like valves).
• min_cycle_duration: Minimum time a switch must stay in its current state (protects boilers). Supports float seconds or hh:mm:ss (default 0s).
• min_off_cycle_duration: Minimum time the heater must remain OFF before turning ON. Defaults to min_cycle_duration.

Safety and Sensor Settings

• sensor_stall: Maximum time between sensor updates before entering safety mode. If exceeded, output is forced to output_safety. (default 6 hours).
• output_safety: The PID output level used in safety mode (float 0.0 to 100.0, default 5.0).
• target_temp_step: Adjustment step for target temperature (0.1, 0.5, or 1.0).
• precision: Displayed temperature precision (0.1, 0.5, or 1.0).

You can define default temperatures for various presets. If a preset temperature is not specified, that feature will be unavailable.

Preset Temperature Parameters

• away_temp: Default temperature for the "Away" preset.
• eco_temp: Default temperature for the "Eco" preset.
• boost_temp: Default temperature for the "Boost" preset.
• comfort_temp: Default temperature for the "Comfort" preset.
• home_temp: Default temperature for the "Home" preset.
• sleep_temp: Default temperature for the "Sleep" preset.
• activity_temp: Default temperature for the "Activity" preset.

Mode Settings

• ac_mode: If true, the heater entity is treated as a heating/cooling device.
• preset_sync_mode: If set to 'sync', manually setting a temperature will automatically enable the corresponding preset (e.g., setting temp to 14°C triggers the 'Away' preset if configured).
• boost_pid_off: If true, the thermostat uses hysteresis mode instead of PID while the boost preset is active, allowing for rapid temperature increases.

To add the thermostat, define a climate section in your configuration.yaml. You can control a single ON/OFF heater or multiple valves.

Key Parameters:

• heater: A single switch entity or a list of valve entities.
• target_sensor: The sensor measuring ambient temperature.
• kp, ki, kd: PID gain values.
• pwm: The Pulse Width Modulation period (e.g., 00:15:00 for 15 minutes or 0 for a simple ON/OFF).
• ac_mode: Set to True for air conditioning, False for heating.
• away_temp: Temperature for the 'away' preset.
• keep_alive: Configuration for how often to keep the connection alive.

climate:
  - platform: smart_thermostat
    name: Smart Thermostat Single ON/OFF Heater Example
    unique_id: smart_thermostat_single_on_off_heat_example
    heater: switch.on_off_heater
    target_sensor: sensor.ambient_temperature
    min_temp: 7
    max_temp: 28
    ac_mode: False
    target_temp: 19
    keep_alive:
      seconds: 60
    away_temp: 14
    kp: 50
    ki: 0.01
    kd: 2000
    pwm: 00:15:00

To tune your PID gains, you can enable debug: true in your configuration. This exposes internal values as attributes on the climate entity. You can then use Home Assistant template sensors to monitor these values in real-time.

Available debug attributes:

• pid_p
• pid_i
• pid_d
• pid_e
• pid_dt

Example configuration.yaml setup:

sensor:
  - platform: template
    sensors:
      smart_thermostat_output:
        friendly_name: PID Output
        unit_of_measurement: "%"
        value_template: "{{ state_attr('climate.smart_thermostat_example', 'control_output') | float(0) }}"
      smart_thermostat_p:
        friendly_name: PID P
        unit_of_measurement: "%"
        value_template: "{{ state_attr('climate.smart_thermostat_example', 'pid_p') | float(0) }}"
      smart_thermostat_i:
        friendly_name: PID I
        unit_of_measurement: "%"
        value_template: "{{ state_attr('climate.smart_thermostat_example', 'pid_i') | float(0) }}"
      smart_thermostat_d:
        friendly_name: PID D
        unit_of_measurement: "%"
        value_template: "{{ state_attr('climate.smart_thermostat_example', 'pid_d') | float(0) }}"
      smart_thermostat_e:
        friendly_name: PID E
        unit_of_measurement: "%"
        value_template: "{{ state_attr('climate.smart_thermostat_example', 'pid_e') | float(0) }}"

Warning: Disable debug mode once tuning is complete to prevent filling your Home Assistant database.

The following services allow you to manage the thermostat dynamically in Home Assistant:

• smart_thermostat.set_pid_gain: Adjust kp, ki, and kd (floats) without restarting. Values are saved to the database.
• smart_thermostat.set_pid_mode: Set mode to 'auto' (PID modulation) or 'off' (simple hysteresis).
• smart_thermostat.set_preset_temp: Update temperatures for preset modes (e.g., away_temp, boost_temp).
• smart_thermostat.clear_integral: Resets the integral part of the PID to 0, useful for rapid testing during tuning.

# Example: Set PID gains
service: smart_thermostat.set_pid_gain
data:
  kp: 11.8
  ki: 0.00878
target:
  entity_id: climate.smart_thermostat_example

# Example: Set PID mode
service: smart_thermostat.set_pid_mode
data:
  mode: 'off'
target:
  entity_id: climate.smart_thermostat_example

# Example: Set preset temperatures
service: smart_thermostat.set_preset_temp
data:
  away_temp: 14.6
  boost_temp: 22.5
  home_temp_disable: true
target:
  entity_id: climate.smart_thermostat_example