HomeAssistant Development

Overview

This skill provides comprehensive guidance for HomeAssistant development across three core areas: custom sensors, dashboards (Lovelace UI), and custom integrations. Use this skill when creating or modifying HomeAssistant configurations, developing custom Python components, or building user interfaces.

When to Use This Skill

Activate this skill when:

• Creating or modifying sensors (template, REST, command line, or Python-based)
• Building or customizing Lovelace dashboards and cards
• Developing custom integrations with Python
• Working with HomeAssistant YAML configuration files
• Implementing automations that require custom sensors or components
• Setting up device integrations or API connections

Core Capabilities

1. Custom Sensors

Template Sensors

Use template sensors for calculations, unit conversions, or combining multiple sensor values. Templates use Jinja2 syntax and are defined in YAML configuration.

When to use:

• Converting units (e.g., Celsius to Fahrenheit)
• Combining multiple sensor values (e.g., total power consumption)
• Creating derived values (e.g., "feels like" temperature)
• Status indicators based on other entity states

Implementation approach:

1. Determine the source entities needed
2. Write the Jinja2 template with proper fallback values using

   | float(0)

   or

   | default()

3. Set appropriate

   device_class

   ,

   state_class

   , and

   unit_of_measurement

4. Add

   unique_id

   for UI customization capability
5. Test the template in Developer Tools → Template

Reference: See

references/sensors.md

for comprehensive template sensor examples and patterns.

RESTful Sensors

Use REST sensors to pull data from external APIs or web services.

When to use:

• Fetching data from external APIs
• Integrating web services without custom components
• Polling HTTP endpoints for status updates

Implementation approach:

1. Identify the API endpoint and authentication method
2. Configure the REST sensor with proper headers and authentication
3. Use

   value_template

   to extract the desired value from JSON responses
4. Use

   json_attributes

   or

   json_attributes_path

   for additional data
5. Set appropriate

   scan_interval

   to balance freshness and API limits

Reference: See

references/sensors.md

for REST sensor configuration patterns.

Command Line Sensors

Use command line sensors to execute shell commands and use their output as sensor values.

When to use:

• Reading system information not available through standard integrations
• Executing custom scripts or binaries
• Processing file contents or system resources

Reference: See

references/sensors.md

for command line sensor examples.

Python Custom Component Sensors

Use custom Python components when sensor logic is too complex for templates or requires external libraries.

When to use:

• Complex calculations or data processing
• Integration with Python libraries
• Stateful sensors that need to maintain data between updates
• Performance-critical operations

Implementation approach:

1. Create directory structure:

   custom_components/<domain>/

2. Start with the integration template in

   assets/integration_template/

3. Implement

   sensor.py

   with proper entity classes
4. Use

   DataUpdateCoordinator

   for efficient data fetching
5. Implement proper error handling and logging

Reference: See

references/sensors.md

for Python sensor implementation details.

2. Lovelace Dashboards

Create intuitive, responsive user interfaces using Lovelace cards and custom layouts.

Planning a Dashboard

Approach:

1. Identify the entities to display (lights, sensors, switches, etc.)
2. Group related entities by room or function
3. Choose appropriate card types for each entity type
4. Consider mobile vs desktop layout
5. Plan views (tabs) for different areas or purposes

Core Card Types

Entities Card - List multiple entities with controls:

• Best for control panels and grouped controls
• Supports sections, dividers, and custom icons
• Can show secondary information (last-changed, entity-id)

Button Card - Single entity with large tap target:

• Best for frequently-used controls
• Customizable icons and colors
• Supports tap, hold, and double-tap actions

Gauge Card - Visual representation of numeric values:

• Best for monitoring metrics (CPU, temperature, battery)
• Configure min/max and severity thresholds
• Visual feedback at a glance

Picture Elements Card - Interactive image with overlays:

• Best for floor plans or device diagrams
• Position controls and labels on images
• Create custom visual interfaces

Conditional Card - Show/hide based on conditions:

• Display cards only when relevant
• Reduce clutter by hiding inactive elements
• Stack multiple conditions for complex logic

Layout Strategies

Grid Layout - Responsive grid of cards:

• Automatically adjusts columns based on screen width
• Consistent sizing with

  square: false

  for flexible heights
• Best for collections of similar items

Vertical/Horizontal Stack - Group cards together:

• Stack cards to create logical groupings
• Combine with conditional cards for dynamic layouts
• Control card order and spacing

Custom Cards (HACS)

Install custom cards via HACS for enhanced functionality:

• Mini Graph Card - Compact sensor history graphs
• Button Card (Custom) - Advanced button customization
• Mushroom Cards - Modern, minimalist card designs
• ApexCharts Card - Powerful charting and graphing

Installation steps:

1. Install HACS if not already installed
2. Go to HACS → Frontend
3. Search for the desired card
4. Install and add resource reference
5. Use in dashboard with

   type: custom:<card-name>

Reference: See

references/dashboards.md

for comprehensive card examples, custom card configurations, and layout patterns.

3. Custom Integrations

Develop full-featured integrations with Python for complex device or service integrations.

When to Create a Custom Integration

• Integrating a device or service not supported by existing integrations
• Complex logic that can't be handled by REST sensors or templates
• Multiple related entities (sensors, switches, lights) from one source
• Need for device registry integration
• Requiring coordinator-based efficient data fetching

Integration Structure

Required files:

