Skip to content

Pre 0.3 Setup

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

1. Configuration

Before we get to compile the code, we need to modify the config.h file located in the src folder.

The file should look like this

// Custom Lock States to be used in MQTT_CUSTOM_STATE_CTRL_TOPIC
enum customLockStates
{
  C_LOCKED = 1,
  C_UNLOCKING = 2,
  C_UNLOCKED = 3,
  C_LOCKING = 4,
  C_JAMMED = 254,
  C_UNKNOWN = 255
};
// Custom Lock Actions to be used in MQTT_CUSTOM_STATE_TOPIC
enum customLockActions
{
  UNLOCK = 1,
  LOCK = 2
};

// MQTT Broker Settings
#define MQTT_HOST "0.0.0.0" //IP adress of mqtt broker
#define MQTT_PORT 1883 //Port of mqtt broker
#define MQTT_CLIENTID "homekey_mqtt" //client-id to connect to mqtt broker
#define MQTT_USERNAME "username"  //username to connect to mqtt broker
#define MQTT_PASSWORD "password"  //password to connect to mqtt broker

//MQTT Flags
#define MQTT_CUSTOM_STATE_ENABLED 0 // Flag to enable the use of custom states and relevant MQTT Topics
#define MQTT_HOMEKEY_ALWAYS_UNLOCK 0 // Flag indicating if a successful Homekey authentication should always set and publish the unlock state
#define MQTT_HOMEKEY_ALWAYS_LOCK 0  // Flag indicating if a successful Homekey authentication should always set and publish the lock state

// MQTT Topics
#define MQTT_CUSTOM_STATE_TOPIC "topic/custom_state" // MQTT Topic for publishing custom lock state
#define MQTT_CUSTOM_STATE_CTRL_TOPIC "topic/set_custom_state" // MQTT Control Topic with custom lock state
#define MQTT_AUTH_TOPIC "topic/auth" // MQTT Topic for publishing HomeKey authentication data or RFID UID
#define MQTT_SET_STATE_TOPIC "topic/set_state" // MQTT Control Topic for the HomeKit lock state (current and target)
#define MQTT_SET_TARGET_STATE_TOPIC "topic/set_target_state" // MQTT Control Topic for the HomeKit lock target state
#define MQTT_SET_CURRENT_STATE_TOPIC "topic/set_current_state" // MQTT Control Topic for the HomeKit lock current state
#define MQTT_STATE_TOPIC "topic/state" // MQTT Topic for publishing the HomeKit lock target state

//Miscellaneous
#define HK_CODE "46637726"  //code used for homekit setup
#define LED_PIN 2 //status led pin, built in is pin 2
#define OTA_PWD "homespan-ota" //custom password for ota
#define NAME "HK Lock" //Device name
#define DISCOVERY 0 //Enable or disable discovery for home assistant tags functionality, set to 1 to enable.
#define CONTROL_PIN 26 // GPIO Pin for a Configuration Mode button (more info on https://github.com/HomeSpan/HomeSpan/blob/master/docs/UserGuide.md#device-configuration-mode)

You can see that each line has a comment(//) providing an explanation for what the value is for.

Each line is composed like so

#define MQTT_HOST "0.0.0.0"
/*  ^        ^        ^
    |        |        |
 Keyword    Name    Value
*/

What we need to do is amend the value by replacing the text enclosed in "" like so

#define MQTT_HOST "10.0.0.28"

For the values without quotes just replace the value.

2. Compiling

Believe it or not but this is actually the easiest step 😁.

If you are using PlatformIO IDE which is the VSCode extension of PlatformIO, all you need to do is the following:

  1. Open the Folder in VSCode
  2. Wait for PlatformIO to finish configuring the project, you should see a notification on the bottom right of the window with the progress
  • If it feels like it's taking forever, don't worry, it's not frozen or something, git is just slow at downloading sometimes for some of the dependencies for some reason
  1. Click the upload button located at the bottom of the window, it's the one with a right arrow ➡️

image

  1. A panel will open on the bottom of VSCode and the compilation should now start.
  2. Make yourself a cup of coffee ☕ 🙂, walk the dog 🐶 as this will take a minute depending on the processing power of your system

If everything went well you should see ${{\color{green}{\textsf{SUCCESS}}}}$.

If you are using PlatformIO Core, you probably know what you are doing, but either way, you just need to run platformio run -t upload

3. WIFI

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), more info about the Configuration Mode can be found on HomeSpan's wiki here

To connect it to WiFi there are three options

  • Open the serial terminal, press W + Return
    • 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 A 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

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

Clone this wiki locally