KeyAtome

🇬🇧 English · 🇫🇷 Français

A Home Assistant integration for Key Atome, a Linky-compatible electricity meter made by TotalEnergies (formerly Total/Direct-Energie). It retrieves your electricity consumption and exposes it as Home Assistant sensors.

Several Key Atome devices within the same account can be managed.

Contents

• Installation
• Configuration
• Sensors
• Energy dashboard
• Notes & known behaviour
• Breaking changes
• Acknowledgments

Installation

HACS (recommended)

KeyAtome is part of the default HACS store:

1. Open HACS in Home Assistant.
2. Select Integrations.
3. Click the add icon and search for keyatome.
4. Select keyatome and install it.
5. Restart Home Assistant.

Manual

Manual procedure

1. Download the keyatome folder from the latest release (right click → Save link as).
2. Copy it into the config/custom_components folder on your Home Assistant machine. If custom_components doesn't exist next to your configuration.yaml, create it first.
3. Restart Home Assistant.

Configuration

Add the integration from the Home Assistant UI: Settings → Devices & Services → Add Integration → KeyAtome.

You'll be asked for the following fields:

Field	Required	Description
username	yes	Your TotalEnergies account login.
password	yes	Your TotalEnergies account password.
user_id	yes	Internal user ID. Retrieve it with the find_user_id.py script.
account_id	yes	The Référence client shown in your TotalEnergies profile.
atome_linky_number	no	Which Key Atome in the account (1, 2, 3, …). Defaults to 1.
name	no	Root name used for the sensors. Defaults to Atome.

Finding your user_id

The user_id is an internal numeric ID that isn't shown anywhere in your TotalEnergies account, so you have to discover it with the find_user_id.py script. Edit the variables at the top of the script (your email, password and Référence client) following the instructions in its header, then run it.

Tip

The script works by scanning candidate IDs one by one, so it can take a long time to find yours (potentially hours). You can narrow the search range in the script to split it across several runs. It stops automatically as soon as it finds your user_id.

Important

Since v8.0.0 the TotalEnergies API is v3, which requires both user_id and account_id at login. YAML configuration (platform: keyatome in configuration.yaml) is deprecated — use the UI instead.

Warning

If the official Home Assistant atome integration is also configured in configuration.yaml, disable it. Running both hits the Atome server too often.

Sensors

Assuming the default name Atome and atome_linky_number = 1, the following sensors are created:

Sensor	Description
sensor.atome_live_power	Instant power (attributes: connection status, max subscription power).
sensor.atome_daily	Current daily consumption (attributes: current price, previous consumption, previous price).
sensor.atome_weekly	Current weekly consumption (same attributes).
sensor.atome_monthly	Current monthly consumption (same attributes).
sensor.atome_login_stat	Current user ID and user reference (since v5.0.0).
sensor.atome_diagnostic	Synthetic server health: NoServerIssue, HandleNonIncreasingValueError, or TooManyServerError (attributes: cumulative_error_warning, cumulative_non_increasing_value) (since v6.0.0).

Note

Check sensor.atome_login_stat to confirm you addressed the right Key Atome within your account.

When atome_linky_number is greater than 1, sensors are named sensor.NAME_linky<number>_... instead of sensor.NAME_....

Energy dashboard

Use sensor.atome_daily to track electricity consumption in the Energy dashboard.

To also expose the price, add this template sensor to your configuration.yaml:

template:
  - sensor:
      - name: atome_daily_price
        state: >-
          {% if state_attr('sensor.atome_daily', 'price') == 'unknown' %}
            unknown
          {% else %}
            {{ state_attr('sensor.atome_daily', 'price') }}
          {% endif %}
        #unit_of_measurement: 'EUR'
        state_class: total_increasing
        #device_class: monetary

Notes & known behaviour

• If you switch contracts from the TotalEnergies mobile app, you must reload this integration in Home Assistant.
• Since 1 April 2026, the TotalEnergies API is in v3 (handled as of v8.0.0).

