Home Assistant 2026.11 : mon guide de migration ClimateEntity

En découvrant les changements annoncés pour Home Assistant 2026.11, j’ai d’abord pensé à un cas très banal : un thermostat connecté qui mesure 20,5 °C et reçoit une consigne de 21 °C. Rien de spectaculaire côté utilisateur. Pourtant, pour une intégration personnalisée, quelques noms de propriétés Python changent et une erreur de conversion Celsius/Fahrenheit peut vite passer inaperçue.

J’ai donc repris un exemple d’intégration ClimateEntity, ligne par ligne, pour voir ce qu’il faut réellement modifier. Ce qui suit est une mise en pratique commentée sur un exemple de code, pas le compte rendu d’un essai sur un appareil physique. Le but est que vous puissiez confronter facilement ces changements à votre propre intégration.

Êtes-vous concerné ?

• Thermostat classique, intégration officielle : normalement aucune automatisation à modifier.
• Intégration HACS : consulter les mises à jour du mainteneur et les journaux, sans modifier directement du code en production.
• Intégration personnelle en Python : migrer les propriétés ClimateEntity, vérifier la compatibilité des versions et les conversions.

Le cas concret : une consigne à 21 °C, mais quelle unité dans le code ?

Prenons un radiateur connecté qui communique en degrés Celsius. Sa passerelle remonte 20,5 °C dans le salon et une consigne à 21 °C. Dans Home Assistant, ces valeurs sont présentées selon le système d’unités configuré par l’utilisateur. Si l’installation utilise le Fahrenheit, Home Assistant effectue la conversion.

Ce qui m’intéresse dans 2026.11, c’est cette séparation enfin explicite : l’unité native de l’appareil, déclarée par l’intégration, n’est pas obligatoirement l’unité publiée dans les états Home Assistant. La classe de base ClimateEntity effectue la conversion et ajoute désormais l’attribut d’état temperature_unit.

Voici à quoi peut ressembler une partie de l’état d’un thermostat dans une instance paramétrée en Celsius. Les valeurs ci-dessous sont un exemple pédagogique, pas une capture d’une installation réelle.

{
  "entity_id": "climate.radiateur_salon",
  "state": "heat",
  "attributes": {
    "current_temperature": 20.5,
    "temperature": 21.0,
    "temperature_unit": "°C"
  }
}

Pour vérifier votre équipement, allez dans Outils de développement → États, recherchez l’entité climate.* concernée et examinez ses attributs. Attention : l’ajout de temperature_unit concerne Home Assistant Core 2026.11, et non les anciennes versions.

Un exemple parlant : 20,5 °C correspondent à 68,9 °F ; une consigne de 21 °C correspond à 69,8 °F. Même lorsque l’interface affiche du Fahrenheit, une passerelle qui travaille en Celsius doit déclarer son unité native en Celsius. Home Assistant se charge de la conversion pour l’état et dans l’autre sens pour la consigne.

Avant / après : la migration Python que j’ai retenue

Le point le plus facile à manquer est le préfixe native_. Avant, une intégration pouvait fournir sa température via current_temperature et annoncer son unité avec _attr_temperature_unit. Dans 2026.11, ce sont les versions natives de ces propriétés qu’il faut définir.

Avant : les anciennes propriétés

from homeassistant.const import UnitOfTemperature

class RadiateurSalon(ClimateEntity):
    _attr_temperature_unit = UnitOfTemperature.CELSIUS

    @property
    def current_temperature(self):
        return self.thermostat.temperature_c

    @property
    def target_temperature(self):
        return self.thermostat.setpoint_c

Le code ne s’arrête pas brutalement de fonctionner dans 2026.11, mais ces anciens noms sont dépréciés et peuvent déclencher des avertissements dans les journaux.

Après : un exemple plus complet avec ClimateEntity

Voici la version que je prendrais comme base pour adapter un thermostat local simple. Les méthodes et attributs de thermostat représentent votre propre passerelle matérielle : ils doivent être remplacés par ceux de votre bibliothèque ou API. Le reste illustre les points d’extension attendus par Home Assistant.

from typing import Any

from homeassistant.components.climate import (
    ClimateEntity,
    ClimateEntityFeature,
    HVACMode,
)
from homeassistant.const import ATTR_TEMPERATURE, UnitOfTemperature


class RadiateurSalon(ClimateEntity):
    """Exemple d'un radiateur piloté par une passerelle locale."""

    _attr_hvac_modes = [HVACMode.OFF, HVACMode.HEAT]
    _attr_supported_features = ClimateEntityFeature.TARGET_TEMPERATURE
    _attr_native_temperature_unit = UnitOfTemperature.CELSIUS
    _attr_target_temperature_step = 0.5

    def __init__(self, thermostat) -> None:
        self.thermostat = thermostat
        self._attr_unique_id = thermostat.serial_number

    @property
    def hvac_mode(self) -> HVACMode:
        return HVACMode.HEAT if self.thermostat.is_heating else HVACMode.OFF

    @property
    def native_current_temperature(self) -> float | None:
        return self.thermostat.temperature_c

    @property
    def native_target_temperature(self) -> float | None:
        return self.thermostat.setpoint_c

    async def async_set_temperature(self, **kwargs: Any) -> None:
        # Home Assistant fournit ici la consigne en unité native.
        await self.thermostat.async_set_setpoint_c(
            kwargs[ATTR_TEMPERATURE]
        )

    async def async_set_hvac_mode(self, hvac_mode: HVACMode) -> None:
        await self.thermostat.async_set_heating(
            hvac_mode == HVACMode.HEAT
        )

