MSA-753: Sets mode to home when somebody is home, away when everyone is gone and home / night (optionally) depending on sunrise / sunset.

[DVCSMP-1338] commenting out unused variables

devicetypes/osotech/plantlink.src/plantlink.groovy

@@ -0,0 +1,163 @@
+/**
+ *  PlantLink
+ *
+ *  This device type takes sensor data and converts it into a json packet to send to myplantlink.com
+ *  where its values will be computed for soil and plant type to show user readable values of how your
+ *  specific plant is doing.
+ *
+ *
+ *  Copyright 2015 Oso Technologies
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ *  in compliance with the License. You may obtain a copy of the License at:
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
+ *  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.
+ *
+ */
+ 
+import groovy.json.JsonBuilder
+
+metadata {
+    definition (name: "PlantLink", namespace: "OsoTech", author: "Oso Technologies") {
+        capability "Sensor"
+
+        command "setStatusIcon"
+        command "setPlantFuelLevel"
+        command "setBatteryLevel"
+        command "setInstallSmartApp"
+
+        attribute "plantStatus","string"
+        attribute "plantFuelLevel","number"
+        attribute "linkBatteryLevel","string"
+        attribute "installSmartApp","string"
+
+        fingerprint profileId: "0104", inClusters: "0000,0001,0B04"
+    }
+
+    simulator {
+        status "battery": "read attr - raw: C0720100010A000021340A, dni: C072, endpoint: 01, cluster: 0001, size: 0A, attrId: 0000, encoding: 21, value: 0a34"
+        status "moisture": "read attr - raw: C072010B040A0001290000, dni: C072, endpoint: 01, cluster: 0B04, size: 0A, attrId: 0100, encoding: 29, value: 0000"
+    }
+
+    tiles {
+        standardTile("Title", "device.label") {
+            state("label", label:'PlantLink ${device.label}')
+        }
+
+        valueTile("plantMoistureTile", "device.plantFuelLevel", width: 1, height: 1) {
+            state("plantMoisture", label: '${currentValue}% Moisture')
+        }
+
+        valueTile("plantStatusTextTile", "device.plantStatus", decoration: "flat", width: 2, height: 2) {
+            state("plantStatusTextTile", label:'${currentValue}')
+        }
+
+        valueTile("battery", "device.linkBatteryLevel" ) {
+            state("battery", label:'${currentValue}% battery')
+        }
+        
+        valueTile("installSmartApp","device.installSmartApp", decoration: "flat", width: 3, height: 1) {
+        	state "needSmartApp", label:'Please install SmartApp "Required PlantLink Connector"', defaultState:true
+            state "connectedToSmartApp", label:'Connected to myplantlink.com'
+        }
+
+        main "plantStatusTextTile"
+        details(['plantStatusTextTile', "plantMoistureTile", "battery", "installSmartApp"])
+    }
+}
+
+def setStatusIcon(value){
+    def status = ''
+    switch (value) {
+    	case '0':
+	        status = 'Needs Water'
+            break
+    	case '1':
+        	status = 'Dry'
+            break
+    	case '2':
+   		case '3':
+        	status = 'Good'
+            break
+        case '4':
+        	status = 'Too Wet'
+            break
+    	case 'No Soil':
+        	status = 'Too Dry'
+        	setPlantFuelLevel(0)
+            break
+    	case 'Recently Watered':
+        	status = 'Watered'
+            setPlantFuelLevel(100)
+    		break
+    	case 'Low Battery':
+        	status = 'Low Battery'
+    		break
+    	case 'Waiting on First Measurement':
+	        status = 'Calibrating'
+            break
+    	default:
+        	status = "?"
+            break
+    }
+    sendEvent("name":"plantStatus", "value":status, "description":statusText, displayed: true, isStateChange: true)
+}
+
+def setPlantFuelLevel(value){
+    sendEvent("name":"plantFuelLevel", "value":value, "description":statusText, displayed: true, isStateChange: true)	
+}
+
+def setBatteryLevel(value){
+    sendEvent("name":"linkBatteryLevel", "value":value, "description":statusText, displayed: true, isStateChange: true)
+}
+
+def setInstallSmartApp(value){
+	sendEvent("name":"installSmartApp", "value":value)
+}
+
+def parse(String description) {
+
+	def description_map = parseDescriptionAsMap(description)
+    def event_name = ""
+    def measurement_map = [
+            type: "link",
+            signal: "0x00",
+            zigbeedeviceid: device.zigbeeId,
+            created: new Date().time /1000 as int
+    ]
+    if (description_map.cluster == "0000"){
+    	/* version number, not used */
+        
+    } else if (description_map.cluster == "0001"){
+        /* battery voltage in mV (device needs minimium 2.1v to run) */
+        log.debug "PlantLink - id ${device.zigbeeId} battery ${description_map.value}"
+        event_name = "battery_status"
+        measurement_map["battery"] = "0x${description_map.value}"
+        
+    } else if (description_map.cluster == "0B04"){
+        /* raw moisture reading (needs to be sent to plantlink for soil/plant type conversion) */
+        log.debug "PlantLink - id ${device.zigbeeId}  raw moisture ${description_map.value}"
+        measurement_map["moisture"] = "0x${description_map.value}"
+        event_name = "moisture_status"
+        
+    } else{
+        log.debug "PlantLink - id ${device.zigbeeId} Unknown '${description}'"
+        return
+    }
+    
+    def json_builder = new JsonBuilder(measurement_map)
+    def result = createEvent(name: event_name, value: json_builder.toString())
+    return result
+}
+
+
+def parseDescriptionAsMap(description) {
+    (description - "read attr - ").split(",").inject([:]) { map, param ->
+        def nameAndValue = param.split(":")
+        map += [(nameAndValue[0].trim()):nameAndValue[1].trim()]
+    }
+}

devicetypes/smartthings/ecobee-thermostat.src/ecobee-thermostat.groovy

@@ -99,7 +99,7 @@ metadata {
 	}
 
 	preferences {
-		input "holdType", "enum", title: "Hold Type", description: "When changing temperature, use Temporary or Permanent hold (default)", required: false, options:["Temporary", "Permanent"]
+		input "holdType", "enum", title: "Hold Type", description: "When changing temperature, use Temporary (Until next transition) or Permanent hold (default)", required: false, options:["Temporary", "Permanent"]
 	}
 
 }

devicetypes/smartthings/smartsense-multi-sensor.src/smartsense-multi-sensor.groovy

@@ -384,20 +384,8 @@ def getTemperature(value) {
 
         "zcl mfg-code ${manufacturerCode}", "delay 200",
         "zcl global read 0xFC02 0x0010",
-        "send 0x${device.deviceNetworkId} 1 1","delay 400",
-        
-        "zcl mfg-code ${manufacturerCode}", "delay 200",
-        "zcl global read 0xFC02 0x0012",
-        "send 0x${device.deviceNetworkId} 1 1","delay 400",
-        
-        "zcl mfg-code ${manufacturerCode}", "delay 200",
-        "zcl global read 0xFC02 0x0013",
-        "send 0x${device.deviceNetworkId} 1 1","delay 400",
-        
-        "zcl mfg-code ${manufacturerCode}", "delay 200",
-        "zcl global read 0xFC02 0x0014",
-        "send 0x${device.deviceNetworkId} 1 1", "delay 400"
-		]
+        "send 0x${device.deviceNetworkId} 1 1","delay 400"
+	]
 
 		return refreshCmds + enrollResponse()
 	}

devicetypes/smartthings/zigbee-lock.src/zigbee-lock.groovy

