How to add ESPHome Devices to Apple HomeKit

• Very simple and requires little effort and time.
• User-friendly.
• Premium service.
• It has more than 200 devices enabling them to plug in.
• Offers seamless integration.

1. Go to the AddToHomeKit website.
2. Select the ESPHome ecosystem.
3. Choose the preferred solution.
4. Select the operating system.
5. Install the HomeBridge plugins.
6. Select the activation package.
7. Follow on-screen instructions.

1. Install HomeBridge on Mac / PC
2. Edit the configuration file

To use add ESPHome plugin to your HomeBridge config.json using the below command:

{
    "name": "ESPHome",
    "username": "your-esphome-email",
    "password": "your-esphome-password",
    "platform": "ESPHome"
}



3. Run the ESPHome Plugin
4. Control devices on HomeKit

1. Install HOOBS on a Raspberry Pi or any other suitable hardware.
2. Visit the HOOBS dashboard.
3. Go to the Home App.
4. Select "Add Accessory".
5. Select the HOOBS server.
6. Scan the QR code displayed on-screen.
7. Finally, follow the on-screen instructions.

1. Installing the ESPHome dashboard

First the ESPHome dashboard must be installed as a Home Assistant add-on. You can find it in the add-on's repository in the admin panel. After that, you have to wait until it is installed. Then click "Start" and click "Open Web UI".



2. Create the configuration

You will need to name your configuration and enter your wireless network settings so that the ESP device can come online and communicate with Home Assistant.




3. Dashboard Interface

On the home page you will see all the configurations for the nodes you have created. For each file, there are a few basic actions you can perform:

• Update
• Edit
• LOGS
• Overflow menu
4. Connecting your device to Home Assistant

Once your configuration is installed on your ESP device and online, it will be automatically detected by Home Assistant.




Click on the “Add Integration” button (bottom right), search for esphome, and enter the host name. local” as the host. Use the same process to add multiple esphome devices.




After the first installation, all features of ESPHome are enabled remotely, so there's no need to use a USB cable ever again.

• Switchbot 5 Channel ESP32-C3 Bulb
• Vont 5 Channel Smart ESP32-C3 Bulb
• Vont 4 Channel Smart ESP32-C3 Bulb
• CloudFree 5 Channel Bulb
• Kauf 5 Channel BR30
• Kauf 5 Channel A21 - Kauf A19 - Kauf A15

• Martin Jerry Single Pole Switch TASMOTA Pre-Flashed or Flashable Switch
• Martin Jerry 3 Way Switch TASMOTA Pre-Flashed (Secondary TuyaMCU unfortunately)
• Milfra Single Pole Motion Switch
• Milfra Dual Button Motion Switch
• Kauf Pre-Flashed LED Panel Switch

• Martin Jerry Single Pole Dimmer
• Hamilton Hills Touch Dimmer

• Martin Jerry Preflashed TASMOTA Fan Controller

• Switchbot 15A ESP32-C3 Plug
• Sonoff S31
• Kauf Plug
• Wyze Dual Relay Outdoor ESP32 Plug WLPPO1
• GHome 6 Plug Outlet Extender
• Xuntiy 4 Plug Power Strip
• AHRISE 6 Outlet Extender
• POWRUI 3 Outlet Extender

• Athom Sound Reactive Pre-Flashed WLED Controller
• Electrodragon LED Controller (get the ESP32-C3 version!)

• Shelly 1
• Shelly Plus 1
• Shelly Plus 2PM
• Shelly Plus i4

General Troubleshooting Tips



1. Device Not Showing in HomeKit
• Check HomeKit Compatibility: Ensure that your ESPHome device is properly configured to work with HomeKit. You should have the `homekit` component enabled in your ESPHome YAML configuration.
• Network Connection: Make sure both your iPhone/iPad and the ESPHome device are connected to the same Wi-Fi network. HomeKit needs local network communication.
• Reset HomeKit Setup: If you’re having issues, try resetting the HomeKit pairing. In the Home app, remove the device and then re-pair it by scanning the HomeKit code again.
• Reboot Devices: Power cycle your router, iPhone, and ESPHome device. A simple reboot can often fix communication issues.
• HomeKit Update: Ensure that both your HomeKit setup and ESPHome device firmware are up to date. Update ESPHome firmware through the ESPHome web interface or using the `esphome` command line tool.


