3.2 KiB
| title | sidebar_label |
|---|---|
| Integration file structure | File structure |
Each integration is stored inside a directory named after the integration domain. The domain is a short name consisting of characters and underscores. This domain has to be unique and cannot be changed. Example of the domain for the mobile app integration: mobile_app. So all files for this integration are in the folder mobile_app/.
The bare minimum content of this folder looks like this:
manifest.json: The manifest file describes the integration and its dependencies. More info__init__.py: The component file. If the integration only offers a platform, you can keep this file limited to a docstring introducing the integration"""The Mobile App integration.""".
Integrating devices - light.py, switch.py etc
If your integration is going to integrate one or more devices, you will need to do this by creating a platform that interacts with an entity integration. For example, if you want to represent a light device inside Home Assistant, you will create light.py, which will contain a light platform for the light integration.
- More info on available entity integrations.
- More info on creating platforms.
Integrating service actions - services.yaml
If your integration is going to register service actions, it will need to provide a description of the available actions. The description is stored in services.yaml. More information about services.yaml.
Data update coordinator - coordinator.py
There are multiple ways for your integration to receive data, including push or poll. Commonly integrations will fetch data with a single coordinated poll across all entities, which requires the use of a DataUpdateCoordinator.
If you want to use one, and you choose to create a subclass of it, it is recommended to define the coordinator class in coordinator.py. More information about DataUpdateCoordinator.
Where Home Assistant looks for integrations
Home Assistant will look for an integration when it sees the domain referenced in the config file (i.e. mobile_app:) or if it is a dependency of another integration. Home Assistant will look at the following locations:
<config directory>/custom_components/<domain>homeassistant/components/<domain>(built-in integrations)
You can override a built-in integration by having an integration with the same domain in your <config directory>/custom_components folder. The manifest.json file requires a version tag when you override a core integration. An overridden core integration can be identified by a specific icon in the upper right corner of the integration box in the overview 
Note that overriding built-in integrations is not recommended as you will no longer get updates. It is recommended to pick a unique name.