Update for 0.3 release

README.md

@@ -1,18 +1,35 @@
-_**Note**: This is a development branch for testing: partitions 2-8, zones 33-64, virtual keypad partitions 1 & 2.  The library methods have changed to accommodate multiple partitions and the previous methods have been removed - see the examples sketches for usage.  The new methods should not change in the future and can be considered stable (in theory!)._
-
 # 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 and Apple HomeKit using MQTT, sending push notifications/email, and reading/decoding Keybus data.
+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:
 
 ![dscHomeKit](https://user-images.githubusercontent.com/12835671/39588413-5a99099a-4ec1-11e8-9a2e-e332fa2d6379.jpg)
 
 ## Features
-* Tested DSC panels: PC1555MX, PC5015, PC1616, PC1832, PC1864
-* Partitions: 1-8, zones: 1-64
-* Virtual keypad: supports sending keys to the panel for partitions 1 and 2
-* Data buffering: helps prevent missing Keybus data when the sketch is busy
-* Non-blocking code: allows sketches to run as quickly as possible without using `delay` or `delayMicroseconds`.
+* Status tracking of armed/alarm/fire states for partitions 1-8
+* Status tracking of zones 1-64
+* Virtual keypad: Enables writing keys to the panel for partitions 1 and 2
+* Data buffering: Helps prevent missing Keybus data when the sketch is busy
+* Non-blocking code: Allows sketches to run as quickly as possible without using `delay` or `delayMicroseconds`.
+* Tested DSC panels: PC1555MX, PC5015, PC1616, PC1832, PC1864.  All PowerSeries panels are supported, post an issue if you have a different panel (PC5020, etc) and have tested the interface to update this list.
+
+## Release notes
+* 0.3
+  - New: Status for partitions 2-8, zones 33-64
+  - New: Virtual keypad support for partition 2
+  - New: [Athom Homey](https://www.athom.com/en/) integration example sketch, contributed by [MagnusPer](https://github.com/MagnusPer)
+  - New: PCB layouts, contributed by [sjlouw](https://github.com/sj-louw)
+  - New: Configurable number of partitions and zones to customize memory usage: `dscPartitions` and `dscZones` in `dscKeybusInterface.h`
+  - New: KeybusReader decoding of commands `0xE6` and `0xEB` 
+  - Changed: Split examples by platform
+  - Changed: MQTT examples updated with username and password fields
+  - Changed: `processRedundantData` now true by default to prevent storing repetitive data, reduces memory usage.
+  - Note: This release changes the library methods to accomodate multiple partitions, existing sketches will need to be updated to match the new example sketches.
+* 0.2
+  - New: Status for zones 9-32
+  - New: HomeAssistant integration example sketch
+  - New: Panel data buffering, adds `dscBufferSize` to `dscKeybusInterface.h` to allow configuration of how many panel commands are buffered to customize memory usage (uses 18 bytes of memory per command buffered).
+* 0.1 - Initial release
 
 ## Usage
 Download the repo and extract to the Arduino library directory or [install through the Arduino IDE](https://www.arduino.cc/en/Guide/Libraries#toc4): `Sketch > Include Library > Add .ZIP Library`.  Alternatively, `git clone` the repo in the Arduino library directory to keep track of the latest changes - after the code has been tested across different panels, I'll flag the library to be added to the Arduino Library Manager for integrated updates.
@@ -24,23 +41,21 @@ Download the repo and extract to the Arduino library directory or [install throu
 
   See `src/dscKeybusPrintData.cpp` for all currently known Keybus protocol commands and messages.  Issues and pull requests with additions/corrections are welcome!
 
-* 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:
-  * Armed away/stay/disarmed
-  * Partition in alarm
-  * Zones
+* 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:
+  * Partitions armed away/stay/disarmed
+  * Partitions in alarm
+  * Partitions exit delay in progress
+  * Partitions entry delay in progress
+  * Partitions fire alarm
+  * Zones open/closed
   * Zones in alarm
-  * Exit delay in progress
-  * Entry delay in progress
-  * Fire
   * Keypad fire/auxiliary/panic alarm
   * Panel AC power
   * 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.
 
-  Note: homebridge-mqttthing seems to have a bug for the smokeSensor object, I've fixed the bug and forked the repo until upstream is patched:  [taligentx/homebridge-mqttthing](https://github.com/taligentx/homebridge-mqttthing)
-
 * 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.
 
 * 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.
@@ -103,7 +118,7 @@ Keys are sent to partition 1 by default and can be changed to a different partit
   Examples:
   * Switch to partition 2 and send keys: `/2` + `1234`
   * Switch back to partition 1: `/1`
-  * Set directly in sketch: `dsc.writePartition = 1`
+  * Set directly in sketch: `dsc.writePartition = 1;`
 
 ## DSC Configuration
 Panel options affecting this interface, configured by `*8 + installer code`:
@@ -112,8 +127,13 @@ Panel options affecting this interface, configured by `*8 + installer code`:
   This section also sets the delay in reporting AC power failure to 30 minutes by default and can be set to 000 for no delay.  
 
 ## Notes
-* Memory usage can be reduced by lowering the number of partitions and zones specified in `src/dscKeybusInterface.h`.  By default, Arduino monitors up to 4 partitions/32 zones and esp8266 monitors up to 8 partitions/64 zones.
-* Support for the esp32 and other platforms depends on adjusting the code to use their platform-specific timers.  In addition to hardware interrupts to capture the DSC clock, this library uses platform-specific timer interrupts to capture the DSC data line in a non-blocking way 250us after the clock changes (without using `delayMicroseconds()`).  This is necessary because the clock and data are asynchronous - I observed keypad data delayed up to 160us after the clock falls.
+* Memory usage can be adjusted based on the number of partitions, zones, and data buffer size specified in `src/dscKeybusInterface.h`.  Default settings:
+  * Arduino: up to 4 partitions, 32 zones, 10 buffered commands
+  * esp8266: up to 8 partitions, 64 zones, 50 buffered commands
+
+* PCB layouts are available in `extras/PCB Layouts` - thanks to [sjlouw](https://github.com/sj-louw) for contributing these designs!
+
+* Support for the esp32 and other platforms depends on adjusting the code to use their platform-specific timers.  In addition to hardware interrupts to capture the DSC clock, this library uses platform-specific timer interrupts to capture the DSC data line in a non-blocking way 250us after the clock changes (without using `delayMicroseconds()`).  This is necessary because the clock and data are asynchronous - I've observed keypad data delayed up to 160us after the clock falls.
 
 ## References
 [AVR Freaks - DSC Keybus Protocol](https://www.avrfreaks.net/forum/dsc-keybus-protocol): An excellent discussion on how data is sent on the Keybus.

examples/Arduino/KeybusReader/KeybusReader.ino

@@ -1,32 +1,28 @@
 /*
- *  DSC Keybus Reader (Arduino, esp8266)
+ *  DSC Keybus Reader (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
  *  to productive use.
  *
  *  Wiring:
- *      DSC Aux(-) --- Arduino/esp8266 ground
+ *      DSC Aux(-) --- Arduino ground
  *
- *                                         +--- dscClockPin (Arduino Uno: 2,3 / esp8266: D1,D2,D8)
+ *                                         +--- dscClockPin (Arduino Uno: 2,3)
  *      DSC Yellow --- 15k ohm resistor ---|
  *                                         +--- 10k ohm resistor --- Ground
  *
- *                                         +--- dscReadPin (Arduino Uno: 2-12 / esp8266: D1,D2,D8)
+ *                                         +--- dscReadPin (Arduino Uno: 2-12)
  *      DSC Green ---- 15k ohm resistor ---|
  *                                         +--- 10k ohm resistor --- Ground
  *
  *  Virtual keypad (optional):
  *      DSC Green ---- NPN collector --\
- *                                      |-- NPN base --- 1k ohm resistor --- dscWritePin (Arduino Uno: 2-12 / esp8266: D1,D2,D8)
+ *                                      |-- NPN base --- 1k ohm resistor --- dscWritePin (Arduino Uno: 2-12)
  *            Ground --- NPN emitter --/
  *
  *  Power (when disconnected from USB):
- *      DSC Aux(+) ---+--- Arduino Vin pin
- *                    |
- *                    +--- 5v voltage regulator --- esp8266 development board 5v pin (NodeMCU, Wemos)
- *                    |
- *                    +--- 3.3v voltage regulator --- esp8266 bare module VCC pin (ESP-12, etc)
+ *      DSC Aux(+) --- Arduino Vin pin
  *
  *  Virtual keypad uses an NPN transistor to pull the data line low - most small signal NPN transistors should
  *  be suitable, for example:
@@ -43,9 +39,9 @@
 
 // Configures the Keybus interface with the specified pins - dscWritePin is optional, leaving it out disables the
 // virtual keypad.
-#define dscClockPin 3  // Arduino Uno: 2,3  esp8266: D1, D2, D8 (GPIO 5, 4, 15)
-#define dscReadPin 4   // Arduino Uno: 2-12  esp8266: D1, D2, D8 (GPIO 5, 4, 15)
-#define dscWritePin 5  // Arduino Uno: 2-12  esp8266: D1, D2, D8 (GPIO 5, 4, 15)
+#define dscClockPin 3  // Arduino Uno hardware interrupt pin: 2,3
+#define dscReadPin 5   // Arduino Uno: 2-12
+#define dscWritePin 6  // Arduino Uno: 2-12
 dscKeybusInterface dsc(dscClockPin, dscReadPin, dscWritePin);