Breaking changes

Show history

• v0.0.1 / v1.0.0 — sensors are named sensor.key_atome_xxx.
• v2.0.0 — sensors are named sensor.atome_xxx (like the HA atome component).
• v2.1.0 — sensors are named sensor.NAME_xxx, where NAME is set during configuration. Defaults to Atome for consistency with HA.
• v4.1.0 — multiple Key Atome devices are supported. For atome_linky_number > 1, sensors are named sensor.NAME_linky<number>_xxx. Nothing changes for number 1.
• v6.1.0 — cumulative_error moves from atome_login_stat to atome_diagnostic.
• v7.0.0 — implements TotalEnergies API v2. As a stopgap, week/month/year are set to zero.
• v7.1.0 — adds local computation for the week. Month/year still zero.
• v7.2.0 — adds local computation for the month. Year still zero.
• v7.3.0 — the year sensor is removed.
• v8.0.0 — uses API v3. user_id and account_id must be provided at login.

Acknowledgments

• Thanks to @baqs for the original Atome implementation in Home Assistant. v0.0.1 of this project is based on the Atome component from Home Assistant 2021.12.4; KeyAtome is a fork that adds new features.
• Thanks to @BenoitAnastay for decoding API v2.

---

Français

Cliquer pour afficher la version française

Une intégration Home Assistant pour Key Atome, un compteur électrique compatible Linky fabriqué par TotalEnergies (anciennement Total/Direct-Energie). Elle récupère votre consommation électrique et l'expose sous forme de capteurs Home Assistant.

Plusieurs Key Atome d'un même compte peuvent être gérés.

Installation

HACS (recommandé)

KeyAtome fait partie du dépôt par défaut HACS :

1. Ouvrez HACS dans Home Assistant.
2. Sélectionnez Intégrations.
3. Cliquez sur l'icône d'ajout et recherchez keyatome.
4. Sélectionnez keyatome et installez-le.
5. Redémarrez Home Assistant.

Manuelle

Procédure manuelle

1. Téléchargez le dossier keyatome depuis la dernière release (clic droit → Enregistrer le lien sous).
2. Copiez-le dans le dossier config/custom_components de votre machine Home Assistant. Si custom_components n'existe pas à côté de votre configuration.yaml, créez-le d'abord.
3. Redémarrez Home Assistant.

Configuration

Ajoutez l'intégration depuis l'interface de Home Assistant : Paramètres → Appareils et services → Ajouter une intégration → KeyAtome.

Les champs suivants vous seront demandés :

Champ	Requis	Description
username	oui	L'identifiant de votre compte TotalEnergies.
password	oui	Le mot de passe de votre compte TotalEnergies.
user_id	oui	Identifiant interne. À récupérer avec le script find_user_id_fr.py.
account_id	oui	La Référence client affichée dans votre profil TotalEnergies.
atome_linky_number	non	Quel Key Atome dans le compte (1, 2, 3, …). Par défaut 1.
name	non	Nom racine utilisé pour les capteurs. Par défaut Atome.

Trouver votre user_id

Le user_id est un identifiant numérique interne qui n'apparaît nulle part dans votre compte TotalEnergies : il faut donc le découvrir avec le script find_user_id_fr.py. Renseignez les variables en haut du script (votre email, mot de passe et Référence client) en suivant les instructions de son en-tête, puis lancez-le.

[!TIP] Le script teste les identifiants candidats un par un : il peut donc prendre beaucoup de temps pour trouver le vôtre (potentiellement plusieurs heures). Vous pouvez réduire la plage de recherche dans le script pour la répartir sur plusieurs exécutions. Il s'arrête automatiquement dès qu'il trouve votre user_id.

