Nuki Bridge Firmware Arduino Framework
This configuration inherits all features from the Stock Firmware and adds a Nuki Bridge component via BLE. Note that it does not support Improv via Bluetooth LE, as the BLE stack is used by the Nuki Bridge component.
Update Firmware
There are several ways to update the firmware:
- ESPHome OTA Requires ESPHome Dashboard
- HTTP OTA Latest release build, no customization
- Web Serial Latest release build, no customization
You can connect your Doorman via USB-C and click the button below to install the latest Doorman Nuki Bridge Firmware (Home Assistant) directly through Web Serial. To use the MQTT firmware, adopt Doorman into your ESPHome Dashboard and apply the MQTT Example Firmware YAML.
Firmware YAML
This is the minimal ESPHome configuration YAML file for use with Home Assistant. Be sure to update the API key.
Minimal Nuki Bridge Firmware (Home Assistant)
# Doorman S3 Nuki Bridge Firmware
# You can change a few options here.
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# log_level: "ERROR"
# led_pin: "GPIO1"
# rgb_led_pin: "GPIO2"
# relay_pin: "GPIO42"
# external_button_pin: "GPIO41"
# Import Doorman Nuki Bridge Firmware Config
packages:
AzonInc.Doorman-Nuki-Bridge: github://AzonInc/doorman/firmware/ha-doorman-nuki-bridge.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
This is the minimal ESPHome configuration YAML file for use with MQTT. Be sure to update the Broker details.
Minimal Nuki Bridge Firmware (MQTT)
# Doorman S3 Nuki Bridge Firmware (MQTT)
# You can change a few options here.
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# log_level: "ERROR"
# led_pin: "GPIO1"
# rgb_led_pin: "GPIO2"
# relay_pin: "GPIO42"
# external_button_pin: "GPIO41"
# Import Doorman Nuki Bridge Firmware Config
packages:
AzonInc.Doorman-Nuki-Bridge: github://AzonInc/doorman/firmware/mqtt-doorman-nuki-bridge.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
mqtt:
broker: 10.0.0.2
username: "mqtt"
password: "password"
Pairing your Nuki Lock
Depending on the PCB revision, either press the FLASH or PRG button on the Doorman PCB for 5 seconds until the status LED starts flashing purple, or enable the Nuki Pairing Mode switch in Home Assistant. Then, press the button on your Nuki Lock for 5 seconds until the light ring turns on.
After a successful pairing, the status LED will remain steadily on for 3 seconds.
WARNING
If your Nuki Lock is already paired, this process will unpair it!
Unpairing your Nuki Lock
You can unpair your device using either the Nuki Unpair Device
button in Home Assistant or the physical FLASH
or PRG
button on the Doorman PCB.
Physical Button
If your lock is already paired with Doorman, press the FLASH
or PRG
button on the Doorman PCB for 5 seconds until the RGB status LED starts flashing purple. Your Nuki Lock will then be unpaired. Note that the pairing mode will time out after 30 seconds.
Examples
Create a simple TC Command Binary Sensor
You can easily add additional binary sensors for any TC Command, alongside the preconfigured ones.
Command Builder:
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
binary_sensor: // //
- platform: tc_bus // [!code ++] // [!code focus]
name: "Custom Command" // //
type: open_door // [!code ++] // [!code focus]
address: 0 // [!code ++] // [!code focus]
web_server: // //
sorting_group_id: sorting_group_listeners // [!code ++] // [!code focus]
32-Bit Commands:
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
binary_sensor: // //
- platform: tc_bus // [!code ++] // [!code focus]
name: "Custom Command" // //
command: 0x00001100 // [!code ++] // [!code focus]
web_server: // //
sorting_group_id: sorting_group_listeners // [!code ++] // [!code focus]
Controlling the internal RGB Status LED
If you want to control the onboard RGB LED with a button (for example), simply use the Light ID: doorman_rgb_status_led
.
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
button: // //
- platform: template // [!code ++] // [!code focus]
name: "Turn on Status RGB LED to red" // //
on_press: // //
- light.turn_on: // //
id: doorman_rgb_status_led // [!code ++] // [!code focus]
red: 100% // [!code ++] // [!code focus]
green: 0% // [!code ++] // [!code focus]
blue: 0% // [!code ++] // [!code focus]
Use the External Hardware Button
If you want to use the external button to trigger automations, you can simply extend your YAML configuration.
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
binary_sensor: // //
- id: !extend doorman_external_button // [!code ++] // [!code focus]
on_press: // //
- logger.log: "External button pressed!" // //
Use I²C Sensors
If you want to add sensors via the I²C bus, you can use the two available GPIO pins and add the I²C component to your configuration. You can then attach your sensors to these two I²C GPIO pins.
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
i2c: // //
sda: GPIO40 // [!code ++] // [!code focus]
scl: GPIO48 // [!code ++] // [!code focus]
scan: true // [!code ++] // [!code focus]
id: i2c_bus // [!code ++] // [!code focus]
Advanced Examples
Home Assistant
Sending Bus commands
You can use Home Assistant actions (formerly known as services) to send commands on the bus. Either use the command
to send raw commands or type
, address
, payload
and serial_number
to send commands via the command builder.
INFO
Remember to include the leading 0x
when calling the action with the command
property. If you omit it, you'll need to convert the HEX command to a decimal number first.
Command Builder:
service: esphome.doorman_s3_send_tc_command
data:
type: open_door
address: 0
payload: 0
serial_number: 123456
Hexadecimal Commands via command
:
service: esphome.doorman_s3_send_tc_command_raw
data:
command: 0x11E24080
Listening for ESPHome events
Doorman will send esphome.doorman events to Home Assistant every time a command is received.
Each event is structured as follows:
event_type: esphome.doorman
data:
device_id: 373c62d6788cf81d322763235513310e
command: "00001100"
type: "open_door"
address: "0"
payload: "0"
serial_number: "0"
origin: LOCAL
time_fired: "2024-08-12T12:34:13.718317+00:00"
context:
id: 01J5399Y2PP2XS2VRYKBT3H3AV
parent_id: null
user_id: null
Automation Example (HEX Command):
alias: Trigger on Doorman TC Open Door Command
description: ""
trigger:
- platform: event
event_type: esphome.doorman
event_data:
command: "00001100"
condition: []
action: []
mode: single
Automation Example (Command Builder):
alias: Trigger on Doorman TC Open Door Command
description: ""
trigger:
- platform: event
event_type: esphome.doorman
event_data:
type: "open_door"
condition: []
action: []
mode: single
ESPHome
Create Your Own Doorbell Pattern
If you want to create a custom doorbell pattern, you can easily extend the existing doorbell entities. For more information about patterns, refer to the ESPHome Docs.
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Extend the doorbell_pattern event entity // //
# Add a new apartment_special event type // //
event: // //
- id: !extend apartment_doorbell_pattern // [!code ++] // [!code focus]
event_types: // //
- "apartment_special" // //
# Extend the apartment_doorbell / entrance_doorbell entity // //
# and add your new special pattern // //
binary_sensor: // //
- id: !extend apartment_doorbell // [!code ++] // [!code focus]
on_multi_click: // //
# Special Pattern // //
- timing: // //
# Press twice with no more than one second between each press. // //
- ON for at most 0.5s // [!code ++] // [!code focus]
- OFF for at most 1s // [!code ++] // [!code focus]
- ON for at most 0.5s // [!code ++] // [!code focus]
- OFF for at least 2s // [!code ++] // [!code focus]
then: // //
- logger.log: "Special pattern detected!" // //
- event.trigger: // //
id: apartment_doorbell_pattern // [!code ++] // [!code focus]
# Use the previously defined new event type here // //
event_type: apartment_special // [!code ++] // [!code focus]
Turn on the light when someone rings the entrance doorbell
You can turn on the light when someone rings the entrance doorbell.
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
binary_sensor: // //
- id: !extend entrance_doorbell // [!code ++] // [!code focus]
on_press: // //
- tc_bus.send: // //
type: "light" // //
If you want to account for the sun's elevation as well, you can adjust it accordingly.
# Doorman S3 Firmware
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
# Import Doorman Stock Firmware Config
packages:
AzonInc.Doorman: github://AzonInc/doorman/firmware/doorman-stock.yaml@master
esphome:
name: ${name}
name_add_mac_suffix: false
friendly_name: ${friendly_name}
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
# Import the Home Assistant sun elevation sensor // //
sensor: // //
- platform: homeassistant // [!code ++] // [!code focus]
id: sun_elevation // [!code ++] // [!code focus]
entity_id: sun.sun // [!code ++] // [!code focus]
attribute: elevation // [!code ++] // [!code focus]
# Extend the entrance doorbell sensor // //
binary_sensor: // //
- id: !extend entrance_doorbell // [!code ++] // [!code focus]
on_press: // //
# Sun elevation is <= 0 (dark) // //
- if: // //
condition: // //
sensor.in_range: // //
id: sun_elevation // [!code ++] // [!code focus]
below: 1 // [!code ++] // [!code focus]
then: // //
# Turn on the light // //
- tc_bus.send: // //
type: "light" // //
MQTT
When using the MQTT firmware, various topics are published to your broker. Here's how the topic structure and controls work.
Topic Structure
Each entity publishes its state to a topic in the following format:
<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/state
You can control certain entities by publishing a command to this topic format:
<TOPIC_PREFIX>/<COMPONENT_TYPE>/<COMPONENT_NAME>/command
ON or OFF or whatever is supported
Example
To enable or disable the Ring-To-Open automation, send ON
or OFF
as the payload to the topic:
doorman-s3/switch/ring_to_open/command
ON
Special Topics
Certain special topics allow for advanced commands.
Send a Command (Hexadecimal)
Here's an example of how to send a hexadecimal command (uint32) to the bus:
doorman-s3/send_raw_command
{
"command": 0x1C30BA80
}
{
"command": 0x1C30BA80,
"is_long": false
}
Send a Command (Command Builder)
Here's an example of how to use the command builder to send a command to the bus:
doorman-s3/send_command
{
"type": "open_door",
"address": 0,
"payload": 0,
"serial_number": 123456
}