2. Device Not Responding in HomeKit
• Check HomeKit Hub: Ensure that your HomePod, Apple TV, or iPad (acting as the HomeKit hub) is connected and functional.
• Re-pair Device: Remove the device from HomeKit and try re-pairing it again by scanning the HomeKit QR code. A fresh pairing might resolve connection issues.
• Check Firmware and Configuration: Ensure the ESPHome device has the correct firmware and that the HomeKit component in the YAML configuration file is correctly set up.


3. Poor Device Performance or Lag
• Check Wi-Fi Signal Strength: Poor performance can occur if your ESPHome device is far from the router. Ensure it is within range or add a Wi-Fi extender if necessary.
• Network Traffic: Ensure your Wi-Fi network has enough bandwidth. Too many devices or heavy network traffic can slow down communication with HomeKit.
• Reduce Device Load: If your ESPHome device is running multiple tasks, try disabling unnecessary components to reduce the load and improve performance.

HOOBS Troubleshooting

1. ESPHome Device Not Appearing in HOOBS
• Check HOOBS Plugin: Ensure the **ESPHome plugin** is installed and properly configured in the HOOBS interface.
• Reboot HOOBS: Try restarting HOOBS from the web interface to refresh device connections.
• API Access: Ensure that your ESPHome device’s API credentials are correctly entered in the HOOBS configuration. Incorrect credentials can prevent communication.


2. Device Not Streaming or Displaying Data in HOOBS
• Network Settings: Ensure that both HOOBS and the ESPHome device are on the same network. If they are on different networks or subnets, they won’t be able to communicate properly.
• HOOBS Plugin Settings: Double-check the settings for your ESPHome device in HOOBS. You may need to adjust certain parameters or tweak the configuration within the plugin.


3. Authentication Issues with ESPHome Device in HOOBS
• Reauthorize ESPHome Account: Ensure that your ESPHome device has the proper API credentials configured in HOOBS. Re-authorizing might help if you’re facing issues.
• Check for Plugin Updates: Ensure the ESPHome plugin for HOOBS is up to date. Developers often release patches for compatibility fixes.
• Manual Pairing: If automatic setup fails, try using manual pairing through HomeKit to resolve the authentication issue.

HomeBridge Troubleshooting Tips

1. ESPHome Device Not Appearing in HomeBridge
• HomeBridge Plugin Configuration: Ensure the HomeBridge ESPHome plugin is correctly configured. Double-check your HomeBridge `config.json` file for any syntax errors or missing parameters.
• Reboot HomeBridge: Sometimes restarting HomeBridge can resolve device connection issues. Run sudo systemctl restart homebridge in your terminal to restart the server.
• Check Dependencies: Ensure that all required dependencies for the HomeBridge ESPHome plugin are installed. If any are missing, reinstall them using npm (Node Package Manager).


2. Data Not Updating in HomeKit (via HomeBridge)
• Reconfigure Settings: Check the HomeBridge configuration file for settings that might affect data refresh or communication. Some parameters might need to be manually adjusted.
• Network Issues: Ensure that both the HomeBridge server and the ESPHome device are on the same Wi-Fi network and that the network has enough bandwidth for smooth communication.


3. Device Fails to Respond in HomeKit (via HomeBridge)
• Plugin Reinstallation: If the device isn’t responding in HomeKit, try uninstalling and reinstalling the ESPHome plugin in HomeBridge.
• Device Power Cycle: Sometimes a power cycle of both the ESPHome device and HomeBridge server is necessary to reestablish the connection.
• Update HomeBridge & Plugin: Ensure both HomeBridge and the ESPHome plugin are updated to the latest versions to avoid compatibility issues.