La différence est nette : la passerelle transmet une température dans son unité d’origine via native_current_temperature ; la consigne est exposée via native_target_temperature ; et _attr_native_temperature_unit indique à Home Assistant comment interpréter ces nombres. Ne convertissez pas deux fois les valeurs : la classe de base s’en charge.

Ce fragment est une classe d’entité, pas une intégration HACS complète prête à installer : les fichiers manifest.json, __init__.py, climate.py, la configuration et l’adaptateur de l’appareil restent nécessaires.

Comment tester le code sans toucher à un vrai thermostat

Pour ne pas rester au stade de la théorie, j’ai contrôlé la syntaxe de l’exemple Python ainsi que ses opérations essentielles dans un environnement isolé, avec un faux appareil. Les vérifications ont réussi pour la lecture des températures, l’envoi d’une consigne et le mode arrêt. Voici un test que vous pouvez adapter au dépôt de votre intégration.

from types import SimpleNamespace
from unittest import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock
from homeassistant.components.climate import HVACMode
from custom_components.mon_integration.climate import RadiateurSalon

class TestRadiateurSalon(IsolatedAsyncioTestCase):
    async def test_lecture_et_commande(self):
        device = SimpleNamespace(
            serial_number="demo-01",
            temperature_c=20.5,
            setpoint_c=21.0,
            is_heating=True,
            async_set_setpoint_c=AsyncMock(),
            async_set_heating=AsyncMock(),
        )
        entity = RadiateurSalon(device)
        self.assertEqual(entity.native_current_temperature, 20.5)
        self.assertEqual(entity.native_target_temperature, 21.0)

        await entity.async_set_temperature(temperature=22.5)
        device.async_set_setpoint_c.assert_awaited_once_with(22.5)

        await entity.async_set_hvac_mode(HVACMode.OFF)
        device.async_set_heating.assert_awaited_once_with(False)

Remplacez mon_integration par le domaine réel, placez le test dans tests/test_climate.py et exécutez python -m unittest tests.test_climate -v dans un environnement où les dépendances Home Assistant sont installées. Les commandes vers la passerelle sont simulées avec AsyncMock ; aucun appareil réel n’est commandé.

Limite importante : le test isolé que j’ai exécuté utilise une simulation des classes Home Assistant. Le test complet d’intégration (machine à états, conversion °C/°F et installation HACS) reste à réaliser sur un environnement Home Assistant Core 2026.11.

Les cinq propriétés à rechercher dans votre intégration

J’ai regroupé les changements dans ce tableau pour éviter de les chercher un par un dans les notes techniques :

Les raccourcis de classe sont également concernés : _attr_target_temperature devient _attr_native_target_temperature, par exemple. En revanche, min_temp, max_temp et target_temperature_step conservent leur nom et sont exprimés dans l’unité native.

Il y a ici une subtilité importante : temperature_unit reste un attribut de l’état publié, mais ce n’est plus une propriété que votre intégration doit remplacer. C’est native_temperature_unit qui décrit l’unité du matériel.

Un vrai avertissement rencontré par la communauté

Le sujet est déjà concret pour certains mainteneurs. Un signalement public concernant Toon Climate mentionne des avertissements liés à _attr_temperature_unit, _attr_current_temperature et _attr_target_temperature sur une bêta 2026.11. Je préfère citer ce cas documenté plutôt que de fabriquer une capture de journaux.

À retenir : un avertissement de dépréciation n’est pas automatiquement une panne. Il faut contrôler le fonctionnement du chauffage et signaler les anciens attributs au mainteneur. Les nouvelles propriétés ne doivent pas non plus être déployées sans vérifier la compatibilité avec les versions Home Assistant antérieures.

Comment je contrôlerais la migration sans dérégler le chauffage

Avant de mettre à jour une intégration utilisée au quotidien, je commencerais par sauvegarder ma configuration et identifier les méthodes concernées. Inutile de modifier à l’aveugle toutes les propriétés du chauffage.

1. Faire une sauvegarde de Home Assistant et conserver une copie de l’ancienne version du composant personnalisé.
2. Rechercher les anciens noms dans le dossier de l’intégration : current_temperature, target_temperature, temperature_unit et les variantes _attr_.
3. Vérifier l’unité physique reçue de l’appareil. Un modèle qui remonte réellement du Fahrenheit doit déclarer UnitOfTemperature.FAHRENHEIT, même si votre installation Home Assistant est en Celsius.
4. Redémarrer et lire les journaux pour repérer d’éventuels avertissements de dépréciation.
5. Tester la lecture et la consigne sur une valeur raisonnable, d’abord dans l’unité habituelle, puis dans une autre unité si votre intégration doit gérer les deux.

