Skip to content

Configuration

Jump to bottom
White Red edited this page Oct 7, 2024 · 1 revision

Important

The project is primarily using MQTT for updating the internal state of the lock and exclusively for sending resulting homekey data.

However, there are some simple GPIO implementations so it can be used without MQTT.

Additionally, HomeKey is not directly linked to the state of the lock and the project is not configured to manipulate the state of the lock upon the usage of homekey by default, however, there are some options implemented for it.

1. Introducing the Web UI

The Web Interface is where you can configure everything for this project(except for the WiFI 😁)

Web UI

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.

1.1. HK Info

HomeKey Info

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 one Endpoint 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.

1.2 MQTT

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:

1.2.1. Broker Connection

MQTT Broker

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 with XXXXXX 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 of online. In the case of the device disconnecting from the broker, this topic will then contain the payload offline 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.

1.2.1. MQTT Topics

MQTT Topics

This subsection is divided into two parts:

§ 1. Core Topics

  • 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

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

  • 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

Tip

Some of you might be asking, "what is the difference between the last 3 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

§ 2. Custom State Topics

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 in Custom Lock Actions
  • MQTT Custom State Cmd Topic is the command topic for the homekit lock entity linked to the states defined in Custom 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.

1.3 Actions

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

1.3.1 HomeKey/NFC Triggers

HomeKey/NFC Triggers

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.

1.3.2 HomeKit/HomeKey Triggers

HomeKit/HomeKey Triggers

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 an optional momentary state option.

Important

Simple GPIO is only configured as output and once active(by assigning a GPIO Pin) the lock entity efectively becomes a dumb switch

Note

The HK Momentary State is only relevant for the HomeKey, this won't affect the HomeKit interaction from the Home App.

When using the HomeKey without the momentary state, the state of the lock entity is 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

1.4 Miscellaneous

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:

1.4.1 HomeKit

HomeKit Configuration

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

The device name field affects the name displayed on the Home app and on Home Assistant.

Always Lock on HomeKey and Always Unlock on HomeKey options function as per the name, this will always set the lock entity state to LOCKED or UNLOCKED upon a succesful HomeKey authentication and also applies to HomeKit/HomeKey Triggers Simple GPIO

1.4.2 WebUI

Web UI Configuration

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)

1.4.3 HomeSpan

HomeSpan Settings

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.

2. Home Assistant

The project also provides an easy and seamless integration with Home Assistant through MQTT and its MQTT Integration.

2.1 Device 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.

HASS Device Page

This makes it easier to create automations based on this lock entity opposed to using directly the MQTT Topics.

2.2 Tags

An integration with Home Assistant's Tags is also available, from where you can easily create an automation based on HomeKey or an regular NFC Tag.

Tags Page

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

2.3 Automations

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.

2.3.1 Lock State Synchronization

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

Physical Lock -> HomeKit Lock

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

NFC Lock -> 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

2.3.2 HomeKey Automations

This can be done in two ways(two triggers):

  1. using the MQTT Topic trigger

alt text

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

alt text

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

3. I did not understand a thing from here :)

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.

Clone this wiki locally