Skip to content
BranchesTags

Repository files navigation

GitHub Release GitHub Activity License Project Maintenance

Donate via PayPal Sponsor on GitHub

Toon Climate Custom Integration

A Home Assistant custom integration for controlling rooted Toon thermostats. Monitor and control HVAC mode, temperature setpoint, and preset modes.

Supported Features

HVAC Modes:

  • Heat: Manual mode - heat to target temperature (schedule off)
  • Auto: Automatic mode - follow Toon's schedule (schedule on)

Presets:

  • Away: Away mode setpoint
  • Home: Home mode setpoint
  • Comfort: Comfort mode setpoint
  • Sleep: Sleep mode setpoint
  • Eco: Vacation mode (requires manual activation on device first; uses 6°C minimum by default)

Extra State Attributes:

The climate entity exposes additional attributes for advanced automations:

Attribute Description
burner_info Burner state: 0 = off, 1 = heating for setpoint, 2 = heating for hot water, 3 = preheating
modulation_level Current boiler modulation percentage (0-100)
current_internal_boiler_setpoint Internal boiler water temperature setpoint
ot_comm_error OpenTherm communication error flag (0 = no error)
program_state Schedule state: 0 = manual, 1 = schedule active, 2 = schedule override
next_setpoint Next scheduled temperature setpoint (°C)
next_state Next scheduled preset name (e.g. comfort, home, sleep, away, eco)
next_switch_time ISO 8601 timestamp of the next program switch
program_info Human-readable next program change, e.g. "at 17:00 to Comfort" (None when unavailable)

Screenshots

Configure Thermostat History

Requirements

  • Rooted Toon thermostat
  • Available in The Netherlands and Belgium

For rooting instructions, visit the Eneco Toon Domotica Forum.

Installation

HACS (Recommended)

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

Alternatively:

  1. Install HACS if not already installed
  2. Search for "Toon Climate" in HACS
  3. Click Download
  4. Restart Home Assistant
  5. Add via Settings → Devices & Services

Manual Installation

  1. Copy custom_components/toon_climate to your <config>/custom_components/ directory
  2. Restart Home Assistant
  3. Add via Settings → Devices & Services

Configuration

Adding the Integration

  1. Navigate to Settings → Devices & Services
  2. Click + Add Integration
  3. Search for "Toon Climate"
  4. Enter your configuration:
    • Host: Your Toon's IP address
    • Port: Default is 80
    • Name: Friendly name prefix (default: "Toon")
    • Minimum Temperature: The minimum temperature which can be set
    • Maximum Temperature: The maximum temperature which can be set
    • Update Interval: Seconds between updates (default: 10)

Migrating from YAML

Note: YAML configuration is deprecated as of v2.0.0

If you previously configured this integration in configuration.yaml, your settings will be automatically imported on your first restart after updating.

Your old YAML config (will be migrated):

climate:
  - platform: toon_climate
    name: Toon
    scan_interval: 90
    host: !secret toon_host

After migration:

  1. Remove the YAML configuration from configuration.yaml
  2. Manage all settings via Settings → Devices & Services → Toon Climate → Configure
  3. Disable unwanted sensors through entity settings

Modifying Settings

Change integration settings without restarting Home Assistant:

  1. Go to Settings → Devices & Services
  2. Find Toon Climate
  3. Click Configure icon
  4. Modify available settings:
    • Host: IP address of your Toon (validated on change)
    • Port: Port number (validated on change)
    • Minimum Temperature: Lower bound for temperature setpoint
    • Maximum Temperature: Upper bound for temperature setpoint
    • Update Interval: Seconds between polling updates
  5. Click Submit

Changes apply immediately — no restart required. If the host or port is changed, the connection to the new address is validated before saving.

Advanced Usage

Automation Examples

Replace climate.toon_thermostat with your entity ID.

Switch HVAC modes:

script:
  - toon_enable_manual_mode:
      alias: Toon enable Manual mode
      sequence:
        - service: climate.set_hvac_mode
          data:
            hvac_mode: "heat"
          entity_id: climate.toon_thermostat
      mode: single
  - toon_enable_schedule_mode:
      alias: Toon enable Schedule mode
      sequence:
        - service: climate.set_hvac_mode
          data:
            hvac_mode: "auto"
          entity_id: climate.toon_thermostat
      mode: single

Change presets:

script:
  - toon_activate_preset_comfort:
      alias: Toon activate preset Comfort
      sequence:
        - service: climate.set_preset_mode
          data:
            preset_mode: "comfort"
          entity_id: climate.toon_thermostat
      mode: single
  - toon_activate_preset_away:
      alias: Toon activate preset Away
      sequence:
        - service: climate.set_preset_mode
          data:
            preset_mode: "away"
          entity_id: climate.toon_thermostat
      mode: single
  - toon_activate_preset_home:
      alias: Toon activate preset Home
      sequence:
        - service: climate.set_preset_mode
          data:
            preset_mode: "home"
          entity_id: climate.toon_thermostat
      mode: single
  - toon_activate_preset_sleep:
      alias: Toon activate preset Sleep
      sequence:
        - service: climate.set_preset_mode
          data:
            preset_mode: "sleep"
          entity_id: climate.toon_thermostat
      mode: single

Activate vacation mode:

script:
  - toon_activate_preset_eco:
      alias: Toon activate preset Eco (Vacation)
      sequence:
        - service: climate.set_preset_mode
          data:
            preset_mode: eco
          entity_id: climate.toon_thermostat
      mode: single

