🇺🇸English

File Locations

• Integration code : ./homeassistant/components/<integration_domain>/
• Integration tests : ./tests/components/<integration_domain>/

Integration Templates

Standard Integration Structure

homeassistant/components/my_integration/
├── __init__.py          # Entry point with async_setup_entry
├── manifest.json        # Integration metadata and dependencies
├── const.py            # Domain and constants
├── config_flow.py      # UI configuration flow
├── coordinator.py      # Data update coordinator (if needed)
├── entity.py          # Base entity class (if shared patterns)
├── sensor.py          # Sensor platform
├── strings.json        # User-facing text and translations
├── services.yaml       # Service definitions (if applicable)
└── quality_scale.yaml  # Quality scale rule status

An integration can have platforms as needed (e.g., sensor.py, switch.py, etc.). The following platforms have extra guidelines:

• Diagnostics : platform-diagnostics.md for diagnostic data collection
• Repairs : platform-repairs.md for user-actionable repair issues

Minimal Integration Checklist

• manifest.json with required fields (domain, name, codeowners, etc.)
• __init__.py with async_setup_entry and async_unload_entry
• config_flow.py with UI configuration support
• const.py with DOMAIN constant
• strings.json with at least config flow text
• Platform files (sensor.py, etc.) as needed
• quality_scale.yaml with rule status tracking

Integration Quality Scale

Home Assistant uses an Integration Quality Scale to ensure code quality and consistency. The quality level determines which rules apply:

Quality Scale Levels

• Bronze : Basic requirements (ALL Bronze rules are mandatory)
• Silver : Enhanced functionality
• Gold : Advanced features
• Platinum : Highest quality standards

Quality Scale Progression

• Bronze → Silver : Add entity unavailability, parallel updates, auth flows
• Silver → Gold : Add device management, diagnostics, translations
• Gold → Platinum : Add strict typing, async dependencies, websession injection

How Rules Apply

1. Checkmanifest.json: Look for "quality_scale" key to determine integration level
2. Bronze Rules : Always required for any integration with quality scale
3. Higher Tier Rules : Only apply if integration targets that tier or higher
4. Rule Status : Check quality_scale.yaml in integration folder for:
   • done: Rule implemented
   • exempt: Rule doesn't apply (with reason in comment)
   • todo: Rule needs implementation

Example quality_scale.yaml Structure

rules:
  # Bronze (mandatory)
  config-flow: done
  entity-unique-id: done
  action-setup:
    status: exempt
    comment: Integration does not register custom actions.

  # Silver (if targeting Silver+)
  entity-unavailable: done
  parallel-updates: done

  # Gold (if targeting Gold+)
  devices: done
  diagnostics: done

  # Platinum (if targeting Platinum)
  strict-typing: done

When Reviewing/Creating Code : Always check the integration's quality scale level and exemption status before applying rules.

Code Organization

Core Locations

• Shared constants: homeassistant/const.py (use these instead of hardcoding)
• Integration structure:
  • homeassistant/components/{domain}/const.py - Constants
  • homeassistant/components/{domain}/models.py - Data models
  • homeassistant/components/{domain}/coordinator.py - Update coordinator
  • homeassistant/components/{domain}/config_flow.py - Configuration flow
  • homeassistant/components/{domain}/{platform}.py - Platform implementations

Common Modules

• coordinator.py : Centralize data fetching logic

  class MyCoordinator(DataUpdateCoordinator[MyData]):
  def __init__(self, hass: HomeAssistant, client: MyClient, config_entry: ConfigEntry) -> None:
      super().__init__(
          hass,
          logger=LOGGER,
          name=DOMAIN,
          update_interval=timedelta(minutes=1),
          config_entry=config_entry,  # ✅ Pass config_entry - it's accepted and recommended
      )
  

• entity.py : Base entity definitions to reduce duplication

  class MyEntity(CoordinatorEntity[MyCoordinator]):
  _attr_has_entity_name = True
  

Runtime Data Storage

