Merge pull request #22 from AzonInc/dev

Automatically start Interactive Setup & Better Colors
AzonInc · Aug 28, 2024 · 2a35fbe · 2a35fbe
2 parents dd42160 + bee01eb
commit 2a35fbe
Show file tree

Hide file tree

Showing 13 changed files with 228 additions and 177 deletions.
diff --git a/README.md b/README.md
@@ -42,7 +42,7 @@ I offer fully assembled and tested Doorman-S3 units with the [Stock Firmware](fi
 
 ## ✔️ Compatibility
 
-If your TCS or Koch intercom has screw terminals labeled `a`, `b`, and `P` and operates on 24V DC, it’s likely compatible with Doorman.\
+If your TCS or Koch intercom has screw terminals labeled `a`, `b`, and `P` and operates on 24V DC, it's likely compatible with Doorman.\
 For detailed compatibility information, check out the [Compatibility Docs](https://doorman.azon.ai/guide/hardware-compatibility).
 
 ## 🚩 Repository Structure

diff --git a/docs/de/guide/getting-started.md b/docs/de/guide/getting-started.md
@@ -1,8 +1,51 @@
 # Erste Schritte
 
-Hier ist eine ausführliche Anleitung, wie du deinen Doorman zum ersten Mal einrichtest. Bitte beachte, dass diese Anweisungen auf dem bereits geflashten Doorman-PCB basieren welches ich verkaufe.
+Ist das dein erster Besuch hier? Keine Sorge, wir haben alles für dich vorbereitet!
+Unten findest du eine ausführliche Anleitung zur Ersteinrichtung deines Doormans.
+
+Bitte beachte, dass diese Anweisungen auf dem bereits geflashten Doorman-PCB basieren welches ich verkaufe.
+Sofern du selbst ein PCB produzieren lassen hast, musst du zuerst die Firmware flashen. Solltest du dem nicht nachgehen, kannst du lange warten, dass irgendwas von dem unten beschriebenen passiert. 😄
+
+**Vielen Dank, dass du Doorman verwendest! ❤️**
+
+## Verkabelung
+Öffne als Erstes das Gehäuse deiner Gegensprechanlage. In den meisten Fällen findest du dort eine Schraubklemme mit den Bezeichnungen `a`, `b`, `E` und `P`.
+
+Schließe die `b`-Leitung (Ground) an einen der TCS:BUS-Anschlüsse deines Doorman an und die `a`-Leitung (24V Bus) an den anderen TCS:BUS-Anschluss deines Doorman.
+
+### Stromversorgungsoptionen:
+::: details 3-Draht-Modus über die Gegensprechanlage <Badge type="tip" text="Empfohlen" />
+Verbinde die `P`-Leitung (+24V) mit dem `P`-Terminal an deinem Doorman.
+
+> [!WARNING]
+> Die Stromversorgung der Gegensprechanlage muss mindestens 60mA liefern.
+
+Beispiel:
+![3-wire](./images/3wire.png){width=300px}
+:::
+
+::: details 2-Draht-Modus über externe Stromversorgung
+Schließe die externe Stromversorgung an deinen Doorman an. Nutze dazu die `P` (+5V bis +30V) und `G` (Ground) Schraubklemmen an deinem Doorman.
+
+Beispiel:
+![2-wire external via screw terminal](./images/2wire_power_screwterminal.png){width=300px}
+:::
+
+::: details 2-Draht-Modus über externe USB-C-Stromversorgung
+Schließe die externe Stromversorgung über den USB-C-Anschluss an.
+
+Beispiel:
+![2-wire external via usb](./images/2wire_power_usb_c.png){width=300px}
+:::
+
+::: details 2-Draht-Modus über die Gegensprechanlage <Badge type="danger" text="Nicht möglich" />
+> [!DANGER] Das ist leider nicht möglich!
+> Die Nutzung der `a`-Bus-Leitung als Stromquelle führt zu einem lauten Piepton. Dieses Problem tritt wahrscheinlich aufgrund der Hochfrequenz-Schaltstromversorgung auf und könnte in zukünftigen Hardware-Versionen behoben werden.
+
+Beispiel:
+![2-wire external via usb](./images/2wire_power_a_terminal.png){width=300px}
+:::
 
-Danke, dass du Doorman verwendest! ❤️
 
 ## Einrichtung
 
@@ -22,27 +65,34 @@ Dank mDNS-Unterstützung wird Home Assistant deinen Doorman automatisch entdecke
 ![Home Assistant Discovery](./images/discovery.png)
 
 ### Schritt 2: Mit Home Assistant verbinden
-Nachdem du den Doorman mit deinem Netzwerk verbunden hast, wird er langsam (blau) blinken und sollte automatisch von Home Assistant entdeckt werden. Klicke einfach auf `Konfigurieren`, um das neu entdeckte ESPHome-Gerät hinzuzufügen.
+Nachdem du deinen Doorman mit deinem Netzwerk verbunden hast, wird die RGB Status LED langsam (blau) blinken. Er sollte automatisch von Home Assistant entdeckt werden. Klicke einfach auf `Konfigurieren`, um das neu entdeckte ESPHome-Gerät hinzuzufügen.
+
+Falls nicht, kannst du ihn manuell per IP Addresse hinzufügen.
+
+Nach erfolgreicher Verbindung leuchtet er für 3 sekunden lang durchgehend blau.
 
-### Schritt 3: Bus-Befehle
-::: warning Bevor du weiter machst
-Du musst deinen Doorman zuerst mit der Gegensprechanlage verbinden. Sieh dir hierfür den Bereich [Verkabelung](#verkabelung) für detaillierte Anweisungen an.
+### Schritt 3: Bus-Befehle konfigurieren
+::: tip
+Nachdem du deinen Doorman mit Home Assistant verbunden hast,\
+startet automatisch der `Interactive Setup`-Prozess, der weiter unten beschrieben ist.
+
+Du musst ihn nicht manuell starten; er wird bei jedem Neustart automatisch gestartet, solange der Prozess nicht abgeschlossen oder abgebrochen wurde.
 :::
 
-#### Easy Setup
-Um die Konfiguration der wichtigsten Befehle zu erleichtern, kannst du den Easy Setup-Prozess nutzen.
+#### Interactive Setup <Badge type="warning" text="NEU" />
+Um die Konfiguration der wichtigsten Befehle zu erleichtern, kannst du den Interactive Setup-Prozess nutzen.
 
 Greif entweder auf den internen Webserver deines Doormans zu oder besuche die [ESPHome Integrationsseite](https://my.home-assistant.io/redirect/integration/?domain=esphome) und wähle das neu aufgeführte Doorman S3-Gerät aus.
 
-In `Konfiguration`-Bereich findest du den Button `Easy Setup: Start`. Klicke darauf, um den Einrichtungsprozess zu starten.
+In `Konfiguration`-Bereich findest du den Button `Interactive Setup: Start`. Klicke darauf, um den Einrichtungsprozess zu starten.
 
-Sobald der Prozess begonnen hat, wird der `Easy Setup: Status` Text Sensor dich durch die erforderlichen Schritte führen (z.B. Knopf X drücken, warten oder das Telefon abheben).\
-Während der Einrichtung pulsiert die RGB-Status-LED rot, solange du die Aufgabe noch nicht abgeschlossen hast, und bleibt 3 Sekunden lang rot, nachdem der Befehl gespeichert wurde.
+Sobald der Prozess begonnen hat, wird der `Interactive Setup: Status` Text Sensor dich durch die erforderlichen Schritte führen (z.B. Knopf X drücken, warten oder das Telefon abheben).\
+Während der Einrichtung pulsiert die RGB-Status-LED grün-türkis, solange du die Aufgabe noch nicht abgeschlossen hast, und bleibt 3 Sekunden lang grün-türkis, nachdem der Befehl gespeichert wurde.
 
 Nach Abschluss der Einrichtung endet der Prozess automatisch und zeigt den entsprechenden Status an.
 
 #### Manuell: No pain, no gain!
-Du findest auch einen `Last Bus Command` Text Sensor, der den letzten Bus-Befehl im Hexadezimalformat anzeigt.
+Du findest auch den guten alten `Last Bus Command` Text Sensor, der den letzten Bus-Befehl im Hexadezimalformat anzeigt.
 Außerdem wird jeder empfangene Befehl in der ESPHome-Konsole (Debug-Log-Ebene) protokolliert und als Home Assistant-Ereignis veröffentlicht.
 
 Um die Codes zu erfassen, drücke die Tasten an deinem Etagen-Telefon und kopiere die Codes anschließend in die entsprechenden Konfigurationstextfelder.
@@ -78,43 +128,4 @@ wifi:
   ssid: !secret wifi_ssid
   password: !secret wifi_password
 ```
-:::
-
-
-## Verkabelung
-Öffne als Erstes das Gehäuse deiner Gegensprechanlage. In den meisten Fällen findest du dort eine Schraubklemme mit den Bezeichnungen `a`, `b`, `E` und `P`.
-
-Schließe die `b`-Leitung (Ground) an einen der TCS:BUS-Anschlüsse deines Doorman an und die `a`-Leitung (24V Bus) an den anderen TCS:BUS-Anschluss deines Doorman.
-
-### Stromversorgungsoptionen:
-::: details 3-Draht-Modus über die Gegensprechanlage <Badge type="tip" text="Empfohlen" />
-Verbinde die `P`-Leitung (+24V) mit dem `P`-Terminal an deinem Doorman.
-
-> [!WARNING]
-> Die Stromversorgung der Gegensprechanlage muss mindestens 60mA liefern.
-
-Beispiel:
-![3-wire](./images/3wire.png){width=300px}
-:::
-
-::: details 2-Draht-Modus über externe Stromversorgung
-Schließe die externe Stromversorgung an deinen Doorman an. Nutze dazu die `P` (+5V bis +30V) und `G` (Ground) Schraubklemmen an deinem Doorman.
-
-Beispiel:
-![2-wire external via screw terminal](./images/2wire_power_screwterminal.png){width=300px}
-:::
-
-::: details 2-Draht-Modus über externe USB-C-Stromversorgung
-Schließe die externe Stromversorgung über den USB-C-Anschluss an.
-
-Beispiel:
-![2-wire external via usb](./images/2wire_power_usb_c.png){width=300px}
-:::
-
-::: details 2-Draht-Modus über die Gegensprechanlage <Badge type="danger" text="Nicht möglich" />
-> [!DANGER] Das ist leider nicht möglich!
-> Die Nutzung der `a`-Bus-Leitung als Stromquelle führt zu einem lauten Piepton. Dieses Problem tritt wahrscheinlich aufgrund der Hochfrequenz-Schaltstromversorgung auf und könnte in zukünftigen Hardware-Versionen behoben werden.
-
-Beispiel:
-![2-wire external via usb](./images/2wire_power_a_terminal.png){width=300px}
 :::
diff --git a/docs/de/guide/hardware-compatibility.md b/docs/de/guide/hardware-compatibility.md
@@ -1,4 +1,4 @@
-### Kann ich Doorman benutzen?
+# Kann ich Doorman benutzen?
 
 Wenn deine [TCS](https://www.tcsag.de/) oder [Koch](https://www.kochag.ch/) Gegensprechanlage die Anschlussklemmen `a`, `b` und `P` hat und mit 24V DC betrieben wird, ist sie wahrscheinlich kompatibel.
 
@@ -22,15 +22,17 @@ Wenn deine Gegensprechanlage im 2-Draht-Modus angeschlossen ist und du keine sep
 Wenn sie im 3-Draht-Modus angeschlossen ist, solltest du in den meisten Fällen die `P`-Leitung zur Stromversorgung vom Doorman nutzen können.
 
 ::: tip
-In einigen Installationen sind die `a`- und `b`-Drähte verdreht, aber das wird von Doormans integriertem Brückengleichrichter berücksichtigt. Berücksichtige dies beim Überprüfen der Spannung auf den Leitungen `a`, `b` und `P`.
+Bei einigen Installationen sind die `a`- und `b`-Drähte verdreht, das wird aber von dem integriertem Brückengleichrichter korrigiert.
+
+Berücksichtige dies beim Überprüfen der Spannung auf den Leitungen `a`, `b` und `P`.
 :::
 
 #### Erklärung der Gegensprechanlagen-Anschlussklemmen
-- **a:** Typischerweise die Bus-Leitung (+24V)
-- **b:** Typischerweise Ground
-- **P:** Die +24V-Leitung im 3-Draht-Modus oder der Klingelknopf der Wohnung im 2-Draht-Modus
+- **a:** In der Regel die Bus-Leitung (+24V)
+- **b:** Normalerweise Ground
+- **P:** Entweder die +24V-Leitung im 3-Draht-Modus oder der Klingelknopf der Wohnung im 2-Draht-Modus. Oftmals gibt es trotzdem eine 24V Leitung irgendwo versteckt.
 
-::: danger
+::: danger VORSICHT
 **NICHT GLEICHZEITIG DIE +24V `P`-LEITUNG UND USB-C VERWENDEN**
 :::
 

diff --git a/docs/de/guide/support/support.md b/docs/de/guide/support/support.md
@@ -17,6 +17,10 @@ If you've received a Doorman-S3 PCB that hasn't been pre-flashed with the [Stock
 To resolve this, hold down the button labeled `FLASH` while connecting the USB cable to your computer. This will put the ESP into bootloader mode, preventing it from constantly restarting.
 :::
 
+::: details A loud beeping noise occurs on the phone
+Please take a look [here](../hardware-compatibility#bekannte-probleme).
+:::
+
 ::: details Home Assistant can't connect / BAD_INDICATOR errno=11
 If Home Assistant can't connect to your Doorman, or you are receiving the error Reading failed: BAD_INDICATOR errno=11 in the logs, this indicates Home Assistant may be trying to connect with an incorrect encryption key.
 
@@ -37,7 +41,7 @@ If your Doorman is unable to receive commands there could be several reasons.
 
 #### Check the wiring
 Please make sure you wired everything correctly.\
-You can find the guide [here](../getting-started#wiring).
+You can find the guide [here](../getting-started#verkabelung).
 
 #### Check the Bus voltage
 There are cases where the bus voltage is inusfficient and causing the reading to fail.\

diff --git a/docs/de/reference/entities.md b/docs/de/reference/entities.md
@@ -54,8 +54,8 @@ Meldet den Türsensorstatus des gekoppelten Nuki Smart Locks.
 
 ## Text Sensors
 
-### Easy Setup: Status
-Zeigt den aktuellen Status vom [Easy Setup](../guide/getting-started#easy-setup) Prozess an.
+### Interactive Setup: Status
+Zeigt den aktuellen Status vom [Interactive Setup](../guide/getting-started#interactive-setup) Prozess an.
 
 
 ## Schalter
@@ -84,11 +84,11 @@ Steuert den Nuki Kopplungsmodus.
 ### Turn on the light  
 Schaltet das Licht ein, indem der Befehl `turn_on_light_command` auf dem Bus gesendet wird.
 
-### Easy Setup: Start <Badge type="tip" text="doorman_easy_setup_start" />
-Startet den [Easy Setup](../guide/getting-started#easy-setup) Prozess um Bus Commands einzurichten.
+### Interactive Setup: Start <Badge type="tip" text="doorman_interactive_setup_start" />
+Startet den [Interactive Setup](../guide/getting-started#interactive-setup) Prozess um Bus Commands einzurichten.
 
-### Easy Setup: Cancel <Badge type="tip" text="doorman_easy_setup_cancel" />
-Beendet den [Easy Setup](../guide/getting-started#easy-setup) Prozess.
+### Interactive Setup: Cancel <Badge type="tip" text="doorman_interactive_setup_cancel" />
+Beendet den [Interactive Setup](../guide/getting-started#interactive-setup) Prozess.
 
 ### Nuki Unpair Device  
 Entkoppelt dein Nuki Smart Lock.

diff --git a/docs/en/guide/getting-started.md b/docs/en/guide/getting-started.md
@@ -1,8 +1,50 @@
-# Getting started
+# Getting Started
 
-Here is a detailed guide on setting up your Doorman for the first time. Please note that these instructions are based on the pre-flashed Doorman PCB that I sell.
+Is this your first time here? Don't worry, we've got you covered!
+Below, you'll find a detailed guide for setting up your Doorman for the first time.
+
+Please note that these instructions are based on the pre-flashed Doorman PCB that I sell. If you've had a PCB manufactured yourself, make sure to flash the firmware first; otherwise, you might be waiting a long time for anything described below to happen. 😄
+
+**Thank you so much for using Doorman! ❤️**
+
+## Wiring
+First, open your intercom enclosure. On most models, you will find a screw terminal labeled with `a`, `b`, `E`, and `P`.
+
+Connect the `b` line (Ground) to one of the TCS:BUS terminals on your Doorman, and connect the `a` line (24V Bus) to the other TCS:BUS terminal on your Doorman.
+
+### Power supply options:
+::: details 3-Wire Mode via intercom <Badge type="tip" text="Recommended" />
+Connect the `P` line (+24V) to the `P` terminal on your Doorman.
+
+> [!WARNING]
+> The intercom power supply must provide at least 60mA.
+
+Example:
+![3-wire](./images/3wire.png){width=300px}
+:::
+
+::: details 2-Wire Mode via external wired Power Supply
+Connect the external power supply to your Doorman using the `P` (+5V to +30V) and `G` (Ground) screw terminals.
+
+Example:
+![2-wire external via screw terminal](./images/2wire_power_screwterminal.png){width=300px}
+:::
+
+::: details 2-Wire Mode via external USB-C Power Supply
+Connect the external power supply via the USB-C port.
+
+Example:
+![2-wire external via usb](./images/2wire_power_usb_c.png){width=300px}
+:::
+
+::: details 2-Wire Mode via intercom <Badge type="danger" text="Impossible" />
+> [!DANGER] Unfortunately this scenario is not possible!
+> Using the `a`-bus line as a power source results in a loud beeping noise. This issue is likely due to the high-frequency switching power supply and may be addressed in future hardware revisions.
+
+Example:
+![2-wire external via usb](./images/2wire_power_a_terminal.png){width=300px}
+:::
 
-Thank you for using Doorman! <3
 
 ## Setup
 
@@ -12,7 +54,7 @@ When you power on your Doorman-S3 for the first time, it will blink rapidly (ora
 The Access Point password is `open-sesame`.
 
 Once connected to the Access Point, the web interface should open automatically (see also login to network notifications).\
-If it doesn’t, you can manually navigate to http://192.168.4.1/ in your browser.
+If it doesn't, you can manually navigate to http://192.168.4.1/ in your browser.
 
 ::: tip
 You can take advantage of automatic setup in Home Assistant if your Home Assistant has Bluetooth enabled.
@@ -25,24 +67,26 @@ Additionally, with mDNS support, Home Assistant will automatically discover your
 After connecting Doorman to your network, it will blink slowly (blue) and should be automatically discovered by Home Assistant. Simply click on `Configure` to add the newly discovered ESPHome node.
 
 ### Step 3: Bus Commands
-::: warning Before proceeding
-You need to connect your Doorman to the intercom. Please refer to the [Wiring](#wiring) section for detailed instructions.
+::: tip
+After connecting your Doorman to Home Assistant, the `Interactive Setup` Process will automatically begin as described below.
+
+There's no need to start it manually; it will initiate automatically on every restart, provided the process hasn't been completed or canceled.
 :::
 
-#### Easy Setup
-To simplify the configuration of the key commands, you can use the Easy Setup Process.
+#### Interactive Setup <Badge type="warning" text="NEW" />
+To simplify the configuration of the key commands, you can use the Interactive Setup Process.
 
 To get started, either access the internal web server of your Doorman or visit the [ESPHome Integration page](https://my.home-assistant.io/redirect/integration/?domain=esphome) and select the newly listed Doorman S3 device entry.
 
-In the `Configuration` section, you will find the `Easy Setup: Start` button. Click this button to initiate the setup process.
+In the `Configuration` section, you will find the `Interactive Setup: Start` button. Click this button to initiate the setup process.
 
-Once started, the `Easy Setup: Status` Text Sensor will guide you through the required steps (e.g., press button X, wait, or pick up the phone).\
-During the setup, the RGB Status LED will pulse red while waiting for you to complete each task and will remain solid red for 3 seconds after saving the command.
+Once started, the `Interactive Setup: Status` Text Sensor will guide you through the required steps (e.g., press button X, wait, or pick up the phone).\
+During the setup, the RGB Status LED will pulse green-turquoise while waiting for you to complete each task and will remain solid green-turquoise for 3 seconds after saving the command.
 
 After the setup is complete, the process will automatically end and display the corresponding status.
 
 #### Manual: No pain, no gain!
-You will also find a `Last Bus Command` Text Sensor that tracks the most recent bus command in hexadecimal format.
+You will also find the good old `Last Bus Command` Text Sensor that tracks the most recent bus command in hexadecimal format.
 Additionally, each received command is logged in the ESPHome Console (at the Debug log level) and published as a Home Assistant event.
 
 To capture the codes, press the buttons on your intercom phone and then copy the codes into the corresponding configuration text inputs.
@@ -79,43 +123,4 @@ wifi:
   ssid: !secret wifi_ssid
   password: !secret wifi_password
 ```
-:::
-
-
-## Wiring
-First, open your intercom enclosure. On most models, you will find a screw terminal labeled with `a`, `b`, `E`, and `P`.
-
-Connect the `b` line (Ground) to one of the TCS:BUS terminals on your Doorman, and connect the `a` line (24V Bus) to the other TCS:BUS terminal on your Doorman.
-
-### Power supply options:
-::: details 3-Wire Mode via intercom <Badge type="tip" text="Recommended" />
-Connect the `P` line (+24V) to the `P` terminal on your Doorman.
-
-> [!WARNING]
-> The intercom power supply must provide at least 60mA.
-
-Example:
-![3-wire](./images/3wire.png){width=300px}
-:::
-
-::: details 2-Wire Mode via external wired Power Supply
-Connect the external power supply to your Doorman using the `P` (+5V to +30V) and `G` (Ground) screw terminals.
-
-Example:
-![2-wire external via screw terminal](./images/2wire_power_screwterminal.png){width=300px}
-:::
-
-::: details 2-Wire Mode via external USB-C Power Supply
-Connect the external power supply via the USB-C port.
-
-Example:
-![2-wire external via usb](./images/2wire_power_usb_c.png){width=300px}
-:::
-
-::: details 2-Wire Mode via intercom <Badge type="danger" text="Impossible" />
-> [!DANGER] Unfortunately this scenario is not possible!
-> Using the `a`-bus line as a power source results in a loud beeping noise. This issue is likely due to the high-frequency switching power supply and may be addressed in future hardware revisions.
-
-Example:
-![2-wire external via usb](./images/2wire_power_a_terminal.png){width=300px}
 :::