HomeKey-ESP32

ESP32 HomeKit Lock with support for the HomeKey

Credit to @kormax for reverse-engineering the Homekey NFC Protocol and publishing a POC and credit to @kupa22 for the research on the HAP side of things, this project was possible thanks to their work. Additionaly, thanks to the Arduino library HomeSpan for being a great library that eased my work on HAP and other things and allowed me to just focus on the homekey functionality.

Overview

Only the PN532 is supported as an NFC module.

Only the FAST and STANDARD flows are implementated right now, the ATTESTATION flow will be implemented at a later time since STANDARD can be used in most cases
Lock State can be received and controlled via MQTT through user-defined topics
Any NFC Target that's not identified as homekey will skip the flow and at least at the moment it only just publishes the UID, ATQA and SAK to the same MQTT topic as homekey with the property homekey set to false
It is not made for battery-powered applications (yet)
Designed for a board with 4MB Flash size as OTA is enabled and it needs a second partition of the same size

The code still needs some working so it's very much a work in progress, but the main implementation is roughly there.

Goal of the project is to make it easy to add the homekey functionality to locks that don't support it or to anything for that matter :) .

Wiring

The current implementation is using SPI for communication.

Pins are the default Arduino pins for SPI which should be as follows:

GPIO18 - SCK

GPIO19 - MISO

GPIO23 - MOSI

GPIO5 - SS

Configuration

Currently the WiFi can only be configured from the terminal, though the library HomeSpan that this is based on also has the option of a hotspot but requires a button so haven't bothered with it.

WIFI

To connect it to WiFi there are two options

Open the serial terminal, press W + Return, and now it should start searching for networks from which to select.
Open the serial terminal, press A to start a temporary Access Point then connect to the Wifi network "HomeSpan-Setup" with the password homespan and if you are on a phone it should automatically open up the page where you can configure the Wifi credentials, alternatively you can access the page manually on http://192.168.4.1/hotspot-detect.html

HomeKit

The pairing code is the default 466-37-726 from the HomeSpan library that can be found in their documentation here. This can be changed at runtime from the terminal.

For any informations regarding the HomeKit implementation not related to the HomeKey feature, please see the repository for HomeSpan here where you will also found the documentation.

MQTT

In order to connect to your MQTT Broker, first create a file called mqtt.h in the src folder with the following content and modify it accordingly with your details

#define MQTT_HOST "0.0.0.0"
#define MQTT_PORT 1883
#define MQTT_CLIENTID "homekey_mqtt"
#define MQTT_USERNAME "username"
#define MQTT_PASSWORD "password"
#define MQTT_AUTH_TOPIC "topic/auth"
#define MQTT_SET_STATE_TOPIC "topic/set_state"
#define MQTT_SET_TARGET_STATE_TOPIC "topic/set_target_state"
#define MQTT_SET_CURRENT_STATE_TOPIC "topic/set_current_state"
#define MQTT_STATE_TOPIC "topic/state"

MQTT_AUTH_TOPIC is where authentication details will be published on success

MQTT_SET_STATE_TOPIC is the control topic that sets the current and target state of the lock

MQTT_SET_TARGET_STATE_TOPIC controls the target state of the lock

MQTT_SET_CURRENT_STATE_TOPIC controls the current state of the lock

MQTT_STATE_TOPIC is where changes to the lock state will be published.

On the MQTT_AUTH_TOPIC topic, the data format is as follows, depending whether a homekey was authenticated or just an NFC Target was sensed.

HomeKey

{
  "endpointId": "000000000000", # This is unique per device
  "homekey": true,
  "issuerId": "0000000000000000" # This is unique per Apple ID
}

ISO14443A card

{
  "atqa": "0004",
  "homekey": false,
  "sak": "08",
  "uid": "00000000"
}

OTA

Authentication is enabled and the default password is homespan-ota.

To upload via OTA, define the address of the ESP on the environment variable PLATFORMIO_UPLOAD_PORT and then use the PlatformIO environment ota,

If the default password is not used, you probably know what you are doing, however, a custom password can be used by setting the environment variable PLATFORMIO_UPLOAD_FLAGS to --auth=<ota-password>

jklap/HomeKey-ESP32