-
Notifications
You must be signed in to change notification settings - Fork 34
Configuration
Important
Make sure to choose the color of the Wallet card in the HomeKit section before pairing if you care about it
The project is primarily using MQTT for updating the internal state of the lock and exclusively for sending resulting homekey data.
If you wish to use HomeKit Automations exclusively, make sure to enable the "Dumb Switch Mode" in the Misc section
Note that HomeKey is not linked to the state of the lock and so the lock state would not change upon usage of the HomeKey. For this you have the following options:
- Configure an automation using the MQTT Topics through your favorite automations system (see examples for HASS in Automations chapter)
- Configure GPIO pins in the Actions section.
- Enable
Always Unlock on HomeKey
orAlways Lock on HomeKey
which make sure to always set the lock state toUnlocked
orLocked
upon using HomeKey. Note if using HomeKit Automations, it will not trigger if the lock is already in the desired state.
The Web Interface is where you can configure everything for this project(except for the WiFI 😁)
This interface can be accessed over the ip address of the ESP32 on port 80.
It is divided into 4 major sections:
- HK Info - Here you'll find essential informtion of HomeKey
- MQTT - In this section you can configure the connection to the MQTT Broker and each individual MQTT Topic
- Actions - This is where you can configure a Neopixel or just a simple GPIO pin
- Misc - Here you'll find settings like Web Authentication, HomeKey color, Device name, etc.
Nothing to be configured here, however, it is important to check that all the data is present.
- Both the Reader GID and Reader ID have to be present after pairing
Note
The Reader GID
is shared with the other HomeKey readers in the Apple Home while the Reader ID is unique per reader
- There should be one
Issuer ID
for each person in your Apple Home and oneEndpoint ID
for each of their devices(iPhone, Watch).
Note
Don't worry if the Endpoint ID
is missing for all/some devices, it will be created on NFC Contact if that didn't happen during pairing.
Tip
The Apple Watch might take a couple of minuted to sync the configuration, wait until you get the "Express Mode enabled" notification on it at which point the HomeKey on the Watch can be used. Alternatively you can try adding the key from the Watch app or try to reboot it.
Project relies on the MQTT protocol to make the data like homekey identification data or lock state and control available to you.
This section is divided into two subsections as follows:
-
Broker Connection
- Configuration of the MQTT Broker Connection -
MQTT Topics
- Configuration of the MQTT Topics
This is where you can configure the connection to your MQTT Broker.
- Client ID is used to identify this device within MQTT and by default has the format of
ESP32_XXXXXX
withXXXXXX
being replaced by the last 3 bytes of the mac address - The
LWT Topic
is used to set the topic for MQTT LWT(Last Will and Testament) which helps determine the status of the mqtt connection. While connected this topic will have the payload ofonline
. In the case of the device disconnecting from the broker, this topic will then contain the payloadoffline
thereby informing any participants that this device is now unavailable - The
HASS MQTT Discovery
option is enabled by default and provides discoverability and integration within Home Assistant through its MQTT integration
Tip
The LWT Topic is used in conjuction with HASS MQTT Discovery, if the device in HASS is Unavailable
, check that this topic is not restricted by your MQTT ACL rules.
This subsection is divided into two parts:
-
Core Topics
which provides the main functionalities -
Custom State Topics
that provide some personalized control of the Lock entity
-
NFC/HK Topic
is is a subscribable topic where the resulting HomeKey data(issuer id, endpoint id, reader id) or the UID, ATQA and SAK of a detected NFC Tag is publlished in JSON format-
{"issuer_id": "0123456789ABCDEF", "endpoint_id": "0123456789AB", "reader_id": "0123456789ABCDEF", "homekey":true}
- HomeKey payload -
{"uid": "012345678","atqa": "04", "sak": "20", "homekey":false}
- Regular NFC Tag Payload
-
-
Ignore NFC Tags
is option to prevent publishing data of detected NFC Tags -
Lock State Topic
is a subscribable topic where the new state of the homekit lock entity can be received- The possible values are as follows:
-
0
- UNLOCKED -
1
- LOCKED -
2
- JAMMED -
3
- UNKNOWN -
4
- UNLOCKING -
5
- LOCKING
-
[!NOTE] State is not published upon using HomeKey, except if "Always Unlock/Lock on HomeKey"(Misc section) is enabled or if "HomeKit/HomeKey Triggers" (Actions section) is used.
- The possible values are as follows:
-
Lock State Cmd Topic
is a command topic that changes the current and target state of the lock entity -
Lock Current State Cmd Topic
is a command topic that only changes the current state of the lock entity -
Lock Target State Cmd Topic
is a command topic that only changes the target state of the lock entity -
SmartLock battery level Cmd Topic
is a command topic that changes the battery level shown in the Home app, useful if your smart lock doesn't have HomeKit support or if it has HomeKit support but doesn't show the battery level in the Home app
Tip
Some of you might be asking, "what is the difference between the 3 lock state cmd topics?"
HomeKit implements a target data architecture, which results in a present-future type of state that requires for the future to be validated in order to become the present.
For short, the current state
is the actual present state and the target state
is the state we want but there is transitional validation phase in-between
For example, say we have a Lock, currently the state of it is LOCKED
and we want it to be UNLOCKED
, however, before it transitions to UNLOCKED
, it has to go through UNLOCKING
execute any business logic there is(e.g. turning a motor) and if successful then it can become UNLOCKED
, if not it returns to being LOCKED
or just stays stucked in the UNLOCKING
state.
Important
When interacting with the Lock in the Home App, only the target state is being set, which means the current state has to be set through the Lock Current State Cmd Topic
or Lock State Cmd Topic
in order to complete the cycle, otherwise it will get stuck to Locking... / Unlocking...
Note
The Lock within HASS uses the Lock State Cmd Topic
which means it skips the transitional phase and instantly changes the state from LOCKED
to UNLOCKED
This was initially developed to directly control a Nuki lock via its MQTT API and due to this the default values match the ones in Nuki's MQTT API documentation to lock and unlock.
-
MQTT Custom State Topic
is the subscribable topic of the homekit lock entity linked to the states defined inCustom Lock Actions
-
MQTT Custom State Cmd Topic
is the command topic for the homekit lock entity linked to the states defined inCustom Lock States
Note
Upon successful Homekey authentication, the flipped lock state will be published on the MQTT Custom State Topic
according to the set Custom Lock Actions
if MQTT Custom States
is enabled.
Actions is where you can define a GPIO Pin to be actioned(LOW/HIGH) on the following events:
- HomeKey Authentication Success or Fail
- NFC Tag Detection
- Home App interaction
Additionally, you have the option to attach one Neopixel that can lit up on the following events:
- HomeKey Authentication Success or Fail
- NFC Tag Detection
This section is divided into two subsections as follows:
-
HomeKey/NFC Triggers
- GPIO Actions to be executed when using the HomeKey or on NFC Tag detection -
HomeKit/HomeKey Triggers
- GPIO Actions to be executed when using the HomeKey or when interacting with the Lock from the Home App
Tip
Setting any GPIO Pin field to 255 disables the associated option
This was mainly intended as a way to provide feedback on interaction such as lighting up an LED hence the inclusion of Neopixel and has been kept like this.
Both the Neopixel and Simple GPIO are actioned whenever the HomeKey is used regardless if that is successful or not as you can assign a a GPIO pin or a Neopixel color for each event(success/failure).
Note
Any regular NFC Tag detection will also trigger the actions here and is treated as Auth Failure
.
The Simple GPIO is meant to provide a link between the Lock in the Home App and a GPIO Pin with the addition of it also being used for a successful HomeKey Authentication separate from the above HomeKey/NFC Triggers
and it implements an optional momentary state option.
Important
Simple GPIO is only configured as output and once enabled(by assigning a GPIO Pin) the lock entity efectively becomes a dumb switch
Note
The Momentary State
has 4 options depending on when you wish to be used:
- Disabled
- Home App Only
- HomeKey Only
- Home App + HomeKey Only
When using the HomeKey without the momentary state, the state of the lock entity is just flipped instead unless "Always Lock/Unlock on HomeKey" is enabled in the Misc section
Tip
You can a assign an unused(or random if none are used) GPIO Pin which will make the lock entity act as a dumb switch(meaning no MQTT needed) and usage of HomeKey will be toggling the lock state
Here is where you can expect to find any other settings related to various aspects of the project.
This is divided into three subsections as follows:
Tip
Make sure to set the "HomeKey Card Finish" before pairing to ensure that it is reflected in the Wallet as it is not clear what is the refresh cycle for it when added after pairing
Note
The device name field affects the name displayed on the Home app and on Home Assistant.
Additionally, if you have set the setup code from the AP page it will not be reflected on this page due to the internal workings of HomeSpan
-
Always Lock on HomeKey
andAlways Unlock on HomeKey
options function as per the name, this will always set the lock entity state toLOCKED
orUNLOCKED
upon a succesful HomeKey authentication and also applies toHomeKit/HomeKey Triggers
Simple GPIO -
Dumb Switch Mode
will make the Lock/Unlock button in the Home app change state without any external validation as it is explained in the MQTT chapter -
SmartLock battery reporting
adds the battery characteristic of HomeKit so you can see the battery level in the Home app that is received on the respective MQTT Topic (see MQTT Topics)
Not much to say about this, here you can choose the GPIO Pins used to communicate with the PN532.
At the moment this only includes the option to enable Authentication for Web Interface.
All endpoints are protected by authentication except for the reboot endpoint (GET /reboot_device
)
This project uses a fork of HomeSpan 1.9.1 as the HomeKit framework and here you can find a couple of options that you can set for it.
The OTA Password is used to authenticate an OTA Update, more info in Updates, defaults to homespan-ota
Recommend reading HomeSpan's documentation for the Control Pin and Status LED.
The project also provides an easy and seamless integration with Home Assistant through MQTT and its MQTT Integration.
If you are a HASS user, you can enable the HASS MQTT Discovery
option in the MQTT
section, this provides the ability for the device to be discovered and integrated into HASS via MQTT using its MQTT integration.
This makes it easier to create automations based on this lock entity opposed to using directly the MQTT Topics.
An integration with Home Assistant's Tags is also available, from where you can easily create an automation based on HomeKey or a regular NFC Tag(unless disabled in the MQTT Topics section).
Important
Everytime you scan a HomeKey, you'll notice that two tags would appear.
The tag with the longer ID is unique per person(Apple ID) and the shorter one is unique per device(iPhone, Watch)
Those IDs can be cross-examined with the IDs that are available in the HK Info
section of the web interface
Tip
Tags can be given a name to easily recognizable as can be seen in the screenshot
Click on the cog icon for the respective tag and from there you can update the name
There are many ways that you may want to create your automations depending on what are your needs, however, in this section it will hopefully give you a starting point.
We start with the syncronization of the state between your real lock the virtual/dummy lock entity from HomeKit.
This is of course optional if you have no use for the lock entity, especially if you already have your lock in HomeKit but since HomeKey without adding a lock is not possible, might as well make it usable rather than just hanging around.
§1 Synchronizing physical lock -> HomeKit lock entity
alias: NFC Lock State change
description: ""
trigger:
- platform: state
entity_id:
- lock.hk_lock_2
condition:
- condition: template
value_template: >-
{{ not( now() - state_attr('automation.nfc_lock', 'last_triggered') <
timedelta(seconds=10)) }}
action:
- if:
- condition: state
entity_id: lock.hk_lock_2
state: unlocked
then:
- action: lock.unlock
metadata: {}
data: {}
target:
entity_id: lock.l600137
else:
- if:
- condition: state
entity_id: lock.hk_lock_2
state: locked
then:
- action: lock.lock
metadata: {}
data: {}
target:
entity_id: lock.l600137
mode: single
§2 Synchronizing HomeKit -> Physical Lock
alias: NFC Lock State change
description: ""
trigger:
- platform: state
entity_id:
- lock.hk_lock
from: null
to: null
condition:
- condition: template
value_template: >-
{{ not( now() - state_attr('automation.nfc_lock', 'last_triggered') <
timedelta(seconds=10)) }}
action:
- if:
- condition: state
entity_id: lock.hk_lock
state: unlocked
then:
- action: lock.unlock
metadata: {}
data: {}
target:
entity_id: lock.l600137
else:
- if:
- condition: state
entity_id: lock.hk_lock
state: locked
then:
- action: lock.lock
metadata: {}
data: {}
target:
entity_id: lock.l600137
mode: single
Tip
The condition in those automations is used to prevent a trigger loop where the state update resulted from one automation creates a trigger for the other and vice-versa
This can be done in two ways(two triggers):
- using the MQTT Topic trigger
alias: Homekey
description: ""
trigger:
- platform: mqtt
topic: topic/homekey/auth
condition:
- condition: template
value_template: "{{trigger.payload_json[\"issuer_id\"] == \"0123456789ABCDEF\"}}"
action:
- if:
- condition: state
entity_id: lock.l600137
state: locked
then:
- action: lock.unlock
metadata: {}
data: {}
target:
entity_id: lock.l600137
else:
- action: lock.unlock
metadata: {}
data: {}
target:
entity_id: lock.l600137
mode: restart
- using the Tag trigger
Note
This still relies on MQTT under the hood therefore the MQTT integration is needed , however, it's a more easily accessible option than using the MQTT Topic directly
description: ""
mode: single
trigger:
- platform: tag
tag_id: 0123456789ABC
condition: []
action:
- if:
- condition: state
entity_id: lock.l600137
state: locked
then:
- action: lock.unlock
metadata: {}
data: {}
target:
entity_id: lock.l600137
else:
- action: lock.unlock
metadata: {}
data: {}
target:
entity_id: lock.l600137
alias: Tag Red's Watch is scanned
I'm always looking to improve the project and its accompanying documentation so if there is anything that you are struggling with or do not understand after reading the docs, please open an issue or reach out on the Discord server https://discord.com/invite/VWpZ5YyUcm and i'll try to help you out if i can.