Pour envoyer une consigne de test à une entité de démonstration ou à un thermostat que vous maîtrisez, l’action Home Assistant conserve cette forme :

action: climate.set_temperature
target:
  entity_id: climate.radiateur_salon
data:
  temperature: 21

La température saisie dans une instance configurée en Celsius est convertie par Home Assistant dans l’unité native attendue par l’entité avant d’être transmise à async_set_temperature. Sur le matériel réel, les noms des entités et les consignes doivent naturellement être adaptés.

Et si l’intégration restaure la température après un redémarrage ?

Autre détail que je ne négligerais pas : la restauration des consignes. Il ne faut pas récupérer aveuglément l’ancienne consigne dans les attributs d’état sauvegardés, puisqu’ils reflètent déjà la conversion et peuvent avoir été arrondis. La documentation recommande d’hériter de RestoreClimate et d’utiliser async_get_last_climate_data() pour retrouver les valeurs natives.

Ce cas mérite une vérification particulière sur les thermostats personnalisés, les passerelles maison et certains composants HACS. Le changement n’altère pas directement les protocoles Zigbee, Z-Wave, Matter ou Modbus : il concerne la manière dont l’intégration expose ses données à Home Assistant.

Pour un composant qui restaure sa consigne après redémarrage, la documentation recommande RestoreClimate et async_get_last_climate_data(). Voici un exemple réduit de la logique à intégrer à votre propre classe :

from homeassistant.components.climate import RestoreClimate

class MonThermostat(RestoreClimate):
    async def async_added_to_hass(self) -> None:
        await super().async_added_to_hass()
        data = await self.async_get_last_climate_data(
            validate_range=True
        )
        if data and data.native_target_temperature is not None:
            self._attr_native_target_temperature = (
                data.native_target_temperature
            )

Avec validate_range=True, la consigne restaurée est contrôlée par rapport aux limites de l’entité. Une valeur invalide doit conduire à une valeur de repli appropriée au matériel plutôt qu’à une consigne dangereuse.

Compatibilité : attention aux installations Home Assistant 2026.10

Les nouvelles propriétés native_current_temperature, native_target_temperature et native_temperature_unit sont prévues pour Core 2026.11. Si vous maintenez une intégration HACS, ne remplacez pas aveuglément les anciens noms dans une version destinée à Home Assistant 2026.10. Pour un code exclusivement destiné à Core 2026.11 ou ultérieur, indiquez une version minimale adaptée dans hacs.json :

{
  "name": "Mon thermostat local",
  "homeassistant": "2026.11.0"
}

HACS documente ce champ comme une version minimale requise. Les anciennes propriétés restent temporairement prises en charge dans 2026.11, avec des avertissements, avant leur suppression annoncée pour 2027.11. Consultez la documentation HACS et l’annonce officielle de Home Assistant.

FAQ : ce que je vérifierais avant la mise à jour

Dois-je refaire mes automatisations de chauffage ?

En principe non : les appels à climate.set_temperature continuent d’utiliser la température configurée dans Home Assistant. La migration concerne surtout le code interne des intégrations.

Pourquoi garder temperature_unit ?

Cet attribut indique l’unité des valeurs publiées dans l’état, tandis que native_temperature_unit décrit l’unité réellement fournie par le périphérique. Ne confondez pas les deux.

Puis-je corriger une intégration HACS moi-même ?

Oui si vous en maîtrisez le développement, mais mieux vaut privilégier une mise à jour maintenue, sauvegarder le composant et contrôler la version minimale de Core. Un simple remplacement de texte ne suffit pas toujours.

Puis-je tester sur mon chauffage principal ?

Je recommande d’abord une instance ou un appareil de test. Sur une installation réellement utilisée, commencez par une sauvegarde et vérifiez les journaux avant tout changement de consigne.

Mon bilan : une petite migration, mais un vrai piège évité

Ce que je retiens de cette évolution, c’est qu’elle ne révolutionne pas l’écran de contrôle du chauffage. Un thermostat reste un thermostat. En revanche, pour quelqu’un qui maintient son propre composant, la distinction entre valeur native et valeur affichée devient plus propre, avec moins d’ambiguïtés lors d’un appel API ou d’un changement d’unité.

Les anciennes propriétés sont encore acceptées temporairement, mais leur retrait est annoncé pour Home Assistant Core 2027.11. Autant mettre à jour tranquillement les intégrations concernées plutôt que de découvrir les avertissements au dernier moment. Et si vous commencez dans cet écosystème, vous pouvez aussi consulter notre guide pour débuter avec Home Assistant.

Sources complémentaires : compatibilité minimale dans HACS et signalement communautaire Toon Climate.

Sources techniques : annonce officielle de la migration climate (8 octobre 2026) et documentation officielle de ClimateEntity.