A Home Assistant add-on to sync Energy dashboards with your Linky smart meter

N.B: Because this tool is targeted for French users, the documentation is...in French!

HA Linky est un add-on pour Home Assistant permettant de synchroniser les données votre compteur Linky avec les tableaux de bord d'énergie de Home Assistant.

Il utilise mon module npm linky et mon service Conso API pour communiquer avec Enedis et récupérer votre consommation.

Pour utiliser cet add-on, il vous faut :

• Un compteur Linky
• Un espace client Enedis
• La collecte de la consommation horaire activée sur votre espace client Enedis (tutoriel)
• Un token d'accès, à générer sur Conso API

• Cliquez ici pour ajouter le repository à Home Assistant. Si le lien ne fonctionne pas :
  • Depuis Home Assistant, ouvrez le menu Paramètres / Settings, puis Modules complémentaires / Add-ons
  • Cliquez sur le bouton Boutique / Store en bas à droite
  • Cliquer sur les trois points en haut à droite, puis Dépôts / Repositories
  • Ajoutez https://github.com/bokub/ha-linky
• Cliquez sur Ajouter / Add puis fermez la boite de dialogue
• Cherchez Linky dans la liste des add-ons et cliquez dessus (vous pouvez utiliser la barre de recherche)
• Installez l'add-on en cliquant sur le bouton dédié

Une fois l'add-on installé, rendez-vous dans l'onglet Configuration, cliquez sur les 3 points, puis Modifier en YAML / Edit in YAML

La configuration YAML de base comporte 2 compteurs dans la liste meters :

• Le premier pour mesurer la consommation d'énergie
• Le deuxième pour mesurer la production d'énergie

Vous pouvez effacer les lignes correspondant à la production si vous ne produisez pas d'électricité, ou rajouter d'autres compteurs si vous en avez besoin.

Pour chaque compteur, remplissez les champs suivants :

• prm : Votre numéro de PRM (14 chiffres).
  • Si vous ne le connaissez pas, entrez votre token sur la page exemples de Conso API et le PRM s'affichera dans le champ PRM
  • Vous pouvez également le trouver sur votre compteur en appuyant sur la touche + jusqu’à lire la valeur du numéro de PRM.
  • Selon les cas, le PRM de consommation peut être identique ou différent de celui qui gère la production.
  • Les 14 chiffres du PRM doivent être saisis entre guillemets ", comme dans l'exemple ci-dessous
• token : Votre token Conso API
• name : Choisissez le nom qui sera affiché dans les tableaux de bord d'énergie. Vous pourrez le changer plus tard si vous le souhaitez.
• action : Laissez la valeur par défaut: sync
• production : Choisissez true pour synchroniser la production électrique du compteur ou false pour synchroniser la consommation

Exemple de configuration pour un seul compteur, en consommation :

- prm: '18435095771264'
  token: abcdef.ghijklmnopqrs.tuvwxyz
  name: Consommation Linky
  action: sync
  production: false

Exemple de configuration pour synchroniser consommation et production du même PRM

- prm: '11111222223333'
  token: abcdef.ghijklmnopqrs.tuvwxyz
  name: Consommation Linky
  action: sync
  production: false

- prm: '11111222223333'
  token: abcdef.ghijklmnopqrs.tuvwxyz
  name: Production Linky
  action: sync
  production: true

Appliquez les modifications et démarrez / redémarrez l'add-on si ce n'est pas déjà fait

N.B: Home Assistant va automatiquement ajouter des retours à la ligne avec le caractère >-. Pas de panique, c'est normal.

token: >-
  abcdef.ghijklmnopqrs.tuvwxyz

Une fois l'add-on démarré, rendez-vous dans l'onglet Journal / Log pour suivre la progression de la synchronisation.

Au premier lancement, HA Linky essaiera de récupérer jusqu'à 1 an de données historiques (sauf si vous fournissez votre propre export CSV).

Ensuite, il synchronisera les données deux fois par jour tant qu'il n'est pas arrêté :

• Une fois entre 6h et 7h du matin pour récupérer les données de la veille
• Une fois entre 9h et 10h du matin au cas où la première synchronisation a échoué

Vous pourrez vérifier le bon fonctionnement de l'add-on en vous rendant dans l'onglet Journal / Log, où toutes les informations utiles seront affichées.

Pour visualiser les données de HA Linky dans vos tableaux de bord d'énergie :

• Cliquez ici, ou ouvrez le menu Paramètres / Settings, puis Tableaux de bord / Dashboards, puis Énergie / Energy
• Dans la section Réseau électrique / Electricity grid, cliquez sur Ajouter une consommation / Add consumption
• Choisissez la statistique correspondant au name que vous avez choisi à l'étape de configuration
• Si vous avez configuré une tarification, cliquez sur Utiliser une entité de suivi des coûts totaux, et choisissez la statistique équivalente dont le nom finit par (costs)
• Cliquez sur Enregistrer / Save