• Use ConfigEntry.runtime_data : Store non-persistent runtime data

  type MyIntegrationConfigEntry = ConfigEntry[MyClient]
  

  async def async_setup_entry(hass: HomeAssistant, entry: MyIntegrationConfigEntry) -> bool: client = MyClient(entry.data[CONF_HOST]) entry.runtime_data = client

Manifest Requirements

• Required Fields : domain, name, codeowners, integration_type, documentation, requirements
• Integration Types : device, hub, service, system, helper

Config Flow Patterns

• Version Control : Always set VERSION = 1 and MINOR_VERSION = 1

• Unique ID Management :

  await self.async_set_unique_id(device_unique_id)
  

  self._abort_if_unique_id_configured()

• Error Handling : Define errors in strings.json under config.error

• Step Methods : Use standard naming (async_step_user, async_step_discovery, etc.)

Integration Ownership

• manifest.json : Add GitHub usernames to codeowners:

  {
  

  "domain": "my_integration", "name": "My Integration", "codeowners": ["@me"] }

Async Dependencies (Platinum)

• Requirement : All dependencies must use asyncio
• Ensures efficient task handling without thread context switching

WebSession Injection (Platinum)

• Pass WebSession : Support passing web sessions to dependencies

  async def async_setup_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
  """Set up integration from config entry."""
  client = MyClient(entry.data[CONF_HOST], async_get_clientsession(hass))
  

• For cookies: Use async_create_clientsession (aiohttp) or create_async_httpx_client (httpx)

Data Update Coordinator

• Standard Pattern : Use for efficient data management

  class MyCoordinator(DataUpdateCoordinator):
  def __init__(self, hass: HomeAssistant, client: MyClient, config_entry: ConfigEntry) -> None:
      super().__init__(
          hass,
          logger=LOGGER,
          name=DOMAIN,
          update_interval=timedelta(minutes=5),
          config_entry=config_entry,  # ✅ Pass config_entry - it's accepted and recommended
      )
      self.client = client
  
  async def _async_update_data(self):
      try:
          return await self.client.fetch_data()
      except ApiError as err:
          raise UpdateFailed(f"API communication error: {err}")
  

• Error Types : Use UpdateFailed for API errors, ConfigEntryAuthFailed for auth issues

• Config Entry : Always pass config_entry parameter to coordinator - it's accepted and recommended

Integration Guidelines

Configuration Flow

• UI Setup Required : All integrations must support configuration via UI

• Manifest : Set "config_flow": true in manifest.json

• Data Storage :

  • Connection-critical config: Store in ConfigEntry.data
  • Non-critical settings: Store in ConfigEntry.options

• Validation : Always validate user input before creating entries

• Config Entry Naming :

  • ❌ Do NOT allow users to set config entry names in config flows
  • Names are automatically generated or can be customized later in UI
  • ✅ Exception: Helper integrations MAY allow custom names in config flow

• Connection Testing : Test device/service connection during config flow:

  try:
  await client.get_data()
  

Reauthentication Support

• Required Method : Implement async_step_reauth in config flow

• Credential Updates : Allow users to update credentials without re-adding

• Validation : Verify account matches existing unique ID:

  await self.async_set_unique_id(user_id)
  

  self._abort_if_unique_id_mismatch(reason="wrong_account") return self.async_update_reload_and_abort( self._get_reauth_entry(), data_updates={CONF_API_TOKEN: user_input[CONF_API_TOKEN]} )

Reconfiguration Flow

• Purpose : Allow configuration updates without removing device
• Implementation : Add async_step_reconfigure method
• Validation : Prevent changing underlying account with _abort_if_unique_id_mismatch

Device Discovery

• Manifest Configuration : Add discovery method (zeroconf, dhcp, etc.)

  {
  

  "zeroconf": ["_mydevice._tcp.local."] }

• Discovery Handler : Implement appropriate async_step_* method:

  async def async_step_zeroconf(self, discovery_info):
  """Handle zeroconf discovery."""
  await self.async_set_unique_id(discovery_info.properties["serialno"])
  self._abort_if_unique_id_configured(updates={CONF_HOST: discovery_info.host})
  

