{"id":14985238,"url":"https://github.com/rednblkx/hap-esphome","last_synced_at":"2025-04-05T02:04:21.437Z","repository":{"id":243130574,"uuid":"811055198","full_name":"rednblkx/HAP-ESPHome","owner":"rednblkx","description":"Apple HomeKit for ESPHome","archived":false,"fork":false,"pushed_at":"2024-12-23T22:53:40.000Z","size":191,"stargazers_count":157,"open_issues_count":8,"forks_count":21,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-04-05T02:03:52.102Z","etag":null,"topics":["apple","esphome","home-automation","homeassistant","homekit"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rednblkx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"rednblkx"}},"created_at":"2024-06-05T21:15:38.000Z","updated_at":"2025-03-24T03:26:42.000Z","dependencies_parsed_at":"2024-07-09T17:59:14.915Z","dependency_job_id":"a3417f09-7433-4d22-b64c-9e0b057e6f90","html_url":"https://github.com/rednblkx/HAP-ESPHome","commit_stats":{"total_commits":71,"total_committers":1,"mean_commits":71.0,"dds":0.0,"last_synced_commit":"da4d1d6816ab5c03cebea827d1d387cd6edc83d4"},"previous_names":["rednblkx/hap-esphome"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHAP-ESPHome","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHAP-ESPHome/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHAP-ESPHome/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHAP-ESPHome/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rednblkx","download_url":"https://codeload.github.com/rednblkx/HAP-ESPHome/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276163,"owners_count":20912288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","esphome","home-automation","homeassistant","homekit"],"created_at":"2024-09-24T14:10:33.156Z","updated_at":"2025-04-05T02:04:21.407Z","avatar_url":"https://github.com/rednblkx.png","language":"C++","funding_links":["https://github.com/sponsors/rednblkx"],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"https://github.com/user-attachments/assets/9939edca-202c-4794-aff1-b6f3d7962eb0\" width=\"128\" height=\"128\"\u003e\n\n# HAP-ESPHome [![CI](https://github.com/rednblkx/HAP-ESPHome/actions/workflows/main.yml/badge.svg?branch=main)](https://github.com/rednblkx/HAP-ESPHome/actions/workflows/main.yml) [![C# Discord](https://badgen.net/discord/members/VWpZ5YyUcm?icon=discord)](https://discord.com/invite/VWpZ5YyUcm)\n\nHomeKit support for ESPHome-based ESP32 devices\n\n## 1. Introduction\n\nThis 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.\n\nComponents can be imported like any other external compoents as follows:\n\n```yaml\nexternal_components:\n  source: github://rednblkx/HAP-ESPHome@main\n  refresh: 0s\n```\n\nSee [Components](#3-components) for documentation.\n\n\u003e [!IMPORTANT]  \n\u003e 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.\n\n### Supported entity types\n\n| Type   | Attributes                                                            | Notes                                                                                                                                               |\n|--------|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|\n| Light  | On/Off, Brightness, RGB, Color Temperature                            |                                                                                                                                                     |\n| Lock   | Lock/Unlock                                                           | Homekey can be enabled but only the `pn532_spi` component is supported to be used with it                                                           |\n| Switch | On/Off                                                                |                                                                                                                                                     |\n| 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](https://www.home-assistant.io/integrations/sensor/#device-class) |\n| Fan    | On/Off                                                                |                                                                                                                                                     |\n\n## 2. Prerequisites\n\nThe components were designed to be used with ESP-IDF version 5.\n\nSee below required configuration that needs to be present in your yaml file.\n\n```yaml\nesp32:\n  board: \u003cinsert board id\u003e\n  framework:\n    type: esp-idf\n    version: 5.2.1\n    platform_version: 6.7.0\n    sdkconfig_options:\n      CONFIG_COMPILER_OPTIMIZATION_SIZE: y\n      CONFIG_LWIP_MAX_SOCKETS: \"16\"\n      CONFIG_MBEDTLS_HKDF_C: y\n```\n\n`CONFIG_COMPILER_OPTIMIZATION_SIZE` is not functionally required but assists with the size optimization since a full configuration will take a lot of space.\n\n## 3. Components\n\nProject is divided into two different components, `homekit_base` which handles the bridge logic and `homekit` that handles the actual accessory logic (lights, switches, etc.).\n\nThis 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.\n\n\u003e [!TIP]\n\u003e For configuration examples, you can see the `.yaml` files in this repository, e.g. [lights-c3.yaml](lights-c3.yaml)\n\n### 3.1. `homekit_base`\n\n\u003e [!NOTE]  \n\u003e 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\n\n#### 3.1.1. Configuration variables:\n\n- **port** (Optional, int): The port HomeKit should listen to\n- **meta** (Optional): Bridge information\n  - **name** (Optional, string): Name of the bridge accessory\n  - **model** (Optional, string): Model name for the bridge accessory\n  - **manufacturer** (Optional, string): Manufacturer name for the bridge accessory\n  - **serial_number** (Optional, string): Serial number for the bridge accessory\n  - **fw_rev** (Optional, string): Firmware revision for the bridge accessory\n- **setup_code** (Optional, string): The HomeKit setup code in the format `XXX-XX-XXX` - **Default:** `159-35-728`\n- **setup_id** (Optional, string): The Setup ID that can be used to generate a pairing QR Code - **Default:** `ES32`\n\nConfiguration Example:\n\n```yaml\n\nhomekit_base:\n  meta:\n    name: \"PRIMO\"\n    manufacturer: \"AMICI\u0026CO\"\n    model: \"IMPERIUM\"\n    serial_number: \"16161616\"\n    fw_rev: \"0.16.2\"\n  setup_code: '159-35-728'\n  setup_id: \"ES32\"\n```\n\n#### 3.1.2. Factory reset\n\n`homekit_base` can also be used as a platform component for the button component to reset the HomeKit pairings, see example below:\n\n  ```yaml\n  button:\n  - platform: homekit_base\n    factory_reset:\n      name: \"Reset HomeKit pairings\"\n  ```\nThis will function like any regular button in ESPHome and therefore will be visible in the Web Interface and HASS.\n\n### 3.2. `homekit`\n\nThis is what handles the accessory logic like syncing states between HomeKit and ESPHome and basic information (name, attributes, etc.).\n\n#### 3.2.1. Configuration variables:\n- **light** (Optional): Array of Light entities\n  - **id** (Required, [Light](https://esphome.io/components/light/)) - Id of the light entity\n  - **meta** (Optional): Accessory information\n    - **name** (Optional, string): Name of the accessory, defaults to name of the entity\n    - **model** (Optional, string): Model name for the accessory\n    - **manufacturer** (Optional, string): Manufacturer name for the accessory\n    - **serial_number** (Optional, string): Serial number for the accessory, defaults to internal object id\n    - **fw_rev** (Optional, string): Firmware revision for the accessory\n   \n  Example:\n  ```yaml\n  homekit:\n    light:\n      - id: desk_light\n        meta:\n          name: \"RGB Light\"\n          manufacturer: \"AMICI\u0026CO\"\n          model: \"IGNIS\"\n          serial_number: \"42424242\"\n          fw_rev: \"0.16.2\"\n  ```\n\n- **lock** (Optional): Array of Lock Entities\n  - **id** (Required, [Lock](https://esphome.io/components/lock/)) - Id of the lock entity\n  - **meta** (Optional): Accessory information\n    - **name** (Optional, string): Name of the accessory, defaults to name of the entity\n    - **model** (Optional, string): Model name for the accessory\n    - **manufacturer** (Optional, string): Manufacturer name for the accessory\n    - **serial_number** (Optional, string): Serial number for the accessory, defaults to internal object id\n    - **fw_rev** (Optional, string): Firmware revision for the accessory\n  - **nfc_id** (Optional, [PN532](https://esphome.io/components/binary_sensor/pn532.html#over-spi)): Id of the `pn532_spi` component, used for the HomeKey functionality\n  - **on_hk_success** (Optional, [Action](https://esphome.io/automations/actions)): Action to be executed when Homekey is successfully authenticated\n  - **on_hk_fail** (Optional, [Action](https://esphome.io/automations/actions)): Action to be executed when Homekey fails to authenticate\n  - **hk_hw_finish**(Optional, string): Color of the Homekey card from the predefined `BLACK`, `SILVER`, `GOLD` and `TAN`, defaults to `BLACK`\n \n  Example:\n  ```yaml\n  homekit:\n    lock:\n      - id: this_lock\n        meta:\n          manufacturer: \"AMICI\u0026CO\"\n          model: \"IMPEDIO\"\n          serial_number: \"42424242\"\n          fw_rev: \"0.16.2\"\n        nfc_id: nfc_spi_module\n        on_hk_success:\n          lambda: |-\n            ESP_LOGI(\"HEREHERE\", \"IssuerID: %s\", x.c_str());\n            ESP_LOGI(\"HEREHERE\", \"EndpointID: %s\", y.c_str());\n            id(test_light).toggle().perform();\n        on_hk_fail:\n          lambda: |-\n            ESP_LOGI(\"GSDGSGS\", \"IT FAILED :(\");\n        hk_hw_finish: \"SILVER\"\n  ```\n- **sensor**\n  - **id** (Required, [Sensor](https://esphome.io/components/sensor/)): Id of the sensor entity\n  - **meta** (Optional): Accessory information\n    - **name** (Optional, string): Name of the accessory, defaults to name of the entity\n    - **model** (Optional, string): Model name for the accessory\n    - **manufacturer** (Optional, string): Manufacturer name for the accessory\n    - **serial_number** (Optional, string): Serial number for the accessory, defaults to internal object id\n    - **fw_rev** (Optional, string): Firmware revision for the accessory\n\n  Example:\n  ```yaml\n  homekit:\n    sensor:\n      - id: my_sensor\n        meta:\n          manufacturer: \"AMICI\u0026CO\"\n          model: \"VARIO\"\n          serial_number: \"42424242\"\n          fw_rev: \"0.16.2\"\n  ```\n- **switch**\n  - **id** (Required, [Switch](https://esphome.io/components/switch/)): Id of the switch entity\n  - **meta** (Optional): Accessory information\n    - **name** (Optional, string): Name of the accessory, defaults to name of the entity\n    - **model** (Optional, string): Model name for the accessory\n    - **manufacturer** (Optional, string): Manufacturer name for the accessory\n    - **serial_number** (Optional, string): Serial number for the accessory, defaults to internal object id\n    - **fw_rev** (Optional, string): Firmware revision for the accessory\n\n  Example:\n  ```yaml\n    switch:\n      - id: some_switch\n        meta:\n          manufacturer: \"AMICI\u0026CO\"\n          model: \"TRANSMUTO\"\n          serial_number: \"42424242\"\n          fw_rev: \"0.16.2\"\n  ```\n - **fan** (Optional): Array of Fan Entities\n   - **id** (Required, [Fan](https://esphome.io/components/fan/)): Id of the fan entity\n   - **meta** (Optional): Accessory information\n     - **name** (Optional, string): Name of the accessory, defaults to name of the entity\n     - **model** (Optional, string): Model name for the accessory\n     - **manufacturer** (Optional, string): Manufacturer name for the accessory\n     - **serial_number** (Optional, string): Serial number for the accessory, defaults to internal object id\n     - **fw_rev** (Optional, string): Firmware revision for the accessory\n\n   Example:\n   ```yaml\n   homekit:\n     fan:\n       - id: my_fan\n         meta:\n           name: \"Living Room Fan\"\n           manufacturer: \"AMICI\u0026CO\"\n           model: \"VENTUS\"\n           serial_number: \"42424242\"\n           fw_rev: \"0.16.2\"\n   ```\n## 4. HomeKey\n\n\u003e [!NOTE]\n\u003e If you notice an error in the logs that says `Can't decode message length.`, you can safely ignore it. The project is using a \"hijacked\" version of the official pn532 component and the message is part of the normal operation of it since it's meant to be used with \"regular\" NFC Tags.\n\n### 4.1 Disclaimer\n\n\u003e [!WARNING]\n\u003e The functionality of Homekey is entirely based on reverse engineering since HomeKit specs stopped being available to hobbyists and therefore the entire functionality or parts of it might or might not break in the future and/or lack official features or any internal implementations.\n\n### 4.2 Setup\n\n\u003e [!IMPORTANT]\n\u003e Only PN532 over SPI(`pn532_spi` component) is supported at the moment due to required modifications that haven't been ported to other protocols or chips\n\n\u003e [!NOTE]\n\u003e For quick reactions and to avoid issues, don't raise the `update_interval` over 500ms\n\n```yaml\nspi:\n  clk_pin: 4\n  miso_pin: 5\n  mosi_pin: 6\n\npn532_spi:\n  id: nfc_spi_module\n  cs_pin: 7\n  update_interval: 100ms\n\nhomekit:\n  lock:\n    - id: \u003cinsert lock id\u003e\n      nfc_id: nfc_spi_module\n```\n\n## Support \u0026 Contributing\n\nIf you wish to contribute with a feature or a fix, a PR will be most welcomed\n\nThe best way to support the work that i do is to :star: the repository but you can also buy me a :coffee: if you wish by sponsoring me on [GitHub](https://github.com/sponsors/rednblkx).\n\nYou can also choose to join the [Discord server](https://discord.com/invite/VWpZ5YyUcm) where you will find a helpful and lovely community.\n\n## Credits\n\n[@kormax](https://github.com/kormax) - Homekey NFC protocol [research](https://github.com/kormax/apple-home-key), [ECP](https://github.com/kormax/apple-enhanced-contactless-polling) and [PoC](https://github.com/kormax/apple-home-key-reader)\n\n[@kupa22](https://github.com/kupa22) - [Documenting](https://github.com/kupa22/apple-homekey) the HAP part for the Homekey\n\n[ESPHome](https://github.com/esphome/esphome) - ESPHome and the PN532 module\n\n[Espressif](https://github.com/espressif) - [esp-homekit-sdk](https://github.com/espressif/esp-homekit-sdk)\n\n## License\n\nThis repository consists of multiple licenses since it contains some components([pn532](https://github.com/rednblkx/HAP-ESPHome/tree/main/components/pn532) and [pn532_spi](https://github.com/rednblkx/HAP-ESPHome/tree/main/components/pn532_spi)) originally from the [ESPHome](https://github.com/esphome/esphome) repository, please consult the LICENSE file in each folder in the [components](https://github.com/rednblkx/HAP-ESPHome/tree/main/components) folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frednblkx%2Fhap-esphome","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frednblkx%2Fhap-esphome","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frednblkx%2Fhap-esphome/lists"}