Merge pull request #4 from gdoor-org/improve-ha-docs

More detailed MQTT docs for Home Assistant
gdoor-org · Dec 28, 2024 · 1f0f3fa · 1f0f3fa
2 parents a44b617 + c099091
commit 1f0f3fa
Showing 1 changed file with 62 additions and 35 deletions.
diff --git a/documentation/homeassistant.md b/documentation/homeassistant.md
@@ -18,22 +18,21 @@ There are two possibilities:
 
 ### MQTT (recommended)
 
-(Work in progress)
-
 GDoor supports Home Assistant MQTT Auto-Discovery.
 
 1. install [Home Assistant Add-on: Mosquitto broker](https://github.com/home-assistant/addons/blob/master/mosquitto/DOCS.md) and MQTT integration
 2. create user to be used for MQTT
 3. open [GDoor adapter web interface](http://GDoor/) (in case the link doesn't work, please lookup adapter IP address in your router)
-4. set MQTT host to the IP of your Home Assistant installation as well as the created MQTT user name and password.
+4. set MQTT host to the IP of your Home Assistant installation as well as the created MQTT user name and password
 5. now the `GDoor Adapter` device should appear in Home Assistant
 6. press the door bell
 7. press the "open door" button on your indoor station
-8. open Logbook and search for "GDoor", now you should see state changes like
+8. open the Home Assitant Logbook view and search for "GDoor", now you should see state changes like
    ```
    GDoor changed to {"action": "BUTTON_RING", "parameters": "0360", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "011011A286FD0360A04A"}
    ```
-   Note the value of the `parameters` field: this is the unique value of your door bell which you can use to identify your door bell in automations.
+9. look for the `BUTTON_RING` action: note the value of the `parameters` field, this is the unique value of your door bell which you can use to identify your door bell in automations.
+10. look for the `DOOR_OPEN` action: note the `busdata` field, if you want to open the door via Home Assistant you need to send this exact value to the MQTT topic `gdoor/bus_tx`
 
 
 
@@ -43,7 +42,7 @@ GDoor supports Home Assistant MQTT Auto-Discovery.
 2. edit `configuration.yaml` (e.g. via the [Home Assistant Add-on: Studio Code Server](https://github.com/hassio-addons/addon-vscode)) and add
 
     ```
-    sensors:
+    sensor:
       - platform: serial
         name: "GDoor"
         serial_port: /dev/ttyUSB0 # change device if needed
@@ -53,35 +52,48 @@ GDoor supports Home Assistant MQTT Auto-Discovery.
 3. restart Home Assistant
 4. press the door bell
 5. press the "open door" button on your indoor station
-6. open Logbook and search for "GDoor", now you should see state changes like
+6. open Home Assitant Logbook and search for "GDoor", now you should see state changes like
    ```
    GDoor changed to {"action": "BUTTON_RING", "parameters": "0360", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "011011A286FD0360A04A"}
    ```
-   Note the value of the `parameters` field: this is the unique value of your door bell which you can use to identify your door bell in automations.
-7. look for the `DOOR_OPEN` action, copy the value of `busdata` and add the following shell command in `configuration.yaml` to be able to open the door programmatically. Replace `<busdata>` with the copied value.
+7. look for the `BUTTON_RING` action: note the value of the `parameters` field, this is the unique value of your door bell which you can use to identify your door bell in automations.
+8. look for the `DOOR_OPEN` action: copy the value of `busdata` and add the following shell command in `configuration.yaml` to be able to open the door programmatically. Replace `<busdata>` with the copied value.
     ```
     shell_command:
       gdoor_open_door: echo -e '<busdata>' > /dev/ttyUSB0 # change busdata and device if needed
     ```
-8. restart Home Assistant
+9. restart Home Assistant
 
 
 
 # Examples for typical use cases
 
-### Open door via Home Assistant dashboard
+### Open door via Home Assistant dashboard / automation
 
-Simply call the above defined service `shell_command.gdoor_open_door` in e.g. a button card:
+Simply perform the HA action "MQTT: Publish" to replay the busdata which is sent when you open the door via your indoor station, e.g. in a button card:
 
 ```
+type: button
+name: Haustür öffnen
+icon: mdi:door-open
 show_name: true
 show_icon: true
-type: button
+tap_action:
+  action: perform-action
+  target: {}
+  perform_action: mqtt.publish
+  data:
+    qos: "0"
+    payload: 020031ED3F4B0060A1A254791A # check in Logbook which busdata is sent when you open the door bell via your indoor station
+    topic: gdoor/bus_tx
+```
+
+When using the USB / Serial connection, replace `tap_action` to call the above defined service `shell_command.gdoor_open_door`:
+
+```
 tap_action:
   action: call-service
   service: shell_command.gdoor_open_door
-name: Haustür öffnen
-icon: mdi:door-open
 ```
 
 ### Send notification to mobile devices on door/floor bell
@@ -90,21 +102,16 @@ Example automation:
 
 ```
 alias: Türklingel
-trigger:
-  - platform: state
-    entity_id:
-      - sensor.gdoor
+triggers:
+  - trigger: mqtt
+    topic: gdoor/bus_rx
 action:
   - choose:
       - conditions:
-          - condition: state
-            entity_id: sensor.gdoor
-            attribute: action
-            state: BUTTON_RING
-          - condition: state
-            entity_id: sensor.gdoor
-            attribute: parameters
-            state: "0360" # check in Logbook which parameter matches your door bell
+          - condition: template
+            value_template: >-
+              {{ trigger.payload_json.action == 'BUTTON_RING' and
+              trigger.payload_json.parameters == '0360' }} # check in Logbook which parameter matches your door bell
         sequence:
           - service: notify.all_smartphones # adjust to your notification group/device
             data:
@@ -113,14 +120,10 @@ action:
                   interruption-level: time-sensitive
               message: Türklingel (außen)
       - conditions:
-          - condition: state
-            entity_id: sensor.gdoor
-            attribute: action
-            state: BUTTON_FLOOR
-          - condition: state
-            entity_id: sensor.gdoor
-            attribute: parameters
-            state: "FF6F" # check in Logbook which parameter matches your floor bell
+          - condition: template
+            value_template: >-
+              {{ trigger.payload_json.action == 'BUTTON_FLOOR' and
+              trigger.payload_json.parameters == 'FF6F' }} # check in Logbook which parameter matches your floor bell
         sequence:
           - service: notify.all_smartphones # adjust to your notification group/device
             data:
@@ -130,3 +133,27 @@ action:
               message: Türklingel (innen)
 mode: single
 ```
+
+
+For USB / serial connection, adjust `triggers` to
+
+```
+triggers:
+  - platform: state
+    entity_id:
+      - sensor.gdoor
+```
+
+and `conditions` to e.g.:
+
+```
+      - conditions:
+          - condition: state
+            entity_id: sensor.gdoor
+            attribute: action
+            state: BUTTON_RING
+          - condition: state
+            entity_id: sensor.gdoor
+            attribute: parameters
+            state: "0360" # check in Logbook which parameter matches your door bell
+```