Creating a Home Assistant integration

I’ve been using Home Assistant for about 7 years now, and it’s kept improving ever since. This continuous improvement is in part due to the company backing it with full time people working to make it the best home automation software. It’s also thanks to the large number of contributors who spent time creating integrations with a variety of devices and services.

In HA, every interaction with the outside world goes through an integration. For example, there’s a “sun” integration that users can use to run automations based on the sun’s position. Or a Bluetooth integration, to communicate with Bluetooth devices.

Bus stop

I promise it’ll make sense, bear with me a second.

I have a bus stop near home and I wanted to have the next departures visible in my hallway.

I initially tinkered with an LCD touchscreen but the brightness made it stand out too much and it ended up off most of the time. I then explored e-ink displays. I already had some around the house to display plant info so I believed it could work. I used an available Raspberry Pi, hooked up the display, and wrote a bit of code to show the data. I’ll probably expand on that in a future post.

Anyway, I needed somewhere to pull data from. I wanted to display things like date and time, weather, bike sharing status (available bikes and spaces) and next bus departures. I figured I could have Home Assistant fetch the data and use the display to fetch data from HA only. This way the complexity of downloading and filtering data would lie in HA only and the display would only need to integrate with HA.

The departures and bike sharing data are available online on the Data Grand Lyon open data platform, but there was no HA integration.

I initially cobbled together scripts and automations to download and extract this data but it was fragile and not very shareable. I wanted to make it available to anyone with a HA install without much tinkering.

HA integration

So I wrote an HA integration for the Grand Lyon Open Data platform! I used Claude Code quite extensively because I didn’t want to spend too many nights and weekends on this - I just wanted to get it done. It helped a lot but had to be carefully controlled to prevent too large diffs.

Making a contribution to such a big project as HA can feel daunting but it’s really not. I’ve felt welcome and helped by maintainers.

The key thing is to start small. Make the smallest possible PR that provides values and respects the project’s guidelines. That’s not what I did at first, and maintainers rightfully but respectfully pointed that out in the initial PR review. After removing a bunch of stuff, I finally ended up with something that was reasonably reviewable but still provided useful data.

Then, after the initial PR was merged, feature by feature, I added things back in. On GitHub, you can find the list of all pull requests I sent for that integration, if you’re curious.

The keys were patience and tenacity. The initial integration PR took nearly a month and many back and forth conversations and code changes to get merged. But when it was, it was because it was good. After that, the following PRs were mostly reviewed and merged in a few days, depending on maintainers availability and PR size.

Here is the integration documentation page.

Quality scale

Home Assistant integrations are evaluated against a “quality scale”.

The integration quality scale is a framework for Home Assistant to grade integrations based on user experience, features, code quality, and developer experience. To grade this, the project has come up with a set of tiers, each with its own set of criteria.

There are 4 scaled tiers, bronze, silver, gold, and platinum. To reach a tier, the integration must fulfill all rules of that tier and the tiers below.

This felt like a checklist to complete, and it is. Each rule has its own description page to help integration developers understand what they should do to satisfy the rule. They all exist to improve the user and developer experience.

Naturally, I wanted them all. I wanted to reach platinum! And bonus points if my new integration could launch at platinum. I got to work, and eventually was able to send the PR updating the quality scale grading.

I’m proud to say that my efforts paid and the Data Grand Lyon integration launched at platinum quality in Home Assistant 2026.6!

Many thanks to @joostlek who reviewed most of my PRs on the core repo 🙏 

Documentation and branding

When adding a new integration, it’s mandatory to add a logo so it can be recognized at a glanced, and more importantly documentation!

Users should know what to expect from an integration, how to configure it, what its shortcomings are, automation examples, etc. This is key for a good experience!

Documentation should also be updated for new features and user-facing changes of course.

Home Assistant enforces that with automated checks and human reviews. Your code won’t be merged if it needs a documentation update and you haven’t opened the companion PR!

On the documentation repo, I mostly had interactions with @c0ffeeca7. Thank you 🙏 

All in all

Contributing to Home Assistant was and still is a fun experience. I’d do it again if I had to! In fact, I did do it again 🙊

Now, I can check when the next bus departure is scheduled without taking my phone out of my pocket and finding the right app! The info is right where I need, when I need it. And everyone interested can add this to their installations in a few clicks.

I already made some improvements to the setup process, and I have other ideas for data that we could retrieve such as park and rides availability and traffic alerts.

I’m not done yet! 😁