home-assistant-dev

name	home-assistant-dev
description	Comprehensive Home Assistant custom integration development skill. Use when developing Home Assistant integrations, custom components, or plugins. Covers entity platforms, config flows, data management, quality requirements, testing, and HACS publishing. Includes complete reference documentation for all 47+ entity types, integration quality scale requirements, and step-by-step publishing guides.

Home Assistant Development

Complete skill for building, testing, and publishing Home Assistant custom integrations.

When to Use This Skill

Use this skill when:

• Creating a new Home Assistant custom integration or component
• Developing entity platforms (sensors, switches, lights, etc.)
• Implementing config flows for UI-based setup
• Managing data coordinators and API polling
• Publishing to HACS (Home Assistant Community Store)
• Troubleshooting integration development issues
• Ensuring integration quality and best practices
• Understanding Home Assistant architecture and APIs

Quick Start Workflow

1. Planning Your Integration

Determine Integration Type:

• Device: Physical hardware (smart bulbs, sensors, thermostats)
• Service: Cloud API or web service (weather, notifications, calendar)
• Hub: Local or cloud hub managing multiple devices (Zigbee, Z-Wave hubs)
• Helper: Utility integration (rare for custom integrations)

Choose IoT Class:

• cloud_polling - Poll cloud API regularly
• cloud_push - Cloud pushes updates to HA
• local_polling - Poll local device
• local_push - Device pushes updates (webhooks, MQTT, etc.)
• calculated - Derives data from other sources

2. Set Up Development Environment

Options:

1. VS Code DevContainer (recommended for core contribution)
   • See: assets/docs/setup_devcontainer_environment.md
2. Custom Integration Development
   • Install Home Assistant (Core, Container, or Supervisor)
   • Create custom_components/<your_domain>/ in config directory
   • Enable debug logging in configuration.yaml

3. Create Integration Structure

Run scaffold command (if contributing to core) or manually create:

custom_components/your_domain/
├── __init__.py              # Setup and coordinator
├── manifest.json            # Integration metadata
├── config_flow.py           # UI configuration flow
├── const.py                 # Constants (DOMAIN, etc.)
├── coordinator.py           # DataUpdateCoordinator (optional)
├── sensor.py                # Entity platforms
├── switch.py
├── strings.json             # Translations
└── translations/
    └── en.json

Key Files:

• manifest.json - Required metadata (domain, name, version, requirements, etc.)
  • Reference: Integration Basics
• __init__.py - Entry point with async_setup_entry() and async_unload_entry()
• config_flow.py - UI-based configuration (Bronze quality requirement)
• Platform files - Entity implementations (sensor.py, switch.py, etc.)

4. Choose Entity Platforms

Identify what entities your integration provides. Reference the complete list:

• See: Entity Platforms Reference

Common combinations:

• Smart Device: sensor + switch + binary_sensor
• Climate Control: climate + sensor + switch
• Media Device: media_player + remote
• Security: binary_sensor + camera + alarm_control_panel
• Voice Assistant: stt + tts + conversation

5. Implement Config Flow

Bronze Quality Requirement - All integrations need UI configuration.

Steps:

1. Create config_flow.py extending ConfigFlow
2. Implement async_step_user() for manual setup
3. Set unique_id with self.async_set_unique_id()
4. Check for duplicates with self._abort_if_unique_id_configured()
5. Create entry with self.async_create_entry()
6. Add config_flow: true to manifest.json

Reference: Config Flows

6. Implement Setup Entry

In __init__.py:

async def async_setup_entry(hass, entry):
    """Set up from config entry."""
    # 1. Create API client or coordinator
    coordinator = MyCoordinator(hass, entry)
    await coordinator.async_config_entry_first_refresh()
    
    # 2. Store in hass.data
    hass.data.setdefault(DOMAIN, {})
    hass.data[DOMAIN][entry.entry_id] = coordinator
    
    # 3. Forward to platforms
    await hass.config_entries.async_forward_entry_setups(
        entry, ["sensor", "switch"]
    )
    
    # 4. Register update listener
    entry.async_on_unload(entry.add_update_listener(update_listener))
    
    return True

async def async_unload_entry(hass, entry):
    """Unload config entry."""
    unload_ok = await hass.config_entries.async_unload_platforms(
        entry, ["sensor", "switch"]
    )
    if unload_ok:
        hass.data[DOMAIN].pop(entry.entry_id)
    return unload_ok

7. Implement Entities

Create platform files (e.g., sensor.py):

async def async_setup_entry(hass, entry, async_add_entities):
    """Set up sensors."""
    coordinator = hass.data[DOMAIN][entry.entry_id]
    
    async_add_entities([
        MySensor(coordinator, "temperature"),
        MySensor(coordinator, "humidity"),
    ])

