Update Docs

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

docs/automation/ring-to-open.md

@@ -1,13 +1,18 @@
 # Ring To Open <Badge type="warning" text="Party Mode" />
 
-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.
 :::

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
 <!--@include: minimal.example.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
 <!--@include: minimal.example.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
 <!--@include: minimal.example.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
 <!--@include: minimal.example.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
 <!--@include: minimal.example.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
 <!--@include: minimal.example.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]
 ```
 :::

docs/firmware/custom-firmware.md

@@ -1,4 +1,4 @@
-# Custom Doorman Firmware
+# Custom Doorman Firmware <Badge type="tip" text="Arduino Framework" />
 
 Github user [peteh](https://github.com/peteh) developed a custom firmware for Doorman circuits.
 

docs/firmware/minimal.example.yaml

@@ -1,5 +1,4 @@
 # Doorman S3 Firmware
-
 substitutions:
   name: "doorman-s3"
   friendly_name: "Doorman S3"

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 <Badge type="info" text="Disabled by default" />
-- Nuki Door Sensor State <Badge type="info" text="Disabled by default" />
-- Entrance Doorbell
-- Apartment Doorbell
-- Pick up phone <Badge type="info" text="Disabled by default" />
-- Hang up phone <Badge type="info" text="Disabled by default" />
-- External Button <Badge type="info" text="Disabled by default" />
+- Entrance Doorbell `entrance_doorbell`
+- Apartment Doorbell `apartment_doorbell`
+- Pick up phone `pick_up_phone` <Badge type="info" text="Disabled by default" />
+- Hang up phone `hang_up_phone` <Badge type="info" text="Disabled by default" />
+- External Button `doorman_external_button` <Badge type="info" text="Disabled by default" />
+- Nuki Connected `nuki_connected`
+- Nuki Paired `nuki_paired`
+- Nuki Battery Critical `nuki_battery_critical`
+- Nuki Door Sensor `nuki_door_sensor` <Badge type="info" text="Disabled by default" />
+- Nuki Door Sensor State `nuki_door_sensor_state` <Badge type="info" text="Disabled by default" />
+
 
 ### Switches
-- Nuki Pairing Mode <Badge type="info" text="Disabled by default" />
-- Ring To Open
-- Relay <Badge type="info" text="Disabled by default" />
+- Ring To Open `doorman_ring_to_open`
+- Relay `doorman_relay` <Badge type="info" text="Disabled by default" />
+- Nuki Pairing Mode `nuki_pairing_mode` <Badge type="info" text="Disabled by default" />
 
 ### Buttons
-- Nuki Unpair Device <Badge type="info" text="Disabled by default" />
-- Open Entrance Door
-- Open Second Door <Badge type="info" text="Disabled by default" />
-- Restart <Badge type="info" text="Disabled by default" />
-- Safe mode <Badge type="info" text="Disabled by default" />
+- Open Entrance Door `open_entrance_door`
+- Open Second Door `open_second_door` <Badge type="info" text="Disabled by default" />
+- Restart `doorman_restart` <Badge type="info" text="Disabled by default" />
+- Safe mode `doorman_safe_mode` <Badge type="info" text="Disabled by default" />
+- Restore Factory Settings `doorman_factory_reset` <Badge type="info" text="Disabled by default" />
+- Nuki Unpair Device `nuki_unpair_device` <Badge type="info" text="Disabled by default" />
 
 ### 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 <Badge type="info" text="Disabled by default" />
-- Pick up phone Command <Badge type="info" text="Disabled by default" />
-- Hang up phone Command <Badge type="info" text="Disabled by default" />
-- Ring To Open Delay <Badge type="info" text="Disabled by default" />
+- 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` <Badge type="info" text="Disabled by default" />
+- Pick up phone Command `pick_up_phone_command_input` <Badge type="info" text="Disabled by default" />
+- Hang up phone Command `hang_up_phone_command_input` <Badge type="info" text="Disabled by default" />
+- Ring To Open Toggle Command `ring_to_open_toggle_command` <Badge type="info" text="Disabled by default" />
+- Ring To Open Delay `ring_to_open_delay` <Badge type="info" text="Disabled by default" />
 
 ## 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.