https://thingsthataresmart.wiki/api.php?action=feedcontributions&user=MichaelStruck&feedformat=atomThings That Are Smart Wiki - User contributions [en]2024-03-28T18:25:19ZUser contributionsMediaWiki 1.32.0https://thingsthataresmart.wiki/index.php?title=Ask_Alexa&diff=15177Ask Alexa2020-09-30T16:03:38Z<p>MichaelStruck: /* Roadmap */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
'''Ask Alexa''' is an add-in to the SmartThings mobile application that allows you to control a broad array of devices with your Amazon Alexa Enabled Devices. When installed along with the proper services at AWS (Amazon Web Services), a simple voice command allows you to control your devices along with querying their status. Simply "Ask" Alexa to do something within your SmartThings environment and she will respond!<br />
<br />
'''Ask Alexa''' can replace the basic integration between SmartThings and Alexa. In the default SmartThings integration, you may only control switches and thermostats and there is limited feedback to ask the status of the devices. '''Ask Alexa''' improves this integration by not only expanding the devices you can control with your voice, but you can now get real-time feedback on inside temperatures, door, switch, dimmer status, etc, and control modes, Smart Home Monitoring security status, run routines and set up complex macro-like events using natural speech. You can even interface other SmartThings SmartApps into '''Ask Alexa''' by using the message queue function and access another popular community-written app, WebCoRE, directly from '''Ask Alexa''' (and in turn, '''Ask Alexa''' macros can be referenced within the WebCoRE application itself).<br />
<br />
No matter how you want to address your home, from a more "Star Trek" experience ("''<Computer, tell studio to turn the lights on"''>) to natural language (<''"Alexa, tell the house I am cold"''>), '''Ask Alexa''' is the go-to app for SmartThings/Alexa integration.<br />
<br />
[[File:AAMainScreen.jpg|890px]]<br />
<br />
==Summary==<br />
[[File:AskAlexa512.png|256px]]<br />
<br />
'''Category:''' My Apps<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Code contributions:''' Keith DeLong, Barry Burke, foxxyben & M3Rocket (utterances), Jimxenus/larry-fuqua (misspellings/logic issues in the GUI), jhamstead and Yves Racine for Ecobee code<br />
<br />
'''Documentation contributions:''' Keith DeLong, Jason Headley, Belgarion, Barry Burke, Andrea Bianco, Yves Racine, Todd M(@Pantheon)<br />
<br />
===Latest Versions===<br />
<br />
{| class="wikitable"<br />
|+The latest version of each of the applications listed in this document (as of 1/14/19)<br />
|-<br />
! '''Ask Alexa Code''' !! Area Used !!'''Version''' !! '''Location'''<br />
|-<br />
| '''SmartApp Code''' || SmartThings IDE || ''2.3.9h'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
|-<br />
| '''Node.js''' || Lambda code for aws.amazon.com (manual install only) || ''1.3.1a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/Node.js<br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|+Extensions<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues]|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
|-<br />
| '''Rooms/Groups Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_Rooms/Groups]|| SmartThings IDE || ''1.0.4b'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
|-<br />
| '''Schedules Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Schedules]|| SmartThings IDE || ''1.0.4a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
|-<br />
| '''Voice Report Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Voice_Reports]|| SmartThings IDE || ''1.0.9'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
|-<br />
| '''Weather Report Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Weather_Reports]|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy <br />
|}<br />
<br />
===Compatibility With Other SmartApps===<br />
'''Ask Alexa''' isn't limited to just the standard devices that come with SmartThings. It can also work directly with other SmartApps and even some custom Device Type Handlers. The following is the current list of compatible SmartApps/DTHs...Items with (2.0) designation already or will support the new message queue structure (see [[Ask_Alexa_-_Message_Queues]]):<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''SmartApp/Custom Device Type''' !! '''Supported Features''' !! '''Author'''<br />
|-<br />
| '''NST Manager''' || ''Message queue (2.0) and thermostat reports'' || Anthony Santilli<br />
|-<br />
| '''WebCoRE''' || ''Message queue (2.0)'' || Adrian Caramaliu<br />
|-<br />
| '''My Ecobee Device & Service Manager (MyEcobeeInit)''' || ''Message queue (2.0) - Comfort & Energy Saving tips for your Ecobee device, ecobee Alerts, exception events and tstat reports'' || Yves Racine<br />
|-<br />
| '''Zoned Heating/Cooling Solutions (ecobeeSetZoneWithSchedule, ScheduleRoomTempControl, ScheduleTstatZones)''' || ''Message queue (2.0) for reporting heating/cooling zoned scheduling events'' || Yves Racine<br />
|-<br />
| '''Device Monitor''' || ''Message queue (2.0) '' || Eric Maycock<br />
|-<br />
| '''MonitorAutomaticCar''' ||''Message Queue (2.0) for reporting hard acceleration/brake/ignition off/on and other Automatic events'' || Yves Racine<br />
|-<br />
| '''OSRAM Lighting Controls-DTH''' [https://raw.githubusercontent.com/gkl-sf/SmartThings/master/osram-bulb-HA.groovy] || ''Loop/Pulse'' || gkl-sf<br />
|-<br />
| '''Foobot Air Quality Monitor-DTH'''[https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/foobot-air-quality-monitor.src/foobot-air-quality-monitor.groovy] || CO2/Particles/VOCs/Temperature/Humidity || Michael Struck/Adam V<br />
|-<br />
| '''Big Talker''' || ''Message Queue (2.0)'' || Brian Lowrance<br />
|-<br />
| '''Lock Manager''' || ''Message Queue (2.0)'' || Erik Thayer<br />
|-<br />
| '''RemindR''' || ''Message Queue (2.0)'' || Bobby Dobrescu <br />
|-<br />
| '''Smart GCal Control''' || ''Message Queue (2.0)'' || Anthony Pastor (infofiend)<br />
|-<br />
| '''Sports Notifications''' || ''Message Queue (2.0)'' || Eric Luttmann<br />
|-<br />
| '''Spruce Status'''|| ''Message Queue (2.0)'' || Barry Burke<br />
|-<br />
| '''Open Source Ecobee Thermostat, Sensors and Companion SmartApps'''|| ''Message Queue 2.0 for Ecobee Alerts and Reminders'' || Barry Burke<br />
|-<br />
| '''My Ecobee stats generation Smartapps'''|| ''Message Queue (2.0) for reporting ecobee daily/weekly/monthly runtime (HomeIQ) stats '' || Yves Racine<br />
|-<br />
| '''MyNeurio & MyNeurioAppliance Service Managers'''|| ''Message Queue (2.0) for reporting exception events and summary Energy Consumption & Generation reports (Daily, Weekly, Monthly)'' || Yves Racine<br />
|-<br />
| '''MyAutomatic Service Manager'''|| ''Message Queue (2.0) for reporting exception events and Driving Summary Reports (Daily, Weekly, Monthly)'' || Yves Racine<br />
|-<br />
| '''MonitorAndSetEcobeeHumidity'''|| ''Message Queue (2.0) for humidity control notifications - using HRV/ERV/Humidifier/Dehumidifier devices connected to your ecobee'' || Yves Racine<br />
|-<br />
|-<br />
| '''MyFlair Devices (Puck, Vent, HvacUnit) & Service Manager'''|| ''Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions'' || Yves Racine<br />
|-<br />
| '''MyNextManager & Devices (Tstat, Alarm, Cam)'''|| ''Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions'' || Yves Racine<br />
|-<br />
| '''Room Occupancy'''||''Control over the occupancy of a room using a custom DTH, Message Queue (2.0)'' || Bangali<br />
|-<br />
| '''GE Motion Switch/Dimmer'''||''Verbal control over the operating mode of the switch (models 26933 and 26931)'' || Michael Struck<br />
|-<br />
|}<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use '''Ask Alexa''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Requirements==<br />
<br />
The following are the basic requirements to use '''Ask Alexa''':<br />
<br />
*A mobile device running the SmartThings mobile application<br />
*An Amazon Alexa Enabled Device (it is not required the device be integrated with SmartThings, but doing so won't interfere with '''Ask Alexa''')<br />
*Devices (Switches, lighting, thermostats, etc) that are operational within the SmartThings environment. To help Alexa understand your devices, they should each be uniquely named in your account. <br />
*An AWS Lambda and developer account<br />
**For the developer account, please ensure you create the account under the same account you used for your Amazon Alexa Enabled Device setup. See the steps to create the account [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide here].<br />
**For the AWS/Lambda account (to host your code), follow the instructions [https://aws.amazon.com/lambda/getting-started/ here]. Please note that you MAY need to provide a credit card for the setup. Be sure to read the pricing structure for AWS Lambda space [https://aws.amazon.com/lambda/pricing/ here].<br />
<br />
==Privacy Statement==<br />
'''Ask Alexa''' leverages an external web hosting service to automate some of the setup and operation of the SmartApp. To ensure complete transparency, you may read the privacy statement here: [http://ask-alexa.com/privacy.html]<br />
<br />
==Limitations==<br />
* The instructions presented here are for US installations only. While many of the concepts are universal, all screen shots and languages assume US/English installations. If you find some slight variation are needed in these instructions please update the wiki or contact the author of this application.<br />
<br />
== Definitions ==<br />
<br />
Throughout this document there will be some specific terms relating to the SmartThings and Amazon development environments.<br />
<br />
===SmartThings/Ask Alexa/General Definitions===<br />
*'''SmartApp:''' Add-in to the SmartThings mobile application that allows for functionality outside of what is provided by default. These SmartApps are not stand alone programs, but only operate within the SmartThings mobile application. SmartApps are open source and written in a form of the Java programming language called “groovy”.<br />
*'''Parent/Child SmartApp:''' A code structure within the SmartThings development environment where a single instance of a parent SmartApp can have multiple child SmartApps associated with it, allowing the single SmartApp to have multiple functions. '''Ask Alexa''' uses this structure for its extensions; there can only be one instance of the '''Ask Alexa''' SmartApp and each extension created within the parent SmartApp is actually an instance of the child SmartApp. This structure cuts down on repeated code within a single SmartApp.<br />
*'''Virtual Switch:''' A device within the SmartThings environment that functions like a regular switch (think of a button or a light switch). However, the device is “virtual” and does not exist as a physical device. Used mostly with [http://thingsthataresmart.wiki/index.php?title=Alexa_Helper Alexa Helper]. However, you can activate virtual switches using '''Ask Alexa''' as well.<br />
*'''Alias:''' In the context of '''Ask Alexa''', this is a name that is used as a place holder (or alias) for another device. This allows to have two devices named the same thing within your SmartThings app, but allows you to address them differently in '''Ask Alexa'''.<br />
*'''IDE:''' Abbreviation for “Integrated Development Environment”. In the context of the SmartThings environment, this is the web site located at http://ide.smartthings.com or https://graph-eu01-euwest1.api.smartthings.com/ (depending on your country) that allows for advanced functionality within the SmartThings environment. This allows you to set up custom devices and applications that appear within your SmartThings mobile application.<br />
*'''DTH:''' '''D'''evice '''T'''ype '''H'''andlers. This is code that is usually community written and allows third-party devices to operate in the SmartThings environment. A good example of this is the Nest Thermostat.<br />
*'''GitHub:''' A web-based repository that allows for distribution revision control and source code management functionality.<br />
*'''OAuth:''' Provides client applications a secure method for accessing resources on behalf of the resource owner. Within the context of SmartThings, certain custom applications that allow for remote access (such as remotely turning on or off a light) will require additional authentication. As the owner of the resource, you can authorize remote access to an application by enabling OAuth.<br />
*'''Access Token:''' A security identity that is linked to OAuth and in the context of SmartThings allows for remote control of a locations devices.<br />
*'''URL:''' Uniform Resource Locator, or basically the address of a web site or online resource, such as http://www.smartthings.com<br />
*'''REST:''' '''RE'''presentational '''S'''tate '''T'''ransfer is an architectural style, and an approach to communications that is often used in the development of Web services. In SmartThings, it is how external applications, such as Amazon's services, can interact the devices in your account, using the OAuth and Access Token as 'keys' to securely access these devices.<br />
*'''Text Field Variables:''' In the context of '''Ask Alexa''', these are variables that can be used in any text areas of the macros to give you 'short cuts' to commonly used text. Typically, they start and end with a percent sign, like %temp%. See [[Ask_Alexa#Text_Field_Variables]] for the variables currently available.<br />
*'''WebCoRE:''' '''W'''eb '''C'''ommunity's '''o'''wn '''R'''ule '''E'''ngine. Another SmartThings community developed application that defines 'pistons' to perform complex, decision-based automation. One of these events could be a trigger from '''Ask Alexa'''. More information can be found here: https://community.smartthings.com/t/webcore-beta-milestone-1/86153<br />
<br />
===Amazon/Alexa Development Definitions===<br />
*'''AWS:''' Amazon Web Services is a collection of cloud computing services that make up the on-demand computing platform offered by Amazon.com.<br />
*'''Lambda:''' An AWS service. Lambda lets you run code without provisioning or managing servers. With Lambda, you can run code for virtually any type of application or back-end service - all with zero administration. <br />
*'''A.S.K.:''' The Alexa Skills Kit is a collection of self-service APIs, tools, documentation and code samples that make it fast and easy for you to add skills to Alexa.<br />
*'''Invocation Name:''' This is the name you will "invoke" to communicate with the Alexa Enabled Devices, which in turn communicates with SmartThings and '''Ask Alexa'''. By default, the invocation name using in '''Ask Alexa''' is "smart things"; however, the invocation name can also be words like "home", or "house" to make command syntax smoother. You may even set up multiple skills, each with the name of a room, and have personalized responses for each room. For example, you could say <''"Alexa, tell the kitchen to turn off the lights"''> and affect the Kitchen, or <''"Alexa, turn the lights off in the bedroom"''> and only have the lights in the bedroom react.<br />
*'''Intents:''' An intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots. <br />
*'''Custom Slots:''' A custom slot type is used for items that are not covered by Amazon’s built-in set of types and is recommended for most use cases where a slot value is one of a set of possible values. The values for the custom slots are generated for you via the Settings page. You will simply copy the provided data and paste it into the Amazon Developer Site. <br />
*'''Utterances:''' A structured text file that connects the intents to likely spoken phrases and containing as many representative phrases as possible.<br />
*'''JSON:''' is an abbreviation for ''JavaScript Object Notation'' is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. The Amazon ASK Development area uses JSON for sending input to and from the Alexa Enabled Devices. The basic structure of JSON looks like this:<br />
<br />
<pre style="display: inline-block;"><br />
{<br />
"intent": "DeviceOperation",<br />
"slots": [<br />
{<br />
"name" : "Operator",<br />
"type" : "LIST_OF_OPERATORS"<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
==How Ask Alexa Works==<br />
<br />
Unlike most SmartThings SmartApps, '''Ask Alexa''' works in concert with the external Amazon developer site, including the Lambda web service. However, the "heavy lifting" of determining the condition of your house, generating reports, and most of the feedback spoken by the Alexa Enabled Devices is actually produced by your SmartThings account, NOT the Amazon cloud services. See the diagram below for a bit more detail on this.<br />
<br />
[[File:AAFlow.png|700px]]<br />
<br />
<pre style="display: inline-block;"><br />
Thanks to Keith DeLong for the above diagram.<br />
</pre><br />
<br />
The user will query their Amazon device, and the Amazon "skill" simply looks for the nouns and verbs (keywords) of your speech and then send those key words to your SmartThings account. The '''Ask Alexa''' SmartApp processes this information, does its actions, and sends Amazon the text response to process through its text-to-speech function. Basically, the Alexa Enabled Device is not turning on your devices...your '''Ask Alexa''' SmartApp is doing the work.<br />
<br />
==Set up of your Alexa Enabled Devices==<br />
Setup of your Amazon Alexa Enabled Devices with SmartThings native functionality is NOT required to use '''Ask Alexa'''. '''Ask Alexa''' operates independently of the integration. However, to have a backup method of controlling your environment, or to use apps like [http://thingsthataresmart.wiki/index.php?title=Alexa_Helper Alexa Helper], you will need to follow the steps below. Please refer to your Amazon Echo documentation, use the Amazon Echo mobile app, or visit http://alexa.amazon.com for more information.<br />
<br />
[[File:EchoApp.png|right|200px]]<br />
* Configure your device on your home’s Wifi and ensured that it is functional<br />
* Configure the device to work with your SmartThings Devices [[https://support.smartthings.com/hc/en-us/articles/205275404-How-to-connect-Amazon-Echo-with-SmartThings]] (via the Amazon Echo application on your mobile phone or http://alexa.amazon.com. Setup within the Amazon Echo app is under ''Settings'' and ''Connected Home'')<br />
* Once SmartThings is properly configured, go into the Amazon Echo SmartApp within SmartThings (See image to the right) and click on the switches you intend to use. These can be real switches/dimmers, virtual switches or momentary button tiles<br />
* Click <<Done>>, then say to your Alexa Enabled Device ''<"Alexa, discover new devices">''<br />
* Within the Amazon Echo Application (NOT the SmartThings app), or http://alexa.amazon.com, you should now see the switches you have "Discovered"<br />
* If you later add switches to SmartThings, you will need to add them to Amazon Echo Smart App within SmartThings, then "Discover" them<br />
<br />
==Setting up your Amazon Lambda and Developer Accounts==<br />
To use '''Ask Alexa''' you will need to create two "free" accounts at Amazon. While the full instructions on setting up these accounts is outside of the scope of this document, very clear instructions are published by Amazon themselves:<br />
<br />
[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide '''Developer Account'''] <br />
<br />
[https://aws.amazon.com/lambda/getting-started/ '''Lambda Account''']<br />
<br />
Please note that these account are 'free' (see the information here[https://aws.amazon.com/free/]). Please be sure to ONLY sign up for the Lambda piece, and the 'basic' tier of service. You MAY be required to provide a credit card number, however, to open an account.<br />
<br />
[[File:AAMainAWS.jpg|700px]]<br />
<br />
'''Notice'''<br />
While the Lambda account is listed as free, if you generate excessive <br />
traffic from your account, Amazon WILL charge you. Fortunately, this <br />
level of traffic would need to exceed 5 million hits per month to account<br />
for even $1.00. So, while the accounts are 'free' for general use, full <br />
public distribution and use would definitely incur a fee if your volume <br />
is high enough.<br />
<br />
==Ask Alexa (SmartThings Code) Installation==<br />
<br />
There are multiple methods to get '''Ask Alexa''' installed into the SmartThings environment. You can use the Community Installer, manually install the code from the links in GitHub, or use the IDE/GitHub integration within SmartThings.<br />
<br />
===Community Installer (Free Marketplace)===<br />
<br />
To install '''Ask Alexa''' via the Community Installer, please see here: http://thingsthataresmart.wiki/index.php?title=Community_Installer_(Free_Marketplace)<br />
<br />
Simply find '''Ask Alexa''' in the list, and install ALL pieces of the application (including Extensions or 'child' applications). If you are upgrading, click the <<Update>> button.<br />
<br />
[[File:CI-AboutApp2.png|250px]]<br />
<br />
===Manual Installation===<br />
<br />
The code for the '''Ask Alexa''' SmartThings SmartApp is found on the GitHub site:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
<br />
While on the GitHub site, find the '''Raw''' button and click it. This will bring up a non-formatted page with just the code present. Select all of the code (typically CTRL+A) and copy It (typically CTRL+C).<br />
<br />
[[File:GitHub.png|700px]]<br />
<br />
<br />
*Next, point your browser to you SmartThings IDE for your country (i.e. http://ide.smartthings.com or https://graph-eu01-euwest1.api.smartthings.com) and '''Log In'''.<br />
<br />
[[File:loginscreen.jpg|700px]]<br />
<br />
*Once you are logged in, find the '''My SmartApps''' link on the top of the page. Clicking '''My SmartApps''' will allow you to produce a new SmartApp.<br />
<br />
[[File:MySmartApps.png|700px]]<br />
<br />
*Find the button on this page labeled '''+New SmartApp''' and click it.<br />
<br />
[[File:+NewSmartApp.png|700px]]<br />
<br />
*Since you already have the code in your computer’s clipboard, find the tab along the top section called '''From Code'''. In the area provided, paste (typically CTRL+V) the code you copied from GitHub. Click '''Create''' in the bottom left corner of the page.<br />
<br />
[[File:NewSmartAppCreate.png|700px]]<br />
<br />
*This will bring up another page, with the code now formatted within the IDE. If the code was copied correctly, there are no other steps except to save and publish the code. In the upper right corner of the page, find and click '''Save'''. Now, click '''Publish (For Me)''', and you should receive a confirmation that the code has been published successfully.<br />
[[File:SavePublish.png]]<br />
<br />
===OAuth Setup===<br />
'''Ask Alexa''' will need to be accessed by the Amazon servers in order to operate correctly. As such, OAuth is REQUIRED for this application.<br />
<br />
To enable OAuth, first find and click the '''App Settings''' button in the upper right corner of the page.<br />
<br />
From here, find the '''OAuth''' section toward the bottom of the page. <br />
<br />
[[File:OAuthBtn.png|700px]]<br />
<br />
Clicking the '''OAuth''' link will reveal a button labeled '''Enable OAuth in Smart App'''. Click this button. The screen will change, giving you a unique code for your '''Client ID''' and '''Client Secret'''. These are the foundations of the security of your app and should be kept secret. You do not need to memorize or write down these codes; nor do you need to add any other information to this page. OAuth simply needs to be enabled for '''Ask Alexa''' to operate.<br />
<br />
[[File:OAuth.jpg|700px]]<br />
<br />
The final step is to press the '''Update''' button at the bottom left corner of the screen, or go back to your code by using the button in the upper-right region of the page, then '''Save''', then '''Publish''' the SmartApp again. <br />
<br />
[[File:SavePublish.png]]<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
Next, you will need to load up the child extension SmartApps. This code for these are located here. Installation is exactly the same for each one. Just repeat the steps below for each set of code.<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy<br />
<br />
The steps for installation are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
===Advanced Installation===<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of SmartThings SmartApp code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found on the SmartThings web site [[http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git]]<br />
<br />
'''Please Note:''' <br />
This process only applies to installing the SmartThings SmartApp. <br />
This process DOES NOT update any of the code on the Amazon developer site; <br />
you will need to follow the process [[Ask_Alexa#Building_The_Skill]] to <br />
install or update your skill information.<br />
<br />
Once you have integration, the four pieces of code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page (this will only appear after you integrate with GitHub)<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''Ask Alexa''' SmartApp code, enter the information as you see it below:<br />
{| class="wikitable"<br />
!'''Owner'''!!'''Name'''!!'''Branch'''<br />
|-<br />
| MichaelStruck || SmartThingsPublic || Master<br />
|}<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. These will typically be:<br />
<br />
<br />
{| class="wikitable"<br />
|+GitHub location of Apps/Extensions<br />
|-<br />
! '''SmartApp''' !! '''Location'''<br />
|-<br />
| '''Main Ask Alexa''' || smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
|-<br />
| '''Message Queue Extension''' || smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
|-<br />
| '''Rooms/Groups Extension''' || smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
|-<br />
| '''Scheduler Extension''' || smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
|-<br />
| '''Voice Report Extension''' || smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
|-<br />
| '''Weather Report Extension''' || smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy<br />
|-<br />
|}<br />
<br />
'''Tip'''<br />
When adding code from the repo you have to add it in a <br />
specific order or the IDE will generate an internal server error. <br />
Add the main Smartapp (Ask Alexa) to your IDE first. Then you can <br />
add the extensions.<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new apps should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Ask Alexa SmartApp Installation==<br />
If you installed the code properly, you should find the '''Ask Alexa''' SmartApp located in the SmartThings Mobile Application under Market Place>>>SmartApps>>>+MyApps. If you have published any of the '''Ask Alexa''' extension you may see them in this list as well. DO NOT install those; just install the main '''Ask Alexa''' app. You may install extensions via the parent SmartApp.<br />
<br />
[[File:AAAddSmartApp.png|250px]]<br />
<br />
After you install '''Ask Alexa''', it is a good idea to set it up, and THEN do the Amazon setup pieces ([[Ask_Alexa#Developer_and_Lambda_Code_Installation]]). This will limit your need to go back and forth as the way you configure '''Ask Alexa''' determines how you set up the Amazon Developer's site.<br />
<br />
==Ask Alexa Interface==<br />
When you first open the SmartApp, you will be greeted with colorful icons where you can interface items with Alexa. Some of these items allow for control (i.e. switches, doors, locks, etc), and some will only provide their status (open/close sensors, water sensors). More devices are being integrated as the application matures. Some menu items (like the <<Device Aliases>>) may not appear in your interface until you activate the appropriate options in the <<Settings>> area (see [[Ask_Alexa#Allow_Device_Aliases]])<br />
<br />
It is recommended that you now add the devices you will want control of and status of to the interface before going on to the next steps of setting up the Developer/Lambda accounts. This will prevent your having to repeat these steps upon the completion of your installation.<br />
<br />
[[File:AAMain.png|250px]]<br />
<br />
===Interface Items===<br />
<br />
Currently, you have the ability to interface switches (dimmers and colored lights), locks, temperature/humidity devices (including thermostats), open/close, presence, motion and water sensors, along with your SmartThings modes, Smart Home Monitor and Routines to your Alexa Enabled Devices. Please note that in addition to the devices to interface, if you have the <<Allow Device Aliases>> enabled in the <<Settings>> area, you will also see options to add devices that can have aliases associated with them.<br />
<br />
*'''Lighting/Switches'''-These devices are very straight forward; you can turn them on, off or toggle their state (<''"Alexa, ask SmartThings toggle the Living Room"''>), change the level of a dimmer (<''"Alexa, tell SmartThings to set the Dining Room to 50%"''>), or even change the color of a bulb (<''"Alexa, ask SmartThings to set the Den to Blue"''>). In addition, you can ask the status of a device easily (<''"Alexa, ask SmartThings the status of the Living Room"''>). For items like colored lights, two commands may be combined into one...For example <''"Alexa, ask SmartThings to set the Den to Blue and to 50%"''>. Also on this page, if you choose colored lights, you will find the option to add a custom color as well under the <<Settings>><<Custom Color Setup>> ([[Ask_Alexa#Custom_Color_Setup]]). As is customary with dimming controls, only positive numbers between zero and 100 are accepted; any numbers exceeding this value will be normalized to the 0-100 range. Finally, you can use custom commands like maximum, increase, decrease, brighten, dim and low, medium and high to specify default behavior of dimmable switches. <br />
<br />
'''Please Note'''<br />
There are over 150 available colors to choose from in the latest version of '''Ask Alexa'''.<br />
A full list of colors would take minutes to recite; if you need to reference <br />
these colored names, it is recommended you view the cheat sheet <br />
(see [[Ask_Alexa#About_Ask_Alexa]]) or the FAQs (see: [[Ask_Alexa#Frequently_Asked_Questions_.28FAQs.29]]).<br />
The names of the colors come directly from SmartThings. Again, if one of these colors <br />
do not meet your needs you can define your own custom color.<br />
<br />
For Temperature (Kelvin) lights, you have the option of choosing four settings, <br />
"Soft White", "Warm White", "Cool White" and "Daylight White", setting the lights <br />
to 2700K, 3500K, 4500K and 6700K degrees Kelvin, respectfully. These are the only <br />
temperature setting available for these lights, which are typically white LED lights.<br />
You can change the default value of these 4 settings by going to <<Settings>><br />
<<Default Command Values>>. See [[Ask_Alexa#Default_Command_Values]]<br />
<br />
*'''Doors/Windows/Locks'''-Another simple set of devices that can be addressed using natural language. A simple command such as <''"Alexa, tell SmartThings to unlock the front door"''> will unlock the door. To enhance security, you do have the option to set up a PIN to prevent these simple commands from allowing access to critical devices (see [[Ask_Alexa#Password_PIN]]). In addition, you can disable commands like "Open" Or "Unlock" for additional security. As with the switches, you can always query the status of device (<''"Alexa, ask SmartThings about the Garage Door"''>). In this category are window shades, locks, doors, and open/closed sensors which are usually used for door or window open/close status.<br />
<br />
'''Important Notice Of Liability'''<br />
It can not be stressed enough that allowing your locks or doors to be controlled by<br />
this SmartApp lowers the security of your household. Anyone with knowledge of your <br />
home setup (including your PIN) can open/close/lock/unlock these devices. The author <br />
of this application accepts NO RESPONSIBILITY with intentional or unintentional <br />
use (or misuse) of these features. Use SmartThings holistically; if you enable this<br />
feature ensure you are also properly monitoring/alerting on the devices as well.<br />
<br />
*'''Environmentals'''- Many SmartThings devices have temperature, humidity or even UV sensors built into them. As such, you may query the status of these devices to get their current readings. Also, you may set the set any SmartThings connected thermostat to a specific setpoint. Please note that many thermostats have both heating and cooling setpoints. As such, unless you have your thermostat set to just heating or just cooling, it is a good idea to ensure you are setting the proper setpoint. For example, if you thermostat is in auto mode, you could say <''"Alexa, tell SmartThings to set the heat in the office to 65 degrees"''>. If your thermostat is in a specific mode (like heating), it is perfectly acceptable to just ask her to set the temperature setpoint...<''"Alexa, tell SmartThings to set the office to 65 degrees"''><br />
<br />
'''Please Note'''<br />
<<Environmentals>> is the area you are most likely to have the same device<br />
in multiple device categories. For example, you might have a humidity sensor that can<br />
also be added as a temperature sensor, or an air quality monitor that registers humidity.<br />
'''The program will not operate correctly if you choose the same device in multiple areas.''' <br />
It should be noted, however, that if you turn on additional attributes within the <<Settings>><br />
<<Device/Event Voice Setting>>menu that you can hear the additional parameters without choosing <br />
the same device in two different categories.<br />
<br />
When you select a thermostat you will be given the option to select some device specific commands. Various devices that work with SmartThings have powerful features or different command sets that don't comply with normal APIs provided by SmartThings. A good example of this is the Nest Thermostat; this device is not officially supported by SmartThings, but there are a few community-written device handlers that allows it to perform normal thermostat functions within your house. However, it also has other features that no other thermostats have; one of these features is the ability for the thermostat to act as a presence sensor, changing the way it behaves based on occupancy. The user may also set the "Home" and "Away" status manually, or through automation. If you are using Nest Manager, you can even expand on the generic Nest commands with custom reports (i.e. <"Alexa, ask SmartThings for Nest report">.<br />
<br />
Another example is the Stelpro baseboard heating thermostat. This device is supported by SmartThings, but had different modes of operation besides heating and cooling; these are "Eco" and "Comfort" modes. Ecobee3 (Connect), as yet another example, allows for specific modes such as "Home", "Away", "Sleep", and "Resume Program" commands.<br />
<br />
====MyEcobee & MyNext Devices' comfort & energy saving tips ====<br />
<br />
If you have a Ecobee or a Nest thermostat, you have the ability to use a community-developed device type handler, written by Yves Racine, to get you tips to operating your device (and your home) more efficiently. To access these tips, do the following:<br />
<br />
*Go to <<Settings>><br />
*Choose <<Device Specific Commands>><br />
*Choose <<Ecobee Specific Thermostat Modes>><br />
*Choose <<MyEcobee Specific Tips>><br />
<br />
Or if you have My Next Tstat for the Nest Thermostat:<br />
<br />
*Choose <<MyNextTstat Specific Tips>><br />
<br />
Then, you can use the following commands with My Ecobee or My NextTstat Device(s):<br />
<br />
'''Individual commands'''<br />
*'''Give Tip/Play Tip''' - This will play the tips available in memory, one at a time, for this device. The tips will increment to the next tip in memory until they have all been heard, at which point they will replay.<br />
*'''Repeat Tip''' - This will repeat the tip that was just played and will not increment the tip counter.<br />
<br />
'''Batch commands (Advanced)'''<br />
*'''Get Tips[Level]''' - Without a number given, it will default to "Level 1" tips, which are the most general. To choose additional tip levels, say that level (i.e. <''"Alexa, tell SmartThings to Get Tips, level 3, for Kitchen"''>. Please note that this will NOT play any tips, it just tells the device handler to load the tips for you into memory. <br />
*'''Reset Tips''' - This will reset the tips in memory. You must then say 'Get Tips' (with or without level) for the device to obtain more tips.<br />
<br />
For more information on the My Ecobee's Get Tips, please see here: http://thingsthataresmart.wiki/index.php?title=EcobeeGetTips<br />
<br />
For more information on the My Next Tstat's Get Tips, please see here: http://thingsthataresmart.wiki/index.php?title=NestGetTips<br />
<br />
<br />
*'''Connected Speakers'''- If you connected speakers such as Sonos, Bose or Samsung with SmartThings, they can be controlled with '''Ask Alexa'''. Basic commands are supported, with plans to implement other features in the future. Simple say, <''"Alexa, tell SmartThings to play Bedroom Speaker"''> and the device will come on. You can also pause, mute, and skip tracks. You can also give a volume command between 0-100. Like the dimmers, you can also "increase" and "decrease" the volume based on the settings you define in the <<Settings>> area. <br />
<br />
'''Notice'''<br />
The Sonos integration within SmartThings is currently in listed as a "Labs" .<br />
release. This means certain functionality is subject to change or may not work as<br />
expected. This includes re-playing music from a saved list.<br />
<br />
*'''Other Sensors'''-You may have other sensors around your house that you would also like to report on. Currently, acceleration, water, presence, occupancy and motion sensors are available. With the water sensors, you get a status reading of either wet or dry. Presence and motion/acceleration sensors behave in a similar fashion, with one state (present or motion) or another. Similarly, using a custom Device Type Handler, you can also check the status or change the occupancy of a room. In addition, as most of these types of sensors also have temperature readings available, if you have the other attributes configured to play, the voice reading will include this as well. Finally, if the sensor is a battery operated device, the battery reading will play if below the designated threshold (Set in <<Settings>>). Typically, sensors are read-only. However, with version 2.2.2, you may use the concept of a 'virtual' or simulated presence sensor so that those without physical presence devices can be accounted for and automations can run based on their presence. Users simply 'check in' or 'check out' with Alexa when entering a location.Physical presence sensors will not work with these additional commands. You will need to create a simulated presence sensor. The instructions for installation of this virtual device is here: [[Virtual_Presence_Sensor]]. <br />
<br />
*'''Modes/Routines/SHM''' - Unlike the native SmartThings integration, '''Ask Alexa''' will allow you to query and/or change the modes or Smart Home Monitor status, in addition to running a specific routine. When speaking to Alexa, ensure you specify what you want to do: <''"Alexa, ask SmartThings to run Good Morning Routine"''> or <''"Alexa, ask SmartThings the current Security status"''>. Be sure your mode or routine names also are unique among your SHM settings as well (i.e. Stay, Arm, etc.). If you have unique names to your routines and modes, you may shorten your commands to <''"Alexa, tell SmartThings Good Morning"''>, assuming you have a "Good Morning" routine. Finally, you have the ability to require a PIN number to activate the modes/routines or change the Smart Home Monitor settings. This option will appear when you have the PIN enabled in the <<Settings>> area (see: [[Ask_Alexa#Password_PIN]])<br />
<br />
'''Please Note'''<br />
For the Smart Home Monitor (SHM) functions, if you do not choose ANY states<br />
this will effectively release the 'reserved' words of "security", "smart home" and <br />
SHM. This is useful if you have switches set up with those same words. For example,<br />
if you use the popular app "Smart Alarm" you can now have a virtual switch called <br />
"security".<br />
<br />
*'''Device Aliases''' - While it is recommended that you have unique names for each of your devices within your SmartThings environment, this is sometimes not possible or practical. However, you can't address devices that appear multiple times with the same name (i.e. the name "Living Room" that is both a lamp device and a motion sensor). To solve this, '''Ask Alexa''' allows you to set up aliases to allow you to access all the devices within your environment without having to rename your devices within the main SmartThings app. You must turn this function on in the <<Setting>> menu item and then select the devices you wish to create aliases for in each of the device categories above. Once you do this, you will see the <<Device Alias>> selection appear. Using the example above, you could keep controlling the living room lamp with just with the name "Living Room" and then create an alias for the living room motion sensor. Once set up, the alias name behaves exactly like any other devices, picking up parameters unique to the device type. Another good example is to shorten a device name so it is easier to address. For example, if you have a long name for your speaker (i.e. "Master Bedroom Sonos") you could create an alias simply called "speaker" to address that device (see figure below).<br />
<br />
[[File:AAAliasMain.png|250px]] <br />
<br />
'''Alias Usage Limitations/Notes'''<br />
* Aliases are one-to-one associations; to control groups of devices using a single name you <br />
will need to create a room/group (see [[Ask_Alexa_Rooms/Groups]]).<br />
<br />
* Alias names must still be unique within the '''Ask Alexa''' app. This means the name should<br />
not be the same as any other device (or alias) or routine, modes or voice macros<br />
<br />
* When creating and deleting alias names, be sure to use the interface buttons provided on <br />
the page and not the SmartThings "Done","Save" or "<" buttons. Using these may give you undesired results.<br />
<br />
* Speaking of interface, due to a limitation of the SmartThings GUI, when you create your first<br />
alias that names will 'stick' in the interface input areas, giving you an error if you do not change <br />
it and simply press ADD again (as the alias name will be one that you just created). Be sure all of your <br />
alias names are unique and that you change the interface when you add or delete an alias.<br />
<br />
===Extensions===<br />
[[File:Ext@2x.png|100px]]<br />
<br />
On the main '''Ask Alexa''' page, scroll down to the area labeled <<Extensions>>. Extensions can be thought of as 'mini' applications that expand the functionality of '''Ask Alexa'''. Currently, there are multiple extensions available: Macros (which are built in), Message Queues, rooms/groups, voice/weather reports and scheduling. Additional extensions coming soon.<br />
<br />
'''Notice'''<br />
When naming your extensions (be it Message Queues, rooms, voice reports or Macro names or aliases), <br />
ensure your names are unique not only within the context of the other extensions, but <br />
within the parent app itself. That means an extension should not share the same name with<br />
devices, aliases, modes, or routines within the parent app. Taking this precaution will <br />
eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
[[File:AAMQMain.png|250px]]<br />
<br />
For information about each extension, including setup instructions, please click on the appropriate link below:<br />
<br />
* '''Macros''': [[Ask_Alexa_-_Macros]]<br />
* '''Message Queues''': [[Ask_Alexa_-_Message_Queues]]<br />
* '''Rooms/Groups''': [[Ask_Alexa_Rooms/Groups]]<br />
* '''Schedules''': [[Ask_Alexa_-_Schedules]]<br />
* '''Weather Reports''': [[Ask_Alexa_-_Weather_Reports]]<br />
* '''Voice Reporting''': [[Ask_Alexa_-_Voice_Reports]]<br />
<br />
===Settings===<br />
<br />
Back on the main (parent) interface you will find the <<Settings>> area. This page is separated into four sections that allow you to customize your '''Ask Alexa''' experience. This includes what the Alexa device will say when you ask for a status of SmartThings devices, whether or not you need a password for security related items (like doors, locks, Smart Home Monitor settings, etc), and the default values used to set up and operate the SmartApp for your environment.<br />
<br />
====Setup Ask Alexa====<br />
The very top menu item is where you want to go for all things related to setting up '''Ask Alexa'''. This includes defining the Skill Invocation name, getting the setup variables for the Amazon AWS and Developer's sites, and displaying the command 'cheat sheet'.<br />
<br />
[[File:AASetup.png|250px]]<br />
<br />
=====Skill Invocation Name=====<br />
<br />
At the top of the page you will set up a specific invocation name for the skill name. Throughout this document the assumption is that you use "Smart Things" (two separate words) as this name; however, it can be anything. If you do change it within Amazon developer web site, you SHOULD change it here to match.<br />
<br />
=====Setup Variables=====<br />
The voice system of the Amazon Alexa Enabled Devices is very programmable. Almost any device you have in your system can be addressed by name. However, the Alexa Enabled Devices do not know these names by default; you must input them into the Amazon developer site as custom slots ([[Ask_Alexa#Custom_Slot_Information]]). While this can be a tedious task, '''Ask Alexa''' reduces the steps by evaluating the devices you have chosen to interface and generate an HTML setup page, allowing you to copy and paste the information directly to the Amazon Developer site.<br />
<br />
When you tap the <<Setup Variables Link>> you will be presented in your SmartThings Live Logging with a web page URL. Copy this link to a computer (desktop) browser and you will then be given a page with the various variables you will need to operate '''Ask Alexa''' properly. <br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Any time you add or remove devices, modes, routines, or reports to your '''Ask Alexa''' SmartApp, it is best practice to put the new information into the custom slots so Alexa recognizes the new commands.<br />
<br />
'''Please note'''<br />
If you find your IDE Live Logging is not presenting the data properly, the page presented<br />
on your mobile device gives you the address you need on your desktop browser to continue<br />
the setup process. Simply copy that address to an e-mail (or other method) the can be <br />
sent to your desktop environment. Of course, the Live Logging method is the preferred <br />
method of obtaining this setup URL.<br />
<br />
[[File:AASetupURL.png|250px]]<br />
<br />
=====Cheat Sheet=====<br />
At the bottom of the setup page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within '''Ask Alexa'''. <br />
<br />
While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See [[Ask Alexa#Setup Variables]])<br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.<br />
<br />
====Additional voice settings====<br />
In this section you will set up what additional information the Alexa Enabled Devices respond back to you and how.<br />
<br />
[[File:AASettings.png|250px]]<br />
<br />
=====Accept Compound Commands=====<br />
<br />
'''Ask Alexa''' can accept 'compound commands' as part of its command structure. Simply put, a compound command is controlling two actions with one statement. For example, you could say ''<"Alexa, tell SmartThings to turn on the office and close the garage"''> to have two actions occur in tandem with one command. While this is convenient, the more words you say to Alexa, the more opportunities she has of misunderstanding you. Turning this option off, you disable the ability for '''Ask Alexa''' to process compound commands. Only single action commands will be accepted.<br />
<br />
=====Device/Event Voice Setting=====<br />
<br />
In this section you will find items relating to the device voice output along with event voice output.<br />
<br />
[[File:AADeviceEvent.png|250px]]<br />
<br />
======Give Brief Device Action Reply======<br />
Under normal operation, when you give an action to a device, Alexa will respond of a confirmation of your action. For example, if you say <''"Alexa, tell SmartThings to lock the Front Door"''>, if the door is locked already she will state that, or if it is unlocked she will respond "I am locking the front door.". However, if you feel that the responses get tedious to hear, you can turn on "Brief" replies to device actions. When clicking this feature, you have the option of having Alexa reply with nothing, an "Ok", "Done", or a user-defined output. Please note a few caveats to this behavior:<br />
* For items like locks and doors, the default action is to check the status of those devices and NOT perform the action if the device is already in the desired state. With brief replies turned on, you will not get this feedback.<br />
* If an error occurs with the device, you will still get the error message if brief replies are activated.<br />
* If you have battery alerting on (See [[Ask Alexa#Battery Level]] below), these messages will append to your brief message.<br />
<br />
Please note that the default behavior has been modified slightly (since version 2.2.9) in that the After Action/Event History Continuation commands will be muted when brief reply is turned on.<br />
<br />
======Speak Additional Status Attributes======<br />
For devices like switches or open/close sensors, there are other attributes that can be accessed besides the primary functions. For example, many light switches also monitor the power usage of the connected device. In addition, most SmartThings sensors (motion, water, or open/close sensors) also monitor temperature. Finally, many stand-alone devices, like motion sensors, are battery operated. When you ask Alexa the status of a device, you also have the option to have the additional attributes spoken.<br />
<br />
To use enable this option, on the main menu of '''Ask Alexa''' find the <<Settings>> option. Tapping this will bring you the <<Settings>> area. Tap the slider labeled <<Speak Additional Device Status Attributes>>.<br />
<br />
Please note items that are NOT selected as motion sensors, but have these capabilities, will ONLY report this attribute when motion is in progress.<br />
<br />
======Device Health======<br />
<br />
Sometimes the devices in your environment go offline. While there are many causes for this, the end result is that you may attempt to control a device and it is offline without you knowing it. If you enable <<Speak Device Health When Offline>> you will be alerted to the offline status of a device when you attempt to control or query the device. Please note that Ask Alexa CANNOT bring the device back online; this requires manual intervention. In addition, some devices that are tagged by SmartThings on being "offline" simply haven't reported in for a while. Many time, just manually toggling the device (be it a switch, or motion sensor) may be enough to put it back into online status.<br />
<br />
======Battery Level======<br />
This option will allow you to set the threshold in which the batteries status is reported on. The default value of the threshold is 20...using this setting, if the battery level on a device is below 20%, when you ask the status of a device (i.e. <''"Alexa, ask SmartThing the status of the living room"''> the battery will be reported as well. Above the threshold, no battery status will be given. Please note that battery report is given whether or not the above attributes setting is selected if the level is below the threshold.<br />
<br />
======Default Number Of Past Events======<br />
SmartThings keeps a log on every change on the devices, whether it be a motion sensor showing movement, or a door opening or closing to a light turning on or off. Using the command "Events" on a device you can access the last events (ex. <''"Alexa, ask SmartThings to give me the last events on Living Room"''>). When no number is specified, the number in the <<Default Number of Past Events To Report>> will be used to give you that number of entries from the log. You can override this by giving a number in the command (ex. <''"Alexa, ask SmartThings to give me the last 4 events from the Bedroom"''>)<br />
<br />
====Enable Flash Briefing====<br />
This option will allow you to enable the ability to use a macro or Message Queue as the output of the native Alexa 'flash briefing' function. This process is described here ([[Ask_Alexa_-_Flash_Briefing]]) and does require additional steps to create a new skill that allows for this functionality. When you select this option, another option appears below it allowing the selection of the output you wish to use for your flash report.<br />
<br />
====Personalization====<br />
With a little bit of configuration on this page, you can give Alexa's responses a more "personalized" touch. This includes allowing her to "follow up" after an error, or address you by name in a formal or even funny manner. All of these options also allow you to have them 'whispered' to you all of the time, or within specific modes or timeframes.<br />
<br />
[[File:AAContCmds.png|250px]]<br />
<br />
Alexa has the ability to continue with a "skill" after the primary function or response is given. With the options in this area, you can choose if you want Alexa to ask ''"Anything else?"'' after certain actions have been performed. For example, if you want to stay within the skill after an error comes up (let's say you didn't choose a valid switch), then you would turn on the <<After Error>> option. When Alexa says ''"Anything else"'' you do not have to use the <''"Alexa, ask SmartThings"''> command; simple state your command (i.e. <''"Turn on the front porch"''>). The settings here are global; if you turn them on <<After Errors>> continuation options will be given after every error. Same for the other switches except <<After Macro Execution>>. For Macros, if you have the <<After Macro Execution>> switch turned on, you DO have the ability to suppress this on a per-macro basis. This does NOT suppress any errors that come up within the macro execution (if turned on); they will only suppress the "Anything else?" questions.<br />
<br />
Also on this screen you can setup your response "Personality". These personalities will give you different types of responses based ranging for "Normal" to "Snarky" to "Courtesy". For advanced users, these can be customize for your environment/mood. You can also set a name that Alexa will occasionally address you by. The responses are random, so it won't happen all of the time. Again, for advanced users, you can use the text variable %people% (see [[Ask_Alexa#Text_Field_Variables]]) to have the responses customized based on who is present in the house. Unfortunately, Alexa has no ability at this time to determine WHO is speaking to her, so the text variable may not be the best solution as it will list everyone in the house.<br />
<br />
=====Playback Options/Restrictions=====<br />
<br />
Under the Global Options of the personality page you will find the playback options/restrictions. Here you can set up restrictions to mute the playback (either disabling Ask Alexa based on the restrictions, or simply mute the playback but continue to process the commands given to it). <br />
<br />
[[File:AAPlayback.png|250px]]<br />
<br />
In addition to muting playback, Alexa also allows the device to change the voice patterns (speed and pitch) including the ability to 'whisper' back to you in a computerize-light voice. Be warned...this has been called by some "creepy", however, there are specific use cases. Because the volume and the overall tone of whispers is less than normal, you can use these during your 'bedtime' to still interact with Alexa and (hopefully) not wake the person next to you. TO do this, simply turn on the switch <<Enable Whisper Mode>>. Leaving the restrictions below this setting blank means that whisper mode will be enabled all of the time. To restrict this, choose the timeframe and/or mode you want whisper mode to operate in. You can also choose which Echo device to apply restrictions to. All output will then be whispered to you until the restrictions conditions change.<br />
<br />
[[File:AHResitrictions.png|250px]]<br />
<br />
For speed and pitch, there are pre-defined configurations you can choose. Please note that if you change the pitch from normal, you will not be able to use the whisper command. Basically, the pitch command is invalid when whispering. However, speed can be used with the whisper mode. You CAN pick and choose between pitch and speed to create a unique voice response within your household.<br />
<br />
'''Please Note'''<br />
Speed, pitch and whisper adjustments configured on this page affect<br />
ALL output coming from '''Ask Alexa.''' This does NOT affect the output<br />
of the normal (non-'''Ask Alexa''' skill) output. If you want specific '<br />
''Ask Alexa''' text to be whispered or emphasized, please use the advanced <br />
features of the <<Text Field Variables>> (see [[Ask_Alexa#Text_Field_Variables]])<br />
<br />
<br />
[[File:AASpeakOpt.png|500px]]<br />
<br />
====Other Values/Variables====<br />
<br />
In this section, depending on your setup, you may have the following options that can be customized by you. The default values should allow for proper operation, but you can change them to suit your needs. <br />
<br />
[[File:AASettings-1.png|250px]]<br />
<br />
=====Default Command Values=====<br />
<br />
Some of the devices that use variable numeric numbers to control them (like dimmers, thermostats or volume control) are context sensitive. This means you don't need to give a specific number to increase or decrease their value. You can simply say <''"Alexa, tell SmartThings to increase the Living Room by 25%">'' and it will rise 25%. However, if you leave off the number, the settings here will be the default amount of the increase or decrease. You can then just say, <''"Alexa, tell SmartThings to increase the Living Room"''> and it will increase by 20% (the default). You can change these numbers accordingly, but be careful for items like volumes and temperature defaults to prevent hearing or heat damage.<br />
<br />
Also, you will see the option for low, medium, high default values. These are good for ceiling fans that operate in 3 different modes, but these settings can be used for lighting as well. Setting these default values will allow you to simply say <''"Alexa, ask SmartThings to set fan to medium"''> and the fan will go to the percentage you place in these areas.<br />
<br />
Finally, if you use Temperature (Kelvin) lights, the values for "Soft White", "Warm White", "Cool White" and "Daylight White". If you do not change these numbers, the defaults will be used (2700K, 3500K, 4500K and 6700K, respectfully).<br />
<br />
=====Device Minimum/Maximum Values=====<br />
For devices with variable inputs that are critical (i.e. volumes, or temperature controls), '''Ask Alexa''' allow you to set minimum and/or maximum values for some of these parameters. For example, a speaker may not need to ever go above 20%...placing 20 in the maximum value slot will prevent your from purposely (or by a misunderstanding from the Amazon TTS system) from setting the volume above this value. In contrast, you may not want to allow your thermostat to be set less than 60 degrees...putting this number in the appropriate slot will prevent any settings from going below that value.<br />
<br />
=====Text Field Variables=====<br />
These global variables are words (typically starting and ending with a percent sign...for example %temp%) that can be used in any text fields of the macros/extensions to give you 'short cuts' to commonly used text. These make it convenient to personalize the messages coming from the Alexa Enabled Devices, macros and extensions.<br />
<br />
[[File:AAVar1.png|250px]][[File:AAVar2.png|250px]]<br />
<br />
A full list of the current variables available to use are here:<br />
<br />
{| class="wikitable"<br />
|+'''Text Field Variables used in pre/post messages and macro acknowledgement areas'''<br />
|-<br />
! '''Variable''' || Translation<br />
|-<br />
| '''%time%''' || This will give the time in 12 hour, AM/PM format<br />
|-<br />
| '''%day%''' || This will speak the day of the week (Monday, Tuesday, etc.)<br />
|-<br />
| '''%date%''' || This will speak the full date (ex. January 25th, 2016)<br />
|-<br />
| '''%temp%''' || When a single device is selected (defined in the temperature report area) the device will report that temperature. If multiple devices are selected, it will average the readings and report the average.<br />
|-<br />
| '''%humid%''' || Similar to the temperature reading above, when a single device is selected the device will report that humidity. If multiple devices are selected, it will average the readings and report the average.<br />
|-<br />
| '''%people%''' || These are defined by presence sensors that are currently present. Using this variable you can personalize some of the responses the Alexa devices give. You can also use this variable when setting up your personalized feedback (See [[Ask Alexa#Personalization]])<br />
|-<br />
| '''%macro%''' || This is the name of the macro/extension that was called.<br />
|-<br />
| '''%mtype%'''|| This is the type of macro/extension being called (i.e. Room/Groups, Control Group, WebCoRE, etc)<br />
|-<br />
|'''%delay%''' || For macros such as WebCoRE and Control macros, this variable holds the delay (in minutes) that was specified within the app or verbally.<br />
|-<br />
|'''%age%''' || For the Schedules extension, this variable holds the age of the schedule (i.e. the person's age or anniversary years) if the original year of the event was defined. <br />
|-<br />
|'''%random{1-3}%''' || When you set up the 3 categories of random responses, placing this variable in a text field will randomly choose a response and play it.<br />
|-<br />
|'''%xParam%''' || For WebCoRE. Extra parameters of control<br />
|}<br />
<br />
For example, if you are giving a nightly report right before you go to bed and you wish to personalize the message, your post message could be something like:<br />
<br />
<pre style="display: inline-block;"><br />
It is %time% on %day%, %date%. It is time for bed %people%. %random1%.<br />
</pre><br />
<br />
This would result in something like ''"It is 9:00pm on Monday June 23, 2016. It is time for bed Jim and Jane. Sleep well...Good night."''. In this particular example, the time and date have been replaced with real time information. The %people% variable is determined by who is present from the presence sensor readings you set up in the main menu <<Setting>> area. Finally, the %random1% list is 3 good night phrases that you have defined. The other two could be "Don't let the bed bugs bite" or "Talk to you in the morning". Anything can be put into these areas.<br />
<br />
In addition to the built-in variables, advanced users have the ability to reference weather reports using a variable. Simple surround your report name with percent signs, and this variable can play in any extension text field. This is very useful for voice reports where you want to include a weather report.<br />
<br />
Finally, there are other advanced flags available ('on-demand whispering', 'emphasis' and 'suppress continuation messages' ) that can be used in text fields. <br />
<br />
The 'on-demand whispering', 'emphasis' tag tags ONLY works if you have the Global Whisper Functions function turned off in the <<Personalization>> section (see [[Ask_Alexa#Personalization]]). This will allow you designate parts of the output as regular and parts as whispers and yet other parts emphasized. <br />
<br />
The 'suppress continuation messages' is only used in macros/extensions when continuation of commands (see [[Ask_Alexa#Personalization]]) is enabled for macros/extensions. Basically, placing this tag at the end of the custom acknowledgement will suppress the prompt "Is there anything else?" placed at the<br />
<br />
To use these features, here is the formatting:<br />
<br />
{| class="wikitable"<br />
|+'''Advanced Tags used in pre/post messages and macro acknowledgement areas'''<br />
|-<br />
! '''Tag''' || '''Usage'''<br />
|-<br />
| '''<w>''' || Any text between here and the "off" switch (below) will be whispered<br />
|-<br />
| '''</w>''' || Any text between the above and this tag whispered<br />
|-<br />
| '''<eH>''' || Any text between here and the "off" switch (below) will be highly emphasized<br />
|-<br />
| '''<eL>''' || Any text between here and the "off" switch (below) will have lower emphasis<br />
|-<br />
| '''</e>''' || Any text between either of the above switches and this tag will be emphasized as outlined(H or L)<br />
|-<br />
| '''%X%''' || Used for macro/extensions custom acknowledgments. Will suppress any output from continuing commands<br />
|}<br />
<br />
For example, let's say you have a voice report that has following custom acknowledgement:<br />
<br />
<pre style="display: inline-block;"><br />
"And that is all. <w>Have a good evening</w>. <eH>Don't let the bed bugs bite!</e> %X%"<br />
</pre><br />
<br />
The section encapsulated by the <w> </w> will be whispered and the text between <eH> </e> will be highly emphasized (slowed down and volume increased) while the other parts will play based as normal. In addition, with the %X% at the end the additional text of "Would you like anything else?" will be suppressed; however, Alexa WILL remain active, listening for any additional commands that can be used within '''Ask Alexa'''.<br />
<br />
=====Custom Color Setup=====<br />
If you have no colored lights in your SmartThings environment, you will not see this selection. If you have chosen any colored lights you will have the option to set up a custom color. Simply give the name of the custom color, the hue and then the saturation of the color (A good reference for hue and saturation is here[http://www.december.com/html/spec/colorhsltable.html]. You will need to ensure you update your developer slots when you have saved this name, but after you do you should have access to this color when utilizing colored lights.<br />
<br />
=====xParams For WebCoRE Macros=====<br />
<br />
If you use '''Ask Alexa''' to run WebCoRE macros and need to pass a word parameter to the piston, you can now (as of 2.3.7) maintain your list of xParams via the SmartApp instead of manually inputting them to the Developer's slots (Under LIST_OF_WCP). More information can be found about passing variables here: [[Ask_Alexa_-_Macros#Advanced_features]]<br />
<br />
[[File:AAxParam.png|250px]]<br />
<br />
====Security====<br />
In this section you can set up security related items such as PIN numbers, or to revoke your Access Token.<br />
<br />
[[File:AASettings-2.png|250px]]<br />
=====Revoke/Reset Access Token=====<br />
It may be necessary sometimes to revoke your Access Token and issue a new one. Typically, this is required when you publicly post the ApplicationID or TokenID to a public site as this would allow others to access your home environment. Once you reset your token, you will need to place the new code pieces into your Lambda code (See [[Ask_Alexa#Finalizing_The_Function_Code]]). <br />
<br />
To proceed with the reset, simply tap the area labeled <<Revoke/Reset Access Token>>. Here, you will be given one last opportunity to cancel this process as doing so will disable the ability for '''Ask Alexa''' to control your SmartThings environment.<br />
<br />
=====Password PIN=====<br />
While one of the strengths of the Alexa Enabled Devices is the voice recognition; one of the weaknesses is that the device has a difficult (and inconsistent) ability to differentiate one person from another. In most household, the Alexa Enabled device is shared among many people. This makes security of commands on the device almost non-existent. For example, imagine a banking app that speaks your bank balance. If you were to have a dinner party, anyone at the party that was savvy enough with the Alexa Enabled Devices could access your bank balance as easily as you. While there is "security through obscurity" in the fact that '''Ask Alexa''' is community built and not mass market, in theory, a person familiar with your home system could yell through a window and say <''"Alexa, ask SmartThings to open the garage door"''>. To prevent this and provide some level of security, '''Ask Alexa''' implements a basic PIN system for security items like doors, locks, modes, routines, SHM, and macros that control these items.<br />
<br />
To use this feature, in the '''Ask Alexa''' SmartApp find the <<Settings>> menu item, then tap the the on/off slider labeled <<Password (PIN) Option Enabled>>. This will reveal an area to enter a PIN number. Be sure to enter numbers in this area. Then, while setting up various items like lock, modes, or control macros, you will be given the option to use the PIN for that function. You can also 'fine tune' this security by adding restrictions, such as the day of the week, or even which Echo devices require a PIN.<br />
<br />
To use this new PIN in the context of opening the garage door, simply say <''"Alexa, ask SmartThings to open the garage door password 1234"''> (assuming you chose 1234 as your PIN). You will always append your commands with the password. Putting it in other locations throughout your syntax may not give the desired results. If you fail to issue the PIN command, you will be prompted by any device or function that requires a PIN to supply this information. This follow up is as simple as <''"Password 1234"''><br />
<br />
====Advanced====<br />
In this section you can enable some of the advanced features of '''Ask Alexa'''. <br />
<br />
[[File:AASettings-3.png|250px]]<br />
<br />
=====Allow Device Aliases=====<br />
To allow devices to have aliases associated with them, enable this option. This will do two things to the main menu interface; first, each device category will have a new area to allow devices to be set up as aliases. Second, once devices are selected, the main menu will display the <<Device Aliases>> area, allowing you to set up the aliases with the devices you have selected. See [[Ask_Alexa#Interface_Items]] for more information.<br />
<br />
=====Assign A Name=====<br />
If you have a need for changing the default name of the SmartApp ('''Ask Alexa''') you may do this using the <<SmartApp Name>> area. This does NOT have any other other affect on the app except to change the name as seen in your SmartThings main app menu. When used with a multi-room setup, you can easily identify the correct app to set up for specific rooms (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]] for more information.)<br />
<br />
===About Ask Alexa===<br />
<br />
The about page gives basic information about the '''Ask Alexa''' app and other parameters you may find useful. You may also produce a "cheat sheet" that can be printed for those not familiar with the setup of the SmartThings environment or your '''Ask Alexa''' configuration. <br />
<br />
In the <<Version Numbers>> section, you will find the versions of the SmartApp and the Lambda code. You can also hear the version numbers of the SmartApp and Lambda code by asking <''"Alexa, Ask SmartThings about Versions"''>.<br />
<br />
In addition, this page displays your current Access Token and Application ID. This is useful for troubleshooting only and should be kept private to prevent someone else from controlling your house. Below this is the list of your Echo devices that have been associated with rooms.<br />
<br />
The Apache license is available on this page as well, along with some basic instructions.<br />
<br />
At the bottom of the page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within '''Ask Alexa'''. <br />
<br />
[[File:AAHelp.png|250px]]<br />
[[File:AAHelp1.png|250px]]<br />
<br />
While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See [[Ask Alexa#Setup Variables]])<br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.<br />
<br />
Finally, if you choose to remove this application (and the corresponding macros), you may do this at the bottom of the page. Simply tap <<Remove>> and the application will be removed from SmartThings. If you choose to set up the app again, you will need to go through the entire setup process again.<br />
<br />
==Developer and Lambda Code Installation==<br />
<br />
The next step is to install the ASK code to the AWS/Lambda server and to define the custom intents, slots and utterances. You will need both an Amazon developer account and an AWS Lambda account. Creation of these accounts is outside of the scope of this document, however, very clear instructions for starting these accounts can be found here: [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide Developer Account] and [https://aws.amazon.com/lambda/getting-started/ Lambda Account]<br />
<br />
===AWS/Lamba Code===<br />
<br />
The basic steps for generically creating Lambda code is listed here [https://developer.amazon.com/alexa-skills-kit/tutorials/fact-skill-1]. Many of the same steps are listed below as well.<br />
<br />
*First, be sure you Lambda account is set to the proper region. The Alexa skills are currently only supported from the <<US East (N. Virginia)>> <<US West (Oregon)>> and <<EU West (Ireland)>> region. Failure to do choose the correct region will prevent you from properly setting up the Configure Triggers ([[Ask Alexa#Configure Triggers]])<br />
[[File:AAAWSP1.png|250px]]<br />
<br />
*Next, find the area within the AWS dashboard for Lambda. This may be a button on the main screen or within the menu below <<Compute>>.<br />
<br />
[[File:AAAWSP2.png|700px]]<br />
<br />
*Find the button labeled <<Create Function>>. Click this and you will begin configuring the parameters of the function.<br />
<br />
[[File:AAAWSP3.png]]<br />
<br />
*You will be brought to a screen to choose a blueprint. Choose <<Author from scratch>> and click it.<br />
<br />
[[File:AAAWSP35.png|700px]]<br />
<br />
From here you will enter a name of the function (it is recommended to use "askAlexa") <br />
<br />
For the area labeled <<Run Time>> it is recommended you set this Node.js (version numbers may be present...always choose the current one), then choose a role or use an existing role. It is recommended that you choose a '''Existing Role''' and select "lambda_basic_execution". If you do not have anything listed in the "Existing Roles" do the following:<br />
<br />
* In the role, choose '''Create a custom role'''<br />
* A new screen will show up<br />
* In the IAM Role, choose '''lambda_basic_execution'''<br />
* Keep the policy name as default<br />
* Click the '''Allow''' button in the bottom right corner of the screen<br />
<br />
[[File:AAlambda.png|700px]]<br />
<br />
When you return to the previous screen and you have configured everything like the screenshot below, click <<Create Function>>.<br />
<br />
[[File:AAAWSP35.png|700px]]<br />
<br />
====Configure Triggers====<br />
<br />
Next, you will be brought to a page where you choose what type of trigger you are creating. On the left side of the screen there is a section called <<Add Trigger>> and here you will choose the "Alexa Skills Kit".<br />
<br />
If you are asked to configure your trigger (specifically with Skill ID), for now choose "Disabled", then <<Add>> in the bottom right of the screen and then click the skill name at the top of the page (above the Skills kit and CloudWatch Logs).<br />
<br />
[[File:AAAWSP3-1.png|700px]]<br />
<br />
'''Please Note''' <br />
If you don't see Alexa Skills Kit in the list, you have chosen the wrong region. <br />
You must use the'''US East (N Viginia)''', '''US West (Oregon)''' or the Ireland datacenters. <br />
Once you have selected Alexa Skills Kit, click <<Configuration>> to go back to the main code <br />
section of the function.<br />
<br />
From here you can enter your code. See the next section (Configure Function) to choose two different methods for entering your code into this area.<br />
<br />
[[File:AAAWSP31-1.png|700px]]<br />
<br />
====Configure Function====<br />
<br />
After version 2.3.5a there are two methods you can use to get the correct information into the Lambda code: A process where you simply click a link on the Setup Variables page, and a more manual method where you paste the authentication information from the Setup Variables page to the Lambda code.<br />
<br />
=====One-Step Method=====<br />
<br />
The one-step method is, by far, the easiest way to get the needed information to your Lambda code. Obtain the code for your configuration, follow these steps:<br />
<br />
* In the Ask Alexa Smartapp, click <<Settings>><<Setup Ask Alexa), then <<Setup Variables Link>> (see [[Ask_Alexa#Setup_Variables]]). Please note you should be using a desktop browser to do this.<br />
* Find the buttons to obtain the Lambda Full Code:<br />
<br />
[[File:LambdaCode.png|700px]]<br />
<br />
* Clicking this link will bring up the raw code, customized with your authentication information already embedded in it. Simply select all the text in the browser (typically Clt+A), then copy it (Ctl+C), then paste it into the proper location.<br />
<br />
[[File:AAAWSP4.png|700px]]<br />
<br />
*Save the code and you are done!<br />
<br />
=====Two-Step Method=====<br />
For those that want to do the installation manually...<br />
<br />
In this step you will need to supply the code with your unique Application ID and Access Token. The app will generate this for you either in your mobile device or via a desktop/laptop browser. See [[Ask_Alexa#Setup_Variables]] for more instructions to obtain this.<br />
<br />
* Obtain the code from From here:<br />
{| class="wikitable"<br />
|-<br />
! '''Ask Alexa Code''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Node.js''' || Lambda code for aws.amazon.com || ''1.3.1a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/Node.js<br />
|}<br />
<br />
*Paste the code here:<br />
<br />
[[File:AAAWSP4.png|700px]]<br />
<br />
*In the '''Ask Alexa''' Smartapp, click <<Settings>><<Setup Ask Alexa>> then <<Setup Variables>> (see [[Ask_Alexa#Setup_Variables]]). Please note you should be using a desktop browser to do this.<br />
<br />
*At the top of the HTML setup page that is generated, you will want to copy the first 3 lines below the title <<Lambda code variables>>.<br />
<br />
[[File:AAAAWSDev1.png]]<br />
<br />
'''Please Note'''<br />
While the web address (URL) to the SmartThings environment should remain constant, it could be different <br />
than what is displayed about depending on the country you reside in. In addition, this address is<br />
subject to change at any time. The '''Ask Alexa''' app uses the SmartThings API to generate this address<br />
when you run the setup page.<br />
<br />
If the app stops working suddenly, please ensure these parameters in your setup web page<br />
match the Lambda code you pasted when you set up this function.<br />
<br />
*Next, paste the lines between the two commented areas (breaks) at the top of the code area.<br />
<br />
[[File:AAAWSP10.png|700px]]<br />
<br />
Failure to copy these lines exactly will prevent the Lambda code from accessing your SmartThings environment. When you have completed copy (or any time you modify the Lambda code, be sure to click Save in the upper-left corner of the screen).<br />
<br />
'''Please Note'''<br />
Do not press the <<Test>> or <<Save and test>> buttons in the AWS Lambda area.<br />
Doing so will not cause any problems, but Lambda works on specifically formatted <br />
inputs and unless you supply these inputs exactly to the test it will always present <br />
you will an error. This error is not valid and this recommendation is simply <br />
made to avoid confusion when setting up the code.<br />
<br />
====ARN Code====<br />
<br />
* When everything is configured properly and saved, you will find in the '''upper right-hand corner''' of the screen an ARN. This is your Amazon Resource Name and will link your function with a corresponding Skill. It is recommended you copy this number or keep your screen open when you are creating the Skill in the developer area below.<br />
<br />
[[File:AAAWSP7.png]]<br />
<br />
===Developer Account (Primary Skill)===<br />
<br />
You will now need to define the primary skil using an Amazon developer account. Be sure you have followed the instructions from Amazon on setting up your developer account: [https://developer.amazon.com/appsandservices/community/post/Tx3U4BH5Y7JB35L/How-To-Create-a-Distribution-Portal-Account.html Developer Account].<br />
<br />
'''Please Note'''<br />
In order to easily test and use your new "skill" it is recommended that you create<br />
your developer account under the same account you used to set up your Alexa device.<br />
If you already have a developer account that is different than your Alexa device account, <br />
you must assign your physical device to the developer account and then associate <br />
your personal account as a "household" under your development account. More information<br />
on this process can be found [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/testing-an-alexa-skill#h2_register here].<br />
<br />
* To begin creating your skill, go to https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit and find the area on the right side labeled <<Start a Skill>>. You will be brought to a dashboard of your current skills. <br />
<br />
[[File:AADevP0.png|700px]]<br />
<br />
* On the Alexa Skills Kit Developer Console, click <<Create Skill>><br />
<br />
====Building The Skill====<br />
* The first page you will be presented with is the Skill Name. Typically, it is recommended to use '''Ask Alexa - SmartThings Integration'''<br />
<br />
* Next, you will be presented with a page with pre-built models' however, you will choose a <<Custom>> skill. Select this option, then click <<Create Skill>> in the upper-right corner of the page.<br />
<br />
[[File:AADevP0-1.png|701px]]<br />
<br />
* Here, you will be presented with options to build your skill. On the right side of the page you will have the various steps required to create your skill. These include Invocation Name, Intents, Samples, and Slots, Build Model, End Point. <br />
<br />
* To begin, click <<Invocation Name>><br />
<br />
[[File:AADevP0-2.png|701px]]<br />
<br />
* While the name can be anything you want, it is recommended to start off with 'smart things'. Other options include words like 'house', home, etc.<br />
<br />
'''Please Note''' <br />
The Invocation name should be typed in lower-case. If you like to use the word '''SmartThings'''<br />
as the invocation name, it is recommended you type 'smart things' (not 'smartthings'). <br />
Also note that the invocation name within your SmartApp (here: [[Ask_Alexa#Personalization]])<br />
should match this name. This is important if you use the [[Ask_Alexa#Single_Step_Interaction_Model]]<br />
to set up your Amazon developer area.<br />
<br />
* After you have entered your Invocation Name, click, <<Save Model>> at the top of the screen. Then click <<Custom>> on the left side of the screen.<br />
<br />
[[File:AADevP1.png|701px]]<br />
<br />
* You should now see your invocation name with a check mark next to it.<br />
<br />
* Next, on the Skills main page, find the <<JSON Editor>> on the left side<br />
<br />
=====JSON upload=====<br />
<br />
[[File:AADevP2.png|700px]]<br />
<br />
* Go back to your '''Ask Alexa''' SmartApp and run your <<Setup Variables>> again (see [[Ask_Alexa#Setup_Variables]])<br />
<br />
* Just like the Lambda code setup (see [[Ask_Alexa#One-Step_Method]]) you will click the link for the Developer Code (Second bold line).<br />
<br />
[[File:LambdaCode.png|700px]]<br />
<br />
* Alternatively, you have the option to download the Developer Code (JSON) as a text file. Please note the file name will have a timestamp on it and may be different than what is shown below. '''This is the recommended way of doing this INSTEAD of copying/pasting the JSON code.'''<br />
<br />
* Select all of the code from webpage, copy it, and then paste it into the Amazon Developer's page. If you chose to download the JSON text file, click the area as shown below, choose the file you downloaded, and click Open. After either (not both) of these steps, click <<Save Model>> in the upper-left corner of the page. Then click <<Build Model>>. Be sure to watch the upper-right corner of the screen to status messages, including any errors that may occur.<br />
<br />
[[File:AADevP3.png|700px]]<br />
<br />
Once the build is completed, click <<CUSTOM>> on the left side of the screen, you will now see steps 1, 2 and 3 on the right side with a green check mark. Click on <<4. Endpoint>><br />
<br />
[[File:AADevP4.png|700px]]<br />
<br />
* On the next step, you will enter the ARN number from the code from the AWS/Lambda area (See [[Ask_Alexa#ARN_Code]]). Place this code in the <<Default Region>> Area<br />
<br />
[[File:AADevP5.png|700px]]<br />
<br />
* Click <<Save Endpoints>> at the top of the screen. Next, click on <<Interfaces>> on the left side of the screen. Ensure your page looks like the screenshot below. Click <<Save Interfaces>> and <<Build Model>> at the top of the screen.<br />
<br />
[[File:AADevP6.png|700px]]<br />
<br />
* Click on Account Linking on the left side of the screen. Ensure the toggle switch is off.<br />
<br />
* The final step is to click <<Permissions>>. This will be set according to the screenshot below with all of the items toggled 'off'<br />
<br />
[[File:AADevP7.png|700px]]<br />
<br />
====Testing Your Skill====<br />
<br />
If you followed the directions properly, you should be ready to test your new skills.<br />
<br />
* Click <<Test>> at the top of the Skill Console.<br />
<br />
* Ensure the <<Test is enabled for this skill>>. While this implies that only testing is impacted, this slider actually disables the operation of your skill using your voice. This must be turned on.<br />
<br />
[[File:AASDev8.png|700px]]<br />
<br />
*As mentioned above, your Alexa Enabled Devices should be associated with your developer account. Please see here ([[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/testing-an-alexa-skill#h2_register]]) if you did not do this.<br />
<br />
*If properly set up, if you go to the <<Skills>> area of https://alexa.amazon.com or the Amazon Echo mobile app and refine the view to <<Your Skills>>, you should see your new '''Ask Alexa''' Skill.<br />
<br />
[[File:AASkill.png|350px]]<br />
<br />
* Start speaking to your Alexa Enabled Device. Start with "Alexa" (or your wake word), along with "ask" or "tell" along with the invocation word, followed by what you want to do.<br />
<br />
* Start with a simple switch (example: Living Room) and say <''"Alexa, ask SmartThings to turn on Living Room"''>. The Living Room should come on. If not, please check all of your settings. You may also visit the SmartThings Community for this app (https://community.smartthings.com/t/coming-soon-ask-alexa/46786) to ask community members (and sometimes the author) questions about this app. Finally, use the [[Ask_Alexa#Troubleshooting]] section for additional advice on how to troubleshoot your issues.<br />
<br />
* If your test goes well, try your other devices. In addition to the voice feedback, you should also also see 'cards' appear in your Echo mobile app to give you an indication of what the device is hearing and the responses it gave. <br />
<br />
[[File:AATestCard.png|350px]]<br />
<br />
* If you have difficulty, you may be able to troubleshoot the application yourself. The Amazon developer web site has tools to allow you to simulate your commands and show you what the responses are. Using this along with the SmartThings Live Logging should allow you to figure out where your issue is.<br />
<br />
* While on the Amazon Developer site, under the Test area, you can type your commands into this simulator to give you access to the skill. Be sure to type your invocation name when using the simualtor (i.e ''tell smart things version'' )<br />
<br />
[[File:AADevTest01.png|700px]]<br />
<br />
* JSON text will appear on the simulator boxes. The left side JSON is useful to see what was input, with right which includes the response from the SmartThings app and presented to the Echo device. <br />
<br />
'''Please Note'''<br />
In order for community members or the author to properly troubleshoot this application<br />
it will be important for you to produce screen shots of your environment. Please ensure<br />
you have provide screen shots of not only the development web site, but the Live Logging<br />
area of the SmartThings IDE so that issues can be quickly resolved.<br />
<br />
====Launch (Optional)====<br />
While optional, you can add icons to your application that will be visible in the Amazon Echo stand alone application on your mobile device, or at http://alexa.amazon.com. On the skills console page, click <<Launch>> at the top of the screen.<br />
<br />
[[File:AADev08.png|700px]]<br />
<br />
The recommended text is outlined below, but again, this is completely optional and is not needed for proper usage of the application or the integration with SmartThings. When you are completed. <br />
<br />
[[File:AAPublish.png|700px]]<br />
<br />
If you choose to use the supplied icons, their locations are listed here to download and use.<br />
{| class="wikitable"<br />
! Icon Size !! Location<br />
|-<br />
|'''108 x 108 icon''' || https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/AskAlexa108.png<br />
|-<br />
|'''512 x 512 icon''' || https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/AskAlexa512.png<br />
|}<br />
<br />
Click <<Save and Continue>> at the bottom. '''Please note that you should stop here''' with your skill. The next steps in the interface are for publishing the app for others to use....something you DON'T want to do unless you want the world to control your home.<br />
<br />
===Developer Account (Secondary Room Skill)===<br />
Coming Soon<br />
<br />
==Ask Alexa Usage==<br />
<br />
Assuming you kept your invocation name as ''"SmartThings"'', the usage of '''Ask Alexa''' is as simple as this: <''"Alexa, ask SmartThings to unlock the front door"''>. The invocation of ''"tell"'' or ''"ask"'' are required to activate the custom ASK Skill. However, they have no other context within the command. In other words, you can 'ask' or 'tell' Alexa the same command and she will respond exactly the same way.<br />
<br />
===Asking/Telling Alexa What To Do===<br />
<br />
Just like human language, the Alexa Enabled Devices will key off of nouns and verbs. The nouns are the device names (or aliases), modes, or routines you have set up in SmartThings. Verbs are the actions (or operations) you would like to carry out. However, just like human language (especially English), the rules are not hard and fast. It is recommended you try different combinations of syntax to get the results you desire. If you come up with a unique one, contact the author of this application so that the "intelligence" of the application can continue to grow.<br />
<br />
Please note that while most of the utterances begin with <''"Alexa, ask SmartThings..."''>, there are also other valid ways to address the '''Ask Alexa''' functions. For example, instead of saying <''"Alexa, ask SmartThings to turn off Dining Room"''>, you could say, <''"Alexa, turn off Dining Room with SmartThings"''>. If "asking" or "telling" Alexa something doesn't feel natural with the "SmartThings" invocation word at the beginning of your command, try another combination with putting <''"...with SmartThings"''> or <''"...using SmartThings"''> at the end of the command. Even "use" can be used (pun) to activate the skill (ex. <''"Alexa, use SmartThings set the Thermostat to auto mode"''><br />
<br />
*'''Switches/Dimmers/Colored Lights''': ''on'', ''off'', ''toggle'', ''status'', ''level'', ''color'', ''increase'', ''decrease'', ''rise'', ''lower'', ''up'', ''down'', ''maximum'', ''minimum'', ''low'', ''medium'', ''high''<br />
**<''"Alexa, tell SmartThings to turn on the living room"''><br />
**<''"Alexa, ask SmartThings to turn on the living room"''><br />
**<''"Alexa, ask SmartThings to increase the level of the living room"''> - Without a numeric settings, "increase" or "decrease" commands will be based on the values you set up in the <<Settings>> area.<br />
**<''"Alexa, tell SmartThings to lower the level of the Living Room by 5%"''> - You can specific the amount of the increase or decrease of the brightness level.<br />
**<''"Alexa, tell SmartThings to set the Media Room to Blue and 30%"''><br />
**<''"Alexa, tell SmartThings to set the Media Room to Red"''> The light will stay at the current level if not specified.<br />
**<''"Alexa, tell SmartThings to set the Bed Room to medium"''> - "Low", "medium" or "high" commands will be based on the values you set up in the <<Settings>> area.<br />
**<''"Alexa, ask SmartThings to set Lamp to maximum"''> - "Maximum" will set the dimmer to 100%.<br />
**<''"Alexa, tell SmartThings to set the Bed Room to medium and green"''> - You can also use two commands in unison as shown here.<br />
*'''Doors/Locks/Shades''': ''lock'', ''unlock'', ''open'', ''close'', ''status''<br />
**<''"Alexa, tell SmartThings to open the front door"''> - Please note that if front door is a connected lock, OPEN will NOT unlock the door. ''Open'' and ''Close'' are reserved for items that have motorized open/close mechanisms.<br />
**<''"Alexa, ask SmartThings to open the garage door password 1234"''> - assuming you chose 1234 as your PIN; see [[Ask_Alexa#Password_PIN]] for more information.<br />
**<''"Alexa, ask SmartThings the status of the garage door"''><br />
*'''Thermostats/Temperature/Humidity''': ''set'', ''status'', ''heat'', ''cool'', ''heating'', ''cooling'', ''mode'', ''off'' (for StelPro baseboard heaters, ''eco'' and ''comfort'' modes also available), ''home/away'' (For Nest Thermostats), ''get/repeat/replay/get/load/reload/restart/erase/delete/clear/reset tips'' (Ecobee Thermostats)<br />
**<''"Alexa, tell SmartThings to set the bedroom to 55 degrees"''> - It should be noted, depending on your thermostat, you may need to append the command with heating or cooling for multi-setpoint thermostats in auto mode.<br />
**<''"Alexa, tell SmartThings to set the bedroom heating to 55 degrees"''> - Same as above, but just sets the heating setpoint<br />
**<''"Alexa, ask SmartThings to turn on bedroom heating mode"''> - For thermostats that have separate heating/cooling/auto mode<br />
**<''"Alexa, ask SmartThings to turn off Bedroom"''> - In this context, when bedroom is a thermostat and NOT a switch, this will turn the thermostat off (from heating/cooling or auto mode)<br />
**<''"Alexa, tell SmartThings to lower the temperature of the living room by 5 degrees"''> - You can specific the amount of the increase or decrease of the temperature setpoint (the value will be based on the current temperature...not the current setpoint).<br />
**<''"Alexa, ask SmartThings to raise the temperature of the den"''> - If no value is given, an increase or decrease in temperature (based on current temperature) will default to the value in the <<Settings>> menu.<br />
**<''"Alexa, ask SmartThings set the Hallway to auto mode"''> - In this context, when hallway is a thermostat and NOT a switch, this will turn to auto mode. Auto mode will require you to set the temperature setpoints using the 'heating' or 'cooling' command.<br />
**<''"Alexa, ask SmartThings the status of the Back Patio"''> - in cases like this, it is better to ask the status of a device and not temperature specifically.<br />
*'''Other Sensors''': ''status''<br />
**<''"Alexa, ask SmartThings the Bathroom Floor status"''><br />
**<''"Alexa, ask SmartThings about Michael"''> - In this context, Michael is a presence sensor. You will receive a response of "present" or "not present".<br />
**<''"Alexa, ask SmartThings about Kitchen Sink"''> - Notice that just the noun can be used and the ''"status"'' is assumed in most cases.<br />
*'''Modes/Routines/SHM''': ''run'', ''execute'', ''status''<br />
**<''"Alexa, tell SmartThings to execute the Good Morning routine"''><br />
**<''"Alexa, ask SmartThings the status of the current mode"''><br />
**<''"Alexa, tell SmartThings good night"''> - Assuming you have a mode or routine called "Good Night", '''Ask Alexa''' will run this mode or routine (please note you must have unique names for modes and routines to use '''Ask Alexa''' properly).<br />
**<''"Alexa, mode status from SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings about security"''> - This is another way to ask about ''status'' of Smart Home Monitor.<br />
**<''"Alexa, tell SmartThings to set security to disarm"''> - please note for the Smart Home Monitor you can also use the noun ''"security"''<br />
*'''Voice/Weather Reports''': ''run''<br />
**<''"Alexa, use SmartThings to run the Nightly report"''> - Notice the word ''"use"'' to activate the skill.<br />
**<''"Alexa, Battery report from SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings for the weather"''> - assumes the name of the weather report is 'Weather'.<br />
*'''Macros''': ''run''<br />
**<''"Alexa, tell SmartThings to set the Media Room Group to 30%"''><br />
**<''"Alexa, tell SmartThings I am going to bed"''> - Please note the creative naming of the control group in this example (Name: "I am going to bed")<br />
*'''Message Queue''': ''play'', ''open'', ''delete'', ''clear'', ''erase'', ''status''<br />
**<''"Alexa, tell SmartThings to play messages"''> Without a queue referenced, the primary message queue will play back<br />
**<''"Alexa, tell SmartThings to open {queue name} queue"''><br />
**<''"Alexa, ask SmartThings to clear message queue"''> As above, without a queue referenced the action will happen on the primary message queue<br />
*'''Connected Speakers''': ''play'', ''pause'', ''stop'', ''mute'', ''unmute'', ''next track'', ''previous track'', ''status'' <br />
**<''"Alexa, ask SmartThings to play Bedroom Speaker"''><br />
**<''"Alexa, tell SmartThings to mute Living Room"''><br />
**<''"Alexa, tell SmartThings to increase the volume of the Office"''> - When no value is given, the increase or decrease will default to the value you set up in the <<Settings>> area.<br />
**<''"Alexa, ask SmartThings about the Guest Room Speaker status"''> - Please note below about querying the status of Sonos speakers<br />
<br />
'''Notice'''<br />
The Sonos integration within SmartThings is currently in listed as a "Labs" .<br />
release. This means certain functionality is subject to change or may not work as<br />
expected. For example, if you manually play the Sonos and then ask Alexa about the <br />
status of the speaker, she may say the speaker is stopped. This is because the Alexa <br />
Enabled Device is pulling the status of the speaker from SmartThings, not the speaker itself. <br />
So, there is typically a 1 to 5 minute delay before SmartThings refreshes the speaker<br />
status. However, commands that YOU issue to the Sonos device are activated immediately.<br />
<br />
*'''Schedules''': ''on'', ''off'', ''status''<br />
**<''"Alexa, ask SmartThings about Doctor's appointment"''><br />
**<''"Alexa, tell SmartThings to turn off Golf Lesson"''><br />
<br />
===Ask Alexa Help/List Commands===<br />
<br />
Obviously, the main purpose of an application like '''Ask Alexa''' is to NOT grab your phone everytime you want to make turn on a light or turn up the speaker. However, humans are visual creatures so it is sometimes difficult to remember the specific name of a device you have included to interface with enabled device without some sort of reminder. '''Ask Alexa''' has a basic help function to guide you through which devices, modes or routine commands you can use. <br />
<br />
Please note that having Alexa call out every device and operation can be time consuming to listen to. If you need her to stop speaking, simply say <''"Alexa, stop!"''>.<br />
<br />
*'''Basic help'''<br />
**<''"Alexa, ask SmartThings for help"''> - This is just an overview of the application usage. At the very end you can confirm what version number of the Lambda code you have running.<br />
<br />
*'''Lists''' - simply issuing a 'List' command and the type of device/operation you want help on will issue a list of what is interfaced with '''Ask Alexa'''.<br />
**<''"Alexa, list switches in SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings to list switches"''><br />
**<''"Alexa, tell SmartThings to list modes"''><br />
**<''"Alexa, ask SmartThings switch list"''><br />
**<''"Alexa, ask SmartThings about the control macros"''><br />
**<''"Alexa, ask SmartThings to list humidity sensors"''><br />
**<''"Alexa, ask SmartThings about the reports"''><br />
**<''"Alexa, ask SmartThings about SHM"''><br />
**<''"Alexa, ask SmartThings about the dimmers"''> - Notice that when asking about a key word noun (dimmer, switches, etc) you can leave off the ''list''.<br />
**<''"Alexa, ask SmartThings to list the colors"''> - This option is available if you have colored lights listed within the '''Ask Alexa''' SmartApp on your mobile device. Please note that the colors list is generated from SmartThings and is quite extensive. It would take over a minute to list the colors, so instead you will be referred to the '''Ask Alexa''' cheat sheet for the full color list.<br />
**<''"Alexa, ask SmartThings to list the colored lights"''> - Please note that this is different the command above. This will give you the list of available colored lights available to control.<br />
<br />
*'''Version'''-You can get the version number of the various pieces of '''Ask Alexa'''<br />
**<''"Alexa, version of SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings about Ask Alexa"''><br />
**<''"Alexa, ask SmartThings about the SmartApp"''><br />
**<''"Alexa, ask SmartThings about versions"''><br />
<br />
*'''Repeat'''- You can request the last thing '''Ask Alexa''' said to you (no action is done, just repeat the last results)<br />
**<''"Alexa, tell SmartThings to repeat"''> <br />
**<''"Alexa, ask SmartThings again"''><br />
**<''"Alexa, ask SmartThings to replay"''><br />
<br />
<br />
There is also a special 'list' that can be retrieved from Device Group Macros (Macros that control groups of similar devices, like switches) and Macro Groups (A macro that runs groups of other macros). Examples include:<br />
*<''"Alexa, tell SmartThings to list HouseMacros"''> - In this context, "HouseSwitches" is a macro groups with child macros included. This command will list the child macros controlled by this group macro<br />
*<''"Alexa, tell SmartThings to list HouseSwtiches devices"''> - "HouseSwitches" is a device group macro. This command will list the devices controlled by this macro<br />
<br />
==Use Cases==<br />
Below are some examples of use cases on how you can use '''Ask Alexa''' to its full advantage.<br />
===Natural Language Responses===<br />
Using a control macro, you can simulate a little bit of intelligence using '''Ask Alexa'''. For example, if you have a room with a few dimmers you could set up a couple of macros called "It is too bright" and "It is too dark". In each of these macros you would set up the dimmers (SmartThings Devices Area) you want to change, and put a default increase/decrease in the provided area. At the bottom of each page you could put in a custom response such as "I have increased the brightness for you". Then, when you say <''"Alexa, tell SmartThings it is too bright"''> or <''"Alexa, tell SmartThings it is too dark"''> and it will increase or decrease the lighting as you requested. Using macro aliases you could use different versions of the phrasing and react accordingly without creating multiple macros for the same action. Future version of '''Ask Alexa''' will allow this type of control for more devices (such as thermostats).<br />
<br />
===Good Night Weekdays/Weekends (Invocation)=== <br />
Using the control, WebCoRE Trigger or voice report restrictions, you can use a single voice command to have multiple outcomes. For example, let’s say you set a different mode on the weekdays than on the weekends when you go to bed. To accomplish this you could set up two control macros; within the first macro you restrict it to run Sunday through Thursday and sets a mode called "Wake up on", and the second only runs on Friday and Saturday and sets a mode called "Wake up off". You would then create a extension group called "Good Night" which includes the first two control macros (no specific order is needed). Each night you could say <''"Alexa, tell SmartThings Good Night">.'' This would allow the same command to be issued nightly but behave differently depending on the day of the week. In the morning, a program such as [http://thingsthataresmart.wiki/index.php?title=Talking_Alarm_Clock Talking Alarm Clock] could key off of the Alarm on/Alarm off modes and react accordingly. If you are using restrictions as part of a extension group you should also click the <<Mute Restriction Messages In Extension Group>> (in the individual macros) to eliminate unwanted restriction warnings within the running of the macros.<br />
<br />
[[File:AHResitrictions.png|250px]]<br />
<br />
===Good Night Weekdays/Weekends (Native, Non-Invocation)===<br />
Similarly to the process above, you can use the native Alexa Routines, along with '''Ask Alexa''', to accomplish the same results without having to utilize the skill directly. The steps are similar to above:<br />
First, just like above, you set up two control macros with the similar weekday/weekend restrictions. You will also create the same extension group which includes these control macros. The difference here is that you will create a virtual momentary switch (using an app like Alexa Virtual Switch Creator [http://thingsthataresmart.wiki/index.php?title=Alexa_Virtual_Switch_Creator]). In this example, the switch is named "Good Night Trigger". Going back to the extension group, you enter this virtual switch in the area labled "Switch trigger for this macro". <br />
<br />
[[File:AAGoodNight.png|250px]]<br />
<br />
In your Native Alexa App, you will then create a routine called "Good Night". You can add a weather report or any other function you'd like, but the most important piece is to include turning the "Good Night Trigger" switch on. Saving the routine and simply saying <''"Alexa, Good Night"''> will set the mode to the correct setting based on the day. <br />
<br />
[[File:AlexaRoutine1.png|250px]]<br />
<br />
Please note that any output you included in the macros or extension group WILL NOT play on Alexa. You can use a message queue and an external speaker to play any output you desire.<br />
<br />
===Weather Reports and Advisories===<br />
Full weather advisories can be lengthy, and if you include them with EVERY other possible weather message (temp, location, lunar, etc.) you are almost guaranteed to exceed the default Lambda timeout (3 secs), and you'll probably exceed even a 10 second timeout if there are multiple alerts for your area. Because of this, you will need to extend your timeouts (if you want to receive the exhaustive Weather Report). Please see below for extending the timeouts. Another solution is to break your Weather Report into 2 separate reports. The first (maybe called "Weather Report") should have everything you want enabled EXCEPT the Full Weather Advisory - you'll get a notice telling you there are one or more Advisories, but not the advisory text. And the second (called "Weather Advisories") has only the temperatures, the <<Full Weather Advisories>>, and the <<Speak Location>> enabled. So, when you run your ''Weather Report'' you will hear there are advisories, and then when the report is done, you can ask Alexa to run the ''Weather Advisories'' report.<br />
<br />
Future versions of '''Ask Alexa''' will allow you to schedule a periodic check of advisories and actually push them to the message queue, which would allow for visual and audio notifications.<br />
<br />
===Basic Control Of Two Homes===<br />
By virtue of how SmartThings and Amazon implement security with their devices, you can typically only control one home's SmartThings devices with the Alexa Enabled Devices in that home. However, you can actually control devices in two different locations using a single Alexa device in each home. This use case assumes you have two SmartThings accounts (or locations) set up.<br />
<br />
To accomplish this, you first need to identify what you want to do at the remote location. This could be simply activating a switch, etc. For simplicity sake, let's use "Home A" and "Home B" as the homes you are working with, with devices, modes or routines listed as "Device A", "Mode A", "Routine A" etc for Home A, and "Device B", "Mode B", "Routine B", etc for Home B. Using this terminology, let's assume you want to control a routine in Home B from Home A's Alexa Device. Using Home B's Ask Alexa implementation you would set up a Control macro that runs Routine B, then obtain the REST endpoint of the macro in Home B you want to run (see below). Next, in Home A's '''Ask Alexa''' SmartApp, you will set up a Control Macro that includes the REST URL in the <<Run this HTTP request...>> section. Then when this Control Macro is run from Home A, Home B's devices will react. There is currently no way to currently gather status feedback from one home to another, however.<br />
<br />
[[File:ControlMacroURL.png|250px]]<br />
<br />
===Multi-Room Controls (Advanced)===<br />
'''Please Note'''<br />
This process requires a bit more effort to accomplish than a normal install.<br />
It is recommended you become familiar with the full home control before you<br />
attempt to do a multi-room install.<br />
<br />
This install does have caveats; message queues still operate, but sending apps<br />
may be confused with multiple rooms set up.<br />
<br />
Use the multi-room setup with careful consideration on the benefits vs the<br />
drawbacks.<br />
<br />
While most users will desire to control their entire home with one invocation name (typically "SmartThings" or "Home"), '''Ask Alexa''' has the ability, with a bit of work, to have a multi-room setup. Consider the following use case:<br />
<br />
You have a large home and routinely have guests over. You want the guest, when in their room, to be able to control the devices within that room without controlling the other rooms or controls in the house. While this is possible in a single-room setup using aliases and macros, this might become confusing. And, this wouldn't prevent the users in that room to do a device or command list and finding out the names of the other devices around the house.<br />
<br />
Instead, the guest in their room could say, <''"Alexa, turn off the lights in this room"''> and the lights in that specific room would go off. If they request a list of devices or commands, only the devices you set up in that room will only be listed. <br />
<br />
To accomplish this, you will need to do the following:<br />
<br />
* For each "room" you will need to have a separate app for that room<br />
** You will need to change the line in the '''Ask Alexa ''' IDE from "singleInstance: true," to "singleInstance: false," (this is currently line 26 in version 2.2.2)<br />
[[file:AAIDEAdv1.png|700px]]<br />
** You will load up another version of '''Ask Alexa ''' from the SmartThings Marketplace. It is recommended that you change the display name under Settings>>SmartApp Name to "Ask Alexa {room name}. Be sure to use the example name in the invocation name example (<<Settings><<Setup Ask Alexa>><<Invocation Name>>) to the name you set up for the room as the skill name.<br />
[[file:AANameAdv1.png|250px]] [[file:AASetup.png|250px]]<br />
* For each "room" you will need to create a separate Lambda function<br />
** For each instance of your SmartApp, you will need to associate the Oauth and Token with your Lambda code.<br />
[[File:AAAWSP10.png|700px]]<br />
** Each Lambda section will have its own unique Oauth and Token from the individual app<br />
* For each "room" you will need to create a separate skill.<br />
** You will name the invocation name the name of the room (placing, for example "this room" where "smart things" is below)<br />
[[file:AADevP1.png|701px]]<br />
**Each skill will require the ARN number from the associated Lambda function<br />
<br />
==Tips and Tricks==<br />
<br />
* The naming of your devices is extremely important for proper usage of '''Ask Alexa'''. If you have two devices named "Living Room" for example, if you ask to turn on that switch and a temperature monitor is also named that same thing, you may not get the results you desire. It is good practice to choose devices to use with '''Ask Alexa''' that have unique names. This also goes for the "labels" of the devices...you may not have empty (null) labels for any of the devices or the SmartApp will crash.<br />
* If you change any settings within you app (add/remove devices to the SmartApp, add/change modes or routines), you will need to get the proper "intents" and paste those into the Amazon Developer Site. See [[Ask_Alexa#Custom_Slot_Information]] for more information. <br />
* The longer your modes or routines are in length, the more likely Alexa will misunderstand what you are asking. Amazon recommends commands of less than three words or syllables.<br />
* By default, SmartThings adds exclamations points to is routines (for example, ''"Good Morning!"'') . While the '''Ask Alexa''' SmartApp attempts to reconcile this when evaluating what the Alexa hears, it is best practice to remove punctuation from your routines or modes.<br />
* Try speaking different ways to Alexa to get the results you want. For example, if you'd rather say the device action first, just append "using SmartThings" at the end to get the same result. For example, instead of <''"Alexa, ask SmartThings to turn on the living room"''> you could say <''"Alexa, turn on living room with SmartThings"''>. Please note that sometimes this doesn't work well depending on what you named the device or how the Alexa Enabled Device hears your commands. However, it is important to be creative in how you address Alexa. If you find that natural speech doesn't work and have a suggestion for another syntax for different types of devices, please contact the author of this app to have additional utterances created.<br />
<br />
==Troubleshooting==<br />
The following are common troubleshooting steps when working with '''Ask Alexa'''.<br />
<br />
* If you use 'smartthings' (one word) as you invocation for the skill and you find Alexa misunderstanding you and not initiating the skill, change the invocation word to 'smart things' (two words) as some users have found this to work considerably better.<br />
* There have been reports that sometimes the URL for the Setup Variables presented in the live logging will not show completely, with a portion of it being replaced with [TRUNCATED]. This is an issue with the SmartThings environment. If you encounter this, within your mobile device scroll down on the Setup Variables page. You will find the full address of the setup page. Copy this and send it (possibly via e-mail) to yourself so you can perform the setup actions using a desktop computer.<br />
[[File:AASetupURL.png|250px]]<br />
* If you see an error similar to below about a mode or routine being missing, this indicates you may have deleted one of these before removing it from '''Ask Alexa'''. To prevent issues, the list will be updated to indicate which modes or routines you need to remove from the list for proper operation. You may also see this situation when you delete an Echo device association with a room. The list presented will mark the missing device, and it should be removed from the list to ensure proper '''Ask Alexa''' operation.<br />
[[File:AAMissingMode.png|250px]]<br />
* If you can use the Amazon Developer simulator with Ask Alexa, but you get an error with the exact same command with voice, check your country selection in both the app and the developer's site. These should match and only US is supported (However, it appears UK DOES work).<br />
* When the application does not operate correctly or as you would expect, please check http://status.smartthings.com/ to ensure the SmartThings environment is working properly. If the SmartApp suddenly stops working, most of the time it is because of an outage or degraded service with SmartThings' cloud environment. Since '''Ask Alexa''' is also heavily based in the Amazon cloud environment, it is also recommended to check the status of those sites as well via http://status.aws.amazon.com/<br />
* There is a known issue where, after editing a macro, the application returns to the main SmartThings app instead of the '''Ask Alexa''' main interface. SmartThings is aware of this and is working on a resolution. This message will be removed when this issues is resolved.<br />
* Removal and renaming of internal SmartThings items (like modes and routines) or changing internal components to '''Ask Alexa''' (such as deleting macros, or renaming extensions) is not well supported in SmartThings. For example, if you have a SmartThings mode that is used in '''Ask Alexa''', deleting this from the SmartThings app BEFORE removing it from '''Ask Alexa''' could result in '''Ask Alexa''' getting confused and giving you an error is the GUI or during operation. Another observed behavior is when you have a weather report within voice report. If you plan to delete the weather report, you should remove it from all areas of the app before deleting it.<br />
* While it is expected that you can upgrade to new versions seamlessly, there are situations where internal variables within the code changes or an old scenario conflicts with new code revisions. If you upgrade and find the application no longer performs as expected, it is recommended that you remove the application completely and start from scratch with new code (this only applies to the code in SmartThings. The Lambda code and Skills data should not be affected by variables unless you change your devices).<br />
* If you receive an error in the app while working with routines, macros and devices, please be sure these items do not have commas, exclamation points, or apostrophes in them. Also, numeric values (1, 2, 3, etc) should be left out in most circumstances from devices and macros. In addition, ensure you have not inadvertently created a 'null' routine...this is a routine you may have attempted to create but abandoned. These will show up in your SmartThings IDE under you Installed SmartApps. If this happens, simply delete the routine via the IDE (<<My Locations>>, <<List SmartApps>>) by tapping <<Edit>> in the upper left corner and the <<Update>> commands will turn into <<Delete>>.<br />
<br />
[[File:AAInstalledSA.png|700px]]<br />
<br />
* When naming your macros, routines, aliases, devices or modes, ensure you don't use words that might sound the same but could be spelled differently. For example, "Kris", "Bryan", "Jon" could be heard as "Chris", "Brian" and "John", respectively. Unfortunately, while sounding the same, the app does not account for different spellings of these types of names. Therefore, it is recommended you stay away from words like this. If you must use these, it is recommended that you set up aliases with different spellings of the same name.<br />
* When making a change to your environment (add/remove devices/aliases, create new modes, etc.) you should go through the setup steps again to capture any new custom slot information. This is required so '''Ask Alexa''' and the Amazon developer site knows the 'nouns' and 'verbs' to use to process your requests.<br />
* As mentioned in the [[Ask_Alexa#Tips_and_Tricks]] section, naming (labels) of your devices are rather important. In addition, even if you name everything uniquely, there are still areas where Alexa will respond with ''"You have multiple devices that are named <device name> in your SmartThings SmartApp. Please rename these items to something unique so I may properly utlize them."''. This could be caused by you choosing the same device for different functions. For example, you can choose a thermostat (Let's say "office") and also choose it for your temperature reading or humidity sensor. This will cause an issue as Alexa has no way of understanding the context of a device that is listed multiple times. It is best practice to not only name you devices uniquely, but use them once within your device setup. For situations where you can't name devices differently, you can use the alias function(see [[Ask_Alexa#Allow_Device_Aliases]]) to utilize different names for the devices in your SmartThings account.<br />
* If you receive an error similar to this when attempting to add a new extension (like a message queue):<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the extension code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
* If you receive feedback that SmartThing SmartApp returned an error, but you see nothing in your IDE Live Logging, you may have an issue with your Application ID or Authentication token. Re-run the setup to get the proper information into your Lambda code. (See [[Ask_Alexa#Finalizing_The_Function_Code]])<br />
* If you are unable to find the Alexa Skill Kit when setting up the Event Triggers ([[Ask_Alexa#Configure_Triggers]]), be sure you have set up your account in one of the supported datacenters (i.e US East (N Virginia), US West (Oregon), etc (see [[Ask_Alexa#AWS.2FLamba_Code]])<br />
* If you find behavior that is not what you would expect from your devices, try changing your syntax of how you are referencing the device. For example, instead of <''"Alexa, tell SmartThings to turn on the Kitchen"''> try a simplistic version such as <''"Alexa, tell SmartThings Kitchen on"''>. If you find a specific syntax works better for you but is not being recognized, you may want to create (or ask for community assistance) a custom utterance for your situation. If it works well for you, you can submit that to the author of '''Ask Alexa''' for inclusion in future updates.<br />
* If you have a custom message (or a pre or post message within the voice report macro) it is recommended to use proper punctuation. This means to end the message with a period, question mark, or exclamation point. This will ensure Alexa pauses if you have a continuing message at the end of your macros.<br />
* While the Lambda accounts are "free" for the most part, you should monitor your usage as much as you can to ensure you know the volume of calls being made to your account. Amazon has some fantastic tools to accomplish this via the main dashboard of your AWS account. The dashboard can also be useful in troubleshooting errors within your application.<br />
<br />
[[file:AAAWSOpen.jpg|700px]]<br />
* If you get the error "There was an error with the requested skills response" from Alexa but the action still happens, what may be happening is that the response was taking too long to get back from SmartThings to the Amazon Lambda code. To help reduce these errors, go to your Lambda code at [https://aws.amazon.com Amazon AWS site] and find section toward the bottom of the page labeled <<Basic Settings>>.Change the <<Timeout>> section to a larger number (6 to 20 seconds should be more than enough time). You can also increase the amount of memory that your Lambda code uses. This MAY result in slightly faster response from the '''Ask Alexa''' skill; however, increasing the timing or memory too much could result in a monthly charge from Amazon. If you do increase these settings, be sure to monitor your usage closely through the Amazon tools. <br />
<br />
[[File:AATimeout.png|700px]]<br />
* '''Ask Alexa''' keys off the labels of the devices; these are what you use to address the device. If these labels are not unique or used multiple time within the SmartApp you will receive a warning at the top of the main interface page.<br />
<br />
[[File:AAWarning.png|250px]]<br />
<br />
To fix a multiple device issue, be sure to examine all of the main interface devices to ensure they are not used more than once. For example, a dimmer can also be a switch, and a motion sensor may also show up in a temperature listing. <br />
<br />
For null device labels, be sure to check the device within the IDE area <<My Devices>> to ensure the label is not blank.<br />
<br />
==Support==<br />
To obtain support for this app, you have a couple of options:<br />
<br />
* A Slack channel has been set up at https://askalexa.slack.com . You must be invited to this app and have a Slack account. This will allow real time conversation and troubleshooting with the developer to get to the bottom of any issues you might be having.<br />
* For general questions about the app, please visit the official forum for this app on the SmartThings Community Page: https://community.smartthings.com/t/release-ask-alexa/46786/<br />
<br />
==Roadmap==<br />
There are many things that can be added to this application. Be sure the visit the forum for this app (See above) for this app to request something be added to the road map. In addition, donations will help speed up development of new features. You can donate via this page: https://paypal.me/mstruck . <br />
Please note that these are only proposed updates...There is currently no timeline to implement these, or any guarantee that they will be implemented at all.<br />
<br />
* % control for window shades<br />
* Continue to improve the setup process (started in 2.3.5a)<br />
* Restrictions based on which speaker is being spoken to (2.3.9)<br />
<br />
==Frequently Asked Questions (FAQs)==<br />
'''Question''': Why do I have to update the Developer JSON every time I change something in my app?<br />
<br />
'''Answer''': The framework of the app allows for great voice recognition as only items that you set up in your SmartApp are being scanned for. Technically, you could simply have every device in your environment from the beginnig. However, that increases the chance of a misunderstanding by Alexa. <br />
<br />
'''Question''': What colors does '''Ask Alexa''' support?<br />
<br />
'''Answer''': '''Ask Alexa''' supports all of the same colors supported by native SmartThings app:<br />
Soft White, Warm White, Daylight White, Cool White, White, Alice Blue, Antique White, Aqua, Aquamarine, Azure, Beige, Bisque, Blanched Almond, Blue, Blue Violet, Brown, Burly Wood, Cadet Blue, Chartreuse, Chocolate, Coral, Corn Flower Blue, Corn Silk, Crimson, Cyan, Dark Blue, Dark Cyan, Dark Golden Rod, Dark Gray, Dark Green, Dark Khaki, Dark Magenta, Dark Olive Green, Dark Orange, Dark Orchid, Dark Red, Dark Salmon, Dark Sea Green, Dark Slate Blue, Dark Slate Gray, Dark Turquoise, Dark Violet, Deep Pink, Deep Sky Blue, Dim Gray, Dodger Blue, Fire Brick, Floral White, Forest Green, Fuchsia, Gainsboro, Ghost White, Gold, Golden Rod, Gray, Green, Green Yellow, Honeydew, Hot Pink, Indian Red, Indigo, Ivory, Khaki, Lavender, Lavender Blush, Lawn Green, Lemon Chiffon, Light Blue, Light Coral, Light Cyan, Light Golden Rod Yellow, Light Gray, Light Green, Light Pink, Light Salmon, Light Sea Green, Light Sky Blue, Light Slate Gray, Light Steel Blue, Light Yellow, Lime, Lime Green, Linen, Maroon, Medium Aquamarine, Medium Blue, Medium Orchid, Medium Purple, Medium Sea Green, Medium Slate Blue, Medium Spring Green, Medium Turquoise, Medium Violet Red, Midnight Blue, Mint Cream, Misty Rose, Moccasin, Navajo White, Navy, Old Lace, Olive, Olive Drab, Orange, Orange Red, Orchid, Pale Golden Rod, Pale Green, Pale Turquoise, Pale Violet Red, Papaya Whip, Peach Puff, Peru, Pink, Plum, Powder Blue, Purple, Red, Rosy Brown, Royal Blue, Saddle Brown, Salmon, Sandy Brown, Sea Green, Sea Shell, Sienna, Silver, Sky Blue, Slate Blue, Slate Gray, Snow, Spring Green, Steel Blue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White Smoke, Yellow and Yellow Green<br />
<br />
==How Do I Upgrade Ask Alexa==<br />
There are 3 different scenarios for upgrading '''Ask Alexa'''; each depends on what was changed in the release. Please refer to the release notes to determine which scenario applies to your situation. For a scenario 2 and 3 upgrade, you should be familiar with the installation processes for the Amazon sites listed here: [[Ask_Alexa#Developer_and_Lambda_Code_Installation]]<br />
<br />
'''Scenario 1 - IDE code change:''' Only the code (either main code, or extension code) has changed. If you have your IDE linked to GitHub (see: [[Ask_Alexa#Advanced_Installation]]), then you simply click the <<Update from Repo>> button at the top of the SmartThings IDE and check the apps that you want to update. Be sure to <<Save>> the files and <<Publish>> them in order to see the changes in your SmartThings mobile application.<br />
<br />
In addition, in a Scenario 1 installation you can also upgrade the applications using the Community Installer (Free Marketplace). See here for more information: [[Community_Installer_(Free_Marketplace)]]<br />
<br />
'''Scenario 2 - Lambda code change:''' It is rare that JUST the Lambda code will change. Sometime you must use the processes in Scenario 1 and this process to get the full upgrade. There are two ways to upgrade your Lambda code. Both require you to go to <<Settings>> <<Setup Variables>> and get your setup URL. <br />
* While displaying the setup variables on a PC, you will simply click the Lambda code link. You will be presented with code on the screen with your security parameters already in the code. You simply copy this code to https://aws.amazon.com and you are done. <br />
* For a more manual method, go into the AWS site and copy the current Token and Application ID from the current code. Copy the new code from this location (https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/Node.js) and paste it into the code area. Then paste the Token and Application ID back into the appropriate location.<br />
<br />
[[File:AAAWSP10.png|700px]]<br />
<br />
'''Scenario 3 - Developer area changes:''' The easiest method of upgrading is to go to <<Settings>><<Setup Ask Alexa>><<Display Setup Variables Link>> and get your setup URL. While displaying this on a PC, you will simply click the Developer code link (or download the code). If you display the code, copy the entire page of JSON code and then paste it to the <<JSON Editor>> section of the Developer Build section. <br />
<br />
[[File:AADevP2.png|701px]]<br />
<br />
If you downloaded the code, simply upload the code to the site. <br />
<br />
[[File:AADevP3.png|701px]]<br />
<br />
Save and build your interaction model and you are complete.</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=15171GE Z-Wave Motion Sensor Dimmer Switch2020-09-16T16:14:45Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 9/16/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.9<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room if you have the Occupancy mode set and turn off based on the timeout duration. || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=15170GE Z-Wave Motion Sensor Dimmer Switch2020-09-16T16:14:32Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.9<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room if you have the Occupancy mode set and turn off based on the timeout duration. || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=15169GE Z-Wave Motion Sensor Switch2020-09-16T16:13:49Z<p>MichaelStruck: /* Summary */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 9/16/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.9<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room if you have the Occupancy mode set and turn off based on the timeout duration. || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Switch#SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=15044GE Z-Wave Motion Sensor Dimmer Switch2020-07-18T22:31:08Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room if you have the Occupancy mode set and turn off based on the timeout duration. || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=15043GE Z-Wave Motion Sensor Switch2020-07-18T22:30:14Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room if you have the Occupancy mode set and turn off based on the timeout duration. || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Switch#SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=15042GE Z-Wave Motion Sensor Dimmer Switch2020-07-18T22:28:27Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room if you have the Occupancy mode set. || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=15041GE Z-Wave Motion Sensor Switch2020-07-18T22:21:22Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room...it just will not time out and will NOT shut itself down. || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Switch#SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=15040GE Z-Wave Motion Sensor Dimmer Switch2020-07-18T22:20:25Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable thi or chose a time between 10 seconds to 27 minutes. The default is 20 seconds. ''Please Note:'' If this parameter is disabled, the motion detection sent to SmartThings is effectively disabled. However, the light WILL come on if you enter a room...it just will not time out and will NOT shut itself down. || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14985GE Z-Wave Motion Sensor Dimmer Switch2020-06-05T15:17:58Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14984GE Z-Wave Motion Sensor Switch2020-06-05T15:17:36Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 6/5/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Switch#SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14983GE Z-Wave Motion Sensor Switch2020-06-05T15:17:24Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.8<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Switch#SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14980GE Z-Wave Motion Sensor Switch2020-06-04T20:44:56Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Switch#SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14979GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:44:22Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14978GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:44:05Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section:<br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_SwitchSmartThings_App_Notice]]<br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14977GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:43:28Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section [SmartThings_App_Notice] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14976GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:43:07Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section [[SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14975GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:42:21Z<p>MichaelStruck: /* Interface */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices (on the SmartThings "Legacy" application), but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14974GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:41:41Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. Please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14973GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:40:52Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.<br />
|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14972GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:36:11Z<p>MichaelStruck: /* Summary */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14971GE Z-Wave Motion Sensor Switch2020-06-04T20:35:46Z<p>MichaelStruck: /* Summary */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing) @Nathancu (Interface, functionality and Samsung Application Compatibility), @panchy345 (button capability testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14970GE Z-Wave Motion Sensor Switch2020-06-04T20:26:56Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14969GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:26:17Z<p>MichaelStruck: /* Dashboard */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section <br />
[[GE_Z-Wave_Motion_Sensor_Dimmer_Switch##SmartThings_App_Notice]] <br />
the dashboard is only visible within the "Legacy" SmartThings <br />
application. While the settings will apply to the device and<br />
should function properly, there is currently no way to display <br />
the devices' dashboard or any custom notifications within the <br />
newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14968GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:24:57Z<p>MichaelStruck: /* Interface */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
'''SmartThing Version Notification'''<br />
As stated in the section [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#SmartThings App Version]] the <br />
dashboard is only visible within the "Legacy" SmartThings application. <br />
While the settings will apply to the device and<br />
should function properly, there is currently no<br />
way to display the dashboard or any custom notifcations<br />
within the newer "Samsung" SmartThings application.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14967GE Z-Wave Motion Sensor Dimmer Switch2020-06-04T20:20:47Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the use of this device type handler (DTH) in the SmartThings "Legacy" application. An attempt has been made in this document to give specific example of the use of this DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14966GE Z-Wave Motion Sensor Switch2020-06-04T20:18:53Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
===SmartThings App Notice===<br />
The instructions listed here, unless otherwise noted, apply to the SmartThings "Legacy" application. An attempt has been made in this document to give example of behavior of the DTH in both the Legacy application and the newer "Samsung" SmartThings application. However, it should be noted that while there is functional parity of the GE devices with this DTH, GUI interface differences are present.<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14965GE Z-Wave Motion Sensor Dimmer Switch2020-06-01T17:42:18Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. <br />
'''Please Note''' If you keep this setting at 0, automations that turn on the <br />
light while in Occupancy and Vacancy mode may not properly register on and off <br />
status within the GUI. It is recommended that if you use any automations with <br />
the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14964GE Z-Wave Motion Sensor Dimmer Switch2020-06-01T17:40:51Z<p>MichaelStruck: /* Default Level */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. '''Please Note''' If you keep this setting at 0, automations that turn on the light while in Occupancy and Vacancy mode may not properly register on and off status within the GUI. It is recommended that if you use any automations with the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), <br />
external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights <br />
while in Occupancy and Vacancy modes may not properly register on and off status within <br />
the GUI. It is recommended that if you use any automations with the dimmer that you set<br />
this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14960GE Z-Wave Motion Sensor Dimmer Switch2020-05-29T23:01:57Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. '''Please Note''' If you keep this setting at 0, automations that turn on the light while in Occupancy and Vacancy mode may not properly register on and off status within the GUI. It is recommended that if you use any automations with the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights while in Occupancy and Vacancy modes may not properly register on and off status within the GUI. It is recommended that if you use any automations with the dimmer that you set this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14959GE Z-Wave Motion Sensor Switch2020-05-29T23:01:23Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/29/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.7<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14958GE Z-Wave Motion Sensor Dimmer Switch2020-05-28T03:45:53Z<p>MichaelStruck: /* Default Level */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 2/11/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.6a<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. '''Please Note''' If you keep this setting at 0, automations that turn on the light while in Occupancy and Vacancy mode may not properly register on and off status within the GUI. It is recommended that if you use any automations with the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
'''Please Note''' If you set this to 0 (either programmatically or through the settings), external automations (WebCore, SmartThings Smart Lighting, etc) that activate the lights while in Occupancy and Vacancy modes may not properly register on and off status within the GUI. It is recommended that if you use any automations with the dimmer that you set this number to greater than 0.<br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14957GE Z-Wave Motion Sensor Dimmer Switch2020-05-28T03:27:25Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 2/11/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.6a<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed. '''Please Note''' If you keep this setting at 0, automations that turn on the light while in Occupancy and Vacancy mode may not properly register on and off status within the GUI. It is recommended that if you use any automations with the dimmer that you set this number to greater than 0.|| Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=14943GE Z-Wave Motion Sensor Switch2020-05-22T15:39:27Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 5/22/20):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.6<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14737GE Z-Wave Motion Sensor Dimmer Switch2020-02-11T20:37:36Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 2/11/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.6a<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed || Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14736GE Z-Wave Motion Sensor Dimmer Switch2020-02-11T20:21:46Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 2/11/20):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.6<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed || Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=14735GE Z-Wave Motion Sensor Dimmer Switch2020-02-11T20:21:16Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 12/6/18):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.6<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed || Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Ask_Alexa&diff=14071Ask Alexa2019-01-14T16:04:44Z<p>MichaelStruck: /* Latest Versions */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
'''Ask Alexa''' is an add-in to the SmartThings mobile application that allows you to control a broad array of devices with your Amazon Alexa Enabled Devices. When installed along with the proper services at AWS (Amazon Web Services), a simple voice command allows you to control your devices along with querying their status. Simply "Ask" Alexa to do something within your SmartThings environment and she will respond!<br />
<br />
'''Ask Alexa''' can replace the basic integration between SmartThings and Alexa. In the default SmartThings integration, you may only control switches and thermostats and there is limited feedback to ask the status of the devices. '''Ask Alexa''' improves this integration by not only expanding the devices you can control with your voice, but you can now get real-time feedback on inside temperatures, door, switch, dimmer status, etc, and control modes, Smart Home Monitoring security status, run routines and set up complex macro-like events using natural speech. You can even interface other SmartThings SmartApps into '''Ask Alexa''' by using the message queue function and access another popular community-written app, WebCoRE, directly from '''Ask Alexa''' (and in turn, '''Ask Alexa''' macros can be referenced within the WebCoRE application itself).<br />
<br />
No matter how you want to address your home, from a more "Star Trek" experience ("''<Computer, tell studio to turn the lights on"''>) to natural language (<''"Alexa, tell the house I am cold"''>), '''Ask Alexa''' is the go-to app for SmartThings/Alexa integration.<br />
<br />
[[File:AAMainScreen.jpg|890px]]<br />
<br />
==Summary==<br />
[[File:AskAlexa512.png|256px]]<br />
<br />
'''Category:''' My Apps<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Code contributions:''' Keith DeLong, Barry Burke, foxxyben & M3Rocket (utterances), Jimxenus/larry-fuqua (misspellings/logic issues in the GUI), jhamstead and Yves Racine for Ecobee code<br />
<br />
'''Documentation contributions:''' Keith DeLong, Jason Headley, Belgarion, Barry Burke, Andrea Bianco, Yves Racine, Todd M(@Pantheon)<br />
<br />
===Latest Versions===<br />
<br />
{| class="wikitable"<br />
|+The latest version of each of the applications listed in this document (as of 1/14/19)<br />
|-<br />
! '''Ask Alexa Code''' !! Area Used !!'''Version''' !! '''Location'''<br />
|-<br />
| '''SmartApp Code''' || SmartThings IDE || ''2.3.9h'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
|-<br />
| '''Node.js''' || Lambda code for aws.amazon.com (manual install only) || ''1.3.1a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/Node.js<br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|+Extensions<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues]|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
|-<br />
| '''Rooms/Groups Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_Rooms/Groups]|| SmartThings IDE || ''1.0.4b'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
|-<br />
| '''Schedules Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Schedules]|| SmartThings IDE || ''1.0.4a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
|-<br />
| '''Voice Report Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Voice_Reports]|| SmartThings IDE || ''1.0.9'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
|-<br />
| '''Weather Report Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Weather_Reports]|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy <br />
|}<br />
<br />
===Compatibility With Other SmartApps===<br />
'''Ask Alexa''' isn't limited to just the standard devices that come with SmartThings. It can also work directly with other SmartApps and even some custom Device Type Handlers. The following is the current list of compatible SmartApps/DTHs...Items with (2.0) designation already or will support the new message queue structure (see [[Ask_Alexa_-_Message_Queues]]):<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''SmartApp/Custom Device Type''' !! '''Supported Features''' !! '''Author'''<br />
|-<br />
| '''NST Manager''' || ''Message queue (2.0) and thermostat reports'' || Anthony Santilli<br />
|-<br />
| '''WebCoRE''' || ''Message queue (2.0)'' || Adrian Caramaliu<br />
|-<br />
| '''My Ecobee Device & Service Manager (MyEcobeeInit)''' || ''Message queue (2.0) - Comfort & Energy Saving tips for your Ecobee device, ecobee Alerts, exception events and tstat reports'' || Yves Racine<br />
|-<br />
| '''Zoned Heating/Cooling Solutions (ecobeeSetZoneWithSchedule, ScheduleRoomTempControl, ScheduleTstatZones)''' || ''Message queue (2.0) for reporting heating/cooling zoned scheduling events'' || Yves Racine<br />
|-<br />
| '''Device Monitor''' || ''Message queue (2.0) '' || Eric Maycock<br />
|-<br />
| '''MonitorAutomaticCar''' ||''Message Queue (2.0) for reporting hard acceleration/brake/ignition off/on and other Automatic events'' || Yves Racine<br />
|-<br />
| '''OSRAM Lighting Controls-DTH''' [https://raw.githubusercontent.com/gkl-sf/SmartThings/master/osram-bulb-HA.groovy] || ''Loop/Pulse'' || gkl-sf<br />
|-<br />
| '''Foobot Air Quality Monitor-DTH'''[https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/foobot-air-quality-monitor.src/foobot-air-quality-monitor.groovy] || CO2/Particles/VOCs/Temperature/Humidity || Michael Struck/Adam V<br />
|-<br />
| '''Big Talker''' || ''Message Queue (2.0)'' || Brian Lowrance<br />
|-<br />
| '''Lock Manager''' || ''Message Queue (2.0)'' || Erik Thayer<br />
|-<br />
| '''RemindR''' || ''Message Queue (2.0)'' || Bobby Dobrescu <br />
|-<br />
| '''Smart GCal Control''' || ''Message Queue (2.0)'' || Anthony Pastor (infofiend)<br />
|-<br />
| '''Sports Notifications''' || ''Message Queue (2.0)'' || Eric Luttmann<br />
|-<br />
| '''Spruce Status'''|| ''Message Queue (2.0)'' || Barry Burke<br />
|-<br />
| '''Open Source Ecobee Thermostat, Sensors and Companion SmartApps'''|| ''Message Queue 2.0 for Ecobee Alerts and Reminders'' || Barry Burke<br />
|-<br />
| '''My Ecobee stats generation Smartapps'''|| ''Message Queue (2.0) for reporting ecobee daily/weekly/monthly runtime (HomeIQ) stats '' || Yves Racine<br />
|-<br />
| '''MyNeurio & MyNeurioAppliance Service Managers'''|| ''Message Queue (2.0) for reporting exception events and summary Energy Consumption & Generation reports (Daily, Weekly, Monthly)'' || Yves Racine<br />
|-<br />
| '''MyAutomatic Service Manager'''|| ''Message Queue (2.0) for reporting exception events and Driving Summary Reports (Daily, Weekly, Monthly)'' || Yves Racine<br />
|-<br />
| '''MonitorAndSetEcobeeHumidity'''|| ''Message Queue (2.0) for humidity control notifications - using HRV/ERV/Humidifier/Dehumidifier devices connected to your ecobee'' || Yves Racine<br />
|-<br />
|-<br />
| '''MyFlair Devices (Puck, Vent, HvacUnit) & Service Manager'''|| ''Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions'' || Yves Racine<br />
|-<br />
| '''MyNextManager & Devices (Tstat, Alarm, Cam)'''|| ''Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions'' || Yves Racine<br />
|-<br />
| '''Room Occupancy'''||''Control over the occupancy of a room using a custom DTH, Message Queue (2.0)'' || Bangali<br />
|-<br />
| '''GE Motion Switch/Dimmer'''||''Verbal control over the operating mode of the switch (models 26933 and 26931)'' || Michael Struck<br />
|-<br />
|}<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use '''Ask Alexa''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Requirements==<br />
<br />
The following are the basic requirements to use '''Ask Alexa''':<br />
<br />
*A mobile device running the SmartThings mobile application<br />
*An Amazon Alexa Enabled Device (it is not required the device be integrated with SmartThings, but doing so won't interfere with '''Ask Alexa''')<br />
*Devices (Switches, lighting, thermostats, etc) that are operational within the SmartThings environment. To help Alexa understand your devices, they should each be uniquely named in your account. <br />
*An AWS Lambda and developer account<br />
**For the developer account, please ensure you create the account under the same account you used for your Amazon Alexa Enabled Device setup. See the steps to create the account [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide here].<br />
**For the AWS/Lambda account (to host your code), follow the instructions [https://aws.amazon.com/lambda/getting-started/ here]. Please note that you MAY need to provide a credit card for the setup. Be sure to read the pricing structure for AWS Lambda space [https://aws.amazon.com/lambda/pricing/ here].<br />
<br />
==Privacy Statement==<br />
'''Ask Alexa''' leverages an external web hosting service to automate some of the setup and operation of the SmartApp. To ensure complete transparency, you may read the privacy statement here: [http://ask-alexa.com/privacy.html]<br />
<br />
==Limitations==<br />
* The instructions presented here are for US installations only. While many of the concepts are universal, all screen shots and languages assume US/English installations. If you find some slight variation are needed in these instructions please update the wiki or contact the author of this application.<br />
<br />
== Definitions ==<br />
<br />
Throughout this document there will be some specific terms relating to the SmartThings and Amazon development environments.<br />
<br />
===SmartThings/Ask Alexa/General Definitions===<br />
*'''SmartApp:''' Add-in to the SmartThings mobile application that allows for functionality outside of what is provided by default. These SmartApps are not stand alone programs, but only operate within the SmartThings mobile application. SmartApps are open source and written in a form of the Java programming language called “groovy”.<br />
*'''Parent/Child SmartApp:''' A code structure within the SmartThings development environment where a single instance of a parent SmartApp can have multiple child SmartApps associated with it, allowing the single SmartApp to have multiple functions. '''Ask Alexa''' uses this structure for its extensions; there can only be one instance of the '''Ask Alexa''' SmartApp and each extension created within the parent SmartApp is actually an instance of the child SmartApp. This structure cuts down on repeated code within a single SmartApp.<br />
*'''Virtual Switch:''' A device within the SmartThings environment that functions like a regular switch (think of a button or a light switch). However, the device is “virtual” and does not exist as a physical device. Used mostly with [http://thingsthataresmart.wiki/index.php?title=Alexa_Helper Alexa Helper]. However, you can activate virtual switches using '''Ask Alexa''' as well.<br />
*'''Alias:''' In the context of '''Ask Alexa''', this is a name that is used as a place holder (or alias) for another device. This allows to have two devices named the same thing within your SmartThings app, but allows you to address them differently in '''Ask Alexa'''.<br />
*'''IDE:''' Abbreviation for “Integrated Development Environment”. In the context of the SmartThings environment, this is the web site located at http://ide.smartthings.com or https://graph-eu01-euwest1.api.smartthings.com/ (depending on your country) that allows for advanced functionality within the SmartThings environment. This allows you to set up custom devices and applications that appear within your SmartThings mobile application.<br />
*'''DTH:''' '''D'''evice '''T'''ype '''H'''andlers. This is code that is usually community written and allows third-party devices to operate in the SmartThings environment. A good example of this is the Nest Thermostat.<br />
*'''GitHub:''' A web-based repository that allows for distribution revision control and source code management functionality.<br />
*'''OAuth:''' Provides client applications a secure method for accessing resources on behalf of the resource owner. Within the context of SmartThings, certain custom applications that allow for remote access (such as remotely turning on or off a light) will require additional authentication. As the owner of the resource, you can authorize remote access to an application by enabling OAuth.<br />
*'''Access Token:''' A security identity that is linked to OAuth and in the context of SmartThings allows for remote control of a locations devices.<br />
*'''URL:''' Uniform Resource Locator, or basically the address of a web site or online resource, such as http://www.smartthings.com<br />
*'''REST:''' '''RE'''presentational '''S'''tate '''T'''ransfer is an architectural style, and an approach to communications that is often used in the development of Web services. In SmartThings, it is how external applications, such as Amazon's services, can interact the devices in your account, using the OAuth and Access Token as 'keys' to securely access these devices.<br />
*'''Text Field Variables:''' In the context of '''Ask Alexa''', these are variables that can be used in any text areas of the macros to give you 'short cuts' to commonly used text. Typically, they start and end with a percent sign, like %temp%. See [[Ask_Alexa#Text_Field_Variables]] for the variables currently available.<br />
*'''WebCoRE:''' '''W'''eb '''C'''ommunity's '''o'''wn '''R'''ule '''E'''ngine. Another SmartThings community developed application that defines 'pistons' to perform complex, decision-based automation. One of these events could be a trigger from '''Ask Alexa'''. More information can be found here: https://community.smartthings.com/t/webcore-beta-milestone-1/86153<br />
<br />
===Amazon/Alexa Development Definitions===<br />
*'''AWS:''' Amazon Web Services is a collection of cloud computing services that make up the on-demand computing platform offered by Amazon.com.<br />
*'''Lambda:''' An AWS service. Lambda lets you run code without provisioning or managing servers. With Lambda, you can run code for virtually any type of application or back-end service - all with zero administration. <br />
*'''A.S.K.:''' The Alexa Skills Kit is a collection of self-service APIs, tools, documentation and code samples that make it fast and easy for you to add skills to Alexa.<br />
*'''Invocation Name:''' This is the name you will "invoke" to communicate with the Alexa Enabled Devices, which in turn communicates with SmartThings and '''Ask Alexa'''. By default, the invocation name using in '''Ask Alexa''' is "smart things"; however, the invocation name can also be words like "home", or "house" to make command syntax smoother. You may even set up multiple skills, each with the name of a room, and have personalized responses for each room. For example, you could say <''"Alexa, tell the kitchen to turn off the lights"''> and affect the Kitchen, or <''"Alexa, turn the lights off in the bedroom"''> and only have the lights in the bedroom react.<br />
*'''Intents:''' An intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots. <br />
*'''Custom Slots:''' A custom slot type is used for items that are not covered by Amazon’s built-in set of types and is recommended for most use cases where a slot value is one of a set of possible values. The values for the custom slots are generated for you via the Settings page. You will simply copy the provided data and paste it into the Amazon Developer Site. <br />
*'''Utterances:''' A structured text file that connects the intents to likely spoken phrases and containing as many representative phrases as possible.<br />
*'''JSON:''' is an abbreviation for ''JavaScript Object Notation'' is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. The Amazon ASK Development area uses JSON for sending input to and from the Alexa Enabled Devices. The basic structure of JSON looks like this:<br />
<br />
<pre style="display: inline-block;"><br />
{<br />
"intent": "DeviceOperation",<br />
"slots": [<br />
{<br />
"name" : "Operator",<br />
"type" : "LIST_OF_OPERATORS"<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
==How Ask Alexa Works==<br />
<br />
Unlike most SmartThings SmartApps, '''Ask Alexa''' works in concert with the external Amazon developer site, including the Lambda web service. However, the "heavy lifting" of determining the condition of your house, generating reports, and most of the feedback spoken by the Alexa Enabled Devices is actually produced by your SmartThings account, NOT the Amazon cloud services. See the diagram below for a bit more detail on this.<br />
<br />
[[File:AAFlow.png|700px]]<br />
<br />
<pre style="display: inline-block;"><br />
Thanks to Keith DeLong for the above diagram.<br />
</pre><br />
<br />
The user will query their Amazon device, and the Amazon "skill" simply looks for the nouns and verbs (keywords) of your speech and then send those key words to your SmartThings account. The '''Ask Alexa''' SmartApp processes this information, does its actions, and sends Amazon the text response to process through its text-to-speech function. Basically, the Alexa Enabled Device is not turning on your devices...your '''Ask Alexa''' SmartApp is doing the work.<br />
<br />
==Set up of your Alexa Enabled Devices==<br />
Setup of your Amazon Alexa Enabled Devices with SmartThings native functionality is NOT required to use '''Ask Alexa'''. '''Ask Alexa''' operates independently of the integration. However, to have a backup method of controlling your environment, or to use apps like [http://thingsthataresmart.wiki/index.php?title=Alexa_Helper Alexa Helper], you will need to follow the steps below. Please refer to your Amazon Echo documentation, use the Amazon Echo mobile app, or visit http://alexa.amazon.com for more information.<br />
<br />
[[File:EchoApp.png|right|200px]]<br />
* Configure your device on your home’s Wifi and ensured that it is functional<br />
* Configure the device to work with your SmartThings Devices [[https://support.smartthings.com/hc/en-us/articles/205275404-How-to-connect-Amazon-Echo-with-SmartThings]] (via the Amazon Echo application on your mobile phone or http://alexa.amazon.com. Setup within the Amazon Echo app is under ''Settings'' and ''Connected Home'')<br />
* Once SmartThings is properly configured, go into the Amazon Echo SmartApp within SmartThings (See image to the right) and click on the switches you intend to use. These can be real switches/dimmers, virtual switches or momentary button tiles<br />
* Click <<Done>>, then say to your Alexa Enabled Device ''<"Alexa, discover new devices">''<br />
* Within the Amazon Echo Application (NOT the SmartThings app), or http://alexa.amazon.com, you should now see the switches you have "Discovered"<br />
* If you later add switches to SmartThings, you will need to add them to Amazon Echo Smart App within SmartThings, then "Discover" them<br />
<br />
==Setting up your Amazon Lambda and Developer Accounts==<br />
To use '''Ask Alexa''' you will need to create two "free" accounts at Amazon. While the full instructions on setting up these accounts is outside of the scope of this document, very clear instructions are published by Amazon themselves:<br />
<br />
[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide '''Developer Account'''] <br />
<br />
[https://aws.amazon.com/lambda/getting-started/ '''Lambda Account''']<br />
<br />
Please note that these account are 'free' (see the information here[https://aws.amazon.com/free/]). Please be sure to ONLY sign up for the Lambda piece, and the 'basic' tier of service. You MAY be required to provide a credit card number, however, to open an account.<br />
<br />
[[File:AAMainAWS.jpg|700px]]<br />
<br />
'''Notice'''<br />
While the Lambda account is listed as free, if you generate excessive <br />
traffic from your account, Amazon WILL charge you. Fortunately, this <br />
level of traffic would need to exceed 5 million hits per month to account<br />
for even $1.00. So, while the accounts are 'free' for general use, full <br />
public distribution and use would definitely incur a fee if your volume <br />
is high enough.<br />
<br />
==Ask Alexa (SmartThings Code) Installation==<br />
<br />
There are multiple methods to get '''Ask Alexa''' installed into the SmartThings environment. You can use the Community Installer, manually install the code from the links in GitHub, or use the IDE/GitHub integration within SmartThings.<br />
<br />
===Community Installer (Free Marketplace)===<br />
<br />
To install '''Ask Alexa''' via the Community Installer, please see here: http://thingsthataresmart.wiki/index.php?title=Community_Installer_(Free_Marketplace)<br />
<br />
Simply find '''Ask Alexa''' in the list, and install ALL pieces of the application (including Extensions or 'child' applications). If you are upgrading, click the <<Update>> button.<br />
<br />
[[File:CI-AboutApp2.png|250px]]<br />
<br />
===Manual Installation===<br />
<br />
The code for the '''Ask Alexa''' SmartThings SmartApp is found on the GitHub site:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
<br />
While on the GitHub site, find the '''Raw''' button and click it. This will bring up a non-formatted page with just the code present. Select all of the code (typically CTRL+A) and copy It (typically CTRL+C).<br />
<br />
[[File:GitHub.png|700px]]<br />
<br />
<br />
*Next, point your browser to you SmartThings IDE for your country (i.e. http://ide.smartthings.com or https://graph-eu01-euwest1.api.smartthings.com) and '''Log In'''.<br />
<br />
[[File:loginscreen.jpg|700px]]<br />
<br />
*Once you are logged in, find the '''My SmartApps''' link on the top of the page. Clicking '''My SmartApps''' will allow you to produce a new SmartApp.<br />
<br />
[[File:MySmartApps.png|700px]]<br />
<br />
*Find the button on this page labeled '''+New SmartApp''' and click it.<br />
<br />
[[File:+NewSmartApp.png|700px]]<br />
<br />
*Since you already have the code in your computer’s clipboard, find the tab along the top section called '''From Code'''. In the area provided, paste (typically CTRL+V) the code you copied from GitHub. Click '''Create''' in the bottom left corner of the page.<br />
<br />
[[File:NewSmartAppCreate.png|700px]]<br />
<br />
*This will bring up another page, with the code now formatted within the IDE. If the code was copied correctly, there are no other steps except to save and publish the code. In the upper right corner of the page, find and click '''Save'''. Now, click '''Publish (For Me)''', and you should receive a confirmation that the code has been published successfully.<br />
[[File:SavePublish.png]]<br />
<br />
===OAuth Setup===<br />
'''Ask Alexa''' will need to be accessed by the Amazon servers in order to operate correctly. As such, OAuth is REQUIRED for this application.<br />
<br />
To enable OAuth, first find and click the '''App Settings''' button in the upper right corner of the page.<br />
<br />
From here, find the '''OAuth''' section toward the bottom of the page. <br />
<br />
[[File:OAuthBtn.png|700px]]<br />
<br />
Clicking the '''OAuth''' link will reveal a button labeled '''Enable OAuth in Smart App'''. Click this button. The screen will change, giving you a unique code for your '''Client ID''' and '''Client Secret'''. These are the foundations of the security of your app and should be kept secret. You do not need to memorize or write down these codes; nor do you need to add any other information to this page. OAuth simply needs to be enabled for '''Ask Alexa''' to operate.<br />
<br />
[[File:OAuth.jpg|700px]]<br />
<br />
The final step is to press the '''Update''' button at the bottom left corner of the screen, or go back to your code by using the button in the upper-right region of the page, then '''Save''', then '''Publish''' the SmartApp again. <br />
<br />
[[File:SavePublish.png]]<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
Next, you will need to load up the child extension SmartApps. This code for these are located here. Installation is exactly the same for each one. Just repeat the steps below for each set of code.<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy<br />
<br />
The steps for installation are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
===Advanced Installation===<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of SmartThings SmartApp code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found on the SmartThings web site [[http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git]]<br />
<br />
'''Please Note:''' <br />
This process only applies to installing the SmartThings SmartApp. <br />
This process DOES NOT update any of the code on the Amazon developer site; <br />
you will need to follow the process [[Ask_Alexa#Building_The_Skill]] to <br />
install or update your skill information.<br />
<br />
Once you have integration, the four pieces of code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page (this will only appear after you integrate with GitHub)<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''Ask Alexa''' SmartApp code, enter the information as you see it below:<br />
{| class="wikitable"<br />
!'''Owner'''!!'''Name'''!!'''Branch'''<br />
|-<br />
| MichaelStruck || SmartThingsPublic || Master<br />
|}<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. These will typically be:<br />
<br />
<br />
{| class="wikitable"<br />
|+GitHub location of Apps/Extensions<br />
|-<br />
! '''SmartApp''' !! '''Location'''<br />
|-<br />
| '''Main Ask Alexa''' || smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
|-<br />
| '''Message Queue Extension''' || smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
|-<br />
| '''Rooms/Groups Extension''' || smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
|-<br />
| '''Scheduler Extension''' || smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
|-<br />
| '''Voice Report Extension''' || smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
|-<br />
| '''Weather Report Extension''' || smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy<br />
|-<br />
|}<br />
<br />
'''Tip'''<br />
When adding code from the repo you have to add it in a <br />
specific order or the IDE will generate an internal server error. <br />
Add the main Smartapp (Ask Alexa) to your IDE first. Then you can <br />
add the extensions.<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new apps should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Ask Alexa SmartApp Installation==<br />
If you installed the code properly, you should find the '''Ask Alexa''' SmartApp located in the SmartThings Mobile Application under Market Place>>>SmartApps>>>+MyApps. If you have published any of the '''Ask Alexa''' extension you may see them in this list as well. DO NOT install those; just install the main '''Ask Alexa''' app. You may install extensions via the parent SmartApp.<br />
<br />
[[File:AAAddSmartApp.png|250px]]<br />
<br />
After you install '''Ask Alexa''', it is a good idea to set it up, and THEN do the Amazon setup pieces ([[Ask_Alexa#Developer_and_Lambda_Code_Installation]]). This will limit your need to go back and forth as the way you configure '''Ask Alexa''' determines how you set up the Amazon Developer's site.<br />
<br />
==Ask Alexa Interface==<br />
When you first open the SmartApp, you will be greeted with colorful icons where you can interface items with Alexa. Some of these items allow for control (i.e. switches, doors, locks, etc), and some will only provide their status (open/close sensors, water sensors). More devices are being integrated as the application matures. Some menu items (like the <<Device Aliases>>) may not appear in your interface until you activate the appropriate options in the <<Settings>> area (see [[Ask_Alexa#Allow_Device_Aliases]])<br />
<br />
It is recommended that you now add the devices you will want control of and status of to the interface before going on to the next steps of setting up the Developer/Lambda accounts. This will prevent your having to repeat these steps upon the completion of your installation.<br />
<br />
[[File:AAMain.png|250px]]<br />
<br />
===Interface Items===<br />
<br />
Currently, you have the ability to interface switches (dimmers and colored lights), locks, temperature/humidity devices (including thermostats), open/close, presence, motion and water sensors, along with your SmartThings modes, Smart Home Monitor and Routines to your Alexa Enabled Devices. Please note that in addition to the devices to interface, if you have the <<Allow Device Aliases>> enabled in the <<Settings>> area, you will also see options to add devices that can have aliases associated with them.<br />
<br />
*'''Lighting/Switches'''-These devices are very straight forward; you can turn them on, off or toggle their state (<''"Alexa, ask SmartThings toggle the Living Room"''>), change the level of a dimmer (<''"Alexa, tell SmartThings to set the Dining Room to 50%"''>), or even change the color of a bulb (<''"Alexa, ask SmartThings to set the Den to Blue"''>). In addition, you can ask the status of a device easily (<''"Alexa, ask SmartThings the status of the Living Room"''>). For items like colored lights, two commands may be combined into one...For example <''"Alexa, ask SmartThings to set the Den to Blue and to 50%"''>. Also on this page, if you choose colored lights, you will find the option to add a custom color as well under the <<Settings>><<Custom Color Setup>> ([[Ask_Alexa#Custom_Color_Setup]]). As is customary with dimming controls, only positive numbers between zero and 100 are accepted; any numbers exceeding this value will be normalized to the 0-100 range. Finally, you can use custom commands like maximum, increase, decrease, brighten, dim and low, medium and high to specify default behavior of dimmable switches. <br />
<br />
'''Please Note'''<br />
There are over 150 available colors to choose from in the latest version of '''Ask Alexa'''.<br />
A full list of colors would take minutes to recite; if you need to reference <br />
these colored names, it is recommended you view the cheat sheet <br />
(see [[Ask_Alexa#About_Ask_Alexa]]) or the FAQs (see: [[Ask_Alexa#Frequently_Asked_Questions_.28FAQs.29]]).<br />
The names of the colors come directly from SmartThings. Again, if one of these colors <br />
do not meet your needs you can define your own custom color.<br />
<br />
For Temperature (Kelvin) lights, you have the option of choosing four settings, <br />
"Soft White", "Warm White", "Cool White" and "Daylight White", setting the lights <br />
to 2700K, 3500K, 4500K and 6700K degrees Kelvin, respectfully. These are the only <br />
temperature setting available for these lights, which are typically white LED lights.<br />
You can change the default value of these 4 settings by going to <<Settings>><br />
<<Default Command Values>>. See [[Ask_Alexa#Default_Command_Values]]<br />
<br />
*'''Doors/Windows/Locks'''-Another simple set of devices that can be addressed using natural language. A simple command such as <''"Alexa, tell SmartThings to unlock the front door"''> will unlock the door. To enhance security, you do have the option to set up a PIN to prevent these simple commands from allowing access to critical devices (see [[Ask_Alexa#Password_PIN]]). In addition, you can disable commands like "Open" Or "Unlock" for additional security. As with the switches, you can always query the status of device (<''"Alexa, ask SmartThings about the Garage Door"''>). In this category are window shades, locks, doors, and open/closed sensors which are usually used for door or window open/close status.<br />
<br />
'''Important Notice Of Liability'''<br />
It can not be stressed enough that allowing your locks or doors to be controlled by<br />
this SmartApp lowers the security of your household. Anyone with knowledge of your <br />
home setup (including your PIN) can open/close/lock/unlock these devices. The author <br />
of this application accepts NO RESPONSIBILITY with intentional or unintentional <br />
use (or misuse) of these features. Use SmartThings holistically; if you enable this<br />
feature ensure you are also properly monitoring/alerting on the devices as well.<br />
<br />
*'''Environmentals'''- Many SmartThings devices have temperature, humidity or even UV sensors built into them. As such, you may query the status of these devices to get their current readings. Also, you may set the set any SmartThings connected thermostat to a specific setpoint. Please note that many thermostats have both heating and cooling setpoints. As such, unless you have your thermostat set to just heating or just cooling, it is a good idea to ensure you are setting the proper setpoint. For example, if you thermostat is in auto mode, you could say <''"Alexa, tell SmartThings to set the heat in the office to 65 degrees"''>. If your thermostat is in a specific mode (like heating), it is perfectly acceptable to just ask her to set the temperature setpoint...<''"Alexa, tell SmartThings to set the office to 65 degrees"''><br />
<br />
'''Please Note'''<br />
<<Environmentals>> is the area you are most likely to have the same device<br />
in multiple device categories. For example, you might have a humidity sensor that can<br />
also be added as a temperature sensor, or an air quality monitor that registers humidity.<br />
'''The program will not operate correctly if you choose the same device in multiple areas.''' <br />
It should be noted, however, that if you turn on additional attributes within the <<Settings>><br />
<<Device/Event Voice Setting>>menu that you can hear the additional parameters without choosing <br />
the same device in two different categories.<br />
<br />
When you select a thermostat you will be given the option to select some device specific commands. Various devices that work with SmartThings have powerful features or different command sets that don't comply with normal APIs provided by SmartThings. A good example of this is the Nest Thermostat; this device is not officially supported by SmartThings, but there are a few community-written device handlers that allows it to perform normal thermostat functions within your house. However, it also has other features that no other thermostats have; one of these features is the ability for the thermostat to act as a presence sensor, changing the way it behaves based on occupancy. The user may also set the "Home" and "Away" status manually, or through automation. If you are using Nest Manager, you can even expand on the generic Nest commands with custom reports (i.e. <"Alexa, ask SmartThings for Nest report">.<br />
<br />
Another example is the Stelpro baseboard heating thermostat. This device is supported by SmartThings, but had different modes of operation besides heating and cooling; these are "Eco" and "Comfort" modes. Ecobee3 (Connect), as yet another example, allows for specific modes such as "Home", "Away", "Sleep", and "Resume Program" commands.<br />
<br />
====MyEcobee & MyNext Devices' comfort & energy saving tips ====<br />
<br />
If you have a Ecobee or a Nest thermostat, you have the ability to use a community-developed device type handler, written by Yves Racine, to get you tips to operating your device (and your home) more efficiently. To access these tips, do the following:<br />
<br />
*Go to <<Settings>><br />
*Choose <<Device Specific Commands>><br />
*Choose <<Ecobee Specific Thermostat Modes>><br />
*Choose <<MyEcobee Specific Tips>><br />
<br />
Or if you have My Next Tstat for the Nest Thermostat:<br />
<br />
*Choose <<MyNextTstat Specific Tips>><br />
<br />
Then, you can use the following commands with My Ecobee or My NextTstat Device(s):<br />
<br />
'''Individual commands'''<br />
*'''Give Tip/Play Tip''' - This will play the tips available in memory, one at a time, for this device. The tips will increment to the next tip in memory until they have all been heard, at which point they will replay.<br />
*'''Repeat Tip''' - This will repeat the tip that was just played and will not increment the tip counter.<br />
<br />
'''Batch commands (Advanced)'''<br />
*'''Get Tips[Level]''' - Without a number given, it will default to "Level 1" tips, which are the most general. To choose additional tip levels, say that level (i.e. <''"Alexa, tell SmartThings to Get Tips, level 3, for Kitchen"''>. Please note that this will NOT play any tips, it just tells the device handler to load the tips for you into memory. <br />
*'''Reset Tips''' - This will reset the tips in memory. You must then say 'Get Tips' (with or without level) for the device to obtain more tips.<br />
<br />
For more information on the My Ecobee's Get Tips, please see here: http://thingsthataresmart.wiki/index.php?title=EcobeeGetTips<br />
<br />
For more information on the My Next Tstat's Get Tips, please see here: http://thingsthataresmart.wiki/index.php?title=NestGetTips<br />
<br />
<br />
*'''Connected Speakers'''- If you connected speakers such as Sonos, Bose or Samsung with SmartThings, they can be controlled with '''Ask Alexa'''. Basic commands are supported, with plans to implement other features in the future. Simple say, <''"Alexa, tell SmartThings to play Bedroom Speaker"''> and the device will come on. You can also pause, mute, and skip tracks. You can also give a volume command between 0-100. Like the dimmers, you can also "increase" and "decrease" the volume based on the settings you define in the <<Settings>> area. <br />
<br />
'''Notice'''<br />
The Sonos integration within SmartThings is currently in listed as a "Labs" .<br />
release. This means certain functionality is subject to change or may not work as<br />
expected. This includes re-playing music from a saved list.<br />
<br />
*'''Other Sensors'''-You may have other sensors around your house that you would also like to report on. Currently, acceleration, water, presence, occupancy and motion sensors are available. With the water sensors, you get a status reading of either wet or dry. Presence and motion/acceleration sensors behave in a similar fashion, with one state (present or motion) or another. Similarly, using a custom Device Type Handler, you can also check the status or change the occupancy of a room. In addition, as most of these types of sensors also have temperature readings available, if you have the other attributes configured to play, the voice reading will include this as well. Finally, if the sensor is a battery operated device, the battery reading will play if below the designated threshold (Set in <<Settings>>). Typically, sensors are read-only. However, with version 2.2.2, you may use the concept of a 'virtual' or simulated presence sensor so that those without physical presence devices can be accounted for and automations can run based on their presence. Users simply 'check in' or 'check out' with Alexa when entering a location.Physical presence sensors will not work with these additional commands. You will need to create a simulated presence sensor. The instructions for installation of this virtual device is here: [[Virtual_Presence_Sensor]]. <br />
<br />
*'''Modes/Routines/SHM''' - Unlike the native SmartThings integration, '''Ask Alexa''' will allow you to query and/or change the modes or Smart Home Monitor status, in addition to running a specific routine. When speaking to Alexa, ensure you specify what you want to do: <''"Alexa, ask SmartThings to run Good Morning Routine"''> or <''"Alexa, ask SmartThings the current Security status"''>. Be sure your mode or routine names also are unique among your SHM settings as well (i.e. Stay, Arm, etc.). If you have unique names to your routines and modes, you may shorten your commands to <''"Alexa, tell SmartThings Good Morning"''>, assuming you have a "Good Morning" routine. Finally, you have the ability to require a PIN number to activate the modes/routines or change the Smart Home Monitor settings. This option will appear when you have the PIN enabled in the <<Settings>> area (see: [[Ask_Alexa#Password_PIN]])<br />
<br />
'''Please Note'''<br />
For the Smart Home Monitor (SHM) functions, if you do not choose ANY states<br />
this will effectively release the 'reserved' words of "security", "smart home" and <br />
SHM. This is useful if you have switches set up with those same words. For example,<br />
if you use the popular app "Smart Alarm" you can now have a virtual switch called <br />
"security".<br />
<br />
*'''Device Aliases''' - While it is recommended that you have unique names for each of your devices within your SmartThings environment, this is sometimes not possible or practical. However, you can't address devices that appear multiple times with the same name (i.e. the name "Living Room" that is both a lamp device and a motion sensor). To solve this, '''Ask Alexa''' allows you to set up aliases to allow you to access all the devices within your environment without having to rename your devices within the main SmartThings app. You must turn this function on in the <<Setting>> menu item and then select the devices you wish to create aliases for in each of the device categories above. Once you do this, you will see the <<Device Alias>> selection appear. Using the example above, you could keep controlling the living room lamp with just with the name "Living Room" and then create an alias for the living room motion sensor. Once set up, the alias name behaves exactly like any other devices, picking up parameters unique to the device type. Another good example is to shorten a device name so it is easier to address. For example, if you have a long name for your speaker (i.e. "Master Bedroom Sonos") you could create an alias simply called "speaker" to address that device (see figure below).<br />
<br />
[[File:AAAliasMain.png|250px]] <br />
<br />
'''Alias Usage Limitations/Notes'''<br />
* Aliases are one-to-one associations; to control groups of devices using a single name you <br />
will need to create a room/group (see [[Ask_Alexa_Rooms/Groups]]).<br />
<br />
* Alias names must still be unique within the '''Ask Alexa''' app. This means the name should<br />
not be the same as any other device (or alias) or routine, modes or voice macros<br />
<br />
* When creating and deleting alias names, be sure to use the interface buttons provided on <br />
the page and not the SmartThings "Done","Save" or "<" buttons. Using these may give you undesired results.<br />
<br />
* Speaking of interface, due to a limitation of the SmartThings GUI, when you create your first<br />
alias that names will 'stick' in the interface input areas, giving you an error if you do not change <br />
it and simply press ADD again (as the alias name will be one that you just created). Be sure all of your <br />
alias names are unique and that you change the interface when you add or delete an alias.<br />
<br />
===Extensions===<br />
[[File:Ext@2x.png|100px]]<br />
<br />
On the main '''Ask Alexa''' page, scroll down to the area labeled <<Extensions>>. Extensions can be thought of as 'mini' applications that expand the functionality of '''Ask Alexa'''. Currently, there are multiple extensions available: Macros (which are built in), Message Queues, rooms/groups, voice/weather reports and scheduling. Additional extensions coming soon.<br />
<br />
'''Notice'''<br />
When naming your extensions (be it Message Queues, rooms, voice reports or Macro names or aliases), <br />
ensure your names are unique not only within the context of the other extensions, but <br />
within the parent app itself. That means an extension should not share the same name with<br />
devices, aliases, modes, or routines within the parent app. Taking this precaution will <br />
eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
[[File:AAMQMain.png|250px]]<br />
<br />
For information about each extension, including setup instructions, please click on the appropriate link below:<br />
<br />
* '''Macros''': [[Ask_Alexa_-_Macros]]<br />
* '''Message Queues''': [[Ask_Alexa_-_Message_Queues]]<br />
* '''Rooms/Groups''': [[Ask_Alexa_Rooms/Groups]]<br />
* '''Schedules''': [[Ask_Alexa_-_Schedules]]<br />
* '''Weather Reports''': [[Ask_Alexa_-_Weather_Reports]]<br />
* '''Voice Reporting''': [[Ask_Alexa_-_Voice_Reports]]<br />
<br />
===Settings===<br />
<br />
Back on the main (parent) interface you will find the <<Settings>> area. This page is separated into four sections that allow you to customize your '''Ask Alexa''' experience. This includes what the Alexa device will say when you ask for a status of SmartThings devices, whether or not you need a password for security related items (like doors, locks, Smart Home Monitor settings, etc), and the default values used to set up and operate the SmartApp for your environment.<br />
<br />
====Setup Ask Alexa====<br />
The very top menu item is where you want to go for all things related to setting up '''Ask Alexa'''. This includes defining the Skill Invocation name, getting the setup variables for the Amazon AWS and Developer's sites, and displaying the command 'cheat sheet'.<br />
<br />
[[File:AASetup.png|250px]]<br />
<br />
=====Skill Invocation Name=====<br />
<br />
At the top of the page you will set up a specific invocation name for the skill name. Throughout this document the assumption is that you use "Smart Things" (two separate words) as this name; however, it can be anything. If you do change it within Amazon developer web site, you SHOULD change it here to match.<br />
<br />
=====Setup Variables=====<br />
The voice system of the Amazon Alexa Enabled Devices is very programmable. Almost any device you have in your system can be addressed by name. However, the Alexa Enabled Devices do not know these names by default; you must input them into the Amazon developer site as custom slots ([[Ask_Alexa#Custom_Slot_Information]]). While this can be a tedious task, '''Ask Alexa''' reduces the steps by evaluating the devices you have chosen to interface and generate an HTML setup page, allowing you to copy and paste the information directly to the Amazon Developer site.<br />
<br />
When you tap the <<Setup Variables Link>> you will be presented in your SmartThings Live Logging with a web page URL. Copy this link to a computer (desktop) browser and you will then be given a page with the various variables you will need to operate '''Ask Alexa''' properly. <br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Any time you add or remove devices, modes, routines, or reports to your '''Ask Alexa''' SmartApp, it is best practice to put the new information into the custom slots so Alexa recognizes the new commands.<br />
<br />
'''Please note'''<br />
If you find your IDE Live Logging is not presenting the data properly, the page presented<br />
on your mobile device gives you the address you need on your desktop browser to continue<br />
the setup process. Simply copy that address to an e-mail (or other method) the can be <br />
sent to your desktop environment. Of course, the Live Logging method is the preferred <br />
method of obtaining this setup URL.<br />
<br />
[[File:AASetupURL.png|250px]]<br />
<br />
=====Cheat Sheet=====<br />
At the bottom of the setup page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within '''Ask Alexa'''. <br />
<br />
While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See [[Ask Alexa#Setup Variables]])<br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.<br />
<br />
====Additional voice settings====<br />
In this section you will set up what additional information the Alexa Enabled Devices respond back to you and how.<br />
<br />
[[File:AASettings.png|250px]]<br />
<br />
=====Accept Compound Commands=====<br />
<br />
'''Ask Alexa''' can accept 'compound commands' as part of its command structure. Simply put, a compound command is controlling two actions with one statement. For example, you could say ''<"Alexa, tell SmartThings to turn on the office and close the garage"''> to have two actions occur in tandem with one command. While this is convenient, the more words you say to Alexa, the more opportunities she has of misunderstanding you. Turning this option off, you disable the ability for '''Ask Alexa''' to process compound commands. Only single action commands will be accepted.<br />
<br />
=====Device/Event Voice Setting=====<br />
<br />
In this section you will find items relating to the device voice output along with event voice output.<br />
<br />
[[File:AADeviceEvent.png|250px]]<br />
<br />
======Give Brief Device Action Reply======<br />
Under normal operation, when you give an action to a device, Alexa will respond of a confirmation of your action. For example, if you say <''"Alexa, tell SmartThings to lock the Front Door"''>, if the door is locked already she will state that, or if it is unlocked she will respond "I am locking the front door.". However, if you feel that the responses get tedious to hear, you can turn on "Brief" replies to device actions. When clicking this feature, you have the option of having Alexa reply with nothing, an "Ok", "Done", or a user-defined output. Please note a few caveats to this behavior:<br />
* For items like locks and doors, the default action is to check the status of those devices and NOT perform the action if the device is already in the desired state. With brief replies turned on, you will not get this feedback.<br />
* If an error occurs with the device, you will still get the error message if brief replies are activated.<br />
* If you have battery alerting on (See [[Ask Alexa#Battery Level]] below), these messages will append to your brief message.<br />
<br />
Please note that the default behavior has been modified slightly (since version 2.2.9) in that the After Action/Event History Continuation commands will be muted when brief reply is turned on.<br />
<br />
======Speak Additional Status Attributes======<br />
For devices like switches or open/close sensors, there are other attributes that can be accessed besides the primary functions. For example, many light switches also monitor the power usage of the connected device. In addition, most SmartThings sensors (motion, water, or open/close sensors) also monitor temperature. Finally, many stand-alone devices, like motion sensors, are battery operated. When you ask Alexa the status of a device, you also have the option to have the additional attributes spoken.<br />
<br />
To use enable this option, on the main menu of '''Ask Alexa''' find the <<Settings>> option. Tapping this will bring you the <<Settings>> area. Tap the slider labeled <<Speak Additional Device Status Attributes>>.<br />
<br />
Please note items that are NOT selected as motion sensors, but have these capabilities, will ONLY report this attribute when motion is in progress.<br />
<br />
======Device Health======<br />
<br />
Sometimes the devices in your environment go offline. While there are many causes for this, the end result is that you may attempt to control a device and it is offline without you knowing it. If you enable <<Speak Device Health When Offline>> you will be alerted to the offline status of a device when you attempt to control or query the device. Please note that Ask Alexa CANNOT bring the device back online; this requires manual intervention. In addition, some devices that are tagged by SmartThings on being "offline" simply haven't reported in for a while. Many time, just manually toggling the device (be it a switch, or motion sensor) may be enough to put it back into online status.<br />
<br />
======Battery Level======<br />
This option will allow you to set the threshold in which the batteries status is reported on. The default value of the threshold is 20...using this setting, if the battery level on a device is below 20%, when you ask the status of a device (i.e. <''"Alexa, ask SmartThing the status of the living room"''> the battery will be reported as well. Above the threshold, no battery status will be given. Please note that battery report is given whether or not the above attributes setting is selected if the level is below the threshold.<br />
<br />
======Default Number Of Past Events======<br />
SmartThings keeps a log on every change on the devices, whether it be a motion sensor showing movement, or a door opening or closing to a light turning on or off. Using the command "Events" on a device you can access the last events (ex. <''"Alexa, ask SmartThings to give me the last events on Living Room"''>). When no number is specified, the number in the <<Default Number of Past Events To Report>> will be used to give you that number of entries from the log. You can override this by giving a number in the command (ex. <''"Alexa, ask SmartThings to give me the last 4 events from the Bedroom"''>)<br />
<br />
====Enable Flash Briefing====<br />
This option will allow you to enable the ability to use a macro or Message Queue as the output of the native Alexa 'flash briefing' function. This process is described here ([[Ask_Alexa_-_Flash_Briefing]]) and does require additional steps to create a new skill that allows for this functionality. When you select this option, another option appears below it allowing the selection of the output you wish to use for your flash report.<br />
<br />
====Personalization====<br />
With a little bit of configuration on this page, you can give Alexa's responses a more "personalized" touch. This includes allowing her to "follow up" after an error, or address you by name in a formal or even funny manner. All of these options also allow you to have them 'whispered' to you all of the time, or within specific modes or timeframes.<br />
<br />
[[File:AAContCmds.png|250px]]<br />
<br />
Alexa has the ability to continue with a "skill" after the primary function or response is given. With the options in this area, you can choose if you want Alexa to ask ''"Anything else?"'' after certain actions have been performed. For example, if you want to stay within the skill after an error comes up (let's say you didn't choose a valid switch), then you would turn on the <<After Error>> option. When Alexa says ''"Anything else"'' you do not have to use the <''"Alexa, ask SmartThings"''> command; simple state your command (i.e. <''"Turn on the front porch"''>). The settings here are global; if you turn them on <<After Errors>> continuation options will be given after every error. Same for the other switches except <<After Macro Execution>>. For Macros, if you have the <<After Macro Execution>> switch turned on, you DO have the ability to suppress this on a per-macro basis. This does NOT suppress any errors that come up within the macro execution (if turned on); they will only suppress the "Anything else?" questions.<br />
<br />
Also on this screen you can setup your response "Personality". These personalities will give you different types of responses based ranging for "Normal" to "Snarky" to "Courtesy". For advanced users, these can be customize for your environment/mood. You can also set a name that Alexa will occasionally address you by. The responses are random, so it won't happen all of the time. Again, for advanced users, you can use the text variable %people% (see [[Ask_Alexa#Text_Field_Variables]]) to have the responses customized based on who is present in the house. Unfortunately, Alexa has no ability at this time to determine WHO is speaking to her, so the text variable may not be the best solution as it will list everyone in the house.<br />
<br />
=====Playback Options/Restrictions=====<br />
<br />
Under the Global Options of the personality page you will find the playback options/restrictions. Here you can set up restrictions to mute the playback (either disabling Ask Alexa based on the restrictions, or simply mute the playback but continue to process the commands given to it). <br />
<br />
[[File:AAPlayback.png|250px]]<br />
<br />
In addition to muting playback, Alexa also allows the device to change the voice patterns (speed and pitch) including the ability to 'whisper' back to you in a computerize-light voice. Be warned...this has been called by some "creepy", however, there are specific use cases. Because the volume and the overall tone of whispers is less than normal, you can use these during your 'bedtime' to still interact with Alexa and (hopefully) not wake the person next to you. TO do this, simply turn on the switch <<Enable Whisper Mode>>. Leaving the restrictions below this setting blank means that whisper mode will be enabled all of the time. To restrict this, choose the timeframe and/or mode you want whisper mode to operate in. You can also choose which Echo device to apply restrictions to. All output will then be whispered to you until the restrictions conditions change.<br />
<br />
[[File:AHResitrictions.png|250px]]<br />
<br />
For speed and pitch, there are pre-defined configurations you can choose. Please note that if you change the pitch from normal, you will not be able to use the whisper command. Basically, the pitch command is invalid when whispering. However, speed can be used with the whisper mode. You CAN pick and choose between pitch and speed to create a unique voice response within your household.<br />
<br />
'''Please Note'''<br />
Speed, pitch and whisper adjustments configured on this page affect<br />
ALL output coming from '''Ask Alexa.''' This does NOT affect the output<br />
of the normal (non-'''Ask Alexa''' skill) output. If you want specific '<br />
''Ask Alexa''' text to be whispered or emphasized, please use the advanced <br />
features of the <<Text Field Variables>> (see [[Ask_Alexa#Text_Field_Variables]])<br />
<br />
<br />
[[File:AASpeakOpt.png|500px]]<br />
<br />
====Other Values/Variables====<br />
<br />
In this section, depending on your setup, you may have the following options that can be customized by you. The default values should allow for proper operation, but you can change them to suit your needs. <br />
<br />
[[File:AASettings-1.png|250px]]<br />
<br />
=====Default Command Values=====<br />
<br />
Some of the devices that use variable numeric numbers to control them (like dimmers, thermostats or volume control) are context sensitive. This means you don't need to give a specific number to increase or decrease their value. You can simply say <''"Alexa, tell SmartThings to increase the Living Room by 25%">'' and it will rise 25%. However, if you leave off the number, the settings here will be the default amount of the increase or decrease. You can then just say, <''"Alexa, tell SmartThings to increase the Living Room"''> and it will increase by 20% (the default). You can change these numbers accordingly, but be careful for items like volumes and temperature defaults to prevent hearing or heat damage.<br />
<br />
Also, you will see the option for low, medium, high default values. These are good for ceiling fans that operate in 3 different modes, but these settings can be used for lighting as well. Setting these default values will allow you to simply say <''"Alexa, ask SmartThings to set fan to medium"''> and the fan will go to the percentage you place in these areas.<br />
<br />
Finally, if you use Temperature (Kelvin) lights, the values for "Soft White", "Warm White", "Cool White" and "Daylight White". If you do not change these numbers, the defaults will be used (2700K, 3500K, 4500K and 6700K, respectfully).<br />
<br />
=====Device Minimum/Maximum Values=====<br />
For devices with variable inputs that are critical (i.e. volumes, or temperature controls), '''Ask Alexa''' allow you to set minimum and/or maximum values for some of these parameters. For example, a speaker may not need to ever go above 20%...placing 20 in the maximum value slot will prevent your from purposely (or by a misunderstanding from the Amazon TTS system) from setting the volume above this value. In contrast, you may not want to allow your thermostat to be set less than 60 degrees...putting this number in the appropriate slot will prevent any settings from going below that value.<br />
<br />
=====Text Field Variables=====<br />
These global variables are words (typically starting and ending with a percent sign...for example %temp%) that can be used in any text fields of the macros/extensions to give you 'short cuts' to commonly used text. These make it convenient to personalize the messages coming from the Alexa Enabled Devices, macros and extensions.<br />
<br />
[[File:AAVar1.png|250px]][[File:AAVar2.png|250px]]<br />
<br />
A full list of the current variables available to use are here:<br />
<br />
{| class="wikitable"<br />
|+'''Text Field Variables used in pre/post messages and macro acknowledgement areas'''<br />
|-<br />
! '''Variable''' || Translation<br />
|-<br />
| '''%time%''' || This will give the time in 12 hour, AM/PM format<br />
|-<br />
| '''%day%''' || This will speak the day of the week (Monday, Tuesday, etc.)<br />
|-<br />
| '''%date%''' || This will speak the full date (ex. January 25th, 2016)<br />
|-<br />
| '''%temp%''' || When a single device is selected (defined in the temperature report area) the device will report that temperature. If multiple devices are selected, it will average the readings and report the average.<br />
|-<br />
| '''%humid%''' || Similar to the temperature reading above, when a single device is selected the device will report that humidity. If multiple devices are selected, it will average the readings and report the average.<br />
|-<br />
| '''%people%''' || These are defined by presence sensors that are currently present. Using this variable you can personalize some of the responses the Alexa devices give. You can also use this variable when setting up your personalized feedback (See [[Ask Alexa#Personalization]])<br />
|-<br />
| '''%macro%''' || This is the name of the macro/extension that was called.<br />
|-<br />
| '''%mtype%'''|| This is the type of macro/extension being called (i.e. Room/Groups, Control Group, WebCoRE, etc)<br />
|-<br />
|'''%delay%''' || For macros such as WebCoRE and Control macros, this variable holds the delay (in minutes) that was specified within the app or verbally.<br />
|-<br />
|'''%age%''' || For the Schedules extension, this variable holds the age of the schedule (i.e. the person's age or anniversary years) if the original year of the event was defined. <br />
|-<br />
|'''%random{1-3}%''' || When you set up the 3 categories of random responses, placing this variable in a text field will randomly choose a response and play it.<br />
|-<br />
|'''%xParam%''' || For WebCoRE. Extra parameters of control<br />
|}<br />
<br />
For example, if you are giving a nightly report right before you go to bed and you wish to personalize the message, your post message could be something like:<br />
<br />
<pre style="display: inline-block;"><br />
It is %time% on %day%, %date%. It is time for bed %people%. %random1%.<br />
</pre><br />
<br />
This would result in something like ''"It is 9:00pm on Monday June 23, 2016. It is time for bed Jim and Jane. Sleep well...Good night."''. In this particular example, the time and date have been replaced with real time information. The %people% variable is determined by who is present from the presence sensor readings you set up in the main menu <<Setting>> area. Finally, the %random1% list is 3 good night phrases that you have defined. The other two could be "Don't let the bed bugs bite" or "Talk to you in the morning". Anything can be put into these areas.<br />
<br />
In addition to the built-in variables, advanced users have the ability to reference weather reports using a variable. Simple surround your report name with percent signs, and this variable can play in any extension text field. This is very useful for voice reports where you want to include a weather report.<br />
<br />
Finally, there are other advanced flags available ('on-demand whispering', 'emphasis' and 'suppress continuation messages' ) that can be used in text fields. <br />
<br />
The 'on-demand whispering', 'emphasis' tag tags ONLY works if you have the Global Whisper Functions function turned off in the <<Personalization>> section (see [[Ask_Alexa#Personalization]]). This will allow you designate parts of the output as regular and parts as whispers and yet other parts emphasized. <br />
<br />
The 'suppress continuation messages' is only used in macros/extensions when continuation of commands (see [[Ask_Alexa#Personalization]]) is enabled for macros/extensions. Basically, placing this tag at the end of the custom acknowledgement will suppress the prompt "Is there anything else?" placed at the<br />
<br />
To use these features, here is the formatting:<br />
<br />
{| class="wikitable"<br />
|+'''Advanced Tags used in pre/post messages and macro acknowledgement areas'''<br />
|-<br />
! '''Tag''' || '''Usage'''<br />
|-<br />
| '''<w>''' || Any text between here and the "off" switch (below) will be whispered<br />
|-<br />
| '''</w>''' || Any text between the above and this tag whispered<br />
|-<br />
| '''<eH>''' || Any text between here and the "off" switch (below) will be highly emphasized<br />
|-<br />
| '''<eL>''' || Any text between here and the "off" switch (below) will have lower emphasis<br />
|-<br />
| '''</e>''' || Any text between either of the above switches and this tag will be emphasized as outlined(H or L)<br />
|-<br />
| '''%X%''' || Used for macro/extensions custom acknowledgments. Will suppress any output from continuing commands<br />
|}<br />
<br />
For example, let's say you have a voice report that has following custom acknowledgement:<br />
<br />
<pre style="display: inline-block;"><br />
"And that is all. <w>Have a good evening</w>. <eH>Don't let the bed bugs bite!</e> %X%"<br />
</pre><br />
<br />
The section encapsulated by the <w> </w> will be whispered and the text between <eH> </e> will be highly emphasized (slowed down and volume increased) while the other parts will play based as normal. In addition, with the %X% at the end the additional text of "Would you like anything else?" will be suppressed; however, Alexa WILL remain active, listening for any additional commands that can be used within '''Ask Alexa'''.<br />
<br />
=====Custom Color Setup=====<br />
If you have no colored lights in your SmartThings environment, you will not see this selection. If you have chosen any colored lights you will have the option to set up a custom color. Simply give the name of the custom color, the hue and then the saturation of the color (A good reference for hue and saturation is here[http://www.december.com/html/spec/colorhsltable.html]. You will need to ensure you update your developer slots when you have saved this name, but after you do you should have access to this color when utilizing colored lights.<br />
<br />
=====xParams For WebCoRE Macros=====<br />
<br />
If you use '''Ask Alexa''' to run WebCoRE macros and need to pass a word parameter to the piston, you can now (as of 2.3.7) maintain your list of xParams via the SmartApp instead of manually inputting them to the Developer's slots (Under LIST_OF_WCP). More information can be found about passing variables here: [[Ask_Alexa_-_Macros#Advanced_features]]<br />
<br />
[[File:AAxParam.png|250px]]<br />
<br />
====Security====<br />
In this section you can set up security related items such as PIN numbers, or to revoke your Access Token.<br />
<br />
[[File:AASettings-2.png|250px]]<br />
=====Revoke/Reset Access Token=====<br />
It may be necessary sometimes to revoke your Access Token and issue a new one. Typically, this is required when you publicly post the ApplicationID or TokenID to a public site as this would allow others to access your home environment. Once you reset your token, you will need to place the new code pieces into your Lambda code (See [[Ask_Alexa#Finalizing_The_Function_Code]]). <br />
<br />
To proceed with the reset, simply tap the area labeled <<Revoke/Reset Access Token>>. Here, you will be given one last opportunity to cancel this process as doing so will disable the ability for '''Ask Alexa''' to control your SmartThings environment.<br />
<br />
=====Password PIN=====<br />
While one of the strengths of the Alexa Enabled Devices is the voice recognition; one of the weaknesses is that the device has a difficult (and inconsistent) ability to differentiate one person from another. In most household, the Alexa Enabled device is shared among many people. This makes security of commands on the device almost non-existent. For example, imagine a banking app that speaks your bank balance. If you were to have a dinner party, anyone at the party that was savvy enough with the Alexa Enabled Devices could access your bank balance as easily as you. While there is "security through obscurity" in the fact that '''Ask Alexa''' is community built and not mass market, in theory, a person familiar with your home system could yell through a window and say <''"Alexa, ask SmartThings to open the garage door"''>. To prevent this and provide some level of security, '''Ask Alexa''' implements a basic PIN system for security items like doors, locks, modes, routines, SHM, and macros that control these items.<br />
<br />
To use this feature, in the '''Ask Alexa''' SmartApp find the <<Settings>> menu item, then tap the the on/off slider labeled <<Password (PIN) Option Enabled>>. This will reveal an area to enter a PIN number. Be sure to enter numbers in this area. Then, while setting up various items like lock, modes, or control macros, you will be given the option to use the PIN for that function. You can also 'fine tune' this security by adding restrictions, such as the day of the week, or even which Echo devices require a PIN.<br />
<br />
To use this new PIN in the context of opening the garage door, simply say <''"Alexa, ask SmartThings to open the garage door password 1234"''> (assuming you chose 1234 as your PIN). You will always append your commands with the password. Putting it in other locations throughout your syntax may not give the desired results. If you fail to issue the PIN command, you will be prompted by any device or function that requires a PIN to supply this information. This follow up is as simple as <''"Password 1234"''><br />
<br />
====Advanced====<br />
In this section you can enable some of the advanced features of '''Ask Alexa'''. <br />
<br />
[[File:AASettings-3.png|250px]]<br />
<br />
=====Allow Device Aliases=====<br />
To allow devices to have aliases associated with them, enable this option. This will do two things to the main menu interface; first, each device category will have a new area to allow devices to be set up as aliases. Second, once devices are selected, the main menu will display the <<Device Aliases>> area, allowing you to set up the aliases with the devices you have selected. See [[Ask_Alexa#Interface_Items]] for more information.<br />
<br />
=====Assign A Name=====<br />
If you have a need for changing the default name of the SmartApp ('''Ask Alexa''') you may do this using the <<SmartApp Name>> area. This does NOT have any other other affect on the app except to change the name as seen in your SmartThings main app menu. When used with a multi-room setup, you can easily identify the correct app to set up for specific rooms (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]] for more information.)<br />
<br />
===About Ask Alexa===<br />
<br />
The about page gives basic information about the '''Ask Alexa''' app and other parameters you may find useful. You may also produce a "cheat sheet" that can be printed for those not familiar with the setup of the SmartThings environment or your '''Ask Alexa''' configuration. <br />
<br />
In the <<Version Numbers>> section, you will find the versions of the SmartApp and the Lambda code. You can also hear the version numbers of the SmartApp and Lambda code by asking <''"Alexa, Ask SmartThings about Versions"''>.<br />
<br />
In addition, this page displays your current Access Token and Application ID. This is useful for troubleshooting only and should be kept private to prevent someone else from controlling your house. Below this is the list of your Echo devices that have been associated with rooms.<br />
<br />
The Apache license is available on this page as well, along with some basic instructions.<br />
<br />
At the bottom of the page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within '''Ask Alexa'''. <br />
<br />
[[File:AAHelp.png|250px]]<br />
[[File:AAHelp1.png|250px]]<br />
<br />
While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See [[Ask Alexa#Setup Variables]])<br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.<br />
<br />
Finally, if you choose to remove this application (and the corresponding macros), you may do this at the bottom of the page. Simply tap <<Remove>> and the application will be removed from SmartThings. If you choose to set up the app again, you will need to go through the entire setup process again.<br />
<br />
==Developer and Lambda Code Installation==<br />
<br />
The next step is to install the ASK code to the AWS/Lambda server and to define the custom intents, slots and utterances. You will need both an Amazon developer account and an AWS Lambda account. Creation of these accounts is outside of the scope of this document, however, very clear instructions for starting these accounts can be found here: [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide Developer Account] and [https://aws.amazon.com/lambda/getting-started/ Lambda Account]<br />
<br />
===AWS/Lamba Code===<br />
<br />
The basic steps for generically creating Lambda code is listed here [https://developer.amazon.com/alexa-skills-kit/tutorials/fact-skill-1]. Many of the same steps are listed below as well.<br />
<br />
*First, be sure you Lambda account is set to the proper region. The Alexa skills are currently only supported from the <<US East (N. Virginia)>> <<US West (Oregon)>> and <<EU West (Ireland)>> region. Failure to do choose the correct region will prevent you from properly setting up the Configure Triggers ([[Ask Alexa#Configure Triggers]])<br />
[[File:AAAWSP1.png|250px]]<br />
<br />
*Next, find the area within the AWS dashboard for Lambda. This may be a button on the main screen or within the menu below <<Compute>>.<br />
<br />
[[File:AAAWSP2.png|700px]]<br />
<br />
*Find the button labeled <<Create Function>>. Click this and you will begin configuring the parameters of the function.<br />
<br />
[[File:AAAWSP3.png]]<br />
<br />
*You will be brought to a screen to choose a blueprint. Choose <<Author from scratch>> and click it.<br />
<br />
[[File:AAAWSP35.png|700px]]<br />
<br />
From here you will enter a name of the function (it is recommended to use "askAlexa") <br />
<br />
For the area labeled <<Run Time>> it is recommended you set this Node.js (version numbers may be present...always choose the current one), then choose a role or use an existing role. It is recommended that you choose a '''Existing Role''' and select "lambda_basic_execution". If you do not have anything listed in the "Existing Roles" do the following:<br />
<br />
* In the role, choose '''Create a custom role'''<br />
* A new screen will show up<br />
* In the IAM Role, choose '''lambda_basic_execution'''<br />
* Keep the policy name as default<br />
* Click the '''Allow''' button in the bottom right corner of the screen<br />
<br />
[[File:AAlambda.png|700px]]<br />
<br />
When you return to the previous screen and you have configured everything like the screenshot below, click <<Create Function>>.<br />
<br />
[[File:AAAWSP35.png|700px]]<br />
<br />
====Configure Triggers====<br />
<br />
Next, you will be brought to a page where you choose what type of trigger you are creating. On the left side of the screen there is a section called <<Add Trigger>> and here you will choose the "Alexa Skills Kit".<br />
<br />
If you are asked to configure your trigger (specifically with Skill ID), for now choose "Disabled", then <<Add>> in the bottom right of the screen and then click the skill name at the top of the page (above the Skills kit and CloudWatch Logs).<br />
<br />
[[File:AAAWSP3-1.png|700px]]<br />
<br />
'''Please Note''' <br />
If you don't see Alexa Skills Kit in the list, you have chosen the wrong region. <br />
You must use the'''US East (N Viginia)''', '''US West (Oregon)''' or the Ireland datacenters. <br />
Once you have selected Alexa Skills Kit, click <<Configuration>> to go back to the main code <br />
section of the function.<br />
<br />
From here you can enter your code. See the next section (Configure Function) to choose two different methods for entering your code into this area.<br />
<br />
[[File:AAAWSP31-1.png|700px]]<br />
<br />
====Configure Function====<br />
<br />
After version 2.3.5a there are two methods you can use to get the correct information into the Lambda code: A process where you simply click a link on the Setup Variables page, and a more manual method where you paste the authentication information from the Setup Variables page to the Lambda code.<br />
<br />
=====One-Step Method=====<br />
<br />
The one-step method is, by far, the easiest way to get the needed information to your Lambda code. Obtain the code for your configuration, follow these steps:<br />
<br />
* In the Ask Alexa Smartapp, click <<Settings>><<Setup Ask Alexa), then <<Setup Variables Link>> (see [[Ask_Alexa#Setup_Variables]]). Please note you should be using a desktop browser to do this.<br />
* Find the buttons to obtain the Lambda Full Code:<br />
<br />
[[File:LambdaCode.png|700px]]<br />
<br />
* Clicking this link will bring up the raw code, customized with your authentication information already embedded in it. Simply select all the text in the browser (typically Clt+A), then copy it (Ctl+C), then paste it into the proper location.<br />
<br />
[[File:AAAWSP4.png|700px]]<br />
<br />
*Save the code and you are done!<br />
<br />
=====Two-Step Method=====<br />
For those that want to do the installation manually...<br />
<br />
In this step you will need to supply the code with your unique Application ID and Access Token. The app will generate this for you either in your mobile device or via a desktop/laptop browser. See [[Ask_Alexa#Setup_Variables]] for more instructions to obtain this.<br />
<br />
* Obtain the code from From here:<br />
{| class="wikitable"<br />
|-<br />
! '''Ask Alexa Code''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Node.js''' || Lambda code for aws.amazon.com || ''1.3.1a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/Node.js<br />
|}<br />
<br />
*Paste the code here:<br />
<br />
[[File:AAAWSP4.png|700px]]<br />
<br />
*In the '''Ask Alexa''' Smartapp, click <<Settings>><<Setup Ask Alexa>> then <<Setup Variables>> (see [[Ask_Alexa#Setup_Variables]]). Please note you should be using a desktop browser to do this.<br />
<br />
*At the top of the HTML setup page that is generated, you will want to copy the first 3 lines below the title <<Lambda code variables>>.<br />
<br />
[[File:AAAAWSDev1.png]]<br />
<br />
'''Please Note'''<br />
While the web address (URL) to the SmartThings environment should remain constant, it could be different <br />
than what is displayed about depending on the country you reside in. In addition, this address is<br />
subject to change at any time. The '''Ask Alexa''' app uses the SmartThings API to generate this address<br />
when you run the setup page.<br />
<br />
If the app stops working suddenly, please ensure these parameters in your setup web page<br />
match the Lambda code you pasted when you set up this function.<br />
<br />
*Next, paste the lines between the two commented areas (breaks) at the top of the code area.<br />
<br />
[[File:AAAWSP10.png|700px]]<br />
<br />
Failure to copy these lines exactly will prevent the Lambda code from accessing your SmartThings environment. When you have completed copy (or any time you modify the Lambda code, be sure to click Save in the upper-left corner of the screen).<br />
<br />
'''Please Note'''<br />
Do not press the <<Test>> or <<Save and test>> buttons in the AWS Lambda area.<br />
Doing so will not cause any problems, but Lambda works on specifically formatted <br />
inputs and unless you supply these inputs exactly to the test it will always present <br />
you will an error. This error is not valid and this recommendation is simply <br />
made to avoid confusion when setting up the code.<br />
<br />
====ARN Code====<br />
<br />
* When everything is configured properly and saved, you will find in the '''upper right-hand corner''' of the screen an ARN. This is your Amazon Resource Name and will link your function with a corresponding Skill. It is recommended you copy this number or keep your screen open when you are creating the Skill in the developer area below.<br />
<br />
[[File:AAAWSP7.png]]<br />
<br />
===Developer Account (Primary Skill)===<br />
<br />
You will now need to define the primary skil using an Amazon developer account. Be sure you have followed the instructions from Amazon on setting up your developer account: [https://developer.amazon.com/appsandservices/community/post/Tx3U4BH5Y7JB35L/How-To-Create-a-Distribution-Portal-Account.html Developer Account].<br />
<br />
'''Please Note'''<br />
In order to easily test and use your new "skill" it is recommended that you create<br />
your developer account under the same account you used to set up your Alexa device.<br />
If you already have a developer account that is different than your Alexa device account, <br />
you must assign your physical device to the developer account and then associate <br />
your personal account as a "household" under your development account. More information<br />
on this process can be found [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/testing-an-alexa-skill#h2_register here].<br />
<br />
* To begin creating your skill, go to https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit and find the area on the right side labeled <<Start a Skill>>. You will be brought to a dashboard of your current skills. <br />
<br />
[[File:AADevP0.png|700px]]<br />
<br />
* On the Alexa Skills Kit Developer Console, click <<Create Skill>><br />
<br />
====Building The Skill====<br />
* The first page you will be presented with is the Skill Name. Typically, it is recommended to use '''Ask Alexa - SmartThings Integration'''<br />
<br />
* Next, you will be presented with a page with pre-built models' however, you will choose a <<Custom>> skill. Select this option, then click <<Create Skill>> in the upper-right corner of the page.<br />
<br />
[[File:AADevP0-1.png|701px]]<br />
<br />
* Here, you will be presented with options to build your skill. On the right side of the page you will have the various steps required to create your skill. These include Invocation Name, Intents, Samples, and Slots, Build Model, End Point. <br />
<br />
* To begin, click <<Invocation Name>><br />
<br />
[[File:AADevP0-2.png|701px]]<br />
<br />
* While the name can be anything you want, it is recommended to start off with 'smart things'. Other options include words like 'house', home, etc.<br />
<br />
'''Please Note''' <br />
The Invocation name should be typed in lower-case. If you like to use the word '''SmartThings'''<br />
as the invocation name, it is recommended you type 'smart things' (not 'smartthings'). <br />
Also note that the invocation name within your SmartApp (here: [[Ask_Alexa#Personalization]])<br />
should match this name. This is important if you use the [[Ask_Alexa#Single_Step_Interaction_Model]]<br />
to set up your Amazon developer area.<br />
<br />
* After you have entered your Invocation Name, click, <<Save Model>> at the top of the screen. Then click <<Custom>> on the left side of the screen.<br />
<br />
[[File:AADevP1.png|701px]]<br />
<br />
* You should now see your invocation name with a check mark next to it.<br />
<br />
* Next, on the Skills main page, find the <<JSON Editor>> on the left side<br />
<br />
=====JSON upload=====<br />
<br />
[[File:AADevP2.png|700px]]<br />
<br />
* Go back to your '''Ask Alexa''' SmartApp and run your <<Setup Variables>> again (see [[Ask_Alexa#Setup_Variables]])<br />
<br />
* Just like the Lambda code setup (see [[Ask_Alexa#One-Step_Method]]) you will click the link for the Developer Code (Second bold line).<br />
<br />
[[File:LambdaCode.png|700px]]<br />
<br />
* Alternatively, you have the option to download the Developer Code (JSON) as a text file. Please note the file name will have a timestamp on it and may be different than what is shown below. '''This is the recommended way of doing this INSTEAD of copying/pasting the JSON code.'''<br />
<br />
* Select all of the code from webpage, copy it, and then paste it into the Amazon Developer's page. If you chose to download the JSON text file, click the area as shown below, choose the file you downloaded, and click Open. After either (not both) of these steps, click <<Save Model>> in the upper-left corner of the page. Then click <<Build Model>>. Be sure to watch the upper-right corner of the screen to status messages, including any errors that may occur.<br />
<br />
[[File:AADevP3.png|700px]]<br />
<br />
Once the build is completed, click <<CUSTOM>> on the left side of the screen, you will now see steps 1, 2 and 3 on the right side with a green check mark. Click on <<4. Endpoint>><br />
<br />
[[File:AADevP4.png|700px]]<br />
<br />
* On the next step, you will enter the ARN number from the code from the AWS/Lambda area (See [[Ask_Alexa#ARN_Code]]). Place this code in the <<Default Region>> Area<br />
<br />
[[File:AADevP5.png|700px]]<br />
<br />
* Click <<Save Endpoints>> at the top of the screen. Next, click on <<Interfaces>> on the left side of the screen. Ensure your page looks like the screenshot below. Click <<Save Interfaces>> and <<Build Model>> at the top of the screen.<br />
<br />
[[File:AADevP6.png|700px]]<br />
<br />
* Click on Account Linking on the left side of the screen. Ensure the toggle switch is off.<br />
<br />
* The final step is to click <<Permissions>>. This will be set according to the screenshot below with all of the items toggled 'off'<br />
<br />
[[File:AADevP7.png|700px]]<br />
<br />
====Testing Your Skill====<br />
<br />
If you followed the directions properly, you should be ready to test your new skills.<br />
<br />
* Click <<Test>> at the top of the Skill Console.<br />
<br />
* Ensure the <<Test is enabled for this skill>>. While this implies that only testing is impacted, this slider actually disables the operation of your skill using your voice. This must be turned on.<br />
<br />
[[File:AASDev8.png|700px]]<br />
<br />
*As mentioned above, your Alexa Enabled Devices should be associated with your developer account. Please see here ([[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/testing-an-alexa-skill#h2_register]]) if you did not do this.<br />
<br />
*If properly set up, if you go to the <<Skills>> area of https://alexa.amazon.com or the Amazon Echo mobile app and refine the view to <<Your Skills>>, you should see your new '''Ask Alexa''' Skill.<br />
<br />
[[File:AASkill.png|350px]]<br />
<br />
* Start speaking to your Alexa Enabled Device. Start with "Alexa" (or your wake word), along with "ask" or "tell" along with the invocation word, followed by what you want to do.<br />
<br />
* Start with a simple switch (example: Living Room) and say <''"Alexa, ask SmartThings to turn on Living Room"''>. The Living Room should come on. If not, please check all of your settings. You may also visit the SmartThings Community for this app (https://community.smartthings.com/t/coming-soon-ask-alexa/46786) to ask community members (and sometimes the author) questions about this app. Finally, use the [[Ask_Alexa#Troubleshooting]] section for additional advice on how to troubleshoot your issues.<br />
<br />
* If your test goes well, try your other devices. In addition to the voice feedback, you should also also see 'cards' appear in your Echo mobile app to give you an indication of what the device is hearing and the responses it gave. <br />
<br />
[[File:AATestCard.png|350px]]<br />
<br />
* If you have difficulty, you may be able to troubleshoot the application yourself. The Amazon developer web site has tools to allow you to simulate your commands and show you what the responses are. Using this along with the SmartThings Live Logging should allow you to figure out where your issue is.<br />
<br />
* While on the Amazon Developer site, under the Test area, you can type your commands into this simulator to give you access to the skill. Be sure to type your invocation name when using the simualtor (i.e ''tell smart things version'' )<br />
<br />
[[File:AADevTest01.png|700px]]<br />
<br />
* JSON text will appear on the simulator boxes. The left side JSON is useful to see what was input, with right which includes the response from the SmartThings app and presented to the Echo device. <br />
<br />
'''Please Note'''<br />
In order for community members or the author to properly troubleshoot this application<br />
it will be important for you to produce screen shots of your environment. Please ensure<br />
you have provide screen shots of not only the development web site, but the Live Logging<br />
area of the SmartThings IDE so that issues can be quickly resolved.<br />
<br />
====Launch (Optional)====<br />
While optional, you can add icons to your application that will be visible in the Amazon Echo stand alone application on your mobile device, or at http://alexa.amazon.com. On the skills console page, click <<Launch>> at the top of the screen.<br />
<br />
[[File:AADev08.png|700px]]<br />
<br />
The recommended text is outlined below, but again, this is completely optional and is not needed for proper usage of the application or the integration with SmartThings. When you are completed. <br />
<br />
[[File:AAPublish.png|700px]]<br />
<br />
If you choose to use the supplied icons, their locations are listed here to download and use.<br />
{| class="wikitable"<br />
! Icon Size !! Location<br />
|-<br />
|'''108 x 108 icon''' || https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/AskAlexa108.png<br />
|-<br />
|'''512 x 512 icon''' || https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/AskAlexa512.png<br />
|}<br />
<br />
Click <<Save and Continue>> at the bottom. '''Please note that you should stop here''' with your skill. The next steps in the interface are for publishing the app for others to use....something you DON'T want to do unless you want the world to control your home.<br />
<br />
===Developer Account (Secondary Room Skill)===<br />
Coming Soon<br />
<br />
==Ask Alexa Usage==<br />
<br />
Assuming you kept your invocation name as ''"SmartThings"'', the usage of '''Ask Alexa''' is as simple as this: <''"Alexa, ask SmartThings to unlock the front door"''>. The invocation of ''"tell"'' or ''"ask"'' are required to activate the custom ASK Skill. However, they have no other context within the command. In other words, you can 'ask' or 'tell' Alexa the same command and she will respond exactly the same way.<br />
<br />
===Asking/Telling Alexa What To Do===<br />
<br />
Just like human language, the Alexa Enabled Devices will key off of nouns and verbs. The nouns are the device names (or aliases), modes, or routines you have set up in SmartThings. Verbs are the actions (or operations) you would like to carry out. However, just like human language (especially English), the rules are not hard and fast. It is recommended you try different combinations of syntax to get the results you desire. If you come up with a unique one, contact the author of this application so that the "intelligence" of the application can continue to grow.<br />
<br />
Please note that while most of the utterances begin with <''"Alexa, ask SmartThings..."''>, there are also other valid ways to address the '''Ask Alexa''' functions. For example, instead of saying <''"Alexa, ask SmartThings to turn off Dining Room"''>, you could say, <''"Alexa, turn off Dining Room with SmartThings"''>. If "asking" or "telling" Alexa something doesn't feel natural with the "SmartThings" invocation word at the beginning of your command, try another combination with putting <''"...with SmartThings"''> or <''"...using SmartThings"''> at the end of the command. Even "use" can be used (pun) to activate the skill (ex. <''"Alexa, use SmartThings set the Thermostat to auto mode"''><br />
<br />
*'''Switches/Dimmers/Colored Lights''': ''on'', ''off'', ''toggle'', ''status'', ''level'', ''color'', ''increase'', ''decrease'', ''rise'', ''lower'', ''up'', ''down'', ''maximum'', ''minimum'', ''low'', ''medium'', ''high''<br />
**<''"Alexa, tell SmartThings to turn on the living room"''><br />
**<''"Alexa, ask SmartThings to turn on the living room"''><br />
**<''"Alexa, ask SmartThings to increase the level of the living room"''> - Without a numeric settings, "increase" or "decrease" commands will be based on the values you set up in the <<Settings>> area.<br />
**<''"Alexa, tell SmartThings to lower the level of the Living Room by 5%"''> - You can specific the amount of the increase or decrease of the brightness level.<br />
**<''"Alexa, tell SmartThings to set the Media Room to Blue and 30%"''><br />
**<''"Alexa, tell SmartThings to set the Media Room to Red"''> The light will stay at the current level if not specified.<br />
**<''"Alexa, tell SmartThings to set the Bed Room to medium"''> - "Low", "medium" or "high" commands will be based on the values you set up in the <<Settings>> area.<br />
**<''"Alexa, ask SmartThings to set Lamp to maximum"''> - "Maximum" will set the dimmer to 100%.<br />
**<''"Alexa, tell SmartThings to set the Bed Room to medium and green"''> - You can also use two commands in unison as shown here.<br />
*'''Doors/Locks/Shades''': ''lock'', ''unlock'', ''open'', ''close'', ''status''<br />
**<''"Alexa, tell SmartThings to open the front door"''> - Please note that if front door is a connected lock, OPEN will NOT unlock the door. ''Open'' and ''Close'' are reserved for items that have motorized open/close mechanisms.<br />
**<''"Alexa, ask SmartThings to open the garage door password 1234"''> - assuming you chose 1234 as your PIN; see [[Ask_Alexa#Password_PIN]] for more information.<br />
**<''"Alexa, ask SmartThings the status of the garage door"''><br />
*'''Thermostats/Temperature/Humidity''': ''set'', ''status'', ''heat'', ''cool'', ''heating'', ''cooling'', ''mode'', ''off'' (for StelPro baseboard heaters, ''eco'' and ''comfort'' modes also available), ''home/away'' (For Nest Thermostats), ''get/repeat/replay/get/load/reload/restart/erase/delete/clear/reset tips'' (Ecobee Thermostats)<br />
**<''"Alexa, tell SmartThings to set the bedroom to 55 degrees"''> - It should be noted, depending on your thermostat, you may need to append the command with heating or cooling for multi-setpoint thermostats in auto mode.<br />
**<''"Alexa, tell SmartThings to set the bedroom heating to 55 degrees"''> - Same as above, but just sets the heating setpoint<br />
**<''"Alexa, ask SmartThings to turn on bedroom heating mode"''> - For thermostats that have separate heating/cooling/auto mode<br />
**<''"Alexa, ask SmartThings to turn off Bedroom"''> - In this context, when bedroom is a thermostat and NOT a switch, this will turn the thermostat off (from heating/cooling or auto mode)<br />
**<''"Alexa, tell SmartThings to lower the temperature of the living room by 5 degrees"''> - You can specific the amount of the increase or decrease of the temperature setpoint (the value will be based on the current temperature...not the current setpoint).<br />
**<''"Alexa, ask SmartThings to raise the temperature of the den"''> - If no value is given, an increase or decrease in temperature (based on current temperature) will default to the value in the <<Settings>> menu.<br />
**<''"Alexa, ask SmartThings set the Hallway to auto mode"''> - In this context, when hallway is a thermostat and NOT a switch, this will turn to auto mode. Auto mode will require you to set the temperature setpoints using the 'heating' or 'cooling' command.<br />
**<''"Alexa, ask SmartThings the status of the Back Patio"''> - in cases like this, it is better to ask the status of a device and not temperature specifically.<br />
*'''Other Sensors''': ''status''<br />
**<''"Alexa, ask SmartThings the Bathroom Floor status"''><br />
**<''"Alexa, ask SmartThings about Michael"''> - In this context, Michael is a presence sensor. You will receive a response of "present" or "not present".<br />
**<''"Alexa, ask SmartThings about Kitchen Sink"''> - Notice that just the noun can be used and the ''"status"'' is assumed in most cases.<br />
*'''Modes/Routines/SHM''': ''run'', ''execute'', ''status''<br />
**<''"Alexa, tell SmartThings to execute the Good Morning routine"''><br />
**<''"Alexa, ask SmartThings the status of the current mode"''><br />
**<''"Alexa, tell SmartThings good night"''> - Assuming you have a mode or routine called "Good Night", '''Ask Alexa''' will run this mode or routine (please note you must have unique names for modes and routines to use '''Ask Alexa''' properly).<br />
**<''"Alexa, mode status from SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings about security"''> - This is another way to ask about ''status'' of Smart Home Monitor.<br />
**<''"Alexa, tell SmartThings to set security to disarm"''> - please note for the Smart Home Monitor you can also use the noun ''"security"''<br />
*'''Voice/Weather Reports''': ''run''<br />
**<''"Alexa, use SmartThings to run the Nightly report"''> - Notice the word ''"use"'' to activate the skill.<br />
**<''"Alexa, Battery report from SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings for the weather"''> - assumes the name of the weather report is 'Weather'.<br />
*'''Macros''': ''run''<br />
**<''"Alexa, tell SmartThings to set the Media Room Group to 30%"''><br />
**<''"Alexa, tell SmartThings I am going to bed"''> - Please note the creative naming of the control group in this example (Name: "I am going to bed")<br />
*'''Message Queue''': ''play'', ''open'', ''delete'', ''clear'', ''erase'', ''status''<br />
**<''"Alexa, tell SmartThings to play messages"''> Without a queue referenced, the primary message queue will play back<br />
**<''"Alexa, tell SmartThings to open {queue name} queue"''><br />
**<''"Alexa, ask SmartThings to clear message queue"''> As above, without a queue referenced the action will happen on the primary message queue<br />
*'''Connected Speakers''': ''play'', ''pause'', ''stop'', ''mute'', ''unmute'', ''next track'', ''previous track'', ''status'' <br />
**<''"Alexa, ask SmartThings to play Bedroom Speaker"''><br />
**<''"Alexa, tell SmartThings to mute Living Room"''><br />
**<''"Alexa, tell SmartThings to increase the volume of the Office"''> - When no value is given, the increase or decrease will default to the value you set up in the <<Settings>> area.<br />
**<''"Alexa, ask SmartThings about the Guest Room Speaker status"''> - Please note below about querying the status of Sonos speakers<br />
<br />
'''Notice'''<br />
The Sonos integration within SmartThings is currently in listed as a "Labs" .<br />
release. This means certain functionality is subject to change or may not work as<br />
expected. For example, if you manually play the Sonos and then ask Alexa about the <br />
status of the speaker, she may say the speaker is stopped. This is because the Alexa <br />
Enabled Device is pulling the status of the speaker from SmartThings, not the speaker itself. <br />
So, there is typically a 1 to 5 minute delay before SmartThings refreshes the speaker<br />
status. However, commands that YOU issue to the Sonos device are activated immediately.<br />
<br />
*'''Schedules''': ''on'', ''off'', ''status''<br />
**<''"Alexa, ask SmartThings about Doctor's appointment"''><br />
**<''"Alexa, tell SmartThings to turn off Golf Lesson"''><br />
<br />
===Ask Alexa Help/List Commands===<br />
<br />
Obviously, the main purpose of an application like '''Ask Alexa''' is to NOT grab your phone everytime you want to make turn on a light or turn up the speaker. However, humans are visual creatures so it is sometimes difficult to remember the specific name of a device you have included to interface with enabled device without some sort of reminder. '''Ask Alexa''' has a basic help function to guide you through which devices, modes or routine commands you can use. <br />
<br />
Please note that having Alexa call out every device and operation can be time consuming to listen to. If you need her to stop speaking, simply say <''"Alexa, stop!"''>.<br />
<br />
*'''Basic help'''<br />
**<''"Alexa, ask SmartThings for help"''> - This is just an overview of the application usage. At the very end you can confirm what version number of the Lambda code you have running.<br />
<br />
*'''Lists''' - simply issuing a 'List' command and the type of device/operation you want help on will issue a list of what is interfaced with '''Ask Alexa'''.<br />
**<''"Alexa, list switches in SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings to list switches"''><br />
**<''"Alexa, tell SmartThings to list modes"''><br />
**<''"Alexa, ask SmartThings switch list"''><br />
**<''"Alexa, ask SmartThings about the control macros"''><br />
**<''"Alexa, ask SmartThings to list humidity sensors"''><br />
**<''"Alexa, ask SmartThings about the reports"''><br />
**<''"Alexa, ask SmartThings about SHM"''><br />
**<''"Alexa, ask SmartThings about the dimmers"''> - Notice that when asking about a key word noun (dimmer, switches, etc) you can leave off the ''list''.<br />
**<''"Alexa, ask SmartThings to list the colors"''> - This option is available if you have colored lights listed within the '''Ask Alexa''' SmartApp on your mobile device. Please note that the colors list is generated from SmartThings and is quite extensive. It would take over a minute to list the colors, so instead you will be referred to the '''Ask Alexa''' cheat sheet for the full color list.<br />
**<''"Alexa, ask SmartThings to list the colored lights"''> - Please note that this is different the command above. This will give you the list of available colored lights available to control.<br />
<br />
*'''Version'''-You can get the version number of the various pieces of '''Ask Alexa'''<br />
**<''"Alexa, version of SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings about Ask Alexa"''><br />
**<''"Alexa, ask SmartThings about the SmartApp"''><br />
**<''"Alexa, ask SmartThings about versions"''><br />
<br />
*'''Repeat'''- You can request the last thing '''Ask Alexa''' said to you (no action is done, just repeat the last results)<br />
**<''"Alexa, tell SmartThings to repeat"''> <br />
**<''"Alexa, ask SmartThings again"''><br />
**<''"Alexa, ask SmartThings to replay"''><br />
<br />
<br />
There is also a special 'list' that can be retrieved from Device Group Macros (Macros that control groups of similar devices, like switches) and Macro Groups (A macro that runs groups of other macros). Examples include:<br />
*<''"Alexa, tell SmartThings to list HouseMacros"''> - In this context, "HouseSwitches" is a macro groups with child macros included. This command will list the child macros controlled by this group macro<br />
*<''"Alexa, tell SmartThings to list HouseSwtiches devices"''> - "HouseSwitches" is a device group macro. This command will list the devices controlled by this macro<br />
<br />
==Use Cases==<br />
Below are some examples of use cases on how you can use '''Ask Alexa''' to its full advantage.<br />
===Natural Language Responses===<br />
Using a control macro, you can simulate a little bit of intelligence using '''Ask Alexa'''. For example, if you have a room with a few dimmers you could set up a couple of macros called "It is too bright" and "It is too dark". In each of these macros you would set up the dimmers (SmartThings Devices Area) you want to change, and put a default increase/decrease in the provided area. At the bottom of each page you could put in a custom response such as "I have increased the brightness for you". Then, when you say <''"Alexa, tell SmartThings it is too bright"''> or <''"Alexa, tell SmartThings it is too dark"''> and it will increase or decrease the lighting as you requested. Using macro aliases you could use different versions of the phrasing and react accordingly without creating multiple macros for the same action. Future version of '''Ask Alexa''' will allow this type of control for more devices (such as thermostats).<br />
<br />
===Good Night Weekdays/Weekends (Invocation)=== <br />
Using the control, WebCoRE Trigger or voice report restrictions, you can use a single voice command to have multiple outcomes. For example, let’s say you set a different mode on the weekdays than on the weekends when you go to bed. To accomplish this you could set up two control macros; within the first macro you restrict it to run Sunday through Thursday and sets a mode called "Wake up on", and the second only runs on Friday and Saturday and sets a mode called "Wake up off". You would then create a extension group called "Good Night" which includes the first two control macros (no specific order is needed). Each night you could say <''"Alexa, tell SmartThings Good Night">.'' This would allow the same command to be issued nightly but behave differently depending on the day of the week. In the morning, a program such as [http://thingsthataresmart.wiki/index.php?title=Talking_Alarm_Clock Talking Alarm Clock] could key off of the Alarm on/Alarm off modes and react accordingly. If you are using restrictions as part of a extension group you should also click the <<Mute Restriction Messages In Extension Group>> (in the individual macros) to eliminate unwanted restriction warnings within the running of the macros.<br />
<br />
[[File:AHResitrictions.png|250px]]<br />
<br />
===Good Night Weekdays/Weekends (Native, Non-Invocation)===<br />
Similarly to the process above, you can use the native Alexa Routines, along with '''Ask Alexa''', to accomplish the same results without having to utilize the skill directly. The steps are similar to above:<br />
First, just like above, you set up two control macros with the similar weekday/weekend restrictions. You will also create the same extension group which includes these control macros. The difference here is that you will create a virtual momentary switch (using an app like Alexa Virtual Switch Creator [http://thingsthataresmart.wiki/index.php?title=Alexa_Virtual_Switch_Creator]). In this example, the switch is named "Good Night Trigger". Going back to the extension group, you enter this virtual switch in the area labled "Switch trigger for this macro". <br />
<br />
[[File:AAGoodNight.png|250px]]<br />
<br />
In your Native Alexa App, you will then create a routine called "Good Night". You can add a weather report or any other function you'd like, but the most important piece is to include turning the "Good Night Trigger" switch on. Saving the routine and simply saying <''"Alexa, Good Night"''> will set the mode to the correct setting based on the day. <br />
<br />
[[File:AlexaRoutine1.png|250px]]<br />
<br />
Please note that any output you included in the macros or extension group WILL NOT play on Alexa. You can use a message queue and an external speaker to play any output you desire.<br />
<br />
===Weather Reports and Advisories===<br />
Full weather advisories can be lengthy, and if you include them with EVERY other possible weather message (temp, location, lunar, etc.) you are almost guaranteed to exceed the default Lambda timeout (3 secs), and you'll probably exceed even a 10 second timeout if there are multiple alerts for your area. Because of this, you will need to extend your timeouts (if you want to receive the exhaustive Weather Report). Please see below for extending the timeouts. Another solution is to break your Weather Report into 2 separate reports. The first (maybe called "Weather Report") should have everything you want enabled EXCEPT the Full Weather Advisory - you'll get a notice telling you there are one or more Advisories, but not the advisory text. And the second (called "Weather Advisories") has only the temperatures, the <<Full Weather Advisories>>, and the <<Speak Location>> enabled. So, when you run your ''Weather Report'' you will hear there are advisories, and then when the report is done, you can ask Alexa to run the ''Weather Advisories'' report.<br />
<br />
Future versions of '''Ask Alexa''' will allow you to schedule a periodic check of advisories and actually push them to the message queue, which would allow for visual and audio notifications.<br />
<br />
===Basic Control Of Two Homes===<br />
By virtue of how SmartThings and Amazon implement security with their devices, you can typically only control one home's SmartThings devices with the Alexa Enabled Devices in that home. However, you can actually control devices in two different locations using a single Alexa device in each home. This use case assumes you have two SmartThings accounts (or locations) set up.<br />
<br />
To accomplish this, you first need to identify what you want to do at the remote location. This could be simply activating a switch, etc. For simplicity sake, let's use "Home A" and "Home B" as the homes you are working with, with devices, modes or routines listed as "Device A", "Mode A", "Routine A" etc for Home A, and "Device B", "Mode B", "Routine B", etc for Home B. Using this terminology, let's assume you want to control a routine in Home B from Home A's Alexa Device. Using Home B's Ask Alexa implementation you would set up a Control macro that runs Routine B, then obtain the REST endpoint of the macro in Home B you want to run (see below). Next, in Home A's '''Ask Alexa''' SmartApp, you will set up a Control Macro that includes the REST URL in the <<Run this HTTP request...>> section. Then when this Control Macro is run from Home A, Home B's devices will react. There is currently no way to currently gather status feedback from one home to another, however.<br />
<br />
[[File:ControlMacroURL.png|250px]]<br />
<br />
===Multi-Room Controls (Advanced)===<br />
'''Please Note'''<br />
This process requires a bit more effort to accomplish than a normal install.<br />
It is recommended you become familiar with the full home control before you<br />
attempt to do a multi-room install.<br />
<br />
This install does have caveats; message queues still operate, but sending apps<br />
may be confused with multiple rooms set up.<br />
<br />
Use the multi-room setup with careful consideration on the benefits vs the<br />
drawbacks.<br />
<br />
While most users will desire to control their entire home with one invocation name (typically "SmartThings" or "Home"), '''Ask Alexa''' has the ability, with a bit of work, to have a multi-room setup. Consider the following use case:<br />
<br />
You have a large home and routinely have guests over. You want the guest, when in their room, to be able to control the devices within that room without controlling the other rooms or controls in the house. While this is possible in a single-room setup using aliases and macros, this might become confusing. And, this wouldn't prevent the users in that room to do a device or command list and finding out the names of the other devices around the house.<br />
<br />
Instead, the guest in their room could say, <''"Alexa, turn off the lights in this room"''> and the lights in that specific room would go off. If they request a list of devices or commands, only the devices you set up in that room will only be listed. <br />
<br />
To accomplish this, you will need to do the following:<br />
<br />
* For each "room" you will need to have a separate app for that room<br />
** You will need to change the line in the '''Ask Alexa ''' IDE from "singleInstance: true," to "singleInstance: false," (this is currently line 26 in version 2.2.2)<br />
[[file:AAIDEAdv1.png|700px]]<br />
** You will load up another version of '''Ask Alexa ''' from the SmartThings Marketplace. It is recommended that you change the display name under Settings>>SmartApp Name to "Ask Alexa {room name}. Be sure to use the example name in the invocation name example (<<Settings><<Setup Ask Alexa>><<Invocation Name>>) to the name you set up for the room as the skill name.<br />
[[file:AANameAdv1.png|250px]] [[file:AASetup.png|250px]]<br />
* For each "room" you will need to create a separate Lambda function<br />
** For each instance of your SmartApp, you will need to associate the Oauth and Token with your Lambda code.<br />
[[File:AAAWSP10.png|700px]]<br />
** Each Lambda section will have its own unique Oauth and Token from the individual app<br />
* For each "room" you will need to create a separate skill.<br />
** You will name the invocation name the name of the room (placing, for example "this room" where "smart things" is below)<br />
[[file:AADevP1.png|701px]]<br />
**Each skill will require the ARN number from the associated Lambda function<br />
<br />
==Tips and Tricks==<br />
<br />
* The naming of your devices is extremely important for proper usage of '''Ask Alexa'''. If you have two devices named "Living Room" for example, if you ask to turn on that switch and a temperature monitor is also named that same thing, you may not get the results you desire. It is good practice to choose devices to use with '''Ask Alexa''' that have unique names. This also goes for the "labels" of the devices...you may not have empty (null) labels for any of the devices or the SmartApp will crash.<br />
* If you change any settings within you app (add/remove devices to the SmartApp, add/change modes or routines), you will need to get the proper "intents" and paste those into the Amazon Developer Site. See [[Ask_Alexa#Custom_Slot_Information]] for more information. <br />
* The longer your modes or routines are in length, the more likely Alexa will misunderstand what you are asking. Amazon recommends commands of less than three words or syllables.<br />
* By default, SmartThings adds exclamations points to is routines (for example, ''"Good Morning!"'') . While the '''Ask Alexa''' SmartApp attempts to reconcile this when evaluating what the Alexa hears, it is best practice to remove punctuation from your routines or modes.<br />
* Try speaking different ways to Alexa to get the results you want. For example, if you'd rather say the device action first, just append "using SmartThings" at the end to get the same result. For example, instead of <''"Alexa, ask SmartThings to turn on the living room"''> you could say <''"Alexa, turn on living room with SmartThings"''>. Please note that sometimes this doesn't work well depending on what you named the device or how the Alexa Enabled Device hears your commands. However, it is important to be creative in how you address Alexa. If you find that natural speech doesn't work and have a suggestion for another syntax for different types of devices, please contact the author of this app to have additional utterances created.<br />
<br />
==Troubleshooting==<br />
The following are common troubleshooting steps when working with '''Ask Alexa'''.<br />
<br />
* If you use 'smartthings' (one word) as you invocation for the skill and you find Alexa misunderstanding you and not initiating the skill, change the invocation word to 'smart things' (two words) as some users have found this to work considerably better.<br />
* There have been reports that sometimes the URL for the Setup Variables presented in the live logging will not show completely, with a portion of it being replaced with [TRUNCATED]. This is an issue with the SmartThings environment. If you encounter this, within your mobile device scroll down on the Setup Variables page. You will find the full address of the setup page. Copy this and send it (possibly via e-mail) to yourself so you can perform the setup actions using a desktop computer.<br />
[[File:AASetupURL.png|250px]]<br />
* If you see an error similar to below about a mode or routine being missing, this indicates you may have deleted one of these before removing it from '''Ask Alexa'''. To prevent issues, the list will be updated to indicate which modes or routines you need to remove from the list for proper operation. You may also see this situation when you delete an Echo device association with a room. The list presented will mark the missing device, and it should be removed from the list to ensure proper '''Ask Alexa''' operation.<br />
[[File:AAMissingMode.png|250px]]<br />
* If you can use the Amazon Developer simulator with Ask Alexa, but you get an error with the exact same command with voice, check your country selection in both the app and the developer's site. These should match and only US is supported (However, it appears UK DOES work).<br />
* When the application does not operate correctly or as you would expect, please check http://status.smartthings.com/ to ensure the SmartThings environment is working properly. If the SmartApp suddenly stops working, most of the time it is because of an outage or degraded service with SmartThings' cloud environment. Since '''Ask Alexa''' is also heavily based in the Amazon cloud environment, it is also recommended to check the status of those sites as well via http://status.aws.amazon.com/<br />
* There is a known issue where, after editing a macro, the application returns to the main SmartThings app instead of the '''Ask Alexa''' main interface. SmartThings is aware of this and is working on a resolution. This message will be removed when this issues is resolved.<br />
* Removal and renaming of internal SmartThings items (like modes and routines) or changing internal components to '''Ask Alexa''' (such as deleting macros, or renaming extensions) is not well supported in SmartThings. For example, if you have a SmartThings mode that is used in '''Ask Alexa''', deleting this from the SmartThings app BEFORE removing it from '''Ask Alexa''' could result in '''Ask Alexa''' getting confused and giving you an error is the GUI or during operation. Another observed behavior is when you have a weather report within voice report. If you plan to delete the weather report, you should remove it from all areas of the app before deleting it.<br />
* While it is expected that you can upgrade to new versions seamlessly, there are situations where internal variables within the code changes or an old scenario conflicts with new code revisions. If you upgrade and find the application no longer performs as expected, it is recommended that you remove the application completely and start from scratch with new code (this only applies to the code in SmartThings. The Lambda code and Skills data should not be affected by variables unless you change your devices).<br />
* If you receive an error in the app while working with routines, macros and devices, please be sure these items do not have commas, exclamation points, or apostrophes in them. Also, numeric values (1, 2, 3, etc) should be left out in most circumstances from devices and macros. In addition, ensure you have not inadvertently created a 'null' routine...this is a routine you may have attempted to create but abandoned. These will show up in your SmartThings IDE under you Installed SmartApps. If this happens, simply delete the routine via the IDE (<<My Locations>>, <<List SmartApps>>) by tapping <<Edit>> in the upper left corner and the <<Update>> commands will turn into <<Delete>>.<br />
<br />
[[File:AAInstalledSA.png|700px]]<br />
<br />
* When naming your macros, routines, aliases, devices or modes, ensure you don't use words that might sound the same but could be spelled differently. For example, "Kris", "Bryan", "Jon" could be heard as "Chris", "Brian" and "John", respectively. Unfortunately, while sounding the same, the app does not account for different spellings of these types of names. Therefore, it is recommended you stay away from words like this. If you must use these, it is recommended that you set up aliases with different spellings of the same name.<br />
* When making a change to your environment (add/remove devices/aliases, create new modes, etc.) you should go through the setup steps again to capture any new custom slot information. This is required so '''Ask Alexa''' and the Amazon developer site knows the 'nouns' and 'verbs' to use to process your requests.<br />
* As mentioned in the [[Ask_Alexa#Tips_and_Tricks]] section, naming (labels) of your devices are rather important. In addition, even if you name everything uniquely, there are still areas where Alexa will respond with ''"You have multiple devices that are named <device name> in your SmartThings SmartApp. Please rename these items to something unique so I may properly utlize them."''. This could be caused by you choosing the same device for different functions. For example, you can choose a thermostat (Let's say "office") and also choose it for your temperature reading or humidity sensor. This will cause an issue as Alexa has no way of understanding the context of a device that is listed multiple times. It is best practice to not only name you devices uniquely, but use them once within your device setup. For situations where you can't name devices differently, you can use the alias function(see [[Ask_Alexa#Allow_Device_Aliases]]) to utilize different names for the devices in your SmartThings account.<br />
* If you receive an error similar to this when attempting to add a new extension (like a message queue):<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the extension code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
* If you receive feedback that SmartThing SmartApp returned an error, but you see nothing in your IDE Live Logging, you may have an issue with your Application ID or Authentication token. Re-run the setup to get the proper information into your Lambda code. (See [[Ask_Alexa#Finalizing_The_Function_Code]])<br />
* If you are unable to find the Alexa Skill Kit when setting up the Event Triggers ([[Ask_Alexa#Configure_Triggers]]), be sure you have set up your account in one of the supported datacenters (i.e US East (N Virginia), US West (Oregon), etc (see [[Ask_Alexa#AWS.2FLamba_Code]])<br />
* If you find behavior that is not what you would expect from your devices, try changing your syntax of how you are referencing the device. For example, instead of <''"Alexa, tell SmartThings to turn on the Kitchen"''> try a simplistic version such as <''"Alexa, tell SmartThings Kitchen on"''>. If you find a specific syntax works better for you but is not being recognized, you may want to create (or ask for community assistance) a custom utterance for your situation. If it works well for you, you can submit that to the author of '''Ask Alexa''' for inclusion in future updates.<br />
* If you have a custom message (or a pre or post message within the voice report macro) it is recommended to use proper punctuation. This means to end the message with a period, question mark, or exclamation point. This will ensure Alexa pauses if you have a continuing message at the end of your macros.<br />
* While the Lambda accounts are "free" for the most part, you should monitor your usage as much as you can to ensure you know the volume of calls being made to your account. Amazon has some fantastic tools to accomplish this via the main dashboard of your AWS account. The dashboard can also be useful in troubleshooting errors within your application.<br />
<br />
[[file:AAAWSOpen.jpg|700px]]<br />
* If you get the error "There was an error with the requested skills response" from Alexa but the action still happens, what may be happening is that the response was taking too long to get back from SmartThings to the Amazon Lambda code. To help reduce these errors, go to your Lambda code at [https://aws.amazon.com Amazon AWS site] and find section toward the bottom of the page labeled <<Basic Settings>>.Change the <<Timeout>> section to a larger number (6 to 20 seconds should be more than enough time). You can also increase the amount of memory that your Lambda code uses. This MAY result in slightly faster response from the '''Ask Alexa''' skill; however, increasing the timing or memory too much could result in a monthly charge from Amazon. If you do increase these settings, be sure to monitor your usage closely through the Amazon tools. <br />
<br />
[[File:AATimeout.png|700px]]<br />
* '''Ask Alexa''' keys off the labels of the devices; these are what you use to address the device. If these labels are not unique or used multiple time within the SmartApp you will receive a warning at the top of the main interface page.<br />
<br />
[[File:AAWarning.png|250px]]<br />
<br />
To fix a multiple device issue, be sure to examine all of the main interface devices to ensure they are not used more than once. For example, a dimmer can also be a switch, and a motion sensor may also show up in a temperature listing. <br />
<br />
For null device labels, be sure to check the device within the IDE area <<My Devices>> to ensure the label is not blank.<br />
<br />
==Support==<br />
To obtain support for this app, you have a couple of options:<br />
<br />
* A Slack channel has been set up at https://askalexa.slack.com . You must be invited to this app and have a Slack account. This will allow real time conversation and troubleshooting with the developer to get to the bottom of any issues you might be having.<br />
* For general questions about the app, please visit the official forum for this app on the SmartThings Community Page: https://community.smartthings.com/t/release-ask-alexa/46786/<br />
<br />
==Roadmap==<br />
There are many things that can be added to this application. Be sure the visit the forum for this app (See above) for this app to request something be added to the road map. In addition, donations will help speed up development of new features. You can donate via this page: https://paypal.me/mstruck . If you are into the bitcoin market, you can also send a donation to this wallet: 1CMgaiKgBfojTBCLpHLfa9KvcrW3cNxVpm (QR Code below)<br />
<br />
[[File:MSWallet.png]]<br />
<br />
Please note that these are only proposed updates...There is currently no timeline to implement these, or any guarantee that they will be implemented at all.<br />
<br />
* % control for window shades<br />
* Continue to improve the setup process (started in 2.3.5a)<br />
* Restrictions based on which speaker is being spoken to (2.3.9)<br />
<br />
==Frequently Asked Questions (FAQs)==<br />
'''Question''': Why do I have to update the Developer JSON every time I change something in my app?<br />
<br />
'''Answer''': The framework of the app allows for great voice recognition as only items that you set up in your SmartApp are being scanned for. Technically, you could simply have every device in your environment from the beginnig. However, that increases the chance of a misunderstanding by Alexa. <br />
<br />
'''Question''': What colors does '''Ask Alexa''' support?<br />
<br />
'''Answer''': '''Ask Alexa''' supports all of the same colors supported by native SmartThings app:<br />
Soft White, Warm White, Daylight White, Cool White, White, Alice Blue, Antique White, Aqua, Aquamarine, Azure, Beige, Bisque, Blanched Almond, Blue, Blue Violet, Brown, Burly Wood, Cadet Blue, Chartreuse, Chocolate, Coral, Corn Flower Blue, Corn Silk, Crimson, Cyan, Dark Blue, Dark Cyan, Dark Golden Rod, Dark Gray, Dark Green, Dark Khaki, Dark Magenta, Dark Olive Green, Dark Orange, Dark Orchid, Dark Red, Dark Salmon, Dark Sea Green, Dark Slate Blue, Dark Slate Gray, Dark Turquoise, Dark Violet, Deep Pink, Deep Sky Blue, Dim Gray, Dodger Blue, Fire Brick, Floral White, Forest Green, Fuchsia, Gainsboro, Ghost White, Gold, Golden Rod, Gray, Green, Green Yellow, Honeydew, Hot Pink, Indian Red, Indigo, Ivory, Khaki, Lavender, Lavender Blush, Lawn Green, Lemon Chiffon, Light Blue, Light Coral, Light Cyan, Light Golden Rod Yellow, Light Gray, Light Green, Light Pink, Light Salmon, Light Sea Green, Light Sky Blue, Light Slate Gray, Light Steel Blue, Light Yellow, Lime, Lime Green, Linen, Maroon, Medium Aquamarine, Medium Blue, Medium Orchid, Medium Purple, Medium Sea Green, Medium Slate Blue, Medium Spring Green, Medium Turquoise, Medium Violet Red, Midnight Blue, Mint Cream, Misty Rose, Moccasin, Navajo White, Navy, Old Lace, Olive, Olive Drab, Orange, Orange Red, Orchid, Pale Golden Rod, Pale Green, Pale Turquoise, Pale Violet Red, Papaya Whip, Peach Puff, Peru, Pink, Plum, Powder Blue, Purple, Red, Rosy Brown, Royal Blue, Saddle Brown, Salmon, Sandy Brown, Sea Green, Sea Shell, Sienna, Silver, Sky Blue, Slate Blue, Slate Gray, Snow, Spring Green, Steel Blue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White Smoke, Yellow and Yellow Green<br />
<br />
==How Do I Upgrade Ask Alexa==<br />
There are 3 different scenarios for upgrading '''Ask Alexa'''; each depends on what was changed in the release. Please refer to the release notes to determine which scenario applies to your situation. For a scenario 2 and 3 upgrade, you should be familiar with the installation processes for the Amazon sites listed here: [[Ask_Alexa#Developer_and_Lambda_Code_Installation]]<br />
<br />
'''Scenario 1 - IDE code change:''' Only the code (either main code, or extension code) has changed. If you have your IDE linked to GitHub (see: [[Ask_Alexa#Advanced_Installation]]), then you simply click the <<Update from Repo>> button at the top of the SmartThings IDE and check the apps that you want to update. Be sure to <<Save>> the files and <<Publish>> them in order to see the changes in your SmartThings mobile application.<br />
<br />
In addition, in a Scenario 1 installation you can also upgrade the applications using the Community Installer (Free Marketplace). See here for more information: [[Community_Installer_(Free_Marketplace)]]<br />
<br />
'''Scenario 2 - Lambda code change:''' It is rare that JUST the Lambda code will change. Sometime you must use the processes in Scenario 1 and this process to get the full upgrade. There are two ways to upgrade your Lambda code. Both require you to go to <<Settings>> <<Setup Variables>> and get your setup URL. <br />
* While displaying the setup variables on a PC, you will simply click the Lambda code link. You will be presented with code on the screen with your security parameters already in the code. You simply copy this code to https://aws.amazon.com and you are done. <br />
* For a more manual method, go into the AWS site and copy the current Token and Application ID from the current code. Copy the new code from this location (https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/Node.js) and paste it into the code area. Then paste the Token and Application ID back into the appropriate location.<br />
<br />
[[File:AAAWSP10.png|700px]]<br />
<br />
'''Scenario 3 - Developer area changes:''' The easiest method of upgrading is to go to <<Settings>><<Setup Ask Alexa>><<Display Setup Variables Link>> and get your setup URL. While displaying this on a PC, you will simply click the Developer code link (or download the code). If you display the code, copy the entire page of JSON code and then paste it to the <<JSON Editor>> section of the Developer Build section. <br />
<br />
[[File:AADevP2.png|701px]]<br />
<br />
If you downloaded the code, simply upload the code to the site. <br />
<br />
[[File:AADevP3.png|701px]]<br />
<br />
Save and build your interaction model and you are complete.</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Alexa_Virtual_Device_Creator&diff=13899Alexa Virtual Device Creator2018-12-12T16:24:06Z<p>MichaelStruck: </p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
'''Alexa Virtual Device Creator''' is a Smartapp for the SmartThings home automation system. This application allows you to create virtual devices (Momentary and virtual dimmers, motion detectors) within the application and not requiring you to use the SmartThings IDE. <br />
<br />
==Summary==<br />
[[File:Alexa@2x.png]]<br />
<br />
'''Category:''' My Apps<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 11:23, 20 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
===Latest Version===<br />
<br />
The latest version of the application is as follows (as of 8/29/18):<br />
'''Alexa Virtual Device Creator:''' <br />
Version: 1.0.2<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/alexa-virtual-switch-creator.src/alexa-virtual-switch-creator.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''Alexa Virtual Device Creator''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Requirements==<br />
The following are the basic requirements to use '''Alexa Virtual Device Creator''':<br />
<br />
*A mobile device running the SmartThings mobile application.<br />
*(Optional) Alexa Echo Device<br />
*(Optional) Some method to tie the changing of the virtual device to a SmartThings process (like Ask Alexa and its macros/extensions, or WebCoRE)<br />
<br />
== Definitions ==<br />
*'''SmartApp:''' Add-in to the SmartThings mobile application that allows for functionality outside of what is provided by default. These SmartApps are not stand alone programs, but only operate within the SmartThings mobile application. SmartApps are open source and written in a form of the Java programming language called “groovy”. <br />
*'''IDE:''' Abbreviation for “Integrated Development Environment”. In the context of the SmartThings environment, this is the web site located at http://ide.smartthings.com that allows for advanced functionality within the SmartThings environment. This allows you to set up custom devices and applications that appear within your SmartThings mobile application.<br />
*'''GitHub:''' A web-based repository that allows for distribution revision control and source code management functionality.<br />
*'''URL:''' Uniform Resource Locator, or basically the address of a web site or online resource, such as http://www.smartthings.com<br />
*'''Virtual Switch:''' A device within the SmartThings environment that functions like a regular switch (think of a button or a light switch). However, the device is “virtual” and does not exist as a physical device. While there are various types of virtual switches, three types of virtual devices can be created using '''Alexa Virtual Device Creator''': a virtual on/off dimmer called an "Alexa Switch" and a Momentary Button Tile.<br />
**'''Alexa Switch:''' A custom type of virtual switch that acts as both a normal on/off switch and as a dimmer. This type of switch can be toggled “on” or “off” and can also be set to different levels (0 to 100) of “brightness”. This type of device is useful for controlling scenarios that need distinct "on" or "off" control along with the volume of a speaker or setting different temperatures on a thermostat. This switch also sends on or off commands regardless of its state; in other words, if it is on and you tell it to turn on, it will still react within other applications as if it was off turning to on. This allows your automations to maintain control of devices regardless if they are interacted with manually or through other automation. You also have the ability to disable the capability of sending on/off commands when the setLevel action is performed.<br />
**'''Momentary Button Tile:''' A type of virtual switch that behaves like a spring-loaded physical switch (think of a doorbell button). In other words, the switch is normally in a closed ("off") state and when pressed, it will toggle from the default state to the opposite state, and then reset again (''off->on->off''). This type of device is good for items that just need a trigger, such as changing modes or routines. Please note that when using a momentary button tile with the Echo, whether you command it to turn "on" or "off", the result will be the same: it will send the same "push" command and the switch itself will then reset to the "off" state.<br />
**'''Virtual Motion Detector:''' A virtual device that can be manually or programmatically set to a condition (motion/no motion). This type of device is useful use in Alexa Routines where the application can act upon a change in the motion (or no motion) condition of the device.<br />
<br />
==Alexa Virtual Device Creator Installation==<br />
<br />
There are multiple methods to get '''Alexa Virtual Device Creator''' installed into the SmartThings environment. You can use the Community Installer, manually install the code from the links in GitHub, or use the IDE/GitHub integration within SmartThings.<br />
<br />
===Community Installer (Free Marketplace)===<br />
<br />
To install '''Alexa Virtual Device Creator''' via the Community Installer, please see here: http://thingsthataresmart.wiki/index.php?title=Community_Installer_(Free_Marketplace)<br />
<br />
Simply find '''Alexa Virtual Device Creator''' in the list, and install ALL pieces of the application. If you are upgrading, click the <<Update>> button.<br />
<br />
[[File:CI-Search.png|250px]]<br />
<br />
===Manual Code Load===<br />
<br />
The code for the main parent app is found on the GitHub site:<br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/alexa-virtual-switch-creator.src/alexa-virtual-switch-creator.groovy<br />
<br />
*While on the GitHub site, find the Raw button and click it. This will bring up a non-formatted page with just the code present. Select all of the code (typically CTRL+A) and copy It (typically CTRL+C).<br />
<br />
[[File:GitHub_raw.png]]<br />
<br />
*Next, point your browser to you SmartThings IDE (http://ide.smartthings.com) and '''Log In'''.<br />
<br />
[[File:loginscreen.jpg|700px]]<br />
<br />
*Once you are logged in, find the '''My SmartApps''' link on the top of the page. Clicking '''My SmartApps''' will allow you to produce a new SmartApp.<br />
<br />
[[File:MySmartApps.png|700px]]<br />
<br />
*Find the button on this page labeled '''+New SmartApp''' and click it.<br />
<br />
[[File:+NewSmartApp.png|700px]]<br />
<br />
*Since you already have the code in your computer’s clipboard, find the tab along the top section called '''From Code'''. In the area provided, paste (typically CTRL+V) the code you copied from GitHub. Click '''Create''' in the bottom left corner of the page.<br />
<br />
[[File:NewSmartAppCreate.png|700px]]<br />
<br />
*This will bring up another page, with the code now formatted within the IDE. If the code was copied correctly, there are no other steps except to save and publish the code. In the upper right corner of the page, find and click '''Save'''. Now, click '''Publish (For Me)''', and you should receive a confirmation that the code has been published successfully.<br />
[[File:SavePublish.png]]<br />
<br />
===Advanced Installation===<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found on the SmartThings web site [[http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git]].<br />
<br />
Once you have integration, the for pieces of code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page (this will only appear after you integrate with GitHub)<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''Alexa Virtual Device Creator''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''Application:''' smartapps/michaelstruck/alexa-virtual-switch-creator.src/alexa-virtual-switch-creator.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new apps should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
===Upgrade from Alexa Virtual Switch Creation===<br />
<br />
If you are upgrading from the '''Alexa Virtual Switch Creation''' the upgrade process should be rather simple. You can upgrade the code in the links above and simply upgrade the code. In addition, you can use the 'Community Installer' (http://thingsthataresmart.wiki/index.php?title=Community_Installer_(Free_Marketplace)). If you have your IDE linked to GitHub, you should also be able to upgrade the code directly through this link. <br />
<br />
You MAY notice the application name within your Mobile Interface. To change the name display, go to <<About Virtual Device Creator>> and go to the bottom of the screen to edit this text.<br />
<br />
==In App Virtual Device Creation==<br />
<br />
While it is perfectly acceptable to create virtual devices via the SmartThings IDE, this is rather inconvenient when you are away from a computer. Instead, '''Alexa Virtual Device Creator''' gives you the ability to create virtual devices within the SmartApp directly. <br />
<br />
'''Notice'''<br />
The devices you create within '''Alexa Virtual Device Creator''' are considered 'child devices' of the SmartApp and you <br />
could receive errors should you attempt to remove '''Alexa Virtual Device Creator''' and the devices are used in other <br />
SmartApps.<br />
<br />
First, like the Alexa Switch installation, you must load the code as a new device type: <br />
<br />
*To create the new virtual devices, copy the code from the following GitHub location:<br />
<br />
'''Alexa Switch:''' https://github.com/MichaelStruck/SmartThingsPublic/blob/master/devicetypes/michaelstruck/alexa-switch.src/alexa-switch.groovy<br />
'''Momentary Button Tile:''' https://github.com/MichaelStruck/SmartThingsPublic/blob/master/devicetypes/michaelstruck/momentary-button-tile.src/momentary-button-tile.groovy<br />
'''Virtual Motion Detector:''' https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/virtual-motion-detector.src/virtual-motion-detector.groovy<br />
<br />
*Be sure to click the '''Raw''' link, and then select all of the code (typically CTRL+A), and then copy it (typically CTRL+C) to your computer’s clipboard.<br />
*Go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and click the link at the top labeled '''My Device Types'''. <br />
*Click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
*Choose '''From Code''' and you will be presented with an empty area where the code you copied earlier can be placed. In the open area in the middle paste (typically CTRL+V) this code.<br />
*Click '''Save''' and then click '''Publish (For Me)'''.<br />
<br />
From here, you may exclusively use the '''Alexa Virtual Device Creator''' SmartApp to create your virtual devices. <br />
<br />
To create a new device, enter the name of the device in the <<Device Label>> area. Be sure to choose a unique name.<br />
<br />
Next, you will need to choose the type of device you would like to create from the <<Device Type...>> area. Currently, your choices are either a Virtual Motion Detector, Alexa Switch or a momentary button tile. The difference in the switches is explained here: [[Alexa Virtual Device Creator#Definitions]]. <br />
<br />
When you enter the above information, the <<Tap to add device>> option will appear. Tapping this area should create your virtual device. If there were any errors in creating the device they will be listed on the screen. The most typical error is that you have not loaded the code properly in the above steps. Ensure the device code is saved and published properly. <br />
<br />
Clicking <<Save>> or "<" to bring you back to the main '''Alexa Virtual Device Creator''' page.<br />
<br />
==Limitations==<br />
There are some limitation you should be aware of when using this SmartApp<br />
<br />
* If you delete the app (and the devices it created are not being used), the devices WILL disappear.<br />
* If you attempt to delete the app and the devices it created ARE being used, the app will NOT delete. You will need to disassociate the devices with the apps you have attached them to.<br />
* YOU MUST use the DTHs I have included above to use this app. It will NOT create generic virtual devices<br />
* You may not be able to delete the app if a device you created with it is still being used else where in SmartThings<br />
* When you create a device, be sure you ‘discover’ it via Alexa’s own app<br />
* If you manually create a virtual device via the IDE, it will NOT show up in this app (but it will also not delete the device when you uninstall the app). So, you could technically use the special DTHs and create your own virtual devices.</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=13856GE Z-Wave Motion Sensor Switch2018-12-06T16:44:52Z<p>MichaelStruck: /* Latest Version */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 12/6/18):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.5<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=13855GE Z-Wave Motion Sensor Dimmer Switch2018-12-06T16:44:20Z<p>MichaelStruck: /* Summary */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 12/6/18):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.5<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed || Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=13803GE Z-Wave Motion Sensor Switch2018-11-26T22:31:19Z<p>MichaelStruck: /* Summary */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 11/22/18):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.4b<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=13802GE Z-Wave Motion Sensor Dimmer Switch2018-11-26T22:31:03Z<p>MichaelStruck: /* Summary */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 11/22/18):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.4b<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed || Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Ask_Alexa&diff=13767Ask Alexa2018-11-22T23:53:14Z<p>MichaelStruck: /* Limitations */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
'''Ask Alexa''' is an add-in to the SmartThings mobile application that allows you to control a broad array of devices with your Amazon Alexa Enabled Devices. When installed along with the proper services at AWS (Amazon Web Services), a simple voice command allows you to control your devices along with querying their status. Simply "Ask" Alexa to do something within your SmartThings environment and she will respond!<br />
<br />
'''Ask Alexa''' can replace the basic integration between SmartThings and Alexa. In the default SmartThings integration, you may only control switches and thermostats and there is limited feedback to ask the status of the devices. '''Ask Alexa''' improves this integration by not only expanding the devices you can control with your voice, but you can now get real-time feedback on inside temperatures, door, switch, dimmer status, etc, and control modes, Smart Home Monitoring security status, run routines and set up complex macro-like events using natural speech. You can even interface other SmartThings SmartApps into '''Ask Alexa''' by using the message queue function and access another popular community-written app, WebCoRE, directly from '''Ask Alexa''' (and in turn, '''Ask Alexa''' macros can be referenced within the WebCoRE application itself).<br />
<br />
No matter how you want to address your home, from a more "Star Trek" experience ("''<Computer, tell studio to turn the lights on"''>) to natural language (<''"Alexa, tell the house I am cold"''>), '''Ask Alexa''' is the go-to app for SmartThings/Alexa integration.<br />
<br />
[[File:AAMainScreen.jpg|890px]]<br />
<br />
==Summary==<br />
[[File:AskAlexa512.png|256px]]<br />
<br />
'''Category:''' My Apps<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Code contributions:''' Keith DeLong, Barry Burke, foxxyben & M3Rocket (utterances), Jimxenus/larry-fuqua (misspellings/logic issues in the GUI), jhamstead and Yves Racine for Ecobee code<br />
<br />
'''Documentation contributions:''' Keith DeLong, Jason Headley, Belgarion, Barry Burke, Andrea Bianco, Yves Racine, Todd M(@Pantheon)<br />
<br />
===Latest Versions===<br />
<br />
{| class="wikitable"<br />
|+The latest version of each of the applications listed in this document (as of 6/16/18)<br />
|-<br />
! '''Ask Alexa Code''' !! Area Used !!'''Version''' !! '''Location'''<br />
|-<br />
| '''SmartApp Code''' || SmartThings IDE || ''2.3.9f'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
|-<br />
| '''Node.js''' || Lambda code for aws.amazon.com (manual install only) || ''1.3.1a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/Node.js<br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|+Extensions<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues]|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
|-<br />
| '''Rooms/Groups Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_Rooms/Groups]|| SmartThings IDE || ''1.0.4b'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
|-<br />
| '''Schedules Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Schedules]|| SmartThings IDE || ''1.0.4a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
|-<br />
| '''Voice Report Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Voice_Reports]|| SmartThings IDE || ''1.0.9'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
|-<br />
| '''Weather Report Code''' [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Weather_Reports]|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy <br />
|}<br />
<br />
===Compatibility With Other SmartApps===<br />
'''Ask Alexa''' isn't limited to just the standard devices that come with SmartThings. It can also work directly with other SmartApps and even some custom Device Type Handlers. The following is the current list of compatible SmartApps/DTHs...Items with (2.0) designation already or will support the new message queue structure (see [[Ask_Alexa_-_Message_Queues]]):<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''SmartApp/Custom Device Type''' !! '''Supported Features''' !! '''Author'''<br />
|-<br />
| '''NST Manager''' || ''Message queue (2.0) and thermostat reports'' || Anthony Santilli<br />
|-<br />
| '''WebCoRE''' || ''Message queue (2.0)'' || Adrian Caramaliu<br />
|-<br />
| '''My Ecobee Device & Service Manager (MyEcobeeInit)''' || ''Message queue (2.0) - Comfort & Energy Saving tips for your Ecobee device, ecobee Alerts, exception events and tstat reports'' || Yves Racine<br />
|-<br />
| '''Zoned Heating/Cooling Solutions (ecobeeSetZoneWithSchedule, ScheduleRoomTempControl, ScheduleTstatZones)''' || ''Message queue (2.0) for reporting heating/cooling zoned scheduling events'' || Yves Racine<br />
|-<br />
| '''Device Monitor''' || ''Message queue (2.0) '' || Eric Maycock<br />
|-<br />
| '''MonitorAutomaticCar''' ||''Message Queue (2.0) for reporting hard acceleration/brake/ignition off/on and other Automatic events'' || Yves Racine<br />
|-<br />
| '''OSRAM Lighting Controls-DTH''' [https://raw.githubusercontent.com/gkl-sf/SmartThings/master/osram-bulb-HA.groovy] || ''Loop/Pulse'' || gkl-sf<br />
|-<br />
| '''Foobot Air Quality Monitor-DTH'''[https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/foobot-air-quality-monitor.src/foobot-air-quality-monitor.groovy] || CO2/Particles/VOCs/Temperature/Humidity || Michael Struck/Adam V<br />
|-<br />
| '''Big Talker''' || ''Message Queue (2.0)'' || Brian Lowrance<br />
|-<br />
| '''Lock Manager''' || ''Message Queue (2.0)'' || Erik Thayer<br />
|-<br />
| '''RemindR''' || ''Message Queue (2.0)'' || Bobby Dobrescu <br />
|-<br />
| '''Smart GCal Control''' || ''Message Queue (2.0)'' || Anthony Pastor (infofiend)<br />
|-<br />
| '''Sports Notifications''' || ''Message Queue (2.0)'' || Eric Luttmann<br />
|-<br />
| '''Spruce Status'''|| ''Message Queue (2.0)'' || Barry Burke<br />
|-<br />
| '''Open Source Ecobee Thermostat, Sensors and Companion SmartApps'''|| ''Message Queue 2.0 for Ecobee Alerts and Reminders'' || Barry Burke<br />
|-<br />
| '''My Ecobee stats generation Smartapps'''|| ''Message Queue (2.0) for reporting ecobee daily/weekly/monthly runtime (HomeIQ) stats '' || Yves Racine<br />
|-<br />
| '''MyNeurio & MyNeurioAppliance Service Managers'''|| ''Message Queue (2.0) for reporting exception events and summary Energy Consumption & Generation reports (Daily, Weekly, Monthly)'' || Yves Racine<br />
|-<br />
| '''MyAutomatic Service Manager'''|| ''Message Queue (2.0) for reporting exception events and Driving Summary Reports (Daily, Weekly, Monthly)'' || Yves Racine<br />
|-<br />
| '''MonitorAndSetEcobeeHumidity'''|| ''Message Queue (2.0) for humidity control notifications - using HRV/ERV/Humidifier/Dehumidifier devices connected to your ecobee'' || Yves Racine<br />
|-<br />
|-<br />
| '''MyFlair Devices (Puck, Vent, HvacUnit) & Service Manager'''|| ''Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions'' || Yves Racine<br />
|-<br />
| '''MyNextManager & Devices (Tstat, Alarm, Cam)'''|| ''Message Queue (2.0) for reporting event summary reports (Daily, Weekly) & exceptions'' || Yves Racine<br />
|-<br />
| '''Room Occupancy'''||''Control over the occupancy of a room using a custom DTH, Message Queue (2.0)'' || Bangali<br />
|-<br />
| '''GE Motion Switch/Dimmer'''||''Verbal control over the operating mode of the switch (models 26933 and 26931)'' || Michael Struck<br />
|-<br />
|}<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use '''Ask Alexa''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Requirements==<br />
<br />
The following are the basic requirements to use '''Ask Alexa''':<br />
<br />
*A mobile device running the SmartThings mobile application<br />
*An Amazon Alexa Enabled Device (it is not required the device be integrated with SmartThings, but doing so won't interfere with '''Ask Alexa''')<br />
*Devices (Switches, lighting, thermostats, etc) that are operational within the SmartThings environment. To help Alexa understand your devices, they should each be uniquely named in your account. <br />
*An AWS Lambda and developer account<br />
**For the developer account, please ensure you create the account under the same account you used for your Amazon Alexa Enabled Device setup. See the steps to create the account [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide here].<br />
**For the AWS/Lambda account (to host your code), follow the instructions [https://aws.amazon.com/lambda/getting-started/ here]. Please note that you MAY need to provide a credit card for the setup. Be sure to read the pricing structure for AWS Lambda space [https://aws.amazon.com/lambda/pricing/ here].<br />
<br />
==Privacy Statement==<br />
'''Ask Alexa''' leverages an external web hosting service to automate some of the setup and operation of the SmartApp. To ensure complete transparency, you may read the privacy statement here: [http://ask-alexa.com/privacy.html]<br />
<br />
==Limitations==<br />
* The instructions presented here are for US installations only. While many of the concepts are universal, all screen shots and languages assume US/English installations. If you find some slight variation are needed in these instructions please update the wiki or contact the author of this application.<br />
<br />
== Definitions ==<br />
<br />
Throughout this document there will be some specific terms relating to the SmartThings and Amazon development environments.<br />
<br />
===SmartThings/Ask Alexa/General Definitions===<br />
*'''SmartApp:''' Add-in to the SmartThings mobile application that allows for functionality outside of what is provided by default. These SmartApps are not stand alone programs, but only operate within the SmartThings mobile application. SmartApps are open source and written in a form of the Java programming language called “groovy”.<br />
*'''Parent/Child SmartApp:''' A code structure within the SmartThings development environment where a single instance of a parent SmartApp can have multiple child SmartApps associated with it, allowing the single SmartApp to have multiple functions. '''Ask Alexa''' uses this structure for its extensions; there can only be one instance of the '''Ask Alexa''' SmartApp and each extension created within the parent SmartApp is actually an instance of the child SmartApp. This structure cuts down on repeated code within a single SmartApp.<br />
*'''Virtual Switch:''' A device within the SmartThings environment that functions like a regular switch (think of a button or a light switch). However, the device is “virtual” and does not exist as a physical device. Used mostly with [http://thingsthataresmart.wiki/index.php?title=Alexa_Helper Alexa Helper]. However, you can activate virtual switches using '''Ask Alexa''' as well.<br />
*'''Alias:''' In the context of '''Ask Alexa''', this is a name that is used as a place holder (or alias) for another device. This allows to have two devices named the same thing within your SmartThings app, but allows you to address them differently in '''Ask Alexa'''.<br />
*'''IDE:''' Abbreviation for “Integrated Development Environment”. In the context of the SmartThings environment, this is the web site located at http://ide.smartthings.com or https://graph-eu01-euwest1.api.smartthings.com/ (depending on your country) that allows for advanced functionality within the SmartThings environment. This allows you to set up custom devices and applications that appear within your SmartThings mobile application.<br />
*'''DTH:''' '''D'''evice '''T'''ype '''H'''andlers. This is code that is usually community written and allows third-party devices to operate in the SmartThings environment. A good example of this is the Nest Thermostat.<br />
*'''GitHub:''' A web-based repository that allows for distribution revision control and source code management functionality.<br />
*'''OAuth:''' Provides client applications a secure method for accessing resources on behalf of the resource owner. Within the context of SmartThings, certain custom applications that allow for remote access (such as remotely turning on or off a light) will require additional authentication. As the owner of the resource, you can authorize remote access to an application by enabling OAuth.<br />
*'''Access Token:''' A security identity that is linked to OAuth and in the context of SmartThings allows for remote control of a locations devices.<br />
*'''URL:''' Uniform Resource Locator, or basically the address of a web site or online resource, such as http://www.smartthings.com<br />
*'''REST:''' '''RE'''presentational '''S'''tate '''T'''ransfer is an architectural style, and an approach to communications that is often used in the development of Web services. In SmartThings, it is how external applications, such as Amazon's services, can interact the devices in your account, using the OAuth and Access Token as 'keys' to securely access these devices.<br />
*'''Text Field Variables:''' In the context of '''Ask Alexa''', these are variables that can be used in any text areas of the macros to give you 'short cuts' to commonly used text. Typically, they start and end with a percent sign, like %temp%. See [[Ask_Alexa#Text_Field_Variables]] for the variables currently available.<br />
*'''WebCoRE:''' '''W'''eb '''C'''ommunity's '''o'''wn '''R'''ule '''E'''ngine. Another SmartThings community developed application that defines 'pistons' to perform complex, decision-based automation. One of these events could be a trigger from '''Ask Alexa'''. More information can be found here: https://community.smartthings.com/t/webcore-beta-milestone-1/86153<br />
<br />
===Amazon/Alexa Development Definitions===<br />
*'''AWS:''' Amazon Web Services is a collection of cloud computing services that make up the on-demand computing platform offered by Amazon.com.<br />
*'''Lambda:''' An AWS service. Lambda lets you run code without provisioning or managing servers. With Lambda, you can run code for virtually any type of application or back-end service - all with zero administration. <br />
*'''A.S.K.:''' The Alexa Skills Kit is a collection of self-service APIs, tools, documentation and code samples that make it fast and easy for you to add skills to Alexa.<br />
*'''Invocation Name:''' This is the name you will "invoke" to communicate with the Alexa Enabled Devices, which in turn communicates with SmartThings and '''Ask Alexa'''. By default, the invocation name using in '''Ask Alexa''' is "smart things"; however, the invocation name can also be words like "home", or "house" to make command syntax smoother. You may even set up multiple skills, each with the name of a room, and have personalized responses for each room. For example, you could say <''"Alexa, tell the kitchen to turn off the lights"''> and affect the Kitchen, or <''"Alexa, turn the lights off in the bedroom"''> and only have the lights in the bedroom react.<br />
*'''Intents:''' An intent represents an action that fulfills a user’s spoken request. Intents can optionally have arguments called slots. <br />
*'''Custom Slots:''' A custom slot type is used for items that are not covered by Amazon’s built-in set of types and is recommended for most use cases where a slot value is one of a set of possible values. The values for the custom slots are generated for you via the Settings page. You will simply copy the provided data and paste it into the Amazon Developer Site. <br />
*'''Utterances:''' A structured text file that connects the intents to likely spoken phrases and containing as many representative phrases as possible.<br />
*'''JSON:''' is an abbreviation for ''JavaScript Object Notation'' is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. The Amazon ASK Development area uses JSON for sending input to and from the Alexa Enabled Devices. The basic structure of JSON looks like this:<br />
<br />
<pre style="display: inline-block;"><br />
{<br />
"intent": "DeviceOperation",<br />
"slots": [<br />
{<br />
"name" : "Operator",<br />
"type" : "LIST_OF_OPERATORS"<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
==How Ask Alexa Works==<br />
<br />
Unlike most SmartThings SmartApps, '''Ask Alexa''' works in concert with the external Amazon developer site, including the Lambda web service. However, the "heavy lifting" of determining the condition of your house, generating reports, and most of the feedback spoken by the Alexa Enabled Devices is actually produced by your SmartThings account, NOT the Amazon cloud services. See the diagram below for a bit more detail on this.<br />
<br />
[[File:AAFlow.png|700px]]<br />
<br />
<pre style="display: inline-block;"><br />
Thanks to Keith DeLong for the above diagram.<br />
</pre><br />
<br />
The user will query their Amazon device, and the Amazon "skill" simply looks for the nouns and verbs (keywords) of your speech and then send those key words to your SmartThings account. The '''Ask Alexa''' SmartApp processes this information, does its actions, and sends Amazon the text response to process through its text-to-speech function. Basically, the Alexa Enabled Device is not turning on your devices...your '''Ask Alexa''' SmartApp is doing the work.<br />
<br />
==Set up of your Alexa Enabled Devices==<br />
Setup of your Amazon Alexa Enabled Devices with SmartThings native functionality is NOT required to use '''Ask Alexa'''. '''Ask Alexa''' operates independently of the integration. However, to have a backup method of controlling your environment, or to use apps like [http://thingsthataresmart.wiki/index.php?title=Alexa_Helper Alexa Helper], you will need to follow the steps below. Please refer to your Amazon Echo documentation, use the Amazon Echo mobile app, or visit http://alexa.amazon.com for more information.<br />
<br />
[[File:EchoApp.png|right|200px]]<br />
* Configure your device on your home’s Wifi and ensured that it is functional<br />
* Configure the device to work with your SmartThings Devices [[https://support.smartthings.com/hc/en-us/articles/205275404-How-to-connect-Amazon-Echo-with-SmartThings]] (via the Amazon Echo application on your mobile phone or http://alexa.amazon.com. Setup within the Amazon Echo app is under ''Settings'' and ''Connected Home'')<br />
* Once SmartThings is properly configured, go into the Amazon Echo SmartApp within SmartThings (See image to the right) and click on the switches you intend to use. These can be real switches/dimmers, virtual switches or momentary button tiles<br />
* Click <<Done>>, then say to your Alexa Enabled Device ''<"Alexa, discover new devices">''<br />
* Within the Amazon Echo Application (NOT the SmartThings app), or http://alexa.amazon.com, you should now see the switches you have "Discovered"<br />
* If you later add switches to SmartThings, you will need to add them to Amazon Echo Smart App within SmartThings, then "Discover" them<br />
<br />
==Setting up your Amazon Lambda and Developer Accounts==<br />
To use '''Ask Alexa''' you will need to create two "free" accounts at Amazon. While the full instructions on setting up these accounts is outside of the scope of this document, very clear instructions are published by Amazon themselves:<br />
<br />
[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide '''Developer Account'''] <br />
<br />
[https://aws.amazon.com/lambda/getting-started/ '''Lambda Account''']<br />
<br />
Please note that these account are 'free' (see the information here[https://aws.amazon.com/free/]). Please be sure to ONLY sign up for the Lambda piece, and the 'basic' tier of service. You MAY be required to provide a credit card number, however, to open an account.<br />
<br />
[[File:AAMainAWS.jpg|700px]]<br />
<br />
'''Notice'''<br />
While the Lambda account is listed as free, if you generate excessive <br />
traffic from your account, Amazon WILL charge you. Fortunately, this <br />
level of traffic would need to exceed 5 million hits per month to account<br />
for even $1.00. So, while the accounts are 'free' for general use, full <br />
public distribution and use would definitely incur a fee if your volume <br />
is high enough.<br />
<br />
==Ask Alexa (SmartThings Code) Installation==<br />
<br />
There are multiple methods to get '''Ask Alexa''' installed into the SmartThings environment. You can use the Community Installer, manually install the code from the links in GitHub, or use the IDE/GitHub integration within SmartThings.<br />
<br />
===Community Installer (Free Marketplace)===<br />
<br />
To install '''Ask Alexa''' via the Community Installer, please see here: http://thingsthataresmart.wiki/index.php?title=Community_Installer_(Free_Marketplace)<br />
<br />
Simply find '''Ask Alexa''' in the list, and install ALL pieces of the application (including Extensions or 'child' applications). If you are upgrading, click the <<Update>> button.<br />
<br />
[[File:CI-AboutApp2.png|250px]]<br />
<br />
===Manual Installation===<br />
<br />
The code for the '''Ask Alexa''' SmartThings SmartApp is found on the GitHub site:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
<br />
While on the GitHub site, find the '''Raw''' button and click it. This will bring up a non-formatted page with just the code present. Select all of the code (typically CTRL+A) and copy It (typically CTRL+C).<br />
<br />
[[File:GitHub.png|700px]]<br />
<br />
<br />
*Next, point your browser to you SmartThings IDE for your country (i.e. http://ide.smartthings.com or https://graph-eu01-euwest1.api.smartthings.com) and '''Log In'''.<br />
<br />
[[File:loginscreen.jpg|700px]]<br />
<br />
*Once you are logged in, find the '''My SmartApps''' link on the top of the page. Clicking '''My SmartApps''' will allow you to produce a new SmartApp.<br />
<br />
[[File:MySmartApps.png|700px]]<br />
<br />
*Find the button on this page labeled '''+New SmartApp''' and click it.<br />
<br />
[[File:+NewSmartApp.png|700px]]<br />
<br />
*Since you already have the code in your computer’s clipboard, find the tab along the top section called '''From Code'''. In the area provided, paste (typically CTRL+V) the code you copied from GitHub. Click '''Create''' in the bottom left corner of the page.<br />
<br />
[[File:NewSmartAppCreate.png|700px]]<br />
<br />
*This will bring up another page, with the code now formatted within the IDE. If the code was copied correctly, there are no other steps except to save and publish the code. In the upper right corner of the page, find and click '''Save'''. Now, click '''Publish (For Me)''', and you should receive a confirmation that the code has been published successfully.<br />
[[File:SavePublish.png]]<br />
<br />
===OAuth Setup===<br />
'''Ask Alexa''' will need to be accessed by the Amazon servers in order to operate correctly. As such, OAuth is REQUIRED for this application.<br />
<br />
To enable OAuth, first find and click the '''App Settings''' button in the upper right corner of the page.<br />
<br />
From here, find the '''OAuth''' section toward the bottom of the page. <br />
<br />
[[File:OAuthBtn.png|700px]]<br />
<br />
Clicking the '''OAuth''' link will reveal a button labeled '''Enable OAuth in Smart App'''. Click this button. The screen will change, giving you a unique code for your '''Client ID''' and '''Client Secret'''. These are the foundations of the security of your app and should be kept secret. You do not need to memorize or write down these codes; nor do you need to add any other information to this page. OAuth simply needs to be enabled for '''Ask Alexa''' to operate.<br />
<br />
[[File:OAuth.jpg|700px]]<br />
<br />
The final step is to press the '''Update''' button at the bottom left corner of the screen, or go back to your code by using the button in the upper-right region of the page, then '''Save''', then '''Publish''' the SmartApp again. <br />
<br />
[[File:SavePublish.png]]<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
Next, you will need to load up the child extension SmartApps. This code for these are located here. Installation is exactly the same for each one. Just repeat the steps below for each set of code.<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy<br />
<br />
The steps for installation are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
===Advanced Installation===<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of SmartThings SmartApp code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found on the SmartThings web site [[http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git]]<br />
<br />
'''Please Note:''' <br />
This process only applies to installing the SmartThings SmartApp. <br />
This process DOES NOT update any of the code on the Amazon developer site; <br />
you will need to follow the process [[Ask_Alexa#Building_The_Skill]] to <br />
install or update your skill information.<br />
<br />
Once you have integration, the four pieces of code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page (this will only appear after you integrate with GitHub)<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''Ask Alexa''' SmartApp code, enter the information as you see it below:<br />
{| class="wikitable"<br />
!'''Owner'''!!'''Name'''!!'''Branch'''<br />
|-<br />
| MichaelStruck || SmartThingsPublic || Master<br />
|}<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. These will typically be:<br />
<br />
<br />
{| class="wikitable"<br />
|+GitHub location of Apps/Extensions<br />
|-<br />
! '''SmartApp''' !! '''Location'''<br />
|-<br />
| '''Main Ask Alexa''' || smartapps/michaelstruck/ask-alexa.src/ask-alexa.groovy<br />
|-<br />
| '''Message Queue Extension''' || smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
|-<br />
| '''Rooms/Groups Extension''' || smartapps/michaelstruck/ask-alexa-rooms-groups.src/ask-alexa-rooms-groups.groovy<br />
|-<br />
| '''Scheduler Extension''' || smartapps/michaelstruck/ask-alexa-schedule.src/ask-alexa-schedule.groovy<br />
|-<br />
| '''Voice Report Extension''' || smartapps/michaelstruck/ask-alexa-voice-report.src/ask-alexa-voice-report.groovy<br />
|-<br />
| '''Weather Report Extension''' || smartapps/michaelstruck/ask-alexa-weather-report.src/ask-alexa-weather-report.groovy<br />
|-<br />
|}<br />
<br />
'''Tip'''<br />
When adding code from the repo you have to add it in a <br />
specific order or the IDE will generate an internal server error. <br />
Add the main Smartapp (Ask Alexa) to your IDE first. Then you can <br />
add the extensions.<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new apps should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Ask Alexa SmartApp Installation==<br />
If you installed the code properly, you should find the '''Ask Alexa''' SmartApp located in the SmartThings Mobile Application under Market Place>>>SmartApps>>>+MyApps. If you have published any of the '''Ask Alexa''' extension you may see them in this list as well. DO NOT install those; just install the main '''Ask Alexa''' app. You may install extensions via the parent SmartApp.<br />
<br />
[[File:AAAddSmartApp.png|250px]]<br />
<br />
After you install '''Ask Alexa''', it is a good idea to set it up, and THEN do the Amazon setup pieces ([[Ask_Alexa#Developer_and_Lambda_Code_Installation]]). This will limit your need to go back and forth as the way you configure '''Ask Alexa''' determines how you set up the Amazon Developer's site.<br />
<br />
==Ask Alexa Interface==<br />
When you first open the SmartApp, you will be greeted with colorful icons where you can interface items with Alexa. Some of these items allow for control (i.e. switches, doors, locks, etc), and some will only provide their status (open/close sensors, water sensors). More devices are being integrated as the application matures. Some menu items (like the <<Device Aliases>>) may not appear in your interface until you activate the appropriate options in the <<Settings>> area (see [[Ask_Alexa#Allow_Device_Aliases]])<br />
<br />
It is recommended that you now add the devices you will want control of and status of to the interface before going on to the next steps of setting up the Developer/Lambda accounts. This will prevent your having to repeat these steps upon the completion of your installation.<br />
<br />
[[File:AAMain.png|250px]]<br />
<br />
===Interface Items===<br />
<br />
Currently, you have the ability to interface switches (dimmers and colored lights), locks, temperature/humidity devices (including thermostats), open/close, presence, motion and water sensors, along with your SmartThings modes, Smart Home Monitor and Routines to your Alexa Enabled Devices. Please note that in addition to the devices to interface, if you have the <<Allow Device Aliases>> enabled in the <<Settings>> area, you will also see options to add devices that can have aliases associated with them.<br />
<br />
*'''Lighting/Switches'''-These devices are very straight forward; you can turn them on, off or toggle their state (<''"Alexa, ask SmartThings toggle the Living Room"''>), change the level of a dimmer (<''"Alexa, tell SmartThings to set the Dining Room to 50%"''>), or even change the color of a bulb (<''"Alexa, ask SmartThings to set the Den to Blue"''>). In addition, you can ask the status of a device easily (<''"Alexa, ask SmartThings the status of the Living Room"''>). For items like colored lights, two commands may be combined into one...For example <''"Alexa, ask SmartThings to set the Den to Blue and to 50%"''>. Also on this page, if you choose colored lights, you will find the option to add a custom color as well under the <<Settings>><<Custom Color Setup>> ([[Ask_Alexa#Custom_Color_Setup]]). As is customary with dimming controls, only positive numbers between zero and 100 are accepted; any numbers exceeding this value will be normalized to the 0-100 range. Finally, you can use custom commands like maximum, increase, decrease, brighten, dim and low, medium and high to specify default behavior of dimmable switches. <br />
<br />
'''Please Note'''<br />
There are over 150 available colors to choose from in the latest version of '''Ask Alexa'''.<br />
A full list of colors would take minutes to recite; if you need to reference <br />
these colored names, it is recommended you view the cheat sheet <br />
(see [[Ask_Alexa#About_Ask_Alexa]]) or the FAQs (see: [[Ask_Alexa#Frequently_Asked_Questions_.28FAQs.29]]).<br />
The names of the colors come directly from SmartThings. Again, if one of these colors <br />
do not meet your needs you can define your own custom color.<br />
<br />
For Temperature (Kelvin) lights, you have the option of choosing four settings, <br />
"Soft White", "Warm White", "Cool White" and "Daylight White", setting the lights <br />
to 2700K, 3500K, 4500K and 6700K degrees Kelvin, respectfully. These are the only <br />
temperature setting available for these lights, which are typically white LED lights.<br />
You can change the default value of these 4 settings by going to <<Settings>><br />
<<Default Command Values>>. See [[Ask_Alexa#Default_Command_Values]]<br />
<br />
*'''Doors/Windows/Locks'''-Another simple set of devices that can be addressed using natural language. A simple command such as <''"Alexa, tell SmartThings to unlock the front door"''> will unlock the door. To enhance security, you do have the option to set up a PIN to prevent these simple commands from allowing access to critical devices (see [[Ask_Alexa#Password_PIN]]). In addition, you can disable commands like "Open" Or "Unlock" for additional security. As with the switches, you can always query the status of device (<''"Alexa, ask SmartThings about the Garage Door"''>). In this category are window shades, locks, doors, and open/closed sensors which are usually used for door or window open/close status.<br />
<br />
'''Important Notice Of Liability'''<br />
It can not be stressed enough that allowing your locks or doors to be controlled by<br />
this SmartApp lowers the security of your household. Anyone with knowledge of your <br />
home setup (including your PIN) can open/close/lock/unlock these devices. The author <br />
of this application accepts NO RESPONSIBILITY with intentional or unintentional <br />
use (or misuse) of these features. Use SmartThings holistically; if you enable this<br />
feature ensure you are also properly monitoring/alerting on the devices as well.<br />
<br />
*'''Environmentals'''- Many SmartThings devices have temperature, humidity or even UV sensors built into them. As such, you may query the status of these devices to get their current readings. Also, you may set the set any SmartThings connected thermostat to a specific setpoint. Please note that many thermostats have both heating and cooling setpoints. As such, unless you have your thermostat set to just heating or just cooling, it is a good idea to ensure you are setting the proper setpoint. For example, if you thermostat is in auto mode, you could say <''"Alexa, tell SmartThings to set the heat in the office to 65 degrees"''>. If your thermostat is in a specific mode (like heating), it is perfectly acceptable to just ask her to set the temperature setpoint...<''"Alexa, tell SmartThings to set the office to 65 degrees"''><br />
<br />
'''Please Note'''<br />
<<Environmentals>> is the area you are most likely to have the same device<br />
in multiple device categories. For example, you might have a humidity sensor that can<br />
also be added as a temperature sensor, or an air quality monitor that registers humidity.<br />
'''The program will not operate correctly if you choose the same device in multiple areas.''' <br />
It should be noted, however, that if you turn on additional attributes within the <<Settings>><br />
<<Device/Event Voice Setting>>menu that you can hear the additional parameters without choosing <br />
the same device in two different categories.<br />
<br />
When you select a thermostat you will be given the option to select some device specific commands. Various devices that work with SmartThings have powerful features or different command sets that don't comply with normal APIs provided by SmartThings. A good example of this is the Nest Thermostat; this device is not officially supported by SmartThings, but there are a few community-written device handlers that allows it to perform normal thermostat functions within your house. However, it also has other features that no other thermostats have; one of these features is the ability for the thermostat to act as a presence sensor, changing the way it behaves based on occupancy. The user may also set the "Home" and "Away" status manually, or through automation. If you are using Nest Manager, you can even expand on the generic Nest commands with custom reports (i.e. <"Alexa, ask SmartThings for Nest report">.<br />
<br />
Another example is the Stelpro baseboard heating thermostat. This device is supported by SmartThings, but had different modes of operation besides heating and cooling; these are "Eco" and "Comfort" modes. Ecobee3 (Connect), as yet another example, allows for specific modes such as "Home", "Away", "Sleep", and "Resume Program" commands.<br />
<br />
====MyEcobee & MyNext Devices' comfort & energy saving tips ====<br />
<br />
If you have a Ecobee or a Nest thermostat, you have the ability to use a community-developed device type handler, written by Yves Racine, to get you tips to operating your device (and your home) more efficiently. To access these tips, do the following:<br />
<br />
*Go to <<Settings>><br />
*Choose <<Device Specific Commands>><br />
*Choose <<Ecobee Specific Thermostat Modes>><br />
*Choose <<MyEcobee Specific Tips>><br />
<br />
Or if you have My Next Tstat for the Nest Thermostat:<br />
<br />
*Choose <<MyNextTstat Specific Tips>><br />
<br />
Then, you can use the following commands with My Ecobee or My NextTstat Device(s):<br />
<br />
'''Individual commands'''<br />
*'''Give Tip/Play Tip''' - This will play the tips available in memory, one at a time, for this device. The tips will increment to the next tip in memory until they have all been heard, at which point they will replay.<br />
*'''Repeat Tip''' - This will repeat the tip that was just played and will not increment the tip counter.<br />
<br />
'''Batch commands (Advanced)'''<br />
*'''Get Tips[Level]''' - Without a number given, it will default to "Level 1" tips, which are the most general. To choose additional tip levels, say that level (i.e. <''"Alexa, tell SmartThings to Get Tips, level 3, for Kitchen"''>. Please note that this will NOT play any tips, it just tells the device handler to load the tips for you into memory. <br />
*'''Reset Tips''' - This will reset the tips in memory. You must then say 'Get Tips' (with or without level) for the device to obtain more tips.<br />
<br />
For more information on the My Ecobee's Get Tips, please see here: http://thingsthataresmart.wiki/index.php?title=EcobeeGetTips<br />
<br />
For more information on the My Next Tstat's Get Tips, please see here: http://thingsthataresmart.wiki/index.php?title=NestGetTips<br />
<br />
<br />
*'''Connected Speakers'''- If you connected speakers such as Sonos, Bose or Samsung with SmartThings, they can be controlled with '''Ask Alexa'''. Basic commands are supported, with plans to implement other features in the future. Simple say, <''"Alexa, tell SmartThings to play Bedroom Speaker"''> and the device will come on. You can also pause, mute, and skip tracks. You can also give a volume command between 0-100. Like the dimmers, you can also "increase" and "decrease" the volume based on the settings you define in the <<Settings>> area. <br />
<br />
'''Notice'''<br />
The Sonos integration within SmartThings is currently in listed as a "Labs" .<br />
release. This means certain functionality is subject to change or may not work as<br />
expected. This includes re-playing music from a saved list.<br />
<br />
*'''Other Sensors'''-You may have other sensors around your house that you would also like to report on. Currently, acceleration, water, presence, occupancy and motion sensors are available. With the water sensors, you get a status reading of either wet or dry. Presence and motion/acceleration sensors behave in a similar fashion, with one state (present or motion) or another. Similarly, using a custom Device Type Handler, you can also check the status or change the occupancy of a room. In addition, as most of these types of sensors also have temperature readings available, if you have the other attributes configured to play, the voice reading will include this as well. Finally, if the sensor is a battery operated device, the battery reading will play if below the designated threshold (Set in <<Settings>>). Typically, sensors are read-only. However, with version 2.2.2, you may use the concept of a 'virtual' or simulated presence sensor so that those without physical presence devices can be accounted for and automations can run based on their presence. Users simply 'check in' or 'check out' with Alexa when entering a location.Physical presence sensors will not work with these additional commands. You will need to create a simulated presence sensor. The instructions for installation of this virtual device is here: [[Virtual_Presence_Sensor]]. <br />
<br />
*'''Modes/Routines/SHM''' - Unlike the native SmartThings integration, '''Ask Alexa''' will allow you to query and/or change the modes or Smart Home Monitor status, in addition to running a specific routine. When speaking to Alexa, ensure you specify what you want to do: <''"Alexa, ask SmartThings to run Good Morning Routine"''> or <''"Alexa, ask SmartThings the current Security status"''>. Be sure your mode or routine names also are unique among your SHM settings as well (i.e. Stay, Arm, etc.). If you have unique names to your routines and modes, you may shorten your commands to <''"Alexa, tell SmartThings Good Morning"''>, assuming you have a "Good Morning" routine. Finally, you have the ability to require a PIN number to activate the modes/routines or change the Smart Home Monitor settings. This option will appear when you have the PIN enabled in the <<Settings>> area (see: [[Ask_Alexa#Password_PIN]])<br />
<br />
'''Please Note'''<br />
For the Smart Home Monitor (SHM) functions, if you do not choose ANY states<br />
this will effectively release the 'reserved' words of "security", "smart home" and <br />
SHM. This is useful if you have switches set up with those same words. For example,<br />
if you use the popular app "Smart Alarm" you can now have a virtual switch called <br />
"security".<br />
<br />
*'''Device Aliases''' - While it is recommended that you have unique names for each of your devices within your SmartThings environment, this is sometimes not possible or practical. However, you can't address devices that appear multiple times with the same name (i.e. the name "Living Room" that is both a lamp device and a motion sensor). To solve this, '''Ask Alexa''' allows you to set up aliases to allow you to access all the devices within your environment without having to rename your devices within the main SmartThings app. You must turn this function on in the <<Setting>> menu item and then select the devices you wish to create aliases for in each of the device categories above. Once you do this, you will see the <<Device Alias>> selection appear. Using the example above, you could keep controlling the living room lamp with just with the name "Living Room" and then create an alias for the living room motion sensor. Once set up, the alias name behaves exactly like any other devices, picking up parameters unique to the device type. Another good example is to shorten a device name so it is easier to address. For example, if you have a long name for your speaker (i.e. "Master Bedroom Sonos") you could create an alias simply called "speaker" to address that device (see figure below).<br />
<br />
[[File:AAAliasMain.png|250px]] <br />
<br />
'''Alias Usage Limitations/Notes'''<br />
* Aliases are one-to-one associations; to control groups of devices using a single name you <br />
will need to create a room/group (see [[Ask_Alexa_Rooms/Groups]]).<br />
<br />
* Alias names must still be unique within the '''Ask Alexa''' app. This means the name should<br />
not be the same as any other device (or alias) or routine, modes or voice macros<br />
<br />
* When creating and deleting alias names, be sure to use the interface buttons provided on <br />
the page and not the SmartThings "Done","Save" or "<" buttons. Using these may give you undesired results.<br />
<br />
* Speaking of interface, due to a limitation of the SmartThings GUI, when you create your first<br />
alias that names will 'stick' in the interface input areas, giving you an error if you do not change <br />
it and simply press ADD again (as the alias name will be one that you just created). Be sure all of your <br />
alias names are unique and that you change the interface when you add or delete an alias.<br />
<br />
===Extensions===<br />
[[File:Ext@2x.png|100px]]<br />
<br />
On the main '''Ask Alexa''' page, scroll down to the area labeled <<Extensions>>. Extensions can be thought of as 'mini' applications that expand the functionality of '''Ask Alexa'''. Currently, there are multiple extensions available: Macros (which are built in), Message Queues, rooms/groups, voice/weather reports and scheduling. Additional extensions coming soon.<br />
<br />
'''Notice'''<br />
When naming your extensions (be it Message Queues, rooms, voice reports or Macro names or aliases), <br />
ensure your names are unique not only within the context of the other extensions, but <br />
within the parent app itself. That means an extension should not share the same name with<br />
devices, aliases, modes, or routines within the parent app. Taking this precaution will <br />
eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
[[File:AAMQMain.png|250px]]<br />
<br />
For information about each extension, including setup instructions, please click on the appropriate link below:<br />
<br />
* '''Macros''': [[Ask_Alexa_-_Macros]]<br />
* '''Message Queues''': [[Ask_Alexa_-_Message_Queues]]<br />
* '''Rooms/Groups''': [[Ask_Alexa_Rooms/Groups]]<br />
* '''Schedules''': [[Ask_Alexa_-_Schedules]]<br />
* '''Weather Reports''': [[Ask_Alexa_-_Weather_Reports]]<br />
* '''Voice Reporting''': [[Ask_Alexa_-_Voice_Reports]]<br />
<br />
===Settings===<br />
<br />
Back on the main (parent) interface you will find the <<Settings>> area. This page is separated into four sections that allow you to customize your '''Ask Alexa''' experience. This includes what the Alexa device will say when you ask for a status of SmartThings devices, whether or not you need a password for security related items (like doors, locks, Smart Home Monitor settings, etc), and the default values used to set up and operate the SmartApp for your environment.<br />
<br />
====Setup Ask Alexa====<br />
The very top menu item is where you want to go for all things related to setting up '''Ask Alexa'''. This includes defining the Skill Invocation name, getting the setup variables for the Amazon AWS and Developer's sites, and displaying the command 'cheat sheet'.<br />
<br />
[[File:AASetup.png|250px]]<br />
<br />
=====Skill Invocation Name=====<br />
<br />
At the top of the page you will set up a specific invocation name for the skill name. Throughout this document the assumption is that you use "Smart Things" (two separate words) as this name; however, it can be anything. If you do change it within Amazon developer web site, you SHOULD change it here to match.<br />
<br />
=====Setup Variables=====<br />
The voice system of the Amazon Alexa Enabled Devices is very programmable. Almost any device you have in your system can be addressed by name. However, the Alexa Enabled Devices do not know these names by default; you must input them into the Amazon developer site as custom slots ([[Ask_Alexa#Custom_Slot_Information]]). While this can be a tedious task, '''Ask Alexa''' reduces the steps by evaluating the devices you have chosen to interface and generate an HTML setup page, allowing you to copy and paste the information directly to the Amazon Developer site.<br />
<br />
When you tap the <<Setup Variables Link>> you will be presented in your SmartThings Live Logging with a web page URL. Copy this link to a computer (desktop) browser and you will then be given a page with the various variables you will need to operate '''Ask Alexa''' properly. <br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Any time you add or remove devices, modes, routines, or reports to your '''Ask Alexa''' SmartApp, it is best practice to put the new information into the custom slots so Alexa recognizes the new commands.<br />
<br />
'''Please note'''<br />
If you find your IDE Live Logging is not presenting the data properly, the page presented<br />
on your mobile device gives you the address you need on your desktop browser to continue<br />
the setup process. Simply copy that address to an e-mail (or other method) the can be <br />
sent to your desktop environment. Of course, the Live Logging method is the preferred <br />
method of obtaining this setup URL.<br />
<br />
[[File:AASetupURL.png|250px]]<br />
<br />
=====Cheat Sheet=====<br />
At the bottom of the setup page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within '''Ask Alexa'''. <br />
<br />
While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See [[Ask Alexa#Setup Variables]])<br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.<br />
<br />
====Additional voice settings====<br />
In this section you will set up what additional information the Alexa Enabled Devices respond back to you and how.<br />
<br />
[[File:AASettings.png|250px]]<br />
<br />
=====Accept Compound Commands=====<br />
<br />
'''Ask Alexa''' can accept 'compound commands' as part of its command structure. Simply put, a compound command is controlling two actions with one statement. For example, you could say ''<"Alexa, tell SmartThings to turn on the office and close the garage"''> to have two actions occur in tandem with one command. While this is convenient, the more words you say to Alexa, the more opportunities she has of misunderstanding you. Turning this option off, you disable the ability for '''Ask Alexa''' to process compound commands. Only single action commands will be accepted.<br />
<br />
=====Device/Event Voice Setting=====<br />
<br />
In this section you will find items relating to the device voice output along with event voice output.<br />
<br />
[[File:AADeviceEvent.png|250px]]<br />
<br />
======Give Brief Device Action Reply======<br />
Under normal operation, when you give an action to a device, Alexa will respond of a confirmation of your action. For example, if you say <''"Alexa, tell SmartThings to lock the Front Door"''>, if the door is locked already she will state that, or if it is unlocked she will respond "I am locking the front door.". However, if you feel that the responses get tedious to hear, you can turn on "Brief" replies to device actions. When clicking this feature, you have the option of having Alexa reply with nothing, an "Ok", "Done", or a user-defined output. Please note a few caveats to this behavior:<br />
* For items like locks and doors, the default action is to check the status of those devices and NOT perform the action if the device is already in the desired state. With brief replies turned on, you will not get this feedback.<br />
* If an error occurs with the device, you will still get the error message if brief replies are activated.<br />
* If you have battery alerting on (See [[Ask Alexa#Battery Level]] below), these messages will append to your brief message.<br />
<br />
Please note that the default behavior has been modified slightly (since version 2.2.9) in that the After Action/Event History Continuation commands will be muted when brief reply is turned on.<br />
<br />
======Speak Additional Status Attributes======<br />
For devices like switches or open/close sensors, there are other attributes that can be accessed besides the primary functions. For example, many light switches also monitor the power usage of the connected device. In addition, most SmartThings sensors (motion, water, or open/close sensors) also monitor temperature. Finally, many stand-alone devices, like motion sensors, are battery operated. When you ask Alexa the status of a device, you also have the option to have the additional attributes spoken.<br />
<br />
To use enable this option, on the main menu of '''Ask Alexa''' find the <<Settings>> option. Tapping this will bring you the <<Settings>> area. Tap the slider labeled <<Speak Additional Device Status Attributes>>.<br />
<br />
Please note items that are NOT selected as motion sensors, but have these capabilities, will ONLY report this attribute when motion is in progress.<br />
<br />
======Device Health======<br />
<br />
Sometimes the devices in your environment go offline. While there are many causes for this, the end result is that you may attempt to control a device and it is offline without you knowing it. If you enable <<Speak Device Health When Offline>> you will be alerted to the offline status of a device when you attempt to control or query the device. Please note that Ask Alexa CANNOT bring the device back online; this requires manual intervention. In addition, some devices that are tagged by SmartThings on being "offline" simply haven't reported in for a while. Many time, just manually toggling the device (be it a switch, or motion sensor) may be enough to put it back into online status.<br />
<br />
======Battery Level======<br />
This option will allow you to set the threshold in which the batteries status is reported on. The default value of the threshold is 20...using this setting, if the battery level on a device is below 20%, when you ask the status of a device (i.e. <''"Alexa, ask SmartThing the status of the living room"''> the battery will be reported as well. Above the threshold, no battery status will be given. Please note that battery report is given whether or not the above attributes setting is selected if the level is below the threshold.<br />
<br />
======Default Number Of Past Events======<br />
SmartThings keeps a log on every change on the devices, whether it be a motion sensor showing movement, or a door opening or closing to a light turning on or off. Using the command "Events" on a device you can access the last events (ex. <''"Alexa, ask SmartThings to give me the last events on Living Room"''>). When no number is specified, the number in the <<Default Number of Past Events To Report>> will be used to give you that number of entries from the log. You can override this by giving a number in the command (ex. <''"Alexa, ask SmartThings to give me the last 4 events from the Bedroom"''>)<br />
<br />
====Enable Flash Briefing====<br />
This option will allow you to enable the ability to use a macro or Message Queue as the output of the native Alexa 'flash briefing' function. This process is described here ([[Ask_Alexa_-_Flash_Briefing]]) and does require additional steps to create a new skill that allows for this functionality. When you select this option, another option appears below it allowing the selection of the output you wish to use for your flash report.<br />
<br />
====Personalization====<br />
With a little bit of configuration on this page, you can give Alexa's responses a more "personalized" touch. This includes allowing her to "follow up" after an error, or address you by name in a formal or even funny manner. All of these options also allow you to have them 'whispered' to you all of the time, or within specific modes or timeframes.<br />
<br />
[[File:AAContCmds.png|250px]]<br />
<br />
Alexa has the ability to continue with a "skill" after the primary function or response is given. With the options in this area, you can choose if you want Alexa to ask ''"Anything else?"'' after certain actions have been performed. For example, if you want to stay within the skill after an error comes up (let's say you didn't choose a valid switch), then you would turn on the <<After Error>> option. When Alexa says ''"Anything else"'' you do not have to use the <''"Alexa, ask SmartThings"''> command; simple state your command (i.e. <''"Turn on the front porch"''>). The settings here are global; if you turn them on <<After Errors>> continuation options will be given after every error. Same for the other switches except <<After Macro Execution>>. For Macros, if you have the <<After Macro Execution>> switch turned on, you DO have the ability to suppress this on a per-macro basis. This does NOT suppress any errors that come up within the macro execution (if turned on); they will only suppress the "Anything else?" questions.<br />
<br />
Also on this screen you can setup your response "Personality". These personalities will give you different types of responses based ranging for "Normal" to "Snarky" to "Courtesy". For advanced users, these can be customize for your environment/mood. You can also set a name that Alexa will occasionally address you by. The responses are random, so it won't happen all of the time. Again, for advanced users, you can use the text variable %people% (see [[Ask_Alexa#Text_Field_Variables]]) to have the responses customized based on who is present in the house. Unfortunately, Alexa has no ability at this time to determine WHO is speaking to her, so the text variable may not be the best solution as it will list everyone in the house.<br />
<br />
=====Playback Options/Restrictions=====<br />
<br />
Under the Global Options of the personality page you will find the playback options/restrictions. Here you can set up restrictions to mute the playback (either disabling Ask Alexa based on the restrictions, or simply mute the playback but continue to process the commands given to it). <br />
<br />
[[File:AAPlayback.png|250px]]<br />
<br />
In addition to muting playback, Alexa also allows the device to change the voice patterns (speed and pitch) including the ability to 'whisper' back to you in a computerize-light voice. Be warned...this has been called by some "creepy", however, there are specific use cases. Because the volume and the overall tone of whispers is less than normal, you can use these during your 'bedtime' to still interact with Alexa and (hopefully) not wake the person next to you. TO do this, simply turn on the switch <<Enable Whisper Mode>>. Leaving the restrictions below this setting blank means that whisper mode will be enabled all of the time. To restrict this, choose the timeframe and/or mode you want whisper mode to operate in. You can also choose which Echo device to apply restrictions to. All output will then be whispered to you until the restrictions conditions change.<br />
<br />
[[File:AHResitrictions.png|250px]]<br />
<br />
For speed and pitch, there are pre-defined configurations you can choose. Please note that if you change the pitch from normal, you will not be able to use the whisper command. Basically, the pitch command is invalid when whispering. However, speed can be used with the whisper mode. You CAN pick and choose between pitch and speed to create a unique voice response within your household.<br />
<br />
'''Please Note'''<br />
Speed, pitch and whisper adjustments configured on this page affect<br />
ALL output coming from '''Ask Alexa.''' This does NOT affect the output<br />
of the normal (non-'''Ask Alexa''' skill) output. If you want specific '<br />
''Ask Alexa''' text to be whispered or emphasized, please use the advanced <br />
features of the <<Text Field Variables>> (see [[Ask_Alexa#Text_Field_Variables]])<br />
<br />
<br />
[[File:AASpeakOpt.png|500px]]<br />
<br />
====Other Values/Variables====<br />
<br />
In this section, depending on your setup, you may have the following options that can be customized by you. The default values should allow for proper operation, but you can change them to suit your needs. <br />
<br />
[[File:AASettings-1.png|250px]]<br />
<br />
=====Default Command Values=====<br />
<br />
Some of the devices that use variable numeric numbers to control them (like dimmers, thermostats or volume control) are context sensitive. This means you don't need to give a specific number to increase or decrease their value. You can simply say <''"Alexa, tell SmartThings to increase the Living Room by 25%">'' and it will rise 25%. However, if you leave off the number, the settings here will be the default amount of the increase or decrease. You can then just say, <''"Alexa, tell SmartThings to increase the Living Room"''> and it will increase by 20% (the default). You can change these numbers accordingly, but be careful for items like volumes and temperature defaults to prevent hearing or heat damage.<br />
<br />
Also, you will see the option for low, medium, high default values. These are good for ceiling fans that operate in 3 different modes, but these settings can be used for lighting as well. Setting these default values will allow you to simply say <''"Alexa, ask SmartThings to set fan to medium"''> and the fan will go to the percentage you place in these areas.<br />
<br />
Finally, if you use Temperature (Kelvin) lights, the values for "Soft White", "Warm White", "Cool White" and "Daylight White". If you do not change these numbers, the defaults will be used (2700K, 3500K, 4500K and 6700K, respectfully).<br />
<br />
=====Device Minimum/Maximum Values=====<br />
For devices with variable inputs that are critical (i.e. volumes, or temperature controls), '''Ask Alexa''' allow you to set minimum and/or maximum values for some of these parameters. For example, a speaker may not need to ever go above 20%...placing 20 in the maximum value slot will prevent your from purposely (or by a misunderstanding from the Amazon TTS system) from setting the volume above this value. In contrast, you may not want to allow your thermostat to be set less than 60 degrees...putting this number in the appropriate slot will prevent any settings from going below that value.<br />
<br />
=====Text Field Variables=====<br />
These global variables are words (typically starting and ending with a percent sign...for example %temp%) that can be used in any text fields of the macros/extensions to give you 'short cuts' to commonly used text. These make it convenient to personalize the messages coming from the Alexa Enabled Devices, macros and extensions.<br />
<br />
[[File:AAVar1.png|250px]][[File:AAVar2.png|250px]]<br />
<br />
A full list of the current variables available to use are here:<br />
<br />
{| class="wikitable"<br />
|+'''Text Field Variables used in pre/post messages and macro acknowledgement areas'''<br />
|-<br />
! '''Variable''' || Translation<br />
|-<br />
| '''%time%''' || This will give the time in 12 hour, AM/PM format<br />
|-<br />
| '''%day%''' || This will speak the day of the week (Monday, Tuesday, etc.)<br />
|-<br />
| '''%date%''' || This will speak the full date (ex. January 25th, 2016)<br />
|-<br />
| '''%temp%''' || When a single device is selected (defined in the temperature report area) the device will report that temperature. If multiple devices are selected, it will average the readings and report the average.<br />
|-<br />
| '''%humid%''' || Similar to the temperature reading above, when a single device is selected the device will report that humidity. If multiple devices are selected, it will average the readings and report the average.<br />
|-<br />
| '''%people%''' || These are defined by presence sensors that are currently present. Using this variable you can personalize some of the responses the Alexa devices give. You can also use this variable when setting up your personalized feedback (See [[Ask Alexa#Personalization]])<br />
|-<br />
| '''%macro%''' || This is the name of the macro/extension that was called.<br />
|-<br />
| '''%mtype%'''|| This is the type of macro/extension being called (i.e. Room/Groups, Control Group, WebCoRE, etc)<br />
|-<br />
|'''%delay%''' || For macros such as WebCoRE and Control macros, this variable holds the delay (in minutes) that was specified within the app or verbally.<br />
|-<br />
|'''%age%''' || For the Schedules extension, this variable holds the age of the schedule (i.e. the person's age or anniversary years) if the original year of the event was defined. <br />
|-<br />
|'''%random{1-3}%''' || When you set up the 3 categories of random responses, placing this variable in a text field will randomly choose a response and play it.<br />
|-<br />
|'''%xParam%''' || For WebCoRE. Extra parameters of control<br />
|}<br />
<br />
For example, if you are giving a nightly report right before you go to bed and you wish to personalize the message, your post message could be something like:<br />
<br />
<pre style="display: inline-block;"><br />
It is %time% on %day%, %date%. It is time for bed %people%. %random1%.<br />
</pre><br />
<br />
This would result in something like ''"It is 9:00pm on Monday June 23, 2016. It is time for bed Jim and Jane. Sleep well...Good night."''. In this particular example, the time and date have been replaced with real time information. The %people% variable is determined by who is present from the presence sensor readings you set up in the main menu <<Setting>> area. Finally, the %random1% list is 3 good night phrases that you have defined. The other two could be "Don't let the bed bugs bite" or "Talk to you in the morning". Anything can be put into these areas.<br />
<br />
In addition to the built-in variables, advanced users have the ability to reference weather reports using a variable. Simple surround your report name with percent signs, and this variable can play in any extension text field. This is very useful for voice reports where you want to include a weather report.<br />
<br />
Finally, there are other advanced flags available ('on-demand whispering', 'emphasis' and 'suppress continuation messages' ) that can be used in text fields. <br />
<br />
The 'on-demand whispering', 'emphasis' tag tags ONLY works if you have the Global Whisper Functions function turned off in the <<Personalization>> section (see [[Ask_Alexa#Personalization]]). This will allow you designate parts of the output as regular and parts as whispers and yet other parts emphasized. <br />
<br />
The 'suppress continuation messages' is only used in macros/extensions when continuation of commands (see [[Ask_Alexa#Personalization]]) is enabled for macros/extensions. Basically, placing this tag at the end of the custom acknowledgement will suppress the prompt "Is there anything else?" placed at the<br />
<br />
To use these features, here is the formatting:<br />
<br />
{| class="wikitable"<br />
|+'''Advanced Tags used in pre/post messages and macro acknowledgement areas'''<br />
|-<br />
! '''Tag''' || '''Usage'''<br />
|-<br />
| '''<w>''' || Any text between here and the "off" switch (below) will be whispered<br />
|-<br />
| '''</w>''' || Any text between the above and this tag whispered<br />
|-<br />
| '''<eH>''' || Any text between here and the "off" switch (below) will be highly emphasized<br />
|-<br />
| '''<eL>''' || Any text between here and the "off" switch (below) will have lower emphasis<br />
|-<br />
| '''</e>''' || Any text between either of the above switches and this tag will be emphasized as outlined(H or L)<br />
|-<br />
| '''%X%''' || Used for macro/extensions custom acknowledgments. Will suppress any output from continuing commands<br />
|}<br />
<br />
For example, let's say you have a voice report that has following custom acknowledgement:<br />
<br />
<pre style="display: inline-block;"><br />
"And that is all. <w>Have a good evening</w>. <eH>Don't let the bed bugs bite!</e> %X%"<br />
</pre><br />
<br />
The section encapsulated by the <w> </w> will be whispered and the text between <eH> </e> will be highly emphasized (slowed down and volume increased) while the other parts will play based as normal. In addition, with the %X% at the end the additional text of "Would you like anything else?" will be suppressed; however, Alexa WILL remain active, listening for any additional commands that can be used within '''Ask Alexa'''.<br />
<br />
=====Custom Color Setup=====<br />
If you have no colored lights in your SmartThings environment, you will not see this selection. If you have chosen any colored lights you will have the option to set up a custom color. Simply give the name of the custom color, the hue and then the saturation of the color (A good reference for hue and saturation is here[http://www.december.com/html/spec/colorhsltable.html]. You will need to ensure you update your developer slots when you have saved this name, but after you do you should have access to this color when utilizing colored lights.<br />
<br />
=====xParams For WebCoRE Macros=====<br />
<br />
If you use '''Ask Alexa''' to run WebCoRE macros and need to pass a word parameter to the piston, you can now (as of 2.3.7) maintain your list of xParams via the SmartApp instead of manually inputting them to the Developer's slots (Under LIST_OF_WCP). More information can be found about passing variables here: [[Ask_Alexa_-_Macros#Advanced_features]]<br />
<br />
[[File:AAxParam.png|250px]]<br />
<br />
====Security====<br />
In this section you can set up security related items such as PIN numbers, or to revoke your Access Token.<br />
<br />
[[File:AASettings-2.png|250px]]<br />
=====Revoke/Reset Access Token=====<br />
It may be necessary sometimes to revoke your Access Token and issue a new one. Typically, this is required when you publicly post the ApplicationID or TokenID to a public site as this would allow others to access your home environment. Once you reset your token, you will need to place the new code pieces into your Lambda code (See [[Ask_Alexa#Finalizing_The_Function_Code]]). <br />
<br />
To proceed with the reset, simply tap the area labeled <<Revoke/Reset Access Token>>. Here, you will be given one last opportunity to cancel this process as doing so will disable the ability for '''Ask Alexa''' to control your SmartThings environment.<br />
<br />
=====Password PIN=====<br />
While one of the strengths of the Alexa Enabled Devices is the voice recognition; one of the weaknesses is that the device has a difficult (and inconsistent) ability to differentiate one person from another. In most household, the Alexa Enabled device is shared among many people. This makes security of commands on the device almost non-existent. For example, imagine a banking app that speaks your bank balance. If you were to have a dinner party, anyone at the party that was savvy enough with the Alexa Enabled Devices could access your bank balance as easily as you. While there is "security through obscurity" in the fact that '''Ask Alexa''' is community built and not mass market, in theory, a person familiar with your home system could yell through a window and say <''"Alexa, ask SmartThings to open the garage door"''>. To prevent this and provide some level of security, '''Ask Alexa''' implements a basic PIN system for security items like doors, locks, modes, routines, SHM, and macros that control these items.<br />
<br />
To use this feature, in the '''Ask Alexa''' SmartApp find the <<Settings>> menu item, then tap the the on/off slider labeled <<Password (PIN) Option Enabled>>. This will reveal an area to enter a PIN number. Be sure to enter numbers in this area. Then, while setting up various items like lock, modes, or control macros, you will be given the option to use the PIN for that function. You can also 'fine tune' this security by adding restrictions, such as the day of the week, or even which Echo devices require a PIN.<br />
<br />
To use this new PIN in the context of opening the garage door, simply say <''"Alexa, ask SmartThings to open the garage door password 1234"''> (assuming you chose 1234 as your PIN). You will always append your commands with the password. Putting it in other locations throughout your syntax may not give the desired results. If you fail to issue the PIN command, you will be prompted by any device or function that requires a PIN to supply this information. This follow up is as simple as <''"Password 1234"''><br />
<br />
====Advanced====<br />
In this section you can enable some of the advanced features of '''Ask Alexa'''. <br />
<br />
[[File:AASettings-3.png|250px]]<br />
<br />
=====Allow Device Aliases=====<br />
To allow devices to have aliases associated with them, enable this option. This will do two things to the main menu interface; first, each device category will have a new area to allow devices to be set up as aliases. Second, once devices are selected, the main menu will display the <<Device Aliases>> area, allowing you to set up the aliases with the devices you have selected. See [[Ask_Alexa#Interface_Items]] for more information.<br />
<br />
=====Assign A Name=====<br />
If you have a need for changing the default name of the SmartApp ('''Ask Alexa''') you may do this using the <<SmartApp Name>> area. This does NOT have any other other affect on the app except to change the name as seen in your SmartThings main app menu. When used with a multi-room setup, you can easily identify the correct app to set up for specific rooms (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]] for more information.)<br />
<br />
===About Ask Alexa===<br />
<br />
The about page gives basic information about the '''Ask Alexa''' app and other parameters you may find useful. You may also produce a "cheat sheet" that can be printed for those not familiar with the setup of the SmartThings environment or your '''Ask Alexa''' configuration. <br />
<br />
In the <<Version Numbers>> section, you will find the versions of the SmartApp and the Lambda code. You can also hear the version numbers of the SmartApp and Lambda code by asking <''"Alexa, Ask SmartThings about Versions"''>.<br />
<br />
In addition, this page displays your current Access Token and Application ID. This is useful for troubleshooting only and should be kept private to prevent someone else from controlling your house. Below this is the list of your Echo devices that have been associated with rooms.<br />
<br />
The Apache license is available on this page as well, along with some basic instructions.<br />
<br />
At the bottom of the page you will find a section to produce a list, or "cheat sheet" of all of the devices (and aliases) that are set up within '''Ask Alexa'''. <br />
<br />
[[File:AAHelp.png|250px]]<br />
[[File:AAHelp1.png|250px]]<br />
<br />
While tapping this section produces the list on your mobile device, you may want to render this on a computer browser to allow you to print this page out. To do this, have your IDE Live Logging active. When you open the page you will see a link. This is similar to the link you acquire the setup variables from (See [[Ask Alexa#Setup Variables]])<br />
<br />
[[File:AALogSetup.jpg|1000px]]<br />
<br />
Once you have the link, put this into any browser and it will produce the list of devices and their corresponding commands. If you desire, you can print this out for your reference.<br />
<br />
Finally, if you choose to remove this application (and the corresponding macros), you may do this at the bottom of the page. Simply tap <<Remove>> and the application will be removed from SmartThings. If you choose to set up the app again, you will need to go through the entire setup process again.<br />
<br />
==Developer and Lambda Code Installation==<br />
<br />
The next step is to install the ASK code to the AWS/Lambda server and to define the custom intents, slots and utterances. You will need both an Amazon developer account and an AWS Lambda account. Creation of these accounts is outside of the scope of this document, however, very clear instructions for starting these accounts can be found here: [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/getting-started-guide Developer Account] and [https://aws.amazon.com/lambda/getting-started/ Lambda Account]<br />
<br />
===AWS/Lamba Code===<br />
<br />
The basic steps for generically creating Lambda code is listed here [https://developer.amazon.com/alexa-skills-kit/tutorials/fact-skill-1]. Many of the same steps are listed below as well.<br />
<br />
*First, be sure you Lambda account is set to the proper region. The Alexa skills are currently only supported from the <<US East (N. Virginia)>> <<US West (Oregon)>> and <<EU West (Ireland)>> region. Failure to do choose the correct region will prevent you from properly setting up the Configure Triggers ([[Ask Alexa#Configure Triggers]])<br />
[[File:AAAWSP1.png|250px]]<br />
<br />
*Next, find the area within the AWS dashboard for Lambda. This may be a button on the main screen or within the menu below <<Compute>>.<br />
<br />
[[File:AAAWSP2.png|700px]]<br />
<br />
*Find the button labeled <<Create Function>>. Click this and you will begin configuring the parameters of the function.<br />
<br />
[[File:AAAWSP3.png]]<br />
<br />
*You will be brought to a screen to choose a blueprint. Choose <<Author from scratch>> and click it.<br />
<br />
[[File:AAAWSP35.png|700px]]<br />
<br />
From here you will enter a name of the function (it is recommended to use "askAlexa") <br />
<br />
For the area labeled <<Run Time>> it is recommended you set this Node.js (version numbers may be present...always choose the current one), then choose a role or use an existing role. It is recommended that you choose a '''Existing Role''' and select "lambda_basic_execution". If you do not have anything listed in the "Existing Roles" do the following:<br />
<br />
* In the role, choose '''Create a custom role'''<br />
* A new screen will show up<br />
* In the IAM Role, choose '''lambda_basic_execution'''<br />
* Keep the policy name as default<br />
* Click the '''Allow''' button in the bottom right corner of the screen<br />
<br />
[[File:AAlambda.png|700px]]<br />
<br />
When you return to the previous screen and you have configured everything like the screenshot below, click <<Create Function>>.<br />
<br />
[[File:AAAWSP35.png|700px]]<br />
<br />
====Configure Triggers====<br />
<br />
Next, you will be brought to a page where you choose what type of trigger you are creating. On the left side of the screen there is a section called <<Add Trigger>> and here you will choose the "Alexa Skills Kit".<br />
<br />
If you are asked to configure your trigger (specifically with Skill ID), for now choose "Disabled", then <<Add>> in the bottom right of the screen and then click the skill name at the top of the page (above the Skills kit and CloudWatch Logs).<br />
<br />
[[File:AAAWSP3-1.png|700px]]<br />
<br />
'''Please Note''' <br />
If you don't see Alexa Skills Kit in the list, you have chosen the wrong region. <br />
You must use the'''US East (N Viginia)''', '''US West (Oregon)''' or the Ireland datacenters. <br />
Once you have selected Alexa Skills Kit, click <<Configuration>> to go back to the main code <br />
section of the function.<br />
<br />
From here you can enter your code. See the next section (Configure Function) to choose two different methods for entering your code into this area.<br />
<br />
[[File:AAAWSP31-1.png|700px]]<br />
<br />
====Configure Function====<br />
<br />
After version 2.3.5a there are two methods you can use to get the correct information into the Lambda code: A process where you simply click a link on the Setup Variables page, and a more manual method where you paste the authentication information from the Setup Variables page to the Lambda code.<br />
<br />
=====One-Step Method=====<br />
<br />
The one-step method is, by far, the easiest way to get the needed information to your Lambda code. Obtain the code for your configuration, follow these steps:<br />
<br />
* In the Ask Alexa Smartapp, click <<Settings>><<Setup Ask Alexa), then <<Setup Variables Link>> (see [[Ask_Alexa#Setup_Variables]]). Please note you should be using a desktop browser to do this.<br />
* Find the buttons to obtain the Lambda Full Code:<br />
<br />
[[File:LambdaCode.png|700px]]<br />
<br />
* Clicking this link will bring up the raw code, customized with your authentication information already embedded in it. Simply select all the text in the browser (typically Clt+A), then copy it (Ctl+C), then paste it into the proper location.<br />
<br />
[[File:AAAWSP4.png|700px]]<br />
<br />
*Save the code and you are done!<br />
<br />
=====Two-Step Method=====<br />
For those that want to do the installation manually...<br />
<br />
In this step you will need to supply the code with your unique Application ID and Access Token. The app will generate this for you either in your mobile device or via a desktop/laptop browser. See [[Ask_Alexa#Setup_Variables]] for more instructions to obtain this.<br />
<br />
* Obtain the code from From here:<br />
{| class="wikitable"<br />
|-<br />
! '''Ask Alexa Code''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Node.js''' || Lambda code for aws.amazon.com || ''1.3.1a'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa.src/Node.js<br />
|}<br />
<br />
*Paste the code here:<br />
<br />
[[File:AAAWSP4.png|700px]]<br />
<br />
*In the '''Ask Alexa''' Smartapp, click <<Settings>><<Setup Ask Alexa>> then <<Setup Variables>> (see [[Ask_Alexa#Setup_Variables]]). Please note you should be using a desktop browser to do this.<br />
<br />
*At the top of the HTML setup page that is generated, you will want to copy the first 3 lines below the title <<Lambda code variables>>.<br />
<br />
[[File:AAAAWSDev1.png]]<br />
<br />
'''Please Note'''<br />
While the web address (URL) to the SmartThings environment should remain constant, it could be different <br />
than what is displayed about depending on the country you reside in. In addition, this address is<br />
subject to change at any time. The '''Ask Alexa''' app uses the SmartThings API to generate this address<br />
when you run the setup page.<br />
<br />
If the app stops working suddenly, please ensure these parameters in your setup web page<br />
match the Lambda code you pasted when you set up this function.<br />
<br />
*Next, paste the lines between the two commented areas (breaks) at the top of the code area.<br />
<br />
[[File:AAAWSP10.png|700px]]<br />
<br />
Failure to copy these lines exactly will prevent the Lambda code from accessing your SmartThings environment. When you have completed copy (or any time you modify the Lambda code, be sure to click Save in the upper-left corner of the screen).<br />
<br />
'''Please Note'''<br />
Do not press the <<Test>> or <<Save and test>> buttons in the AWS Lambda area.<br />
Doing so will not cause any problems, but Lambda works on specifically formatted <br />
inputs and unless you supply these inputs exactly to the test it will always present <br />
you will an error. This error is not valid and this recommendation is simply <br />
made to avoid confusion when setting up the code.<br />
<br />
====ARN Code====<br />
<br />
* When everything is configured properly and saved, you will find in the '''upper right-hand corner''' of the screen an ARN. This is your Amazon Resource Name and will link your function with a corresponding Skill. It is recommended you copy this number or keep your screen open when you are creating the Skill in the developer area below.<br />
<br />
[[File:AAAWSP7.png]]<br />
<br />
===Developer Account (Primary Skill)===<br />
<br />
You will now need to define the primary skil using an Amazon developer account. Be sure you have followed the instructions from Amazon on setting up your developer account: [https://developer.amazon.com/appsandservices/community/post/Tx3U4BH5Y7JB35L/How-To-Create-a-Distribution-Portal-Account.html Developer Account].<br />
<br />
'''Please Note'''<br />
In order to easily test and use your new "skill" it is recommended that you create<br />
your developer account under the same account you used to set up your Alexa device.<br />
If you already have a developer account that is different than your Alexa device account, <br />
you must assign your physical device to the developer account and then associate <br />
your personal account as a "household" under your development account. More information<br />
on this process can be found [https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/testing-an-alexa-skill#h2_register here].<br />
<br />
* To begin creating your skill, go to https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit and find the area on the right side labeled <<Start a Skill>>. You will be brought to a dashboard of your current skills. <br />
<br />
[[File:AADevP0.png|700px]]<br />
<br />
* On the Alexa Skills Kit Developer Console, click <<Create Skill>><br />
<br />
====Building The Skill====<br />
* The first page you will be presented with is the Skill Name. Typically, it is recommended to use '''Ask Alexa - SmartThings Integration'''<br />
<br />
* Next, you will be presented with a page with pre-built models' however, you will choose a <<Custom>> skill. Select this option, then click <<Create Skill>> in the upper-right corner of the page.<br />
<br />
[[File:AADevP0-1.png|701px]]<br />
<br />
* Here, you will be presented with options to build your skill. On the right side of the page you will have the various steps required to create your skill. These include Invocation Name, Intents, Samples, and Slots, Build Model, End Point. <br />
<br />
* To begin, click <<Invocation Name>><br />
<br />
[[File:AADevP0-2.png|701px]]<br />
<br />
* While the name can be anything you want, it is recommended to start off with 'smart things'. Other options include words like 'house', home, etc.<br />
<br />
'''Please Note''' <br />
The Invocation name should be typed in lower-case. If you like to use the word '''SmartThings'''<br />
as the invocation name, it is recommended you type 'smart things' (not 'smartthings'). <br />
Also note that the invocation name within your SmartApp (here: [[Ask_Alexa#Personalization]])<br />
should match this name. This is important if you use the [[Ask_Alexa#Single_Step_Interaction_Model]]<br />
to set up your Amazon developer area.<br />
<br />
* After you have entered your Invocation Name, click, <<Save Model>> at the top of the screen. Then click <<Custom>> on the left side of the screen.<br />
<br />
[[File:AADevP1.png|701px]]<br />
<br />
* You should now see your invocation name with a check mark next to it.<br />
<br />
* Next, on the Skills main page, find the <<JSON Editor>> on the left side<br />
<br />
=====JSON upload=====<br />
<br />
[[File:AADevP2.png|700px]]<br />
<br />
* Go back to your '''Ask Alexa''' SmartApp and run your <<Setup Variables>> again (see [[Ask_Alexa#Setup_Variables]])<br />
<br />
* Just like the Lambda code setup (see [[Ask_Alexa#One-Step_Method]]) you will click the link for the Developer Code (Second bold line).<br />
<br />
[[File:LambdaCode.png|700px]]<br />
<br />
* Alternatively, you have the option to download the Developer Code (JSON) as a text file. Please note the file name will have a timestamp on it and may be different than what is shown below. '''This is the recommended way of doing this INSTEAD of copying/pasting the JSON code.'''<br />
<br />
* Select all of the code from webpage, copy it, and then paste it into the Amazon Developer's page. If you chose to download the JSON text file, click the area as shown below, choose the file you downloaded, and click Open. After either (not both) of these steps, click <<Save Model>> in the upper-left corner of the page. Then click <<Build Model>>. Be sure to watch the upper-right corner of the screen to status messages, including any errors that may occur.<br />
<br />
[[File:AADevP3.png|700px]]<br />
<br />
Once the build is completed, click <<CUSTOM>> on the left side of the screen, you will now see steps 1, 2 and 3 on the right side with a green check mark. Click on <<4. Endpoint>><br />
<br />
[[File:AADevP4.png|700px]]<br />
<br />
* On the next step, you will enter the ARN number from the code from the AWS/Lambda area (See [[Ask_Alexa#ARN_Code]]). Place this code in the <<Default Region>> Area<br />
<br />
[[File:AADevP5.png|700px]]<br />
<br />
* Click <<Save Endpoints>> at the top of the screen. Next, click on <<Interfaces>> on the left side of the screen. Ensure your page looks like the screenshot below. Click <<Save Interfaces>> and <<Build Model>> at the top of the screen.<br />
<br />
[[File:AADevP6.png|700px]]<br />
<br />
* Click on Account Linking on the left side of the screen. Ensure the toggle switch is off.<br />
<br />
* The final step is to click <<Permissions>>. This will be set according to the screenshot below with all of the items toggled 'off'<br />
<br />
[[File:AADevP7.png|700px]]<br />
<br />
====Testing Your Skill====<br />
<br />
If you followed the directions properly, you should be ready to test your new skills.<br />
<br />
* Click <<Test>> at the top of the Skill Console.<br />
<br />
* Ensure the <<Test is enabled for this skill>>. While this implies that only testing is impacted, this slider actually disables the operation of your skill using your voice. This must be turned on.<br />
<br />
[[File:AASDev8.png|700px]]<br />
<br />
*As mentioned above, your Alexa Enabled Devices should be associated with your developer account. Please see here ([[https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/testing-an-alexa-skill#h2_register]]) if you did not do this.<br />
<br />
*If properly set up, if you go to the <<Skills>> area of https://alexa.amazon.com or the Amazon Echo mobile app and refine the view to <<Your Skills>>, you should see your new '''Ask Alexa''' Skill.<br />
<br />
[[File:AASkill.png|350px]]<br />
<br />
* Start speaking to your Alexa Enabled Device. Start with "Alexa" (or your wake word), along with "ask" or "tell" along with the invocation word, followed by what you want to do.<br />
<br />
* Start with a simple switch (example: Living Room) and say <''"Alexa, ask SmartThings to turn on Living Room"''>. The Living Room should come on. If not, please check all of your settings. You may also visit the SmartThings Community for this app (https://community.smartthings.com/t/coming-soon-ask-alexa/46786) to ask community members (and sometimes the author) questions about this app. Finally, use the [[Ask_Alexa#Troubleshooting]] section for additional advice on how to troubleshoot your issues.<br />
<br />
* If your test goes well, try your other devices. In addition to the voice feedback, you should also also see 'cards' appear in your Echo mobile app to give you an indication of what the device is hearing and the responses it gave. <br />
<br />
[[File:AATestCard.png|350px]]<br />
<br />
* If you have difficulty, you may be able to troubleshoot the application yourself. The Amazon developer web site has tools to allow you to simulate your commands and show you what the responses are. Using this along with the SmartThings Live Logging should allow you to figure out where your issue is.<br />
<br />
* While on the Amazon Developer site, under the Test area, you can type your commands into this simulator to give you access to the skill. Be sure to type your invocation name when using the simualtor (i.e ''tell smart things version'' )<br />
<br />
[[File:AADevTest01.png|700px]]<br />
<br />
* JSON text will appear on the simulator boxes. The left side JSON is useful to see what was input, with right which includes the response from the SmartThings app and presented to the Echo device. <br />
<br />
'''Please Note'''<br />
In order for community members or the author to properly troubleshoot this application<br />
it will be important for you to produce screen shots of your environment. Please ensure<br />
you have provide screen shots of not only the development web site, but the Live Logging<br />
area of the SmartThings IDE so that issues can be quickly resolved.<br />
<br />
====Launch (Optional)====<br />
While optional, you can add icons to your application that will be visible in the Amazon Echo stand alone application on your mobile device, or at http://alexa.amazon.com. On the skills console page, click <<Launch>> at the top of the screen.<br />
<br />
[[File:AADev08.png|700px]]<br />
<br />
The recommended text is outlined below, but again, this is completely optional and is not needed for proper usage of the application or the integration with SmartThings. When you are completed. <br />
<br />
[[File:AAPublish.png|700px]]<br />
<br />
If you choose to use the supplied icons, their locations are listed here to download and use.<br />
{| class="wikitable"<br />
! Icon Size !! Location<br />
|-<br />
|'''108 x 108 icon''' || https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/AskAlexa108.png<br />
|-<br />
|'''512 x 512 icon''' || https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/AskAlexa512.png<br />
|}<br />
<br />
Click <<Save and Continue>> at the bottom. '''Please note that you should stop here''' with your skill. The next steps in the interface are for publishing the app for others to use....something you DON'T want to do unless you want the world to control your home.<br />
<br />
===Developer Account (Secondary Room Skill)===<br />
Coming Soon<br />
<br />
==Ask Alexa Usage==<br />
<br />
Assuming you kept your invocation name as ''"SmartThings"'', the usage of '''Ask Alexa''' is as simple as this: <''"Alexa, ask SmartThings to unlock the front door"''>. The invocation of ''"tell"'' or ''"ask"'' are required to activate the custom ASK Skill. However, they have no other context within the command. In other words, you can 'ask' or 'tell' Alexa the same command and she will respond exactly the same way.<br />
<br />
===Asking/Telling Alexa What To Do===<br />
<br />
Just like human language, the Alexa Enabled Devices will key off of nouns and verbs. The nouns are the device names (or aliases), modes, or routines you have set up in SmartThings. Verbs are the actions (or operations) you would like to carry out. However, just like human language (especially English), the rules are not hard and fast. It is recommended you try different combinations of syntax to get the results you desire. If you come up with a unique one, contact the author of this application so that the "intelligence" of the application can continue to grow.<br />
<br />
Please note that while most of the utterances begin with <''"Alexa, ask SmartThings..."''>, there are also other valid ways to address the '''Ask Alexa''' functions. For example, instead of saying <''"Alexa, ask SmartThings to turn off Dining Room"''>, you could say, <''"Alexa, turn off Dining Room with SmartThings"''>. If "asking" or "telling" Alexa something doesn't feel natural with the "SmartThings" invocation word at the beginning of your command, try another combination with putting <''"...with SmartThings"''> or <''"...using SmartThings"''> at the end of the command. Even "use" can be used (pun) to activate the skill (ex. <''"Alexa, use SmartThings set the Thermostat to auto mode"''><br />
<br />
*'''Switches/Dimmers/Colored Lights''': ''on'', ''off'', ''toggle'', ''status'', ''level'', ''color'', ''increase'', ''decrease'', ''rise'', ''lower'', ''up'', ''down'', ''maximum'', ''minimum'', ''low'', ''medium'', ''high''<br />
**<''"Alexa, tell SmartThings to turn on the living room"''><br />
**<''"Alexa, ask SmartThings to turn on the living room"''><br />
**<''"Alexa, ask SmartThings to increase the level of the living room"''> - Without a numeric settings, "increase" or "decrease" commands will be based on the values you set up in the <<Settings>> area.<br />
**<''"Alexa, tell SmartThings to lower the level of the Living Room by 5%"''> - You can specific the amount of the increase or decrease of the brightness level.<br />
**<''"Alexa, tell SmartThings to set the Media Room to Blue and 30%"''><br />
**<''"Alexa, tell SmartThings to set the Media Room to Red"''> The light will stay at the current level if not specified.<br />
**<''"Alexa, tell SmartThings to set the Bed Room to medium"''> - "Low", "medium" or "high" commands will be based on the values you set up in the <<Settings>> area.<br />
**<''"Alexa, ask SmartThings to set Lamp to maximum"''> - "Maximum" will set the dimmer to 100%.<br />
**<''"Alexa, tell SmartThings to set the Bed Room to medium and green"''> - You can also use two commands in unison as shown here.<br />
*'''Doors/Locks/Shades''': ''lock'', ''unlock'', ''open'', ''close'', ''status''<br />
**<''"Alexa, tell SmartThings to open the front door"''> - Please note that if front door is a connected lock, OPEN will NOT unlock the door. ''Open'' and ''Close'' are reserved for items that have motorized open/close mechanisms.<br />
**<''"Alexa, ask SmartThings to open the garage door password 1234"''> - assuming you chose 1234 as your PIN; see [[Ask_Alexa#Password_PIN]] for more information.<br />
**<''"Alexa, ask SmartThings the status of the garage door"''><br />
*'''Thermostats/Temperature/Humidity''': ''set'', ''status'', ''heat'', ''cool'', ''heating'', ''cooling'', ''mode'', ''off'' (for StelPro baseboard heaters, ''eco'' and ''comfort'' modes also available), ''home/away'' (For Nest Thermostats), ''get/repeat/replay/get/load/reload/restart/erase/delete/clear/reset tips'' (Ecobee Thermostats)<br />
**<''"Alexa, tell SmartThings to set the bedroom to 55 degrees"''> - It should be noted, depending on your thermostat, you may need to append the command with heating or cooling for multi-setpoint thermostats in auto mode.<br />
**<''"Alexa, tell SmartThings to set the bedroom heating to 55 degrees"''> - Same as above, but just sets the heating setpoint<br />
**<''"Alexa, ask SmartThings to turn on bedroom heating mode"''> - For thermostats that have separate heating/cooling/auto mode<br />
**<''"Alexa, ask SmartThings to turn off Bedroom"''> - In this context, when bedroom is a thermostat and NOT a switch, this will turn the thermostat off (from heating/cooling or auto mode)<br />
**<''"Alexa, tell SmartThings to lower the temperature of the living room by 5 degrees"''> - You can specific the amount of the increase or decrease of the temperature setpoint (the value will be based on the current temperature...not the current setpoint).<br />
**<''"Alexa, ask SmartThings to raise the temperature of the den"''> - If no value is given, an increase or decrease in temperature (based on current temperature) will default to the value in the <<Settings>> menu.<br />
**<''"Alexa, ask SmartThings set the Hallway to auto mode"''> - In this context, when hallway is a thermostat and NOT a switch, this will turn to auto mode. Auto mode will require you to set the temperature setpoints using the 'heating' or 'cooling' command.<br />
**<''"Alexa, ask SmartThings the status of the Back Patio"''> - in cases like this, it is better to ask the status of a device and not temperature specifically.<br />
*'''Other Sensors''': ''status''<br />
**<''"Alexa, ask SmartThings the Bathroom Floor status"''><br />
**<''"Alexa, ask SmartThings about Michael"''> - In this context, Michael is a presence sensor. You will receive a response of "present" or "not present".<br />
**<''"Alexa, ask SmartThings about Kitchen Sink"''> - Notice that just the noun can be used and the ''"status"'' is assumed in most cases.<br />
*'''Modes/Routines/SHM''': ''run'', ''execute'', ''status''<br />
**<''"Alexa, tell SmartThings to execute the Good Morning routine"''><br />
**<''"Alexa, ask SmartThings the status of the current mode"''><br />
**<''"Alexa, tell SmartThings good night"''> - Assuming you have a mode or routine called "Good Night", '''Ask Alexa''' will run this mode or routine (please note you must have unique names for modes and routines to use '''Ask Alexa''' properly).<br />
**<''"Alexa, mode status from SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings about security"''> - This is another way to ask about ''status'' of Smart Home Monitor.<br />
**<''"Alexa, tell SmartThings to set security to disarm"''> - please note for the Smart Home Monitor you can also use the noun ''"security"''<br />
*'''Voice/Weather Reports''': ''run''<br />
**<''"Alexa, use SmartThings to run the Nightly report"''> - Notice the word ''"use"'' to activate the skill.<br />
**<''"Alexa, Battery report from SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings for the weather"''> - assumes the name of the weather report is 'Weather'.<br />
*'''Macros''': ''run''<br />
**<''"Alexa, tell SmartThings to set the Media Room Group to 30%"''><br />
**<''"Alexa, tell SmartThings I am going to bed"''> - Please note the creative naming of the control group in this example (Name: "I am going to bed")<br />
*'''Message Queue''': ''play'', ''open'', ''delete'', ''clear'', ''erase'', ''status''<br />
**<''"Alexa, tell SmartThings to play messages"''> Without a queue referenced, the primary message queue will play back<br />
**<''"Alexa, tell SmartThings to open {queue name} queue"''><br />
**<''"Alexa, ask SmartThings to clear message queue"''> As above, without a queue referenced the action will happen on the primary message queue<br />
*'''Connected Speakers''': ''play'', ''pause'', ''stop'', ''mute'', ''unmute'', ''next track'', ''previous track'', ''status'' <br />
**<''"Alexa, ask SmartThings to play Bedroom Speaker"''><br />
**<''"Alexa, tell SmartThings to mute Living Room"''><br />
**<''"Alexa, tell SmartThings to increase the volume of the Office"''> - When no value is given, the increase or decrease will default to the value you set up in the <<Settings>> area.<br />
**<''"Alexa, ask SmartThings about the Guest Room Speaker status"''> - Please note below about querying the status of Sonos speakers<br />
<br />
'''Notice'''<br />
The Sonos integration within SmartThings is currently in listed as a "Labs" .<br />
release. This means certain functionality is subject to change or may not work as<br />
expected. For example, if you manually play the Sonos and then ask Alexa about the <br />
status of the speaker, she may say the speaker is stopped. This is because the Alexa <br />
Enabled Device is pulling the status of the speaker from SmartThings, not the speaker itself. <br />
So, there is typically a 1 to 5 minute delay before SmartThings refreshes the speaker<br />
status. However, commands that YOU issue to the Sonos device are activated immediately.<br />
<br />
*'''Schedules''': ''on'', ''off'', ''status''<br />
**<''"Alexa, ask SmartThings about Doctor's appointment"''><br />
**<''"Alexa, tell SmartThings to turn off Golf Lesson"''><br />
<br />
===Ask Alexa Help/List Commands===<br />
<br />
Obviously, the main purpose of an application like '''Ask Alexa''' is to NOT grab your phone everytime you want to make turn on a light or turn up the speaker. However, humans are visual creatures so it is sometimes difficult to remember the specific name of a device you have included to interface with enabled device without some sort of reminder. '''Ask Alexa''' has a basic help function to guide you through which devices, modes or routine commands you can use. <br />
<br />
Please note that having Alexa call out every device and operation can be time consuming to listen to. If you need her to stop speaking, simply say <''"Alexa, stop!"''>.<br />
<br />
*'''Basic help'''<br />
**<''"Alexa, ask SmartThings for help"''> - This is just an overview of the application usage. At the very end you can confirm what version number of the Lambda code you have running.<br />
<br />
*'''Lists''' - simply issuing a 'List' command and the type of device/operation you want help on will issue a list of what is interfaced with '''Ask Alexa'''.<br />
**<''"Alexa, list switches in SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings to list switches"''><br />
**<''"Alexa, tell SmartThings to list modes"''><br />
**<''"Alexa, ask SmartThings switch list"''><br />
**<''"Alexa, ask SmartThings about the control macros"''><br />
**<''"Alexa, ask SmartThings to list humidity sensors"''><br />
**<''"Alexa, ask SmartThings about the reports"''><br />
**<''"Alexa, ask SmartThings about SHM"''><br />
**<''"Alexa, ask SmartThings about the dimmers"''> - Notice that when asking about a key word noun (dimmer, switches, etc) you can leave off the ''list''.<br />
**<''"Alexa, ask SmartThings to list the colors"''> - This option is available if you have colored lights listed within the '''Ask Alexa''' SmartApp on your mobile device. Please note that the colors list is generated from SmartThings and is quite extensive. It would take over a minute to list the colors, so instead you will be referred to the '''Ask Alexa''' cheat sheet for the full color list.<br />
**<''"Alexa, ask SmartThings to list the colored lights"''> - Please note that this is different the command above. This will give you the list of available colored lights available to control.<br />
<br />
*'''Version'''-You can get the version number of the various pieces of '''Ask Alexa'''<br />
**<''"Alexa, version of SmartThings"''> - Notice how the invocation word is at the end. <br />
**<''"Alexa, ask SmartThings about Ask Alexa"''><br />
**<''"Alexa, ask SmartThings about the SmartApp"''><br />
**<''"Alexa, ask SmartThings about versions"''><br />
<br />
*'''Repeat'''- You can request the last thing '''Ask Alexa''' said to you (no action is done, just repeat the last results)<br />
**<''"Alexa, tell SmartThings to repeat"''> <br />
**<''"Alexa, ask SmartThings again"''><br />
**<''"Alexa, ask SmartThings to replay"''><br />
<br />
<br />
There is also a special 'list' that can be retrieved from Device Group Macros (Macros that control groups of similar devices, like switches) and Macro Groups (A macro that runs groups of other macros). Examples include:<br />
*<''"Alexa, tell SmartThings to list HouseMacros"''> - In this context, "HouseSwitches" is a macro groups with child macros included. This command will list the child macros controlled by this group macro<br />
*<''"Alexa, tell SmartThings to list HouseSwtiches devices"''> - "HouseSwitches" is a device group macro. This command will list the devices controlled by this macro<br />
<br />
==Use Cases==<br />
Below are some examples of use cases on how you can use '''Ask Alexa''' to its full advantage.<br />
===Natural Language Responses===<br />
Using a control macro, you can simulate a little bit of intelligence using '''Ask Alexa'''. For example, if you have a room with a few dimmers you could set up a couple of macros called "It is too bright" and "It is too dark". In each of these macros you would set up the dimmers (SmartThings Devices Area) you want to change, and put a default increase/decrease in the provided area. At the bottom of each page you could put in a custom response such as "I have increased the brightness for you". Then, when you say <''"Alexa, tell SmartThings it is too bright"''> or <''"Alexa, tell SmartThings it is too dark"''> and it will increase or decrease the lighting as you requested. Using macro aliases you could use different versions of the phrasing and react accordingly without creating multiple macros for the same action. Future version of '''Ask Alexa''' will allow this type of control for more devices (such as thermostats).<br />
<br />
===Good Night Weekdays/Weekends (Invocation)=== <br />
Using the control, WebCoRE Trigger or voice report restrictions, you can use a single voice command to have multiple outcomes. For example, let’s say you set a different mode on the weekdays than on the weekends when you go to bed. To accomplish this you could set up two control macros; within the first macro you restrict it to run Sunday through Thursday and sets a mode called "Wake up on", and the second only runs on Friday and Saturday and sets a mode called "Wake up off". You would then create a extension group called "Good Night" which includes the first two control macros (no specific order is needed). Each night you could say <''"Alexa, tell SmartThings Good Night">.'' This would allow the same command to be issued nightly but behave differently depending on the day of the week. In the morning, a program such as [http://thingsthataresmart.wiki/index.php?title=Talking_Alarm_Clock Talking Alarm Clock] could key off of the Alarm on/Alarm off modes and react accordingly. If you are using restrictions as part of a extension group you should also click the <<Mute Restriction Messages In Extension Group>> (in the individual macros) to eliminate unwanted restriction warnings within the running of the macros.<br />
<br />
[[File:AHResitrictions.png|250px]]<br />
<br />
===Good Night Weekdays/Weekends (Native, Non-Invocation)===<br />
Similarly to the process above, you can use the native Alexa Routines, along with '''Ask Alexa''', to accomplish the same results without having to utilize the skill directly. The steps are similar to above:<br />
First, just like above, you set up two control macros with the similar weekday/weekend restrictions. You will also create the same extension group which includes these control macros. The difference here is that you will create a virtual momentary switch (using an app like Alexa Virtual Switch Creator [http://thingsthataresmart.wiki/index.php?title=Alexa_Virtual_Switch_Creator]). In this example, the switch is named "Good Night Trigger". Going back to the extension group, you enter this virtual switch in the area labled "Switch trigger for this macro". <br />
<br />
[[File:AAGoodNight.png|250px]]<br />
<br />
In your Native Alexa App, you will then create a routine called "Good Night". You can add a weather report or any other function you'd like, but the most important piece is to include turning the "Good Night Trigger" switch on. Saving the routine and simply saying <''"Alexa, Good Night"''> will set the mode to the correct setting based on the day. <br />
<br />
[[File:AlexaRoutine1.png|250px]]<br />
<br />
Please note that any output you included in the macros or extension group WILL NOT play on Alexa. You can use a message queue and an external speaker to play any output you desire.<br />
<br />
===Weather Reports and Advisories===<br />
Full weather advisories can be lengthy, and if you include them with EVERY other possible weather message (temp, location, lunar, etc.) you are almost guaranteed to exceed the default Lambda timeout (3 secs), and you'll probably exceed even a 10 second timeout if there are multiple alerts for your area. Because of this, you will need to extend your timeouts (if you want to receive the exhaustive Weather Report). Please see below for extending the timeouts. Another solution is to break your Weather Report into 2 separate reports. The first (maybe called "Weather Report") should have everything you want enabled EXCEPT the Full Weather Advisory - you'll get a notice telling you there are one or more Advisories, but not the advisory text. And the second (called "Weather Advisories") has only the temperatures, the <<Full Weather Advisories>>, and the <<Speak Location>> enabled. So, when you run your ''Weather Report'' you will hear there are advisories, and then when the report is done, you can ask Alexa to run the ''Weather Advisories'' report.<br />
<br />
Future versions of '''Ask Alexa''' will allow you to schedule a periodic check of advisories and actually push them to the message queue, which would allow for visual and audio notifications.<br />
<br />
===Basic Control Of Two Homes===<br />
By virtue of how SmartThings and Amazon implement security with their devices, you can typically only control one home's SmartThings devices with the Alexa Enabled Devices in that home. However, you can actually control devices in two different locations using a single Alexa device in each home. This use case assumes you have two SmartThings accounts (or locations) set up.<br />
<br />
To accomplish this, you first need to identify what you want to do at the remote location. This could be simply activating a switch, etc. For simplicity sake, let's use "Home A" and "Home B" as the homes you are working with, with devices, modes or routines listed as "Device A", "Mode A", "Routine A" etc for Home A, and "Device B", "Mode B", "Routine B", etc for Home B. Using this terminology, let's assume you want to control a routine in Home B from Home A's Alexa Device. Using Home B's Ask Alexa implementation you would set up a Control macro that runs Routine B, then obtain the REST endpoint of the macro in Home B you want to run (see below). Next, in Home A's '''Ask Alexa''' SmartApp, you will set up a Control Macro that includes the REST URL in the <<Run this HTTP request...>> section. Then when this Control Macro is run from Home A, Home B's devices will react. There is currently no way to currently gather status feedback from one home to another, however.<br />
<br />
[[File:ControlMacroURL.png|250px]]<br />
<br />
===Multi-Room Controls (Advanced)===<br />
'''Please Note'''<br />
This process requires a bit more effort to accomplish than a normal install.<br />
It is recommended you become familiar with the full home control before you<br />
attempt to do a multi-room install.<br />
<br />
This install does have caveats; message queues still operate, but sending apps<br />
may be confused with multiple rooms set up.<br />
<br />
Use the multi-room setup with careful consideration on the benefits vs the<br />
drawbacks.<br />
<br />
While most users will desire to control their entire home with one invocation name (typically "SmartThings" or "Home"), '''Ask Alexa''' has the ability, with a bit of work, to have a multi-room setup. Consider the following use case:<br />
<br />
You have a large home and routinely have guests over. You want the guest, when in their room, to be able to control the devices within that room without controlling the other rooms or controls in the house. While this is possible in a single-room setup using aliases and macros, this might become confusing. And, this wouldn't prevent the users in that room to do a device or command list and finding out the names of the other devices around the house.<br />
<br />
Instead, the guest in their room could say, <''"Alexa, turn off the lights in this room"''> and the lights in that specific room would go off. If they request a list of devices or commands, only the devices you set up in that room will only be listed. <br />
<br />
To accomplish this, you will need to do the following:<br />
<br />
* For each "room" you will need to have a separate app for that room<br />
** You will need to change the line in the '''Ask Alexa ''' IDE from "singleInstance: true," to "singleInstance: false," (this is currently line 26 in version 2.2.2)<br />
[[file:AAIDEAdv1.png|700px]]<br />
** You will load up another version of '''Ask Alexa ''' from the SmartThings Marketplace. It is recommended that you change the display name under Settings>>SmartApp Name to "Ask Alexa {room name}. Be sure to use the example name in the invocation name example (<<Settings><<Setup Ask Alexa>><<Invocation Name>>) to the name you set up for the room as the skill name.<br />
[[file:AANameAdv1.png|250px]] [[file:AASetup.png|250px]]<br />
* For each "room" you will need to create a separate Lambda function<br />
** For each instance of your SmartApp, you will need to associate the Oauth and Token with your Lambda code.<br />
[[File:AAAWSP10.png|700px]]<br />
** Each Lambda section will have its own unique Oauth and Token from the individual app<br />
* For each "room" you will need to create a separate skill.<br />
** You will name the invocation name the name of the room (placing, for example "this room" where "smart things" is below)<br />
[[file:AADevP1.png|701px]]<br />
**Each skill will require the ARN number from the associated Lambda function<br />
<br />
==Tips and Tricks==<br />
<br />
* The naming of your devices is extremely important for proper usage of '''Ask Alexa'''. If you have two devices named "Living Room" for example, if you ask to turn on that switch and a temperature monitor is also named that same thing, you may not get the results you desire. It is good practice to choose devices to use with '''Ask Alexa''' that have unique names. This also goes for the "labels" of the devices...you may not have empty (null) labels for any of the devices or the SmartApp will crash.<br />
* If you change any settings within you app (add/remove devices to the SmartApp, add/change modes or routines), you will need to get the proper "intents" and paste those into the Amazon Developer Site. See [[Ask_Alexa#Custom_Slot_Information]] for more information. <br />
* The longer your modes or routines are in length, the more likely Alexa will misunderstand what you are asking. Amazon recommends commands of less than three words or syllables.<br />
* By default, SmartThings adds exclamations points to is routines (for example, ''"Good Morning!"'') . While the '''Ask Alexa''' SmartApp attempts to reconcile this when evaluating what the Alexa hears, it is best practice to remove punctuation from your routines or modes.<br />
* Try speaking different ways to Alexa to get the results you want. For example, if you'd rather say the device action first, just append "using SmartThings" at the end to get the same result. For example, instead of <''"Alexa, ask SmartThings to turn on the living room"''> you could say <''"Alexa, turn on living room with SmartThings"''>. Please note that sometimes this doesn't work well depending on what you named the device or how the Alexa Enabled Device hears your commands. However, it is important to be creative in how you address Alexa. If you find that natural speech doesn't work and have a suggestion for another syntax for different types of devices, please contact the author of this app to have additional utterances created.<br />
<br />
==Troubleshooting==<br />
The following are common troubleshooting steps when working with '''Ask Alexa'''.<br />
<br />
* If you use 'smartthings' (one word) as you invocation for the skill and you find Alexa misunderstanding you and not initiating the skill, change the invocation word to 'smart things' (two words) as some users have found this to work considerably better.<br />
* There have been reports that sometimes the URL for the Setup Variables presented in the live logging will not show completely, with a portion of it being replaced with [TRUNCATED]. This is an issue with the SmartThings environment. If you encounter this, within your mobile device scroll down on the Setup Variables page. You will find the full address of the setup page. Copy this and send it (possibly via e-mail) to yourself so you can perform the setup actions using a desktop computer.<br />
[[File:AASetupURL.png|250px]]<br />
* If you see an error similar to below about a mode or routine being missing, this indicates you may have deleted one of these before removing it from '''Ask Alexa'''. To prevent issues, the list will be updated to indicate which modes or routines you need to remove from the list for proper operation. You may also see this situation when you delete an Echo device association with a room. The list presented will mark the missing device, and it should be removed from the list to ensure proper '''Ask Alexa''' operation.<br />
[[File:AAMissingMode.png|250px]]<br />
* If you can use the Amazon Developer simulator with Ask Alexa, but you get an error with the exact same command with voice, check your country selection in both the app and the developer's site. These should match and only US is supported (However, it appears UK DOES work).<br />
* When the application does not operate correctly or as you would expect, please check http://status.smartthings.com/ to ensure the SmartThings environment is working properly. If the SmartApp suddenly stops working, most of the time it is because of an outage or degraded service with SmartThings' cloud environment. Since '''Ask Alexa''' is also heavily based in the Amazon cloud environment, it is also recommended to check the status of those sites as well via http://status.aws.amazon.com/<br />
* There is a known issue where, after editing a macro, the application returns to the main SmartThings app instead of the '''Ask Alexa''' main interface. SmartThings is aware of this and is working on a resolution. This message will be removed when this issues is resolved.<br />
* Removal and renaming of internal SmartThings items (like modes and routines) or changing internal components to '''Ask Alexa''' (such as deleting macros, or renaming extensions) is not well supported in SmartThings. For example, if you have a SmartThings mode that is used in '''Ask Alexa''', deleting this from the SmartThings app BEFORE removing it from '''Ask Alexa''' could result in '''Ask Alexa''' getting confused and giving you an error is the GUI or during operation. Another observed behavior is when you have a weather report within voice report. If you plan to delete the weather report, you should remove it from all areas of the app before deleting it.<br />
* While it is expected that you can upgrade to new versions seamlessly, there are situations where internal variables within the code changes or an old scenario conflicts with new code revisions. If you upgrade and find the application no longer performs as expected, it is recommended that you remove the application completely and start from scratch with new code (this only applies to the code in SmartThings. The Lambda code and Skills data should not be affected by variables unless you change your devices).<br />
* If you receive an error in the app while working with routines, macros and devices, please be sure these items do not have commas, exclamation points, or apostrophes in them. Also, numeric values (1, 2, 3, etc) should be left out in most circumstances from devices and macros. In addition, ensure you have not inadvertently created a 'null' routine...this is a routine you may have attempted to create but abandoned. These will show up in your SmartThings IDE under you Installed SmartApps. If this happens, simply delete the routine via the IDE (<<My Locations>>, <<List SmartApps>>) by tapping <<Edit>> in the upper left corner and the <<Update>> commands will turn into <<Delete>>.<br />
<br />
[[File:AAInstalledSA.png|700px]]<br />
<br />
* When naming your macros, routines, aliases, devices or modes, ensure you don't use words that might sound the same but could be spelled differently. For example, "Kris", "Bryan", "Jon" could be heard as "Chris", "Brian" and "John", respectively. Unfortunately, while sounding the same, the app does not account for different spellings of these types of names. Therefore, it is recommended you stay away from words like this. If you must use these, it is recommended that you set up aliases with different spellings of the same name.<br />
* When making a change to your environment (add/remove devices/aliases, create new modes, etc.) you should go through the setup steps again to capture any new custom slot information. This is required so '''Ask Alexa''' and the Amazon developer site knows the 'nouns' and 'verbs' to use to process your requests.<br />
* As mentioned in the [[Ask_Alexa#Tips_and_Tricks]] section, naming (labels) of your devices are rather important. In addition, even if you name everything uniquely, there are still areas where Alexa will respond with ''"You have multiple devices that are named <device name> in your SmartThings SmartApp. Please rename these items to something unique so I may properly utlize them."''. This could be caused by you choosing the same device for different functions. For example, you can choose a thermostat (Let's say "office") and also choose it for your temperature reading or humidity sensor. This will cause an issue as Alexa has no way of understanding the context of a device that is listed multiple times. It is best practice to not only name you devices uniquely, but use them once within your device setup. For situations where you can't name devices differently, you can use the alias function(see [[Ask_Alexa#Allow_Device_Aliases]]) to utilize different names for the devices in your SmartThings account.<br />
* If you receive an error similar to this when attempting to add a new extension (like a message queue):<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the extension code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
* If you receive feedback that SmartThing SmartApp returned an error, but you see nothing in your IDE Live Logging, you may have an issue with your Application ID or Authentication token. Re-run the setup to get the proper information into your Lambda code. (See [[Ask_Alexa#Finalizing_The_Function_Code]])<br />
* If you are unable to find the Alexa Skill Kit when setting up the Event Triggers ([[Ask_Alexa#Configure_Triggers]]), be sure you have set up your account in one of the supported datacenters (i.e US East (N Virginia), US West (Oregon), etc (see [[Ask_Alexa#AWS.2FLamba_Code]])<br />
* If you find behavior that is not what you would expect from your devices, try changing your syntax of how you are referencing the device. For example, instead of <''"Alexa, tell SmartThings to turn on the Kitchen"''> try a simplistic version such as <''"Alexa, tell SmartThings Kitchen on"''>. If you find a specific syntax works better for you but is not being recognized, you may want to create (or ask for community assistance) a custom utterance for your situation. If it works well for you, you can submit that to the author of '''Ask Alexa''' for inclusion in future updates.<br />
* If you have a custom message (or a pre or post message within the voice report macro) it is recommended to use proper punctuation. This means to end the message with a period, question mark, or exclamation point. This will ensure Alexa pauses if you have a continuing message at the end of your macros.<br />
* While the Lambda accounts are "free" for the most part, you should monitor your usage as much as you can to ensure you know the volume of calls being made to your account. Amazon has some fantastic tools to accomplish this via the main dashboard of your AWS account. The dashboard can also be useful in troubleshooting errors within your application.<br />
<br />
[[file:AAAWSOpen.jpg|700px]]<br />
* If you get the error "There was an error with the requested skills response" from Alexa but the action still happens, what may be happening is that the response was taking too long to get back from SmartThings to the Amazon Lambda code. To help reduce these errors, go to your Lambda code at [https://aws.amazon.com Amazon AWS site] and find section toward the bottom of the page labeled <<Basic Settings>>.Change the <<Timeout>> section to a larger number (6 to 20 seconds should be more than enough time). You can also increase the amount of memory that your Lambda code uses. This MAY result in slightly faster response from the '''Ask Alexa''' skill; however, increasing the timing or memory too much could result in a monthly charge from Amazon. If you do increase these settings, be sure to monitor your usage closely through the Amazon tools. <br />
<br />
[[File:AATimeout.png|700px]]<br />
* '''Ask Alexa''' keys off the labels of the devices; these are what you use to address the device. If these labels are not unique or used multiple time within the SmartApp you will receive a warning at the top of the main interface page.<br />
<br />
[[File:AAWarning.png|250px]]<br />
<br />
To fix a multiple device issue, be sure to examine all of the main interface devices to ensure they are not used more than once. For example, a dimmer can also be a switch, and a motion sensor may also show up in a temperature listing. <br />
<br />
For null device labels, be sure to check the device within the IDE area <<My Devices>> to ensure the label is not blank.<br />
<br />
==Support==<br />
To obtain support for this app, you have a couple of options:<br />
<br />
* A Slack channel has been set up at https://askalexa.slack.com . You must be invited to this app and have a Slack account. This will allow real time conversation and troubleshooting with the developer to get to the bottom of any issues you might be having.<br />
* For general questions about the app, please visit the official forum for this app on the SmartThings Community Page: https://community.smartthings.com/t/release-ask-alexa/46786/<br />
<br />
==Roadmap==<br />
There are many things that can be added to this application. Be sure the visit the forum for this app (See above) for this app to request something be added to the road map. In addition, donations will help speed up development of new features. You can donate via this page: https://paypal.me/mstruck . If you are into the bitcoin market, you can also send a donation to this wallet: 1CMgaiKgBfojTBCLpHLfa9KvcrW3cNxVpm (QR Code below)<br />
<br />
[[File:MSWallet.png]]<br />
<br />
Please note that these are only proposed updates...There is currently no timeline to implement these, or any guarantee that they will be implemented at all.<br />
<br />
* % control for window shades<br />
* Continue to improve the setup process (started in 2.3.5a)<br />
* Restrictions based on which speaker is being spoken to (2.3.9)<br />
<br />
==Frequently Asked Questions (FAQs)==<br />
'''Question''': Why do I have to update the Developer JSON every time I change something in my app?<br />
<br />
'''Answer''': The framework of the app allows for great voice recognition as only items that you set up in your SmartApp are being scanned for. Technically, you could simply have every device in your environment from the beginnig. However, that increases the chance of a misunderstanding by Alexa. <br />
<br />
'''Question''': What colors does '''Ask Alexa''' support?<br />
<br />
'''Answer''': '''Ask Alexa''' supports all of the same colors supported by native SmartThings app:<br />
Soft White, Warm White, Daylight White, Cool White, White, Alice Blue, Antique White, Aqua, Aquamarine, Azure, Beige, Bisque, Blanched Almond, Blue, Blue Violet, Brown, Burly Wood, Cadet Blue, Chartreuse, Chocolate, Coral, Corn Flower Blue, Corn Silk, Crimson, Cyan, Dark Blue, Dark Cyan, Dark Golden Rod, Dark Gray, Dark Green, Dark Khaki, Dark Magenta, Dark Olive Green, Dark Orange, Dark Orchid, Dark Red, Dark Salmon, Dark Sea Green, Dark Slate Blue, Dark Slate Gray, Dark Turquoise, Dark Violet, Deep Pink, Deep Sky Blue, Dim Gray, Dodger Blue, Fire Brick, Floral White, Forest Green, Fuchsia, Gainsboro, Ghost White, Gold, Golden Rod, Gray, Green, Green Yellow, Honeydew, Hot Pink, Indian Red, Indigo, Ivory, Khaki, Lavender, Lavender Blush, Lawn Green, Lemon Chiffon, Light Blue, Light Coral, Light Cyan, Light Golden Rod Yellow, Light Gray, Light Green, Light Pink, Light Salmon, Light Sea Green, Light Sky Blue, Light Slate Gray, Light Steel Blue, Light Yellow, Lime, Lime Green, Linen, Maroon, Medium Aquamarine, Medium Blue, Medium Orchid, Medium Purple, Medium Sea Green, Medium Slate Blue, Medium Spring Green, Medium Turquoise, Medium Violet Red, Midnight Blue, Mint Cream, Misty Rose, Moccasin, Navajo White, Navy, Old Lace, Olive, Olive Drab, Orange, Orange Red, Orchid, Pale Golden Rod, Pale Green, Pale Turquoise, Pale Violet Red, Papaya Whip, Peach Puff, Peru, Pink, Plum, Powder Blue, Purple, Red, Rosy Brown, Royal Blue, Saddle Brown, Salmon, Sandy Brown, Sea Green, Sea Shell, Sienna, Silver, Sky Blue, Slate Blue, Slate Gray, Snow, Spring Green, Steel Blue, Tan, Teal, Thistle, Tomato, Turquoise, Violet, Wheat, White Smoke, Yellow and Yellow Green<br />
<br />
==How Do I Upgrade Ask Alexa==<br />
There are 3 different scenarios for upgrading '''Ask Alexa'''; each depends on what was changed in the release. Please refer to the release notes to determine which scenario applies to your situation. For a scenario 2 and 3 upgrade, you should be familiar with the installation processes for the Amazon sites listed here: [[Ask_Alexa#Developer_and_Lambda_Code_Installation]]<br />
<br />
'''Scenario 1 - IDE code change:''' Only the code (either main code, or extension code) has changed. If you have your IDE linked to GitHub (see: [[Ask_Alexa#Advanced_Installation]]), then you simply click the <<Update from Repo>> button at the top of the SmartThings IDE and check the apps that you want to update. Be sure to <<Save>> the files and <<Publish>> them in order to see the changes in your SmartThings mobile application.<br />
<br />
In addition, in a Scenario 1 installation you can also upgrade the applications using the Community Installer (Free Marketplace). See here for more information: [[Community_Installer_(Free_Marketplace)]]<br />
<br />
'''Scenario 2 - Lambda code change:''' It is rare that JUST the Lambda code will change. Sometime you must use the processes in Scenario 1 and this process to get the full upgrade. There are two ways to upgrade your Lambda code. Both require you to go to <<Settings>> <<Setup Variables>> and get your setup URL. <br />
* While displaying the setup variables on a PC, you will simply click the Lambda code link. You will be presented with code on the screen with your security parameters already in the code. You simply copy this code to https://aws.amazon.com and you are done. <br />
* For a more manual method, go into the AWS site and copy the current Token and Application ID from the current code. Copy the new code from this location (https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/ask-alexa.src/Node.js) and paste it into the code area. Then paste the Token and Application ID back into the appropriate location.<br />
<br />
[[File:AAAWSP10.png|700px]]<br />
<br />
'''Scenario 3 - Developer area changes:''' The easiest method of upgrading is to go to <<Settings>><<Setup Ask Alexa>><<Display Setup Variables Link>> and get your setup URL. While displaying this on a PC, you will simply click the Developer code link (or download the code). If you display the code, copy the entire page of JSON code and then paste it to the <<JSON Editor>> section of the Developer Build section. <br />
<br />
[[File:AADevP2.png|701px]]<br />
<br />
If you downloaded the code, simply upload the code to the site. <br />
<br />
[[File:AADevP3.png|701px]]<br />
<br />
Save and build your interaction model and you are complete.</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues&diff=13766Ask Alexa - Message Queues2018-11-22T23:46:20Z<p>MichaelStruck: /* Message Delivery */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
The Message Queues are an extension to ''Ask Alexa'', the popular SmartThings Add in. You must be running '''Ask Alexa''' to use Message Queue. More information about '''Ask Alexa''' can be found here: [[Ask Alexa]]<br />
<br />
The message queues are a holding area for external messages that may come in from other SmartApps. Unfortunately, Alexa Enabled Devices can't wake with anything other than voice (or button push) yet, so alerting in real time using these devices is impossible. However, the message queue can hold these alerts or message and they can be played back (i.e. ''<"Alexa, tell SmartThings to play {message queue name} Messages">''). If you DO need real time notifications, you also have the option of sending the notification to an external speaker or synth device.<br />
<br />
==Summary==<br />
[[File:Mailbox.png]]<br />
<br />
'''Category:''' Ask Alexa Extension - Requires [[Ask Alexa]]<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
===Latest Version===<br />
{| class="wikitable"<br />
|+The latest version this extension (as of 3/16/18)<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code'''|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy <br />
|}<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
To install the extension use the code located here:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
<br />
The steps for installation of the extensions are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
==Message Queue Options==<br />
These options will enable you to configure the '''Ask Alexa''' Message Queue. These options are global to all message queues. In other words, these settings apply to all message queues (primary and the ones you create).<br />
<br />
[[File:AAMQOptions.png|250px]]<br />
<br />
===Message Queues Displayed On Main Menu===<br />
Since messages that in the queue may be important (locks unlocked, water present), you have the ability to turn on a notification on the '''Ask Alexa''' main menu allowing you to know when messages are present and are able to view the messages without being near the Alexa device. You can also delete these messages from your message queue using the user interface.<br />
<br />
[[file:MQMain.png|250px]]<br />
<br />
===External SmartApps Delete Message Queues===<br />
Depending on the SmartApp, there may be a need to delete message from the queue (i.e. expired messages, updates to messages, etc). Enabling the <<Allow External SmartApps To Delete Message From These Queues>> option will allow those SmartApps to delete messages from the queue. Please refer to the instructions of the sending SmartApp (see: [[Ask_Alexa_-_Message_Queues#Delete_Messages_In_Message_Queue]]) to determine if you need this option enabled.<br />
<br />
===Append Alexa Output With Message Notification===<br />
When you choose Message Queues in the <<Append Alexa Output With Message Notification From These Queues>> area, a message will be appended to the Alexa output every time you use the device. For example, the conversation flow with your Alexa might be like this:<br />
<br />
'''You:''' ''"Alexa, tell SmartThings to turn off Kitchen"''<br />
'''Alexa:''' ''"I have turned off the kitchen. Please note: You have messages present in<br />
the following message queues: Primary Message Queue and John's room"''<br />
<br />
If you choose not to append your messages with these notifications, you may still query the Alexa connected device to find out if you have messages. The syntax is simply ''<"Alexa, Ask SmartThings about {message queue name}">'' You many alse delete the messages using the syntax (''<"Alexa, tell SmartThings to erase {message queue name} Messages">'' or ''<"Alexa, tell SmartThings to delete the {message queue name} Messages">'' ).<br />
<br />
===Forward Messages From Primary Queue===<br />
To support legacy applications that do not yet support the message queue extensions, the <<Forward Messages From Primary Message Queue To>> option will give you a selection of message queues to forward messages to. This setting is universal; all messages received by the primary message queue will be forwarded to queue you choose regardless of their source. When you view your message queue on the main menu, or when you play the messages from your Alexa Connected Device, the message will be appended with a note that it was forwarded from the primary message queue.<br />
<br />
This option will eventually be deprecated as partner developers migrate to the newest message queue structure.<br />
<br />
==Primary Message Queue==<br />
The Primary Message Queue is the default mail box (and can not be deleted) and provides external partners' SmartApps an area to send messages to if they do not yet support the message queue extensions. Prior to version 2.2.4, there was only one message queue; now, the user can configure multiple message queues. Most developers have committed to supporting this new structure.<br />
<br />
'''Please Note'''<br />
It is estimated before 3.0.0 the primary message queue will be deprecated. <br />
It is recommended you create your own message queues instead of using primary <br />
message queue. Current versions of '''Ask Alexa''' provide a forwarding function <br />
(see: [[Ask_Alexa_-_Message_Queues#Forward_Messages_From_Primary_Queue]]) to intercept primary message <br />
queue messages and re-directed them to another queue. This function will also deprecate, <br />
but may lag the primary message queue deprecation by a few versions.<br />
<br />
The options on this primary message queue are identical to the options you can set for the message queues you create.<br />
<br />
[[file:AAMsgQueue.png|500px]]<br />
<br />
You can choose how the messages are played back (oldest to newest, or newest to oldest) on the Alexa Connected Device. This setting is also applicable to how they are displayed on the main screen if you choose this option (see: [[Ask_Alexa_-_Message_Queues#Message_Queues_Displayed_On_Main_Menu]]). <br />
<br />
If you need real-time alerting to notifications, you have a few options. See [[Ask_Alexa_-_Message_Queues#Message_Notification_Options]] for these notification options. <br />
<br />
In each of the notification areas, you can choose to implement restrictions (global to the queue you are creating) to have times of day, presences, days of week, mode or which switches are on or off to determine if notification happens when a message arrives (the message will always be delivered to the message queue even if notifications are restricted).<br />
<br />
==Additional Message Queues==<br />
You will create new message queues similar to how new macros are created. Find the green button labeled <<Create A New Message Queue...>><br />
<br />
[[File:AANewMQ.png|250px]]<br />
<br />
As you create message queues, you will be required to enter a name for the message queue, along with different options for message playback and message notification, whether it be a light going on/off, a speaker/synth device notification, or an SMS/Push notification.<br />
<br />
'''Notice'''<br />
As mentioned a number of times, when naming your message queues, ensure your<br />
message queue names are unique not only within the context of the other queues, but <br />
within the parent app itself. That means a message queue should not share the same name <br />
with devices, aliases, modes, or routines within the parent app. Taking this precaution <br />
will eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
If you receive an error similar to this when attempting to create new message queue:<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the message queue code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
<br />
==Message Notification Options==<br />
<br />
When a message arrives within one of the message queues there are various methods you can use to either hear the message in real-time, or be alerted a message is waiting for you in the message queue.<br />
<br />
===Audio Notification===<br />
<br />
When you click the area labeled <<Message notification - Audio>> an additional set of options for output devices (speaker or synth device) will appear. When choosing this notification option, you have the choice to play the full message on the speaker, synth device or to just a notification that there is an incoming message. No matter what option you choose, your message will always be waiting on the Alexa Connected device if you simply say ''<"Alexa, tell SmartThings to play primary messages">''. If you choose to output to a speaker (like Sonos), you also have the ability to choose the voice that will be output during a message.<br />
<br />
'''Please Note'''<br />
Messages going directly to Alexa devices using TTS need to utilize applications<br />
such as Echo Speaker or Echo Speaks (http://thingsthataresmart.wiki/index.php?title=Echo_Speaks). <br />
Each of these applications allow you to setup your Alexa devices as SmartThings TTS<br />
speakers. Please note that Echo Speaks utilizes different programming commands, <br />
so if you choose devices from this be sure to check the "Echo Speaks" toggle when <br />
selecting the speakers.<br />
<br />
===Visual Notification===<br />
<br />
You can have a visual notification of a message in the message queue via an on/off light or colored light that turns on when there is a message waiting. Simply choose a light switch from the <<Turn On Lights When Messages Present>> or <<Turn On/Set Colored Lights When Messages Present>> selection areas. If you use a light to indicate a message is waiting, you also have an option to turn off the lights when the queue has been emptied (either by you or by a partner SmartApp).<br />
<br />
===Mobile Notification===<br />
<br />
If you want to be notified of a message on your mobile phone, you can choose the options in the <<Message notification - Mobile>> area.<br />
<br />
'''Notice'''<br />
Newer versions of the SmartThings Mobile App will allow you to set up specific <br />
contacts to push or send SMS messages to. The app automatically detects when<br />
you have the Contacts page available to you and will be the preferred method<br />
of contact when enabled.<br />
<br />
'''Also Note''' <br />
It has been advised by SmartThings to NOT excessively use the SMS functionality<br />
of the app. While it is fine for general notifications as you would do with the<br />
other aspects of SmartThings Mobile App, DO NOT use '''Ask Alexa''' as a way to text <br />
friends and family for recreation; doing so may require SmartThings to disable<br />
or limit this functionality in the future. If you need to generate excessive<br />
notification traffic, please use the push functionality.<br />
<br />
==Reminder About Amazon Developer Slots==<br />
<br />
Please remember ANY changes or additions you make to your '''Ask Alexa''' environment should immediately be followed up with running <<Settings>> <<Setup Variables>> in the main '''Ask Alexa''' SmartApp. This will allow newly created message queues to be reflected in the Amazon developer site. See [[Ask_Alexa#Setup_Variables]] for more information.<br />
<br />
==Message Delivery==<br />
Please note that while message delivery using the 'sendLocationEvent' is rather consistent, this is a non-standard way to exchange information between SmartApps...If your app sends out multiple messages per second, there is a possibility that the message may not be processed by '''Ask Alexa'''. It is recommended you meter the speed at which messages are sent to the queue while a message verification system is being developed.<br />
<br />
==Advanced: Interfacing With Ask Alexa (Developers)==<br />
Within the SmartThings environment, each SmartApp runs independently from each other. For example, '''Ask Alexa''' can not interfere with CoRE, or vis-versa. However, the drawback of this is that SmartApps can not work together in normal circumstances. However, there are ways for SmartApps to share information using the ''SmartThings location events''. This is how CoRE, for example, knows the names of the '''Ask Alexa''' Macros, or knows when a macro has run. <br />
<br />
With the implementation of the Message Queues in '''Ask Alexa''', a standard method of sending messages to '''Ask Alexa''' is required. The '''SmartThings location events''' will serve this purpose. If you are a developer of a SmartApp and wish to send messages to the '''Ask Alexa''' Message Queue you will need to conform your output to the follow standards.<br />
<br />
Currently, the following community apps [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa#Compatibility_With_Other_SmartApps] support or plan to support the message queue (items with (2.0) in them can utilize the user-created message queues).<br />
<br />
===Send Messages To Ask Alexa===<br />
There are two required steps in order to interface with '''Ask Alexa''''s message queues:<br />
<br />
* First, you must subscribe to the ''askAlexaMQ'' location event. This will feed your app a list of available message queues within '''Ask Alexa'''. The formatting of this command is simple:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
The location information you receive back will have a data field with the list of queues available. It is recommended you place these in a state variable like this:<br />
<br />
<pre style="display: inline-block;"> <br />
def askAlexaMQHandler(evt) {<br />
if (!evt) return<br />
switch (evt.value) {<br />
case "refresh":<br />
state.askAlexaMQ = evt.jsonData && evt.jsonData?.queues ? evt.jsonData.queues : []<br />
break<br />
}<br />
}<br />
</pre><br />
<br />
Please note the queues listing will be a data map with the ID and the name of the queue. <br />
<br />
* Second, with the information above, you will typically deliver an option to the end user with a list of where to send the output. You can do with with an "enum" input like this:<br />
<br />
<pre style="display: inline-block;"><br />
input "listOfMQs", "enum", title: "This is a list of the Ask Alexa Message Queues", options: state.askAlexaMQ, multiple: true, required: false<br />
</pre><br />
<br />
Then, when you are ready to trigger the output you will use a ''sendLocationEvent()'' with the follow parameters:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueue", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
descriptionText: "This is the message I am sending to Ask Alexa", <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...],<br />
overwrite: true*,<br />
expires: seconds**,<br />
notifyOnly: true*,<br />
suppressTimeDate: true*,<br />
trackDelete: true*<br />
]<br />
)<br />
<br />
*='overwrite','suppressTimeDate', 'notifyOnly' and 'trackDelete' default to 'false' if these parameters are not used<br />
**=Having no value in this field means the system will keep the message in the queue until deleted by the <br />
user or in bulk by the sending application<br />
</pre><br />
<br />
As seen here in the SmartThings documentation [http://docs.smartthings.com/en/latest/ref-docs/smartapp-ref.html?highlight=sendlocationevent], there are many parameters you can use when logging a Location Event (using ''sendLocationEvent()''). '''Ask Alexa''' uses these:<br />
{| class = "wikitable"<br />
! '''Parameter''' !! '''Information'''<br />
|-<br />
|'''name'''|| This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueue''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name that be spoken as part of the Message Queue voice message.<br />
|-<br />
|'''descriptionText''' || This is the message you wish to have Alexa play.<br />
|-<br />
|'''isStateChange''' || This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is OPTIONAL for sending message to the message queue, but REQUIRED if you ever want your app to delete messages from the queue. Setting 'unit' provides additional security by allowing sending apps to delete specific messages from the message queue, either in bulk, or by individual message. It is the responsibility of the sending app to keep track and organize their ID ('''unit''') naming structure so that other applications don't accidentally delete their messages within the queue. This can be any STRING designated by the sending app.<br />
|-<br />
|'''data''' || This field allows for future expansion. See below for the current labels/tags.<br />
|}<br />
<br />
<br />
<br />
{| class = "wikitable"<br />
|+Data field items<br />
! '''Data Label''' !! '''How used'''<br />
|-<br />
|'''queues'''|| This is a map of the message queues that should accept the messages. Please note that these will be either the message queue AppID or "Primary Message Queue". It is recommended you obtain the map from the list sent by '''Ask Alexa''' <br />
|-<br />
|'''overwrite'''|| "true" or "false" (lower case). Defaults to "false" if no value is given. This is similar to the message queue delete function (see [[Ask_Alexa#Delete_Messages_In_Message_Queue]] in that it requires the value and unit fields to be populated. In addition, the user must still enable the ability for smartapps to delete messages. This function is perfect for applications that send multiple entries (like a door opening or closing) but only the latest value is relevant.<br />
|-<br />
|'''expires'''|| This is the number of seconds from when the message is received that it will automatically remove itself from the message queue. It is recommended that you give the user the option to enter a number in minutes, then multiple this number by 60 to send '''Ask Alexa''' the number of seconds.<br />
|-<br />
|'''notifyOnly'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to only notify (based on the user's notification settings) to a message an NOT place it into the message queue. It is up to the user to ensure that notifications (Visual, Audio or Mobile) are enabled as the message will be be saved if no notification options are enabled. This option is good for real-time alerting (such as weather advisories) that are not relevant even moments after the message is sent<br />
|-<br />
|'''suppressTimeDate'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to suppress the time and date playback when listening to messages from the queue on the Alexa. Users have the option to suppress this information on a global queue basis; this option allows for the suppression to be on a per-message basis. This is useful for smartapps that embed their own time date information into the messages. For example, "The bedroom light was turned on at 4:45pm on Tuesday"...it would be a little redundant to have a header that also told the time and date.<br />
|-<br />
|'''trackDelete'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to be sent a sendLocationEvent (value = messageValue.messageUnit) when the message expires or is deleted by the user.<br />
|-<br />
|}<br />
<br />
===Receiving Message===<br />
To receive these messages, '''Ask Alexa''' subscribes to the location event like this:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "AskAlexaMsgQueue", msgHandler)<br />
</pre><br />
<br />
The message, once received, is placed into a state variable within the application. Since Alexa can not wake on alerts (see [[Ask_Alexa#Limitations]]), the alerts are kept in this variable until the user initiates a command using '''Ask Alexa'''. When the action requested is completed, the user is alerted to the pending message(s), giving them the option to play the messages.<br />
<br />
At this time, there is no scheduling function for these notes. In other words, the sending app is responsible for delivering messages to '''Ask Alexa''', and the date stamp is dependent on the order in which they are received. The user has the option to play oldest first, or newest first (default it oldest first).<br />
<br />
'''Please Note'''<br />
In a multi-room setup (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]]), the messages<br />
will still go to each instance of the app you have set up. This will change as '''Ask Alexa''' <br />
is further developed and Amazon opens up the 'push' notification function.<br />
<br />
===Delete Messages In Message Queue===<br />
The message queue is very flexible in how it can be used; however, with anything voice related it is always important to balance between information relevance and quantity. For example, if you have an app that alerts (sends messages to the queue) of a non-critical nature (maybe some sort of information only message), it may not be important for the user to hear all of the messages if the original alert/notification has subsequently cleared. As such, using both the '''value''' and '''unit''' parameters, a developer can issue a ''sendLocationEvent()'' that will allow an external app to selectively delete messages that may have sent to the '''Ask Alexa''' queue previously. For this option to work, the end user must enable the queue to allow for deletions (see [[Ask_Alexa#External_SmartApps_Delete_Message_Queues]])<br />
<br />
'''Please Note:'''<br />
You must use send the '''unit''' and '''value''' parameter when sending the original message<br />
to successfully delete messages from the message queue. This is to prevent <br />
one app from deleting another app's messages when the same application name ('''value''') is used. <br />
You will be UNABLE to delete any message from the queue if the '''unit''' parameter is missing. <br />
As such, your '''unit''' parameter should be unique. Depending on your needs, this '''unit''' <br />
parameter can be unique to every messages (allowing individual messages to be deleted), or the <br />
same for every message and the sending app, allowing ALL messages with that unique identifier <br />
to be deleted in bulk. <br />
<br />
To issue a delete command to the message queue, use the following parameters:<br />
{| class = "wikitable"<br />
|'''name''' || This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueueDelete''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name. This '''value''' must match the original message(s) that you are attempting to delete.<br />
|-<br />
|'''isStateChange'''|| This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is REQUIRED for a delete. This is a string value and MUST match the message(s) you want to delete. As mentioned above, to delete messages in bulk, simply use a '''unit''' parameter that is linked to the '''value''' parameter. Or, individual messages can be selectively deleted by having the '''unit''' parameter unique to each message sent from the app. <br />
|-<br />
|'''data''' || This field allows for future expansion. Currently, it is used to send a map of message queues IDs/Labels to partner applications.<br />
|}<br />
<br />
Putting this together, the syntax within your SmartApp would look like this:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueueDelete", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...]<br />
]<br />
)<br />
</pre><br />
<br />
Currently, there are no "wildcard" searches for the '''unit''' parameter. To delete multiple messages, separate ''sendLocationEvent()'' commands should be sent for every unique '''unit''' parameter.<br />
<br />
===Refresh Message Queue List===<br />
<br />
For developers that may want to install and app and immediately refresh the list of message queues available (instead of going out of the newly installed app and then going into Ask Alexa, then back into the the app, you can call the following command:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMQRefresh", <br />
isStateChange: true <br />
)<br />
</pre><br />
<br />
The list will be rebroadcast as mentioned above using the "askAlexaMQ.refresh" event value.<br />
<br />
===Track Deletion Of Messages===<br />
If your app needs to know if a message you sent has been deleted, you must first tag you message. You do this in the "data" field by setting the "trackDelete" to "true" (see [[Ask_Alexa_-_Message_Queues#Send_Messages_To_Ask_Alexa]])<br />
<br />
Next, you app should already be subscribed to the "askAlexaMQ" location event:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
At the method "askAlexaMQHandler(evt)", you will look for the evt.value of the your original message's app name (value) and message id (unit) combined with a period between them.<br />
<br />
For example, if your a is "MyApp" and your message id is 1234, you will look for this combination<br />
<br />
<pre style="display: inline-block;"><br />
def askAlexaMQHandler(evt){<br />
if (evt.value == "MyApp.1234") {<br />
<Event to occur when your message is deleted><br />
}<br />
}<br />
</pre><br />
<br />
If you need to know if the deletion of the message was a clearing of the queue (user invoked), an app deletion (usually through an overwrite or when your app deletes a message), or through expiration of a message, the data field delivered with the askAlexMQ event will include the following JSON fields:<br />
<br />
* '''deleteType:''' "delete", "delete all" or "expire"<br />
* '''queues:''' The message queue name where the message was removed from</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues&diff=13765Ask Alexa - Message Queues2018-11-22T23:22:56Z<p>MichaelStruck: /* Audio Notification */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
The Message Queues are an extension to ''Ask Alexa'', the popular SmartThings Add in. You must be running '''Ask Alexa''' to use Message Queue. More information about '''Ask Alexa''' can be found here: [[Ask Alexa]]<br />
<br />
The message queues are a holding area for external messages that may come in from other SmartApps. Unfortunately, Alexa Enabled Devices can't wake with anything other than voice (or button push) yet, so alerting in real time using these devices is impossible. However, the message queue can hold these alerts or message and they can be played back (i.e. ''<"Alexa, tell SmartThings to play {message queue name} Messages">''). If you DO need real time notifications, you also have the option of sending the notification to an external speaker or synth device.<br />
<br />
==Summary==<br />
[[File:Mailbox.png]]<br />
<br />
'''Category:''' Ask Alexa Extension - Requires [[Ask Alexa]]<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
===Latest Version===<br />
{| class="wikitable"<br />
|+The latest version this extension (as of 3/16/18)<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code'''|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy <br />
|}<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
To install the extension use the code located here:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
<br />
The steps for installation of the extensions are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
==Message Queue Options==<br />
These options will enable you to configure the '''Ask Alexa''' Message Queue. These options are global to all message queues. In other words, these settings apply to all message queues (primary and the ones you create).<br />
<br />
[[File:AAMQOptions.png|250px]]<br />
<br />
===Message Queues Displayed On Main Menu===<br />
Since messages that in the queue may be important (locks unlocked, water present), you have the ability to turn on a notification on the '''Ask Alexa''' main menu allowing you to know when messages are present and are able to view the messages without being near the Alexa device. You can also delete these messages from your message queue using the user interface.<br />
<br />
[[file:MQMain.png|250px]]<br />
<br />
===External SmartApps Delete Message Queues===<br />
Depending on the SmartApp, there may be a need to delete message from the queue (i.e. expired messages, updates to messages, etc). Enabling the <<Allow External SmartApps To Delete Message From These Queues>> option will allow those SmartApps to delete messages from the queue. Please refer to the instructions of the sending SmartApp (see: [[Ask_Alexa_-_Message_Queues#Delete_Messages_In_Message_Queue]]) to determine if you need this option enabled.<br />
<br />
===Append Alexa Output With Message Notification===<br />
When you choose Message Queues in the <<Append Alexa Output With Message Notification From These Queues>> area, a message will be appended to the Alexa output every time you use the device. For example, the conversation flow with your Alexa might be like this:<br />
<br />
'''You:''' ''"Alexa, tell SmartThings to turn off Kitchen"''<br />
'''Alexa:''' ''"I have turned off the kitchen. Please note: You have messages present in<br />
the following message queues: Primary Message Queue and John's room"''<br />
<br />
If you choose not to append your messages with these notifications, you may still query the Alexa connected device to find out if you have messages. The syntax is simply ''<"Alexa, Ask SmartThings about {message queue name}">'' You many alse delete the messages using the syntax (''<"Alexa, tell SmartThings to erase {message queue name} Messages">'' or ''<"Alexa, tell SmartThings to delete the {message queue name} Messages">'' ).<br />
<br />
===Forward Messages From Primary Queue===<br />
To support legacy applications that do not yet support the message queue extensions, the <<Forward Messages From Primary Message Queue To>> option will give you a selection of message queues to forward messages to. This setting is universal; all messages received by the primary message queue will be forwarded to queue you choose regardless of their source. When you view your message queue on the main menu, or when you play the messages from your Alexa Connected Device, the message will be appended with a note that it was forwarded from the primary message queue.<br />
<br />
This option will eventually be deprecated as partner developers migrate to the newest message queue structure.<br />
<br />
==Primary Message Queue==<br />
The Primary Message Queue is the default mail box (and can not be deleted) and provides external partners' SmartApps an area to send messages to if they do not yet support the message queue extensions. Prior to version 2.2.4, there was only one message queue; now, the user can configure multiple message queues. Most developers have committed to supporting this new structure.<br />
<br />
'''Please Note'''<br />
It is estimated before 3.0.0 the primary message queue will be deprecated. <br />
It is recommended you create your own message queues instead of using primary <br />
message queue. Current versions of '''Ask Alexa''' provide a forwarding function <br />
(see: [[Ask_Alexa_-_Message_Queues#Forward_Messages_From_Primary_Queue]]) to intercept primary message <br />
queue messages and re-directed them to another queue. This function will also deprecate, <br />
but may lag the primary message queue deprecation by a few versions.<br />
<br />
The options on this primary message queue are identical to the options you can set for the message queues you create.<br />
<br />
[[file:AAMsgQueue.png|500px]]<br />
<br />
You can choose how the messages are played back (oldest to newest, or newest to oldest) on the Alexa Connected Device. This setting is also applicable to how they are displayed on the main screen if you choose this option (see: [[Ask_Alexa_-_Message_Queues#Message_Queues_Displayed_On_Main_Menu]]). <br />
<br />
If you need real-time alerting to notifications, you have a few options. See [[Ask_Alexa_-_Message_Queues#Message_Notification_Options]] for these notification options. <br />
<br />
In each of the notification areas, you can choose to implement restrictions (global to the queue you are creating) to have times of day, presences, days of week, mode or which switches are on or off to determine if notification happens when a message arrives (the message will always be delivered to the message queue even if notifications are restricted).<br />
<br />
==Additional Message Queues==<br />
You will create new message queues similar to how new macros are created. Find the green button labeled <<Create A New Message Queue...>><br />
<br />
[[File:AANewMQ.png|250px]]<br />
<br />
As you create message queues, you will be required to enter a name for the message queue, along with different options for message playback and message notification, whether it be a light going on/off, a speaker/synth device notification, or an SMS/Push notification.<br />
<br />
'''Notice'''<br />
As mentioned a number of times, when naming your message queues, ensure your<br />
message queue names are unique not only within the context of the other queues, but <br />
within the parent app itself. That means a message queue should not share the same name <br />
with devices, aliases, modes, or routines within the parent app. Taking this precaution <br />
will eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
If you receive an error similar to this when attempting to create new message queue:<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the message queue code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
<br />
==Message Notification Options==<br />
<br />
When a message arrives within one of the message queues there are various methods you can use to either hear the message in real-time, or be alerted a message is waiting for you in the message queue.<br />
<br />
===Audio Notification===<br />
<br />
When you click the area labeled <<Message notification - Audio>> an additional set of options for output devices (speaker or synth device) will appear. When choosing this notification option, you have the choice to play the full message on the speaker, synth device or to just a notification that there is an incoming message. No matter what option you choose, your message will always be waiting on the Alexa Connected device if you simply say ''<"Alexa, tell SmartThings to play primary messages">''. If you choose to output to a speaker (like Sonos), you also have the ability to choose the voice that will be output during a message.<br />
<br />
'''Please Note'''<br />
Messages going directly to Alexa devices using TTS need to utilize applications<br />
such as Echo Speaker or Echo Speaks (http://thingsthataresmart.wiki/index.php?title=Echo_Speaks). <br />
Each of these applications allow you to setup your Alexa devices as SmartThings TTS<br />
speakers. Please note that Echo Speaks utilizes different programming commands, <br />
so if you choose devices from this be sure to check the "Echo Speaks" toggle when <br />
selecting the speakers.<br />
<br />
===Visual Notification===<br />
<br />
You can have a visual notification of a message in the message queue via an on/off light or colored light that turns on when there is a message waiting. Simply choose a light switch from the <<Turn On Lights When Messages Present>> or <<Turn On/Set Colored Lights When Messages Present>> selection areas. If you use a light to indicate a message is waiting, you also have an option to turn off the lights when the queue has been emptied (either by you or by a partner SmartApp).<br />
<br />
===Mobile Notification===<br />
<br />
If you want to be notified of a message on your mobile phone, you can choose the options in the <<Message notification - Mobile>> area.<br />
<br />
'''Notice'''<br />
Newer versions of the SmartThings Mobile App will allow you to set up specific <br />
contacts to push or send SMS messages to. The app automatically detects when<br />
you have the Contacts page available to you and will be the preferred method<br />
of contact when enabled.<br />
<br />
'''Also Note''' <br />
It has been advised by SmartThings to NOT excessively use the SMS functionality<br />
of the app. While it is fine for general notifications as you would do with the<br />
other aspects of SmartThings Mobile App, DO NOT use '''Ask Alexa''' as a way to text <br />
friends and family for recreation; doing so may require SmartThings to disable<br />
or limit this functionality in the future. If you need to generate excessive<br />
notification traffic, please use the push functionality.<br />
<br />
==Reminder About Amazon Developer Slots==<br />
<br />
Please remember ANY changes or additions you make to your '''Ask Alexa''' environment should immediately be followed up with running <<Settings>> <<Setup Variables>> in the main '''Ask Alexa''' SmartApp. This will allow newly created message queues to be reflected in the Amazon developer site. See [[Ask_Alexa#Setup_Variables]] for more information.<br />
<br />
==Message Delivery==<br />
Please note that while message delivery using the 'sendLocationEvent' is rather consistent, the is a non-standard way to exchange information between SmartApps...If your app sends out multiple messages per second, there is a possibility that the message may not be processed by '''Ask Alexa'''. It is recommended you meter the speed at which messages are sent to the queue while a message verification system is being developed.<br />
<br />
==Advanced: Interfacing With Ask Alexa (Developers)==<br />
Within the SmartThings environment, each SmartApp runs independently from each other. For example, '''Ask Alexa''' can not interfere with CoRE, or vis-versa. However, the drawback of this is that SmartApps can not work together in normal circumstances. However, there are ways for SmartApps to share information using the ''SmartThings location events''. This is how CoRE, for example, knows the names of the '''Ask Alexa''' Macros, or knows when a macro has run. <br />
<br />
With the implementation of the Message Queues in '''Ask Alexa''', a standard method of sending messages to '''Ask Alexa''' is required. The '''SmartThings location events''' will serve this purpose. If you are a developer of a SmartApp and wish to send messages to the '''Ask Alexa''' Message Queue you will need to conform your output to the follow standards.<br />
<br />
Currently, the following community apps [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa#Compatibility_With_Other_SmartApps] support or plan to support the message queue (items with (2.0) in them can utilize the user-created message queues).<br />
<br />
===Send Messages To Ask Alexa===<br />
There are two required steps in order to interface with '''Ask Alexa''''s message queues:<br />
<br />
* First, you must subscribe to the ''askAlexaMQ'' location event. This will feed your app a list of available message queues within '''Ask Alexa'''. The formatting of this command is simple:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
The location information you receive back will have a data field with the list of queues available. It is recommended you place these in a state variable like this:<br />
<br />
<pre style="display: inline-block;"> <br />
def askAlexaMQHandler(evt) {<br />
if (!evt) return<br />
switch (evt.value) {<br />
case "refresh":<br />
state.askAlexaMQ = evt.jsonData && evt.jsonData?.queues ? evt.jsonData.queues : []<br />
break<br />
}<br />
}<br />
</pre><br />
<br />
Please note the queues listing will be a data map with the ID and the name of the queue. <br />
<br />
* Second, with the information above, you will typically deliver an option to the end user with a list of where to send the output. You can do with with an "enum" input like this:<br />
<br />
<pre style="display: inline-block;"><br />
input "listOfMQs", "enum", title: "This is a list of the Ask Alexa Message Queues", options: state.askAlexaMQ, multiple: true, required: false<br />
</pre><br />
<br />
Then, when you are ready to trigger the output you will use a ''sendLocationEvent()'' with the follow parameters:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueue", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
descriptionText: "This is the message I am sending to Ask Alexa", <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...],<br />
overwrite: true*,<br />
expires: seconds**,<br />
notifyOnly: true*,<br />
suppressTimeDate: true*,<br />
trackDelete: true*<br />
]<br />
)<br />
<br />
*='overwrite','suppressTimeDate', 'notifyOnly' and 'trackDelete' default to 'false' if these parameters are not used<br />
**=Having no value in this field means the system will keep the message in the queue until deleted by the <br />
user or in bulk by the sending application<br />
</pre><br />
<br />
As seen here in the SmartThings documentation [http://docs.smartthings.com/en/latest/ref-docs/smartapp-ref.html?highlight=sendlocationevent], there are many parameters you can use when logging a Location Event (using ''sendLocationEvent()''). '''Ask Alexa''' uses these:<br />
{| class = "wikitable"<br />
! '''Parameter''' !! '''Information'''<br />
|-<br />
|'''name'''|| This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueue''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name that be spoken as part of the Message Queue voice message.<br />
|-<br />
|'''descriptionText''' || This is the message you wish to have Alexa play.<br />
|-<br />
|'''isStateChange''' || This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is OPTIONAL for sending message to the message queue, but REQUIRED if you ever want your app to delete messages from the queue. Setting 'unit' provides additional security by allowing sending apps to delete specific messages from the message queue, either in bulk, or by individual message. It is the responsibility of the sending app to keep track and organize their ID ('''unit''') naming structure so that other applications don't accidentally delete their messages within the queue. This can be any STRING designated by the sending app.<br />
|-<br />
|'''data''' || This field allows for future expansion. See below for the current labels/tags.<br />
|}<br />
<br />
<br />
<br />
{| class = "wikitable"<br />
|+Data field items<br />
! '''Data Label''' !! '''How used'''<br />
|-<br />
|'''queues'''|| This is a map of the message queues that should accept the messages. Please note that these will be either the message queue AppID or "Primary Message Queue". It is recommended you obtain the map from the list sent by '''Ask Alexa''' <br />
|-<br />
|'''overwrite'''|| "true" or "false" (lower case). Defaults to "false" if no value is given. This is similar to the message queue delete function (see [[Ask_Alexa#Delete_Messages_In_Message_Queue]] in that it requires the value and unit fields to be populated. In addition, the user must still enable the ability for smartapps to delete messages. This function is perfect for applications that send multiple entries (like a door opening or closing) but only the latest value is relevant.<br />
|-<br />
|'''expires'''|| This is the number of seconds from when the message is received that it will automatically remove itself from the message queue. It is recommended that you give the user the option to enter a number in minutes, then multiple this number by 60 to send '''Ask Alexa''' the number of seconds.<br />
|-<br />
|'''notifyOnly'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to only notify (based on the user's notification settings) to a message an NOT place it into the message queue. It is up to the user to ensure that notifications (Visual, Audio or Mobile) are enabled as the message will be be saved if no notification options are enabled. This option is good for real-time alerting (such as weather advisories) that are not relevant even moments after the message is sent<br />
|-<br />
|'''suppressTimeDate'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to suppress the time and date playback when listening to messages from the queue on the Alexa. Users have the option to suppress this information on a global queue basis; this option allows for the suppression to be on a per-message basis. This is useful for smartapps that embed their own time date information into the messages. For example, "The bedroom light was turned on at 4:45pm on Tuesday"...it would be a little redundant to have a header that also told the time and date.<br />
|-<br />
|'''trackDelete'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to be sent a sendLocationEvent (value = messageValue.messageUnit) when the message expires or is deleted by the user.<br />
|-<br />
|}<br />
<br />
===Receiving Message===<br />
To receive these messages, '''Ask Alexa''' subscribes to the location event like this:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "AskAlexaMsgQueue", msgHandler)<br />
</pre><br />
<br />
The message, once received, is placed into a state variable within the application. Since Alexa can not wake on alerts (see [[Ask_Alexa#Limitations]]), the alerts are kept in this variable until the user initiates a command using '''Ask Alexa'''. When the action requested is completed, the user is alerted to the pending message(s), giving them the option to play the messages.<br />
<br />
At this time, there is no scheduling function for these notes. In other words, the sending app is responsible for delivering messages to '''Ask Alexa''', and the date stamp is dependent on the order in which they are received. The user has the option to play oldest first, or newest first (default it oldest first).<br />
<br />
'''Please Note'''<br />
In a multi-room setup (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]]), the messages<br />
will still go to each instance of the app you have set up. This will change as '''Ask Alexa''' <br />
is further developed and Amazon opens up the 'push' notification function.<br />
<br />
===Delete Messages In Message Queue===<br />
The message queue is very flexible in how it can be used; however, with anything voice related it is always important to balance between information relevance and quantity. For example, if you have an app that alerts (sends messages to the queue) of a non-critical nature (maybe some sort of information only message), it may not be important for the user to hear all of the messages if the original alert/notification has subsequently cleared. As such, using both the '''value''' and '''unit''' parameters, a developer can issue a ''sendLocationEvent()'' that will allow an external app to selectively delete messages that may have sent to the '''Ask Alexa''' queue previously. For this option to work, the end user must enable the queue to allow for deletions (see [[Ask_Alexa#External_SmartApps_Delete_Message_Queues]])<br />
<br />
'''Please Note:'''<br />
You must use send the '''unit''' and '''value''' parameter when sending the original message<br />
to successfully delete messages from the message queue. This is to prevent <br />
one app from deleting another app's messages when the same application name ('''value''') is used. <br />
You will be UNABLE to delete any message from the queue if the '''unit''' parameter is missing. <br />
As such, your '''unit''' parameter should be unique. Depending on your needs, this '''unit''' <br />
parameter can be unique to every messages (allowing individual messages to be deleted), or the <br />
same for every message and the sending app, allowing ALL messages with that unique identifier <br />
to be deleted in bulk. <br />
<br />
To issue a delete command to the message queue, use the following parameters:<br />
{| class = "wikitable"<br />
|'''name''' || This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueueDelete''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name. This '''value''' must match the original message(s) that you are attempting to delete.<br />
|-<br />
|'''isStateChange'''|| This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is REQUIRED for a delete. This is a string value and MUST match the message(s) you want to delete. As mentioned above, to delete messages in bulk, simply use a '''unit''' parameter that is linked to the '''value''' parameter. Or, individual messages can be selectively deleted by having the '''unit''' parameter unique to each message sent from the app. <br />
|-<br />
|'''data''' || This field allows for future expansion. Currently, it is used to send a map of message queues IDs/Labels to partner applications.<br />
|}<br />
<br />
Putting this together, the syntax within your SmartApp would look like this:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueueDelete", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...]<br />
]<br />
)<br />
</pre><br />
<br />
Currently, there are no "wildcard" searches for the '''unit''' parameter. To delete multiple messages, separate ''sendLocationEvent()'' commands should be sent for every unique '''unit''' parameter.<br />
<br />
===Refresh Message Queue List===<br />
<br />
For developers that may want to install and app and immediately refresh the list of message queues available (instead of going out of the newly installed app and then going into Ask Alexa, then back into the the app, you can call the following command:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMQRefresh", <br />
isStateChange: true <br />
)<br />
</pre><br />
<br />
The list will be rebroadcast as mentioned above using the "askAlexaMQ.refresh" event value.<br />
<br />
===Track Deletion Of Messages===<br />
If your app needs to know if a message you sent has been deleted, you must first tag you message. You do this in the "data" field by setting the "trackDelete" to "true" (see [[Ask_Alexa_-_Message_Queues#Send_Messages_To_Ask_Alexa]])<br />
<br />
Next, you app should already be subscribed to the "askAlexaMQ" location event:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
At the method "askAlexaMQHandler(evt)", you will look for the evt.value of the your original message's app name (value) and message id (unit) combined with a period between them.<br />
<br />
For example, if your a is "MyApp" and your message id is 1234, you will look for this combination<br />
<br />
<pre style="display: inline-block;"><br />
def askAlexaMQHandler(evt){<br />
if (evt.value == "MyApp.1234") {<br />
<Event to occur when your message is deleted><br />
}<br />
}<br />
</pre><br />
<br />
If you need to know if the deletion of the message was a clearing of the queue (user invoked), an app deletion (usually through an overwrite or when your app deletes a message), or through expiration of a message, the data field delivered with the askAlexMQ event will include the following JSON fields:<br />
<br />
* '''deleteType:''' "delete", "delete all" or "expire"<br />
* '''queues:''' The message queue name where the message was removed from</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues&diff=13764Ask Alexa - Message Queues2018-11-22T23:21:11Z<p>MichaelStruck: /* Audio Notification */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
The Message Queues are an extension to ''Ask Alexa'', the popular SmartThings Add in. You must be running '''Ask Alexa''' to use Message Queue. More information about '''Ask Alexa''' can be found here: [[Ask Alexa]]<br />
<br />
The message queues are a holding area for external messages that may come in from other SmartApps. Unfortunately, Alexa Enabled Devices can't wake with anything other than voice (or button push) yet, so alerting in real time using these devices is impossible. However, the message queue can hold these alerts or message and they can be played back (i.e. ''<"Alexa, tell SmartThings to play {message queue name} Messages">''). If you DO need real time notifications, you also have the option of sending the notification to an external speaker or synth device.<br />
<br />
==Summary==<br />
[[File:Mailbox.png]]<br />
<br />
'''Category:''' Ask Alexa Extension - Requires [[Ask Alexa]]<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
===Latest Version===<br />
{| class="wikitable"<br />
|+The latest version this extension (as of 3/16/18)<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code'''|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy <br />
|}<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
To install the extension use the code located here:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
<br />
The steps for installation of the extensions are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
==Message Queue Options==<br />
These options will enable you to configure the '''Ask Alexa''' Message Queue. These options are global to all message queues. In other words, these settings apply to all message queues (primary and the ones you create).<br />
<br />
[[File:AAMQOptions.png|250px]]<br />
<br />
===Message Queues Displayed On Main Menu===<br />
Since messages that in the queue may be important (locks unlocked, water present), you have the ability to turn on a notification on the '''Ask Alexa''' main menu allowing you to know when messages are present and are able to view the messages without being near the Alexa device. You can also delete these messages from your message queue using the user interface.<br />
<br />
[[file:MQMain.png|250px]]<br />
<br />
===External SmartApps Delete Message Queues===<br />
Depending on the SmartApp, there may be a need to delete message from the queue (i.e. expired messages, updates to messages, etc). Enabling the <<Allow External SmartApps To Delete Message From These Queues>> option will allow those SmartApps to delete messages from the queue. Please refer to the instructions of the sending SmartApp (see: [[Ask_Alexa_-_Message_Queues#Delete_Messages_In_Message_Queue]]) to determine if you need this option enabled.<br />
<br />
===Append Alexa Output With Message Notification===<br />
When you choose Message Queues in the <<Append Alexa Output With Message Notification From These Queues>> area, a message will be appended to the Alexa output every time you use the device. For example, the conversation flow with your Alexa might be like this:<br />
<br />
'''You:''' ''"Alexa, tell SmartThings to turn off Kitchen"''<br />
'''Alexa:''' ''"I have turned off the kitchen. Please note: You have messages present in<br />
the following message queues: Primary Message Queue and John's room"''<br />
<br />
If you choose not to append your messages with these notifications, you may still query the Alexa connected device to find out if you have messages. The syntax is simply ''<"Alexa, Ask SmartThings about {message queue name}">'' You many alse delete the messages using the syntax (''<"Alexa, tell SmartThings to erase {message queue name} Messages">'' or ''<"Alexa, tell SmartThings to delete the {message queue name} Messages">'' ).<br />
<br />
===Forward Messages From Primary Queue===<br />
To support legacy applications that do not yet support the message queue extensions, the <<Forward Messages From Primary Message Queue To>> option will give you a selection of message queues to forward messages to. This setting is universal; all messages received by the primary message queue will be forwarded to queue you choose regardless of their source. When you view your message queue on the main menu, or when you play the messages from your Alexa Connected Device, the message will be appended with a note that it was forwarded from the primary message queue.<br />
<br />
This option will eventually be deprecated as partner developers migrate to the newest message queue structure.<br />
<br />
==Primary Message Queue==<br />
The Primary Message Queue is the default mail box (and can not be deleted) and provides external partners' SmartApps an area to send messages to if they do not yet support the message queue extensions. Prior to version 2.2.4, there was only one message queue; now, the user can configure multiple message queues. Most developers have committed to supporting this new structure.<br />
<br />
'''Please Note'''<br />
It is estimated before 3.0.0 the primary message queue will be deprecated. <br />
It is recommended you create your own message queues instead of using primary <br />
message queue. Current versions of '''Ask Alexa''' provide a forwarding function <br />
(see: [[Ask_Alexa_-_Message_Queues#Forward_Messages_From_Primary_Queue]]) to intercept primary message <br />
queue messages and re-directed them to another queue. This function will also deprecate, <br />
but may lag the primary message queue deprecation by a few versions.<br />
<br />
The options on this primary message queue are identical to the options you can set for the message queues you create.<br />
<br />
[[file:AAMsgQueue.png|500px]]<br />
<br />
You can choose how the messages are played back (oldest to newest, or newest to oldest) on the Alexa Connected Device. This setting is also applicable to how they are displayed on the main screen if you choose this option (see: [[Ask_Alexa_-_Message_Queues#Message_Queues_Displayed_On_Main_Menu]]). <br />
<br />
If you need real-time alerting to notifications, you have a few options. See [[Ask_Alexa_-_Message_Queues#Message_Notification_Options]] for these notification options. <br />
<br />
In each of the notification areas, you can choose to implement restrictions (global to the queue you are creating) to have times of day, presences, days of week, mode or which switches are on or off to determine if notification happens when a message arrives (the message will always be delivered to the message queue even if notifications are restricted).<br />
<br />
==Additional Message Queues==<br />
You will create new message queues similar to how new macros are created. Find the green button labeled <<Create A New Message Queue...>><br />
<br />
[[File:AANewMQ.png|250px]]<br />
<br />
As you create message queues, you will be required to enter a name for the message queue, along with different options for message playback and message notification, whether it be a light going on/off, a speaker/synth device notification, or an SMS/Push notification.<br />
<br />
'''Notice'''<br />
As mentioned a number of times, when naming your message queues, ensure your<br />
message queue names are unique not only within the context of the other queues, but <br />
within the parent app itself. That means a message queue should not share the same name <br />
with devices, aliases, modes, or routines within the parent app. Taking this precaution <br />
will eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
If you receive an error similar to this when attempting to create new message queue:<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the message queue code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
<br />
==Message Notification Options==<br />
<br />
When a message arrives within one of the message queues there are various methods you can use to either hear the message in real-time, or be alerted a message is waiting for you in the message queue.<br />
<br />
===Audio Notification===<br />
<br />
When you click the area labeled <<Message notification - Audio>> an additional set of options for output devices (speaker or synth device) will appear. When choosing this notification option, you have the choice to play the full message on the speaker, synth device or to just a notification that there is an incoming message. No matter what option you choose, your message will always be waiting on the Alexa Connected device if you simply say ''<"Alexa, tell SmartThings to play primary messages">''. If you choose to output to a speaker (like Sonos), you also have the ability to choose the voice that will be output during a message.<br />
<br />
<br />
'''Please Note'''<br />
Messages going directly to Alexa devices using TTS need to utilize applications<br />
such as Echo Speaker or Echo Speaks. Each of these allows you to choose the <br />
speakers in your accounts as SmartThings TTS devices. Please note that Echo Speaks<br />
utilizes different programming commands, so if you choose devices from this app<br />
be sure to check the "Echo Speaks" toggle when selecting the speakers.<br />
<br />
===Visual Notification===<br />
<br />
You can have a visual notification of a message in the message queue via an on/off light or colored light that turns on when there is a message waiting. Simply choose a light switch from the <<Turn On Lights When Messages Present>> or <<Turn On/Set Colored Lights When Messages Present>> selection areas. If you use a light to indicate a message is waiting, you also have an option to turn off the lights when the queue has been emptied (either by you or by a partner SmartApp).<br />
<br />
===Mobile Notification===<br />
<br />
If you want to be notified of a message on your mobile phone, you can choose the options in the <<Message notification - Mobile>> area.<br />
<br />
'''Notice'''<br />
Newer versions of the SmartThings Mobile App will allow you to set up specific <br />
contacts to push or send SMS messages to. The app automatically detects when<br />
you have the Contacts page available to you and will be the preferred method<br />
of contact when enabled.<br />
<br />
'''Also Note''' <br />
It has been advised by SmartThings to NOT excessively use the SMS functionality<br />
of the app. While it is fine for general notifications as you would do with the<br />
other aspects of SmartThings Mobile App, DO NOT use '''Ask Alexa''' as a way to text <br />
friends and family for recreation; doing so may require SmartThings to disable<br />
or limit this functionality in the future. If you need to generate excessive<br />
notification traffic, please use the push functionality.<br />
<br />
==Reminder About Amazon Developer Slots==<br />
<br />
Please remember ANY changes or additions you make to your '''Ask Alexa''' environment should immediately be followed up with running <<Settings>> <<Setup Variables>> in the main '''Ask Alexa''' SmartApp. This will allow newly created message queues to be reflected in the Amazon developer site. See [[Ask_Alexa#Setup_Variables]] for more information.<br />
<br />
==Message Delivery==<br />
Please note that while message delivery using the 'sendLocationEvent' is rather consistent, the is a non-standard way to exchange information between SmartApps...If your app sends out multiple messages per second, there is a possibility that the message may not be processed by '''Ask Alexa'''. It is recommended you meter the speed at which messages are sent to the queue while a message verification system is being developed.<br />
<br />
==Advanced: Interfacing With Ask Alexa (Developers)==<br />
Within the SmartThings environment, each SmartApp runs independently from each other. For example, '''Ask Alexa''' can not interfere with CoRE, or vis-versa. However, the drawback of this is that SmartApps can not work together in normal circumstances. However, there are ways for SmartApps to share information using the ''SmartThings location events''. This is how CoRE, for example, knows the names of the '''Ask Alexa''' Macros, or knows when a macro has run. <br />
<br />
With the implementation of the Message Queues in '''Ask Alexa''', a standard method of sending messages to '''Ask Alexa''' is required. The '''SmartThings location events''' will serve this purpose. If you are a developer of a SmartApp and wish to send messages to the '''Ask Alexa''' Message Queue you will need to conform your output to the follow standards.<br />
<br />
Currently, the following community apps [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa#Compatibility_With_Other_SmartApps] support or plan to support the message queue (items with (2.0) in them can utilize the user-created message queues).<br />
<br />
===Send Messages To Ask Alexa===<br />
There are two required steps in order to interface with '''Ask Alexa''''s message queues:<br />
<br />
* First, you must subscribe to the ''askAlexaMQ'' location event. This will feed your app a list of available message queues within '''Ask Alexa'''. The formatting of this command is simple:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
The location information you receive back will have a data field with the list of queues available. It is recommended you place these in a state variable like this:<br />
<br />
<pre style="display: inline-block;"> <br />
def askAlexaMQHandler(evt) {<br />
if (!evt) return<br />
switch (evt.value) {<br />
case "refresh":<br />
state.askAlexaMQ = evt.jsonData && evt.jsonData?.queues ? evt.jsonData.queues : []<br />
break<br />
}<br />
}<br />
</pre><br />
<br />
Please note the queues listing will be a data map with the ID and the name of the queue. <br />
<br />
* Second, with the information above, you will typically deliver an option to the end user with a list of where to send the output. You can do with with an "enum" input like this:<br />
<br />
<pre style="display: inline-block;"><br />
input "listOfMQs", "enum", title: "This is a list of the Ask Alexa Message Queues", options: state.askAlexaMQ, multiple: true, required: false<br />
</pre><br />
<br />
Then, when you are ready to trigger the output you will use a ''sendLocationEvent()'' with the follow parameters:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueue", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
descriptionText: "This is the message I am sending to Ask Alexa", <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...],<br />
overwrite: true*,<br />
expires: seconds**,<br />
notifyOnly: true*,<br />
suppressTimeDate: true*,<br />
trackDelete: true*<br />
]<br />
)<br />
<br />
*='overwrite','suppressTimeDate', 'notifyOnly' and 'trackDelete' default to 'false' if these parameters are not used<br />
**=Having no value in this field means the system will keep the message in the queue until deleted by the <br />
user or in bulk by the sending application<br />
</pre><br />
<br />
As seen here in the SmartThings documentation [http://docs.smartthings.com/en/latest/ref-docs/smartapp-ref.html?highlight=sendlocationevent], there are many parameters you can use when logging a Location Event (using ''sendLocationEvent()''). '''Ask Alexa''' uses these:<br />
{| class = "wikitable"<br />
! '''Parameter''' !! '''Information'''<br />
|-<br />
|'''name'''|| This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueue''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name that be spoken as part of the Message Queue voice message.<br />
|-<br />
|'''descriptionText''' || This is the message you wish to have Alexa play.<br />
|-<br />
|'''isStateChange''' || This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is OPTIONAL for sending message to the message queue, but REQUIRED if you ever want your app to delete messages from the queue. Setting 'unit' provides additional security by allowing sending apps to delete specific messages from the message queue, either in bulk, or by individual message. It is the responsibility of the sending app to keep track and organize their ID ('''unit''') naming structure so that other applications don't accidentally delete their messages within the queue. This can be any STRING designated by the sending app.<br />
|-<br />
|'''data''' || This field allows for future expansion. See below for the current labels/tags.<br />
|}<br />
<br />
<br />
<br />
{| class = "wikitable"<br />
|+Data field items<br />
! '''Data Label''' !! '''How used'''<br />
|-<br />
|'''queues'''|| This is a map of the message queues that should accept the messages. Please note that these will be either the message queue AppID or "Primary Message Queue". It is recommended you obtain the map from the list sent by '''Ask Alexa''' <br />
|-<br />
|'''overwrite'''|| "true" or "false" (lower case). Defaults to "false" if no value is given. This is similar to the message queue delete function (see [[Ask_Alexa#Delete_Messages_In_Message_Queue]] in that it requires the value and unit fields to be populated. In addition, the user must still enable the ability for smartapps to delete messages. This function is perfect for applications that send multiple entries (like a door opening or closing) but only the latest value is relevant.<br />
|-<br />
|'''expires'''|| This is the number of seconds from when the message is received that it will automatically remove itself from the message queue. It is recommended that you give the user the option to enter a number in minutes, then multiple this number by 60 to send '''Ask Alexa''' the number of seconds.<br />
|-<br />
|'''notifyOnly'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to only notify (based on the user's notification settings) to a message an NOT place it into the message queue. It is up to the user to ensure that notifications (Visual, Audio or Mobile) are enabled as the message will be be saved if no notification options are enabled. This option is good for real-time alerting (such as weather advisories) that are not relevant even moments after the message is sent<br />
|-<br />
|'''suppressTimeDate'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to suppress the time and date playback when listening to messages from the queue on the Alexa. Users have the option to suppress this information on a global queue basis; this option allows for the suppression to be on a per-message basis. This is useful for smartapps that embed their own time date information into the messages. For example, "The bedroom light was turned on at 4:45pm on Tuesday"...it would be a little redundant to have a header that also told the time and date.<br />
|-<br />
|'''trackDelete'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to be sent a sendLocationEvent (value = messageValue.messageUnit) when the message expires or is deleted by the user.<br />
|-<br />
|}<br />
<br />
===Receiving Message===<br />
To receive these messages, '''Ask Alexa''' subscribes to the location event like this:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "AskAlexaMsgQueue", msgHandler)<br />
</pre><br />
<br />
The message, once received, is placed into a state variable within the application. Since Alexa can not wake on alerts (see [[Ask_Alexa#Limitations]]), the alerts are kept in this variable until the user initiates a command using '''Ask Alexa'''. When the action requested is completed, the user is alerted to the pending message(s), giving them the option to play the messages.<br />
<br />
At this time, there is no scheduling function for these notes. In other words, the sending app is responsible for delivering messages to '''Ask Alexa''', and the date stamp is dependent on the order in which they are received. The user has the option to play oldest first, or newest first (default it oldest first).<br />
<br />
'''Please Note'''<br />
In a multi-room setup (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]]), the messages<br />
will still go to each instance of the app you have set up. This will change as '''Ask Alexa''' <br />
is further developed and Amazon opens up the 'push' notification function.<br />
<br />
===Delete Messages In Message Queue===<br />
The message queue is very flexible in how it can be used; however, with anything voice related it is always important to balance between information relevance and quantity. For example, if you have an app that alerts (sends messages to the queue) of a non-critical nature (maybe some sort of information only message), it may not be important for the user to hear all of the messages if the original alert/notification has subsequently cleared. As such, using both the '''value''' and '''unit''' parameters, a developer can issue a ''sendLocationEvent()'' that will allow an external app to selectively delete messages that may have sent to the '''Ask Alexa''' queue previously. For this option to work, the end user must enable the queue to allow for deletions (see [[Ask_Alexa#External_SmartApps_Delete_Message_Queues]])<br />
<br />
'''Please Note:'''<br />
You must use send the '''unit''' and '''value''' parameter when sending the original message<br />
to successfully delete messages from the message queue. This is to prevent <br />
one app from deleting another app's messages when the same application name ('''value''') is used. <br />
You will be UNABLE to delete any message from the queue if the '''unit''' parameter is missing. <br />
As such, your '''unit''' parameter should be unique. Depending on your needs, this '''unit''' <br />
parameter can be unique to every messages (allowing individual messages to be deleted), or the <br />
same for every message and the sending app, allowing ALL messages with that unique identifier <br />
to be deleted in bulk. <br />
<br />
To issue a delete command to the message queue, use the following parameters:<br />
{| class = "wikitable"<br />
|'''name''' || This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueueDelete''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name. This '''value''' must match the original message(s) that you are attempting to delete.<br />
|-<br />
|'''isStateChange'''|| This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is REQUIRED for a delete. This is a string value and MUST match the message(s) you want to delete. As mentioned above, to delete messages in bulk, simply use a '''unit''' parameter that is linked to the '''value''' parameter. Or, individual messages can be selectively deleted by having the '''unit''' parameter unique to each message sent from the app. <br />
|-<br />
|'''data''' || This field allows for future expansion. Currently, it is used to send a map of message queues IDs/Labels to partner applications.<br />
|}<br />
<br />
Putting this together, the syntax within your SmartApp would look like this:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueueDelete", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...]<br />
]<br />
)<br />
</pre><br />
<br />
Currently, there are no "wildcard" searches for the '''unit''' parameter. To delete multiple messages, separate ''sendLocationEvent()'' commands should be sent for every unique '''unit''' parameter.<br />
<br />
===Refresh Message Queue List===<br />
<br />
For developers that may want to install and app and immediately refresh the list of message queues available (instead of going out of the newly installed app and then going into Ask Alexa, then back into the the app, you can call the following command:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMQRefresh", <br />
isStateChange: true <br />
)<br />
</pre><br />
<br />
The list will be rebroadcast as mentioned above using the "askAlexaMQ.refresh" event value.<br />
<br />
===Track Deletion Of Messages===<br />
If your app needs to know if a message you sent has been deleted, you must first tag you message. You do this in the "data" field by setting the "trackDelete" to "true" (see [[Ask_Alexa_-_Message_Queues#Send_Messages_To_Ask_Alexa]])<br />
<br />
Next, you app should already be subscribed to the "askAlexaMQ" location event:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
At the method "askAlexaMQHandler(evt)", you will look for the evt.value of the your original message's app name (value) and message id (unit) combined with a period between them.<br />
<br />
For example, if your a is "MyApp" and your message id is 1234, you will look for this combination<br />
<br />
<pre style="display: inline-block;"><br />
def askAlexaMQHandler(evt){<br />
if (evt.value == "MyApp.1234") {<br />
<Event to occur when your message is deleted><br />
}<br />
}<br />
</pre><br />
<br />
If you need to know if the deletion of the message was a clearing of the queue (user invoked), an app deletion (usually through an overwrite or when your app deletes a message), or through expiration of a message, the data field delivered with the askAlexMQ event will include the following JSON fields:<br />
<br />
* '''deleteType:''' "delete", "delete all" or "expire"<br />
* '''queues:''' The message queue name where the message was removed from</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=Ask_Alexa_-_Message_Queues&diff=13763Ask Alexa - Message Queues2018-11-22T23:16:49Z<p>MichaelStruck: /* NotifyMe Skill (Alexa Notification) */</p>
<hr />
<div>[[Category:Unpublished SmartApps]]<br />
The Message Queues are an extension to ''Ask Alexa'', the popular SmartThings Add in. You must be running '''Ask Alexa''' to use Message Queue. More information about '''Ask Alexa''' can be found here: [[Ask Alexa]]<br />
<br />
The message queues are a holding area for external messages that may come in from other SmartApps. Unfortunately, Alexa Enabled Devices can't wake with anything other than voice (or button push) yet, so alerting in real time using these devices is impossible. However, the message queue can hold these alerts or message and they can be played back (i.e. ''<"Alexa, tell SmartThings to play {message queue name} Messages">''). If you DO need real time notifications, you also have the option of sending the notification to an external speaker or synth device.<br />
<br />
==Summary==<br />
[[File:Mailbox.png]]<br />
<br />
'''Category:''' Ask Alexa Extension - Requires [[Ask Alexa]]<br />
<br />
'''Author''':Michael Struck''' --[[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 00:01, 1 January 2016 (EST)<br />
<br />
'''ST Community handle''': https://community.smartthings.com/users/michaels/activity<br />
<br />
===Latest Version===<br />
{| class="wikitable"<br />
|+The latest version this extension (as of 3/16/18)<br />
|-<br />
! '''Ask Alexa Extensions''' !! Area Used !! '''Version''' !! '''Location'''<br />
|-<br />
| '''Message Queue Code'''|| SmartThings IDE || ''1.0.8'' || https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy <br />
|}<br />
<br />
===Ask Alexa Extension Code Installation===<br />
<br />
To install the extension use the code located here:<br />
<br />
https://github.com/MichaelStruck/SmartThingsPublic/blob/master/smartapps/michaelstruck/ask-alexa-message-queue.src/ask-alexa-message-queue.groovy<br />
<br />
The steps for installation of the extensions are almost exactly the same as [[Ask_Alexa#Ask_Alexa_Code_Installation]]:<br />
*Copy the raw code from the GitHub link above<br />
*Go to the SmartThings IDE page and log in<br />
*Click the '''My SmartApps''' link<br />
*Click the '''+New SmartApp''' link<br />
*Click the '''From Code''' tab<br />
*Paste the GitHub code in the open area<br />
*Click '''Create''' from the bottom left corner<br />
*'''Save''' the code using the button in the upper right-hand corner of the page<br />
*There is no need to do any OAuth settings on extension code.<br />
<br />
'''Please Note:'''<br />
You DO NOT need to publish the extension code; however, there is no harm in doing so. <br />
Simply be aware that if you publish it the extension will show up in the <br />
SmartThings Marketplace. However, you should NOT install it from there...<br />
'''Ask Alexa''' will utilize this child code from the main (parent) application.<br />
<br />
==Message Queue Options==<br />
These options will enable you to configure the '''Ask Alexa''' Message Queue. These options are global to all message queues. In other words, these settings apply to all message queues (primary and the ones you create).<br />
<br />
[[File:AAMQOptions.png|250px]]<br />
<br />
===Message Queues Displayed On Main Menu===<br />
Since messages that in the queue may be important (locks unlocked, water present), you have the ability to turn on a notification on the '''Ask Alexa''' main menu allowing you to know when messages are present and are able to view the messages without being near the Alexa device. You can also delete these messages from your message queue using the user interface.<br />
<br />
[[file:MQMain.png|250px]]<br />
<br />
===External SmartApps Delete Message Queues===<br />
Depending on the SmartApp, there may be a need to delete message from the queue (i.e. expired messages, updates to messages, etc). Enabling the <<Allow External SmartApps To Delete Message From These Queues>> option will allow those SmartApps to delete messages from the queue. Please refer to the instructions of the sending SmartApp (see: [[Ask_Alexa_-_Message_Queues#Delete_Messages_In_Message_Queue]]) to determine if you need this option enabled.<br />
<br />
===Append Alexa Output With Message Notification===<br />
When you choose Message Queues in the <<Append Alexa Output With Message Notification From These Queues>> area, a message will be appended to the Alexa output every time you use the device. For example, the conversation flow with your Alexa might be like this:<br />
<br />
'''You:''' ''"Alexa, tell SmartThings to turn off Kitchen"''<br />
'''Alexa:''' ''"I have turned off the kitchen. Please note: You have messages present in<br />
the following message queues: Primary Message Queue and John's room"''<br />
<br />
If you choose not to append your messages with these notifications, you may still query the Alexa connected device to find out if you have messages. The syntax is simply ''<"Alexa, Ask SmartThings about {message queue name}">'' You many alse delete the messages using the syntax (''<"Alexa, tell SmartThings to erase {message queue name} Messages">'' or ''<"Alexa, tell SmartThings to delete the {message queue name} Messages">'' ).<br />
<br />
===Forward Messages From Primary Queue===<br />
To support legacy applications that do not yet support the message queue extensions, the <<Forward Messages From Primary Message Queue To>> option will give you a selection of message queues to forward messages to. This setting is universal; all messages received by the primary message queue will be forwarded to queue you choose regardless of their source. When you view your message queue on the main menu, or when you play the messages from your Alexa Connected Device, the message will be appended with a note that it was forwarded from the primary message queue.<br />
<br />
This option will eventually be deprecated as partner developers migrate to the newest message queue structure.<br />
<br />
==Primary Message Queue==<br />
The Primary Message Queue is the default mail box (and can not be deleted) and provides external partners' SmartApps an area to send messages to if they do not yet support the message queue extensions. Prior to version 2.2.4, there was only one message queue; now, the user can configure multiple message queues. Most developers have committed to supporting this new structure.<br />
<br />
'''Please Note'''<br />
It is estimated before 3.0.0 the primary message queue will be deprecated. <br />
It is recommended you create your own message queues instead of using primary <br />
message queue. Current versions of '''Ask Alexa''' provide a forwarding function <br />
(see: [[Ask_Alexa_-_Message_Queues#Forward_Messages_From_Primary_Queue]]) to intercept primary message <br />
queue messages and re-directed them to another queue. This function will also deprecate, <br />
but may lag the primary message queue deprecation by a few versions.<br />
<br />
The options on this primary message queue are identical to the options you can set for the message queues you create.<br />
<br />
[[file:AAMsgQueue.png|500px]]<br />
<br />
You can choose how the messages are played back (oldest to newest, or newest to oldest) on the Alexa Connected Device. This setting is also applicable to how they are displayed on the main screen if you choose this option (see: [[Ask_Alexa_-_Message_Queues#Message_Queues_Displayed_On_Main_Menu]]). <br />
<br />
If you need real-time alerting to notifications, you have a few options. See [[Ask_Alexa_-_Message_Queues#Message_Notification_Options]] for these notification options. <br />
<br />
In each of the notification areas, you can choose to implement restrictions (global to the queue you are creating) to have times of day, presences, days of week, mode or which switches are on or off to determine if notification happens when a message arrives (the message will always be delivered to the message queue even if notifications are restricted).<br />
<br />
==Additional Message Queues==<br />
You will create new message queues similar to how new macros are created. Find the green button labeled <<Create A New Message Queue...>><br />
<br />
[[File:AANewMQ.png|250px]]<br />
<br />
As you create message queues, you will be required to enter a name for the message queue, along with different options for message playback and message notification, whether it be a light going on/off, a speaker/synth device notification, or an SMS/Push notification.<br />
<br />
'''Notice'''<br />
As mentioned a number of times, when naming your message queues, ensure your<br />
message queue names are unique not only within the context of the other queues, but <br />
within the parent app itself. That means a message queue should not share the same name <br />
with devices, aliases, modes, or routines within the parent app. Taking this precaution <br />
will eliminate confusion when addressing the Alexa Enabled Devices with commands.<br />
<br />
If you receive an error similar to this when attempting to create new message queue:<br />
<br />
[[File:AAMQError.png|250px]]<br />
<br />
This indicates you have not put the message queue code into your SmartThings IDE. Please follow the direction here [[Ask_Alexa#Ask_Alexa_Extension_Code_Installation]] to resolve this issue.<br />
<br />
==Message Notification Options==<br />
<br />
When a message arrives within one of the message queues there are various methods you can use to either hear the message in real-time, or be alerted a message is waiting for you in the message queue.<br />
<br />
===Audio Notification===<br />
<br />
When you click the area labeled <<Message notification - Audio>> an additional set of options for output devices (speaker or synth device) will appear. When choosing this notification option, you have the choice to play the full message on the speaker, synth device or to just a notification that there is an incoming message. No matter what option you choose, your message will always be waiting on the Alexa Connected device if you simply say ''<"Alexa, tell SmartThings to play primary messages">''. If you choose to output to a speaker (like Sonos), you also have the ability to choose the voice that will be output during a message.<br />
<br />
===Visual Notification===<br />
<br />
You can have a visual notification of a message in the message queue via an on/off light or colored light that turns on when there is a message waiting. Simply choose a light switch from the <<Turn On Lights When Messages Present>> or <<Turn On/Set Colored Lights When Messages Present>> selection areas. If you use a light to indicate a message is waiting, you also have an option to turn off the lights when the queue has been emptied (either by you or by a partner SmartApp).<br />
<br />
===Mobile Notification===<br />
<br />
If you want to be notified of a message on your mobile phone, you can choose the options in the <<Message notification - Mobile>> area.<br />
<br />
'''Notice'''<br />
Newer versions of the SmartThings Mobile App will allow you to set up specific <br />
contacts to push or send SMS messages to. The app automatically detects when<br />
you have the Contacts page available to you and will be the preferred method<br />
of contact when enabled.<br />
<br />
'''Also Note''' <br />
It has been advised by SmartThings to NOT excessively use the SMS functionality<br />
of the app. While it is fine for general notifications as you would do with the<br />
other aspects of SmartThings Mobile App, DO NOT use '''Ask Alexa''' as a way to text <br />
friends and family for recreation; doing so may require SmartThings to disable<br />
or limit this functionality in the future. If you need to generate excessive<br />
notification traffic, please use the push functionality.<br />
<br />
==Reminder About Amazon Developer Slots==<br />
<br />
Please remember ANY changes or additions you make to your '''Ask Alexa''' environment should immediately be followed up with running <<Settings>> <<Setup Variables>> in the main '''Ask Alexa''' SmartApp. This will allow newly created message queues to be reflected in the Amazon developer site. See [[Ask_Alexa#Setup_Variables]] for more information.<br />
<br />
==Message Delivery==<br />
Please note that while message delivery using the 'sendLocationEvent' is rather consistent, the is a non-standard way to exchange information between SmartApps...If your app sends out multiple messages per second, there is a possibility that the message may not be processed by '''Ask Alexa'''. It is recommended you meter the speed at which messages are sent to the queue while a message verification system is being developed.<br />
<br />
==Advanced: Interfacing With Ask Alexa (Developers)==<br />
Within the SmartThings environment, each SmartApp runs independently from each other. For example, '''Ask Alexa''' can not interfere with CoRE, or vis-versa. However, the drawback of this is that SmartApps can not work together in normal circumstances. However, there are ways for SmartApps to share information using the ''SmartThings location events''. This is how CoRE, for example, knows the names of the '''Ask Alexa''' Macros, or knows when a macro has run. <br />
<br />
With the implementation of the Message Queues in '''Ask Alexa''', a standard method of sending messages to '''Ask Alexa''' is required. The '''SmartThings location events''' will serve this purpose. If you are a developer of a SmartApp and wish to send messages to the '''Ask Alexa''' Message Queue you will need to conform your output to the follow standards.<br />
<br />
Currently, the following community apps [http://thingsthataresmart.wiki/index.php?title=Ask_Alexa#Compatibility_With_Other_SmartApps] support or plan to support the message queue (items with (2.0) in them can utilize the user-created message queues).<br />
<br />
===Send Messages To Ask Alexa===<br />
There are two required steps in order to interface with '''Ask Alexa''''s message queues:<br />
<br />
* First, you must subscribe to the ''askAlexaMQ'' location event. This will feed your app a list of available message queues within '''Ask Alexa'''. The formatting of this command is simple:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
The location information you receive back will have a data field with the list of queues available. It is recommended you place these in a state variable like this:<br />
<br />
<pre style="display: inline-block;"> <br />
def askAlexaMQHandler(evt) {<br />
if (!evt) return<br />
switch (evt.value) {<br />
case "refresh":<br />
state.askAlexaMQ = evt.jsonData && evt.jsonData?.queues ? evt.jsonData.queues : []<br />
break<br />
}<br />
}<br />
</pre><br />
<br />
Please note the queues listing will be a data map with the ID and the name of the queue. <br />
<br />
* Second, with the information above, you will typically deliver an option to the end user with a list of where to send the output. You can do with with an "enum" input like this:<br />
<br />
<pre style="display: inline-block;"><br />
input "listOfMQs", "enum", title: "This is a list of the Ask Alexa Message Queues", options: state.askAlexaMQ, multiple: true, required: false<br />
</pre><br />
<br />
Then, when you are ready to trigger the output you will use a ''sendLocationEvent()'' with the follow parameters:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueue", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
descriptionText: "This is the message I am sending to Ask Alexa", <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...],<br />
overwrite: true*,<br />
expires: seconds**,<br />
notifyOnly: true*,<br />
suppressTimeDate: true*,<br />
trackDelete: true*<br />
]<br />
)<br />
<br />
*='overwrite','suppressTimeDate', 'notifyOnly' and 'trackDelete' default to 'false' if these parameters are not used<br />
**=Having no value in this field means the system will keep the message in the queue until deleted by the <br />
user or in bulk by the sending application<br />
</pre><br />
<br />
As seen here in the SmartThings documentation [http://docs.smartthings.com/en/latest/ref-docs/smartapp-ref.html?highlight=sendlocationevent], there are many parameters you can use when logging a Location Event (using ''sendLocationEvent()''). '''Ask Alexa''' uses these:<br />
{| class = "wikitable"<br />
! '''Parameter''' !! '''Information'''<br />
|-<br />
|'''name'''|| This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueue''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name that be spoken as part of the Message Queue voice message.<br />
|-<br />
|'''descriptionText''' || This is the message you wish to have Alexa play.<br />
|-<br />
|'''isStateChange''' || This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is OPTIONAL for sending message to the message queue, but REQUIRED if you ever want your app to delete messages from the queue. Setting 'unit' provides additional security by allowing sending apps to delete specific messages from the message queue, either in bulk, or by individual message. It is the responsibility of the sending app to keep track and organize their ID ('''unit''') naming structure so that other applications don't accidentally delete their messages within the queue. This can be any STRING designated by the sending app.<br />
|-<br />
|'''data''' || This field allows for future expansion. See below for the current labels/tags.<br />
|}<br />
<br />
<br />
<br />
{| class = "wikitable"<br />
|+Data field items<br />
! '''Data Label''' !! '''How used'''<br />
|-<br />
|'''queues'''|| This is a map of the message queues that should accept the messages. Please note that these will be either the message queue AppID or "Primary Message Queue". It is recommended you obtain the map from the list sent by '''Ask Alexa''' <br />
|-<br />
|'''overwrite'''|| "true" or "false" (lower case). Defaults to "false" if no value is given. This is similar to the message queue delete function (see [[Ask_Alexa#Delete_Messages_In_Message_Queue]] in that it requires the value and unit fields to be populated. In addition, the user must still enable the ability for smartapps to delete messages. This function is perfect for applications that send multiple entries (like a door opening or closing) but only the latest value is relevant.<br />
|-<br />
|'''expires'''|| This is the number of seconds from when the message is received that it will automatically remove itself from the message queue. It is recommended that you give the user the option to enter a number in minutes, then multiple this number by 60 to send '''Ask Alexa''' the number of seconds.<br />
|-<br />
|'''notifyOnly'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to only notify (based on the user's notification settings) to a message an NOT place it into the message queue. It is up to the user to ensure that notifications (Visual, Audio or Mobile) are enabled as the message will be be saved if no notification options are enabled. This option is good for real-time alerting (such as weather advisories) that are not relevant even moments after the message is sent<br />
|-<br />
|'''suppressTimeDate'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to suppress the time and date playback when listening to messages from the queue on the Alexa. Users have the option to suppress this information on a global queue basis; this option allows for the suppression to be on a per-message basis. This is useful for smartapps that embed their own time date information into the messages. For example, "The bedroom light was turned on at 4:45pm on Tuesday"...it would be a little redundant to have a header that also told the time and date.<br />
|-<br />
|'''trackDelete'''||"true" or "false" (lower case). Defaults to "false" if no value is given. This value will allow applications to be sent a sendLocationEvent (value = messageValue.messageUnit) when the message expires or is deleted by the user.<br />
|-<br />
|}<br />
<br />
===Receiving Message===<br />
To receive these messages, '''Ask Alexa''' subscribes to the location event like this:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "AskAlexaMsgQueue", msgHandler)<br />
</pre><br />
<br />
The message, once received, is placed into a state variable within the application. Since Alexa can not wake on alerts (see [[Ask_Alexa#Limitations]]), the alerts are kept in this variable until the user initiates a command using '''Ask Alexa'''. When the action requested is completed, the user is alerted to the pending message(s), giving them the option to play the messages.<br />
<br />
At this time, there is no scheduling function for these notes. In other words, the sending app is responsible for delivering messages to '''Ask Alexa''', and the date stamp is dependent on the order in which they are received. The user has the option to play oldest first, or newest first (default it oldest first).<br />
<br />
'''Please Note'''<br />
In a multi-room setup (see [[Ask_Alexa#Multi-Room_Controls_.28Advanced.29]]), the messages<br />
will still go to each instance of the app you have set up. This will change as '''Ask Alexa''' <br />
is further developed and Amazon opens up the 'push' notification function.<br />
<br />
===Delete Messages In Message Queue===<br />
The message queue is very flexible in how it can be used; however, with anything voice related it is always important to balance between information relevance and quantity. For example, if you have an app that alerts (sends messages to the queue) of a non-critical nature (maybe some sort of information only message), it may not be important for the user to hear all of the messages if the original alert/notification has subsequently cleared. As such, using both the '''value''' and '''unit''' parameters, a developer can issue a ''sendLocationEvent()'' that will allow an external app to selectively delete messages that may have sent to the '''Ask Alexa''' queue previously. For this option to work, the end user must enable the queue to allow for deletions (see [[Ask_Alexa#External_SmartApps_Delete_Message_Queues]])<br />
<br />
'''Please Note:'''<br />
You must use send the '''unit''' and '''value''' parameter when sending the original message<br />
to successfully delete messages from the message queue. This is to prevent <br />
one app from deleting another app's messages when the same application name ('''value''') is used. <br />
You will be UNABLE to delete any message from the queue if the '''unit''' parameter is missing. <br />
As such, your '''unit''' parameter should be unique. Depending on your needs, this '''unit''' <br />
parameter can be unique to every messages (allowing individual messages to be deleted), or the <br />
same for every message and the sending app, allowing ALL messages with that unique identifier <br />
to be deleted in bulk. <br />
<br />
To issue a delete command to the message queue, use the following parameters:<br />
{| class = "wikitable"<br />
|'''name''' || This is the key that '''Ask Alexa''' subscribes to. This MUST be ''AskAlexaMsgQueueDelete''<br />
|-<br />
|'''value''' || This is the (sending SmartApp) name. This '''value''' must match the original message(s) that you are attempting to delete.<br />
|-<br />
|'''isStateChange'''|| This must be set to TRUE<br />
|-<br />
|'''unit''' || This parameter is REQUIRED for a delete. This is a string value and MUST match the message(s) you want to delete. As mentioned above, to delete messages in bulk, simply use a '''unit''' parameter that is linked to the '''value''' parameter. Or, individual messages can be selectively deleted by having the '''unit''' parameter unique to each message sent from the app. <br />
|-<br />
|'''data''' || This field allows for future expansion. Currently, it is used to send a map of message queues IDs/Labels to partner applications.<br />
|}<br />
<br />
Putting this together, the syntax within your SmartApp would look like this:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMsgQueueDelete", <br />
value: "MySmartApp", <br />
isStateChange: true, <br />
unit: "######", <br />
data:[<br />
queues:[ID1,ID2...]<br />
]<br />
)<br />
</pre><br />
<br />
Currently, there are no "wildcard" searches for the '''unit''' parameter. To delete multiple messages, separate ''sendLocationEvent()'' commands should be sent for every unique '''unit''' parameter.<br />
<br />
===Refresh Message Queue List===<br />
<br />
For developers that may want to install and app and immediately refresh the list of message queues available (instead of going out of the newly installed app and then going into Ask Alexa, then back into the the app, you can call the following command:<br />
<br />
<pre style="display: inline-block;"><br />
sendLocationEvent(<br />
name: "AskAlexaMQRefresh", <br />
isStateChange: true <br />
)<br />
</pre><br />
<br />
The list will be rebroadcast as mentioned above using the "askAlexaMQ.refresh" event value.<br />
<br />
===Track Deletion Of Messages===<br />
If your app needs to know if a message you sent has been deleted, you must first tag you message. You do this in the "data" field by setting the "trackDelete" to "true" (see [[Ask_Alexa_-_Message_Queues#Send_Messages_To_Ask_Alexa]])<br />
<br />
Next, you app should already be subscribed to the "askAlexaMQ" location event:<br />
<br />
<pre style="display: inline-block;"><br />
subscribe(location, "askAlexaMQ", askAlexaMQHandler)<br />
</pre><br />
<br />
At the method "askAlexaMQHandler(evt)", you will look for the evt.value of the your original message's app name (value) and message id (unit) combined with a period between them.<br />
<br />
For example, if your a is "MyApp" and your message id is 1234, you will look for this combination<br />
<br />
<pre style="display: inline-block;"><br />
def askAlexaMQHandler(evt){<br />
if (evt.value == "MyApp.1234") {<br />
<Event to occur when your message is deleted><br />
}<br />
}<br />
</pre><br />
<br />
If you need to know if the deletion of the message was a clearing of the queue (user invoked), an app deletion (usually through an overwrite or when your app deletes a message), or through expiration of a message, the data field delivered with the askAlexMQ event will include the following JSON fields:<br />
<br />
* '''deleteType:''' "delete", "delete all" or "expire"<br />
* '''queues:''' The message queue name where the message was removed from</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Dimmer_Switch&diff=13762GE Z-Wave Motion Sensor Dimmer Switch2018-11-22T19:29:51Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Dimmer Switch is combination dimmer switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionDimmerDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26933)<br />
<br />
'''Capabilities:''' Motion Sensor, Dimmer Switch<br />
<br />
'''Type:''' In-wall mounted dimmer switch with motion sensor capabilities<br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 11/22/18):<br />
'''GE Z-Wave Motion Sensor Dimmer Switch DTH:''' <br />
Version: 1.0.4a<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Dimmer Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Dimmer Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Dimmer Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Dimmers as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Dimmer Switch:''' devicetypes/michaelstruck/ge-motion-dimmer-switch-26933.src/ge-motion-dimmer-switch-26933.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH, you can access some of the advanced settings for the DTH. (See H on the interface here: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Interface]]) <br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option Name''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating''' || This allows you to set the operating mode to one of the 3 modes listed below: <br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal dimmer switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current mode <br />
|| Y<br />
|-<br />
| '''Timeout Duration'''|| This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || Y <br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command twice). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light) then waiting 1 second, press the on button again, wait one second, then press the on button a final time will do just fine. || N <br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above || Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high || Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N <br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Z-Wave Dimmer Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with either a Z-Wave (programmic) command. The default if is 1% every 30 milliseconds. So the switch will go to 100% in 3 second (3000 milliseconds) || N<br />
|-<br />
| '''Slow Dim Rate''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with the press of the physical button. The default (when this setting is off) is "Quickly", taking about 1 second to go to 100%. Enabling this 'Slow' option will have the light taking around 3 seconds to reach level || N<br />
|-<br />
| '''Manual Ramp Rate Settings''' || These settings allow you to control the 'ramp rate' (the amount of change over time) with a 'press and hold' of the physical buttons. The default is 1% every 30 milliseconds. With these default settings the switch will go to 100% in 3 second (3000 milliseconds). Please note that this is the ramp rate used when the operating mode is set to 'Occupancy' and the light goes on with motion || N<br />
|-<br />
| '''Default Dim Level''' || For a single tap of the 'on' button, this allows you to define what level the dimmer goes to by default. A setting of '0' will use the previous level. Any value above 0 will be the percent the dimmer goes to when the button is pressed || Y<br />
|-<br />
| '''Enable Switch Mode'''|| This essentially turns the dimmer into an on/off switch. Pressing the top button will force the light to 100%, the bottom button will turn off the light. Dimming action will not occur. The speed at which the light turns on and off will be very quick (like a switch) and overrides the '''Default Dim Level''', '''Z-Wave Dimmer Ramp Rate Settings''' and '''Manual Ramp Rate Settings''' || Y<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
| '''setLevel Command Mode'''|| Normally, if a dimmer switch receives a 'setLevel' command, the light turns on and sets to this level. This is default behavior with most SmartThings dimmers, along with this one. However, this setting can be overridden, however, allowing you to set the level of the dimmer without turning it on. Some automations may need this setting to get desired results. However, please note that depending on your settings, you may not get the desired results if you have the '''Default Dim Level''' set || N <br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionDimmerDTHCGUI.png|300px]]<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Dimmer Indicator/Control''' || This is both an indicator of the dimmer level and a control. Tapping this icon will bring up a vertical slider that will allow you to set the dimmer level of the switch<br />
|-<br />
| '''D''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''E''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''F''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''G''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''H''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off/Light Level===<br />
Just like an ordinary dimmer, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
device.setLevel(value)<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode.<br />
<br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically.<br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Default Level===<br />
This command is exclusive to the GE Z-Wave Motion Sensor Dimmer Switch and it allows you to programmatically define the level of the switch when it turns on. This is useful to 'reset' the switch to a default level when it is turned off in case it was set lower the last time it was used. If you change this to number and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setDefaultLevel(value)<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionDimmerSync.png|250px]]<br />
<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
===Switch Mode===<br />
<br />
These commands allow you to control how the dimmer operates. You can turn the dimmer in to an on/off switch that will go from 0 to 100 and back to 0, with dimming capabilities disabled. This is useful when setting up a room where the normal operation (for example, during the day) is simply on or off. But at night, you can have it change to a dimmer (possibly using the default dim level ([[GE_Z-Wave_Motion_Sensor_Dimmer_Switch#Default_Level]]) for less harsh lighting in certain situations. <br />
<br />
<pre style="display: inline-block;"><br />
switchModeOn()<br />
switchModeOff()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruckhttps://thingsthataresmart.wiki/index.php?title=GE_Z-Wave_Motion_Sensor_Switch&diff=13761GE Z-Wave Motion Sensor Switch2018-11-22T19:29:05Z<p>MichaelStruck: /* DTH Specific Options */</p>
<hr />
<div>The GE Z-Wave Motion Sensor Switch is combination on/off switch and motion detector that when configured with the proper SmartThings device type handler (DTH) can locally control a light when there is movement in the room. This document outlines the installation and usage of this custom DTH. In addition, this DTH allows for you to directly control other Z-Wave switches within your SmartThings environment, allowing you to have a bit of automation without the need to program. <br />
<br />
[[File:GEMotionSwitchDTH.png|300px]]<br />
<br />
==Summary==<br />
<br />
'''Product:''' GE Z-Wave Motion Sensor Switch (Model 26931)<br />
<br />
'''Capabilities:''' Motion Sensor, on/off Switch<br />
<br />
'''Type:''' In-wall mounted on/off switch with motion sensor capabilities <br />
<br />
'''Protocol:''' Z-wave Plus<br />
<br />
'''Device Type Author:''' [[User:MichaelStruck|MichaelStruck]] ([[User talk:MichaelStruck|talk]]) 17:02, 3 January 2016 (EST) with code originally from @mlebaugh<br />
<br />
'''ST Community Handle:''' https://community.smartthings.com/users/michaels/activity<br />
<br />
'''Contributions:''' @Darwin (Motion Sensitivity Settings, programming interface, double press, testing)<br />
<br />
===Latest Version===<br />
The latest version of the device code is as follows (as of 11/22/18):<br />
'''GE Z-Wave Motion Sensor Switch DTH:''' <br />
Version: 1.0.4a<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
===Open Source License/Trademarks===<br />
Licensed under the Apache License, Version 2.0 (the "License"); you may not use the '''GE Z-Wave Motion Sensor Switch DTH''' code except in compliance with the License. You may obtain a copy of the License at:<br />
<br />
::http://www.apache.org/licenses/LICENSE-2.0<br />
<br />
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.<br />
<br />
All product and company names are trademarks™ or registered® trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.<br />
<br />
==Installation==<br />
<br />
First, copy the code from the following GitHub location: <br />
<br />
https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
Click the '''Raw''' link, and then select all of the code (CTRL+A), and then copy it (CTRL+C) to your computer’s clipboard.<br />
Then go to the SmartThings IDE at http://ide.smartthings.com. Log into the site and proceed to the link at the top labeled '''My Device Types'''. Click on this link.<br />
<br />
[[File:MyDeviceTypes.png|700px]]<br />
<br />
This will present you with a list of custom device types that you may have within your account. If you do not yet have the GE Z-Wave Motion Sensor Switch listed, click the link '''+New Device Type''' in the upper right-hand corner of the screen.<br />
<br />
[[File:+newDevice.png|700px]]<br />
<br />
There will be three tabs at the top, which represent the different ways to add a device. Choose '''From Code''' and you will be presented an empty area where the code you copied earlier can be placed. In the open area in the middle paste (CTRL+V) this code.<br />
<br />
From here, simply '''Save''' and '''Publish''' this code.<br />
<br />
[[File:DeviceSavePublish.png|700px]]<br />
<br />
'''Notice'''<br />
The code for the GE Z-Wave Motion Sensor Switch only needs to be installed in this manner once; <br />
you can add multiple Z-Wave Motion Sensor Switches as long as this code is in place.<br />
<br />
You can now go through the normal process of adding devices to SmartThings. <br />
<br />
===Advanced Installation===<br />
<br />
For advanced users who have their SmartThings IDE integrated with GitHub, the installation and maintaining of code becomes very simple. This manual will not go into detail about setting up your IDE with GitHub; those instructions can be found here: http://docs.smartthings.com/en/latest/tools-and-ide/github-integration.html?highlight=git<br />
<br />
Once you have integration, the code you might need will be available to you to download and keep in sync with the latest versions. <br />
* First, find the '''Settings''' button at the top of your SmartThings IDE page under '''My SmartApps''' or '''My Device Handlers'''(this button will only appear after you integrate with GitHub). For the virtual dimmer, you should be under the '''My Device Handlers''' section<br />
<br />
[[File:IdeSettings.jpg]]<br />
<br />
* Clicking this button will open the GitHub Repository Integration page. To find the '''GE Z-Wave Motion Sensor Dimmer Switch''' code, enter the information as you see it below:<br />
<br />
'''Owner:''' MichaelStruck<br />
<br />
'''Name:''' SmartThingsPublic<br />
<br />
[[File:GitHubIntegration.jpg]]<br />
<br />
* Close the GitHub Repository Integration page<br />
*Next, click the '''Update from Repo''' button at the upper-right corner of the IDE<br />
*On the right-hand column, scroll down to click the apps you want to install. This will typically be:<br />
<br />
'''GE Z-Wave Motion Sensor Switch:''' devicetypes/michaelstruck/ge-motion-switch-26931.src/ge-motion-switch-26931.groovy<br />
<br />
* Click the '''Execute Update''' in the bottom-right corner of the screen. When done syncing, the new device handler should now appear in your IDE. If they ever change color, that indicates a new version is available.<br />
<br />
==Settings==<br />
Using the 'gear' in the upper right corner of the DTH (See Item "F" on [[GE_Z-Wave_Motion_Sensor_Switch#Interface]]), you can access some of the advanced settings for the DTH.<br />
<br />
===General SmartThings Options===<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes'''<br />
|-<br />
| '''Name''' || This is the name of the switch that will be seen by other applications and SmartThings.<br />
|-<br />
| '''Icon''' || This is the icon associated with the switch and will be seen throughout the SmartThings app<br />
|-<br />
|}<br />
<br />
===DTH Specific Options===<br />
<br />
'''Please Note'''<br />
The settings marked as 'Default' will be applied to the switch regardless<br />
of whether you have set them within the '''Settings''' area. The only item<br />
this does NOT apply to is the Operating Mode. If this is left blank in the <br />
'''Settings''' the value will NOT be changed from what it was previously (be <br />
it Manual, Vacant or Occupied.<br />
<br />
Also note that tapping 'SAVE' on the '''Settings''' page will overwrite <br />
all settings that may have been set, including any settings that<br />
have been set programmatically. The dashboard on the main interface<br />
will show you which settings differ from the '''Settings''' page.<br />
<br />
{| class="wikitable"<br />
|-<br />
! '''Option''' !! '''Settings/Notes''' !! Programming Access<br />
|-<br />
| '''Operating Mode''' || This allows you to set the operating mode to one of the 3 modes listed below:<br />
<br />
* '''Occupancy''' - Used in conjunction with the settings below, the light will turn on when motion is sensed and off when the motion stops<br />
* '''Vacancy''' - Similar to Occupancy, except the light will not automatically come on with motion. However, it will turn off after motion has subsided<br />
* '''Manual''' - This disables the automation within the dimmer switch, allowing it to behave just like a normal switch. Please note the motion sensor can still be used with other SmartThings' applications even in 'Manual' mode (as long as the motion sensor setting below is enabled)<br />
<br />
As mentioned above, leaving this area blank in the '''Settings''' area will retain the current operating mode<br />
|| Y<br />
|-<br />
| '''Timeout Duration''' || This is utilized only in the "Occupancy" and "Vacancy" modes and is the amount of time after the motion sensor stops sensing motion that the lights will turn off. The default time is 5 minutes and can be set as short at 5 seconds, and as long as 30 minutes. To disable this functionality, you can set the operating mode to 'Manual' || N<br />
|-<br />
| '''Triple Press Timeout''' || Like the option above, this is utilized only in the "Occupancy" and "Vacancy" modes. However, this timeout will only be initiated if you press the 'on' (top) button three times within 10 seconds of each other (this does NOT get implemented if you programmatically send the on command three). This timeout overrides the setting above. When the light it turned off (either through physical press or programmatically), the original settings are re-implemented. It is NOT recommended you press the button in rapid secession to implement this override; instead a simple press (turning on the light), then waiting 1 second, press the on button again, wait 1 second, then press a final time will do just fine. || N<br />
|-<br />
|'''Triple Press Mode''' || By setting this option, when the physical 'off' (bottom) is pressed twice withing 10 seconds (physical presses only) it will override the currently set operating mode. A good use case for this would be a switch in a guest room that is normally in the 'vacant' operating mode, which will not turn on the light, but will turn it off after a time of inactivity. If a guest arrives and does not need to turn off the light automatically, pressing 'off' three times within 10 seconds then back on could put the switch into 'manual' operating mode. Please note there is not an override for this; you must use the app or programmatically change the mode again || N<br />
|-<br />
| '''Enable Motion Sensor''' || With this setting, you can enable or disable the motion sensor. Doing this will affect the '''Operating Mode''' listed above. ||Y<br />
|-<br />
| '''Motion Sensitivity''' || When the motion sensor is activated above, you can set the sensitivity of the detector from low, medium (Default) to high ||Y<br />
|-<br />
| '''Enable Light Sensing''' || Used exclusively with the "Occupancy" operating mode, this will sense the light in the room and determine if the light will come on with motion. Unfortunately, the light levels are NOT exposed to SmartThings and are used internally by the switch itself. Turning this option off will simply allow the motion sensor (if enabled) to control when the light automatically comes on. || Y<br />
|-<br />
| '''Invert Remote Switch Orientation''' || This setting, while defined as orientation by GE's documentation, does NOT change the orientation of the dimmer switch itself; the top button of the switch will always be the 'on' position and the bottom switch will always turn off the switch. However, if you have a 'child' switch connected via the 'traveler' wire, this child switch WILL have its on/off orientation swapped (inverted) || N<br />
|-<br />
| '''Motion Reset Cycle''' || This is the amount of time after motion stops that the DTH will report out that the motion has stopped. You can choose to disable this (if the motion detector goes on, it stays on), or chose a time between 10 seconds to 27 minutes. The default is 20 seconds || N<br />
|-<br />
| '''Association Groups''' || This is a very unique feature of this DTH. When set up, it allows you to control other switches (Z-Wave only) when physically pressing the main dimmer switch associated with this DTH, or activated through the local (motion detector controlled) activation. Simply place the Device Network ID (from the SmartThings IDE>>My Devices) in one of the two lists provided. Separate each device with a comma; then, when you press the "on" button from the main dimmer (or is activated through the local motion detector option in the "occupancy" mode), all of the Z-Wave devices will go on as well. This control is only one way; you can not go to one of the 'associated' Z-Wave switches and turn it off and expect the main switch to react, unless you have this DTH on THAT switch as well. Please note that these commands bypass the normal SmartThings cloud. Turning on remote lights via this method MAY NOT properly show the correct status of the associated switches in the SmartThings Mobile Application || N<br />
|-<br />
|}<br />
<br />
==Interface==<br />
<br />
The interface for the DTH is rather straight forward and is consistent with other SmartThings devices, but there are a few custom buttons you should be familiar with:<br />
<br />
[[File:GEMotionSwitchDTHGUI.png|300px]]<br />
{| class="wikitable"<br />
|-<br />
! '''Item''' !! '''Name''' !! '''Notes'''<br />
|-<br />
| '''A''' || '''On/Off Indicator/Button''' || Just like an ordinary switch, this area not only shows the state of the switch, but also acts as a button to turn on or off the device with a tap<br />
|-<br />
| '''B''' || '''Version Number''' || This is informational and will show the version and date of the DTH.<br />
|-<br />
| '''C''' || '''Motion Detector''' || This is an indicator of the motion registered at the dimmer. Please note that the device may appear non-operational if the settings are turned off for the motion detector<br />
|-<br />
| '''D''' || '''Operation Mode Button''' || This indicates the current operation mode (Occupancy, Vacancy, Manual) for how the device reacts to motion. You can also tap this button to toggle the modes one at a time<br />
|-<br />
| '''E''' || '''Refresh''' || This refreshes the display when tapped. Some actions may require you to leave the DTH and come back into it to see the changes<br />
|-<br />
| '''F''' || '''Dashboard''' || This area shows you individual settings that could differ from your global device settings (due to other apps controlling aspects of the DTH)<br />
|-<br />
| '''G''' || '''Settings''' || This area allows you to access the advanced settings of the DTH (See: [[GE_Z-Wave_Motion_Sensor_Switch#Settings]])<br />
|-<br />
|}<br />
<br />
===Dashboard===<br />
<br />
The small section at the bottom of the main page is designated as a dashboard. This area shows settings that can be changed by other applications. If you see a double exclamation points (!!) appear in front of a setting, that means it differs from the settings you set up in the '''Settings''' area (or the default values if you haven't set up a specific value for some of the settings).<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please note'''<br />
If you are upgrading from a previous version, you MAY see <br />
an empty dashboard or simply two dashes (--). To resolve this, <br />
enter the '''Settings''' area and save the settings. Your <br />
dashboard should now be visible.<br />
<br />
==Developer Notes==<br />
While a user can set the capabilities of the dimmer using the Settings area ([[GE_Z-Wave_Motion_Sensor_Switch#Settings]]), advanced users/developers can access many of these same settings from applications using the commands below. Many of these commands are already used in applications like WebCoRE or Ask Alexa. Changing these setting via other applications will display a log entry in SmartThings' Live Logging. Please note that all these commands are case-sensitive.<br />
<br />
===On/Off===<br />
Just like an ordinary switch, you can use the standard SmartThings commands for lighting:<br />
<br />
<pre style="display: inline-block;"><br />
device.on()<br />
device.off()<br />
</pre><br />
<br />
===Operating Mode===<br />
<br />
These 3 commands can be used to set the operating mode for the switch and how it reacts to motion (Vacancy, Occupancy, Manual). Please note that you MUST have the motion detector enabled in order to utilize some of these functions.<br />
<br />
====Vacancy====<br />
<br />
These commands set the operation mode to 'Vacant'. This means that the switch will NOT turn on automatically, but will turn off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Vacancy' operations mode. <br />
<br />
<pre style="display: inline-block;"><br />
device.vacancy()<br />
device.vacant()<br />
</pre><br />
<br />
====Occupancy====<br />
<br />
These commands set the operation mode to 'Occupancy'. This means that the switch will turn on and off automatically based on the motion parameters you have set up. Please note there is no preference on which command you utilize; both will place the device into the 'Occupancy' operations mode. <br />
<pre style="display: inline-block;"><br />
device.occupancy()<br />
device.occupied()<br />
</pre><br />
<br />
====Manual====<br />
<br />
This command set the operation mode to 'Manual'. This means that the switch will not turn on or off automatically. <br />
<br />
<pre style="display: inline-block;"><br />
device.manual()<br />
</pre><br />
<br />
===Motion Sense===<br />
<br />
These commands allow you to set the sensitivity of the motion sensor (when activated) via Groovy programming or through the WebCoRE interface. You can also turn the motion sense capability off using the '''''device.setMotionSenseOff()''''' command. <br />
<br />
<pre style="display: inline-block;"><br />
device.setMotionSenseLow()<br />
device.setMotionSenseMed()<br />
device.setMotionSenseHigh()<br />
device.setMotionSenseOff()<br />
</pre><br />
<br />
If you change this to a level (or off) that differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
[[File:GEMotionSwitchSync.png|250px]]<br />
<br />
'''Please Note'''<br />
If you programmatically set the motion sense to anything but off<br />
and the motion sensor is currently disabled, this action will not <br />
only set the sensitively of the motion sensor, but it will also enable<br />
it.<br />
<br />
===Light Sense===<br />
<br />
These commands will programmatically set the light sensor. The light sensor is used while in "Occupancy" operational mode to determine if the light should come on in response to motion. If you change this setting and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.lightSenseOn()<br />
device.lightSenseOff()<br />
</pre><br />
<br />
===Timeout Delay===<br />
<br />
These commands are only used in the "Occupancy" and "Vacancy" modes. "Timeout delay" is the amount of time after the motion sensor stops sensing motion that the lights will turn off. Instead of sending a specific time, there are commands for each of the options, from 5 seconds to 30 minutes. Any requirement of anything longer that 30 minutes and you should consider using the "Manual" mode with requires a ZWave (programmic) or physical push of the 'off' button to turn off the light. If you change this timeout and it differs than how you have it set within the device's settings area, a small "!!" will appear in your dashboard to indicate this.<br />
<br />
<pre style="display: inline-block;"><br />
device.setTimeout5Second()<br />
device.setTimeout1Minute()<br />
device.setTimeout5Minutes()<br />
device.setTimeout15Minutes()<br />
device.setTimeout30Minutes()<br />
</pre><br />
<br />
==Community Discussion==<br />
<br />
You may participate in the community discussion for this DTH here:<br />
<br />
https://community.smartthings.com/t/release-ge-z-wave-motion-switch-26931-and-motion-dimmer-26933-version-1-0-2/131305<br />
<br />
<br />
[[Category:Unofficially supported devices]]</div>MichaelStruck