@@ -136,15 +136,15 @@ def parse(String description) {
 
 // Lock capability commands
 def lock() {
-    def cmds = zigbee.zigbeeCommand("${CLUSTER_DOORLOCK}", "${DOORLOCK_CMD_LOCK_DOOR}", "{}")
-    log.info "lock() -- cmds: $cmds"
+    //def cmds = zigbee.zigbeeCommand("${CLUSTER_DOORLOCK}", "${DOORLOCK_CMD_LOCK_DOOR}", "{}")
+    //log.info "lock() -- cmds: $cmds"
     //return cmds
     "st cmd 0x${device.deviceNetworkId} 0x${device.endpointId} ${CLUSTER_DOORLOCK} ${DOORLOCK_CMD_LOCK_DOOR} {}"
 }
 
 def unlock() {
-    def cmds = zigbee.zigbeeCommand("${CLUSTER_DOORLOCK}", "${DOORLOCK_CMD_UNLOCK_DOOR}", "{}")
-    log.info "unlock() -- cmds: $cmds"
+    //def cmds = zigbee.zigbeeCommand("${CLUSTER_DOORLOCK}", "${DOORLOCK_CMD_UNLOCK_DOOR}", "{}")
+    //log.info "unlock() -- cmds: $cmds"
     //return cmds
     "st cmd 0x${device.deviceNetworkId} 0x${device.endpointId} ${CLUSTER_DOORLOCK} ${DOORLOCK_CMD_UNLOCK_DOOR} {}"
 }

smartapps/imbrianj/nobody-home.src/nobody-home.groovy

@@ -1,164 +1,427 @@
 /**
  *  Nobody Home
  *
- *  Author: brian@bevey.org
- *  Date: 12/19/14
+ *  Author: brian@bevey.org, raychi@gmail.com
+ *  Date: 12/02/2015
  *
- *  Monitors a set of presence detectors and triggers a mode change when everyone has left.
- *  When everyone has left, sets mode to a new defined mode.
- *  When at least one person returns home, set the mode back to a new defined mode.
- *  When someone is home - or upon entering the home, their mode may change dependent on sunrise / sunset.
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at:
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing,
+ *  software distributed under the License is distributed 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.
  */
 
-definition(
-  name: "Nobody Home",
-  namespace: "imbrianj",
-  author: "brian@bevey.org",
-  description: "When everyone leaves, change mode.  If at least one person home, switch mode based on sun position.",
-  category: "Mode Magic",
-  iconUrl: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
-  iconX2Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience%402x.png"
+/**
+ *  Monitors a set of presence sensors and trigger appropriate mode
+ *  based on configured modes and sunrise/sunset time.
+ *
+ *  - When everyone is away [Away]
+ *  - When someone is home during the day [Home]
+ *  - When someone is home at the night [Night]
+ */
+
+// ********** App related functions **********
+
+// The definition provides metadata about the App to SmartThings.
+definition (
+    name:        "Nobody Home",
+    namespace:   "imbrianj",
+    author:      "brian@bevey.org",
+    description: "Automatically set Away/Home/Night mode based on a set of presence sensors and sunrise/sunset time.",
+    category:    "Mode Magic",
+    iconUrl:     "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
+    iconX2Url:   "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png",
+    iconX3Url:   "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png"
 )
 
+// The preferences defines information the App needs from the user.
 preferences {
-  section("When all of these people leave home") {
-    input "people", "capability.presenceSensor", multiple: true
-  }
-
-  section("Change to this mode to...") {
-    input "newAwayMode",    "mode", title: "Everyone is away"
-    input "newSunsetMode",  "mode", title: "At least one person home and nightfall"
-    input "newSunriseMode", "mode", title: "At least one person home and sunrise"
-  }
-
-  section("Away threshold (defaults to 10 min)") {
-    input "awayThreshold", "decimal", title: "Number of minutes", required: false
-  }
-
-  section("Notifications") {
-    input "sendPushMessage", "enum", title: "Send a push notification?", metadata:[values:["Yes","No"]], required:false
-  }
-}
-
-def installed() {
-  init()
-}
-
-def updated() {
-  unsubscribe()
-  init()
-}
-
-def init() {
-  subscribe(people,   "presence", presence)
-  subscribe(location, "sunrise",  setSunrise)
-  subscribe(location, "sunset",   setSunset)
-
-  state.sunMode = location.mode
-}
-
-def setSunrise(evt) {
-  changeSunMode(newSunriseMode)
-}
-
-def setSunset(evt) {
-  changeSunMode(newSunsetMode)
-}
-
-def changeSunMode(newMode) {
-  state.sunMode = newMode
-
-  if(everyoneIsAway() && (location.mode == newAwayMode)) {
-    log.debug("Mode is away, not evaluating")
-  }
-
-  else if(location.mode != newMode) {
-    def message = "${app.label} changed your mode to '${newMode}'"
-    send(message)
-    setLocationMode(newMode)
-  }
-
-  else {
-    log.debug("Mode is the same, not evaluating")
-  }
-}
-
-def presence(evt) {
-  if(evt.value == "not present") {
-    log.debug("Checking if everyone is away")
-
-    if(everyoneIsAway()) {
-      log.info("Starting ${newAwayMode} sequence")
-      def delay = (awayThreshold != null && awayThreshold != "") ? awayThreshold * 60 : 10 * 60
-      runIn(delay, "setAway")
-    }
-  }
-
-  else {
-    if(location.mode != state.sunMode) {
-      log.debug("Checking if anyone is home")
-
-      if(anyoneIsHome()) {
-        log.info("Starting ${state.sunMode} sequence")
-
-        changeSunMode(state.sunMode)
-      }
+    section("Presence sensors to monitor") {
+        input "people", "capability.presenceSensor", multiple: true
     }
 
-    else {
-      log.debug("Mode is the same, not evaluating")
-    }
-  }
-}
-
-def setAway() {
-  if(everyoneIsAway()) {
-    if(location.mode != newAwayMode) {
-      def message = "${app.label} changed your mode to '${newAwayMode}' because everyone left home"
-      log.info(message)
-      send(message)
-      setLocationMode(newAwayMode)
+    section("Mode setting") {
+        input "newAwayMode",    "mode", title: "Everyone is away"
+        input "newSunriseMode", "mode", title: "Someone is home during the day"
+        input "newSunsetMode",  "mode", title: "Someone is home at night"
     }
 
-    else {
-      log.debug("Mode is the same, not evaluating")
+    section("Mode change delay (minutes)") {
+        input "awayThreshold", "decimal", title: "Away delay [5m]", required: false
+        input "arrivalThreshold", "decimal", title: "Arrival delay [2m]", required: false
     }
-  }
 
-  else {
-    log.info("Somebody returned home before we set to '${newAwayMode}'")
-  }
+    section("Notifications") {
+        input "sendPushMessage", "bool", title: "Push notification", required:false
+    }
 }
 
-private everyoneIsAway() {
-  def result = true
-
-  if(people.findAll { it?.currentPresence == "present" }) {
-    result = false
-  }
-
-  log.debug("everyoneIsAway: ${result}")
-
-  return result
+// called when the user installs the App
+def installed()
+{
+    log.debug("installed() @${location.name}: ${settings}")
+    initialize(true)
 }
 
-private anyoneIsHome() {
-  def result = false
-
-  if(people.findAll { it?.currentPresence == "present" }) {
-    result = true
-  }
-
-  log.debug("anyoneIsHome: ${result}")
-
-  return result
+// called when the user installs the app, or changes the App
+// preference
+def updated()
+{
+    log.debug("updated() @${location.name}: ${settings}")
+    unsubscribe()
+    initialize(false)
 }
 
-private send(msg) {
-  if(sendPushMessage != "No") {
-    log.debug("Sending push message")
-    sendPush(msg)
-  }
+def initialize(isInstall)
+{
+    // subscribe to all the events we care about
+    log.debug("Subscribing to events ...")
 
-  log.debug(msg)
+    // thing to subscribe, attribute/state we care about, and callback fn
+    subscribe(people,   "presence", presenceHandler)
+    subscribe(location, "sunrise",  sunriseHandler)
+    subscribe(location, "sunset",   sunsetHandler)
+
+    // set the optional parameter values. these are not available
+    // directly until the app has initialized (that is,
+    // installed/updated has returned). so here we access them through
+    // the settings object, as otherwise will get an exception.
+
+    // store information we need in state object so we can get access
+    // to it later in our event handlers.
+
+    // calculate the away threshold in seconds. can't use the simpler
+    // default falsy value, as value of 0 (no delay) is evaluated to
+    // false (not specified), but we want 0 to represent no delay. so
+    // we compare against null explicitly to see if the user has set a
+    // value or not.
+    if (settings.awayThreshold == null) {
+        settings.awayThreshold = 5  // default away 5 minute
+    }
+    state.awayDelay = (int) settings.awayThreshold * 60
+    log.debug("awayThreshold set to " + state.awayDelay + " second(s)")
+
+    if (settings.arrivalThreshold == null) {
+        settings.arrivalThreshold = 2  // default arrival 2 minute
+    }
+    state.arrivalDelay = (int) settings.arrivalThreshold * 60
+    log.debug("arrivalThreshold set to " + state.arrivalDelay + " second(s)")
+
+    // get push notification setting
+    state.isPush = settings.sendPushMessage ? true : false
+    log.debug("sendPushMessage set to " + state.isPush)
+
+    // on install (not update), figure out what mode we should be in
+    // IF someone's home. This value is needed so that when a presence
+    // sensor is triggered, we know what mode to set the system to, as
+    // the sunrise/sunset event handler may not be triggered yet after
+    // a fresh install.
+    if (isInstall) {
+        // TODO: for now, we simply assume daytime. a better approach
+        //       would be to figure out whether current time is day or
+        //       night, and set it appropriately. However there
+        //       doesn't seem to be a way to query this directly
+        //       without a zip code. This will become the correct
+        //       value at the next sunrise/sunset event.
+        log.debug("No sun info yet, assuming daytime")
+        state.modeIfHome = newSunriseMode
+
+        // set keep a separate sun mode state so we can show a more
+        // helpful message when sun events are triggered.
+        state.currentSunMode = "sunUnknown"
+
+        state.eventDevice = ""  // last event device
+
+        // device that triggered timer. This is not necessarily the
+        // eventDevice. For example, if A arrives, kick off timer,
+        // then b arrives before timer elapsed, we want the
+        // notification message to reference A, not B.
+        state.timerDevice = null
+
+        // anything in flight? We use this to avoid scheduling
+        // duplicate timers (so we don't extend the timer).
+        state.pendingOp = "init"
+
+        // now set the correct mode for the location. This way, we
+        // don't need to wait for the next sun/presence event.
+
+        // we schedule this action to run after the app has fully
+        // initialized. This way, the app install is faster and the
+        // user customized app name is used in the notification.
+        runIn(7, "setInitialMode")
+    }
+    // On update, we don't change state.modeIfHome. This is so that we
+    // preserve the current sun rise/set state we obtained in earlier
+    // sunset/sunrise handler. This way the app remains in the correct
+    // sun state when the user reconfigures it.
 }
+
+def setInitialMode()
+{
+    changeSunMode(state.modeIfHome)
+    state.pendingOp = null
+}
+
+// ********** sunrise/sunset handling **********
+
+// event handler when the sunrise time is reached
+def sunriseHandler(evt)
+{
+    // we store the mode we should be in, IF someone's home
+    state.modeIfHome = newSunriseMode
+    state.currentSunMode = "sunRise"
+
+    // change mode if someone's home, otherwise set to away
+    changeSunMode(newSunriseMode)
+}
+
+// event handler when the sunset time is reached
+def sunsetHandler(evt)
+{
+    // we store the mode we should be in, IF someone's home
+    state.modeIfHome = newSunsetMode
+    state.currentSunMode = "sunSet"
+
+    // change mode if someone's home, otherwise set to away
+    changeSunMode(newSunsetMode)
+}
+
+def changeSunMode(newMode)
+{
+    // if everyone is away, we need to check and ensure the system is
+    // in away mode.
+    if (isEveryoneAway()) {
+        // this shouldn not happen normally as the mode should already
+        // be changed during presenceHandler, but in case this is not
+        // done, such as when app is initially installed while away,
+        // and system is not in away mode, then we toggle it to away
+        // at the sun rise/set event.
+        changeMode(newAwayMode, " because no one is present")
+    } else {
+        // someone is home, we update the mode depending on
+        // sunrise/sunset.
+        if (state.currentSunMode == "sunRise") {
+            changeMode(newMode, " because it's sunrise")
+        } else if (state.currentSunMode == "sunSet") {
+            changeMode(newMode, " because it's sunset")
+        } else {
+            changeMode(newMode)
+        }
+    }
+}
+
+// ********** presence handling **********
+
+// event handler when presence sensor changes state
+def presenceHandler(evt)
+{
+    // get the device name that resulted in the change
+    state.eventDevice= evt.device?.displayName
+
+    // is setInitialMode() still pending?
+    if (state.pendingOp == "init") {
+        log.debug("Pending ${state.pendingOp} op still in progress, ignoring presence event")
+        return
+    }
+
+    if (evt.value == "not present") {
+        handleDeparture()
+    } else {
+        handleArrival()
+    }
+}
+
+def handleDeparture()
+{
+    log.info("${state.eventDevice} left ${location.name}")
+
+    // do nothing if someone's still home
+    if (!isEveryoneAway()) {
+        log.info("Someone is still present, no actions needed")
+        return
+    }
+
+    // Now we set away mode. We perform the following actions even if
+    // home is already in away mode because an arrival timer may be
+    // pending, and scheduling delaySetMode() has the nice effect of
+    // canceling any previous pending timer, which is what we want to
+    // do. So we do this even if delay is 0.
+    log.info("Scheduling ${newAwayMode} mode in " + state.awayDelay + "s")
+    state.pendingOp = "away"
+    state.timerDevice = state.eventDevice
+    // we always use runIn(). This has the benefit of automatically
+    // replacing any pending arrival/away timer. if any arrival timer
+    // is active, it will be clobbered with this away timer. If any
+    // away timer is active, it will be extended with this new timeout
+    // (though normally it should not happen)
+    runIn(state.awayDelay, "delaySetMode")
+}
+
+def handleArrival()
+{
+    // someone returned home, set home/night mode after delay
+    log.info("${state.eventDevice} arrived at ${location.name}")
+
+    def numHome = isAnyoneHome()
+    if (!numHome) {
+        // no one home, do nothing for now (should NOT happen)
+        log.warn("${deviceName} arrived, but isAnyoneHome() returned false!")
+        return
+    }
+
+    if (numHome > 1) {
+        // not the first one home, do nothing, as any action that
+        // should happen would've happened when the first sensor
+        // arrived. this is the opposite of isEveryoneAway() where we
+        // don't do anything if someone's still home.
+        log.debug("Someone is already present, no actions needed")
+        return
+    }
+
+    // check if any pending arrival timer is already active. we want
+    // the timer to trigger when the 1st person arrives, but not
+    // extended when the 2nd person arrives later. this should not
+    // happen because of the >1 check above, but just in case.
+    if (state.pendingOp == "arrive") {
+        log.debug("Pending ${state.pendingOp} op already in progress, do nothing")
+        return
+    }
+
+    // now we set home/night mode
+    log.info("Scheduling ${state.modeIfHome} mode in " + state.arrivalDelay + "s")
+    state.pendingOp = "arrive"
+    state.timerDevice = state.eventDevice
+    // if any away timer is active, it will be clobbered with
+    // this arrival timer
+    runIn(state.arrivalDelay, "delaySetMode")
+}
+
+
+// ********** helper functions **********
+
+// change the system to the new mode, unless its already in that mode.
+def changeMode(newMode, reason="")
+{
+    if (location.mode != newMode) {
+        // notification message
+        def message = "${location.name} changed mode from '${location.mode}' to '${newMode}'" + reason
+        setLocationMode(newMode)
+        send(message)  // send message after changing mode
+    } else {
+        log.debug("${location.name} is already in ${newMode} mode, no actions needed")
+    }
+}
+
+// create a useful departure/arrival reason string
+def reasonStr(isAway, delaySec, delayMin)
+{
+    def reason
+
+    // if we are invoked by timer, use the stored timer trigger
+    // device, otherwise use the last event device
+    if (state.timerDevice) {
+        reason = " because ${state.timerDevice} "
+    } else {
+        reason = " because ${state.eventDevice} "
+    }
+
+    if (isAway) {
+        reason += "left"
+    } else {
+        reason += "arrived"
+    }
+
+    if (delaySec) {
+        if (delaySec > 60) {
+            if (delayMin == null) {
+                delayMin = (int) delaySec / 60
+            }
+            reason += " ${delayMin} minutes ago"
+        } else {
+            reason += " ${delaySec}s ago"
+        }
+    }
+
+    return reason
+}
+
+// http://docs.smartthings.com/en/latest/smartapp-developers-guide/scheduling.html#schedule-from-now
+//
+// By default, if a method is scheduled to run in the future, and then
+// another call to runIn with the same method is made, the last one
+// overwrites the previously scheduled method.
+//
+// We use the above property to schedule our arrval/departure delay
+// using the same function so we don't have to worry about
+// arrival/departure timer firing independently and complicating code.
+def delaySetMode()
+{
+    def newMode = null
+    def reason = ""
+
+    // timer has elapsed, check presence status to figure out what we
+    // need to do
+    if (isEveryoneAway()) {
+        reason = reasonStr(true, state.awayDelay, awayThreshold)
+        newMode = newAwayMode
+        if (state.pendingOp) {
+            log.debug("${state.pendingOp} timer elapsed: everyone is away")
+        }
+    } else {
+        reason = reasonStr(false, state.arrivalDelay, arrivalThreshold)
+        newMode = state.modeIfHome
+        if (state.pendingOp) {
+            log.debug("${state.pendingOp} timer elapsed: someone is home")
+        }
+    }
+
+    // now change the mode
+    changeMode(newMode, reason);
+
+    state.pendingOp = null
+    state.timerDevice = null
+}
+
+private isEveryoneAway()
+{
+    def result = true
+
+    if (people.findAll { it?.currentPresence == "present" }) {
+        result = false
+    }
+    // log.debug("isEveryoneAway: ${result}")
+
+    return result
+}
+
+// return the number of people that are home
+private isAnyoneHome()
+{
+    def result = 0
+    // iterate over our people variable that we defined
+    // in the preferences method
+    for (person in people) {
+        if (person.currentPresence == "present") {
+            result++
+        }
+    }
+    return result
+}
+
+private send(msg)
+{
+    if (state.isPush) {
+        log.debug("Sending push notification")
+        sendPush(msg)
+    } else {
+        log.debug("Sending notification")
+        sendNotificationEvent(msg)
+    }
+    log.info(msg)
+}

smartapps/initialstate-events/initial-state-event-streamer.src/initial-state-event-streamer.groovy

@@ -11,9 +11,9 @@
  *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
  *  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.
- *  
+ *
  *  SmartThings data is sent from this SmartApp to Initial State. This is event data only for
- *  devices for which the user has authorized. Likewise, Initial State's services call this 
+ *  devices for which the user has authorized. Likewise, Initial State's services call this
  *  SmartApp on the user's behalf to configure Initial State specific parameters. The ToS and
  *  Privacy Policy for Initial State can be found here: https://www.initialstate.com/terms
  */
@@ -90,7 +90,7 @@ def subscribeToEvents() {
 	if (beacons != null) {
 		subscribe(beacons, "presence", genericHandler)
 	}
-	
+
 	if (cos != null) {
 		subscribe(cos, "carbonMonoxide", genericHandler)
 	}
@@ -218,7 +218,7 @@ def setAccessKey() {
 		atomicState.grokerSubdomain = "$newGrokerSubdomain"
 		atomicState.isBucketCreated = false
 	}
-    
+
 	if (newAccessKey && newAccessKey != atomicState.accessKey) {
 		atomicState.accessKey = "$newAccessKey"
 		atomicState.isBucketCreated = false
@@ -262,7 +262,7 @@ def uninstalled() {
 }
 
 def tryCreateBucket() {
-	
+
 	// can't ship events if there is no grokerSubdomain
 	if (atomicState.grokerSubdomain == null || atomicState.grokerSubdomain == "") {
 		log.error "streaming url is currently null"
@@ -330,57 +330,57 @@ def genericHandler(evt) {
 // This is a handler function for flushing the event buffer
 // after a specified amount of time to reduce the load on ST servers
 def flushBuffer() {
+	def eventBuffer = atomicState.eventBuffer
 	log.trace "About to flush the buffer on schedule"
-	if (atomicState.eventBuffer != null && atomicState.eventBuffer.size() > 0) {
-		tryShipEvents()
+	if (eventBuffer != null && eventBuffer.size() > 0) {
+		atomicState.eventBuffer = []
+		tryShipEvents(eventBuffer)
 	}
 }
 
 def eventHandler(name, value) {
-	log.debug atomicState.eventBuffer
-
-	def eventBuffer = atomicState.eventBuffer
 	def epoch = now() / 1000
-	
-	// if for some reason this code block is being run
-	// but the SmartApp wasn't propery setup during install
-	// we need to set initialize the eventBuffer.
-	if (!atomicState.eventBuffer) {
-		atomicState.eventBuffer = []
-	}
+	def eventBuffer = atomicState.eventBuffer ?: []
 	eventBuffer << [key: "$name", value: "$value", epoch: "$epoch"]
-	
-	log.debug eventBuffer
-
-	atomicState.eventBuffer = eventBuffer
 
 	if (eventBuffer.size() >= 10) {
-		tryShipEvents()
+		// Clear eventBuffer right away since we've already pulled it off of atomicState to reduce the risk of missing
+		// events.  This assumes the grokerSubdomain, accessKey, and bucketKey are set correctly to avoid the eventBuffer
+		// from growing unbounded.
+		atomicState.eventBuffer = []
+		tryShipEvents(eventBuffer)
+	} else {
+		// Make sure we persist the updated eventBuffer with the new event added back to atomicState
+		atomicState.eventBuffer = eventBuffer
 	}
+	log.debug "Event added to buffer: " + eventBuffer
 }
 
 // a helper function for shipping the atomicState.eventBuffer to Initial State
-def tryShipEvents() {
+def tryShipEvents(eventBuffer) {
 
+	def grokerSubdomain = atomicState.grokerSubdomain
 	// can't ship events if there is no grokerSubdomain
-	if (atomicState.grokerSubdomain == null || atomicState.grokerSubdomain == "") {
+	if (grokerSubdomain == null || grokerSubdomain == "") {
 		log.error "streaming url is currently null"
 		return
 	}
+	def accessKey = atomicState.accessKey
+	def bucketKey = atomicState.bucketKey
 	// can't ship if access key and bucket key are null, so finish trying
-	if (atomicState.accessKey == null || atomicState.bucketKey == null) {
+	if (accessKey == null || bucketKey == null) {
 		return
 	}
 
 	def eventPost = [
-		uri: "https://${atomicState.grokerSubdomain}.initialstate.com/api/events",
+		uri: "https://${grokerSubdomain}.initialstate.com/api/events",
 		headers: [
 			"Content-Type": "application/json",
-			"X-IS-BucketKey": "${atomicState.bucketKey}",
-			"X-IS-AccessKey": "${atomicState.accessKey}",
+			"X-IS-BucketKey": "${bucketKey}",
+			"X-IS-AccessKey": "${accessKey}",
 			"Accept-Version": "0.0.2"
 		],
-		body: atomicState.eventBuffer
+		body: eventBuffer
 	]
 
 	try {
@@ -389,13 +389,10 @@ def tryShipEvents() {
 			log.debug "shipped events and got ${resp.status}"
 			if (resp.status >= 400) {
 				log.error "shipping failed... ${resp.data}"
-			} else {
-				// clear the buffer
-				atomicState.eventBuffer = []
 			}
 		}
 	} catch (e) {
 		log.error "shipping events failed: $e"
 	}
-	
+
 }

smartapps/osotech/plantlink-connector.src/plantlink-connector.groovy

@@ -0,0 +1,389 @@
+/**
+ *  Required PlantLink Connector
+ *  This SmartApp forwards the raw data of the deviceType to myplantlink.com
+ *  and returns it back to your device after calculating soil and plant type.
+ *
+ *  Copyright 2015 Oso Technologies
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ *  in compliance with the License. You may obtain a copy of the License at:
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
+ *  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.
+ *
+ */
+import groovy.json.JsonBuilder
+import java.util.regex.Matcher
+import java.util.regex.Pattern
+ 
+definition(
+    name: "PlantLink Connector",
+    namespace: "Osotech",
+    author: "Oso Technologies",
+    description: "This SmartApp connects to myplantlink.com and forwards the device data to it so it can calculate easy to read plant status for your specific plant's needs.",
+    category:  "Convenience",
+    iconUrl:   "https://dashboard.myplantlink.com/images/apple-touch-icon-76x76-precomposed.png",
+    iconX2Url: "https://dashboard.myplantlink.com/images/apple-touch-icon-120x120-precomposed.png",
+    iconX3Url: "https://dashboard.myplantlink.com/images/apple-touch-icon-152x152-precomposed.png"
+) {
+    appSetting "client_id"
+    appSetting "client_secret"
+    appSetting "https_plantLinkServer"
+}
+
+preferences {
+    page(name: "auth", title: "Step 1 of 2", nextPage:"deviceList", content:"authPage")
+    page(name: "deviceList", title: "Step 2 of 2", install:true, uninstall:false){
+        section {
+            input "plantlinksensors", "capability.sensor", title: "Select PlantLink sensors", multiple: true
+        }
+    }
+}
+
+mappings {
+    path("/swapToken") {
+        action: [
+                GET: "swapToken"
+        ]
+    }
+}
+
+def authPage(){
+    if(!atomicState.accessToken){
+        createAccessToken()
+        atomicState.accessToken = state.accessToken
+    }
+
+	def redirectUrl = oauthInitUrl()
+    def uninstallAllowed = false
+    def oauthTokenProvided = false
+    if(atomicState.authToken){
+        uninstallAllowed = true
+        oauthTokenProvided = true
+    }
+
+    if (!oauthTokenProvided) {
+        return dynamicPage(name: "auth", title: "Step 1 of 2", nextPage:null, uninstall:uninstallAllowed) {
+            section(){
+                href(name:"login",
+                     url:redirectUrl, 
+                     style:"embedded",
+                     title:"PlantLink", 
+                     image:"https://dashboard.myplantlink.com/images/PLlogo.png", 
+                     description:"Tap to login to myplantlink.com")
+            }
+        }
+    }else{
+        return dynamicPage(name: "auth", title: "Step 1 of 2 - Completed", nextPage:"deviceList", uninstall:uninstallAllowed) {
+	        section(){
+               paragraph "You are logged in to myplantlink.com, tap next to continue", image: iconUrl
+ 			   href(url:redirectUrl, title:"Or", description:"tap to switch accounts")
+            }
+        }
+    }
+}
+
+def installed() {
+    log.debug "Installed with settings: ${settings}"
+    initialize()
+}
+
+def updated() {
+    log.debug "Updated with settings: ${settings}"
+    unsubscribe()
+    initialize()
+}
+
+def uninstalled() {
+    if (plantlinksensors){
+        plantlinksensors.each{ sensor_device ->
+            sensor_device.setInstallSmartApp("needSmartApp")
+        }
+    }
+}
+
+def initialize() {
+    atomicState.attached_sensors = [:]
+    if (plantlinksensors){
+        subscribe(plantlinksensors, "moisture_status", moistureHandler)
+        subscribe(plantlinksensors, "battery_status", batteryHandler)
+        plantlinksensors.each{ sensor_device ->
+            sensor_device.setStatusIcon("Waiting on First Measurement")
+            sensor_device.setInstallSmartApp("connectedToSmartApp")
+        }
+    }
+}
+
+def dock_sensor(device_serial, expected_plant_name) {
+    def docking_body_json_builder = new JsonBuilder([version: '1c', smartthings_device_id: device_serial])
+    def docking_params = [
+            uri        : appSettings.https_plantLinkServer,
+            path       : "/api/v1/smartthings/links",
+            headers    : ["Content-Type": "application/json", "Authorization": "Bearer ${atomicState.authToken}"],
+            contentType: "application/json",
+            body: docking_body_json_builder.toString()
+    ]
+    def plant_post_body_map = [
+            plant_type_key: 999999,
+            soil_type_key : 1000004
+    ]
+    def plant_post_params = [
+            uri        : appSettings.https_plantLinkServer,
+            path       : "/api/v1/plants",
+            headers    : ["Content-Type": "application/json", "Authorization": "Bearer ${atomicState.authToken}"],
+            contentType: "application/json",
+    ]
+    log.debug "Creating new plant on myplantlink.com - ${expected_plant_name}"
+    httpPost(docking_params) { docking_response ->
+        if (parse_api_response(docking_response, "Docking a link")) {
+            if (docking_response.data.plants.size() == 0) {
+                log.debug "creating plant for - ${expected_plant_name}"
+                plant_post_body_map["name"] = expected_plant_name
+                plant_post_body_map['links_key'] = [docking_response.data.key]
+                def plant_post_body_json_builder = new JsonBuilder(plant_post_body_map)
+                plant_post_params["body"] = plant_post_body_json_builder.toString()
+                httpPost(plant_post_params) { plant_post_response ->
+                    if(parse_api_response(plant_post_response, 'creating plant')){
+                        def attached_map = atomicState.attached_sensors
+                        attached_map[device_serial] = plant_post_response.data
+                        atomicState.attached_sensors = attached_map
+                    }
+                }
+            } else {
+                def plant = docking_response.data.plants[0]
+                def attached_map = atomicState.attached_sensors
+                attached_map[device_serial] = plant
+                atomicState.attached_sensors = attached_map
+                checkAndUpdatePlantIfNeeded(plant, expected_plant_name)
+            }
+        }
+    }
+    return true
+}
+
+def checkAndUpdatePlantIfNeeded(plant, expected_plant_name){
+    def plant_put_params = [
+		uri : appSettings.https_plantLinkServer,
+        headers : ["Content-Type": "application/json", "Authorization": "Bearer ${atomicState.authToken}"],
+        contentType : "application/json"
+    ]
+    if (plant.name != expected_plant_name) {
+        log.debug "updating plant for - ${expected_plant_name}"
+        plant_put_params["path"] = "/api/v1/plants/${plant.key}"
+        def plant_put_body_map = [
+			name: expected_plant_name
+        ]
+        def plant_put_body_json_builder = new JsonBuilder(plant_put_body_map)
+        plant_put_params["body"] = plant_put_body_json_builder.toString()
+        httpPut(plant_put_params) { plant_put_response ->
+            parse_api_response(plant_put_response, 'updating plant name')
+        }
+    }
+}
+
+def moistureHandler(event){
+    def expected_plant_name = "SmartThings - ${event.displayName}"
+    def device_serial = getDeviceSerialFromEvent(event)
+    
+    if (!atomicState.attached_sensors.containsKey(device_serial)){
+        dock_sensor(device_serial, expected_plant_name)
+    }else{
+        def measurement_post_params = [
+                uri: appSettings.https_plantLinkServer,
+                path: "/api/v1/smartthings/links/${device_serial}/measurements",
+                headers: ["Content-Type": "application/json", "Authorization": "Bearer ${atomicState.authToken}"],
+                contentType: "application/json",
+                body: event.value
+        ]
+        httpPost(measurement_post_params) { measurement_post_response ->
+            if (parse_api_response(measurement_post_response, 'creating moisture measurement') &&
+                    measurement_post_response.data.size() >0){
+                def measurement = measurement_post_response.data[0]
+                def plant =  measurement.plant
+                log.debug plant
+                checkAndUpdatePlantIfNeeded(plant, expected_plant_name)
+                plantlinksensors.each{ sensor_device ->
+                    if (sensor_device.id == event.deviceId){
+                        sensor_device.setStatusIcon(plant.status)
+                        if (plant.last_measurements && plant.last_measurements[0].moisture){
+                            sensor_device.setPlantFuelLevel(plant.last_measurements[0].moisture * 100 as int)
+                        }
+                        if (plant.last_measurements && plant.last_measurements[0].battery){
+                            sensor_device.setBatteryLevel(plant.last_measurements[0].battery * 100 as int)
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+def batteryHandler(event){
+    def expected_plant_name = "SmartThings - ${event.displayName}"
+    def device_serial = getDeviceSerialFromEvent(event)
+    
+    if (!atomicState.attached_sensors.containsKey(device_serial)){
+        dock_sensor(device_serial, expected_plant_name)
+    }else{
+        def measurement_post_params = [
+                uri: appSettings.https_plantLinkServer,
+                path: "/api/v1/smartthings/links/${device_serial}/measurements",
+                headers: ["Content-Type": "application/json", "Authorization": "Bearer ${atomicState.authToken}"],
+                contentType: "application/json",
+                body: event.value
+        ]
+        httpPost(measurement_post_params) { measurement_post_response ->
+            parse_api_response(measurement_post_response, 'creating battery measurement')
+        }
+    }
+}
+
+def getDeviceSerialFromEvent(event){
+    def pattern = /.*"zigbeedeviceid"\s*:\s*"(\w+)".*/
+    def match_result = (event.value =~ pattern)
+    return match_result[0][1]
+}
+
+def oauthInitUrl(){
+	atomicState.oauthInitState = UUID.randomUUID().toString()
+    def oauthParams = [
+            response_type: "code",
+            client_id: appSettings.client_id,
+            state: atomicState.oauthInitState,
+            redirect_uri: buildRedirectUrl()
+    ]
+    return appSettings.https_plantLinkServer + "/oauth/oauth2/authorize?" + toQueryString(oauthParams)
+}
+
+def buildRedirectUrl(){
+    return getServerUrl() + "/api/token/${atomicState.accessToken}/smartapps/installations/${app.id}/swapToken"
+}
+
+def swapToken(){
+    def code = params.code
+    def oauthState = params.state
+    def stcid = appSettings.client_id
+    def postParams = [
+            method: 'POST',
+            uri: "https://oso-tech.appspot.com",
+            path: "/api/v1/oauth-token",
+            query: [grant_type:'authorization_code', code:params.code, client_id:stcid,
+                    client_secret:appSettings.client_secret, redirect_uri: buildRedirectUrl()],
+    ]
+
+    def jsonMap
+    httpPost(postParams) { resp ->
+        jsonMap = resp.data
+    }
+
+    atomicState.refreshToken = jsonMap.refresh_token
+    atomicState.authToken = jsonMap.access_token
+
+    def html = """
+<html>
+<head>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+	.container {
+		padding:25px;
+	}
+	.flex1 {
+    	width:33%;
+		float:left;
+		text-align: center;
+	}
+	p {
+		font-size: 2em;
+		font-family: Verdana, Geneva, sans-serif;
+		text-align: center;
+		color: #777;
+	}
+</style>
+</head>
+<body>
+	<div class="container">
+		<div class="flex1"><img src="https://dashboard.myplantlink.com/images/PLlogo.png" alt="PlantLink" height="75"/></div>
+		<div class="flex1"><img src="https://s3.amazonaws.com/smartapp-icons/Partner/support/connected-device-icn%402x.png" alt="connected to"  height="25" style="padding-top:25px;" /></div>
+		<div class="flex1"><img src="https://s3.amazonaws.com/smartapp-icons/Partner/support/st-logo%402x.png" alt="SmartThings" height="75"/></div>
+		<br clear="all">
+  </div>
+  <div class="container">
+		<p>Your PlantLink Account is now connected to SmartThings!</p>
+		<p style="color:green;">Click <strong>Done</strong> at the top right to finish setup.</p>
+	</div>
+</body>
+</html>
+"""
+    render contentType: 'text/html', data: html
+}
+
+private refreshAuthToken() {
+    def stcid = appSettings.client_id
+    def refreshParams = [
+            method: 'POST',
+            uri: "https://hardware-dot-oso-tech.appspot.com",
+            path: "/api/v1/oauth-token",
+            query: [grant_type:'refresh_token', code:"${atomicState.refreshToken}", client_id:stcid,
+                    client_secret:appSettings.client_secret],
+    ]
+    try{
+        def jsonMap
+        httpPost(refreshParams) { resp ->
+            if(resp.status == 200){
+                log.debug "OAuth Token refreshed"
+                jsonMap = resp.data
+                if (resp.data) {
+                    atomicState.refreshToken = resp?.data?.refresh_token
+                    atomicState.authToken = resp?.data?.access_token
+                    if (data?.action && data?.action != "") {
+                        log.debug data.action
+                        "{data.action}"()
+                        data.action = ""
+                    }
+                }
+                data.action = ""
+            }else{
+                log.debug "refresh failed ${resp.status} : ${resp.status.code}"
+            }
+        }
+    }
+    catch(Exception e){
+        log.debug "caught exception refreshing auth token: " + e
+    }
+}
+
+def parse_api_response(resp, message) {
+    if (resp.status == 200) {
+        return true
+    } else {
+        log.error "sent ${message} Json & got http status ${resp.status} - ${resp.status.code}"
+        if (resp.status == 401) {
+            refreshAuthToken()
+            return false
+        } else {
+            debugEvent("Authentication error, invalid authentication method, lack of credentials, etc.", true)
+            return false
+        }
+    }
+}
+
+def getServerUrl() { 
+	return "https://graph.api.smartthings.com" 
+}
+
+def debugEvent(message, displayEvent) {
+    def results = [
+            name: "appdebug",
+            descriptionText: message,
+            displayed: displayEvent
+    ]
+    log.debug "Generating AppDebug Event: ${results}"
+    sendEvent (results)
+}
+
+def toQueryString(Map m){
+    return m.collect { k, v -> "${k}=${URLEncoder.encode(v.toString())}" }.sort().join("&")
+}

smartapps/smartthings/ecobee-connect.src/ecobee-connect.groovy

@@ -1,4 +1,15 @@
 /**
+ *  Copyright 2015 SmartThings
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ *  in compliance with the License. You may obtain a copy of the License at:
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software distributed under the License is distributed
+ *  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.
+ *
  *	Ecobee Service Manager
  *
  *	Author: scott

smartapps/smartthings/examples/every-element.src/every-element.groovy

@@ -1,7 +1,7 @@
 /**
  *  Every Element
  *
- *  Copyright 2014 SmartThings
+ *  Copyright 2015 SmartThings
  *
  *  Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
  *  in compliance with the License. You may obtain a copy of the License at:
@@ -14,349 +14,555 @@
  *
  */
 definition(
-	name: "Every Element",
-	namespace: "smartthings/examples",
-	author: "SmartThings",
-	description: "Every element demonstration app",
-	category: "SmartThings Internal",
-	iconUrl: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
-	iconX2Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png"
+        name: "Every Element",
+        namespace: "smartthings/examples",
+        author: "SmartThings",
+        description: "Every element demonstration app",
+        category: "SmartThings Internal",
+        iconUrl: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png",
+        iconX2Url: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience@2x.png"
 )
 
 preferences {
-	page(name: "firstPage")
-	page(name: "inputPage")
-	page(name: "appPage")
-	page(name: "labelPage")
-	page(name: "modePage")
-	page(name: "paragraphPage")
-	page(name: "iconPage")
-	page(name: "hrefPage")
-	page(name: "buttonsPage")
-	page(name: "imagePage")
-	page(name: "videoPage")
-	page(name: "deadEnd", title: "Nothing to see here, move along.", content: "foo")
-	page(name: "flattenedPage")
+    // landing page
+    page(name: "firstPage")
+
+    // PageKit
+    page(name: "buttonsPage")
+    page(name: "imagePage")
+    page(name: "inputPage")
+    page(name: "inputBooleanPage")
+    page(name: "inputIconPage")
+    page(name: "inputImagePage")
+    page(name: "inputDevicePage")
+    page(name: "inputCapabilityPage")
+    page(name: "inputRoomPage")
+    page(name: "inputModePage")
+    page(name: "inputSelectionPage")
+    page(name: "inputHubPage")
+    page(name: "inputContactBookPage")
+    page(name: "inputTextPage")
+    page(name: "inputTimePage")
+    page(name: "appPage")
+    page(name: "hrefPage")
+    page(name: "paragraphPage")
+    page(name: "videoPage")
+    page(name: "labelPage")
+    page(name: "modePage")
+
+    // Every element helper pages
+    page(name: "deadEnd", title: "Nothing to see here, move along.", content: "foo")
+    page(name: "flattenedPage")
 }
 
 def firstPage() {
-	dynamicPage(name: "firstPage", title: "Where to first?", install: true, uninstall: true) {
-		section() {
-			href(page: "inputPage", title: "Element: 'input'")
-			href(page: "appPage", title: "Element: 'app'")
-			href(page: "labelPage", title: "Element: 'label'")
-			href(page: "modePage", title: "Element: 'mode'")
-			href(page: "paragraphPage", title: "Element: 'paragraph'")
-			href(page: "iconPage", title: "Element: 'icon'")
-			href(page: "hrefPage", title: "Element: 'href'")
-			href(page: "buttonsPage", title: "Element: 'buttons'")
-			href(page: "imagePage", title: "Element: 'image'")
-			href(page: "videoPage", title: "Element: 'video'")
-		}
-		section() {
-			href(page: "flattenedPage", title: "All of the above elements on a single page")
-		}
-	}
+    dynamicPage(name: "firstPage", title: "Where to first?", install: true, uninstall: true) {
+        section {
+            href(page: "appPage", title: "Element: 'app'")
+            href(page: "buttonsPage", title: "Element: 'buttons'")
+            href(page: "hrefPage", title: "Element: 'href'")
+            href(page: "imagePage", title: "Element: 'image'")
+            href(page: "inputPage", title: "Element: 'input'")
+            href(page: "labelPage", title: "Element: 'label'")
+            href(page: "modePage", title: "Element: 'mode'")
+            href(page: "paragraphPage", title: "Element: 'paragraph'")
+            href(page: "videoPage", title: "Element: 'video'")
+        }
+        section {
+            href(page: "flattenedPage", title: "All of the above elements on a single page")
+        }
+    }
 }
 
 def inputPage() {
-	dynamicPage(name: "inputPage", title: "Every 'input' type") {
-		section("enum") {
-			input(type: "enum", name: "enumRefresh", title: "submitOnChange:true", required: false, multiple: true, options: ["one", "two", "three"], submitOnChange: true)
-			if (enumRefresh) {
-				paragraph "${enumRefresh}"
-			}
-			input(type: "enum", name: "enumSegmented", title: "style:segmented", required: false, multiple: true, options: ["one", "two", "three"], style: "segmented")
-			input(type: "enum", name: "enum", title: "required:false, multiple:false", required: false, multiple: false, options: ["one", "two", "three"])
-			input(type: "enum", name: "enumRequired", title: "required:true", required: true, multiple: false, options: ["one", "two", "three"])
-			input(type: "enum", name: "enumMultiple", title: "multiple:true", required: false, multiple: true, options: ["one", "two", "three"])
-			input(type: "enum", name: "enumWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, options: ["one", "two", "three"], image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-			input(type: "enum", name: "enumWithGroupedOptions", title: "groupedOptions", description: "This enum has grouped options", required: false, multiple: true, groupedOptions: [
-				[
-					title : "the group title that is displayed",
-					order : 0, // the order of the group; 0-based
-					image : "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", // not yet supported
-					values: [
-						[
-							key  : "the value that will be placed in SmartApp settings.", // such as a device id
-							value: "the title of the selectable option that is displayed", // such as a device name
-							order: 0 // the order of the option
-						]
-					]
-				],
-				[
-					title : "the second group title that is displayed",
-					order : 1, // the order of the group; 0-based
-					image : null, // not yet supported
-					values: [
-						[
-							key  : "some_device_id",
-							value: "some_device_name",
-							order: 1 // the order of the option. This option will appear second in the list even though it is the first option defined in this map
-						],
-						[
-							key  : "some_other_device_id",
-							value: "some_other_device_name",
-							order: 0 // the order of the option. This option will appear first in the list even though it is not the first option defined in this map
-						]
-					]
-				]
-			])
-		}
-		section("text") {
-			input(type: "text", name: "text", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "text", name: "textRequired", title: "required:true", required: true, multiple: false)
-			input(type: "text", name: "textWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("number") {
-			input(type: "number", name: "number", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "number", name: "numberRequired", title: "required:true", required: true, multiple: false)
-			input(type: "number", name: "numberWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("boolean") {
-			input(type: "boolean", name: "boolean", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "boolean", name: "booleanWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("password") {
-			input(type: "password", name: "password", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "password", name: "passwordRequired", title: "required:true", required: true, multiple: false)
-			input(type: "password", name: "passwordWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("phone") {
-			input(type: "phone", name: "phone", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "phone", name: "phoneRequired", title: "required:true", required: true, multiple: false)
-			input(type: "phone", name: "phoneWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("email") {
-			input(type: "email", name: "email", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "email", name: "emailRequired", title: "required:true", required: true, multiple: false)
-			input(type: "email", name: "emailWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("decimal") {
-			input(type: "decimal", name: "decimal", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "decimal", name: "decimalRequired", title: "required:true", required: true, multiple: false)
-			input(type: "decimal", name: "decimalWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("mode") {
-			input(type: "mode", name: "mode", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "mode", name: "modeRequired", title: "required:true", required: true, multiple: false)
-			input(type: "mode", name: "modeMultiple", title: "multiple:true", required: false, multiple: true)
-			input(type: "mode", name: "iconWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("icon") {
-			input(type: "icon", name: "icon", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "icon", name: "iconRequired", title: "required:true", required: true, multiple: false)
-			input(type: "icon", name: "iconWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("capability") {
-			input(type: "capability.switch", name: "capability", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "capability.switch", name: "capabilityRequired", title: "required:true", required: true, multiple: false)
-			input(type: "capability.switch", name: "capabilityMultiple", title: "multiple:true", required: false, multiple: true)
-			input(type: "capability.switch", name: "capabilityWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("hub") {
-			input(type: "hub", name: "hub", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "hub", name: "hubRequired", title: "required:true", required: true, multiple: false)
-			input(type: "hub", name: "hubMultiple", title: "multiple:true", required: false, multiple: true)
-			input(type: "hub", name: "hubWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("device") {
-			input(type: "device.switch", name: "device", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "device.switch", name: "deviceRequired", title: "required:true", required: true, multiple: false)
-			input(type: "device.switch", name: "deviceMultiple", title: "multiple:true", required: false, multiple: true)
-			input(type: "device.switch", name: "deviceWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("time") {
-			input(type: "time", name: "time", title: "required:false, multiple:false", required: false, multiple: false)
-			input(type: "time", name: "timeRequired", title: "required:true", required: true, multiple: false)
-			input(type: "time", name: "timeWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-		section("contact-book") {
-			input("recipients", "contact", title: "Notify", description: "Send notifications to") {
-				input(type: "phone", name: "phone", title: "Send text message to", required: false, multiple: false)
-				input(type: "boolean", name: "boolean", title: "Send push notification", required: false, multiple: false)
-			}
-		}
-	}
+    dynamicPage(name: "inputPage", title: "Links to every 'input' element") {
+        section {
+            href(page: "inputBooleanPage", title: "to boolean page")
+            href(page: "inputIconPage", title: "to icon page")
+            href(page: "inputImagePage", title: "to image page")
+            href(page: "inputSelectionPage", title: "to selection page")
+            href(page: "inputTextPage", title: "to text page")
+            href(page: "inputTimePage", title: "to time page")
+        }
+        section("subsets of selection input") {
+            href(page: "inputDevicePage", title: "to device selection page")
+            href(page: "inputCapabilityPage", title: "to capability selection page")
+            href(page: "inputRoomPage", title: "to room selection page")
+            href(page: "inputModePage", title: "to mode selection page")
+            href(page: "inputHubPage", title: "to hub selection page")
+            href(page: "inputContactBookPage", title: "to contact-book selection page")
+        }
+    }
+}
+
+def inputBooleanPage() {
+    dynamicPage(name: "inputBooleanPage") {
+        section {
+            paragraph "The `required` and `multiple` attributes have no effect because the value will always be either `true` or `false`"
+        }
+        section {
+            input(type: "boolean", name: "booleanWithoutDescription", title: "without description", description: null)
+            input(type: "boolean", name: "booleanWithDescription", title: "with description", description: "This has a description")
+        }
+        section("defaultValue: 'true'") {
+            input(type: "boolean", name: "booleanWithDefaultValue", title: "", description: "", defaultValue: "true")
+        }
+        section("with image") {
+            input(type: "boolean", name: "booleanWithoutDescriptionWithImage", title: "without description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", description: null)
+            input(type: "boolean", name: "booleanWithDescriptionWithImage", title: "with description", description: "This has a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputIconPage() {
+    dynamicPage(name: "inputIconPage") {
+        section {
+            paragraph "`description` is not displayed for icon elements"
+            paragraph "`multiple` has no effect because you can only choose a single icon"
+        }
+        section("required: true") {
+            input(type: "icon", name: "iconRequired", title: "without description", required: true)
+            input(type: "icon", name: "iconRequiredWithDescription", title: "with description", description: "this is a description", required: true)
+        }
+        section("with image") {
+            paragraph "The image specified will be replaced after an icon is selected"
+            input(type: "icon", name: "iconwithImage", title: "without description", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputImagePage() {
+    dynamicPage(name: "inputImagePage") {
+        section {
+            paragraph "This only exists in DeviceTypes. Someone should do something about that. (glares at MikeDave)"
+            paragraph "Go to the device preferences of a Mobile Presence device to see it in action"
+            paragraph "If you try to set the value of this, it will not behave as it would in Device Preferences"
+            input(type: "image", title: "This is kind of what it looks like", required: false)
+        }
+    }
+}
+
+
+def optionsGroup(List groups, String title) {
+    def group = [values:[], order: groups.size()]
+    group.title = title ?: ""
+    groups << group
+    return groups
+}
+def addValues(List groups, String key, String value) {
+    def lastGroup = groups[-1]
+    lastGroup["values"] << [
+            key: key,
+            value: value,
+            order: lastGroup["values"].size()
+    ]
+    return groups
+}
+def listToMap(List original) {
+    original.inject([:]) { result, v ->
+        result[v] = v
+        return result
+    }
+}
+def addGroup(List groups, String title, values) {
+    if (values instanceof List) {
+        values = listToMap(values)
+    }
+
+    values.inject(optionsGroup(groups, title)) { result, k, v ->
+        return addValues(result, k, v)
+    }
+    return groups
+}
+def addGroup(values) {
+    addGroup([], null, values)
+}
+/* Example usage of options builder
+
+// Creating grouped options
+    def newGroups = []
+    addGroup(newGroups, "first group", ["foo", "bar", "baz"])
+    addGroup(newGroups, "second group", [zero: "zero", one: "uno", two: "dos", three: "tres"])
+
+// simple list
+    addGroup(["a", "b", "c"])
+
+// simple map
+    addGroup(["a": "yes", "b": "no", "c": "maybe"])​​​​
+*/
+
+
+def inputSelectionPage() {
+
+    def englishOptions = ["One", "Two", "Three"]
+    def spanishOptions = ["Uno", "Dos", "Tres"]
+    def groupedOptions = []
+    addGroup(groupedOptions, "English", englishOptions)
+    addGroup(groupedOptions, "Spanish", spanishOptions)
+
+    dynamicPage(name: "inputSelectionPage") {
+
+        section("options variations") {
+            paragraph "tap these elements and look at the differences when selecting an option"
+            input(type: "enum", name: "selectionSimple", title: "Simple options", description: "no separators in the selectable options", groupedOptions: addGroup(englishOptions + spanishOptions))
+            input(type: "enum", name: "selectionGrouped", title: "Grouped options", description: "separate groups of options with headers", groupedOptions: groupedOptions)
+        }
+
+        section("list vs map") {
+            paragraph "These should be identical in UI, but are different in code and will produce different settings"
+            input(type: "enum", name: "selectionList", title: "Choose a device", description: "settings will be something like ['Device1 Label']", groupedOptions: addGroup(["Device1 Label", "Device2 Label"]))
+            input(type: "enum", name: "selectionMap", title: "Choose a device", description: "settings will be something like ['device1-id']", groupedOptions: addGroup(["device1-id": "Device1 Label", "device2-id": "Device2 Label"]))
+        }
+
+        section("segmented") {
+            paragraph "segmented should only work if there are either 2 or 3 options to choose from"
+            input(type: "enum", name: "selectionSegmented1", style: "segmented", title: "1 option", groupedOptions: addGroup(["One"]))
+            input(type: "enum", name: "selectionSegmented4", style: "segmented", title: "4 options", groupedOptions: addGroup(["One", "Two", "Three", "Four"]))
+
+            paragraph "multiple and required will have no effect on segmented selection elements. There will always be exactly 1 option selected"
+            input(type: "enum", name: "selectionSegmented2", style: "segmented", title: "2 options", options: ["One", "Two"])
+            input(type: "enum", name: "selectionSegmented3", style: "segmented", title: "3 options", options: ["One", "Two", "Three"])
+
+            paragraph "specifying defaultValue still works with segmented selection elements"
+            input(type: "enum", name: "selectionSegmentedWithDefault", title: "defaulted to 'two'", groupedOptions: addGroup(["One", "Two", "Three"]), defaultValue: "Two")
+        }
+
+        section("required: true") {
+            input(type: "enum", name: "selectionRequired", title: "This is required", description: "It should look different when nothing is selected", groupedOptions: addGroup(["only option"]), required: true)
+        }
+
+        section("multiple: true") {
+            input(type: "enum", name: "selectionMultiple", title: "This allows multiple selections", description: "It should look different when nothing is selected", groupedOptions: addGroup(["an option", "another option", "no way, one more?"]), multiple: true)
+        }
+
+        section("with image") {
+            input(type: "enum", name: "selectionWithImage", title: "This has an image", description: "and a description", groupedOptions: addGroup(["an option", "another option", "no way, one more?"]), image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputTextPage() {
+    dynamicPage(name: "inputTextPage", title: "Every 'text' variation") {
+        section("style and functional differences") {
+            input(type: "text", name: "textRequired", title: "required: true", description: "This should look different when nothing has been entered", required: true)
+            input(type: "text", name: "textWithImage", title: "with image", description: "This should look different when nothing has been entered", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", required: false)
+        }
+        section("text") {
+            input(type: "text", name: "text", title: "This has an alpha-numeric keyboard", description: "no special formatting", required: false)
+        }
+        section("password") {
+            input(type: "password", name: "password", title: "This has an alpha-numeric keyboard", description: "masks value", required: false)
+        }
+        section("email") {
+            input(type: "email", name: "email", title: "This has an email-specific keyboard", description: "no special formatting", required: false)
+        }
+        section("phone") {
+            input(type: "phone", name: "phone", title: "This has a numeric keyboard", description: "formatted for phone numbers", required: false)
+        }
+        section("decimal") {
+            input(type: "decimal", name: "decimal", title: "This has an numeric keyboard with decimal point", description: "no special formatting", required: false)
+        }
+        section("number") {
+            input(type: "number", name: "number", title: "This has an numeric keyboard without decimal point", description: "no special formatting", required: false)
+        }
+
+        section("specified ranges") {
+            paragraph "You can limit number and decimal inputs to a specific range."
+            input(range: "50..150", type: "decimal", name: "decimalRange50..150", title: "only values between 50 and 150 will pass validation", description: "no special formatting", required: false)
+            paragraph "Negative limits will add a negative symbol to the keyboard."
+            input(range: "-50..50", type: "number", name: "numberRange-50..50", title: "only values between -50 and 50 will pass validation", description: "no special formatting", required: false)
+            paragraph "Specify * to not limit one side or the other."
+            input(range: "*..0", type: "decimal", name: "decimalRange*..0", title: "only negative values will pass validation", description: "no special formatting", required: false)
+            input(range: "*..*", type: "number", name: "numberRange*..*", title: "only positive values will pass validation", description: "no special formatting", required: false)
+            paragraph "If you don't specify a range, it defaults to 0..*"
+        }
+    }
+}
+def inputTimePage() {
+    dynamicPage(name: "inputTimePage") {
+        section {
+            input(type: "time", name: "timeWithDescription", title: "a time picker", description: "with a description", required: false)
+            input(type: "time", name: "timeWithoutDescription", title: "without a description", description: null, required: false)
+            input(type: "time", name: "timeRequired", title: "required: true", required: true)
+        }
+    }
+}
+
+/// selection subsets
+def inputDevicePage() {
+
+    dynamicPage(name: "inputDevicePage") {
+
+        section("required: true") {
+            input(type: "device.switch", name: "deviceRequired", title: "This is required", description: "It should look different when nothing is selected")
+        }
+
+        section("multiple: true") {
+            input(type: "device.switch", name: "deviceMultiple", title: "This is required", description: "It should look different when nothing is selected", multiple: true)
+        }
+
+        section("with image") {
+            input(type: "device.switch", name: "deviceRequired", title: "This has an image", description: "and a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputCapabilityPage() {
+
+    dynamicPage(name: "inputCapabilityPage") {
+
+        section("required: true") {
+            input(type: "capability.switch", name: "capabilityRequired", title: "This is required", description: "It should look different when nothing is selected")
+        }
+
+        section("multiple: true") {
+            input(type: "capability.switch", name: "capabilityMultiple", title: "This is required", description: "It should look different when nothing is selected", multiple: true)
+        }
+
+        section("with image") {
+            input(type: "capability.switch", name: "capabilityRequired", title: "This has an image", description: "and a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputRoomPage() {
+
+    dynamicPage(name: "inputRoomPage") {
+
+        section("required: true") {
+            input(type: "room", name: "roomRequired", title: "This is required", description: "It should look different when nothing is selected")
+        }
+
+        section("multiple: true") {
+            input(type: "room", name: "roomMultiple", title: "This is required", description: "It should look different when nothing is selected", multiple: true)
+        }
+
+        section("with image") {
+            input(type: "room", name: "roomRequired", title: "This has an image", description: "and a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputModePage() {
+
+    dynamicPage(name: "inputModePage") {
+
+        section("required: true") {
+            input(type: "mode", name: "modeRequired", title: "This is required", description: "It should look different when nothing is selected")
+        }
+
+        section("multiple: true") {
+            input(type: "mode", name: "modeMultiple", title: "This is required", description: "It should look different when nothing is selected", multiple: true)
+        }
+
+        section("with image") {
+            input(type: "mode", name: "modeRequired", title: "This has an image", description: "and a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputHubPage() {
+
+    dynamicPage(name: "inputHubPage") {
+
+        section("required: true") {
+            input(type: "hub", name: "hubRequired", title: "This is required", description: "It should look different when nothing is selected")
+        }
+
+        section("multiple: true") {
+            input(type: "hub", name: "hubMultiple", title: "This is required", description: "It should look different when nothing is selected", multiple: true)
+        }
+
+        section("with image") {
+            input(type: "hub", name: "hubRequired", title: "This has an image", description: "and a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
+}
+def inputContactBookPage() {
+
+    dynamicPage(name: "inputContactBookPage") {
+
+        section("required: true") {
+            input(type: "contact", name: "contactRequired", title: "This is required", description: "It should look different when nothing is selected")
+        }
+
+        section("multiple: true") {
+            input(type: "contact", name: "contactMultiple", title: "This is required", description: "It should look different when nothing is selected", multiple: true)
+        }
+
+        section("with image") {
+            input(type: "contact", name: "contactRequired", title: "This has an image", description: "and a description", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
 }
 
 def appPage() {
-	dynamicPage(name: "appPage", title: "Every 'app' type") {
-		section {
-			paragraph "These won't work unless you create a child SmartApp to link to... Sorry."
-		}
-		section("app") {
-			app(
-				name: "app",
-				title: "required:false, multiple:false",
-				required: false,
-				multiple: false,
-				namespace: "Steve",
-				appName: "Child SmartApp"
-			)
-			app(name: "appRequired", title: "required:true", required: true, multiple: false, namespace: "Steve", appName: "Child SmartApp")
-			app(name: "appComplete", title: "state:complete", required: false, multiple: false, namespace: "Steve", appName: "Child SmartApp", state: "complete")
-			app(name: "appWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", namespace: "Steve", appName: "Child SmartApp")
-		}
-		section("multiple:true") {
-			app(name: "appMultiple", title: "multiple:true", required: false, multiple: true, namespace: "Steve", appName: "Child SmartApp")
-		}
-		section("multiple:true with image") {
-			app(name: "appMultipleWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", namespace: "Steve", appName: "Child SmartApp")
-		}
-	}
+    dynamicPage(name: "appPage", title: "Every 'app' type") {
+        section {
+            paragraph "These won't work unless you create a child SmartApp to link to... Sorry."
+        }
+        section("app") {
+            app(
+                    name: "app",
+                    title: "required:false, multiple:false",
+                    required: false,
+                    multiple: false,
+                    namespace: "Steve",
+                    appName: "Child SmartApp"
+            )
+            app(name: "appRequired", title: "required:true", required: true, multiple: false, namespace: "Steve", appName: "Child SmartApp")
+            app(name: "appComplete", title: "state:complete", required: false, multiple: false, namespace: "Steve", appName: "Child SmartApp", state: "complete")
+            app(name: "appWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", namespace: "Steve", appName: "Child SmartApp")
+        }
+        section("multiple:true") {
+            app(name: "appMultiple", title: "multiple:true", required: false, multiple: true, namespace: "Steve", appName: "Child SmartApp")
+        }
+        section("multiple:true with image") {
+            app(name: "appMultipleWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", namespace: "Steve", appName: "Child SmartApp")
+        }
+    }
 }
 
 def labelPage() {
-	dynamicPage(name: "labelPage", title: "Every 'Label' type") {
-		section("label") {
-			label(name: "label", title: "required:false, multiple:false", required: false, multiple: false)
-			label(name: "labelRequired", title: "required:true", required: true, multiple: false)
-			label(name: "labelWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-	}
+    dynamicPage(name: "labelPage", title: "Every 'Label' type") {
+        section("label") {
+            paragraph "The difference between a label element and a text input element is that the label element will effect the SmartApp directly by setting the label. An input element will place the set value in the SmartApp's settings."
+            paragraph "There are 3 here as an example. Never use more than 1 label element on a page."
+            label(name: "label", title: "required:false, multiple:false", required: false, multiple: false)
+            label(name: "labelRequired", title: "required:true", required: true, multiple: false)
+            label(name: "labelWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
 }
 
 def modePage() {
-	dynamicPage(name: "modePage", title: "Every 'mode' type") { // TODO: finish this
-		section("mode") {
-			mode(name: "mode", title: "required:false, multiple:false", required: false, multiple: false)
-			mode(name: "modeRequired", title: "required:true", required: true, multiple: false)
-			mode(name: "modeMultiple", title: "multiple:true", required: false, multiple: true)
-			mode(name: "modeWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-	}
+    dynamicPage(name: "modePage", title: "Every 'mode' type") { // TODO: finish this
+        section("mode") {
+            paragraph "The difference between a mode element and a mode input element is that the mode element will effect the SmartApp directly by setting the modes it executes in. A mode input element will place the set value in the SmartApp's settings."
+            paragraph "Another difference is that you can select 'All Modes' when choosing which mode the SmartApp should execute in. This is the same as selecting no modes. When a SmartApp does not have modes specified, it will execute in all modes."
+            paragraph "There are 4 here as an example. Never use more than 1 mode element on a page."
+            mode(name: "mode", title: "required:false, multiple:false", required: false, multiple: false)
+            mode(name: "modeRequired", title: "required:true", required: true, multiple: false)
+            mode(name: "modeMultiple", title: "multiple:true", required: false, multiple: true)
+            mode(name: "modeWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, multiple: true, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+        }
+    }
 }
 
 def paragraphPage() {
-	dynamicPage(name: "paragraphPage", title: "Every 'paragraph' type") {
-		section("paragraph") {
-			paragraph "This us how you should make a paragraph element"
-			paragraph image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", "This is a long description, blah, blah, blah."
-		}
-	}
-}
-
-def iconPage() {
-	dynamicPage(name: "iconPage", title: "Every 'icon' type") { // TODO: finish this
-		section("icon") {
-			icon(name: "icon", title: "required:false, multiple:false", required: false, multiple: false)
-			icon(name: "iconRequired", title: "required:true", required: true, multiple: false)
-			icon(name: "iconWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-	}
+    dynamicPage(name: "paragraphPage", title: "Every 'paragraph' type") {
+        section("paragraph") {
+            paragraph "This is how you should make a paragraph element"
+            paragraph image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", "This is a long description, blah, blah, blah."
+        }
+    }
 }
 
 def hrefPage() {
-	dynamicPage(name: "hrefPage", title: "Every 'href' type") {
-		section("page") {
-			href(name: "hrefPage", title: "required:false, multiple:false", required: false, multiple: false, page: "deadEnd")
-			href(name: "hrefPageRequired", title: "required:true", required: true, multiple: false, page: "deadEnd", description: "Don't make hrefs required")
-			href(name: "hrefPageComplete", title: "state:complete", required: false, multiple: false, page: "deadEnd", state: "complete")
-			href(name: "hrefPageWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", page: "deadEnd",)
-		}
-		section("external") {
-			href(name: "hrefExternal", title: "required:false, multiple:false", required: false, multiple: false, style: "external", url: "http://smartthings.com/")
-			href(name: "hrefExternalRequired", title: "required:true", required: true, multiple: false, style: "external", url: "http://smartthings.com/", description: "Don't make hrefs required")
-			href(name: "hrefExternalComplete", title: "state:complete", required: false, multiple: true, style: "external", url: "http://smartthings.com/", state: "complete")
-			href(name: "hrefExternalWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", url: "http://smartthings.com/")
-		}
-		section("embedded") {
-			href(name: "hrefEmbedded", title: "required:false, multiple:false", required: false, multiple: false, style: "embedded", url: "http://smartthings.com/")
-			href(name: "hrefEmbeddedRequired", title: "required:true", required: true, multiple: false, style: "embedded", url: "http://smartthings.com/", description: "Don't make hrefs required")
-			href(name: "hrefEmbeddedComplete", title: "state:complete", required: false, multiple: true, style: "embedded", url: "http://smartthings.com/", state: "complete")
-			href(name: "hrefEmbeddedWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", url: "http://smartthings.com/")
-		}
-	}
+    dynamicPage(name: "hrefPage", title: "Every 'href' variation") {
+        section("stylistic differences") {
+            href(page: "deadEnd", title: "state: 'complete'", description: "gives the appearance of an input that has been filled out", state: "complete")
+            href(page: "deadEnd", title: "with image", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
+            href(page: "deadEnd", title: "with image and description", description: "and state: 'complete'", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", state: "complete")
+        }
+        section("functional differences") {
+            href(page: "deadEnd", title: "to a page within the app")
+            href(url: "http://www.google.com", title: "to a url using all defaults")
+            href(url: "http://www.google.com", title: "external: true", description: "takes you outside the app", external: true)
+        }
+    }
 }
 
 def buttonsPage() {
-	dynamicPage(name: "buttonsPage", title: "Every 'button' type") {
-		section("buttons") {
-			buttons(name: "buttons", title: "required:false, multiple:false", required: false, multiple: false, buttons: [
-				[label: "foo", action: "foo"],
-				[label: "bar", action: "bar"]
-			])
-			buttons(name: "buttonsRequired", title: "required:true", required: true, multiple: false, buttons: [
-				[label: "foo", action: "foo"],
-				[label: "bar", action: "bar"]
-			])
-			buttons(name: "buttonsWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", buttons: [
-				[label: "foo", action: "foo"],
-				[label: "bar", action: "bar"]
-			])
-		}
-		section("Colored Buttons") {
-			buttons(name: "buttonsColoredSpecial", title: "special strings", description: "SmartThings highly recommends using these colors", buttons: [
-				[label: "complete", action: "bar", backgroundColor: "complete"],
-				[label: "required", action: "bar", backgroundColor: "required"]
-			])
-			buttons(name: "buttonsColoredHex", title: "hex values work", buttons: [
-				[label: "bg: #000dff", action: "foo", backgroundColor: "#000dff"],
-				[label: "fg: #ffac00", action: "foo", color: "#ffac00"],
-				[label: "both fg and bg", action: "foo", color: "#ffac00", backgroundColor: "#000dff"]
-			])
-			buttons(name: "buttonsColoredString", title: "strings work too", buttons: [
-				[label: "green", action: "foo", backgroundColor: "green"],
-				[label: "red", action: "foo", backgroundColor: "red"],
-				[label: "both fg and bg", action: "foo", color: "red", backgroundColor: "green"]
-			])
-		}
-	}
+    dynamicPage(name: "buttonsPage", title: "Every 'button' type") {
+        section("Simple Buttons") {
+            paragraph "If there are an odd number of buttons, the last button will span the entire view area."
+            buttons(name: "buttons1", title: "1 button", buttons: [
+                    [label: "foo", action: "foo"]
+            ])
+            buttons(name: "buttons2", title: "2 buttons", buttons: [
+                    [label: "foo", action: "foo"],
+                    [label: "bar", action: "bar"]
+            ])
+            buttons(name: "buttons3", title: "3 buttons", buttons: [
+                    [label: "foo", action: "foo"],
+                    [label: "bar", action: "bar"],
+                    [label: "baz", action: "baz"]
+            ])
+            buttons(name: "buttonsWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", buttons: [
+                    [label: "foo", action: "foo"],
+                    [label: "bar", action: "bar"]
+            ])
+        }
+        section("Colored Buttons") {
+            buttons(name: "buttonsColoredSpecial", title: "special strings", description: "SmartThings highly recommends using these colors", buttons: [
+                    [label: "complete", action: "bar", backgroundColor: "complete"],
+                    [label: "required", action: "bar", backgroundColor: "required"]
+            ])
+            buttons(name: "buttonsColoredHex", title: "hex values work", buttons: [
+                    [label: "bg: #000dff", action: "foo", backgroundColor: "#000dff"],
+                    [label: "fg: #ffac00", action: "foo", color: "#ffac00"],
+                    [label: "both fg and bg", action: "foo", color: "#ffac00", backgroundColor: "#000dff"]
+            ])
+            buttons(name: "buttonsColoredString", title: "strings work too", buttons: [
+                    [label: "green", action: "foo", backgroundColor: "green"],
+                    [label: "red", action: "foo", backgroundColor: "red"],
+                    [label: "both fg and bg", action: "foo", color: "red", backgroundColor: "green"]
+            ])
+        }
+    }
 
 }
 
 def imagePage() {
-	dynamicPage(name: "imagePage", title: "Every 'image' type") { // TODO: finish thise
-		section("image") {
-			image "http://f.cl.ly/items/1k1S0A0m3805402o3O12/20130915-191127.jpg"
-			image(name: "imageWithImage", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, image: "https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png")
-		}
-	}
+    dynamicPage(name: "imagePage", title: "Every 'image' type") { // TODO: finish thise
+        section("image") {
+            image "http://f.cl.ly/items/1k1S0A0m3805402o3O12/20130915-191127.jpg"
+            image(name: "imageWithMultipleImages", title: "This element has an image and a long title.", description: "I am setting long title and descriptions to test the offset", required: false, images: ["https://s3.amazonaws.com/smartapp-icons/Convenience/Cat-Convenience.png", "http://f.cl.ly/items/1k1S0A0m3805402o3O12/20130915-191127.jpg"])
+        }
+    }
 }
 
 def videoPage() {
-	dynamicPage(name: "imagePage", title: "Every 'image' type") { // TODO: finish this
-		section("video") {
-			// TODO: update this when there is a videoElement method
-			element(name: "videoElement", element: "video", type: "video", title: "this is a video!", description: "I am setting long title and descriptions to test the offset", required: false, image: "http://ec2-54-161-144-215.compute-1.amazonaws.com:8081/jesse/cam1/54aafcd1c198347511c26321.jpg", video: "http://ec2-54-161-144-215.compute-1.amazonaws.com:8081/jesse/cam1/54aafcd1c198347511c2631f.mp4")
-		}
-	}
+    dynamicPage(name: "videoPage", title: "Every 'video' type") { // TODO: finish this
+        section("video") {
+            // TODO: update this when there is a videoElement method
+            element(name: "videoElement", element: "video", type: "video", title: "this is a video!", description: "I am setting long title and descriptions to test the offset", required: false, image: "http://f.cl.ly/items/0w0D1p0K2D0d190F3H3N/Image%202015-12-14%20at%207.57.27%20AM.jpg", video: "http://f.cl.ly/items/3O2L03471l2K3E3l3K1r/Zombie%20Kid%20Likes%20Turtles.mp4")
+        }
+    }
 }
 
 def flattenedPage() {
-	def allSections = []
-	firstPage().sections.each { section ->
-		section.body.each { hrefElement ->
-			if (hrefElement.page != "flattenedPage") {
-				allSections += "${hrefElement.page}"().sections
-			}
-		}
-	}
-	def flattenedPage = dynamicPage(name: "flattenedPage", title: "All elements in one page!") {}
-	flattenedPage.sections = allSections
-	return flattenedPage
+    def allSections = []
+    firstPage().sections[0].body.each { hrefElement ->
+        if (hrefElement.name != "inputPage") {
+            // inputPage is a bunch of hrefs
+            allSections += "${hrefElement.page}"().sections
+        }
+    }
+    // collect the input elements
+    inputPage().sections.each { section ->
+        section.body.each { hrefElement ->
+            allSections += "${hrefElement.page}"().sections
+        }
+    }
+    def flattenedPage = dynamicPage(name: "flattenedPage", title: "All elements in one page!") {}
+    flattenedPage.sections = allSections
+    return flattenedPage
 }
 
 def foo() {
-	dynamicPage(name: "deadEnd") {
-
-	}
+    dynamicPage(name: "deadEnd") {
+        section {  }
+    }
 }
 
 def installed() {
-	log.debug "Installed with settings: ${settings}"
+    log.debug "Installed with settings: ${settings}"
 
-	initialize()
+    initialize()
 }
 
 def updated() {
-	log.debug "Updated with settings: ${settings}"
+    log.debug "Updated with settings: ${settings}"
 
-	unsubscribe()
-	initialize()
+    unsubscribe()
+    initialize()
 }
 
 def initialize() {
-	// TODO: subscribe to attributes, devices, locations, etc.
+    // TODO: subscribe to attributes, devices, locations, etc.
 }

smartapps/smartthings/speaker-notify-with-sound.src/speaker-notify-with-sound.groovy

@@ -75,8 +75,8 @@ def mainPage() {
 			ifUnset "timeOfDay", "time", title: "At a Scheduled Time", required: false
 		}
 		section{
-			input "actionType", "enum", title: "Action?", required: true, defaultValue: "Custom Message", options: [
-				"Custom Message",
+			input "actionType", "enum", title: "Action?", required: true, defaultValue: "Bell 1", options: [
+				//"Custom Message",
 				"Bell 1",
 				"Bell 2",
 				"Dogs Barking",
@@ -89,7 +89,7 @@ def mainPage() {
 				"Someone is arriving",
 				"Piano",
 				"Lightsaber"]
-			input "message","text",title:"Play this message", required:false, multiple: false
+			//input "message","text",title:"Play this message", required:false, multiple: false
 		}
 		section {
 			input "sonos", "capability.musicPlayer", title: "On this Speaker player", required: true
@@ -409,12 +409,13 @@ private loadText() {
 			state.sound = [uri: "http://s3.amazonaws.com/smartapp-media/sonos/lightsaber.mp3", duration: "10"]
 			break;
 		default:
-			if (message) {
+			/*if (message) {
 				state.sound = textToSpeech(message instanceof List ? message[0] : message) // not sure why this is (sometimes) needed)
 			}
 			else {
 				state.sound = textToSpeech("You selected the custom message option but did not enter a message in the $app.label Smart App")
-			}
+			}*/
+			state.sound = [uri: "http://s3.amazonaws.com/smartapp-media/sonos/bell1.mp3", duration: "10"]
 			break;
 	}
 }