ha-linky and the Home Assistant app for Linky smart meter data

What the add-on does, and where it sits in Home Assistant

HA Linky is a Home Assistant app for synchronising your Linky smart meter data with the Energy dashboards. The README notes that the app was formerly called an add-on or a module, which is the older name for the same thing in Home Assistant's extension model.

The scope is narrow and specific. The add-on reads consumption and production figures from an Enedis Linky meter and pushes them into Home Assistant as statistics, where you then pick them in the Energy dashboard configuration. It is not a general Enedis integration and not a device tracker: it exists to move a specific set of numbers from a French utility's meter into one place.

The README is also upfront about the audience, with a note that because the tool is targeted at French users, the documentation is in French. That is a real factor in adoption, since the configuration steps, the wizard labels and the wiki tutorial are all in French, even though the add-on itself is written in TypeScript and the underlying npm module is published separately.

The mechanism is described plainly: the add-on uses the author's npm module called linky and the author's Conso API service to talk to Enedis and retrieve consumption. So there are three parties in the chain: the meter and the utility, the author's API service, and the add-on. The add-on does not authenticate to Enedis directly, it asks Conso API to do it.

The repository is MIT licensed, the primary language is TypeScript, and the last push was on 2026-10-07, the same day as the 1.9.0 release. The previous releases were 1.8.0 on 2026-08-07 and 1.7.0 on 2026-01-07, so the project ships on a steady monthly-ish cadence with occasional gaps.

The audience is a French Home Assistant user with a Linky meter who wants the utility's numbers in their own dashboard rather than in the utility's portal.

The prerequisites, and why each one is a hard requirement

The Prerequisites section lists four things, and each of them exists because something in the chain fails without it.

The first is a Linky meter, which is the obvious one. The second is an Enedis customer account, since that is where the data comes from. The third is that hourly consumption collection is enabled in that customer account, with a wiki tutorial linked for turning it on. The fourth is an access token, generated on Conso API.

The third is the one that surprises people. Enedis does not expose hourly data by default; the meter has to be configured to collect it, and until that is done the add-on has nothing to fetch. The wiki link in the README is there because this is a manual step in the utility's portal that has to happen before the software can do anything.

The fourth prerequisite is the token, and this is where the design decision bites. The add-on does not take your Enedis password. It takes a token from Conso API, which is a separate service the same author runs. That is a meaningful choice for a piece of software that handles household energy consumption data, and it has two consequences. The first is that the credential you paste into the add-on configuration is not an Enedis credential, so the blast radius of a leak is smaller, but the second is that you are now trusting a third-party service in the middle of the path between your meter and your dashboard.

The PRM number, the 14-digit identifier of your meter, is the other half of the configuration and the README is precise about it. It has to be entered in quotes, because the 14 digits are a number that would otherwise lose its leading zeros or be parsed as something else. There are two documented ways to find it: enter your token on the examples page of Conso API and the PRM appears in the PRM field, or press the plus key on the meter itself and read the PRM number off the display. And the note about the consumption PRM possibly being identical to or different from the production one is a real-world detail that bites people with solar installations.

Installing the repository and configuring the meters

Installation follows the standard Home Assistant add-on repository flow, and the README gives both a shortcut link and the manual path.

The shortcut is a redirect link that adds the repository to Home Assistant directly. If it does not work, the manual route is: open the Settings menu in Home Assistant, go to Apps, click the Store button in the bottom right, click the three dots in the top right, go to Repositories, and add the repository URL:

https://github.com/bokub/ha-linky

Then you click Add, close the dialog, search for Linky in the apps list, and install it with the dedicated button.

Configuration is done in the add-on's Configuration tab, through the three-dot menu and the Edit in YAML option. The base configuration has two meters in the meters list, one for consumption and one for production, and you can remove the production lines if you do not generate electricity, or add more if you need them.

Each meter takes five fields. The prm is your 14-digit PRM number, entered in quotes. The token is your Conso API token. The name is what appears in the Energy dashboards and you can change it later. The action is left at its default value of sync. The production flag is set to true to synchronise electricity production from the meter and false to synchronise consumption.

A single-meter configuration for consumption looks like this:

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

And the two-meter case for a household that both consumes and produces from the same 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

One quirk is worth expecting rather than being confused by. Home Assistant will automatically reformat the token onto a folded line with the >- character, and the README says not to panic, because that is normal.

The sync schedule and how much history you get

The operation section explains the behaviour, and the timing is the part that matters for planning your dashboard.

On first launch, HA Linky will try to retrieve up to 1 year of historical data, unless you supply your own CSV export instead. That backfill is what makes the Energy dashboard useful immediately instead of filling in over months.