• Network Updates : Use discovery to update dynamic IP addresses

Network Discovery Implementation

• Zeroconf/mDNS : Use async instances

  aiozc = await zeroconf.async_get_async_instance(hass)
  

• SSDP Discovery : Register callbacks with cleanup

  entry.async_on_unload(
  ssdp.async_register_callback(
      hass, _async_discovered_device,
      {"st": "urn:schemas-upnp-org:device:ZonePlayer:1"}
  )
  

  )

Bluetooth Integration

• Manifest Dependencies : Add bluetooth_adapters to dependencies

• Connectable : Set "connectable": true for connection-required devices

• Scanner Usage : Always use shared scanner instance

  scanner = bluetooth.async_get_scanner()
  

  entry.async_on_unload( bluetooth.async_register_callback( hass, _async_discovered_device, {"service_uuid": "example_uuid"}, bluetooth.BluetoothScanningMode.ACTIVE ) )

• Connection Handling : Never reuse BleakClient instances, use 10+ second timeouts

Setup Validation

• Test Before Setup : Verify integration can be set up in async_setup_entry
• Exception Handling :
  • ConfigEntryNotReady: Device offline or temporary failure
  • ConfigEntryAuthFailed: Authentication issues
  • ConfigEntryError: Unresolvable setup problems

Config Entry Unloading

• Required : Implement async_unload_entry for runtime removal/reload

• Platform Unloading : Use hass.config_entries.async_unload_platforms

• Cleanup : Register callbacks with entry.async_on_unload:

  async def async_unload_entry(hass: HomeAssistant, entry: MyConfigEntry) -> bool:
  """Unload a config entry."""
  if unload_ok := await hass.config_entries.async_unload_platforms(entry, PLATFORMS):
      entry.runtime_data.listener()  # Clean up resources
  return unload_ok
  

Service Actions

• Registration : Register all service actions in async_setup, NOT in async_setup_entry

• Validation : Check config entry existence and loaded state:

  async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
  async def service_action(call: ServiceCall) -> ServiceResponse:
      if not (entry := hass.config_entries.async_get_entry(call.data[ATTR_CONFIG_ENTRY_ID])):
          raise ServiceValidationError("Entry not found")
      if entry.state is not ConfigEntryState.LOADED:
          raise ServiceValidationError("Entry not loaded")
  

• Exception Handling : Raise appropriate exceptions:

  # For invalid input
  

  if end_date < start_date: raise ServiceValidationError("End date must be after start date")

  For service errors

  try: await client.set_schedule(start_date, end_date) except MyConnectionError as err: raise HomeAssistantError("Could not connect to the schedule") from err

Service Registration Patterns

• Entity Services : Register on platform setup

  platform.async_register_entity_service(
  "my_entity_service",
  {vol.Required("parameter"): cv.string},
  "handle_service_method"
  

  )

• Service Schema : Always validate input

  SERVICE_SCHEMA = vol.Schema({
  vol.Required("entity_id"): cv.entity_ids,
  vol.Required("parameter"): cv.string,
  vol.Optional("timeout", default=30): cv.positive_int,
  

  })

• Services File : Create services.yaml with descriptions and field definitions

Polling

• Use update coordinator pattern when possible

• Polling intervals are NOT user-configurable : Never add scan_interval, update_interval, or polling frequency options to config flows or config entries

• Integration determines intervals : Set update_interval programmatically based on integration logic, not user input

• Minimum Intervals :

  • Local network: 5 seconds
  • Cloud services: 60 seconds

• Parallel Updates : Specify number of concurrent updates:

  PARALLEL_UPDATES = 1  # Serialize updates to prevent overwhelming device
  

  OR

  PARALLEL_UPDATES = 0 # Unlimited (for coordinator-based or read-only)

Entity Development

Unique IDs

• Required : Every entity must have a unique ID for registry tracking

• Must be unique per platform (not per integration)

