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 DevicesThis 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), or a Community Edition relay with its local server enabled
- Home Assistant 2026.4.0 or newer
- HACS (Home Assistant Community Store)
Installation
1. Install via HACS
- Open HACS in your Home Assistant sidebar
- Click the ⋮ menu in the top right corner and choose Custom repositories
- Enter
https://github.com/parob/homecast-hassas the repository and choose Integration as the type, then click Add - Search HACS for Homecast, open it and click Download
- Restart Home Assistant
2. Add the integration
- Go to Settings > Devices & Services > Add Integration
- Search for Homecast
- Choose Homecast Cloud or Homecast Community (local server)
- Cloud: you'll be redirected to the Homecast login and OAuth consent screen — select which homes to share and whether to grant view or control access. Community: enter your Homecast server URL (e.g.
http://your-mac.local:5656) - 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.
Coming to the HACS default store
Homecast has been submitted to the HACS default store. Once accepted, the custom-repository step above won't be needed — you'll find Homecast directly in HACS search.
Supported devices
| HomeKit Device | HA Entity | What you can control |
|---|---|---|
| Lightbulb | Light | On/off, brightness, color, color temperature |
| Switch / Outlet | Switch | On/off |
| Heater-Cooler (air conditioners, radiators, underfloor heating) | Climate | Off and the modes the unit supports, the setpoint for the current mode (a heat–cool range in auto), swing |
| Thermostat | Climate | The modes it supports, target temperature |
| Lock | Lock | Lock / unlock |
| Window Covering | Cover | Position, open/close |
| Fan | Fan | On/off, speed |
| Security System | Alarm Control Panel | Arm/disarm modes |
| Motion / Contact Sensor | Binary Sensor | Motion detected / open-closed |
| Occupancy, Leak, Smoke, CO Sensor | Binary Sensor | Detected / clear |
| Temperature / Light / Humidity reading | Sensor | Temperature, illuminance, humidity |
Battery-powered accessories also get battery level and battery-low entities, and an accessory with several sensors keeps all of its readings — a Hue motion sensor brings its temperature and light level along.
Not supported yet: garage doors, air purifiers, humidifiers, valves, speakers and TVs, cameras, and HomeKit scenes.
How it works
The integration uses Homecast's REST API and WebSocket under the hood:
- WebSocket push delivers state changes as they happen — when a device changes (from the Apple Home app, Siri, or anywhere else), Home Assistant is told straight away rather than waiting for a poll
POST /rest/statesends control commands when you interact with devices in HAGET /rest/stateruns 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: 3000Lock 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_doorTroubleshooting
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 also publishes device state to MQTT, which Home Assistant's MQTT integration can read.
Cloud plan: Turn on Homecast MQTT Broker in Settings → Homes → [Home] → MQTT (needs Developer Mode). In HA, add the MQTT integration pointing to mqtt.homecast.cloud:8883 with a blank username and your API access token as the password. The cloud broker does not publish Home Assistant discovery configs, so you define the MQTT entities you want yourself; the Homecast integration above is the simpler route.
Community Edition: Configure your local broker (e.g., Mosquitto) in the Mac app settings. With HA Auto-Discovery on, the app publishes discovery configs to homeassistant/ topics.
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