HomeKey-ESP32

Apple HomeKey functionality for the rest of us

Documentation • Quick Start • Setup Guide • Discord

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

1. Download Firmware

   • Visit GitHub Releases
   • Download the *.firmware.factory.bin file
   • This contains everything you need - no compilation required!

2. 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

3. 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!

4. 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

5. 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

# 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 monitor

Contributions are welcomed! Please see the Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request against the main branch

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