Apple HomeKey functionality for the rest of us
The 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.
No proprietary hardware required – just an ESP32 and a PN532 NFC module
- ESP32 Development Board
- PN532 NFC Module (SPI interface)
- USB Cable (for flashing and power)
- Computer (Windows, Mac, or Linux)
- Basic Electronics Knowledge (not a problem if you're new to this, ask away!)
The following chips are supported for Ethernet:
- W5500
- DM9051
- KSZ8851
- LAN8720 / LAN8710
- TLK110
- RTL8201
- DP83848
- KSZ8041
- KSZ8081
Important
The following are only supported for ESP32-WROOM-32 boards as other variants lack the internal EMAC needed for the RMII interface:
- LAN8720 / LAN8710
- TLK110
- RTL8201
- DP83848
- KSZ8041
- KSZ8081
-
Download Firmware
- Visit GitHub Releases
- Download the
*.firmware.factory.binfile - This contains everything you need - no compilation required!
-
Connect Your Hardware
- Wire your PN532 NFC module to your ESP32 using the default pins
- Refer to the detailed wiring guide for your specific setup
-
Flash the Firmware
# 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
Prefer a GUI? Use the browser-based flasher - no command line needed!
-
Initial Setup
- Connect to the device's WiFi AP (
HomeSpan-Setup/homespan) - Access the web interface at
http://192.168.4.1 - Configure your WiFi credentials and HomeKit setup code
- Pair with Apple Home using code:
466-37-726
- Connect to the device's WiFi AP (
-
Start Using HomeKey!
- Hold your iPhone or Apple Watch near the NFC reader
- Enjoy instant, secure access to your home! 🎉
graph TD
A[iPhone/Apple Watch] -->|NFC| B[PN532 Module]
B -->|SPI| C[ESP32]
C -->|MQTT| D[Home Assistant/Broker]
C -->|HomeKit| E[Apple Home]
C -->|HTTP| F[Web Interface]
C -->|GPIO| G[Physical Lock]
subgraph "HomeKey-ESP32 Core"
C
H[ConfigManager]
I[LockManager]
J[NfcManager]
K[HomeKitLock]
L[WebServerManager]
M[MqttManager]
end
style A fill:#1f2937,stroke:#374151,color:#fff
style C fill:#059669,stroke:#047857,color:#fff
style B fill:#3b82f6,stroke:#2563eb,color:#fff
- Express Mode: Unlock without waking your device
- Power Reserve: Unlock even when the device needs to be charged
- Multi-Device Support: Works with iPhone and Apple Watch
- Fast Authentication: Sub-300ms unlock times
- HomeKit Native: Full Apple Home ecosystem integration
- MQTT Support: Connect to Home Assistant, OpenHAB, and other platforms
- Home Assistant Discovery: Automatic device detection and configuration
- Custom States: Support for complex lock states (jamming, unlocking, etc.)
- Svelte Frontend: Responsive, modern UI built with Svelte 5 + Tailwind CSS
- Real-time Updates: WebSocket-powered live status updates
- OTA Updates: Over-the-air firmware updates via web interface
- Configuration Management: Easy setup without recompiling
- Open Source: MIT licensed, community-driven development
- Modular Architecture: Clean separation of concerns
- Event System: Pub/sub architecture for extensibility
- Comprehensive Logging: Debug and monitor with detailed logs
graph TD
%% External Systems & Hardware
subgraph "External World"
A[iPhone / Apple Watch]
B[Apple Home]
C[Web Browser]
D[MQTT Broker]
E[Physical Lock, Buttons & LEDs]
end
%% Main Application on ESP32
subgraph "HomeKey-ESP32 Core"
subgraph "Interface Managers (I/O)"
direction LR
Nfc[NfcManager]
HK[HomeKitLock]
Web[WebServerManager]
Mqtt[MqttManager]
Hw[HardwareManager]
end
subgraph "Logic Core (State Machine)"
Lock[LockManager]
end
subgraph "Data Services (Persistence)"
direction LR
Config[ConfigManager]
Reader[ReaderDataManager]
NVS[(NVS Storage)]
end
%% High-level Data and Control Flow
DataServices[Data Services] -- "Provides Config & Reader Data" --> InterfaceManagers[Interface Managers]
DataServices -- "Provides Config" --> LogicCore[Logic Core]
Config -- "Reads/Writes" --> NVS
Reader -- "Reads/Writes" --> NVS
InterfaceManagers -- "State Change Requests (e.g., Unlock)" --> Lock
Lock -- "Actions & State Updates" --> InterfaceManagers
end
%% Connections to the External World
A -- NFC --> Nfc
B -- HomeKit --> HK
C -- HTTP/WebSocket --> Web
D -- MQTT --> Mqtt
E -- GPIO --> Hw
Hw -- GPIO --> E
HK -- HomeKit --> B
Web -- HTTP/WebSocket --> C
Mqtt -- MQTT --> D
%% Styling for clarity
style A fill:#1f2937,stroke:#374151,color:#fff
style B fill:#1f2937,stroke:#374151,color:#fff
style C fill:#1f2937,stroke:#374151,color:#fff
style D fill:#1f2937,stroke:#374151,color:#fff
style E fill:#1f2937,stroke:#374151,color:#fff
style Nfc fill:#3b82f6,stroke:#2563eb,color:#fff
style HK fill:#059669,stroke:#047857,color:#fff
style Web fill:#f59e0b,stroke:#d97706,color:#fff
style Mqtt fill:#ef4444,stroke:#dc2626,color:#fff
style Hw fill:#8b5cf6,stroke:#7c3aed,color:#fff
style Lock fill:#ec4899,stroke:#db2777,color:#fff
style Config fill:#6b7280,stroke:#4b5563,color:#fff
style Reader fill:#6b7280,stroke:#4b5563,color:#fff
style NVS fill:#9ca3af,stroke:#6b7280,color:#fff
HomeKey-ESP32/
├── main/ # Core ESP32 application
│ ├── main.cpp # Application entry point
│ ├── ConfigManager.cpp # Configuration management
│ ├── ReaderDataManager.cpp # Reader data management
│ ├── NfcManager.cpp # NFC communication
│ ├── HomeKitLock.cpp # HomeKit integration
│ ├── LockManager.cpp # Lock state management
│ ├── MqttManager.cpp # MQTT client
│ ├── WebServerManager.cpp # Web interface
│ ├── WebSocketLogSinker.cpp # WebSocket logging sinker
│ ├── HardwareManager.cpp # Hardware manager
│ └── HKServices.cpp # HomeKit services
├── data/ # Web interface files
│ ├── src/ # Vue.js application
│ └── index.html # Web UI entry point
├── components/ # External dependencies
│ ├── HK-HomeKit-Lib/ # HomeKey implementation
│ ├── HomeSpan/ # HomeKit framework
│ └── PN532/ # NFC driver
└── docs/ # Documentation
└── content/ # Hugo documentation
| Component | File | Purpose |
|---|---|---|
| NFC Manager | NfcManager.cpp |
Handles PN532 communication and HomeKey authentication |
| HomeKit Bridge | HomeKitLock.cpp |
Manages Apple HomeKit integration and pairing |
| Lock Manager | LockManager.cpp |
Controls lock state transitions and GPIO actions |
| MQTT Client | MqttManager.cpp |
Enables smart home integration via MQTT |
| Web Server | WebServerManager.cpp |
Provides configuration UI and OTA updates |
| Config Manager | ConfigManager.cpp |
Handles persistent configuration storage |
# Install dependencies
git submodule update --init --recursive
# Install esp-idf (see https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#get-started)
# Build firmware
idf.py build
# Flash to device
idf.py -p /dev/ttyUSB0 flash
# Monitor output
idf.py monitorContributions are welcomed! Please see the Contributing Guidelines for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request against the
mainbranch
HomeKey-ESP32 is openly developed and maintained by the community. Your support helps us continue improving the project.
- Star the repository to show your appreciation
- Report bugs to help improve stability
- Suggest features to guide development
- Share the project with your network
- Contribute documentation to help others
- @kormax: Reverse-engineered the HomeKey NFC protocol and published the foundational PoC implementation
- @kupa22: Researched the HAP (HomeKit Accessory Protocol) side of HomeKey
- HomeSpan: Excellent HomeKit framework that powers our integration
- ESP-IDF: Robust IoT development framework from Espressif
This project is licensed under the MIT License - see the LICENSE file for details.
Important: This project implements Apple HomeKey functionality through reverse engineering. While we strive for security and compatibility:
- Not affiliated in any shape or form nor condoned by Apple Inc.
- Use at your own risk for security-critical applications
- May lack elements from Apple's private specifications
- Subject to change as Apple updates their protocols
- Apple, iPhone, and Apple Watch are trademarks of Apple Inc.
- ESP32 is a trademark of Espressif Systems (Shanghai) Co., Ltd.
- Home Assistant is a trademark of Open Home Foundation
![@coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=64&v=4){kind=small}