After that, it syncs twice a day for as long as it is running. The first run is between 6am and 7:30am to fetch the previous day's data. The second is between 9am and 10:30am, in case the first synchronisation failed. That retry window is a sensible design choice given what the add-on is doing, since the previous day's hourly data is what the utility publishes overnight and a single failure would otherwise mean a full day of missing bars.

The Good to know section is where the data-granularity limits are stated, and there are three of them.

The first is latency: the data for a given day is not available in real time, and you have to wait until the day after it was measured, between 6am and 10am, before you can retrieve it.

The second is resolution for recent data: for dates under 7 days old, HA Linky will try to fetch half-hourly data in preference.

The third is resolution for older data: for older dates it retrieves only daily data. The visible consequence is spelled out, and it is a good example of a documentation note that saves support questions. You will see a single large bar between midnight and 1am on your Energy dashboard for such a day if you display the detailed chart.

That is not a bug, it is the resolution the utility exposes for historical data, and the app is being explicit that the shape of the chart will differ between the recent and historical portions of your history.

Wiring the statistics into the Energy dashboard

Getting the data into Home Assistant is one thing, and getting it into the Energy dashboard is a second configuration step that the README documents separately.

You open the Energy section of the Dashboards settings, either through the linked redirect or through Settings, Dashboards, Energy. In the Electricity grid section you click Add consumption, then choose the statistic that matches the name you set in the add-on configuration. If you have configured a tariff, you click the option to use a total cost tracking entity and pick the equivalent statistic whose name ends in (costs). Then you save.

The name-matching step is the one that catches people out, and it is why the add-on configuration has a name field at all. The statistics arrive in Home Assistant under the name you chose, and the dashboard has to be told which one to point at. If you rename it later in the add-on configuration, you will have to update the dashboard too.

The reset path is documented in the same section as troubleshooting support, and it is a good thing to know about before you need it. In case of a problem you can always erase all the consumption or production data created by HA Linky. You go back to the add-on Configuration tab, change the value of action to reset on the meter you are interested in, and apply the changes.

So the action field is doing double duty. It is the mode selector for the add-on, with sync as the default and reset as the recovery option, and it is a per-meter field rather than a global one, which means you can reset consumption without touching production.

The packaging, and the middleware question behind the token

The repository layout shows the add-on side of Home Assistant rather than an ordinary npm package, and that changes how you install and update it.

There is a Dockerfile and a standalone.Dockerfile, a config.yaml and a repository.yaml, both of which are the Home Assistant add-on manifest files that describe the app to the Supervisor, a run.sh entry point, and a .devcontainer/ directory for development. The build is TypeScript compiled with tsc, the tests run under vitest, and the lint script combines prettier in check mode with eslint. Husky handles the git hooks, with lint-staged configured to run prettier and eslint on staged files.

The Dockerfile is where the add-on packaging is clearest. It takes a build argument for the base image, adds nodejs and npm with apk, copies package.json and package-lock.json, runs npm ci with scripts ignored, copies the application code, makes run.sh executable, transpiles the TypeScript, and finally runs that script as the container command. The npm ci with --ignore-scripts is the detail that matters: it means the install step cannot execute anything from the dependency tree, which is the right posture for a container build.

The dependencies themselves describe the runtime shape: the linky module for talking to the service, node-cron for the twice-daily schedule, websocket for the Home Assistant websocket API, csv-parse for reading CSV exports, and chalk and dayjs for output. The devDependencies include home-assistant-js-websocket, which is how the add-on pushes statistics into Home Assistant.

The architectural point worth drawing out is the split between the add-on and the Conso API service. The add-on is what you install in Home Assistant, and it is MIT licensed and open. The service that actually talks to Enedis, using your account, is a hosted API run by the same author, and the add-on holds a token for it. That is a deliberate design choice for a project that wants to avoid asking users for their Enedis password inside a Home Assistant add-on, and it is also the main thing to weigh before installing. The token you put in the YAML is a credential for that service, and the README does not describe any offline or self-hosted path that bypasses it.

Editorial conclusion

ha-linky is a good fit for a French household with a Linky smart meter who wants consumption and production figures in the Home Assistant Energy dashboard, because the add-on handles the Enedis authentication, the backfill and the twice-daily polling instead of requiring a custom integration. It is a poor fit if you are outside France, since it depends on the Enedis customer account and the Linky meter specifically, and a poor fit if you need same-day figures, because the data for a given day only becomes available the next morning between 6 and 10. Before installing, confirm that hourly collection is enabled in your Enedis account, since the add-on cannot work without it, and generate a Conso API token, which is the credential the whole chain depends on.

Frequently asked questions

Official sources

1. bokub/ha-linky on GitHub
2. Issues
3. License: MIT
4. README
5. Releases