Merge branch 'master' of https://github.com/jimtng/dscalarm-mqtt

CHANGELOG.md

@@ -2,16 +2,24 @@
 All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
+
+## [1.1.0]
 ### Added
-- MQTT Topic `panel-time` to get/set the alarm panel time
-- MQTT Topic `partition-N-access-code` the access code is published whenever the alarm was armed/disarmed
+- The alarm panel's time is published via MQTT Topic `homie/device-id/alarm/panel-time` and set through `homie/device-id/alarm/panel-time/set`
+- MQTT Topic `homie/device-id/partition-N/entry-delay` to indicate that the alarm is in the entry-delay state
+- MQTT Topic `homie/device-id/partition-N/access-code` the access code is published whenever the alarm was armed/disarmed
+- MQTT Topic `homie/device-id/partition-N/lights` the light status for the partition
 
 ### Changed
-- Updated library dependency to use Homie-esp8266 v3.0.1
+- Major change: each partition is now implemented as a individual node. 
+  MQTT topics `partition-N-xxx` moved from the `alarm` node to individual `partition-N` nodes. Hence the topics will change from `homie/device-id/alarm/partition-N-away` to `homie/device-id/partition-N/away` etc. Note the removal of `alarm` in the topic.
+- Only active partitions are announced. If partitions were added/removed from the alarm after boot up, perform a reboot via `maintenance/set`: `reboot`
+- Updated library dependency to use Homie-esp8266 v3.0.1 (Homie convention v3)
 - Updated library dependency to use dscKeybusInterface v1.3 (develop branch)
+- `openzone-N` topics changed from retained to not retained
 
 ### Fixed
-- Writing to `keypad` topic no longer causes an unexpected behaviour due to a bug in the dscKeybusInterface library.
+- Fixed a bug when writing to `keypad` topic
 
 ## [1.0.1] 2019-06-05
 ### Added

README.md

@@ -8,66 +8,88 @@ For a detailed wiring diagram, please see:
 https://github.com/taligentx/dscKeybusInterface
 
 
-## Features:
+## Features
 - MQTT Based
 - OTA Updateable (Thanks to Homie)
 - Configurable Wifi, MQTT, device id, and Alarm's access code. See the Setup Instructions below
-- Tested with OpenHAB, but it should work with other home automation systems
+- Tested with OpenHAB, but it should work with other home automation systems. Let me know if you're using it with other home automation systems so I can update this document.
 
+## Usage Examples
+- To arm partition 1 to away mode, publish to `homie/device-id/partition-1/away/set`: `1`
+- To disarm it, publish to `homie/device-id/partition-1/away/set`: `0`
+- To monitor motions on zone 1 (regardless of armed status), subscribe to `homie/device-id/alarm/openzone-1`
+- To know partition 1 alarm has been triggered, subscribe to `homie/device-id/partition-1/alarm`
+- When zone 3 triggered an alarm `homie/device-id/alarm/alarmzone-3` will be published with a value of `1`
+- To know whether partition 1 is armed, subscribe to `homie/device-id/partition-1/away` for away mode, or `homie/device-id/partition-1/stay` for stay mode
 
-## MQTT Topics:
+## Homie
+The Homie convention specifies the following syntax for MQTT topics:
+`homie/device-id/nodename/xxx`
 
-Base MQTT Topic (prepend this to all the topics below):
-```
-homie/device-id/alarm/
-```
+- The `device-id` can be set in Homie configuration - see **Initial Setup** below.
+
+## Homie Nodes
+- `alarm` for the main alarm functionalities
+- `partition-N` for partition related status/commands
+
+So for `alarm` node, the full MQTT topics will start with `homie/device-id/alarm/`, and for the `partition-N` the full MQTT topics will be `homie/device-id/partition-N/`
+
+## MQTT Topics:
 
 ### General MQTT topics:
-- `trouble`
-- `power-trouble`
-- `battery-trouble`
-- `fire-alarm-keypad` 
-- `aux-alarm-keypad`
-- `panic-alarm-keypad`
-- `panel-time` provides the date/time stored in the alarm system formatted as YYYY-MM-DD HH:mm
+- `homie/device-id/alarm/trouble` this corresponds to the "Trouble" light / status of the alarm
+- `homie/device-id/alarm/power-trouble`
+- `homie/device-id/alarm/battery-trouble`
+- `homie/device-id/alarm/fire-alarm-keypad` 
+- `homie/device-id/alarm/aux-alarm-keypad`
+- `homie/device-id/alarm/panic-alarm-keypad`
+- `homie/device-id/alarm/panel-time` provides the date/time stored in the alarm system formatted as YYYY-MM-DD HH:mm
 
 ### Partitions:
-- `partition-1-away`:  0 (disarmed) | 1 (armed away)
-- `partition-1-stay`:  0 (disarmed) | 1 (armed stay)
-- `partition-1-alarm`: 0 (no alarm) | 1 (triggered)
-- `partition-1-fire`:  0 (no alarm) | 1 (fire alarm)
-- `partition-1-access-code`: The access code used to arm/disarm
+Each partition is implemented as a homie node, so the base MQTT topic for partition 1 is `homie/device-id/partition-N/`
+- `homie/device-id/partition-1/away`:  0 (disarmed) | 1 (armed away)
+- `homie/device-id/partition-1/stay`:  0 (disarmed) | 1 (armed stay)
+- `homie/device-id/partition-1/alarm`: 0 (no alarm) | 1 (the alarm has been triggered)
+- `homie/device-id/partition-1/entry-delay`: 0 | 1 (the system is in entry-delay state)
+- `homie/device-id/partition-1/exit-delay`: 0 | 1 (the system is in exit-delay state)
+- `homie/device-id/partition-1/fire`:  0 (no alarm) | 1 (fire alarm)
+- `homie/device-id/partition-1/access-code`: The access code used to arm/disarm
+- `homie/device-id/partition-1/lights`: Status lights in JSON { "ready": "ON|OFF", "armed": "ON|OFF", "memory": "ON|OFF", "bypass": "ON|OFF", "trouble": "ON|OFF", "program": "ON|OFF", "fire": "ON|OFF", "backlight": "ON|OFF"}
 - ...
