Skip to content

rednblkx/HAP-ESPHome

BranchesTags

Repository files navigation

HAP-ESPHome CI C# Discord

HomeKit support for ESPHome-based ESP32 devices

1. Introduction

This project aims to bring HomeKit support to ESP32 devices flashed with an ESPHome configuration that will enable you to directly control the device from the Apple Home app without anything else inbetween.

Components can be imported like any other external compoents as follows:

external_components:
  source: github:https://rednblkx/HAP-ESPHome@main
  refresh: 0s

See Components for documentation.

Important

Some components like Bluetooth for example, take up a lot of space in RAM and will result in error during compiling, something like section '.iram0.text' will not fit in region 'iram0_0_seg' will be present in the log.

Supported entity types

Type Attributes Notes
Light On/Off, Brightness, RGB, Color Temperature
Lock Lock/Unlock Homekey can be enabled but only the pn532_spi component is supported to be used with it
Switch On/Off
Sensor Temperature, Humidity, Illuminance, Air Quality, CO2, CO, PM10, PM2.5 device_class property has to be declared with the sensor type as per HASS docs

2. Essentials

The underlying esp-homekit-sdk library and the components were designed to be used with ESP-IDF 5.

See below required configuration which needs to be present at all times.

esp32:
  board: <insert board id>
  framework:
    type: esp-idf
    version: 5.2.1
    platform_version: 6.7.0
    sdkconfig_options:
      CONFIG_COMPILER_OPTIMIZATION_SIZE: y
      CONFIG_LWIP_MAX_SOCKETS: "16"
      CONFIG_MBEDTLS_HKDF_C: y

3. Components

Project is divided into two different components, homekit_base which handles the bridge logic and homekit that handles the actual accessory logic (lights, switches, etc.).

This repository also includes the pn532 and pn532_spi components which are just slightly modified versions of the official ones from the ESPHome repository to suit HomeKey needs with no extra options added to them nor deleted, however, it's not guaranteed to be kept up to date with upstream changes.

3.1. homekit_base

Note

The homekit_base component does not have to included in the configuration unless you are interested in one of the properties listed below as it is automatically loaded by the homekit component

3.1.1. Configuration variables:

  • port (Optional, int): The port HomeKit should listen to
  • meta (Optional): Bridge information
    • name (Optional, string): Name of the bridge accessory
    • model (Optional, string): Model name for the bridge accessory
    • manufacturer (Optional, string): Manufacturer name for the bridge accessory
    • serial_number (Optional, string): Serial number for the bridge accessory
    • fw_rev (Optional, string): Firmware revision for the bridge accessory
  • setup_code (Optional, string): The HomeKit setup code in the format XXX-XX-XXX - Default: 159-35-728
  • setup_id (Optional, string): The Setup ID that can be used to generate a pairing QR Code - Default: ES32

Configuration Example:

homekit_base:
  meta:
    name: "PRIMO"
    manufacturer: "AMICI&CO"
    model: "IMPERIUM"
    serial_number: "16161616"
    fw_rev: "0.16.2"
  setup_code: '159-35-728'
  setup_id: "ES32"

3.1.2. Factory reset

homekit_base can also be used as a platform component for the button component to reset the HomeKit pairings, see example below:

button:
- platform: homekit_base
  factory_reset:
    name: "Reset HomeKit pairings"

This will function like any regular button in ESPHome and therefore will be visible in the Web Interface and HASS.

3.2. homekit

This is what handles the accessory logic like syncing states between HomeKit and ESPHome and basic information (name, attributes, etc.).