Integration Overview

Understanding Home Assistant integrations and their architecture

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:

manifest.json - Service Integration

{
  "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:

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 integration

after_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