• manifest.json

  - Integration metadata, dependencies, and requirements

• __init__.py

  - Integration setup and platform loading

• config_flow.py

  - UI-based configuration (recommended)
• Platform files (

  sensor.py

  ,

  switch.py

  , etc.) - Entity implementations

Optional but recommended:

• coordinator.py

  - Centralized data fetching

• const.py

  - Constants and configuration keys

• strings.json

  - UI text and translations

Development Workflow

Step 1: Plan the Integration

• Identify the device/service API or protocol
• List the entity types needed (sensors, switches, lights, etc.)
• Determine authentication and connection requirements
• Plan data update strategy (polling vs push)

Step 2: Start with Template Copy the integration template from

assets/integration_template/

to

custom_components/<your_domain>/

:

cp -r assets/integration_template custom_components/my_device

Step 3: Customize Manifest Update

manifest.json

:

• Set unique

  domain

  (lowercase, underscores)
• Update

  name

  ,

  documentation

  ,

  codeowners

• Add Python package dependencies to

  requirements

• Set appropriate

  iot_class

  (local_polling, cloud_polling, etc.)

Step 4: Implement Config Flow In

config_flow.py

:

• Define configuration schema (host, port, API key, etc.)
• Implement connection validation in

  _test_connection

• Handle errors appropriately (cannot_connect, invalid_auth, etc.)
• Support discovery if applicable (SSDP, Zeroconf)

Step 5: Implement Coordinator In

coordinator.py

:

• Create API client or device communication class
• Implement

  _async_update_data

  to fetch device data
• Handle errors and raise

  UpdateFailed

  on failures
• Set appropriate

  update_interval

Step 6: Implement Platforms For each platform (sensor.py, switch.py, etc.):

• Create entity classes inheriting from

  CoordinatorEntity

  and platform base
• Set proper device classes, state classes, and units
• Implement

  native_value

  property to return current state
• Add

  DeviceInfo

  to group entities under one device
• Set

  unique_id

  for each entity

Step 7: Test and Iterate

• Copy to HomeAssistant's

  custom_components/

  directory
• Restart HomeAssistant
• Add integration via UI (Settings → Devices & Services)
• Monitor logs for errors
• Test all entity states and controls
• Verify device registry entry

Best Practices

Data Fetching:

• Always use

  DataUpdateCoordinator

  to centralize API calls
• This prevents multiple entities from making duplicate requests
• Coordinator automatically handles retries and error states

Error Handling:

• Use try/except blocks around all I/O operations
• Log errors with appropriate severity levels
• Raise

  UpdateFailed

  in coordinator when data fetch fails
• Return

  None

  or fallback values for unavailable data

Entity Design:

• Always set

  unique_id

  to enable UI customization
• Use appropriate

  device_class

  for proper icon and unit handling
• Set

  state_class

  for sensors that should appear in statistics
• Group related entities using

  DeviceInfo

Code Quality:

• Use type hints throughout (

  -> bool

  ,

  : str

  , etc.)
• Follow HomeAssistant code style (use pylint)
• Use async/await for all I/O operations
• Import only necessary modules

Configuration:

• Prefer

  config_flow.py

  over YAML configuration
• Validate user input before accepting
• Provide clear error messages
• Support reloading configuration when possible

Reference: See

references/integrations.md

for complete integration development guide with detailed code examples.

Resources

references/

Detailed documentation loaded into context as needed:

• sensors.md

  - Comprehensive sensor implementation guide covering all sensor types, device classes, state classes, and best practices

• dashboards.md

  - Complete Lovelace dashboard reference with card types, custom cards, layouts, and design patterns

• integrations.md

  - In-depth custom integration development guide with file structure, coordinator patterns, and platform implementation

When to read references:

• Read

  sensors.md

  when implementing any type of sensor
• Read

  dashboards.md

  when building or modifying dashboards
• Read

  integrations.md

  when developing custom Python integrations

assets/

Template files used in development output:

• integration_template/

  - Complete, working integration boilerplate with:

  • manifest.json

    - Integration metadata template

  • __init__.py

    - Integration setup with coordinator

  • config_flow.py

    - UI configuration flow

  • coordinator.py

    - Data update coordinator

  • sensor.py

    - Example sensor platform with multiple sensors

  • const.py

    - Constants file

  • strings.json

    - UI translations

  • README.md

    - Customization guide

When to use assets:

• Copy

  integration_template/

  as starting point for new integrations
• Customize the template by replacing "my_integration" with actual domain
• Follow the README.md for step-by-step customization instructions

Development Tips

Testing Templates

Use Developer Tools → Template in HomeAssistant to test Jinja2 templates before adding to configuration.

Checking Configuration

Run Configuration → Check Configuration before restarting HomeAssistant to catch YAML errors.

Viewing Logs

Monitor logs at Settings → System → Logs or via command line:

tail -f /config/home-assistant.log

Reloading Without Restart

Many components support reload without full restart:

• Developer Tools → YAML → Reload Template Entities
• Developer Tools → YAML → Reload Automations
• Developer Tools → YAML → Reload Scripts

Debugging Custom Integrations

Add debug logging to

configuration.yaml

:

logger:
  default: info
  logs:
    custom_components.my_integration: debug

Version Compatibility

Always check HomeAssistant version compatibility:

• Template syntax may change between versions
• Entity platform APIs evolve with releases
• Test integrations on target HomeAssistant version
• Review breaking changes in release notes