{"id":19006009,"url":"https://github.com/rednblkx/homekey-esp32","last_synced_at":"2026-05-01T10:03:58.768Z","repository":{"id":211815903,"uuid":"729997515","full_name":"rednblkx/HomeKey-ESP32","owner":"rednblkx","description":"ESP32 HomeKit Lock with support for Apple Home Key (reverse-engineered)","archived":false,"fork":false,"pushed_at":"2026-04-19T22:17:14.000Z","size":7639,"stargazers_count":933,"open_issues_count":45,"forks_count":70,"subscribers_count":33,"default_branch":"main","last_synced_at":"2026-04-20T00:22:29.402Z","etag":null,"topics":["apple","apple-home-key","arduino","ecp","enhanced-contactless-polling","home-assistant","home-automation","home-key","homekit","nfc"],"latest_commit_sha":null,"homepage":"https://rednblkx.github.io/HomeKey-ESP32/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rednblkx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"ko_fi":"rednblkx","custom":"https://www.paypal.me/rednblkx"}},"created_at":"2023-12-11T01:03:58.000Z","updated_at":"2026-04-19T22:11:39.000Z","dependencies_parsed_at":"2024-03-22T19:48:40.768Z","dependency_job_id":"d976fb79-c588-48b3-8f88-525abc41a123","html_url":"https://github.com/rednblkx/HomeKey-ESP32","commit_stats":{"total_commits":245,"total_committers":6,"mean_commits":"40.833333333333336","dds":"0.23673469387755097","last_synced_commit":"16e88f9c6a83167e8e3de2dec286ae88e525dc3d"},"previous_names":["rednblkx/homekey-esp32"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/rednblkx/HomeKey-ESP32","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHomeKey-ESP32","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHomeKey-ESP32/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHomeKey-ESP32/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHomeKey-ESP32/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rednblkx","download_url":"https://codeload.github.com/rednblkx/HomeKey-ESP32/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rednblkx%2FHomeKey-ESP32/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32492595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","apple-home-key","arduino","ecp","enhanced-contactless-polling","home-assistant","home-automation","home-key","homekit","nfc"],"created_at":"2024-11-08T18:29:54.895Z","updated_at":"2026-05-01T10:03:58.729Z","avatar_url":"https://github.com/rednblkx.png","language":"C++","funding_links":["https://ko-fi.com/rednblkx","https://www.paypal.me/rednblkx"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"169\" height=\"200\" alt=\"homekey-logo-200x200\" src=\"https://github.com/user-attachments/assets/6c4bc1e8-c294-4a4b-842a-9837a680b913\" /\u003e\n\n  # HomeKey-ESP32\n  [![Discord](https://badgen.net/discord/members/VWpZ5YyUcm?icon=discord)](https://discord.com/invite/VWpZ5YyUcm)\n  [![CI](https://github.com/rednblkx/HomeKey-ESP32/actions/workflows/esp32.yml/badge.svg?branch=main)](https://github.com/rednblkx/HomeKey-ESP32/actions/workflows/esp32.yml)\n  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n  \n  **Apple HomeKey functionality for the rest of us**\n  \n\n  [Documentation](https://rednblkx.github.io/HomeKey-ESP32/)\n\n\u003c/div\u003e\n\n## What is HomeKey-ESP32?\n\nThe project aims to be the easy DIY solution for using Apple's HomeKey feature without the need to purchase a compatible smart lock that you probably don't want. HomeKey-ESP32 brings Apple's secure NFC-based unlocking to an ESP32 module near you, enabling you to unlock doors and whatnot with a simple tap of your iPhone or Apple Watch.\n\n**No proprietary hardware required** – just an ESP32 and a PN532 NFC module\n\n\u003e [!WARNING]\n\u003e The flash memory is not encrypted as this kinda started as a pet project of mine but a lot of people started using\n\u003e so unfortunately it's stuck like this because migration would be painful and i don't want to be telling people to\n\u003e reconfigure their device if they want to update.\n\u003e\n\u003e If you care about this, i'm working on a new project implementing the new Aliro standard and flash will be\n\u003e encrypted first thing, however, honestly don't know when that will be public, you can join the Discord server\n\u003e if you want to know as soon as it is available.\n\n## Getting Started\n\n### Prerequisites\n\n- **ESP32 Development Board**\n- **PN532 NFC Module** (SPI interface)\n- **USB Cable** (for flashing and power)\n- **Computer** (Windows, Mac, or Linux)\n- **Basic Electronics Knowledge** (not a problem if you're new to this, ask away!)\n\n#### Ethernet\n\nThe following chips are supported for Ethernet:\n\n-  W5500\n-  DM9051\n-  KSZ8851\n-  LAN8720 / LAN8710\n-  TLK110\n-  RTL8201\n-  DP83848\n-  KSZ8041\n-  KSZ8081\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e The following are only supported for ESP32-WROOM-32 boards as other variants lack the internal EMAC needed for the RMII interface:\n\u003e -  LAN8720 / LAN8710\n\u003e -  TLK110\n\u003e -  RTL8201\n\u003e -  DP83848\n\u003e -  KSZ8041\n\u003e -  KSZ8081\n\n### Installation Steps\n\n1. **Download Firmware**\n   - Visit [GitHub Releases](https://github.com/rednblkx/HomeKey-ESP32/releases/latest)\n   - Download the `*.firmware.factory.bin` file\n   - This contains everything you need - no compilation required!\n\n2. **Connect Your Hardware**\n   - Wire your PN532 NFC module to your ESP32 using the default pins\n   - Refer to the [detailed wiring guide](https://rednblkx.github.io/HomeKey-ESP32/setup/#21-nfc-module-wiring) for your specific setup\n\n3. **Flash the Firmware**\n   ```bash\n   # Install esptool (one-time setup)\n   pip install esptool\n   \n   # Flash the firmware (replace YOUR_PORT)\n   esptool.py --port /dev/ttyUSB0 write_flash 0x0 firmware.factory.bin\n   ```\n   \n   **Prefer a GUI?** Use the [browser-based flasher](https://espressif.github.io/esptool-js/) - no command line needed!\n\n4. **Initial Setup**\n   - Connect to the device's WiFi AP (`HomeSpan-Setup` / `homespan`)\n   - Access the web interface at `http://192.168.4.1`\n   - Configure your WiFi credentials and HomeKit setup code\n   - Pair with Apple Home using code: `466-37-726`\n\n5. **Start Using HomeKey!**\n   - Hold your iPhone or Apple Watch near the NFC reader\n   - Enjoy instant, secure access to your home! 🎉\n\n## System Architecture\n\n\u003cdiv align=\"center\"\u003e\n  \n```mermaid\ngraph TD\n    A[iPhone/Apple Watch] --\u003e|NFC| B[PN532 Module]\n    B --\u003e|SPI| C[ESP32]\n    C --\u003e|MQTT| D[Home Assistant/Broker]\n    C --\u003e|HomeKit| E[Apple Home]\n    C --\u003e|HTTP| F[Web Interface]\n    C --\u003e|GPIO| G[Physical Lock]\n    \n    subgraph \"HomeKey-ESP32 Core\"\n        C\n        H[ConfigManager]\n        I[LockManager]\n        J[NfcManager]\n        K[HomeKitLock]\n        L[WebServerManager]\n        M[MqttManager]\n    end\n    \n    style A fill:#1f2937,stroke:#374151,color:#fff\n    style C fill:#059669,stroke:#047857,color:#fff\n    style B fill:#3b82f6,stroke:#2563eb,color:#fff\n```\n\n\u003c/div\u003e\n\n## ✨ Key Features\n\n### **Apple HomeKey Integration**\n- **Express Mode**: Unlock without waking your device\n- **Power Reserve**: Unlock even when the device needs to be charged\n- **Multi-Device Support**: Works with iPhone and Apple Watch\n- **Fast Authentication**: Sub-300ms unlock times\n\n### **Smart Home Ready**\n- **HomeKit Native**: Full Apple Home ecosystem integration\n- **MQTT Support**: Connect to Home Assistant, OpenHAB, and other platforms\n- **Home Assistant Discovery**: Automatic device detection and configuration\n- **Custom States**: Support for complex lock states (jamming, unlocking, etc.)\n\n### **Modern Web Interface**\n- **Svelte Frontend**: Responsive, modern UI built with Svelte 5 + Tailwind CSS\n- **Real-time Updates**: WebSocket-powered live status updates\n- **OTA Updates**: Over-the-air firmware updates via web interface\n- **Configuration Management**: Easy setup without recompiling\n\n### **Developer Friendly**\n- **Open Source**: MIT licensed, community-driven development\n- **Modular Architecture**: Clean separation of concerns\n- **Event System**: Pub/sub architecture for extensibility\n- **Comprehensive Logging**: Debug and monitor with detailed logs\n\n## Development\n\n\u003cdiv align=\"center\"\u003e\n  \n```mermaid\ngraph TD\n  %% External Systems \u0026 Hardware\n  subgraph \"External World\"\n      A[iPhone / Apple Watch]\n      B[Apple Home]\n      C[Web Browser]\n      D[MQTT Broker]\n      E[Physical Lock, Buttons \u0026 LEDs]\n  end\n\n  %% Main Application on ESP32\n  subgraph \"HomeKey-ESP32 Core\"\n      \n      subgraph \"Interface Managers (I/O)\"\n          direction LR\n          Nfc[NfcManager]\n          HK[HomeKitLock]\n          Web[WebServerManager]\n          Mqtt[MqttManager]\n          Hw[HardwareManager]\n      end\n\n      subgraph \"Logic Core (State Machine)\"\n          Lock[LockManager]\n      end\n\n      subgraph \"Data Services (Persistence)\"\n          direction LR\n          Config[ConfigManager]\n          Reader[ReaderDataManager]\n          NVS[(NVS Storage)]\n      end\n\n      %% High-level Data and Control Flow\n      DataServices[Data Services] -- \"Provides Config \u0026 Reader Data\" --\u003e InterfaceManagers[Interface Managers]\n      DataServices -- \"Provides Config\" --\u003e LogicCore[Logic Core]\n      Config -- \"Reads/Writes\" --\u003e NVS\n      Reader -- \"Reads/Writes\" --\u003e NVS\n      \n      InterfaceManagers -- \"State Change Requests (e.g., Unlock)\" --\u003e Lock\n      Lock -- \"Actions \u0026 State Updates\" --\u003e InterfaceManagers\n  end\n  \n  %% Connections to the External World\n  A -- NFC --\u003e Nfc\n  B -- HomeKit --\u003e HK\n  C -- HTTP/WebSocket --\u003e Web\n  D -- MQTT --\u003e Mqtt\n  E -- GPIO --\u003e Hw\n  \n  Hw -- GPIO --\u003e E\n  HK -- HomeKit --\u003e B\n  Web -- HTTP/WebSocket --\u003e C\n  Mqtt -- MQTT --\u003e D\n\n  %% Styling for clarity\n  style A fill:#1f2937,stroke:#374151,color:#fff\n  style B fill:#1f2937,stroke:#374151,color:#fff\n  style C fill:#1f2937,stroke:#374151,color:#fff\n  style D fill:#1f2937,stroke:#374151,color:#fff\n  style E fill:#1f2937,stroke:#374151,color:#fff\n\n  style Nfc fill:#3b82f6,stroke:#2563eb,color:#fff\n  style HK fill:#059669,stroke:#047857,color:#fff\n  style Web fill:#f59e0b,stroke:#d97706,color:#fff\n  style Mqtt fill:#ef4444,stroke:#dc2626,color:#fff\n  style Hw fill:#8b5cf6,stroke:#7c3aed,color:#fff\n\n  style Lock fill:#ec4899,stroke:#db2777,color:#fff\n  \n  style Config fill:#6b7280,stroke:#4b5563,color:#fff\n  style Reader fill:#6b7280,stroke:#4b5563,color:#fff\n  style NVS fill:#9ca3af,stroke:#6b7280,color:#fff\n```\n\n\u003c/div\u003e\n\n### Project Structure\n\n```\nHomeKey-ESP32/\n├── main/                    # Core ESP32 application\n│   ├── main.cpp            # Application entry point\n│   ├── ConfigManager.cpp    # Configuration management\n│   ├── ReaderDataManager.cpp # Reader data management\n│   ├── NfcManager.cpp      # NFC communication\n│   ├── HomeKitLock.cpp     # HomeKit integration\n│   ├── LockManager.cpp     # Lock state management\n│   ├── MqttManager.cpp     # MQTT client\n│   ├── WebServerManager.cpp # Web interface\n│   ├── WebSocketLogSinker.cpp # WebSocket logging sinker\n│   ├── HardwareManager.cpp # Hardware manager\n│   └── HKServices.cpp # HomeKit services\n├── data/                   # Web interface files\n│   ├── src/               # Vue.js application\n│   └── index.html         # Web UI entry point\n├── components/            # External dependencies\n│   ├── HK-HomeKit-Lib/   # HomeKey implementation\n│   ├── HomeSpan/         # HomeKit framework\n│   └── PN532/            # NFC driver\n└── docs/                 # Documentation\n    └── content/          # Hugo documentation\n```\n\n### Core Components\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| **NFC Manager** | [`NfcManager.cpp`](main/NfcManager.cpp) | Handles PN532 communication and HomeKey authentication |\n| **HomeKit Bridge** | [`HomeKitLock.cpp`](main/HomeKitLock.cpp) | Manages Apple HomeKit integration and pairing |\n| **Lock Manager** | [`LockManager.cpp`](main/LockManager.cpp) | Controls lock state transitions and GPIO actions |\n| **MQTT Client** | [`MqttManager.cpp`](main/MqttManager.cpp) | Enables smart home integration via MQTT |\n| **Web Server** | [`WebServerManager.cpp`](main/WebServerManager.cpp) | Provides configuration UI and OTA updates |\n| **Config Manager** | [`ConfigManager.cpp`](main/ConfigManager.cpp) | Handles persistent configuration storage |\n\n### Building from Source\n\n```bash\n# Install dependencies\ngit submodule update --init --recursive\n\n# Install esp-idf (see https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#get-started)\n\n# Build firmware\nidf.py build\n\n# Flash to device\nidf.py -p /dev/ttyUSB0 flash\n\n# Monitor output\nidf.py monitor\n```\n\n### Contributing\n\nContributions are welcomed! Please see the [Contributing Guidelines](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'feat: Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request against the `main` branch\n\n## Support the Project\n\nHomeKey-ESP32 is openly developed and maintained by the community. Your support helps us continue improving the project.\n\n- **Star the repository** to show your appreciation\n- **Report bugs** to help improve stability\n- **Suggest features** to guide development\n- **Share the project** with your network\n- **Contribute documentation** to help others\n\n## Credits\n\n- **[@kormax](https://github.com/kormax)**: Reverse-engineered the HomeKey NFC protocol and published the foundational [PoC implementation](https://github.com/kormax/apple-home-key-reader)\n- **[@kupa22](https://github.com/kupa22)**: Researched the HAP (HomeKit Accessory Protocol) side of HomeKey\n- **[HomeSpan](https://github.com/HomeSpan/HomeSpan)**: Excellent HomeKit framework that powers our integration\n- **[ESP-IDF](https://github.com/espressif/esp-idf)**: Robust IoT development framework from Espressif\n\n## License \u0026 Legal\n\n### License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n\n### Disclaimer\n\n**Important**: This project implements Apple HomeKey functionality through reverse engineering. While we strive for security and compatibility:\n\n- **Not affiliated** in any shape or form nor condoned by Apple Inc.\n- **Use at your own risk** for security-critical applications\n- **May lack elements** from Apple's private specifications\n- **Subject to change** as Apple updates their protocols\n\n### Trademarks\n\n- **Apple**, **iPhone**, and **Apple Watch** are trademarks of Apple Inc.\n- **ESP32** is a trademark of Espressif Systems (Shanghai) Co., Ltd.\n- **Home Assistant** is a trademark of Open Home Foundation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frednblkx%2Fhomekey-esp32","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frednblkx%2Fhomekey-esp32","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frednblkx%2Fhomekey-esp32/lists"}