class MySensor(CoordinatorEntity, SensorEntity):
    """Sensor entity."""
    
    def __init__(self, coordinator, sensor_type):
        """Initialize sensor."""
        super().__init__(coordinator)
        self._attr_unique_id = f"{coordinator.device_id}_{sensor_type}"
        self._attr_has_entity_name = True
        self._attr_name = sensor_type.title()
        self._sensor_type = sensor_type
    
    @property
    def native_value(self):
        """Return sensor value."""
        return self.coordinator.data[self._sensor_type]
    
    @property
    def device_info(self):
        """Return device info."""
        return {
            "identifiers": {(DOMAIN, self.coordinator.device_id)},
            "name": "My Device",
            "manufacturer": "My Company",
            "model": "Model X",
        }

Reference specific entity types: Entity Platforms

8. Test Your Integration

Required for Bronze Quality:

1. Write config flow tests - Test all flow steps, error cases, duplicates
2. Test setup/unload - Verify entry lifecycle
3. Test entities - State, attributes, updates, availability
4. Run validation - python3 -m script.hassfest

Reference: Testing and Validation

9. Ensure Quality

Follow the integration quality scale for reliability:

Bronze (Required for HACS):

• ✓ Config flow
• ✓ Config flow tests
• ✓ Unique config entry
• ✓ Brand assets

Silver (Recommended):

• ✓ Reauthentication flow
• ✓ Proper error handling
• ✓ Entity availability states

Gold (Professional):

• ✓ Reconfiguration flow
• ✓ Diagnostics
• ✓ Entity translations
• ✓ Good documentation

Reference: Quality Scale

10. Publish to HACS

Prerequisites:

1. Public GitHub repository
2. Valid manifest.json with version field
3. Repository description, topics, and README
4. hacs.json file (optional but recommended)
5. GitHub releases

Publishing Steps:

1. Add hacs.json to repository root
2. Validate with hacs/action GitHub Action
3. Create first GitHub release
4. Test as custom repository
5. Submit PR to hacs/default (optional, for default store)

Reference: HACS Publishing

Reference Documentation

Integration Basics

File: references/integration-basics.md

Core integration concepts:

• Integration types and IoT classes
• Manifest.json requirements
• File structure and organization
• Setup methods (async_setup_entry)
• Service definitions
• Device and entity registry
• State and event system
• AsyncIO best practices

When to consult:

• Starting a new integration
• Understanding integration architecture
• Setting up async coordinators
• Working with registries
• Implementing services

Entity Platforms

File: references/entity-platforms.md

Complete reference for all 47+ entity platform types:

• Sensor, Binary Sensor, Switch, Light, Climate
• Media Player, Camera, Cover, Lock, Fan, Vacuum
• Weather, Humidifier, Water Heater
• Number, Select, Text, Button, Date/Time
• Calendar, Todo, Scene, Event
• Voice entities (STT, TTS, Conversation, Wake Word)
• And 20+ more specialized types

Each platform includes:

• Properties and device classes
• State classes and units of measurement
• Common patterns and examples
• Links to complete documentation

When to consult:

• Choosing entity types for your integration
• Understanding entity properties
• Implementing specific platforms
• Finding device classes and units
• Learning platform-specific features

Config Flows and Data Management

File: references/config-flows.md

UI-based configuration and data handling:

• Config flow implementation
• Options flow for settings
• Data entry flow framework
• Setup and teardown
• DataUpdateCoordinator patterns
• Registry management (entity, device, area)
• Network discovery (mDNS, SSDP, DHCP, etc.)
• Authentication systems

When to consult:

• Implementing config flows (Bronze requirement)
• Adding options flows
• Managing data polling and updates
• Handling setup failures
• Working with discovery protocols
• Setting up authentication

Integration Quality Scale

File: references/quality-scale.md

Quality tier requirements and best practices:

• Bronze: UI setup, basic tests, brand assets
• Silver: Reauth flow, error handling, availability
• Gold: Reconfigure flow, diagnostics, translations
• Platinum: Repairs, advanced features, comprehensive docs

Complete rule reference with paths to detailed documentation for each requirement.

When to consult:

• Planning integration features
• Preparing for HACS submission
• Improving integration reliability
• Understanding best practices
• Meeting quality requirements

Testing and Validation

File: references/testing-validation.md

Comprehensive testing guide:

• Test structure and fixtures
• Config flow testing
• Entity testing patterns
• Mocking best practices
• Test coverage requirements
• Type checking with mypy
• Code style (ruff, pylint)
• hassfest validation
• CI/CD setup

When to consult:

• Writing tests for your integration
• Achieving required test coverage
• Mocking external dependencies
• Running validation tools
• Setting up CI/CD
• Preparing for code review

HACS Publishing Guide

File: references/hacs-publishing.md

Complete HACS publishing process:

• General requirements
• hacs.json configuration
• Joining the default store
• GitHub Action validation
• Repository type requirements (integration, plugin, theme, etc.)
• Review pipeline
• Operations and lifecycle

When to consult:

• Publishing to HACS
• Understanding HACS requirements
• Configuring hacs.json
• Validating before submission
• Submitting to default store
• Maintaining published integrations

