Updates

devicetypes/bspranger/xiaomi-door-window-sensor.src/xiaomi-door-window-sensor.groovy

@@ -1,5 +1,6 @@
 /**
  *  Xiaomi Door/Window Sensor
+ *  Version 1.0
  *
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
@@ -11,22 +12,15 @@
  *  on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
  *  for the specific language governing permissions and limitations under the License.
  *
- * Based on original DH by Eric Maycock 2015 and Rave from Lazcad
- *  change log:
- *    added DH Colours
- *  added 100% battery max
- *  fixed battery parsing problem
- *  added lastcheckin attribute and tile
- *  added extra tile to show when last opened
- *  colours to confirm to new smartthings standards
- *  added ability to force override current state to Open or Closed.
- *  added experimental health check as worked out by rolled54.Why
- *  Rinkelk - added date-attribute support for Webcore
- *  Rinkelk - Changed battery icon according to Mobile785
- *  bspranger - renamed to bspranger to remove confusion of a4refillpad
+ *  Original device handler code by a4refillpad, adapted for use with Aqara model by bspranger
+ *  Additional contributions to code by alecm, alixjg, bspranger, gn0st1c, foz333, jmagnuson, rinkek, ronvandegraaf, snalee, tmleafs, twonk, & veeceeoh 
+ * 
+ *  Known issues:
+ *  Xiaomi sensors do not seem to respond to refresh requests
+ *  Inconsistent rendering of user interface text/graphics between iOS and Android devices - This is due to SmartThings, not this device handler
+ *  Pairing Xiaomi sensors can be difficult as they were not designed to use with a SmartThings hub.
  *
  */
-
 metadata {
    definition (name: "Xiaomi Door/Window Sensor", namespace: "bspranger", author: "bspranger") {
    capability "Configuration"
@@ -90,34 +84,35 @@ metadata {
 	details(["contact","battery","resetClosed","resetOpen","spacer","lastcheckin", "spacer", "spacer", "batteryRuntime", "spacer"])
    }
    preferences {
-	section {
+		//Date & Time Config
 		input description: "", type: "paragraph", element: "paragraph", title: "DATE & CLOCK"    
 		input name: "dateformat", type: "enum", title: "Set Date Format\n US (MDY) - UK (DMY) - Other (YMD)", description: "Date Format", options:["US","UK","Other"]
-		input name: "clockformat", type: "bool", title: "Use 24 hour clock?", defaultValue: false
-		}
-	section {
+		input name: "clockformat", type: "bool", title: "Use 24 hour clock?"
+		//Battery Reset Config
             	input description: "If you have installed a new battery, the toggle below will reset the Changed Battery date to help remember when it was changed.", type: "paragraph", element: "paragraph", title: "CHANGED BATTERY DATE RESET"
-		input name: "battReset", type: "bool", title: "Battery Changed?", description: ""
-		}
-	section {
+		input name: "battReset", type: "bool", title: "Battery Changed?"
+		//Battery Voltage Offset
 	        input description: "Only change the settings below if you know what you're doing.", type: "paragraph", element: "paragraph", title: "ADVANCED SETTINGS"
 		input name: "voltsmax", title: "Max Volts\nA battery is at 100% at __ volts\nRange 2.8 to 3.4", type: "decimal", range: "2.8..3.4", defaultValue: 3, required: false
 		input name: "voltsmin", title: "Min Volts\nA battery is at 0% (needs replacing) at __ volts\nRange 2.0 to 2.7", type: "decimal", range: "2..2.7", defaultValue: 2.5, required: false
-		}
     } 
 }
 
+// Parse incoming device messages to generate events
 def parse(String description) {
     log.debug "${device.displayName}: Parsing '${description}'"
 
-    //  send event for heartbeat    
+	// Determine current time and date in the user-selected date format and clock style
     def now = formatDate()
     def nowDate = new Date(now).getTime()
+	// Any report - button press & Battery - results in a lastCheckin event and update to Last Checkin tile
+	// However, only a non-parseable report results in lastCheckin being displayed in events log
     sendEvent(name: "lastCheckin", value: now, displayed: false)
     sendEvent(name: "lastCheckinDate", value: nowDate, displayed: false) 
 
     Map map = [:]
 
+	// Send message data to appropriate parsing function based on the type of report
     if (description?.startsWith('on/off: ')) 
     {
         map = parseCustomMessage(description) 
@@ -166,6 +161,7 @@ private Map parseReadAttrMessage(String description) {
     return result
 }
 
+// Convert raw 4 digit integer voltage value into percentage based on minVolts/maxVolts range
 private Map getBatteryResult(rawValue) {
     def rawVolts = rawValue / 1000
 	 def minVolts
@@ -196,6 +192,7 @@ private Map getBatteryResult(rawValue) {
     return result
 }
 
+// Check catchall for battery voltage data to pass to getBatteryResult for conversion to percentage report
 private Map parseCatchAllMessage(String description) {
     Map resultMap = [:]
     def cluster = zigbee.parse(description)
@@ -225,9 +222,6 @@ private Map parseCatchAllMessage(String description) {
     return resultMap
 }
 
-
-
-
 private Map parseCustomMessage(String description) {
     def result
     if (description?.startsWith('on/off: ')) {
@@ -277,6 +271,7 @@ def installed() {
     checkIntervalEvent("installed");
 }
 
+// updated() will run twice every time user presses save in preference settings page
 def updated() {
     checkIntervalEvent("updated");
 	if(battReset){
@@ -295,6 +290,7 @@ def formatDate(batteryReset) {
     def correctedTimezone = ""
     def timeString = clockformat ? "HH:mm:ss" : "h:mm:ss aa"
 
+	// If user's hub timezone is not set, display error messages in log and events log, and set timezone to GMT to avoid errors
     if (!(location.timeZone)) {
         correctedTimezone = TimeZone.getTimeZone("GMT")
         log.error "${device.displayName}: Time Zone not set, so GMT was used. Please set up your location in the SmartThings mobile app."