• Don't include integration domain or platform in ID

• Implementation :

  class MySensor(SensorEntity):
  def __init__(self, device_id: str) -> None:
      self._attr_unique_id = f"{device_id}_temperature"
  

Acceptable ID Sources :

• Device serial numbers
• MAC addresses (formatted using format_mac from device registry)
• Physical identifiers (printed/EEPROM)
• Config entry ID as last resort: f"{entry.entry_id}-battery"

Never Use :

• IP addresses, hostnames, URLs
• Device names
• Email addresses, usernames

Entity Descriptions

• Lambda/Anonymous Functions : Often used in EntityDescription for value transformation

• Multiline Lambdas : When lambdas exceed line length, wrap in parentheses for readability

• Bad pattern :

  SensorEntityDescription(
  key="temperature",
  name="Temperature",
  value_fn=lambda data: round(data["temp_value"] * 1.8 + 32, 1) if data.get("temp_value") is not None else None,  # ❌ Too long
  

  )

• Good pattern :

  SensorEntityDescription(
  key="temperature",
  name="Temperature",
  value_fn=lambda data: (  # ✅ Parenthesis on same line as lambda
      round(data["temp_value"] * 1.8 + 32, 1)
      if data.get("temp_value") is not None
      else None
  ),
  

  )

Entity Naming

• Use has_entity_name : Set _attr_has_entity_name = True

• For specific fields :

  class MySensor(SensorEntity):
  _attr_has_entity_name = True
  def __init__(self, device: Device, field: str) -> None:
      self._attr_device_info = DeviceInfo(
          identifiers={(DOMAIN, device.id)},
          name=device.name,
      )
      self._attr_name = field  # e.g., "temperature", "humidity"
  

• For device itself : Set _attr_name = None

Event Lifecycle Management

• Subscribe inasync_added_to_hass:

  async def async_added_to_hass(self) -> None:
  """Subscribe to events."""
  self.async_on_remove(
      self.client.events.subscribe("my_event", self._handle_event)
  )
  

• Unsubscribe inasync_will_remove_from_hass if not using async_on_remove

• Never subscribe in __init__ or other methods

State Handling

• Unknown values: Use None (not "unknown" or "unavailable")
• Availability: Implement available() property instead of using "unavailable" state

Entity Availability

• Mark Unavailable : When data cannot be fetched from device/service

• Coordinator Pattern :

  @property
  

  def available(self) -> bool: """Return if entity is available.""" return super().available and self.identifier in self.coordinator.data

• Direct Update Pattern :

  async def async_update(self) -> None:
  """Update entity."""
  try:
      data = await self.client.get_data()
  except MyException:
      self._attr_available = False
  else:
      self._attr_available = True
      self._attr_native_value = data.value
  

Extra State Attributes

• All attribute keys must always be present
• Unknown values: Use None
• Provide descriptive attributes

Device Management

Device Registry

• Create Devices : Group related entities under devices

• Device Info : Provide comprehensive metadata:

  _attr_device_info = DeviceInfo(
  connections={(CONNECTION_NETWORK_MAC, device.mac)},
  identifiers={(DOMAIN, device.id)},
  name=device.name,
  manufacturer="My Company",
  model="My Sensor",
  sw_version=device.version,
  

  )

• For services: Add entry_type=DeviceEntryType.SERVICE

Dynamic Device Addition

• Auto-detect New Devices : After initial setup

• Implementation Pattern :

  def _check_device() -> None:
  current_devices = set(coordinator.data)
  new_devices = current_devices - known_devices
  if new_devices:
      known_devices.update(new_devices)
      async_add_entities([MySensor(coordinator, device_id) for device_id in new_devices])
  

  entry.async_on_unload(coordinator.async_add_listener(_check_device))

Stale Device Removal

• Auto-remove : When devices disappear from hub/account

• Device Registry Update :

  device_registry.async_update_device(
  device_id=device.id,
  remove_config_entry_id=self.config_entry.entry_id,
  

  )

