name: Home Assistant Integration knowledge description: Everything you need to know to build, test and review Home Assistant Integrations. If you're looking at an integration, you must use this as your primary reference.
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.mdfor diagnostic data collection - Repairs:
platform-repairs.mdfor user-actionable repair issues
Minimal Integration Checklist
-
manifest.jsonwith required fields (domain, name, codeowners, etc.) -
__init__.pywithasync_setup_entryandasync_unload_entry -
config_flow.pywith UI configuration support -
const.pywithDOMAINconstant -
strings.jsonwith at least config flow text - Platform files (
sensor.py, etc.) as needed -
quality_scale.yamlwith 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
- Check
manifest.json: Look for `