ESPHome PID Autotune Status

An ESPHome custom component that exposes the PID Climate autotune status, error messages, and phase progress as sensors in Home Assistant. All sensors automatically appear under the Diagnostic category with appropriate icons. It now also includes a dedicated Switch component to seamlessly start, configure, and safely abort the tuning process directly from your dashboard.

You don't need to download any files manually. Just add the repository directly to your ESPHome configuration using the external_components block.

external_components:
  - source: github://denpavibes/esphome-pid-autotune-status

climate:
  - platform: pid
    id: my_pid_climate
    # ... rest of your climate config

switch:
  - platform: pid_autotune
    name: "PID Autotune Switch"
    climate_id: my_pid_climate
    # Optional parameters (defaults shown)
    noiseband: 0.25
    positive_output: 1.0
    negative_output: -1.0
    update_interval: 5s

text_sensor:
  - platform: pid_autotune
    climate_id: my_pid_climate
    status:
      id: autotune_status
      name: "PID Autotune Status"
    error_message:
      id: autotune_error
      name: "PID Autotune Error"
    update_interval: 5s

sensor:
  - platform: pid_autotune
    climate_id: my_pid_climate
    # Optional parameters (defaults shown)
    rules: ZIEGLER_NICHOLS_PID
    phase:
      id: autotune_phase
      name: "PID Autotune Phase"
    kp:
      id: autotune_kp
      name: "PID Autotune Kp"
    ki:
      id: autotune_ki
      name: "PID Autotune Ki"
    kd:
      id: autotune_kd
      name: "PID Autotune Kd"
    update_interval: 5s

The switch allows you to control the autotune process interactively:

• Turning On: Creates a new autotuner configured with your provided parameters (noiseband, positive_output, negative_output) and starts the tuning process.
• Turning Off: Immediately aborts an active autotune by destroying the autotuner object in memory.
• Auto-Sync: The switch automatically toggles itself to the Off position when the autotune finishes or fails, keeping your Home Assistant dashboard perfectly synchronized with the hardware state.

• climate_id (Optional, ID): The ID of the PID climate controller to tune.
• noiseband (Optional, float): The amplitude of noise on the sensor. The autotuner will only trigger a relay state change when the measurement exceeds this value. Defaults to 0.25.
• positive_output (Optional, float): The output value to apply for the heating phase during tuning. Defaults to 1.0.
• negative_output (Optional, float): The output value to apply for the cooling phase during tuning. Defaults to -1.0.
• update_interval (Optional, Time): The interval to check the background process state to keep the switch UI in sync. Defaults to 5s.

Both status and error_message text sensors are optional, but at least one must be configured.

The status sensor will report one of the following states to Home Assistant:

• Off: Autotune is not running.
• Running: Autotune is currently in progress.
• Finished: Autotune completed successfully (data was convergent and symmetrical).
• Failed: Autotune finished, but failed to reach amplitude convergence or symmetry.

Provides diagnostic error information if autotuning fails:

• None: No error detected (autotune is Off, Running, or completed successfully).
• Amplitude not convergent: Autotune finished, but could not reliably determine oscillation amplitude.
• Frequency not symmetrical: Autotune finished, but oscillation frequency was not symmetrical.

All sensors under this platform (phase, kp, ki, kd) are optional, but at least one must be configured.

• Phase (phase): Tracks the phase_count during the autotuning process.
  • Returns 0 when the autotuner is Off, Finished, or Failed.
  • Increments sequentially during the Running state as the relay function oscillates.
• Kp, Ki, Kd (kp, ki, kd):
  • While the autotuner is Off or Running, these sensors report as Unavailable in Home Assistant.
  • When autotune completes, these values update to the calculated parameters using the selected rules.

• climate_id (Optional, ID): The ID of the PID climate controller to tune.

• rules (Optional, string): The Ziegler-Nichols tuning rule used to calculate kp, ki, and kd after autotune finishes. Has no effect if none of kp, ki, or kd are configured. Defaults to ZIEGLER_NICHOLS_PID.

  Value	Kp factor	Ki factor	Kd factor
  ZIEGLER_NICHOLS_PID (default)	0.6	1.2	0.075
  ZIEGLER_NICHOLS_PI	0.45	0.54	0.0
  PESSEN_INTEGRAL_PID	0.7	1.75	0.105
  SOME_OVERSHOOT_PID	0.333	0.667	0.111
  NO_OVERSHOOT_PID	0.2	0.4	0.0625

• update_interval (Optional, Time): The interval to poll the autotuner state. Defaults to 5s.

This project is licensed under the MIT License - see the LICENSE file for details.