Update README.md

TheHolyRoger · May 18, 2022 · cc8ad7a · cc8ad7a
1 parent 1fa7482
commit cc8ad7a
Showing 1 changed file with 122 additions and 5 deletions.
diff --git a/README.md b/README.md
@@ -27,18 +27,32 @@ Designed for the standard "4x4 Matrix Keypad" you can find online. Tested with t
 
 Based off of the work from https://github.com/devWaves/SwitchBot-MQTT-BLE-ESP32
 
+Default Button config:
+  - **#**: Broadcast Alarm **ARM** code
+  - **D**: Broadcast Alarm **DISARM** code
+  - **B, C**: Clear inputted code
+  - **A**: Ignored (Both my keypads have issues with `B`/`C` being confused with `A`)
+
+Example LED config:
+  - **SUCCESS**: First (green) LED on pin 15
+  - **FAILURE**: Second (red) LED on pin 4
+  - **WARNING**: Third (yellow) LED on pin 18
+  - **STATUS**: Fourth (blue) LED on pin 19
+  - **KEYPRESS**: Second (red) LED on pin 4
+
 Notes:
   - Supports Home Assistant MQTT Discovery
   - OTA update included. Go to ESP32 IP address in browser. In Arduino IDE menu - Sketch / Export compile Binary . Upload the .bin file
   - Designed for 4x4 keypad but should work with 3x3 keypad by modifying `keys` in the advanced section.
+  - Also works if no code is set for arm/disarm, simply press the arm/disarm key without entering a code.
 
 **ESPMQTTTopic**
 
 \<ESPMQTTTopic\> = \<mqtt_main_topic\>/\<host\>
 
   - Default = esp32_alarm_keypad/home_alarm_keypad
 
-**ESP32 will subscribe to MQTT 'set' topic for 2 LED pins**
+**ESP32 will SUBSCRIBE to MQTT 'set' topic for 2 LED pins**
 
   - \<ESPMQTTTopic\>/status_light/set
   - \<ESPMQTTTopic\>/warning_light/set
@@ -48,7 +62,7 @@ Strings:
   - "ON"
   - "OFF"
 
-**ESP32 will respond with MQTT on 'state' topic for 2 LED pins**
+**ESP32 will RESPOND with MQTT on 'state' topic for 2 LED pins**
 
   - \<ESPMQTTTopic\>/status_light/state
   - \<ESPMQTTTopic\>/warning_light/state
@@ -57,16 +71,32 @@ Example payload:
   - "ON"
   - "OFF"
 
-**ESP32 will subscribe to MQTT 'code_success' topic which flashes the LEDs, used for successful/failed alarm code entry**
+**ESP32 will BROADCAST to MQTT 'code_exit' topic upon press of the Arm key with the entered code**
+
+  - \<ESPMQTTTopic\>/code_exit
+
+Use a Home Assistant automation to listen to this topic and then call the alarm arm service with the received code.
+Strings:
+  - \<ALARM_CODE\>
+
+**ESP32 will BROADCAST to MQTT 'code_entry' topic upon press of the Disarm key with the entered code**
+
+  - \<ESPMQTTTopic\>/code_entry
+
+Use a Home Assistant automation to listen to this topic and then call the alarm disarm service with the received code.
+Strings:
+  - \<ALARM_CODE\>
+
+**ESP32 will SUBSCRIBE to MQTT 'code_success' topic which flashes the LEDs, used for successful/failed alarm code entry**
 
   - \<ESPMQTTTopic\>/code_success
 
-Use a Home Assistant automation to detect success/failure then send a payload to the 'code_success' MQTT topic. 
+Use a Home Assistant automation to detect success/failure when arming/disarming the alarm, then send a payload to the 'code_success' MQTT topic. 
 Strings:
   - { "success": true }
   - { "success": false }
 
-**ESP32 will respond with MQTT on ESPMQTTTopic with ESP32 status**
+**ESP32 will RESPOND with MQTT on ESPMQTTTopic with ESP32 status**
 
   - \<ESPMQTTTopic\>
 
@@ -107,3 +137,90 @@ example payloads:
 <br>
 <br>
 
+## Example HASS Automations
+
+### Listen for ARM / Exit code
+```yaml
+
+alias: '[Alarm] Keypad Exit'
+description: ''
+trigger:
+  - platform: mqtt
+    topic: esp32_alarm_keypad/home_alarm_keypad/code_exit
+condition: []
+action:
+  - service: alarm_control_panel.alarm_arm_away
+    data:
+      code: '{{ trigger.payload | string }}'
+    target:
+      entity_id: alarm_control_panel.alarmo  # Adjust for your alarm entity
+  - delay:
+      hours: 0
+      minutes: 0
+      seconds: 1
+      milliseconds: 0
+  - choose:
+      - conditions:
+          - condition: not
+            conditions:
+              - condition: state
+                entity_id: alarm_control_panel.alarmo  # Adjust for your alarm entity
+                state: arming
+        sequence:
+          - service: mqtt.publish
+            data:
+              topic: esp32_alarm_keypad/home_alarm_keypad/code_success
+              payload: '{ "success": false }'
+    default: []
+mode: single
+
+```
+
+### Listen for DISARM / Entry code
+```yaml
+
+alias: '[Alarm] Keypad Entry'
+description: ''
+trigger:
+  - platform: mqtt
+    topic: esp32_alarm_keypad/home_alarm_keypad/code_entry
+condition: []
+action:
+  - service: alarm_control_panel.alarm_disarm
+    data:
+      code: '{{ trigger.payload | string }}'
+    target:
+      entity_id: alarm_control_panel.alarmo  # Adjust for your alarm entity
+  - delay:
+      hours: 0
+      minutes: 0
+      seconds: 1
+      milliseconds: 0
+  - choose:
+      - conditions:
+          - condition: not
+            conditions:
+              - condition: state
+                entity_id: alarm_control_panel.alarmo  # Adjust for your alarm entity
+                state: disarmed
+        sequence:
+          - service: mqtt.publish
+            data:
+              topic: esp32_alarm_keypad/home_alarm_keypad/code_success
+              payload: '{ "success": false }'
+    default: []
+mode: single
+
+```
+
+### Activating Warning/Status Lights
+Simply add triggers for your alarm entity changing state to turn the corresponding `LIGHT` entities on/off.
+
+E.g.
+  - **ARMING**: Turn `WARNING` light `ON`.
+  - **ARMED**: Turn `STATUS` light `ON`.
+  - **DISARMED**: Turn `STATUS` and `WARNING` lights `OFF`.
+  - **ENTRY**: Turn `STATUS` and `WARNING` lights `ON`.
+
+
+