nuki-sesami 2.0.1

Open an electric door using Nuki smartlock status

Nuki Sesami

Open (and hold) an electric door equipped with an Nuki 3.0 Pro smart lock using a pushbutton and/or a smartphone using the Nuki Sesami app.

Overview

An electric door somehow needs to receive trigger signals for it to be opened, closed or held open. The Nuki Sesami package can perform this logic for you when using an ERREKA Smart Evolution Pro electric door controller in combination with an Nuki 3.0 Pro smart lock.

The door will be opened by the Nuki Sesami service when the smart lock is unlatched using the Nuki Smartlock app. After a brief moment the door will close again. The door can also be opened and held open by pressing a pushbutton connected to the Raspberry Pi board on which the Nuki Sesami service is running. When pressing this pushbutton again the door will be closed again. Finally the door can be opened, held open or closed using the Nuki Sesami smartphone app. Communication between the Nuki Sesami service and the Nuki 3.0 smart lock is achived using the mqtt protocol; e.g. by running a Mosquitto (mqtt) broker on the Raspberry Pi board.

Requirements

The following components are required when using this package:

• Nuki 3.0 Pro smart lock (or similar)
• ERREKA Smart Evolution Pro electric door controller (or similar)
• Raspberry Pi (or similar) with Raspbian BullsEye (or later) installed
• Waveshare RPi relay board (or similar)
• mqtt broker mosquitto, running on the same Raspberry Pi board
• Pushbutton connected to the relay board
• Android (v11+) smartphone with the Nuki Sesami app installed

Installation and setup

The package can be installed on the Raspberry PI board using following commands:

sudo apt update
sudo apt-get install -y python3-pip python3-gpiozero bluez pi-bluetooth
python3 -m venv --system-site-packages $HOME/nuki-sesami
source $HOME/nuki-sesami/bin/activate
pip3 install nuki-sesami

In order for nuki-sesami to be able to communicate with the Nuki smart lock, a Mosquitto broker must be running and configured. The bash script below can be used to install and configure the Mosquitto broker (on the same Raspberry Pi board):

#!/bin/bash
#
# Example script to setup a Mosquitto broker on a fresh RaspberryPi.
#
set -e -o pipefail

echo "[INFO] install packages and enable systemd service"
sudo apt update
sudo apt-get install -y mosquitto mosquitto-clients
sudo systemctl enable mosquitto.service

echo "[INFO] create passwords file"
sudo touch /etc/mosquitto/passwords
echo "nuki:secret1" | sudo tee -a /etc/mosquitto/passwords
echo "sesami:secret2" | sudo tee -a /etc/mosquitto/passwords
read -p "change passwords in /etc/mosquitto/passwords, press enter when done"
sudo mosquitto_passwd -U /etc/mosquitto/passwords

echo "[INFO] configure mosquitto; disallow anonymous access, set path to passwords file"
echo "listener 1883" | sudo tee -a /etc/mosquitto/mosquitto.conf
echo "allow_anonymous false" | sudo tee -a /etc/mosquitto/mosquitto.conf
echo "password_file /etc/mosquitto/passwords" | sudo tee -a /etc/mosquitto/mosquitto.conf
sudo systemctl restart mosquitto.service

echo "[INFO] verify if systemd services are running"
sudo systemctl status mosquitto.service

Once the Mosquitto broker is running, the Nuki smart lock can be configured to communicate with the Mosquitto mqtt broker using the Nuki Sesami app running on your smartphone:

• Go to the setting of your smart lock, by pressing Settings in the lower right of the screen
• Press Features & Configuration and select the MQTT feature
• Enable the MQTT feature and enter the following settings:
  • Host name: hostname of the Raspberry Pi board running the Mosquitto broker
  • User name: nuki
  • Password: nuki-password
  • Auto discovery: on
  • Allow locking: on

Verify the Nuki smart lock is able to communicate with the Mosquitto broker by using the following command on the Raspberry Pi board:

mosquitto_sub -h <mqtt-broker-hostname> -p 1883 -u sesami -P <sesami-password> -t nuki/DEVID/state

Where DEVID is the hexadecimal device ID; e.g. 3807B7EC, of the Nuki smart lock. The device ID can be found in the Nuki app under Settings > Features & Configuration > General.

Next step is to configure and start the Nuki Sesami systemd services, as presented in the example below:

device=${NUKI_SESAMI_DEVICE:-'3807B7EC'}
host=${NUKI_SESAMI_HOST:-'raspi-door'}
macaddr=${NUKI_SESAMI_BLUE_MACADDR:-'B8:27:EB:B9:2A:F0'}
channel=${NUKI_SESAMI_BLUE_CHANNEL:-4}
backlog=${NUKI_SESAMI_BLUE_BACKLOG:-10}
username=${NUKI_SESAMI_USERNAME:-'sesami'}
password=${NUKI_SESAMI_PASSWORD}
pushbutton=${NUKI_SESAMI_PUSHBUTTON:-'openhold'}

nuki-sesami-admin setup \
    -d $device \
    -H $host \
    -m $macaddr \
    -b $channel \
    -n $backlog \
    -U $username \
    -P $password \
    -B $pushbutton \
    --verbose

sudo systemctl restart nuki-sesami
sudo systemctl restart nuki-sesami-bluez

Next pair all smartphones with the Nuki Sesami app to the Raspberry Pi board running the Nuki Sesami services:

• Lookup the bluetooth address and name of your smartphone

• Ensure bluetooth is running the Raspberry pi board:

  • sudo systemctl status bluetooth.service

• Pair the smartphone with the Raspberry Pi board:

  • sudo bluetoothctl
  • power on
  • scan on
  • ensure the smartphone's bluetooth address is listed
  • scan off
  • pair <bluetooth-address>
  • trust <bluetooth-address>
  • scan on

Repeat steps above for all smartphones that need to be paired with the Raspberry Pi board.

Final step is to configure the ERREKA Smart Evolution Pro electric door controller to operate the electric door as per the Nuki smart lock state. In the BATS programming menu of the ERREKA door controller ensure the external switch for manual changing the operating mode is activated:

• Function FC01 == OFF, the door will be in open/close mode when switch is in position I
• Function FC07 == ON, the door will be in open and hold mode when switch is in position II

Use wiring connection as depicted in the diagram below:

Door controller operation

Once the system has been setup as described above, the smartlock can be operated as per usual using the Nuki smartphone app and/or other Nuki peripherals; like for instance the Nuki Fob. As soon as the smartlock state changes from unlatching to unlatched the electric door will be opened by means of the relay board using a short on/off puls on Relay CH1.

The relay board can also be operated manually using a pushbutton. This is useful when the door needs to be opened without the Nuki app or Nuki peripherals and/or change the door operating mode. The pushbutton logic can be as follows:

• pushbutton-openhold When pressing the pushbutton once the smartlock will be unlatched and the door will be opened and held open (openhold mode) until the pushbutton is pressed again (default logic).

• pushbutton-open When pressing the pushbutton once the smartlock will be unlatched and the door will be opened. After a few seconds the door will automaticaly be closed again.

• pushbutton-toggle When pressing the pushbutton once the smartlock will be unlatched and the door will be opened. If during the opening phase the pushbutton is pressed again, the door will be kept open (openhold mode) until the pushbutton is pressed again. Otherwise the door will be closed again after a few seconds.

Please note that when the system starts up, the door will be in open/close mode; i.e. Relay CH3 will be active and Relay CH2 will be inactive. This is to ensure the door can be opened and closed as per usual. When the system is in in openhold mode the relay states will be flipped; i.e. the Relay CH3 will be inactive and Relay CH2 will be active.