• Manual Deletion : Implement async_remove_config_entry_device when needed

Entity Categories

• Required : Assign appropriate category to entities

• Implementation : Set _attr_entity_category

  class MySensor(SensorEntity):
  _attr_entity_category = EntityCategory.DIAGNOSTIC
  

• Categories include: DIAGNOSTIC for system/technical information

Device Classes

• Use When Available : Set appropriate device class for entity type

  class MyTemperatureSensor(SensorEntity):
  _attr_device_class = SensorDeviceClass.TEMPERATURE
  

• Provides context for: unit conversion, voice control, UI representation

Disabled by Default

• Disable Noisy/Less Popular Entities : Reduce resource usage

  class MySignalStrengthSensor(SensorEntity):
  _attr_entity_registry_enabled_default = False
  

• Target: frequently changing states, technical diagnostics

Entity Translations

• Required with has_entity_name : Support international users

• Implementation :

  class MySensor(SensorEntity):
  _attr_has_entity_name = True
  _attr_translation_key = "phase_voltage"
  

• Create strings.json with translations:

  {
  

  "entity": { "sensor": { "phase_voltage": { "name": "Phase voltage" } } } }

Exception Translations (Gold)

• Translatable Errors : Use translation keys for user-facing exceptions

• Implementation :

  raise ServiceValidationError(
  translation_domain=DOMAIN,
  translation_key="end_date_before_start_date",
  

  )

• Add to strings.json:

  {
  

  "exceptions": { "end_date_before_start_date": { "message": "The end date cannot be before the start date." } } }

Icon Translations (Gold)

• Dynamic Icons : Support state and range-based icon selection

• State-based Icons :

  {
  

  "entity": { "sensor": { "tree_pollen": { "default": "mdi:tree", "state": { "high": "mdi:tree-outline" } } } } }

• Range-based Icons (for numeric values):

  {
  

  "entity": { "sensor": { "battery_level": { "default": "mdi:battery-unknown", "range": { "0": "mdi:battery-outline", "90": "mdi:battery-90", "100": "mdi:battery" } } } } }

Testing Requirements

• Location : tests/components/{domain}/
• Coverage Requirement : Above 95% test coverage for all modules
• Best Practices :
  • Use pytest fixtures from tests.common
  • Mock all external dependencies
  • Use snapshots for complex data structures
  • Follow existing test patterns

Config Flow Testing

• 100% Coverage Required : All config flow paths must be tested
• Patch Boundaries : Only patch library or client methods when testing config flows. Do not patch methods defined in config_flow.py; exercise the flow logic end-to-end.
• Test Scenarios :
  • All flow initiation methods (user, discovery, import)
  • Successful configuration paths
  • Error recovery scenarios
  • Prevention of duplicate entries
  • Flow completion after errors
  • Reauthentication/reconfigure flows

Testing

• Integration-specific tests (recommended):

  pytest ./tests/components/<integration_domain> \
  

  --cov=homeassistant.components.<integration_domain>
  --cov-report term-missing
  --durations-min=1
  --durations=0
  --numprocesses=auto

Testing Best Practices

• Never accesshass.data directly - Use fixtures and proper integration setup instead
• Use snapshot testing - For verifying entity states and attributes
• Test through integration setup - Don't test entities in isolation
• Mock external APIs - Use fixtures with realistic JSON data
• Verify registries - Ensure entities are properly registered with devices

Config Flow Testing Template

async def test_user_flow_success(hass, mock_api):
    """Test successful user flow."""
    result = await hass.config_entries.flow.async_init(
        DOMAIN, context={"source": config_entries.SOURCE_USER}
    )
    assert result["type"] == FlowResultType.FORM
    assert result["step_id"] == "user"

    # Test form submission
    result = await hass.config_entries.flow.async_configure(
        result["flow_id"], user_input=TEST_USER_INPUT
    )
    assert result["type"] == FlowResultType.CREATE_ENTRY
    assert result["title"] == "My Device"
    assert result["data"] == TEST_USER_INPUT

