This is a quick guide for how to set up an August Smart Lock Pro for use with Home Assistant using only locally hosted open source software.
This is a nice solution if you already have a deadbolt with a manual key-less toggle on the inside of the door since installation takes about two minutes and you don't loose the manual toggle capability even if the batteries die.
The initial setup process if full of badness (identity verification, cloud bullshit and location data) but after the one-time setup it will run locally with just z-wave and no proprietary or cloud stuff.
The August lock uses four AA batteries. They recommend non-rechargable batteries (probably due to the discharge curve for AA being better for correlating voltage with battery level and warning users about low battery before it's too late).
Note that you will need a bunch of non-free terrible software for the initial setup and to change certain settings. Specifically you will need an iOS or Android device with bluetooth, internet and in case of Android, the Google Play Store. I haven't experimented with installing the August Home app on a de-googlefied android but I doubt it would work. Maybe with microG.
For initial calibration and setup you will need the August Home app and this requires a (free as in beer) August account which requires both phone number (SMS) and email verification. It will also require your location (GNSS). All of this of course horrible and makes me not want to support this company at all. Even worse, if you use their August Connect WiFi bridge then their tech support has the ability to remotely factory reset your lock, which almost certainly means that they they literally have a backdoor to your house. Who knows if the terms of service allows them to open the door for e.g. law enforcement without your consent or a warrant? Certainly not me since I havne't read it.
Luckily you will not need the August Connect WiFi bridge at any point so while they might still have a bluetooth and/or z-wave backdoor in the device at least physical presence is required.
Unfortunately it seems like it's impossible to turn off bluetooth functionality. It might be possible to open the lock, find the bluetooth antenna (probably shared with the wifi antenna we don't need but probably not shared with the z-wave antenna that we do need) and cover it in foil or something. What good would it do? Well if there is a bluetooth based backdoor then only e.g. a phone and custom software would be required. If only a z-wave based backdoor is available then something running August's custom software and having z-wave capability would be needed.
- August Smart Lock Pro 3rd gen
- Aeotec Z-Stick Gen5
- Linux box with USB port
You will need Python 3.8 or later. The latest Debian Stable as of this writing (Bullseye) has Python 3.9
The official install guide for home-assistant assumes a Debian based system.
This guide assumes that you do not want to run Home Assistant in a VM. You will want to follow the installation instructions for the so-called Home Assistant Core.
To auto-start home-assistant with systemd place the following in /etc/systemd/system/homeasssistant.service:
[Unit]
Description=Home Assistant
After=network-online.target
[Service]
Type=simple
User=homeassistant
ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"
[Install]
WantedBy=multi-user.target
Then:
systemctl enable homeassistant
systemctl start homeassistant
You will probably want to set up TLS with a self-signed cert but that is not covered in this guide
Home-assistant talks to Z-Wave devices through a Z-Wave JS server that listens on local port 3000.
The z-wave usb device should show up at /dev/ttyACM0 or similar. First you'll need to create a user and grant it access to serial ports:
useradd -rm zwave-js
usermod -a -G dialout zwave-js
Now install npm (node package manager):
sudo apt install npm
Then become the zwave-js:
sudo su -l zwave-js
and install the Z-Wave JS server:
npm install -g @zwave-js/server
Unfortunately it seems someone messed up and the package.json for the Z-Wave JS server is missing quite a few dependencies.
To fix this, repeatedly try to start the server and then npm -g install <name of missing package> until it successfully starts. The command to start the server is:
zwave-server /dev/ttyACM0
Make sure you do this only as the zwave-js user or you will run into permission issues later.
Once it is successfully starting you will need a config file with security keys for you z-wave devices. Create the file /etc/zwave-js.conf.js with content like:
module.exports = {
securityKeys: {
S2_Unauthenticated: Buffer.from([0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0]),
S2_Authenticated: Buffer.from([0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0]),
S2_AccessControl: Buffer.from([0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0]),
S0_Legacy: Buffer.from([0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0, 0xf0])
}
};
Replace all of the 0xf0 values with random values. Don't use the same values for the four different keys. You should keep a backup of this file somewhere.
Create the file /etc/systemd/system/zwave-js.service with the contents:
[Unit]
Description=zwave-js
After=network-online.target
[Service]
Type=simple
User=zwave-js
ExecStart=/usr/local/bin/zwave-server --config /etc/zwave-js.conf.js /dev/ttyACM0
[Install]
WantedBy=multi-user.target
Replace "/path/to/zwave-server" with the output of whereis zwave-server. Make sure you run that command as the zwave-js user.
Now you might want to run zwave-server manually using the command from ExecStart= while you're running through the Configuration section below but after you're done, tell systemd to auto-start zwave-js:
systemctl enable zwave-js
systemctl start zwave-js
Log into the home-assistant web interface. There will be a first run setup process. It should be running at http://:8123
Go to Configuration -> Integrations. Click Add Integration then find Z-Wave JS and add it. It will ask for the address where your ZWave JS server is listening. The defaults should be correct if you followed this guide.
Get the August Home app from the apple/google app stores on a device with bluetoooth and internet. Walk through the account setup process, then add your lock and walk through the calibration.
Now in the August Home app go to your lock's settings. Scroll to the bottom and click "Device Information". Write down the first five digits of your Device DSK. In fact put those digits in your copy-paste buffer on the device you're using to access home-assistant since you will have to input it within a short time window.
Go back to the lock settings again, then click "Z-Wave Settings".
Now, in home-assistant, in Configuration -> Integrations, click "Configure" under Z-Wave JS. Click "Add Device".
Now, before you click anything else know that as soon as you follow the next step you will have to be ready to input the 5-digit code from before into home-assistant _quickly).
In the August Home app click the button to proceed. Home-assistant will pop up a dialog asking for a 5-digit code. Paste the code from before and click next as fast as you can. If you get an error in the August Home app saying specifically that the device was added with S0 security or low security or something to that effect then you weren't fast enough. You will have to wait for the device to finish adding in home-assistant, then remove the device and then try again to add it. If you get any other error in the August Home app, like "can't connect to device" or something to that effect then don't worry about it.
Now wait for home-assistant to finish adding your lock. This will take a minute or two as it is interrogating the device in various ways. If you are running ZWave-JS server manually in a terminal at terminal at the moment then you should see this interrogation happening.
Once it is done, go to Overview in home-assistant and you should see your lock with a link saying LOCK or UNLOCK. Try to click it. Leave 5-10 seconds between clicks to lock and unlock.
Now you are not done. There is a weird bug which happens to some people where the lock will only respond to one lock/unlock command and then refuse to respond to any other lock/unlock commands (but respond fine to status queries) until the lock has either been locked/unlocked from the August Home app (using bluetooth) or the door closed/open or locked/unlocked state has been changed manually. The odd thing is that this bug goes away when the August Home app is running and linked to the lock, so first put the device with the August Home app in airplane mode (or turn it off).
Now try to lock and unlock repeatedly from home-assistant, again leaving 5-10 seconds in between each attempt. If it keeps working then you are all done.
If it doesn't keep working then use then in home-assistant go to Configuration -> Integrations. Under Z-Wave JS click Configure, then Remove Device and use the August Home app (remember to enable bluetooth) to go into the lock settings and click the Z-wave settings. This will let you disassociate the lock from the z-wave controller.
Now shut down Z-wave JS and home-assistant:
sudo systemctl stop zwave-js
sudo systemctl stop homeassistant
In the August Home app, in the lock settings, click the Factory Reset option. You will have to re-add the lock and run through the calibration procedure again.
After this is done, start zwave-js and homeassistant:
sudo systemctl start zwave-js
sudo systemctl start homeassistant
Follow the procedure from before to re-add the lock as a z-wave device in home-assistant.
This disassociate -> factory reset -> reassociate process solved the issue for me and at least one other person.