Creating a New Integration

Step-by-step guide to creating a new Home Assistant integration

This guide will walk you through creating a new integration for Home Assistant. We’ll cover the essential files, structure, and best practices for building a high-quality integration.

Prerequisites

Before you begin, ensure you have:

• A working Home Assistant development environment
• Python 3.12 or later installed
• Familiarity with async/await patterns in Python
• Understanding of the device or service you want to integrate

Integration Structure

A basic integration consists of several key files:

homeassistant/components/your_integration/
├── __init__.py           # Main integration setup
├── manifest.json         # Integration metadata
├── config_flow.py        # Configuration UI flow
├── const.py             # Constants and configuration keys
├── sensor.py            # Entity platform (example)
└── strings.json         # Translations for UI

Step 1: Create the Manifest

The manifest.json file defines your integration’s metadata. This is required for Home Assistant to recognize your integration.

manifest.json

{
  "domain": "your_integration",
  "name": "Your Integration",
  "codeowners": ["@your-github-username"],
  "config_flow": true,
  "documentation": "https://www.home-assistant.io/integrations/your_integration",
  "iot_class": "cloud_polling",
  "requirements": ["your-library==1.0.0"],
  "version": "1.0.0"
}

Key Manifest Fields

• domain: Unique identifier for your integration (lowercase, no spaces)
• name: Human-readable name displayed in the UI
• config_flow: Set to true if your integration uses the UI configuration flow
• iot_class: How the integration communicates (see IoT class documentation)
• requirements: Python packages required by your integration
• codeowners: GitHub usernames responsible for maintaining this integration

Step 2: Define Constants

Create a const.py file to store configuration keys and constants:

const.py

"""Constants for the Your Integration integration."""

DOMAIN = "your_integration"

# Configuration keys
CONF_API_KEY = "api_key"
CONF_HOST = "host"

# Default values
DEFAULT_PORT = 8080
DEFAULT_SCAN_INTERVAL = 60

Step 3: Implement the Main Integration

The __init__.py file contains the core integration setup logic:

__init__.py

"""The Your Integration integration."""
from __future__ import annotations

import logging

from homeassistant.config_entries import ConfigEntry
from homeassistant.const import Platform
from homeassistant.core import HomeAssistant
from homeassistant.exceptions import ConfigEntryNotReady

from .const import DOMAIN

_LOGGER = logging.getLogger(__name__)

# List of platforms to support
PLATFORMS: list[Platform] = [Platform.SENSOR]


async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Set up Your Integration from a config entry."""
    # Store an API client or coordinator in hass.data
    hass.data.setdefault(DOMAIN, {})
    
    try:
        # Initialize your API client or data coordinator
        # Example: api_client = YourAPIClient(entry.data[CONF_API_KEY])
        # await api_client.async_connect()
        
        # Store the client for use by platforms
        hass.data[DOMAIN][entry.entry_id] = {
            "client": None,  # Your API client here
        }
    except Exception as err:
        raise ConfigEntryNotReady(f"Unable to connect: {err}") from err
    
    # Forward the setup to platforms
    await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
    
    return True


async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Unload a config entry."""
    # Unload platforms
    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
    
    if unload_ok:
        # Clean up stored data
        hass.data[DOMAIN].pop(entry.entry_id)
    
    return unload_ok

Key Functions

async_setup_entry

This is the main entry point for modern integrations. It:

1. Initializes API clients or data coordinators
2. Stores shared data in hass.data[DOMAIN]
3. Forwards setup to entity platforms
4. Returns True on success or raises ConfigEntryNotReady on failure

async_unload_entry

Cleans up when the integration is removed:

1. Unloads all entity platforms
2. Cleans up stored data
3. Closes API connections if needed

Step 4: Create a Config Flow

The config flow handles user configuration through the UI. See the Config Entries guide for detailed information.

config_flow.py

"""Config flow for Your Integration."""
from __future__ import annotations

import voluptuous as vol

from homeassistant import config_entries
from homeassistant.data_entry_flow import FlowResult

from .const import CONF_API_KEY, DOMAIN


class YourIntegrationConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
    """Handle a config flow for Your Integration."""
    
    VERSION = 1
    
    async def async_step_user(
        self, user_input: dict[str, Any] | None = None
    ) -> FlowResult:
        """Handle the initial step."""
        errors = {}
        
        if user_input is not None:
            # Validate the input
            try:
                # Test the connection with provided credentials
                # await validate_credentials(user_input[CONF_API_KEY])
                
                # Create the config entry
                return self.async_create_entry(
                    title="Your Integration",
                    data=user_input,
                )
            except Exception:
                errors["base"] = "cannot_connect"
        
        # Show the configuration form
        return self.async_show_form(
            step_id="user",
            data_schema=vol.Schema({
                vol.Required(CONF_API_KEY): str,
            }),
            errors=errors,
        )

Step 5: Create Entity Platforms

Entity platforms provide the actual functionality. For example, a sensor platform:

sensor.py

"""Sensor platform for Your Integration."""
from homeassistant.components.sensor import SensorEntity
from homeassistant.config_entries import ConfigEntry
from homeassistant.core import HomeAssistant
from homeassistant.helpers.entity_platform import AddEntitiesCallback

from .const import DOMAIN


async def async_setup_entry(
    hass: HomeAssistant,
    entry: ConfigEntry,
    async_add_entities: AddEntitiesCallback,
) -> None:
    """Set up sensor platform."""
    # Get the API client from hass.data
    client = hass.data[DOMAIN][entry.entry_id]["client"]
    
    # Create sensor entities
    async_add_entities([
        YourSensor(client, "temperature"),
        YourSensor(client, "humidity"),
    ])


class YourSensor(SensorEntity):
    """Representation of a Your Integration sensor."""
    
    def __init__(self, client, sensor_type):
        """Initialize the sensor."""
        self._client = client
        self._sensor_type = sensor_type
        self._attr_name = f"Your Integration {sensor_type}"
        self._attr_unique_id = f"{DOMAIN}_{sensor_type}"
    
    async def async_update(self) -> None:
        """Fetch new state data for the sensor."""
        # Update the sensor value
        # self._attr_native_value = await self._client.get_value(self._sensor_type)
        pass

See the Entity Component guide for more details on creating entities.

Step 6: Add Translations

Create a strings.json file for UI translations:

strings.json

{
  "config": {
    "step": {
      "user": {
        "title": "Connect to Your Integration",
        "description": "Enter your API credentials",
        "data": {
          "api_key": "API Key"
        }
      }
    },
    "error": {
      "cannot_connect": "Failed to connect, please check your API key"
    }
  }
}

Testing Your Integration

Before submitting your integration:

1. Run tests: Ensure your integration has comprehensive test coverage
2. Check code quality: Run pylint and mypy on your code
3. Test manually: Install your integration in a development Home Assistant instance
4. Review the checklist: Follow the integration quality scale requirements

Best Practices

Use DataUpdateCoordinator

For integrations that poll data, use DataUpdateCoordinator to efficiently manage updates:

from homeassistant.helpers.update_coordinator import DataUpdateCoordinator

coordinator = DataUpdateCoordinator(
    hass,
    _LOGGER,
    name="your_integration",
    update_method=async_update_data,
    update_interval=timedelta(seconds=60),
)

Handle Connection Errors

Always handle connection errors gracefully:

• Raise ConfigEntryNotReady during setup if the device is temporarily unavailable
• Raise ConfigEntryAuthFailed if authentication fails
• Set entity available property based on connection status

Use Unique IDs

Always provide unique IDs for entities to enable customization:

self._attr_unique_id = f"{entry.entry_id}_{device_id}_{sensor_type}"

Follow the Quality Scale

Aim for at least Silver quality scale:

• Use config flow (no YAML configuration)
• Implement proper entity naming
• Handle errors gracefully
• Provide translations
• Include tests

Next Steps

• Learn about Config Entries
• Create Entity Components
• Implement Device Automation
• Review existing integrations for examples
• Read the Integration Quality Scale

Common Patterns

Single Config Entry Integrations

For services that should only have one configuration:

manifest.json

{
  "single_config_entry": true
}

Virtual Integrations

For integrations that re-use another integration’s code:

manifest.json

{
  "integration_type": "virtual"
}

Resources

• Home Assistant Developer Documentation
• Integration Examples
• Discord Developer Channel