How to Integrate Home Assistant with HomeKit

Overview

Home Assistant and Apple HomeKit work together seamlessly through a bi-directional integration that combines Home Assistant’s powerful automation capabilities with HomeKit’s family-friendly interface. This guide shows you how to set up and leverage both platforms effectively.

Before you begin

Make sure to have these prerequisites in place:

• Home Assistant installed and running
• iOS device with the Home app
• Network that supports mDNS/Bonjour traffic
• Admin access to both Home Assistant and Apple Home

This guide will help you set up this bi-directional integration:

Two Integration Methods

HomeKit Controller: Import HomeKit Devices to Home Assistant

Allows Home Assistant to discover and control existing HomeKit-compatible devices on your network.

Use when: You have native HomeKit devices and want to control them from Home Assistant while keeping them in Apple Home.

HomeKit Bridge: Expose Home Assistant Devices to Apple Home

Makes Home Assistant act as a HomeKit bridge, exposing non-HomeKit devices to Apple Home.

Use when: You have devices connected to Home Assistant that you want to control through Apple Home and Siri.

Recommended Setup: Home Assistant as Primary Hub

The most powerful configuration uses Home Assistant as your primary hub, connecting your HomeKit devices through the HomeKit Controller integration, then exposing them back to Apple Home via the HomeKit Bridge. This approach offers:

• Unified Device Management: All HomeKit devices connect to Home Assistant
• Complex Automations: Leverage Home Assistant’s advanced automation engine
• Maintain Apple Home Compatibility: Keep using Apple Home alongside Home Assistant
• Family-Friendly Interface: Apple Home remains simple for family members
• Voice Control: Full Siri integration for all devices

How It Works

1. HomeKit devices connect to Home Assistant via HomeKit Controller integration
2. Home Assistant’s HomeKit Bridge creates a virtual bridge
3. Apple Home discovers the bridge and adds your devices
4. Devices appear in Apple Home as native HomeKit accessories
5. All Apple Home features work normally (Siri, automations, scenes)

Migration Guide: Moving Devices from Apple Home to Home Assistant

Step 1: Document Your Current Setup

1. Open the Home app on your iPhone or iPad
2. For each device you plan to migrate:
   • Take screenshots of the device settings
   • Document all automations involving the device
   • Note which rooms and zones the device belongs to
   • Record any custom names you’ve assigned

Example: Smart Lock in HomeKit

• Device name: “Main Door”
• Room: Front Porch
• Automations:
  • “When Main Door Unlocks, Turn On Lights in Front Porch”
  • “When Main Door Unlocks, Turn On 2 Lights in Living Room” (only at night, turn off after 5 minutes)
  • “When The Last Person Leaves Home, Lock” (only at night)

Step 2: Remove Device from Apple Home

1. Open the Home app
2. Long-press on the device tile
3. Scroll to the bottom and tap “Remove Accessory”
4. Confirm the removal

Step 3: Configure HomeKit Bridge in Home Assistant

1. Add the HomeKit integration to Home Assistant:

   

   

   

2. The bridge device has been created, select the Area where your Home Assistant is installed:

   

   

Your HomeKit bridge is now ready to be added to your Apple Home app. To do so, go to your Home Assistant notifications (bottom left corner in the Desktop app and web UI), you will find a QR Code to scan in Apple Home:

Step 4: Add Device to Home Assistant

1. In Home Assistant, you should now see HomeKit devices, and especially the one you removed at the step 2:

   

2. Pair the device in Home Assistant, using the device pairing code (find this code on the device itself):

   

3. The device is now configured in Home Assistant, ready to be added again in Apple Home (through the HomeKit Bridge):

   

4. A new QR Code has been generated for the device in the notifications:

   

Step 5: Add to Apple Home

1. Open the Home app
2. Tap the “+” icon and select “Add Accessory”
3. Scan the QR code displayed in Home Assistant at the end of Step 4
4. Your devices will now appear in Apple Home

Step 6: Recreate Automations

Choose where to create each automation based on complexity and who needs to manage it. Use the decision guide below to help decide.

Best Practices

Choosing Where to Create Automations

Use Apple Home for:

• Simple time-based or presence-based automations
• Voice-activated scenes and shortcuts
• Automations family members need to modify
• Quick setups without complex conditions

Use Home Assistant for:

• Multiple conditions and triggers
• Variables, templates, and scripts
• Advanced timing and delays
• Integration with non-HomeKit services
• Conditional branching logic

Organization Tips

• Naming: Keep consistent device and automation names across both platforms
• Rooms: Use Home Assistant Areas that match Apple Home Rooms
• Documentation: Maintain a list of which automations exist in each platform
• Backups: Regularly backup your Home Assistant configuration
• Testing: Test all automations after migration before relying on them

Troubleshooting

Devices Not Appearing in Apple Home

1. Verify the HomeKit integration is properly configured in Home Assistant
2. Check that entities are included in the filter section of your HomeKit config
3. Ensure your network allows mDNS/Bonjour traffic between devices
4. Restart both Home Assistant and the Home app

Pairing Failures

1. Remove the HomeKit integration from both Home Assistant and Apple Home
2. Check for port conflicts (HomeKit uses port 51827 by default)
3. Ensure Home Assistant has a static IP address on your network
4. Re-add the HomeKit integration and try pairing again

Automations Not Working After Migration

1. Verify device entity names match in your automations
2. Check that all conditions and triggers are properly recreated
3. Ensure time zones are correctly configured in both systems
4. Test automations individually to isolate issues

Conclusion

Integrating Home Assistant with HomeKit creates a powerful smart home system that combines advanced automation capabilities with a family-friendly interface. While migration requires careful planning, the result is a flexible setup where power users get full control and family members enjoy the simplicity of Apple Home.

Key Takeaways:

• Document your existing setup before making any changes
• Use Home Assistant as your primary hub for maximum flexibility
• Choose the right platform for each automation based on complexity
• Migrate devices gradually to minimize disruption

Additional Resources

Integration Documentation

• HomeKit Controller - Import HomeKit devices to Home Assistant
• HomeKit Bridge - Expose devices to Apple Home
• Entity Filtering - Control which devices appear in Apple Home

Home Assistant Guides

• Getting Started
• Automation Basics
• Areas and Zones
• Backups