[!IMPORTANT] Depuis la v8.0.0, l'API TotalEnergies est en v3, qui exige à la fois user_id et account_id à la connexion. La configuration en YAML (platform: keyatome dans configuration.yaml) est dépréciée — utilisez l'interface à la place.

[!WARNING] Si l'intégration officielle atome de Home Assistant est aussi configurée dans configuration.yaml, désactivez-la. Faire tourner les deux sollicite trop souvent le serveur Atome.

Capteurs

Avec le nom par défaut Atome et atome_linky_number = 1, les capteurs suivants sont créés :

Capteur	Description
sensor.atome_live_power	Puissance instantanée (attributs : état de connexion, puissance souscrite max).
sensor.atome_daily	Consommation journalière en cours (attributs : prix courant, consommation précédente, prix précédent).
sensor.atome_weekly	Consommation hebdomadaire en cours (mêmes attributs).
sensor.atome_monthly	Consommation mensuelle en cours (mêmes attributs).
sensor.atome_login_stat	Identifiant et référence client courants (depuis la v5.0.0).
sensor.atome_diagnostic	État synthétique du serveur : NoServerIssue, HandleNonIncreasingValueError ou TooManyServerError (attributs : cumulative_error_warning, cumulative_non_increasing_value) (depuis la v6.0.0).

[!NOTE] Vérifiez sensor.atome_login_stat pour confirmer que vous avez bien ciblé le bon Key Atome de votre compte.

Lorsque atome_linky_number est supérieur à 1, les capteurs sont nommés sensor.NOM_linky<numéro>_... au lieu de sensor.NOM_....

Tableau de bord énergie

Utilisez sensor.atome_daily pour suivre la consommation électrique dans le tableau de bord Énergie.

Pour exposer aussi le prix, ajoutez ce capteur template à votre configuration.yaml :

template:
  - sensor:
      - name: atome_daily_price
        state: >-
          {% if state_attr('sensor.atome_daily', 'price') == 'unknown' %}
            unknown
          {% else %}
            {{ state_attr('sensor.atome_daily', 'price') }}
          {% endif %}
        #unit_of_measurement: 'EUR'
        state_class: total_increasing
        #device_class: monetary

Notes et comportements connus

• Si vous changez de contrat depuis l'application mobile TotalEnergies, vous devez recharger cette intégration dans Home Assistant.
• Depuis le 1er avril 2026, l'API TotalEnergies est en v3 (prise en charge à partir de la v8.0.0).

Changements cassants

Afficher l'historique

• v0.0.1 / v1.0.0 — les capteurs sont nommés sensor.key_atome_xxx.
• v2.0.0 — les capteurs sont nommés sensor.atome_xxx (comme le composant atome de HA).
• v2.1.0 — les capteurs sont nommés sensor.NOM_xxx, où NOM est défini à la configuration. Par défaut Atome pour rester cohérent avec HA.
• v4.1.0 — la gestion de plusieurs Key Atome est ajoutée. Pour atome_linky_number > 1, les capteurs sont nommés sensor.NOM_linky<numéro>_xxx. Rien ne change pour le numéro 1.
• v6.1.0 — cumulative_error passe de atome_login_stat à atome_diagnostic.
• v7.0.0 — implémente l'API TotalEnergies v2. Provisoirement, semaine/mois/année sont mis à zéro.
• v7.1.0 — ajoute le calcul local de la semaine. Mois/année toujours à zéro.
• v7.2.0 — ajoute le calcul local du mois. Année toujours à zéro.
• v7.3.0 — le capteur année est supprimé.
• v8.0.0 — utilise l'API v3. user_id et account_id doivent être fournis à la connexion.

Remerciements

• Merci à @baqs pour l'implémentation Atome originale dans Home Assistant. La v0.0.1 de ce projet est basée sur le composant Atome de Home Assistant 2021.12.4 ; KeyAtome en est un fork qui ajoute de nouvelles fonctionnalités.
• Merci à @BenoitAnastay pour le décodage de l'API v2.