Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
rednblkx authored Mar 16, 2024
1 parent 24728a5 commit 777b6e1
Showing 1 changed file with 5 additions and 102 deletions.
107 changes: 5 additions & 102 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,115 +18,18 @@ While functional, **the project is still a work in progress so expect breaking c
Right now only the PN532 is supported as the NFC module, however, beware of cheap clones espcially clones of Elechouse's as it will cause issues, i recommend the Elechouse PN532 NFC Module V3 just make sure to buy from a trusted vendor.

- It integrates with HomeAssistant's Tags and can be used to create automations based on a person(issuer) or device(endpoint).
- Lock State is published and controlled via MQTT through user-defined topics
- The lock's state is published and controlled via MQTT through user-defined topics
- Any NFC Target that's not identified as homekey will skip the flow and publishes the UID, ATQA and SAK on the same Authentication MQTT topic
- It is not made for battery-powered applications (yet)
- It is not made for battery-powered applications due to the power hungry WiFi and the code not being optimized for this
- Designed for a board with an ESP32 chip and 4MB Flash size

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

The current implementation is using SPI for communication.
Please visit the [wiki](https://github.com/rednblkx/HomeKey-ESP32/wiki) for documentation on the project

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 either be configured from the terminal or with the help of the HomeSpan's Configuration Mode for which a GPIO pin needs to be assigned to a button(see [Configuration File](#configuration-file)), more info about the Configuration Mode can be found on HomeSpan's wiki [here](https://github.com/HomeSpan/HomeSpan/blob/master/docs/UserGuide.md#device-configuration-mode)

### WIFI

To connect it to WiFi there are three options
- Open the serial terminal, press <kbd>W</kbd> + <kbd>Return</kbd>
- Now it should start searching for networks and after a few seconds a list of names should appear from which you can select using their respective numbers or just type the name manually.
- Open the serial terminal, press <kbd>A</kbd> to start a temporary Access Point
- 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 once connected to the AP you can access the page manually on `http://192.168.4.1/hotspot-detect.html`
- Enter Configuration Mode by pressing the Control Button for 3 seconds, at which point the Status LED should begin to flash rapidly (10 times per second). Upon releasing the button the device will switch into the Device Configuration Mode.
- Press the button briefly two times(with a brief pause in-between) and the Status LED should now blink three times with a pause in-between indicating Action 3 is selected which is *Launch HomeSpan’s temporary WiFi network*
- Hold the button for 3 seconds to execute the action
- Same steps as when starting the AP from terminal apply, connect to the `HomeSpan-Setup` network with the password `homespan`

### HomeKit

The pairing code is the default `466-37-726` from the HomeSpan library that can be found in their documentation [here](https://github.com/HomeSpan/HomeSpan/blob/master/docs/UserGuide.md#pairing-to-homekit). 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](https://github.com/HomeSpan/HomeSpan) where you will also found the documentation.

### Configuration file

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

```cpp
#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"
#define HK_CODE "46637726"
#define LED_PIN 2
#define OTA_PWD "homespan-ota"
#define CONTROL_PIN 26
#define NAME "HK Lock"
#define DISCOVERY "1"
```
`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.
`HK_CODE` is the paring code for HomeKit
`LED_PIN` is the pin for the status led
`OTA_PWD` is the password for OTA
`CONTROL_PIN` is the pin for HomeSpan's Configuration Mode button
`NAME` is the name for the lock in HomeKit
`DISCOVERY` controls if [discovery](https://www.home-assistant.io/integrations/tag.mqtt/) messages for the [Home Assistant tag functionality](https://www.home-assistant.io/integrations/tag/) are send at startup, set to 1 to enable, 0 to disable.
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
```yaml
{
"endpointId": "000000000000", # This is unique per device
"homekey": true,
"issuerId": "0000000000000000" # This is unique per Apple ID
}
```
- ISO14443A card
```yaml
{
"atqa": "0004",
"homekey": false,
"sak": "08",
"uid": "00000000"
}
```

### OTA
## OTA

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

Expand Down

0 comments on commit 777b6e1

Please sign in to comment.