Complete Documentation Archive

All Home Assistant developer documentation is available in: assets/docs/

This includes:

• 290+ documentation files
• All 47 entity platform guides
• 53 quality scale rules
• API documentation (WebSocket, REST)
• Frontend development guides
• Add-on development
• Voice integration
• Testing frameworks
• And much more

Organization:

• core/entity/ - All entity platforms
• core/integration-quality-scale/rules/ - All quality rules
• api/ - WebSocket and REST APIs
• frontend/ - UI development
• Root level - Core development guides

Use the file paths provided in reference docs to access specific topics.

Common Patterns and Solutions

Data Coordinator Pattern

Use DataUpdateCoordinator for polling:

from homeassistant.helpers.update_coordinator import DataUpdateCoordinator, UpdateFailed

class MyCoordinator(DataUpdateCoordinator):
    """Coordinator for managing data updates."""
    
    def __init__(self, hass, entry):
        """Initialize coordinator."""
        super().__init__(
            hass,
            _LOGGER,
            name=DOMAIN,
            update_interval=timedelta(seconds=30),
        )
        self.api = MyAPI(entry.data["host"])
    
    async def _async_update_data(self):
        """Fetch data from API."""
        try:
            return await self.api.async_get_data()
        except ConnectionError as err:
            raise UpdateFailed(f"Error communicating with API: {err}")

Entity Naming Pattern (Gold Quality)

class MySensor(SensorEntity):
    _attr_has_entity_name = True
    _attr_name = "Temperature"  # Just the sensor function, not device name
    
    @property
    def device_info(self):
        return {
            "identifiers": {(DOMAIN, self._device_id)},
            "name": "My Smart Device",  # Device name here
            "manufacturer": "ACME Corp",
        }

Result: Entity named "My Smart Device Temperature"

Reauth Flow Pattern (Silver Quality)

# In your update method, detect auth failure
if response.status == 401:
    entry.async_start_reauth(hass)
    return

# In config_flow.py
async def async_step_reauth(self, user_input=None):
    """Handle reauth flow."""
    entry = self.hass.config_entries.async_get_entry(self.context["entry_id"])
    
    if user_input is not None:
        # Validate new credentials
        try:
            await self._test_credentials(user_input["password"])
        except InvalidAuth:
            return self.async_show_form(
                step_id="reauth_confirm",
                errors={"base": "invalid_auth"},
            )
        
        # Update entry with new credentials
        self.hass.config_entries.async_update_entry(
            entry,
            data={**entry.data, **user_input},
        )
        await self.hass.config_entries.async_reload(entry.entry_id)
        return self.async_abort(reason="reauth_successful")
    
    return self.async_show_form(
        step_id="reauth_confirm",
        data_schema=vol.Schema({vol.Required("password"): str}),
    )

Diagnostics Pattern (Gold Quality)

# In your integration's __init__.py
async def async_get_config_entry_diagnostics(hass, entry):
    """Return diagnostics for a config entry."""
    coordinator = hass.data[DOMAIN][entry.entry_id]
    
    return {
        "entry_data": dict(entry.data),
        "device_info": {
            "model": coordinator.device.model,
            "firmware": coordinator.device.firmware_version,
        },
        "api_data": coordinator.data,
        "last_update": coordinator.last_update_success,
    }

Tips and Best Practices

1. Always use config flows - YAML configuration is deprecated for new integrations
2. Set unique_id early - First thing in config flow to prevent duplicates
3. Use DataUpdateCoordinator - Don't poll in individual entities
4. Implement proper error handling - Raise ConfigEntryNotReady for temporary issues
5. Make entities unavailable - Set available = False when device offline (Silver quality)
6. Add entity translations - Use strings.json for professional quality (Gold)
7. Write comprehensive tests - Config flow tests are mandatory for Bronze
8. Follow entity naming - Use has_entity_name = True pattern (Gold quality)
9. Provide device_info - Link entities to devices in registry
10. Document thoroughly - Good docs are required for all quality tiers

Development Checklist

Before publishing:

• Config flow implemented and tested
• All entity platforms working
• Proper error handling (ConfigEntryNotReady, ConfigEntryAuthFailed)
• Entities report unavailable state when offline
• Unique IDs set for all entities
• Device info provided
• manifest.json complete with version
• Tests written with good coverage
• Documentation complete
• hassfest validation passes
• hacs.json created
• GitHub repository with releases
• HACS validation passes

Support and Resources

Official Documentation: https://developers.home-assistant.io/ HACS Documentation: https://hacs.xyz/ Discord: Join #developers channel Forum: https://community.home-assistant.io/

Skill Maintenance

This skill contains documentation current as of December 2024. Home Assistant releases monthly updates, so check for:

• New entity platforms or features
• Updated quality scale requirements
• Changes to config flow patterns
• New HACS requirements

The complete documentation archive in assets/docs/ can be consulted for any topic.