Smart Home Integrations

Integrate your smart home with Homarr to monitor sensors, control devices, trigger automations, and display calendar events from Home Assistant.

Home Assistant

Home Assistant is the leading open-source home automation platform. The Homarr integration provides real-time entity monitoring and control capabilities.

Configuration

url

string

required

Base URL of your Home Assistant instance (e.g., http://homeassistant.local:8123)

apiKey

string

required

Long-lived access token from Home Assistant

Generating a Long-Lived Access Token

Open Profile

Click your username in the bottom-left corner of Home Assistant

Scroll to Tokens

Scroll down to the Long-Lived Access Tokens section

Create Token

Click Create Token

Name Your Token

Enter “Homarr” as the token name

Copy Token

Important: Copy the token immediately - it’s only shown once!

Long-lived access tokens are sensitive credentials. Store them securely and never share them publicly.

Available Features

Entity State Monitoring

Retrieve real-time state information for any Home Assistant entity.

Supported Entity Types

The integration works with all Home Assistant entities:

Sensors: Temperature, humidity, power consumption
Switches: Toggle smart plugs and switches
Lights: Control brightness and colors
Climate: Monitor thermostats and HVAC
Locks: Check lock status
Covers: Control blinds and garage doors
Binary Sensors: Motion, door/window contacts
Cameras: View camera feeds
Media Players: Control playback
And many more…

API Method: getEntityStateAsync(entityId)

Entity State Response

{
  success: true,
  data: {
    entity_id: "sensor.living_room_temperature",
    state: "21.5",
    attributes: {
      unit_of_measurement: "°C",
      friendly_name: "Living Room Temperature",
      device_class: "temperature"
      // ... additional attributes
    },
    last_changed: "2024-03-06T10:30:00Z",
    last_updated: "2024-03-06T10:30:00Z"
  }
}

Returns { success: false, error: "..." } on failure.

Automation Control

Trigger Home Assistant automations directly from Homarr.

Trigger Automation

Execute any automation by entity ID:

await integration.triggerAutomationAsync('automation.morning_routine');

Use Cases:

Manual trigger for scheduled automations
Create buttons in Homarr to run scenes
Integrate with Homarr’s own automation system
Dashboard shortcuts for common tasks

API Method: triggerAutomationAsync(entityId)

Return Value

Returns boolean:

true: Automation triggered successfully
false: Failed to trigger (check logs)

The method handles errors gracefully and logs issues for debugging.

Toggle Control

Toggle any compatible Home Assistant entity.

Toggle Entity

Toggle lights, switches, and other controllable entities:

await integration.triggerToggleAsync('light.living_room');
await integration.triggerToggleAsync('switch.coffee_maker');

Behavior:

If entity is on, it will turn off
If entity is off, it will turn on
Works with any entity supporting toggle service

API Method: triggerToggleAsync(entityId)

Supported Entities

Toggle works with:

Lights
Switches
Input booleans
Automations (enable/disable)
Scripts
Media players (play/pause)
Fans
And more…

Calendar Integration

Display Home Assistant calendar events in Homarr.

Calendar Events

Fetch events from all Home Assistant calendars:

Personal calendars
Shared family calendars
Event calendars (sports, holidays)
Maintenance schedules
Trash/recycling collection
School events

Widget: Calendar Widget with Home Assistant integrationAPI Method: getCalendarEventsAsync(start, end)

Event Properties

{
  title: "Event Title",
  subTitle: null,
  description: "Event description from calendar",
  startDate: Date,  // Auto-normalized for all-day events
  endDate: Date,
  image: null,
  indicatorColor: "#18bcf2",  // Home Assistant blue
  location: "Event location",
  links: []
}

All-Day Events: Automatically normalized to midnight (00:00) to display correctly in UTC.

Example Configuration

{
  "name": "Home Assistant",
  "url": "http://192.168.1.100:8123",
  "secrets": {
    "apiKey": "your-long-lived-access-token-here"
  }
}

Usage Examples

Create a custom widget displaying multiple entities:

Temperature Sensors
Control Panel
Scene Buttons

// Display multiple room temperatures
const rooms = [
  'sensor.living_room_temperature',
  'sensor.bedroom_temperature',
  'sensor.kitchen_temperature'
];

for (const entityId of rooms) {
  const state = await ha.getEntityStateAsync(entityId);
  if (state.success) {
    console.log(`${state.data.attributes.friendly_name}: ${state.data.state}°C`);
  }
}

// Create a control panel for lights
const lights = [
  'light.living_room',
  'light.bedroom',
  'light.kitchen'
];

// Toggle all lights
for (const light of lights) {
  await ha.triggerToggleAsync(light);
}

// Trigger scenes via automations
const scenes = {
  'Movie Time': 'automation.movie_scene',
  'Good Night': 'automation.goodnight_routine',
  'Wake Up': 'automation.morning_routine'
};

// Trigger movie scene
await ha.triggerAutomationAsync(scenes['Movie Time']);

Entity ID Format

Home Assistant entity IDs follow the format: domain.object_id Examples:

sensor.living_room_temperature - Temperature sensor
light.bedroom_ceiling - Bedroom ceiling light
switch.coffee_maker - Coffee maker switch
automation.morning_routine - Morning automation
binary_sensor.front_door - Front door contact sensor
climate.thermostat - Thermostat device

Find entity IDs in Home Assistant under Developer Tools → States

Authentication & Security

API Endpoints

The integration uses these Home Assistant API endpoints:

GET /api/config - Test connection
GET /api/states/{entity_id} - Get entity state
POST /api/services/automation/trigger - Trigger automation
POST /api/services/homeassistant/toggle - Toggle entity
GET /api/calendars - List calendars
GET /api/calendars/{entity_id} - Get calendar events

Authorization Header

All requests include:

Authorization: Bearer your-long-lived-access-token

Token Security

Security Best Practices:

Never commit tokens to version control
Use environment variables in Homarr config
Regenerate tokens if compromised
Create separate tokens for different services
Monitor token usage in Home Assistant logs

Add Calendar Widget

Edit Mode → Add Widget → Calendar

Select Home Assistant

Choose your Home Assistant integration

Configure Display

Set date range (1 week, 2 weeks, month)
Choose view mode (list, grid, timeline)
Enable/disable event descriptions

Save Widget

Your Home Assistant calendar events now appear in Homarr

Calendar Features

All-Day Events: Properly formatted and displayed
Multi-Calendar: Combines all HA calendars into one view
Location Display: Shows event location if available
Color Coding: Uses Home Assistant’s signature blue
Auto-Refresh: Updates based on widget refresh interval

Troubleshooting

Connection Failed

Symptoms: “Unable to connect” or “Connection refused” Solutions:

Verify Home Assistant is running and accessible
Check URL includes protocol (http:// or https://)
Ensure port is correct (default: 8123)
Test URL in browser first
Check firewall allows connections from Homarr

Unauthorized Error

Symptoms: “401 Unauthorized” or “Authentication failed” Solutions:

Verify token is copied correctly (no extra spaces)
Check token hasn’t expired or been deleted
Create a new long-lived access token
Ensure token has necessary permissions
Check Home Assistant logs for auth failures

Entity Not Found

Symptoms: “Entity not found” or empty response Solutions:

Verify entity ID is correct (check Developer Tools → States)
Ensure entity exists and is enabled
Check entity hasn’t been renamed
Try refreshing Home Assistant configuration

Automation Not Triggering

Symptoms: Automation doesn’t run when triggered from Homarr Solutions:

Verify automation is enabled in Home Assistant
Check automation entity ID is correct
Review automation conditions (may be blocking trigger)
Check Home Assistant logs for errors
Test automation manually in HA first

Calendar Events Missing

Symptoms: Calendar widget shows no events Solutions:

Verify calendars are configured in Home Assistant
Check date range includes events
Ensure calendar integration is loaded in HA
Test API endpoint directly: /api/calendars
Review Homarr logs for parsing errors

Advanced Usage

Custom Entity Widgets

Create custom widgets that poll specific entities:

// Example: Energy monitoring widget
setInterval(async () => {
  const power = await ha.getEntityStateAsync('sensor.total_power');
  const cost = await ha.getEntityStateAsync('sensor.energy_cost');
  
  if (power.success && cost.success) {
    updateWidget({
      power: `${power.data.state} W`,
      cost: `$${cost.data.state}`
    });
  }
}, 5000); // Update every 5 seconds

Automation Integration

Use Homarr conditions to trigger HA automations:

# Homarr automation example
triggers:
  - type: schedule
    cron: "0 7 * * *"  # Every day at 7 AM

actions:
  - type: integration
    integration: home_assistant
    action: triggerAutomation
    entityId: automation.morning_routine

Multi-Entity Status

Monitor multiple entities and aggregate status:

async function getHomeStatus() {
  const entities = [
    'binary_sensor.front_door',
    'binary_sensor.back_door',
    'binary_sensor.garage_door'
  ];

  const states = await Promise.all(
    entities.map(id => ha.getEntityStateAsync(id))
  );

  const anyOpen = states.some(s => 
    s.success && s.data.state === 'on'
  );

  return anyOpen ? '🔓 Door Open' : '🔒 Secure';
}

Supported Entity Domains

The integration supports all Home Assistant domains:

Domain	Description	Toggle Support
`sensor`	Read-only sensors	❌
`binary_sensor`	On/off sensors	❌
`switch`	Controllable switches	✅
`light`	Lights and bulbs	✅
`climate`	Thermostats	⚠️ (Limited)
`lock`	Smart locks	⚠️ (Use lock/unlock)
`cover`	Blinds, garage doors	⚠️ (Use open/close)
`fan`	Fans	✅
`media_player`	Media devices	✅
`automation`	Automations	✅ (Enable/disable)
`script`	Scripts	✅
`input_boolean`	Input helpers	✅
`scene`	Scenes	✅

⚠️ = Works with toggle but may have unexpected behavior. Use specific service calls instead.

Next Steps

Create Widgets

Build custom smart home dashboard widgets

Entity State Widget

Display Home Assistant entity states

Calendar Integration

View Home Assistant calendar events

Home Assistant Docs

Learn more about Home Assistant

Get Started

Core Features

Configuration

Integrations

Guides

​Home Assistant

​Configuration

​Generating a Long-Lived Access Token

​Available Features

​Entity State Monitoring

​Automation Control

​Toggle Control

​Calendar Integration

​Example Configuration

​Usage Examples

​Smart Home Dashboard Widget

​Entity ID Format

​Authentication & Security

​API Endpoints

​Authorization Header

​Token Security

​Calendar Widget Setup

​Calendar Features

​Troubleshooting

​Connection Failed

​Unauthorized Error

​Entity Not Found

​Automation Not Triggering

​Calendar Events Missing

​Advanced Usage

​Custom Entity Widgets

​Automation Integration

​Multi-Entity Status

​Supported Entity Domains

​Next Steps

Create Widgets

Entity State Widget

Calendar Integration

Home Assistant Docs

Build docs developers (and LLMs) love

Home Assistant

Configuration

Generating a Long-Lived Access Token

Available Features

Entity State Monitoring

Automation Control

Toggle Control

Calendar Integration

Example Configuration

Usage Examples

Smart Home Dashboard Widget

Entity ID Format

Authentication & Security

API Endpoints

Authorization Header

Token Security

Calendar Widget Setup

Calendar Features

Troubleshooting

Connection Failed

Unauthorized Error

Entity Not Found

Automation Not Triggering

Calendar Events Missing

Advanced Usage

Custom Entity Widgets

Automation Integration

Multi-Entity Status

Supported Entity Domains

Next Steps