• Les données d’une journée ne sont pas accessibles en temps réel, il faut attendre le lendemain de leur mesure pour pouvoir les récupérer, entre 6h et 10h.
• Pour les dates récentes (moins de 7 jours), HA Linky essaiera de récupérer en priorité des données par demi-heure
• Pour les dates plus anciennes, HA Linky récupèrera seulement des données quotidiennes. Vous verrez alors une seule grande barre entre 0h et 1h du matin sur votre tableau de bord d'énergie si vous affichez le graphique détaillé d'une telle journée.

En cas de problème, il est toujours possible d'effacer toutes les données de consommation ou de production créées par HA Linky

Revenez sur l'onglet Configuration de l'add-on et changez la valeur de action à reset sur le compteur qui vous intéresse, puis appliquez les modifications et redémarrez l'add-on.

Ouvrez ensuite l'onglet Journal / Log pour vérifier que la remise à zéro s'est bien déroulée.

Au prochain démarrage, si action est repassé à sync, HA Linky réimportera à nouveau vos données historiques, soit via Conso API, soit via un fichier CSV si vous en avez fourni un (voir paragraphe suivant).

Lors de l'initialisation, HA Linky télécharge jusqu'à 1 an de données quotidiennes (une valeur par jour) via Conso API.

Dans le cas d'un calcul de coûts avec une configuration HP/HC, les données quotidiennes ne seront pas suffisantes pour un calcul précis.

Si vous souhaitez un historique plus long ainsi qu'une précision horaire, vous pouvez importer un fichier CSV à partir duquel HA Linky pourra extraire les données.

La marche à suivre est la suivante :

• Téléchargez un export de vos données horaires depuis votre espace client Enedis (tutoriel)
• Déposez ce fichier dans le dossier /addon_configs/cf6b56a3_linky (tutoriel)
• Si vous avez déjà importé des données dans Home Assistant, faites une remise à zéro en suivant le paragraphe précédent
• Repassez l'action du compteur à sync et redémarrez l'add-on
• Si un fichier CSV correspondant à votre PRM est trouvé, HA Linky l'utilisera pour initialiser les données au lieu d'appeler l'API.
• En cas de gros import, il faudra peut-être attendre une ou deux minutes pour voir les statistiques apparaître dans la configuration du tableau de bord d'énergie

En plus de récupérer les données de votre compteur, HA Linky peut calculer le coût de votre consommation ou les gains de votre production, en fonction de vos tarifs d'électricité.

La configuration des tarifs est optionnelle, et s'écrit dans l'encadré costs de l'onglet Configuration, sous forme de liste de tarifs.

Chaque item de la liste correspond à un tarif spécifique, qui peut être défini selon plusieurs critères (heure, jour de la semaine, date, PRM, production/consommation).

Pour chaque tarif, vous devez définir soit un prix fixe en €/kWh (price), soit une entité Home Assistant (entity_id) qui fournira un prix variable dans le temps.

Les paramètres possibles pour chaque tarif sont expliqués dans le tableau ci-dessous. Ils sont tous optionnels, sauf price et entity_id dont exactement un doit être renseigné :

N.B : Les filtres horaires (after, before, weekday) ne peuvent pas être utilisés avec entity_id, car les entités de tarification dynamique contiennent déjà les variations de prix dans le temps. Seuls les filtres de dates (start_date, end_date) sont compatibles avec entity_id.

Configuration la plus simple : 0,23 € / kWh quelle que soit la date ou l'heure

- price: 0.23

Configuration HP/HC : 0,21 € / kWh de 22h à 6h30 et de 12h30 à 14h, et 0,25 € / kWh le reste du temps.

⚠️ N.B : Il faut configurer séparément la période minuit - 6h30 et la période 22h - minuit, comme dans l'exemple ci-dessous

- price: 0.21
  before: '06:30'
- price: 0.25
  after: '06:30'
  before: '12:30'
- price: 0.21
  after: '12:30'
  before: '14:00'
- price: 0.25
  after: '14:00'
  before: '22:00'
- price: 0.21
  after: '22:00'

Configuration par jour de la semaine : 0,24 €/kWh la semaine, 0,22 €/kWh le week-end

- price: 0.24
  weekday:
    - mon
    - tue
    - wed
    - thu
    - fri
- price: 0.22
  weekday:
    - sat
    - sun

Tarif qui évolue au cours du temps : 0,21 €/kWh jusqu'au 30 juin inclus, 0,22 €/kWh en juillet et août, puis 0,23 €/kWh à partir du 1 septembre

