Alexa Virtual Device Creator

The Unofficial SmartThings Blog
Jump to: navigation, search

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.

Summary

Alexa@2x.png

Category: My Apps

Author:Michael Struck --MichaelStruck (talk) 11:23, 20 January 2016 (EST)

ST Community handle: https://community.smartthings.com/users/michaels/activity

Latest Version

The latest version of the application is as follows (as of 8/29/18):

   Alexa Virtual Device Creator: 
   Version: 1.0.2
   https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/alexa-virtual-switch-creator.src/alexa-virtual-switch-creator.groovy

Open Source License/Trademarks

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:

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

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.

Requirements

The following are the basic requirements to use Alexa Virtual Device Creator:

  • A mobile device running the SmartThings mobile application.
  • (Optional) Alexa Echo Device
  • (Optional) Some method to tie the changing of the virtual device to a SmartThings process (like Ask Alexa and its macros/extensions, or WebCoRE)

Definitions

  • 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”.
  • 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.
  • GitHub: A web-based repository that allows for distribution revision control and source code management functionality.
  • URL: Uniform Resource Locator, or basically the address of a web site or online resource, such as http://www.smartthings.com
  • 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.
    • 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.
    • 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.
    • 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.

Alexa Virtual Device Creator Installation

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.

Community Installer (Free Marketplace)

To install Alexa Virtual Device Creator via the Community Installer, please see here: http://thingsthataresmart.wiki/index.php?title=Community_Installer_(Free_Marketplace)

Simply find Alexa Virtual Device Creator in the list, and install ALL pieces of the application. If you are upgrading, click the <<Update>> button.

CI-Search.png

Manual Code Load

The code for the main parent app is found on the GitHub site:

  https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/smartapps/michaelstruck/alexa-virtual-switch-creator.src/alexa-virtual-switch-creator.groovy
  • 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).

GitHub raw.png

Loginscreen.jpg

  • 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.

MySmartApps.png

  • Find the button on this page labeled +New SmartApp and click it.

+NewSmartApp.png

  • 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.

NewSmartAppCreate.png

  • 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.

SavePublish.png

Advanced Installation

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 [[1]].

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.

  • First, find the Settings button at the top of your SmartThings IDE page (this will only appear after you integrate with GitHub)

IdeSettings.jpg

  • 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:

Owner: MichaelStruck

Name: SmartThingsPublic

GitHubIntegration.jpg

  • Close the GitHub Repository Integration page
  • Next, click the Update from Repo button at the upper-right corner of the IDE
  • On the right-hand column, scroll down to click the apps you want to install. This will typically be:
   Application: smartapps/michaelstruck/alexa-virtual-switch-creator.src/alexa-virtual-switch-creator.groovy
  • 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.

Upgrade from Alexa Virtual Switch Creation

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.

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.

In App Virtual Device Creation

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.

   Notice
   The devices you create within Alexa Virtual Device Creator are considered 'child devices' of the SmartApp and you 
   could receive errors should you attempt to remove Alexa Virtual Device Creator and the devices are used in other 
   SmartApps.
   

First, like the Alexa Switch installation, you must load the code as a new device type:

  • To create the new virtual devices, copy the code from the following GitHub location:
   Alexa Switch: https://github.com/MichaelStruck/SmartThingsPublic/blob/master/devicetypes/michaelstruck/alexa-switch.src/alexa-switch.groovy
   Momentary Button Tile: https://github.com/MichaelStruck/SmartThingsPublic/blob/master/devicetypes/michaelstruck/momentary-button-tile.src/momentary-button-tile.groovy
   Virtual Motion Detector: https://raw.githubusercontent.com/MichaelStruck/SmartThingsPublic/master/devicetypes/michaelstruck/virtual-motion-detector.src/virtual-motion-detector.groovy
  • 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.
  • 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.
  • Click the link +New Device Type in the upper right-hand corner of the screen.
  • 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.
  • Click Save and then click Publish (For Me).

From here, you may exclusively use the Alexa Virtual Device Creator SmartApp to create your virtual devices.

To create a new device, enter the name of the device in the <<Device Label>> area. Be sure to choose a unique name.

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.

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.

Clicking <<Save>> or "<" to bring you back to the main Alexa Virtual Device Creator page.

Limitations

There are some limitation you should be aware of when using this SmartApp

  • If you delete the app (and the devices it created are not being used), the devices WILL disappear.
  • 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.
  • YOU MUST use the DTHs I have included above to use this app. It will NOT create generic virtual devices
  • You may not be able to delete the app if a device you created with it is still being used else where in SmartThings
  • When you create a device, be sure you ‘discover’ it via Alexa’s own app
  • 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.