# HomeKey-ESP32: Apple Home Key unlocking on an ESP32 and an NFC reader > HomeKey-ESP32 is firmware for an ESP32 that speaks Apple's Home Key protocol, so an iPhone or Apple Watch tap can unlock a door without a proprietary smart lock, with a Svelte web interface, MQTT support for Home Assistant, and optional flash encryption variants. It suits a builder who wants the feature without the hardware, and it asks you to accept a security model that the project itself describes as best effort. **rednblkx/HomeKey-ESP32** — ESP32 HomeKit Lock with support for Apple Home Key (reverse-engineered) - Repository: https://github.com/rednblkx/HomeKey-ESP32 - Website: https://rednblkx.github.io/HomeKey-ESP32/ - Stars: 1,103 · Forks: 97 - Language: C++ - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/rednblkx-homekey-esp32 ## What the project is The project positions itself as Apple HomeKey functionality for the rest of us, and the stated aim is to be the easy DIY solution for using Apple's HomeKey feature without needing to buy a compatible smart lock that you probably do not want. That is the honest framing, and it explains the design. Home Key is a feature where an iPhone or an Apple Watch can unlock a door by tapping an NFC reader that is cryptographically paired with the HomeKit controller. Apple sells locks that support it, and the ones that are cheap are not, and the ones that are good are expensive. This project is the third option, a small board next to your existing lock that pretends to be a Home Key reader. The hardware claim is at the top of the installation section: no proprietary hardware required, just an ESP32 and one of the supported NFC modules. That is accurate, and it is also the whole cost of the project, roughly the price of a development board and a reader module. The feature list covers the parts of Home Key that users notice. Express Mode unlocks without waking the device. Power Reserve unlocks even when the phone needs charging. There is multi-device support across iPhone and Apple Watch, and the README claims sub-300ms unlock times. The implementation is C++ for the ESP32, built with the ESP-IDF toolchain rather than the Arduino one, and the licence is MIT. The last push to the repository was on 2026-10-03, with the current development build from the same day and the version 0.9 release from 2026-09-22. ## The hardware, and the Ethernet options The prerequisites are short and there is a friendly note about the last one. You need an ESP32 development board, an NFC reader, a USB cable for flashing and power, a computer running Windows, Mac or Linux, and basic electronics knowledge, with the note that it is not a problem if you are new to this and you can ask. Three readers are supported. The PN532 over SPI, the PN7161 over SPI which is available in the development release, and the ST25R3916 over I2C which is also in the development release. So the stable release has one reader and the development builds have three, which is worth knowing before you order parts. The Ethernet support is a long list of chips, and the list comes with a restriction that matters for a specific set of them. The supported chips are the W5500, the DM9051, the KSZ8851, the LAN8720 and LAN8710, the TLK110, the RTL8201, the DP83848, the KSZ8041 and the KSZ8081. But eight of those are only supported for ESP32-WROOM-32 boards, because the other variants lack the internal Ethernet MAC that the RMII interface needs. The W5500 and the DM9051 and the KSZ8851 are the exceptions, and the reason is obvious once you know it, because they bring their own MAC with them and talk to the ESP32 over SPI rather than over the parallel RMII bus. So the board you pick constrains the Ethernet chip you pick, and that is the one hardware decision with a real dependency behind it. ## Installing: a prebuilt binary and esptool The installation steps are deliberately simple, and the key decision is that you do not compile anything. You download the factory firmware binary from the GitHub releases page, and the README says it contains everything you need with no compilation required. You wire your chosen NFC module to the ESP32 using the default pins, with a detailed wiring guide linked for the specific module. And then you flash it. ```bash # Install esptool (one-time setup) pip install esptool # Flash the firmware (replace YOUR_PORT) esptool.py --port /dev/ttyUSB0 write_flash 0x0 firmware.factory.bin ``` There is also a browser based flasher linked for anyone who would rather not use the command line, so the flash step does not require a terminal at all. The first run is a small sequence of its own. You connect to the device's own WiFi access point, named HomeSpan-Setup or homespan, open the web interface at 192.168.4.1, and configure the WiFi credentials and the HomeKit setup code there. Then you pair with Apple Home using the code 466-37-726. That pairing code is in the README, which is worth pausing on, because it is the kind of detail that is either obvious or alarming. It is a fixed code for this project, and it is the same for every installation, so anyone who knows it can attempt to pair with an unconfigured device. In practice that is a risk only before the device is set up and paired with your own HomeKit controller. After pairing, you hold the phone or the watch near the reader and the door opens. The configuration is done through the web interface, with the README stressing that no recompilation is needed for configuration changes. ## The encrypted variants, and what they cost There is a warning block in the README about the encrypted firmware, and it is the most important paragraph in the document for anyone choosing a build. The enc.firmware.ota.bin and enc.firmware.factory.bin release artifacts have Flash Encryption enabled and disable the UART and USB/JTAG download. Flashing that variant will render tools like esptool useless, and any future updates will only be possible through the project's own OTA implementation. You are also told not to attempt to update from an unencrypted version, because the bootloader and the partition table are different. The final sentence is the one to sit with. The flash encryption is provided as is and does not provide any guarantee of a bulletproof solution against attacks, but attempts to diminish the attack surface. So the trade is stated plainly. With the encrypted build, the firmware image on the device is not readable by a serial flash dump, which means a physical attacker with the board cannot pull the configuration and the keys out of the flash, and a supply chain attacker who intercepts a firmware update cannot read what they are shipping. What you give up is the ability to recover the device with a serial cable if something goes wrong, and the ability to go back to the unencrypted build. For a device that unlocks a front door, the attack surface argument is the right one, because a dumped configuration could contain the pairing material. The caveat is that the project does not claim the scheme is unbreakable, and it says so rather than overselling it. ## The architecture: managers around a lock state machine The two architecture diagrams in the README describe the design at two levels, and the second one is the more useful. The first is the data flow. The iPhone or the watch talks to the NFC module over RF, the module talks to the ESP32 over SPI, and the ESP32 talks out in four directions at once, over MQTT to a broker such as Home Assistant, over HomeKit to Apple Home, over HTTP to the web interface, and over GPIO to the physical lock. The second diagram is the internal structure, and it is a clean separation into three layers. The interface managers handle the outside world, with the NfcManager, the HomeKitLock, the WebServerManager, the MqttManager and a HardwareManager for the buttons and LEDs. The logic core is a single component, the LockManager, which the diagram labels as the state machine. And the data services handle persistence, with the ConfigManager, a ReaderDataManager and the NVS storage that both of them read and write. The arrows make the dependency rule explicit. The data services provide configuration and reader data to the interface managers and configuration to the logic core, and the interface managers drive the logic core when the state changes. So the lock's state has exactly one owner, and everything that touches the outside world goes through a manager that talks to that owner. That structure is why the custom states feature is possible. The README lists support for complex lock states such as jamming and unlocking, and a state machine is what makes a multi-state lock coherent. ## The web interface, the MQTT side and the state of the project The modern web interface section is short and the implementation choices are given. The front end is Svelte 5 with Tailwind CSS, the status updates are WebSocket powered, the firmware updates are over the air through the web interface, and the configuration is manageable without recompiling. There is a real-time element in that list, and it is the piece that makes the interface usable for a device whose state changes when someone taps a phone against it. The smart home side covers HomeKit natively, MQTT support for Home Assistant, OpenHAB and other platforms, automatic Home Assistant discovery so the device appears on its own, and custom states. The developer side is the MIT licence, a modular architecture, an event system described as publish and subscribe for extensibility, and comprehensive logging. On the state of the project, the release list is the development build, then version 0.9 in September 2026 and version 0.8 in February 2026. So it is a project in active development with a version below one, and the two NFC readers that are only in the development release are a good indicator of where the work is. The repository layout fits the ESP-IDF world, with a components directory, a main directory, a CMakeLists file, sdkconfig defaults in several variants including a specific ESP32 one, and CSV files describing the flash layouts for the builds with and without over the air updates. The presence of a flake file means the toolchain can be reproduced with Nix, and the dependencies lock file and the submodules point at the vendored pieces. For anyone planning to build this, the practical order is the one the README gives: decide the variant, decide the reader, flash the factory binary, and only then worry about encryption. ## Conclusion Adopt HomeKey-ESP32 if you want Apple Home Key unlocking without buying a compatible smart lock and you are comfortable flashing firmware and wiring an NFC reader to an ESP32, because the project ships prebuilt binaries and a browser flasher. Do not adopt it as a door lock you depend on for daily access without reading the flash encryption warning, since the project states the encryption is provided as is and offers no guarantee against attacks. Before you flash, decide which variant you want, because the encrypted one permanently disables the serial and debug download paths and cannot be downgraded back. ## FAQ ### What does HomeKey-ESP32 do? It is firmware for an ESP32 that implements Apple's Home Key, so tapping an iPhone or Apple Watch against a supported NFC reader unlocks a door, without requiring a proprietary Home Key smart lock. The claim is that no proprietary hardware is required, just an ESP32 and one of the supported NFC modules. ### Which NFC readers does HomeKey-ESP32 support? The PN532 over SPI is the one in the stable release, and the PN7161 over SPI and the ST25R3916 over I2C are available in the development release. The prerequisites also list an ESP32 development board, a USB cable for flashing and power, and a computer running Windows, Mac or Linux. ### What is the difference between the encrypted and unencrypted firmware? The enc.firmware.ota.bin and enc.firmware.factory.bin artifacts have Flash Encryption enabled and disable the UART and USB/JTAG download, so flashing them renders esptool useless and updates are only possible through the project's OTA implementation. You must not update from an unencrypted version because the bootloader and partition table differ, and the project states the encryption is provided as is with no guarantee against attacks, only an attempt to diminish the attack surface. ### How is the HomeKey-ESP32 set up after flashing? You connect to the device's own WiFi access point, HomeSpan-Setup or homespan, open the web interface at 192.168.4.1, configure the WiFi credentials and the HomeKit setup code, and then pair with Apple Home using the code given in the readme, after which a tap of the phone or watch near the reader unlocks the door. ## Sources - [License: MIT](https://github.com/rednblkx/HomeKey-ESP32/blob/main/LICENSE) - [Project website](https://rednblkx.github.io/HomeKey-ESP32/) - [README](https://github.com/rednblkx/HomeKey-ESP32/blob/main/README.md) - [rednblkx/HomeKey-ESP32 on GitHub](https://github.com/rednblkx/HomeKey-ESP32) - [Releases](https://github.com/rednblkx/HomeKey-ESP32/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/rednblkx-homekey-esp32