diff --git a/docs/automation/pattern-events.md b/docs/automation/pattern-events.md
index cd19a24..5806164 100644
--- a/docs/automation/pattern-events.md
+++ b/docs/automation/pattern-events.md
@@ -2,6 +2,13 @@
The Doorman Firmware includes pattern event entities which you can use in [Home Assistant](https://www.home-assistant.io/) automations.
+Each pattern is configured like:
+- Push
+- Maximum 1 second break
+- Push
+
+Take a look at the [advanced examples](../firmware/stock-firmware#advanced-examples) to see how to extend the patterns with your very own pattern.
+
## Doorbell Pattern
### Event Types
diff --git a/docs/automation/ring-to-open.md b/docs/automation/ring-to-open.md
index dd34219..b5dac9c 100644
--- a/docs/automation/ring-to-open.md
+++ b/docs/automation/ring-to-open.md
@@ -1,13 +1,18 @@
# Ring To Open
-The [Stock Doorman Firmware](../firmware/stock-firmware.md) includes a `Ring To Open` automation.
+The Doorman Firmware offers a `Ring To Open` automation, also known as `Party Mode`.
### What does it do?
As the name already says, the entrance door will be opened as soon as someone rings the entrance doorbell.
It could be useful when you have a party. That way your guests can just enter the building by ringing.
### How do I use it?
-You can enable and disable the `Ring To Open` automation with a switch in Home Assistant.
+You can enable and disable the `Ring To Open` automation with either the switch in Home Assistant or the TCS `Ring To Open Toggle Command`.
+
+The latter is useful when you have an unused function button on your intercom phone.
+
::: tip
It is also possible to configure a delay for the opener command with the `Ring To Open Delay` Number Input in the Configuration section.
+
+If you set the delay to 60 seconds it will choose a random time between 5 and 15 seconds.
:::
\ No newline at end of file
diff --git a/docs/firmware/additions.md b/docs/firmware/additions.md
index 22a0209..ee15818 100644
--- a/docs/firmware/additions.md
+++ b/docs/firmware/additions.md
@@ -1,14 +1,14 @@
## Examples
-::: details Handle static TCS Commands
+::: details Create a simple TCS Command Binary Sensor
You can easily add more binary sensors next to the preconfigured ones for every possible TCS Command.
```yaml
-binary_sensor: // [!code ++]
- - platform: tcs_intercom // [!code ++]
- name: "Custom Command" // [!code ++]
- command: 0x3b8f9a00 // [!code ++]
+binary_sensor: // [!code ++] // [!code focus]
+ - platform: tcs_intercom // [!code ++] // [!code focus]
+ name: "Custom Command" // [!code ++] // [!code focus]
+ command: 0x3b8f9a00 // [!code ++] // [!code focus]
```
:::
@@ -17,15 +17,15 @@ If you want to control the onboard RGB LED with a Button (Example) just use the
```yaml
-button: // [!code ++]
- - platform: template // [!code ++]
- name: "Turn on Status RGB LED to red" // [!code ++]
- on_press: // [!code ++]
- - light.turn_on: // [!code ++]
- id: doorman_rgb_status_led // [!code ++]
- red: 100% // [!code ++]
- green: 0% // [!code ++]
- blue: 0% // [!code ++]
+button: // [!code ++] // [!code focus]
+ - platform: template // [!code ++] // [!code focus]
+ name: "Turn on Status RGB LED to red" // [!code ++] // [!code focus]
+ on_press: // [!code ++] // [!code focus]
+ - light.turn_on: // [!code ++] // [!code focus]
+ id: doorman_rgb_status_led // [!code ++] // [!code focus]
+ red: 100% // [!code ++] // [!code focus]
+ green: 0% // [!code ++] // [!code focus]
+ blue: 0% // [!code ++] // [!code focus]
```
:::
@@ -34,15 +34,16 @@ If you want to use the external button to trigger automations you can just exten
```yaml
-binary_sensor: // [!code ++]
- - id: !extend doorman_external_button // [!code ++]
- on_press: // [!code ++]
- - logger.log: "External button pressed!" // [!code ++]
+binary_sensor: // [!code ++] // [!code focus]
+ - id: !extend doorman_external_button // [!code ++] // [!code focus]
+ on_press: // [!code ++] // [!code focus]
+ - logger.log: "External button pressed!" // [!code ++] // [!code focus]
```
:::
## Advanced Examples
-::: details Home Assistant: Sending Bus commands
+### Home Assistant
+::: details Sending Bus commands
You can use Home Assistant actions (formerly services) to send commands on the Bus.
> [!INFO]
> Don't forget the leading `0x` if you want to send the HEX command. Otherwise you have to convert the hex command into a decimal number.
@@ -54,7 +55,7 @@ data:
```
:::
-::: details Home Assistant: Listening for ESPHome events
+::: details Listening for ESPHome events
Doorman will send `esphome.doorman` events to Home Assistant everytime a command is received.
Each Event is structured like:
@@ -86,90 +87,96 @@ mode: single
```
:::
-::: details ESPHome: Handle runtime config TCS Commands
+### ESPHome
+::: details Create a runtime config TCS Command Binary Sensor
You can add more configurable command binary sensors next to the preconfigured ones using lambda, globals and text inputs.
```yaml
-globals: // [!code ++]
- - id: custom_command // [!code ++]
- type: int // [!code ++]
- restore_value: true // [!code ++]
- initial_value: '0x3b8f9a00' // [!code ++]
-
-text: // [!code ++]
- - platform: template // [!code ++]
- name: Custom Command // [!code ++]
- optimistic: true // [!code ++]
- mode: text // [!code ++]
- restore_value: true // [!code ++]
- initial_value: '3b8f9a00' // [!code ++]
- on_value: // [!code ++]
- then: // [!code ++]
- - lambda: |- // [!code ++]
- id(custom_command) = std::stoi(x.c_str(), nullptr, 16); // [!code ++]
- entity_category: CONFIG // [!code ++]
- icon: "mdi:console-network" // [!code ++]
-
-binary_sensor: // [!code ++]
- - platform: tcs_intercom // [!code ++]
- name: "Custom Command" // [!code ++]
- lambda: !lambda "return id(custom_command);" // [!code ++]
+globals: // [!code ++] // [!code focus]
+ - id: custom_command // [!code ++] // [!code focus]
+ type: int // [!code ++] // [!code focus]
+ restore_value: true // [!code ++] // [!code focus]
+ initial_value: '0x3b8f9a00' // [!code ++] // [!code focus]
+
+text: // [!code ++] // [!code focus]
+ - platform: template // [!code ++] // [!code focus]
+ name: Custom Command // [!code ++] // [!code focus]
+ optimistic: true // [!code ++] // [!code focus]
+ mode: text // [!code ++] // [!code focus]
+ restore_value: true // [!code ++] // [!code focus]
+ initial_value: '3b8f9a00' // [!code ++] // [!code focus]
+ on_value: // [!code ++] // [!code focus]
+ then: // [!code ++] // [!code focus]
+ - lambda: |- // [!code ++] // [!code focus]
+ id(custom_command) = std::stoi(x.c_str(), nullptr, 16); // [!code ++] // [!code focus]
+ entity_category: CONFIG // [!code ++] // [!code focus]
+ icon: "mdi:console-network" // [!code ++] // [!code focus]
+
+binary_sensor: // [!code ++] // [!code focus]
+ - platform: tcs_intercom // [!code ++] // [!code focus]
+ name: "Custom Command" // [!code ++] // [!code focus]
+ lambda: !lambda "return id(custom_command);" // [!code ++] // [!code focus]
```
:::
-::: details ESPHome: Adding a Bus Voltage sensor
+::: details Create a Bus Voltage sensor
You can add a `Bus Voltage` sensor for older intercoms operating on 14-24V DC.\
It might be possible to implement other protocols as well in the future.
```yaml
-# New ADC Voltage Sensor // [!code ++]
-sensor: // [!code ++]
- - platform: adc // [!code ++]
- id: bus_voltage // [!code ++]
- name: Bus Voltage // [!code ++]
- pin: // [!code ++]
- number: GPIO9 // [!code ++]
- allow_other_uses: true // [!code ++]
- update_interval: 500ms // [!code ++]
- attenuation: 11dB // [!code ++]
-
-# Extend tcs_intercom component // [!code ++]
-# Allow RX pin to be used for other cases as well // [!code ++]
-tcs_intercom: // [!code ++]
- rx_pin: // [!code ++]
- number: GPIO9 // [!code ++]
- allow_other_uses: true // [!code ++]
+# New ADC Voltage Sensor // [!code ++] // [!code focus]
+sensor: // [!code ++] // [!code focus]
+ - platform: adc // [!code ++] // [!code focus]
+ id: bus_voltage // [!code ++] // [!code focus]
+ name: Bus Voltage // [!code ++] // [!code focus]
+ pin: // [!code ++] // [!code focus]
+ number: GPIO9 // [!code ++] // [!code focus]
+ allow_other_uses: true // [!code ++] // [!code focus]
+ update_interval: 500ms // [!code ++] // [!code focus]
+ attenuation: 11dB // [!code ++] // [!code focus]
+
+# Extend tcs_intercom component // [!code ++] // [!code focus]
+# Allow RX pin to be used for other cases as well // [!code ++] // [!code focus]
+tcs_intercom: // [!code ++] // [!code focus]
+ rx_pin: // [!code ++] // [!code focus]
+ number: GPIO9 // [!code ++] // [!code focus]
+ allow_other_uses: true // [!code ++] // [!code focus]
```
:::
-::: details ESPHome: Create your own Doorbell Pattern
+::: details Create your own Doorbell Pattern
If you want to create a special doorbell pattern you can easily extend the existing doorbell entities.
+You can find more information about the patterns in the [ESPHome Docs](https://esphome.io/components/binary_sensor/index.html#on-multi-click).
```yaml
-# Extend the doorbell_pattern event entity // [!code ++]
-# Add a new apartment_special event type // [!code ++]
-event: // [!code ++]
- - id: !extend doorbell_pattern // [!code ++]
- event_types: // [!code ++]
- - "apartment_special" // [!code ++]
-
-# Extend the doorman_apartment_doorbell entity // [!code ++]
-# and add your new special pattern // [!code ++]
-binary_sensor: // [!code ++]
- - id: !extend doorman_apartment_doorbell // [!code ++]
- on_multi_click: // [!code ++]
- # Special Pattern // [!code ++]
- - timing: // [!code ++]
- - ON for at most 0.5s // [!code ++]
- - OFF for at least 2s // [!code ++]
- then: // [!code ++]
- - logger.log: "Special pattern detected!" // [!code ++]
- - event.trigger: // [!code ++]
- id: doorbell_pattern // [!code ++]
- event_type: apartment_special // [!code ++]
+# Extend the doorbell_pattern event entity // [!code ++] // [!code focus]
+# Add a new apartment_special event type // [!code ++] // [!code focus]
+event: // [!code ++] // [!code focus]
+ - id: !extend doorbell_pattern // [!code ++] // [!code focus]
+ event_types: // [!code ++] // [!code focus]
+ - "apartment_special" // [!code ++] // [!code focus]
+
+# Extend the apartment_doorbell / entrance_doorbell entity // [!code ++] // [!code focus]
+# and add your new special pattern // [!code ++] // [!code focus]
+binary_sensor: // [!code ++] // [!code focus]
+ - id: !extend apartment_doorbell // [!code ++] // [!code focus]
+ on_multi_click: // [!code ++] // [!code focus]
+ # Special Pattern // [!code ++] // [!code focus]
+ - timing: // [!code ++] // [!code focus]
+ # Press twice with no more than one second between each press. // [!code ++] // [!code focus]
+ - 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: // [!code ++] // [!code focus]
+ - logger.log: "Special pattern detected!" // [!code ++] // [!code focus]
+ - event.trigger: // [!code ++] // [!code focus]
+ id: doorbell_pattern // [!code ++] // [!code focus]
+ # Use the previously defined new event type here // [!code ++] // [!code focus]
+ event_type: apartment_special // [!code ++] // [!code focus]
```
:::
\ No newline at end of file
diff --git a/docs/firmware/custom-firmware.md b/docs/firmware/custom-firmware.md
index 4a281c7..a640503 100644
--- a/docs/firmware/custom-firmware.md
+++ b/docs/firmware/custom-firmware.md
@@ -1,4 +1,4 @@
-# Custom Doorman Firmware
+# Custom Doorman Firmware
Github user [peteh](https://github.com/peteh) developed a custom firmware for Doorman circuits.
diff --git a/docs/firmware/minimal.example.yaml b/docs/firmware/minimal.example.yaml
index 772cacd..411eeb1 100644
--- a/docs/firmware/minimal.example.yaml
+++ b/docs/firmware/minimal.example.yaml
@@ -1,5 +1,4 @@
# Doorman S3 Firmware
-
substitutions:
name: "doorman-s3"
friendly_name: "Doorman S3"
diff --git a/docs/firmware/nuki-bridge-firmware.md b/docs/firmware/nuki-bridge-firmware.md
index 271b632..fd9ca30 100644
--- a/docs/firmware/nuki-bridge-firmware.md
+++ b/docs/firmware/nuki-bridge-firmware.md
@@ -33,48 +33,51 @@ You can connect your Doorman via USB-C and click the button below to install the
## Entities
### Locks
-- Nuki Lock
+- Nuki Lock `nuki_smart_lock`
### Sensors
-- Nuki Battery Level
-- Last Bus Command
+- Last Bus Command `last_bus_command`
+- Nuki Battery Level `nuki_battery_level`
### Binary Sensors
-- Nuki Connected
-- Nuki Paired
-- Nuki Battery Critical
-- Nuki Door Sensor
-- Nuki Door Sensor State
-- Entrance Doorbell
-- Apartment Doorbell
-- Pick up phone
-- Hang up phone
-- External Button
+- Entrance Doorbell `entrance_doorbell`
+- Apartment Doorbell `apartment_doorbell`
+- Pick up phone `pick_up_phone`
+- Hang up phone `hang_up_phone`
+- External Button `doorman_external_button`
+- Nuki Connected `nuki_connected`
+- Nuki Paired `nuki_paired`
+- Nuki Battery Critical `nuki_battery_critical`
+- Nuki Door Sensor `nuki_door_sensor`
+- Nuki Door Sensor State `nuki_door_sensor_state`
+
### Switches
-- Nuki Pairing Mode
-- Ring To Open
-- Relay
+- Ring To Open `doorman_ring_to_open`
+- Relay `doorman_relay`
+- Nuki Pairing Mode `nuki_pairing_mode`
### Buttons
-- Nuki Unpair Device
-- Open Entrance Door
-- Open Second Door
-- Restart
-- Safe mode
+- Open Entrance Door `open_entrance_door`
+- Open Second Door `open_second_door`
+- Restart `doorman_restart`
+- Safe mode `doorman_safe_mode`
+- Restore Factory Settings `doorman_factory_reset`
+- Nuki Unpair Device `nuki_unpair_device`
### Events
-- Doorbell Pattern
-- Phone pickup Pattern
+- Doorbell Pattern `doorbell_pattern`
+- Phone pickup Pattern `phone_pickup_pattern`
### Configuration Inputs
-- Apartment Doorbell Command
-- Entrance Doorbell Command
-- Open Entrance Door Command
-- Open Second Door Command
-- Pick up phone Command
-- Hang up phone Command
-- Ring To Open Delay
+- Apartment Doorbell Command `apartment_doorbell_command_input`
+- Entrance Doorbell Command `entrance_doorbell_command_input`
+- Open Entrance Door Command `open_entrance_door_command_input`
+- Open Second Door Command `open_second_door_command_input`
+- Pick up phone Command `pick_up_phone_command_input`
+- Hang up phone Command `hang_up_phone_command_input`
+- Ring To Open Toggle Command `ring_to_open_toggle_command`
+- Ring To Open Delay `ring_to_open_delay`
## Pairing your Nuki Lock
Depending on the PCB revision, press the `FLASH` or `PRG` button on the Doorman PCB for 5 seconds until the Status LED starts flashing purple or turn on the `Nuki Pairing Mode` switch in Home Assistant. Press the Button on your Nuki Lock for 5 seconds until the light-ring turns on.
diff --git a/docs/firmware/stock-firmware.md b/docs/firmware/stock-firmware.md
index bb2a7cf..147eba4 100644
--- a/docs/firmware/stock-firmware.md
+++ b/docs/firmware/stock-firmware.md
@@ -33,37 +33,39 @@ You can connect your Doorman via USB-C and click the button below to install the
## Entities
### Sensors
-- Last Bus Command
+- Last Bus Command `last_bus_command`
### Binary Sensors
-- Entrance Doorbell
-- Apartment Doorbell
-- Pick up phone
-- Hang up phone
-- External Button
+- Entrance Doorbell `entrance_doorbell`
+- Apartment Doorbell `apartment_doorbell`
+- Pick up phone `pick_up_phone`
+- Hang up phone `hang_up_phone`
+- External Button `doorman_external_button`
### Switches
-- Ring To Open
-- Relay
+- Ring To Open `doorman_ring_to_open`
+- Relay `doorman_relay`
### Buttons
-- Open Entrance Door
-- Open Second Door
-- Restart
-- Safe mode
+- Open Entrance Door `open_entrance_door`
+- Open Second Door `open_second_door`
+- Restart `doorman_restart`
+- Safe mode `doorman_safe_mode`
+- Restore Factory Settings `doorman_factory_reset`
### Events
-- Doorbell Pattern
-- Phone pickup Pattern
+- Doorbell Pattern `doorbell_pattern`
+- Phone pickup Pattern `phone_pickup_pattern`
### Configuration Inputs
-- Apartment Doorbell Command
-- Entrance Doorbell Command
-- Open Entrance Door Command
-- Open Second Door Command
-- Pick up phone Command
-- Hang up phone Command
-- Ring To Open Delay
+- Apartment Doorbell Command `apartment_doorbell_command_input`
+- Entrance Doorbell Command `entrance_doorbell_command_input`
+- Open Entrance Door Command `open_entrance_door_command_input`
+- Open Second Door Command `open_second_door_command_input`
+- Pick up phone Command `pick_up_phone_command_input`
+- Hang up phone Command `hang_up_phone_command_input`
+- Ring To Open Toggle Command `ring_to_open_toggle_command`
+- Ring To Open Delay `ring_to_open_delay`
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index d86ba09..a926ef4 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -103,9 +103,9 @@ Example:
:::
::: details 2-Wire Mode via intercom
-> [!DANGER] This scenario is currently not possible!
+> [!DANGER] Unfortunately this scenario is not possible!
> A loud beeping noise occurs if the a-bus line is used as a power source.\
-> This is most likely caused by the high-frequency switching power supply.
+> This is most likely caused by the high-frequency switching power supply and might get fixed in future hardware revisions.
Example:
![2-wire external via usb](./images/2wire_power_a_terminal.png){width=300px}
diff --git a/firmware/base.yaml b/firmware/base.yaml
index 7306c90..8ee6b60 100644
--- a/firmware/base.yaml
+++ b/firmware/base.yaml
@@ -141,6 +141,7 @@ tcs_intercom:
event: "doorman"
bus_command:
name: "Last Bus Command"
+ id: last_bus_command
hardware_version:
name: "Hardware"
icon: "mdi:router-wireless"
@@ -176,23 +177,27 @@ switch:
button:
# System Actions
- platform: restart
+ id: doorman_restart
entity_category: CONFIG
name: Restart
icon: mdi:restart
disabled_by_default: true
- platform: safe_mode
+ id: doorman_safe_mode
name: Safe mode
entity_category: CONFIG
disabled_by_default: true
- platform: factory_reset
+ id: doorman_factory_reset
name: Restore Factory Settings
entity_category: CONFIG
disabled_by_default: true
# Preconfigured Open Door Button
- platform: template
+ id: open_entrance_door
name: "Open Entrance Door"
icon: mdi:door
on_press:
@@ -200,6 +205,7 @@ button:
command: !lambda "return id(first_door_opener_command);"
- platform: template
+ id: open_second_door
name: "Open Second Door"
icon: mdi:door
on_press:
@@ -253,7 +259,7 @@ light:
binary_sensor:
# Preconfigured Sensors
- platform: tcs_intercom
- id: doorman_entrance_doorbell
+ id: entrance_doorbell
name: "Entrance Doorbell"
lambda: !lambda "return id(entrance_doorbell_command);"
auto_off: 0.2s
@@ -264,7 +270,17 @@ binary_sensor:
condition:
switch.is_on: doorman_ring_to_open
then:
- - delay: !lambda "return id(ring_to_open_door_opener_delay).state*1000;"
+ # If delay is 60 seconds, use random delay from 5 to 20 seconds
+ - if:
+ condition:
+ number.in_range:
+ id: ring_to_open_delay
+ above: 59
+ then:
+ - delay: !lambda "return 5000 + (rand() % 10000);"
+ else:
+ - delay: !lambda "return id(ring_to_open_delay).state*1000;"
+
- tcs_intercom.send:
command: !lambda "return id(first_door_opener_command);"
on_multi_click:
@@ -306,7 +322,7 @@ binary_sensor:
- platform: tcs_intercom
- id: doorman_apartment_doorbell
+ id: apartment_doorbell
name: "Apartment Doorbell"
lambda: !lambda "return id(apartment_doorbell_command);"
auto_off: 0.2s
@@ -349,6 +365,7 @@ binary_sensor:
- platform: tcs_intercom
+ id: "pick_up_phone"
name: "Pick up phone"
lambda: !lambda "return id(pick_up_phone_command);"
auto_off: 0.2s
@@ -391,6 +408,7 @@ binary_sensor:
event_type: triple
- platform: tcs_intercom
+ id: "hang_up_phone"
name: "Hang up phone"
lambda: !lambda "return id(hang_up_phone_command);"
auto_off: 0.2s
@@ -419,7 +437,7 @@ binary_sensor:
number:
- platform: template
name: Ring To Open Delay
- id: ring_to_open_door_opener_delay
+ id: ring_to_open_delay
mode: slider
min_value: 0
max_value: 60
@@ -433,6 +451,7 @@ number:
text:
- platform: template
+ id: open_entrance_door_command_input
name: Open Entrance Door Command
optimistic: true
mode: text
@@ -446,6 +465,7 @@ text:
icon: "mdi:console-network"
- platform: template
+ id: open_second_door_command_input
name: Open Second Door Command
optimistic: true
mode: text
@@ -460,6 +480,7 @@ text:
icon: "mdi:console-network"
- platform: template
+ id: entrance_doorbell_command_input
name: Entrance Doorbell Command
optimistic: true
mode: text
@@ -473,6 +494,7 @@ text:
icon: "mdi:console-network"
- platform: template
+ id: apartment_doorbell_command_input
name: Apartment Doorbell Command
optimistic: true
mode: text
@@ -486,6 +508,7 @@ text:
icon: "mdi:console-network"
- platform: template
+ id: pick_up_phone_command_input
name: Pick up phone Command
optimistic: true
mode: text
@@ -500,6 +523,7 @@ text:
icon: "mdi:console-network"
- platform: template
+ id: hang_up_command_input
name: Hang up phone Command
optimistic: true
mode: text
@@ -514,6 +538,7 @@ text:
icon: "mdi:console-network"
- platform: template
+ id: toggle_ring_to_open_command_input
name: Toggle Ring To Open Command
optimistic: true
mode: text
diff --git a/firmware/doorman-nuki-bridge.yaml b/firmware/doorman-nuki-bridge.yaml
index 1e47b89..e544553 100644
--- a/firmware/doorman-nuki-bridge.yaml
+++ b/firmware/doorman-nuki-bridge.yaml
@@ -30,6 +30,7 @@ lock:
# Required:
is_connected:
+ id: nuki_connected
name: "Nuki Connected"
icon: "mdi:link"
@@ -40,24 +41,30 @@ lock:
# Optional:
battery_critical:
+ id: nuki_battery_critical
name: "Nuki Battery Critical"
battery_level:
+ id: nuki_battery_level
name: "Nuki Battery Level"
door_sensor:
+ id: nuki_door_sensor
name: "Nuki Door Sensor"
disabled_by_default: true
door_sensor_state:
+ id: nuki_door_sensor_state
name: "Nuki Door Sensor State"
disabled_by_default: true
unpair:
+ id: nuki_unpair_device
name: "Nuki Unpair Device"
disabled_by_default: true
pairing_mode:
+ id: nuki_pairing_mode
name: "Nuki Pairing Mode"
disabled_by_default: true