Skip to main content

​
Integration Overview

Integrations in Home Assistant are the building blocks that connect your home automation system with external devices, services, and platforms. This guide explains the architecture and core concepts behind Home Assistant integrations.

​
What is an Integration?

An integration is a Python package that enables Home Assistant to communicate with a specific device, service, or protocol. Each integration lives in the homeassistant/components/ directory and contains all the code needed to interact with that particular system.
Example: The MQTT integration (homeassistant/components/mqtt/) enables Home Assistant to communicate with devices using the MQTT protocol.

​
Integration Types

Home Assistant defines several integration types in the manifest, each serving a different purpose: 
{
  "domain": "mqtt",
  "name": "MQTT",
  "integration_type": "service",
  "iot_class": "local_push"
}

​
Available Integration Types

  • entity - Provides entity platforms for controlling devices
  • device - Represents physical devices with multiple entities
  • hardware - Interfaces with hardware (USB, GPIO, etc.)
  • helper - Provides utility functions or services
  • hub - Connects to a central hub that manages multiple devices
  • service - Provides connectivity to external services
  • system - Core Home Assistant functionality
  • virtual - Provides virtual/computed entities

​
Integration Architecture

Home Assistant uses a sophisticated loader system to discover and load integrations. Here’s how it works:
1
Discovery
2
Home Assistant scans for integrations in two locations:
3
  • Built-in integrations: homeassistant.components
  • Custom integrations: custom_components
    • 4
    # From loader.py
PACKAGE_CUSTOM_COMPONENTS = "custom_components"
PACKAGE_BUILTIN = "homeassistant.components"
    5
    Loading
    6
    The Integration class in loader.py handles loading integrations:
    7
    class Integration:
    """An integration in Home Assistant."""
    
    def __init__(
        self,
        hass: HomeAssistant,
        pkg_path: str,
        file_path: pathlib.Path,
        manifest: Manifest,
    ) -> None:
        self.hass = hass
        self.pkg_path = pkg_path
        self.file_path = file_path
        self.manifest = manifest
    8
    Setup
    9
    Integrations can be set up in two ways:
    10
  • YAML Configuration: Traditional async_setup() method
  • Config Flow: UI-based configuration with async_setup_entry()

    • ​
    Core Concepts

    ​
    Platforms

    Platforms are specific entity types that an integration can provide. Common platforms include:
    • light - Light entities
    • switch - Switch entities
    • sensor - Sensor entities
    • climate - Climate control entities
    • binary_sensor - Binary sensor entities
    # From const.py
class Platform(StrEnum):
    """Available entity platforms."""
    
    LIGHT = "light"
    SWITCH = "switch"
    SENSOR = "sensor"
    # ... more platforms

    ​
    Dependencies

    Integrations can depend on other integrations to function: 
    {
  "domain": "mqtt",
  "dependencies": ["file_upload", "http"],
  "after_dependencies": ["hassio"]
}
    dependencies: Must be loaded before this integrationafter_dependencies: Should be loaded before this integration if present, but not required

    ​
    Quality Scale

    Integrations can achieve different quality levels:
    • platinum - Highest quality, well-tested, excellent code
    • gold - High quality, good test coverage
    • silver - Good quality, basic tests
    • internal - Core Home Assistant integrations
    • custom - Custom integrations (default)
    When looking for examples to learn from, examine Platinum and Gold level integrations. The MQTT integration is a great example with a “platinum” quality scale.

    ​
    IoT Class

    The IoT class describes how an integration communicates:
    • local_push - Device pushes updates to Home Assistant locally
    • local_polling - Home Assistant polls device locally
    • cloud_push - Device pushes updates via cloud
    • cloud_polling - Home Assistant polls cloud API
    • calculated - Values are calculated, not from external sources

    ​
    Import Executor

    For performance, integrations can be loaded in an executor thread: 
    @cached_property
def import_executor(self) -> bool:
    """Import integration in the executor."""
    # Defaults to True for better performance
    return self.manifest.get("import_executor", True)
    Set "import_executor": false only if your integration must be imported in the event loop. This is rare and should be avoided when possible.

    ​
    Single Config Entry

    Some integrations should only have one configuration entry: 
    {
  "domain": "mqtt",
  "single_config_entry": true
}
    This prevents users from accidentally creating multiple entries for the same integration.

    ​
    Preload Platforms

    Certain platforms are automatically preloaded for faster startup: 
    BASE_PRELOAD_PLATFORMS = [
    "backup",
    "config_flow",
    "diagnostics",
    "logbook",
    "recorder",
    # ... more platforms
]

    ​
    Next Steps

    Creating Your First Integration

    Learn how to create a basic integration from scratch

    Integration Manifest

    Understand the manifest.json file structure

    Config Flow

    Implement UI-based configuration

    Entity Platforms

    Create entity platforms for your integration

    Build docs developers (and LLMs) love

    Get started for freeTalk to us