About Home Assistant
Home Assistant is a community-led, free and open source smart home automation platform that prioritizes local control and privacy. It empowers over two million homes to connect a wide range of devices, allowing them to keep their data in their homes without being beholden to a single device manufacturer. It breathes new life into smart home devices, allowing households to use them longer, boosting sustainability in the smart home.
The community works together to build Home Assistant using GitHub to add features, report issues, fix bugs, add translations, and more. In fact, it was the top open source project on GitHub in 2024, with the most active community worldwide with over 21,000 contributors in that year alone. The community also organizes its development via other communication channels, specifically Discord and the Home Assistant Community Forum.
What are core integrations?
Linking up manufacturer devices with Home Assistant requires an integration. Anyone can create an integration and distribute it themselves, often called custom integrations or hosted separately, but when a number of requirements are met an integration can be built into Home Assistant, these are called ‘core integrations’. Used by the majority of our community, core integrations are built to provide an easy out-of-the-box experience for users, with no added installation or extra downloads.
Core integrations are built and maintained by community members, our core team, and device manufacturers who understand the power of working with our open source community.
Core code quality is reviewed by the internal core team of our employees as well as some of our dedicated core reviewer volunteers. The core integrations are central to user experience and so its code needs to follow best practice and standards.
Building and maintaining an integration
01. What skills do our team need to build / maintain an integration?
The project is built on Python, and to build an integration you will require a Python engineer who is familiar with async programming.
We would also recommend your engineers familiarize themselves with git and GitHub, in particular the requirements of submitting code to Home Assistant.
If you do not have these skills in-house, speak to us about mobilizing our community to help you build and maintain an integration. If you come to an agreement with a member of our community, we would expect them to be compensated fairly for their time and expertise, in whatever form that may take.
Some companies have also used agencies for these types of integrations. If so, we would recommend that they are familiar with the open source community and its values. You could ask to see other integrations they have written for Home Assistant and check them against the code quality scale.
02. Creating a Home Assistant core integration?
Every integration is different, but the scope largely depends on the number of device types, the functions each device supports, and the types of control included.
We recommend you build iteratively, starting with one device type or function, submitting code to us for feedback, and adding more over time.
On average, a standard integration in Home Assistant from someone with mid-level experience will take about a month.
We would generally recommend 1-3 full-time Python engineers to work on an integration in Core depending on its complexity.
A company should have its own Github organization structure, which engineers should join with their personal accounts.
03. Maintenance
Committing to a company-maintained integration also means ongoing maintenance. This is a much lower time-commitment than the build, but is important to keep on top of community feedback, suggestions, and pull requests.
Our core team also helps ensure that PRs are reviewed regularly and that each integration is maintained with each of our regular releases to keep it working into the future.
04. Licensing
Bearing in mind that we’re an open source project, your code must be published under an OSI-approved license. Because we are redistributing under an open source project, we need to be able to distribute without limitations.
05. Taking ownership of an existing community-built core integration
- Take a look at who maintains the integration currently and contact us about getting in touch with them. Most contributors would be thrilled to work alongside a manufacturer but we request that you don’t reach out to them cold, our team are happy to arrange an introduction.
- Use this contact and the existing open-sourced code to understand how the current integration is built and whether it’s realistic to expand on or improve it. Speak to our team if this is the case and we can help you find the best approach.
- Familiarize yourself with our documentation area.
- Assess the current integration against the integration quality scale to help set your improvement priorities.
06. Top tips
Remember the majority of our contributors are volunteers
Our community volunteers are the lifeblood of the project. Remember that they give their time for free to the project purely for their passion, curiosity, or improvement of their own smart home. Whilst we do have a core team of engineers, they are not your employees and are responsible for improving Home Assistant Core as a whole, not just for your integration.
Be understanding of our workload
At any given time our team and our volunteers have a list of several hundred ‘Pull Requests’ to review. Because of this, we cannot promise that an integration will be reviewed by a specific date.
Each month we have a Core Beta Release with a Core Release a week later. These release dates are on Wednesdays aside from widespread public holidays and you can see the calendar on our developer docs. It is highly unlikely that if you contact us on those days we’ll be able to take action quickly. Please be aware that our workload during the beta sprint is very high.
Here are some tips to help us implement your changes more quickly:
- Familiarize yourself with the pull request review process.
- Make small, iterative changes. Volunteers are more likely to be able to review your code in small bite-sized pieces rather than several thousand lines of code in one go. This will also help you stay on the right development track, rather than writing a full integration and realising the basics are incorrect and having to start again from scratch.
- If you would prefer not to publicly release in small chunks it is possible for us to use intermediate branches to store all the small iterations before full release.
- Be open to feedback - if you need to, ask for clarification, and don’t take changes or comments personally. Remember we have contributions from all over the world too so English may not be the reviewer’s or our engineer’s first language.
- Take advantage of our #devs category in our Discord chat.
