Home Assistant Integration

Connect your HomeKit devices to Home Assistant for unified smart home control, automations, and dashboards. Works with both Community Edition and Cloud.

Overview

The Homecast integration for Home Assistant exposes your HomeKit devices as native Home Assistant entities. Lights become HA lights, thermostats become HA climate entities, locks become HA locks, and so on.

Home Assistant ──REST/WebSocket──► Homecast (Cloud or Community) ──► Relay ──► HomeKit Devices

This means you can:

• Control HomeKit devices from HA dashboards and the HA mobile app
• Include HomeKit devices in HA automations (e.g., turn on lights when motion is detected)
• Use voice assistants like Google Assistant or Alexa through HA to control HomeKit devices
• Combine ecosystems — mix HomeKit devices with Zigbee, Z-Wave, and other HA integrations

Prerequisites

• A Homecast account with an active relay (Mac or iOS app connected)
• Home Assistant 2024.1.0 or newer
• HACS (Home Assistant Community Store)

Installation

1. Install via HACS

1. Open HACS in your Home Assistant sidebar
2. Go to Integrations > click the three-dot menu > Custom repositories
3. Paste: https://github.com/parob/homecast-hass
4. Select Integration as the category, then click Add
5. Search for Homecast and click Download
6. Restart Home Assistant

2. Add the integration

1. Go to Settings > Devices & Services > Add Integration
2. Search for Homecast
3. Choose Homecast Cloud or Homecast Community (local server)
4. You'll be redirected to the Homecast login and OAuth consent screen
5. Select which homes to share and whether to grant view or control access
6. Confirm — your devices will appear in Home Assistant within seconds

No manual OAuth setup needed

The integration automatically registers itself with Homecast's OAuth server. You don't need to create an OAuth client or copy credentials.

Official Home Assistant integration — coming soon

We're working toward an official integration built into Home Assistant Core. In the meantime, the HACS version above is the recommended install path and has the full feature set.

Supported devices

HomeKit Device	HA Entity	What you can control
Lightbulb	Light	On/off, brightness, color, color temperature
Switch / Outlet	Switch	On/off
Thermostat / Heater-Cooler	Climate	HVAC mode, temperature targets
Lock	Lock	Lock / unlock
Window Covering	Cover	Position, open/close
Fan	Fan	On/off, speed
Security System	Alarm Control Panel	Arm/disarm modes
Motion Sensor	Binary Sensor	Motion detected
Contact Sensor	Binary Sensor	Open/closed
Temperature Sensor	Sensor	Temperature reading
Light Sensor	Sensor	Illuminance

Devices with batteries automatically get battery level and low battery entities.

How it works

The integration uses Homecast's REST API and WebSocket under the hood:

• WebSocket push delivers real-time state updates — when a device changes (from the Apple Home app, Siri, or anywhere else), Home Assistant is notified in under a second
• POST /rest/state sends control commands when you interact with devices in HA
• GET /rest/state runs every five minutes as a safety-net resync in case any events are missed
• OAuth 2.1 with PKCE handles authentication and token refresh

Devices are automatically organized by their HomeKit room names using Home Assistant's area feature.

Example automations

Turn on lights at sunset

automation:
  - alias: "Sunset lights"
    trigger:
      - platform: sun
        event: sunset
    action:
      - service: light.turn_on
        target:
          entity_id: light.living_room_lamp
        data:
          brightness_pct: 60
          color_temp_kelvin: 3000

Lock all doors at bedtime

automation:
  - alias: "Bedtime locks"
    trigger:
      - platform: time
        at: "23:00:00"
    action:
      - service: lock.lock
        target:
          entity_id:
            - lock.front_door
            - lock.back_door

Troubleshooting

Devices not showing up

• Verify your relay is online in the Homecast dashboard
• Check that the OAuth consent granted access to the correct homes
• Restart Home Assistant after installation

Re-authentication

If your token expires, Home Assistant will show a notification. Go to Settings > Devices & Services > Homecast and follow the re-auth prompt.

Alternative: MQTT

Homecast supports Home Assistant MQTT auto-discovery. Devices appear automatically in HA when you connect your MQTT broker.

Cloud plan: Enable the Homecast Broker in Settings → Homes → [Home]. In HA, add the MQTT integration pointing to mqtt.homecast.cloud:8883 with your API access token as the password. Devices auto-discover.

Community Edition: Configure your local broker (e.g., Mosquitto) in the Mac app settings. The app publishes HA discovery configs to homeassistant/ topics automatically.

Topic structure and connection details: MQTT. Browse live data at mqtt.homecast.cloud.

Source code

The integration is open source: github.com/parob/homecast-hass