Update examples, fix HomeAssistant configuration.yaml, add HomeAssist…

…ant trouble status
taligentx · Jun 25, 2018 · 7c1b2c2 · 7c1b2c2
1 parent 3bdde1f
commit 7c1b2c2
Show file tree

Hide file tree

Showing 12 changed files with 147 additions and 223 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,13 @@
 # DSC Keybus Interface
 This library directly interfaces Arduino and esp8266 microcontrollers to [DSC PowerSeries](http://www.dsc.com/dsc-security-products/g/PowerSeries/4) security systems for integration with home automation, notifications on system events, and usage as a virtual keypad.  The included examples demonstrate monitoring armed/alarm/zone/fire/trouble states, integrating with Home Assistant/Apple HomeKit/Homey, sending push notifications/email, and reading/decoding Keybus data.
 
-For example, an Arduino Uno (with an ethernet module) or the inexpensive NodeMCU and Wemos D1 Mini modules ($3USD shipped) can be used with [Homebridge](https://github.com/nfarina/homebridge) for notifications and control of the security system through the iOS Home app and Siri:
+For example, an Arduino Uno (with an ethernet/wifi module) or the inexpensive NodeMCU and Wemos D1 Mini modules ($3USD shipped) can enable mobile devices to control the security system:
 
-![dscHomeKit](https://user-images.githubusercontent.com/12835671/39588413-5a99099a-4ec1-11e8-9a2e-e332fa2d6379.jpg)
+* Apple Home and Siri:
+  ![HomeKit](https://user-images.githubusercontent.com/12835671/39588413-5a99099a-4ec1-11e8-9a2e-e332fa2d6379.jpg)
+
+* Home Assistant:
+  ![HomeAssistant](https://user-images.githubusercontent.com/12835671/41829054-34741e74-77fe-11e8-9d5e-fbc8601b9fc4.png)
 
 ## Features
 * Status tracking of armed/alarm/fire states for partitions 1-8
@@ -17,11 +21,13 @@ For example, an Arduino Uno (with an ethernet module) or the inexpensive NodeMCU
   - esp8266: NodeMCU, Wemos D1 Mini, ESP12, etc
 
 ## Release notes
-* 0.4-develop
+* 0.4
   - New: Virtual keypad support for partitions 3-8, thanks to [jvitkauskas](https://github.com/jvitkauskas) for contributing the necessary logs
   - New: Support ATmega32U4-based Arduino boards (switched to AVR Timer1)
+  - Changed: Simplified example names, configurations, added version numbers
   - Bugfix: Virtual keypad writes with partitions 5-8 enabled
   - Bugfix: F/A/P alarm key writes with `processModuleData` disabled
+  - Bugfix: HomeAssistant example `configuration.yaml` error for `alarm_control_panel`
 * 0.3
   - New: Status for partitions 2-8, zones 33-64
   - New: Virtual keypad support for partition 2
@@ -49,13 +55,9 @@ For example, an Arduino Uno (with an ethernet module) or the inexpensive NodeMCU
 * Alternatively, `git clone` or download the repo .zip to the Arduino/PlatformIO library directory to keep track of the latest changes.
 
 ## Examples
-* KeybusReader: Decodes and prints data from the Keybus to a serial interface, including reading from serial for the virtual keypad.
-
-  This is primarily to help decode the Keybus protocol - at this point, I've decoded a substantial portion of the commands seen in the [DSC IT-100 Developers Guide](http://cms.dsc.com/download.php?t=1&id=16238) (which also means that a very basic IT-100 emulator is possible).  The notable exceptions are the thermostat and wireless commands as I do not have these modules.
-
-  See `src/dscKeybusPrintData.cpp` for all currently known Keybus protocol commands and messages.  Issues and pull requests with additions/corrections are welcome!
+The included examples demonstrate how to use the library and can be used as-is or adapted to integrate with other software.  Post an issue/pull request if you've developed a sketch/integration that others can use.
 
-* Status: Processes and prints the security system status to a serial interface, including reading from serial for the virtual keypad.  This demonstrates how to determine if the security system status has changed, what has changed, and how to take action based on those changes.  Post an issue/pull request if you have a use for additional commands - for now, only a subset of all decoded commands are being tracked for status to limit memory usage:
+* Status: Processes and prints the security system status to a serial interface, including reading from serial for the virtual keypad.  This demonstrates how to determine if the security system status has changed, what has changed, and how to take action based on those changes.  Post an issue/pull request if you have a use for additional system states - for now, only a subset of all decoded commands are being tracked for status to limit memory usage:
   * Partitions armed away/stay/disarmed
   * Partitions in alarm
   * Partitions exit delay in progress
@@ -68,15 +70,21 @@ For example, an Arduino Uno (with an ethernet module) or the inexpensive NodeMCU
   * Panel battery
   * Panel trouble
 
-* Status-MQTT-Homebridge: Processes the security system status and allows for control using Apple HomeKit, including the iOS Home app and Siri.  This uses MQTT to interface with [Homebridge](https://github.com/nfarina/homebridge) and [homebridge-mqttthing](https://github.com/arachnetech/homebridge-mqttthing) for HomeKit integration and demonstrates using the armed and alarm states for the HomeKit securitySystem object, zone states for the contactSensor objects, and fire alarm states for the smokeSensor object.
+* Homebridge-MQTT: Integrates with Apple HomeKit, including the iOS Home app and Siri.  This uses MQTT to interface with [Homebridge](https://github.com/nfarina/homebridge) and [homebridge-mqttthing](https://github.com/arachnetech/homebridge-mqttthing) and demonstrates using the armed and alarm states for the HomeKit securitySystem object, zone states for the contactSensor objects, and fire alarm states for the smokeSensor object.
 
-* Status-MQTT-HomeAssistant: Processes the security system status and allows for control with [Home Assistant](https://www.home-assistant.io) via MQTT.  This uses the armed and alarm states for the HomeAssistant [Alarm Control Panel](https://www.home-assistant.io/components/alarm_control_panel.mqtt) component, as well as fire alarm and zone states for the [Binary Sensor](https://www.home-assistant.io/components/binary_sensor.mqtt) component.
+* HomeAssistant-MQTT: Integrates with [Home Assistant](https://www.home-assistant.io) via MQTT.  This uses the armed and alarm states for the HomeAssistant [Alarm Control Panel](https://www.home-assistant.io/components/alarm_control_panel.mqtt) component, as well as zone, fire alarm, and trouble states for the [Binary Sensor](https://www.home-assistant.io/components/binary_sensor.mqtt) component.
 
-* Status-Homey: Processes the security system status and allows for control using [Athom Homey](https://www.athom.com/en/) and the [Homeyduino](https://github.com/athombv/homey-arduino-library/) library, including armed, alarm, fire, and zone states.
+* Homey: Integrates with [Athom Homey](https://www.athom.com/en/) and the [Homeyduino](https://github.com/athombv/homey-arduino-library/) library, including armed, alarm, fire, and zone states.
 
-* Status-Pushbullet (esp8266-only):  Processes the security system status and demonstrates how to send a push notification when the status has changed. This example sends notifications via [Pushbullet](https://www.pushbullet.com) and requires the esp8266 for SSL support.
+* Pushbullet (esp8266-only):  Demonstrates how to send a push notification when the status has changed. This example sends notifications via [Pushbullet](https://www.pushbullet.com) and requires the esp8266 for SSL support.
 
-* Status-Email (esp8266-only): Processes the security system status and demonstrates how to send an email when the status has changed. Email is sent using SMTPS (port 465) with SSL for encryption - this is necessary on the ESP8266 until STARTTLS can be supported.  For example, this will work with Gmail after changing the account settings to [allow less secure apps](https://support.google.com/accounts/answer/6010255).
+* Email (esp8266-only): Demonstrates how to send an email when the status has changed. Email is sent using SMTPS (port 465) with SSL for encryption - this is necessary on the ESP8266 until STARTTLS can be supported.  For example, this will work with Gmail after changing the account settings to [allow less secure apps](https://support.google.com/accounts/answer/6010255).
+
+* KeybusReader: Decodes and prints data from the Keybus to a serial interface, including reading from serial for the virtual keypad.
+
+  This is primarily to help decode the Keybus protocol - at this point, I've decoded a substantial portion of the commands seen in the [DSC IT-100 Developers Guide](http://cms.dsc.com/download.php?t=1&id=16238) (which also means that a very basic IT-100 emulator is possible).  The notable exceptions are the thermostat and wireless commands as I do not have these modules.
+
+  See `src/dscKeybusPrintData.cpp` for all currently known Keybus protocol commands and messages.  Issues and pull requests with additions/corrections are welcome!
 
 ## Wiring
 

diff --git a/...meAssistant/Status-MQTT-HomeAssistant.ino → ...HomeAssistant-MQTT/HomeAssistant-MQTT.ino b/...meAssistant/Status-MQTT-HomeAssistant.ino → ...HomeAssistant-MQTT/HomeAssistant-MQTT.ino
@@ -1,17 +1,12 @@
 /*
- *  DSC Status with MQTT (Arduino)
+ *  HomeAssistant-MQTT 0.4 (Arduino)
  *
  *  Processes the security system status and allows for control using Home Assistant via MQTT.
  *
  *  Home Assistant: https://www.home-assistant.io
  *  Mosquitto MQTT broker: https://mosquitto.org
  *
- *  For a single partition, the commands to set the alarm state are setup in Home Assistant as:
- *    Disarm: "D"
- *    Arm stay: "S"
- *    Arm away: "A"
- *
- *  For multiple partitions, add the partition number as a prefix to the command:
+ *  The commands to set the alarm state are setup in Home Assistant with the partition number (1-8) as a prefix to the command:
  *    Partition 1 disarm: "1D"
  *    Partition 2 arm stay: "2S"
  *    Partition 2 arm away: "2A"
@@ -24,15 +19,19 @@
  *    Exit delay in progress: "pending"
  *    Alarm tripped: "triggered"
  *
+ *  The trouble state is published in the configured mqttTroubleTopic.  The trouble state is published as an integer:
+ *    Trouble: "1"
+ *    Trouble restored: "0"
+ *
  *  Zone states are published in a separate topic per zone with the configured mqttZoneTopic appended with the zone
  *  number.  The zone state is published as an integer:
- *    Closed: "0"
  *    Open: "1"
+ *    Closed: "0"
  *
  *  Fire states are published in a separate topic per partition with the configured mqttFireTopic appended with the
  *  partition number.  The fire state is published as an integer:
- *    "0": fire alarm restored
- *    "1": fire alarm tripped
+ *    Fire alarm: "1"
+ *    Fire alarm restored: "0"
  *
  *  Example Home Assistant configuration.yaml:
 
@@ -42,17 +41,6 @@
         client_id: homeAssistant
 
       # https://www.home-assistant.io/components/alarm_control_panel.mqtt/
-      # Single partition example:
-      alarm_control_panel:
-        - platform: mqtt
-          name: "Security System"
-          state_topic: "dsc/Get/Partition1"
-          command_topic: "dsc/Set"
-          payload_disarm: "D"
-          payload_arm_home: "S"
-          payload_arm_away: "A"
-
-      # Multiple partition example:
       alarm_control_panel:
         - platform: mqtt
           name: "Security System Partition 1"
@@ -61,7 +49,6 @@
           payload_disarm: "1D"
           payload_arm_home: "1S"
           payload_arm_away: "1A"
-      alarm_control_panel:
         - platform: mqtt
           name: "Security System Partition 2"
           state_topic: "dsc/Get/Partition2"
@@ -72,22 +59,40 @@
 
       # https://www.home-assistant.io/components/binary_sensor/
       binary_sensor:
+        - platform: mqtt
+          name: "Security Trouble"
+          state_topic: "dsc/Get/Trouble"
+          device_class: "problem"
+          payload_on: "1"
+          payload_off: "0"
+        - platform: mqtt
+          name: "Smoke Alarm 1"
+          state_topic: "dsc/Get/Fire1"
+          device_class: "smoke"
+          payload_on: "1"
+          payload_off: "0"
+        - platform: mqtt
+          name: "Smoke Alarm 2"
+          state_topic: "dsc/Get/Fire2"
+          device_class: "smoke"
+          payload_on: "1"
+          payload_off: "0"
         - platform: mqtt
           name: "Zone 1"
           state_topic: "dsc/Get/Zone1"
           device_class: "door"
           payload_on: "1"
           payload_off: "0"
         - platform: mqtt
-          name: "Zone 8"
-          state_topic: "dsc/Get/Zone8"
+          name: "Zone 2"
+          state_topic: "dsc/Get/Zone2"
           device_class: "window"
           payload_on: "1"
           payload_off: "0"
         - platform: mqtt
-          name: "Smoke Alarm"
-          state_topic: "dsc/Get/Fire1"
-          device_class: "smoke"
+          name: "Zone 3"
+          state_topic: "dsc/Get/Zone3"
+          device_class: "motion"
           payload_on: "1"
           payload_off: "0"
 
@@ -138,6 +143,7 @@ const char* mqttClientName = "dscKeybusInterface";
 const char* mqttPartitionTopic = "dsc/Get/Partition";  // Sends armed and alarm status per partition: dsc/Get/Partition1 ... dsc/Get/Partition8
 const char* mqttZoneTopic = "dsc/Get/Zone";            // Sends zone status per zone: dsc/Get/Zone1 ... dsc/Get/Zone64
 const char* mqttFireTopic = "dsc/Get/Fire";            // Sends fire status per partition: dsc/Get/Fire1 ... dsc/Get/Fire8
+const char* mqttTroubleTopic = "dsc/Get/Trouble";      // Sends trouble status
 const char* mqttSubscribeTopic = "dsc/Set";            // Receives messages to write to the panel
 unsigned long mqttPreviousTime;
 
@@ -196,6 +202,12 @@ void loop() {
       dsc.write(accessCode);
     }
 
+    if (dsc.troubleChanged) {
+      dsc.troubleChanged = false;  // Resets the trouble status flag
+      if (dsc.trouble) mqtt.publish(mqttTroubleTopic, "1", true);
+      else mqtt.publish(mqttTroubleTopic, "0", true);
+    }
+
     // Publishes status per partition
     for (byte partition = 0; partition < dscPartitions; partition++) {
 

diff --git a/...QTT-Homebridge/Status-MQTT-Homebridge.ino → ...duino/Homebridge-MQTT/Homebridge-MQTT.ino b/...QTT-Homebridge/Status-MQTT-Homebridge.ino → ...duino/Homebridge-MQTT/Homebridge-MQTT.ino
@@ -1,5 +1,5 @@
 /*
- *  DSC Status with MQTT (Arduino)
+ *  Homebridge-MQTT 0.4 (Arduino)
  *
  *  Processes the security system status and allows for control using Apple HomeKit, including the iOS Home app and
  *  Siri.  This uses MQTT to interface with Homebridge and the homebridge-mqttthing plugin for HomeKit integration
@@ -10,13 +10,7 @@
  *  homebridge-mqttthing: https://github.com/arachnetech/homebridge-mqttthing
  *  Mosquitto MQTT broker: https://mosquitto.org
  *
- *  For a single partition, the commands to set the alarm state are setup in Homebridge as:
- *    Stay arm: "S"
- *    Away arm: "A"
- *    Night arm (arm without an entry delay): "N"
- *    Disarm: "D"
- *
- *  For multiple partitions, add the partition number as a prefix to the command:
+ *  The commands to set the alarm state are setup in Homebridge with the partition number (1-8) as a prefix to the command:
  *    Partition 1 stay arm: "1S"
  *    Partition 1 away arm: "1A"
  *    Partition 2 night arm (arm without an entry delay): "2N"
@@ -32,63 +26,15 @@
  *
  *  Zone states are published in a separate topic per zone with the configured mqttZoneTopic appended with the zone
  *  number.  The zone state is published as an integer:
- *    "0": closed
- *    "1": open
+ *    Open: "1"
+ *    Closed: "0"
  *
  *  Fire states are published in a separate topic per partition with the configured mqttFireTopic appended with the
  *  partition number.  The fire state is published as an integer:
- *    "0": fire alarm restored
- *    "1": fire alarm tripped
+ *    Fire alarm: "1"
+ *    Fire alarm restored: "0"
  *
- *  Example Homebridge config.json "accessories" configuration for a single partition:
-
-        {
-            "accessory": "mqttthing",
-            "type": "securitySystem",
-            "name": "Security System",
-            "url": "http://127.0.0.1:1883",
-            "topics":
-            {
-                "getCurrentState":    "dsc/Get/Partition1",
-                "setTargetState":     "dsc/Set"
-            },
-            "targetStateValues": ["S", "A", "N", "D"]
-        },
-        {
-            "accessory": "mqttthing",
-            "type": "contactSensor",
-            "name": "Zone 1",
-            "url": "http://127.0.0.1:1883",
-            "topics":
-            {
-                "getContactSensorState": "dsc/Get/Zone1"
-            },
-            "integerValue": "true"
-        },
-        {
-            "accessory": "mqttthing",
-            "type": "contactSensor",
-            "name": "Zone 8",
-            "url": "http://127.0.0.1:1883",
-            "topics":
-            {
-                "getContactSensorState": "dsc/Get/Zone8"
-            },
-            "integerValue": "true"
-        },
-        {
-            "accessory": "mqttthing",
-            "type": "smokeSensor",
-            "name": "Smoke Alarm",
-            "url": "http://127.0.0.1:1883",
-            "topics":
-            {
-                "getSmokeDetected": "dsc/Get/Fire1"
-            },
-            "integerValue": "true"
-        }
-
- *  Example Homebridge config.json "accessories" configuration for multiple partitions:
+ *  Example Homebridge config.json "accessories" configuration:
 
         {
             "accessory": "mqttthing",
@@ -116,45 +62,45 @@
         },
         {
             "accessory": "mqttthing",
-            "type": "contactSensor",
-            "name": "Zone 1",
+            "type": "smokeSensor",
+            "name": "Smoke Alarm Partition 1",
             "url": "http://127.0.0.1:1883",
             "topics":
             {
-                "getContactSensorState": "dsc/Get/Zone1"
+                "getSmokeDetected": "dsc/Get/Fire1"
             },
             "integerValue": "true"
         },
         {
             "accessory": "mqttthing",
-            "type": "contactSensor",
-            "name": "Zone 8",
+            "type": "smokeSensor",
+            "name": "Smoke Alarm Partition 2",
             "url": "http://127.0.0.1:1883",
             "topics":
             {
-                "getContactSensorState": "dsc/Get/Zone8"
+                "getSmokeDetected": "dsc/Get/Fire2"
             },
             "integerValue": "true"
         },
         {
             "accessory": "mqttthing",
-            "type": "smokeSensor",
-            "name": "Smoke Alarm Partition 1",
+            "type": "contactSensor",
+            "name": "Zone 1",
             "url": "http://127.0.0.1:1883",
             "topics":
             {
-                "getSmokeDetected": "dsc/Get/Fire1"
+                "getContactSensorState": "dsc/Get/Zone1"
             },
             "integerValue": "true"
-        }
+        },
         {
             "accessory": "mqttthing",
-            "type": "smokeSensor",
-            "name": "Smoke Alarm Partition 2",
+            "type": "contactSensor",
+            "name": "Zone 2",
             "url": "http://127.0.0.1:1883",
             "topics":
             {
-                "getSmokeDetected": "dsc/Get/Fire2"
+                "getContactSensorState": "dsc/Get/Zone2"
             },
             "integerValue": "true"
         }

diff --git a/examples/Arduino/KeybusReader/KeybusReader.ino b/examples/Arduino/KeybusReader/KeybusReader.ino
@@ -1,5 +1,5 @@
 /*
- *  DSC Keybus Reader (Arduino)
+ *  DSC Keybus Reader 0.4 (Arduino)
  *
  *  Decodes and prints data from the Keybus to a serial interface, including reading from serial for the virtual
  *  keypad.  This is primarily to help decode the Keybus protocol - see the Status examples to put the interface

diff --git a/examples/Arduino/Status/Status.ino b/examples/Arduino/Status/Status.ino
@@ -1,5 +1,5 @@
 /*
- *  DSC Status (Arduino)
+ *  DSC Status 0.4 (Arduino)
  *
  *  Processes and prints the security system status to a serial interface, including reading from serial for the
  *  virtual keypad.  This demonstrates how to determine if the security system status has changed, what has

diff --git a/...les/esp8266/Status-Email/Status-Email.ino → examples/esp8266/Email/Email.ino b/...les/esp8266/Status-Email/Status-Email.ino → examples/esp8266/Email/Email.ino
@@ -1,5 +1,5 @@
 /*
- *  DSC Status with email notification (esp8266)
+ *  Email Notification 0.4 (esp8266)
  *
  *  Processes the security system status and demonstrates how to send an email when the status has changed.  Configure
  *  the email SMTP server settings in sendEmail().