- price: 0.21
  end_date: '2024-07-01'
- price: 0.22
  start_date: '2024-07-01'
  end_date: '2024-09-01'
- price: 0.23
  start_date: '2024-09-01'

Configuration avec une entité contenant un prix variable dans le temps :

- entity_id: sensor.electricity_price

Utilisation d'entités différentes selon la période de l'année :

- entity_id: sensor.electricity_price_winter
  start_date: '2024-11-01'
  end_date: '2024-04-01'
- entity_id: sensor.electricity_price_summer
  start_date: '2024-04-01'
  end_date: '2024-11-01'

Note sur les unités : HA Linky convertit automatiquement les unités de prix des entités :

• c€/kWh, cent/kWh → divisé par 100 pour conversion en €/kWh
• EUR/MWh, €/MWh → divisé par 1000 pour conversion en €/kWh
• €/kWh, EUR/kWh ou pas d'unité → utilisé tel quel

• Les coûts sont calculés au moment où la consommation est importée dans Home Assistant. Le coût des consommations déjà importées ne sera pas recalculé, sauf si vous faites une remise à zéro
• Si vous avez déjà importé toutes vos données de consommation au moment de la mise en place de la configuration des coûts, il faudra attendre le prochain import (le lendemain) ou faire une remise à zéro pour que l'entité dédiée aux coûts apparaisse dans votre tableau de bord Énergie
• L'ajout des coûts au tableau de bord Énergie s'effectue en choisissant Utiliser une entité de suivi des coûts totaux dans la fenêtre de configuration de la consommation
• Vous pouvez combiner plusieurs paramètres (horaires, jours de la semaine, dates, prm) pour personnaliser au maximum le calcul des coûts
• La tarification statique (price) et dynamique (entity_id) peuvent être combinées dans différents items de configuration
• Avec entity_id, HA Linky récupère l'historique des prix de l'entité et applique le prix le plus récent au moment de chaque mesure de consommation
• La configuration des horaires ne fonctionne que pour les heures pile et les demi-heures, autrement dit, les minutes différentes de :00 et :30 pourraient créer des valeurs inattendues
• Si plusieurs items de la liste sont valides au même moment (chevauchement d'horaires ou de dates par exemple), HA Linky choisira l'item le plus haut placé dans la liste
• Assurez-vous d'entourer les heures et les dates par des guillemets doubles " ou simples ' pour être certain que celles-ci soient bien interprétées par HA Linky
• Vous pouvez vérifier le coût calculé d'une heure en particulier en vous rendant dans Outils de développement, onglet Statistiques, puis en cliquant sur l'icône la plus à droite de la ligne qui vous intéresse (flèche montante)

Si votre installation de Home Assistant ne vous permet pas d'accéder au système d'add-ons, il est également possible de lancer HA Linky en utilisant Docker

Construisez une image Docker ha-linky adaptée à votre système avec la commande suivante :

docker build https://github.com/bokub/ha-linky.git -f standalone.Dockerfile -t ha-linky

Créez ensuite un fichier nommé options.json, au format suivant, puis suivez les instructions du paragraphe "Configuration" ci-dessus pour le remplir.

{
  "meters": [
    {
      "prm": "",
      "token": "",
      "name": "Linky consumption",
      "action": "sync",
      "production": false
    },
    {
      "prm": "",
      "token": "",
      "name": "Linky production",
      "action": "sync",
      "production": true
    }
  ],
  "costs": []
}

Créez un jeton d'accès longue durée depuis la page de votre profil Home Assistant (accessible en cliquant sur vos initiales en bas du menu latéral)

Vous pouvez désormais lancer l'image Docker de HA Linky avec la commande docker run ou via Docker compose, selon vos préférences.

Dans les deux cas, remplacez :

• <options-folder> par le dossier contenant le fichier options.json
• <jeton> par le jeton d'accès longue durée que vous avez créé juste avant dans Home Assistant
• <ha-ip> par l'IP de votre instance Home assistant (avec le port si nécessaire)
• <timezone> par votre timezone (ex. Europe/Paris), si votre système est configuré différement

# docker run
docker run -e SUPERVISOR_TOKEN='<jeton>' -e WS_URL='ws://<ha-ip>/api/websocket' -e TZ='<timezone>' -v <options-folder>:/data ha-linky

# docker-compose.yml
services:
  ha-linky:
    image: ha-linky
    environment:
      - SUPERVISOR_TOKEN=<jeton>
      - WS_URL=ws://<ha-ip>/api/websocket
      - TZ=<timezone>
    volumes:
      - <options-folder>:/data

Pour importer des fichiers CSV (optionnel), rajoutez simplement un deuxième volume <csv-folder>:/config où <csv-folder> correspond au dossier contenant vos fichiers CSV.