Doorman

English

Deutsch

English

Deutsch

Appearance

Stock Firmware ESP-IDF Framework ​

This is the preferred firmware as it works out of the box with the Doorman S3 and supports Improv via Bluetooth LE.

Install or Update Firmware ​

There are several ways to update the firmware.

WARNING

Be aware that some updates may introduce breaking changes — always review the changelogs carefully to ensure your system functions reliably in critical situations.

Web Serial Latest release build, no customization ​

Connect your Doorman-S3 via USB-C and click the button below to install or update the latest firmware directly via Web Serial, enabling seamless integration with the Home Assistant API. This setup ensures you can effortlessly apply community-driven updates in the future.

HTTP OTA Updates Latest release build, no customization ​

By integrating Doorman with Home Assistant, you unlock the convenience of automated firmware builds and seamless updates to the latest releases. The Update will appear directly in your Update list, allowing you to initiate an OTA update with just a click of the Update button — simple, efficient, and hassle-free.

ESPHome CLI / Dashboard Full customization ​

For full customization and complete control over the firmware, you can adopt it into your ESPHome Dashboard or utilize the ESPHome CLI by executing:
esphome run <yamlfile.yaml>

If you prefer using the MQTT-only firmware, simply apply the provided MQTT example YAML tailored for your board below.

Board Configuration Options: ​
Doorman-S3 (1.5) / ESP32-S3 (Octal PSRAM)
yaml
# Doorman Stock Firmware (Home Assistant)
# Base Board ESP32-S3

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
yaml
# Doorman Stock Firmware (MQTT)
# Base Board ESP32-S3

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.mqtt.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

mqtt:
  broker: "10.10.0.2"
  username: ""
  password: ""
Doorman-S3 (1.4) / ESP32-S3 (Quad PSRAM)
yaml
# Doorman Stock Firmware (Home Assistant)
# Base Board ESP32-S3-QUAD

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3-quad.ha.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
yaml
# Doorman Stock Firmware (MQTT)
# Base Board ESP32-S3-QUAD

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3-quad.mqtt.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

mqtt:
  broker: "10.10.0.2"
  username: ""
  password: ""
Generic ESP32

GPIO configuration ​

  • TC:BUS RX: GPIO 22
  • TC:BUS TX: GPIO 23
  • Status LED: GPIO 2
  • RGB Status LED: GPIO 4
  • Relay: GPIO 21
  • External button: GPIO 20
  • ADC Input: GPIO 36
yaml
# Doorman Stock Firmware (Home Assistant)
# Base Board ESP32

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32.ha.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
yaml
# Doorman Stock Firmware (MQTT)
# Base Board ESP32

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32.mqtt.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

mqtt:
  broker: "10.10.0.2"
  username: ""
  password: ""
Generic ESP8266

GPIO configuration ​

  • TC:BUS RX: GPIO 12
  • TC:BUS TX: GPIO 13
  • Status LED: GPIO 2
  • RGB Status LED: Dummy
  • Relay: GPIO 14
  • External button: GPIO 15
  • ADC Input: A0
yaml
# Doorman Stock Firmware (Home Assistant)
# Base Board ESP8266

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp8266.ha.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
yaml
# Doorman Stock Firmware (MQTT)
# Base Board ESP8266

# 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"
  # adc_input_pin: "GPIO10"

# Import Doorman Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp8266.mqtt.stock.master.yaml@master

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

mqtt:
  broker: "10.10.0.2"
  username: ""
  password: ""

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:

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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:

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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.

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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.

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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.

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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:

yaml
service: esphome.doorman_s3_send_tc_command
data:
  type: open_door
  address: 0
  payload: 0
  serial_number: 123456

Hexadecimal Commands via command:

yaml
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:

yaml
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):

yaml
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):

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

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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.

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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.

yaml
# Doorman S3 Firmware
substitutions:
  name: "doorman-s3"
  friendly_name: "Doorman S3"

# Import Doorman Stock Firmware Config
packages:
  AzonInc.Doorman: github://azoninc/doorman/firmware/configurations/esp32-s3.ha.stock.master.yaml@master

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
json
{
    "command": 0x1C30BA80
}
json
{
    "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
json
{
    "type": "open_door",
    "address": 0,
    "payload": 0,
    "serial_number": 123456
}

Released under the GPL 3.0 License.

Made with ❤️ by the Creators of Doorman.