When activated, the Eco preset enables vacation mode and maintains the last set vacation temperature as the minimum. Exit by selecting any other preset.

Template Sensors

Current operation mode:

template:
  - sensor:
      - name: "Toon Operation Mode"
        unique_id: toon_operation_mode
        state: >-
          {% if is_state('climate.toon_thermostat','off') %}
            Vakantie
          {% elif is_state('climate.toon_thermostat','heat') %}
            Handmatig
          {% elif is_state('climate.toon_thermostat','auto') %}
            Automatisch
          {% endif %}

Next scheduled program:

template:
  - sensor:
      - name: "Toon Volgend Programma"
        unique_id: toon_next_program
        state: "{{ state_attr('climate.toon_thermostat', 'program_info') | default('Onbekend') }}"

Current room temperature:

template:
  - sensor:
      - name: "Temperatuur Woonkamer"
        unique_id: toon_current_temperature
        state: "{{ state_attr('climate.toon', 'current_temperature') }}"
        unit_of_measurement: °C
        device_class: temperature
        state_class: measurement

Toon2 environment sensors:

sensor:
  - platform: rest
    name: Toon2 AirSensors
    json_attributes:
      - humidity
      - tvoc
      - eco2
    value_template: '{{ value_json["temperature"] }}'
    device_class: temperature
    unit_of_measurement: "°C"
    resource: http://192.168.2.106/tsc/sensors

template:
  - sensor:
      - name: "Toon2 Humidity"
        unique_id: toon2_humidity
        state: '{{ state_attr("sensor.toon2_airsensors", "humidity") }}'
        device_class: humidity
        state_class: measurement
        unit_of_measurement: "%"
      - name: "Toon2 TVOC"
        unique_id: toon2_tvoc
        state: '{{ state_attr("sensor.toon2_airsensors", "tvoc") }}'
        device_class: volatile_organic_compounds
        state_class: measurement
        unit_of_measurement: "ppb"
      - name: "Toon2 eCO2"
        unique_id: toon2_eco2
        state: '{{ state_attr("sensor.toon2_airsensors", "eco2") }}'
        device_class: carbon_dioxide
        state_class: measurement
        unit_of_measurement: "ppm"

You can create a sensor with more heating information like so:

template:
  - sensor:
      - name: "Toon Driewegklep"
        unique_id: toon_burner_valve
        state: >-
          {% if is_state_attr('climate.toon', 'burner_info', 0) %}
            Neutraal
          {% elif is_state_attr('climate.toon', 'burner_info', 1) %}
            CV
          {% elif is_state_attr('climate.toon', 'burner_info', 2) %}
            Warm Water
          {% endif %}

Detect burner state changes:

automation:
  - alias: "Detect Burnerstate change"
    trigger:
      platform: state
      entity_id: climate.toon_thermostat
    condition:
      condition: template
      value_template: >
        {{ trigger.from_state and
            trigger.to_state.attributes.burner_info == 0 and
            trigger.from_state.attributes.burner_info == 1}}
    action:
      service: persistent_notification.create
      data:
        message: Burner state changed!
        title: "Thermostat Info"

Troubleshooting

Common Issues

My Thermostat isn't working after update

  • It probably created another (duplicate) thermostat device, look it up under Developers Tools
  • Delete old one & rename new, or deinstall/reinstall integration to fix

Integration won't connect:

  • Verify your Toon's IP address is correct
  • Check that port 80 is accessible (try visiting http://YOUR_TOON_IP/happ_thermstat?action=getThermostatInfo in a browser)

Old YAML config not migrating:

  • Check Home Assistant logs for import errors
  • Verify the YAML syntax is correct
  • Manually add via UI if automatic import fails

Enable Debug Logging

Add the relevant lines below to the configuration.yaml:

logger:
  default: info
  logs:
    custom_components.toon_climate: debug

Alternatively, enable debug logging via the UI in Settings → Devices & Services → Toon Climate → Enable debug logging:

Enable Debug Logging

Then perform any steps to reproduce the issue and disable debug logging again. It will download the relevant log file automatically.

Development

Quick-start (from project root):

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements_lint.txt
./scripts/lint    # runs pre-commit + vulture
# or: ruff check .
# to auto-fix: ruff check . --fix

💖 Support This Project

If you find this library useful for your projects, please consider supporting its continued development and maintenance:

🌟 Ways to Support

  • ⭐ Star this repository - Help others discover the project
  • 💰 Financial Support - Contribute to development and hosting costs
  • 🐛 Report Issues - Help improve stability and compatibility
  • 📖 Spread the Word - Share with other developers

💳 Financial Support Options

Donate via PayPal Sponsor on GitHub

Why Support?

  • Keeps the project actively maintained
  • Enables faster bug fixes and new features
  • Supports infrastructure costs (testing, AI, CI/CD)
  • Shows appreciation for hundreds of hours of development

Every contribution, no matter the size, makes a difference and is greatly appreciated! 🙏

License

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

About

This custom integration provides a climate device for rooted Toon thermostats.

Topics

custom-integrationhacs-integrationhome-assistantthermostattoon

Resources

Readme
MIT license

Security policy

Security policy
Activity

Stars

54 stars

Watchers

2 watching

Forks

13 forks
Report repository

Releases

Sponsor this project

Packages

Used by

Contributors

Languages