From 1e7c36a5c1f6d355cc720250346a00387e80f217 Mon Sep 17 00:00:00 2001 From: Florian Date: Tue, 13 Aug 2024 01:54:16 +0200 Subject: [PATCH] Update Docs --- docs/automation/pattern-events.md | 7 + docs/automation/ring-to-open.md | 9 +- docs/firmware/additions.md | 177 +++++++++++++------------- docs/firmware/custom-firmware.md | 2 +- docs/firmware/minimal.example.yaml | 1 - docs/firmware/nuki-bridge-firmware.md | 63 ++++----- docs/firmware/stock-firmware.md | 44 ++++--- docs/guide/getting-started.md | 4 +- firmware/base.yaml | 33 ++++- firmware/doorman-nuki-bridge.yaml | 7 + 10 files changed, 201 insertions(+), 146 deletions(-) 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