-- `partition-N-xxxx` as above
+- `homie/device-id/partition-N/xxxx` as above
 
 ### To arm/disarm a partition, publish to:
-- `partition-N-away/set`: 0 (disarm) | 1 (arm partition - away mode)
-- `partition-N-stay/set`: 0 (disarm) | 1 (arm partition - stay mode)
+- `homie/device-id/partition-N/away/set`: 1 | on | arm = arm partition N - away mode. 0 | off | disarm = disarm
+- `homie/device-id/partition-N/stay/set`: 1 | on | arm = arm partition N - stay mode. 0 | off | disarm = disarm
 
 ### Zones:
-- `openzone-1`: 0 (no movement) | 1 (movement detected)
+#### General Motion Detection
+These will be published whenever motion is detected within the zone, regardless of the armed state:
+- `homie/device-id/alarm/openzone-1`: 0 (no movement) | 1 (movement detected)
 - ...
-- `openzone-N`: as above
+- `homie/device-id/alarm/openzone-N`: as above
 
-- `alarmzone-1`: 0|1
+#### Triggered Alarm Zones
+These will be published when the alarm was triggered by zone motion detection during the armed state:
+- `homie/device-id/alarm/alarmzone-1`: 0|1
 - ...
-- `alarmzone-N`: as above
+- `homie/device-id/alarm/alarmzone-N`: as above
 
 ## Commands
 ### To request status refresh, publish to
-- `refresh-status/set`: 1
+- `homie/device-id/alarm/refresh-status/set`: 1
 
 ### To set the panel date/time, publish to
-- `panel-time/set`: "YYYY-MM-DD HH:mm"
+- `homie/device-id/alarm/panel-time/set`: "YYYY-MM-DD HH:mm"
 
 ### To reboot the device, publish to
-- `maintenance/set`: "reboot" to reboot
-- `maintenance/set`: "dsc-stop" to stop dsc keybus interrupts
-- `maintenance/set`: "dsc-start" to start dsc keybus interface
+- `homie/device-id/alarm/maintenance/set`: "reboot" to reboot
+- `homie/device-id/alarm/maintenance/set`: "dsc-stop" to stop dsc keybus interrupts
+- `homie/device-id/alarm/maintenance/set`: "dsc-start" to start dsc keybus interface
 
 The DSC Keybus interrupts seem to interfere with the OTA and Config update operation (when publishing to `homie/device-id/$implementation/config/set`), causing the ESP8266 to reset, and in the case of configuration update, to cause a corruption in the Homie configuration file and put Homie into the initial configuration mode.
 
-So before sending a config update, stop the DSC interrupts by publishing to `maintenance/set`: "dsc-stop". Once the config update has been made, restart the DSC interface using `maintenance/set`: "dsc-start" or sending a reboot request.
+So before sending a config update, stop the DSC interrupts by publishing to `homie/device-id/alarm/maintenance/set`: "dsc-stop". Once the config update has been made, restart the DSC interface using `homie/device-id/alarm/maintenance/set`: "dsc-start" or sending a reboot request.
 
 ## Initial Setup
 Homie needs to be configured before it can connect to your Wifi / MQTT server. 
@@ -102,9 +124,9 @@ curl -X PUT http://192.168.123.1/config --header "Content-Type: application/json
 ## Updating The Stored Alarm Access Code
 
 Before updating Homie config, the DSC interface needs to be deactivated / stopped, because it interferes with writing the configuration file. To do this, publish an MQTT message to
-`maintenance/set` `dsc-stop`
+`homie/device-id/alarm/maintenance/set` `dsc-stop`
 
-After setting the configuration, reactivate the DSC interface by publishing to `maintenance/set` `dsc-start`
+After setting the configuration, reactivate the DSC interface by publishing to `homie/device-id/alarm/maintenance/set` `dsc-start`
 
 To change/update your access code that's stored on the device once it's operational (i.e. connected to your MQTT server), publish to
 `homie/device-id/$implementation/config/set {"settings":{"access-code":"1234"}}`
@@ -121,4 +143,10 @@ Note
 
 ## Library Dependencies
 - [Homie-esp8266 v3.x](https://github.com/homieiot/homie-esp8266.git#develop-v3)
-- [dscKeybusReader v1.3](https://github.com/taligentx/dscKeybusInterface.git#develop)
+- [dscKeybusReader v1.3](https://github.com/taligentx/dscKeybusInterface.git#develop)
+
+## Tips When Working with the Alarm
+
+- My alarm would go off when I opened my panel enclosure. It uses zone 5 for this detection. In order to stop it from going off, bypass zone 5 using `*1` to enter bypass mode. The zone LEDs will light up for bypassed zones. To toggle the zone bypass, enter the 2 digit zone number, e.g. `05`. When zone 5 is lit up, it will be bypassed. Press `#` to return to ready state.
+
+- While working/testing the alarm, disconnect the internal / external speakers, and replace it with a 10K resistor. This will avoid disturbing the neighbours.