async def test_flow_connection_error(hass, mock_api_error):
    """Test connection error handling."""
    result = await hass.config_entries.flow.async_init(
        DOMAIN, context={"source": config_entries.SOURCE_USER}
    )
    result = await hass.config_entries.flow.async_configure(
        result["flow_id"], user_input=TEST_USER_INPUT
    )
    assert result["type"] == FlowResultType.FORM
    assert result["errors"] == {"base": "cannot_connect"}

Entity Testing Patterns

@pytest.fixture
def platforms() -> list[Platform]:
    """Overridden fixture to specify platforms to test."""
    return [Platform.SENSOR]  # Or another specific platform as needed.

@pytest.mark.usefixtures("entity_registry_enabled_by_default", "init_integration")
async def test_entities(
    hass: HomeAssistant,
    snapshot: SnapshotAssertion,
    entity_registry: er.EntityRegistry,
    device_registry: dr.DeviceRegistry,
    mock_config_entry: MockConfigEntry,
) -> None:
    """Test the sensor entities."""
    await snapshot_platform(hass, entity_registry, snapshot, mock_config_entry.entry_id)

    # Ensure entities are correctly assigned to device
    device_entry = device_registry.async_get_device(
        identifiers={(DOMAIN, "device_unique_id")}
    )
    assert device_entry
    entity_entries = er.async_entries_for_config_entry(
        entity_registry, mock_config_entry.entry_id
    )
    for entity_entry in entity_entries:
        assert entity_entry.device_id == device_entry.id

Mock Patterns

# Modern integration fixture setup
@pytest.fixture
def mock_config_entry() -> MockConfigEntry:
    """Return the default mocked config entry."""
    return MockConfigEntry(
        title="My Integration",
        domain=DOMAIN,
        data={CONF_HOST: "127.0.0.1", CONF_API_KEY: "test_key"},
        unique_id="device_unique_id",
    )

@pytest.fixture
def mock_device_api() -> Generator[MagicMock]:
    """Return a mocked device API."""
    with patch("homeassistant.components.my_integration.MyDeviceAPI", autospec=True) as api_mock:
        api = api_mock.return_value
        api.get_data.return_value = MyDeviceData.from_json(
            load_fixture("device_data.json", DOMAIN)
        )
        yield api

@pytest.fixture
def platforms() -> list[Platform]:
    """Fixture to specify platforms to test."""
    return PLATFORMS

@pytest.fixture
async def init_integration(
    hass: HomeAssistant,
    mock_config_entry: MockConfigEntry,
    mock_device_api: MagicMock,
    platforms: list[Platform],
) -> MockConfigEntry:
    """Set up the integration for testing."""
    mock_config_entry.add_to_hass(hass)

    with patch("homeassistant.components.my_integration.PLATFORMS", platforms):
        await hass.config_entries.async_setup(mock_config_entry.entry_id)
        await hass.async_block_till_done()

    return mock_config_entry

Debugging & Troubleshooting

Common Issues & Solutions

• Integration won't load : Check manifest.json syntax and required fields
• Entities not appearing : Verify unique_id and has_entity_name implementation
• Config flow errors : Check strings.json entries and error handling
• Discovery not working : Verify manifest discovery configuration and callbacks
• Tests failing : Check mock setup and async context

Debug Logging Setup

# Enable debug logging in tests
caplog.set_level(logging.DEBUG, logger="my_integration")

# In integration code - use proper logging
_LOGGER = logging.getLogger(__name__)
_LOGGER.debug("Processing data: %s", data)  # Use lazy logging

Validation Commands

# Check specific integration
python -m script.hassfest --integration-path homeassistant/components/my_integration

# Validate quality scale
# Check quality_scale.yaml against current rules

# Run integration tests with coverage
pytest ./tests/components/my_integration \
  --cov=homeassistant.components.my_integration \
  --cov-report term-missing

Weekly Installs

–

Repository

home-assistant/core

GitHub Stars

85.8K

First Seen

–

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass