Building integrations

An integration connects Home Assistant to a device, a service, or an idea. It lives in its own folder, describes itself in a manifest, sets itself up from a config entry, and hands its data to Home Assistant as entities.

This part of the site walks through all of it, task by task. It is written for people who write Python. You do not need to read it front to back: start with the tutorial, and come back for the rest when your integration needs it.

• How an integration fits in: integrations, config entries, platforms, entities, devices, coordinators, and the event loop, in plain language.
• Build your first integration: a complete integration, step by step, from the scaffold to the pull request.
• Build a Python library: the library every integration uses to talk to its device or service.
• Create an integration: what is accepted in core, the scaffold script, and the smallest possible integration.
• File structure: which file does what, and where Home Assistant looks for integrations.
• Writing tests, in the development workflow: how to test an integration, with fixtures, mocks, and snapshots.

• Config entries: set up, unload, and migrate an integration, and keep its runtime data.
• Config flow: let users add your integration from the UI.
• Forms, menus, and progress: the building blocks of every flow.
• Options flow: let users change how the integration behaves.
• Subentries: store repeatable parts of a config entry, like locations.
• Reauthentication and reconfiguration: fix credentials and connection details without removing the integration.
• OAuth 2.0 and application credentials: link a user's account at a cloud service.
• YAML configuration: when it is still allowed, and how it works.
• Setup failures and exceptions: retry when a device is offline, and raise the right errors.

• Fetching data: polling, push, and the data update coordinator.
• Events: fire events, and listen to what happens in Home Assistant.
• Instance URL: find the URL a device or service can reach Home Assistant on.

• Discovery: how Home Assistant finds devices and starts your config flow.
• Network discovery: the zeroconf, SSDP, DHCP, USB, and network APIs.
• Bluetooth integrations: best practices and the Bluetooth API.
• Fetching Bluetooth data: coordinators driven by advertisements.

• Device registry: register devices, and link and split them.
• Entity registry: look up and migrate the entities of your integration.
• Area registry: what Home Assistant knows about areas.

• Actions: register actions that users can call from automations and scripts.
• Device automations: device triggers, conditions, and actions.
• Triggers and conditions: provide automation triggers and conditions.
• Diagnostics: let users download data to troubleshoot.
• System health: show the state of your integration on the system information page.
• Repairs: tell users about problems, and help them fix them.
• Asking for a restart: tell Home Assistant it needs a restart to apply a change.
• Reproduce state: make scenes work with your entities.
• Significant change: tell exporters which state changes matter.
• Backup: store backups somewhere, or prepare for one.
• Media source: expose browsable and playable media.

• The manifest: every key of manifest.json.
• Integration brands and images: icons, logos, and grouping integrations under one brand.
• Translations: every section of strings.json, references, and placeholders.

• Entities and platforms: the entity types your integration provides, like sensors and lights.
• Development workflow: the environment, tests, code style, and submitting your work.
• How core works: the hass object, the event loop, and the APIs beneath your integration.
• Make your strings translatable: how to write strings that translators can work with.
• Document your integration: every integration has a page on home-assistant.io.

• Ask in the #core channel on the Home Assistant Discord. Share a link to your branch, so people can see the code you are asking about.
• Look at a well maintained integration that does something similar. Many integrations at the Platinum tier of the quality scale, like airgradient, are good examples of current patterns.
• Not sure if your idea fits Home Assistant? Open a discussion in the architecture repository before you write a lot of code.