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 directly through Web Serial.

Firmware YAML

This is the minimal ESPHome configuration YAML file. Be sure to update the API key.

Minimal Nuki Bridge Firmware

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

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 TCS Command Binary Sensor

You can easily add additional binary sensors for any TCS Command, alongside the preconfigured ones.

# 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: tcs_intercom
    name: "Custom Command"
    command: 0x3b8f9a00

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
    name: "Turn on Status RGB LED to red"
    on_press: 
      - light.turn_on: 
          id: doorman_rgb_status_led
          red: 100%
          green: 0%
          blue: 0%

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
    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
  scl: GPIO48
  scan: true
  id: i2c_bus

Advanced Examples

Home Assistant

Sending Bus commands

You can use Home Assistant actions (formerly known as services) to send commands on the bus.

INFO

Remember to include the leading 0x when sending a HEX command. If you omit it, you'll need to convert the HEX command to a decimal number.

service: esphome.doorman_s3_send_tcs_command
data:
  command: 0x3a001100

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"
origin: LOCAL
time_fired: "2024-08-12T12:34:13.718317+00:00"
context:
  id: 01J5399Y2PP2XS2VRYKBT3H3AV
  parent_id: null
  user_id: null

Home Assistant Automation Example:

alias: Trigger on Doorman TCS Open Door Command
description: ""
trigger:
  - platform: event
    event_type: esphome.doorman
    event_data:
      command: "00001100"
condition: []
action: []
mode: single

ESPHome

Create a Runtime Config TCS Command Binary Sensor

You can add additional configurable command binary sensors alongside the preconfigured ones by using lambda, globals, and text inputs.

# 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

globals: 
  - id: custom_command
    type: int
    restore_value: true
    initial_value: '0x3b8f9a00'

text: 
  - platform: template
    id: custom_command_input
    name: Custom Command
    entity_category: CONFIG
    icon: "mdi:console-network"
    mode: text
    lambda: |-
      unsigned long number = id(custom_command);
      return str_upper_case(format_hex(number));
    set_action: 
      then: 
        - lambda: |-
            x.erase(std::remove_if(x.begin(), x.end(), [](char c) { return !std::isxdigit(c); }), x.end());
            x.erase(0, x.find_first_not_of('0'));
            x.resize(8);
            unsigned long number = 0;
            if(std::string(x.c_str()) != "") {
              number = std::stoul(x.c_str(), nullptr, 16);
            }
            id(custom_command) = number;
            id(custom_command_input)->publish_state(str_upper_case(format_hex(number)));

binary_sensor: 
  - platform: tcs_intercom
    name: "Custom Command"
    lambda: !lambda "return id(custom_command);"

Create a Bus Voltage Sensor

You can add a Bus Voltage sensor for older intercoms operating on 14-24V DC.
It may also be possible to implement other protocols in the future.

# 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

# New ADC Voltage Sensor
sensor: 
  - platform: adc
    id: bus_voltage
    name: Bus Voltage
    pin: 
      number: GPIO9
      allow_other_uses: true
    update_interval: 500ms
    attenuation: 12dB

# Extend tcs_intercom component
# Allow RX pin to be used for other cases as well
tcs_intercom: 
  rx_pin: 
    number: GPIO9
    allow_other_uses: true

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 doorbell_pattern
    event_types: 
      - "apartment_special"

# Extend the apartment_doorbell / entrance_doorbell entity
# and add your new special pattern
binary_sensor: 
  - id: !extend apartment_doorbell
    on_multi_click: 
      # Special Pattern
      - timing: 
          # Press twice with no more than one second between each press.
          - ON for at most 0.5s
          - OFF for at most 1s
          - ON for at most 0.5s
          - OFF for at least 2s
        then: 
          - logger.log: "Special pattern detected!"
          - event.trigger: 
              id: doorbell_pattern
              # Use the previously defined new event type here
              event_type: apartment_special

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
    on_press: 
      - tcs_intercom.send: 
          command: !lambda "return id(turn_on_light_command);"

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
    id: sun_elevation
    entity_id: sun.sun
    attribute: elevation

# Extend the entrance doorbell sensor
binary_sensor: 
  - id: !extend entrance_doorbell
    on_press: 
      # Sun elevation is <= 0 (dark)
      - if: 
          condition: 
            sensor.in_range: 
              id: sun_elevation
              below: 1
          then: 
            # Turn on the light
            - tcs_intercom.send: 
                command: !lambda "return id(turn_on_light_command);"