Ask Alexa - Macros

The Unofficial SmartThings Blog
Jump to: navigation, search

Macros allow you to group multiple functions into one command. Here is a quick example of where macros can be of assistance: Let's say you want to perform multiple functions with one command. For example, if you want to turn all of the lights in the living room on and you also want to set the mode and/or arm the Smart Home Monitor. In this case, you would create a control macro with all of these functions. When you execute the control macro, all of the functions are performed. If you wish to run the function at a later time (maybe as a delay before leaving the house) you can specify a time delay and the macro will run in the future.

WebCoRE trigger macros are also included and are used to trigger WebCoRE 'pistons' using a voice command.

Finally, using a extension group, you can combine control macros, WebCoRE triggers and reporting into one function. For example, let's say you have three control macros for various floors within your house. You can run each of these individually, or you can also place them into a extension group to run them sequentially with one command, along with a nightly report to finish out the macro.

Summary

Speak.png

Category: Ask Alexa Extension - Requires Ask Alexa

Author:Michael Struck --MichaelStruck (talk) 00:01, 1 January 2016 (EST)

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

Latest Version

Macros are built into the base code of Ask Alexa. There is no additional code to install to use macros.

Creating Macros

Once you enter the <<Macros>> page from the <<Ask Alexa Extensions>> main menu item, you will see any macros that are already created along with the option to create a new macro by pressing the green button at the bottom of the page

AAMacroOptions.png

On the <<Macro Settings>> page, you will enter a name for the macro (required), up to 3 aliases for the macro (optional), and then choose a type of macro you want.

   Notice
   When naming your macros (or using macro aliases), as is the case with devices and aliases, 
   ensure your macro names are unique not only within the context of the other macros, but 
   within the parent app itself. That means a macro should not share the same name with
   devices, aliases, modes, or routines within the parent app. Taking this precaution will 
   eliminate confusion when addressing the Alexa Enabled Devices with commands.
   Notes about macro aliases
   Macro aliases allow you to use different phrases to activate the same macro. For example, if
   you create a conversational macro name like "I am cold", you could also set up aliases for this
   macro such as "It is cold in here" and "Turn up the heat". You could then use different phrases to 
   activate the same action. For example, you could say <"Alexa, tell SmartThings I am cold">, 
   <"Alexa, tell SmartThings it is cold"> or even <"Alexa, tell SmartThings turn up the heat">
   and have the result be the heat going up by an amount you specify. With a custom response, you can
   create a totally conversational experience with Alexa Connected Devices.

Next, you will choose the type of macro. There are currently 3 types of macros currently available: Control Macro, WebCoRE Triggers and Extension Group, and they can be used in different ways.

AAMacroTypes.png

Once you choose a macro type, depending on what type you choose, you will have the ability to enter your settings for that particular macro, or to choose restrictions for the macro. Restrictions are used exclusively with Control, WebCoRE Trigger and Voice reporting macros. Also available on this page is the ability to post when this macro is triggered within the Message Queue, which can post a note to speakers, the notification feed, or send you a text message.. In addition, you have the ability to send the message to the queue when the macro is actually triggered (i.e. in case it was delayed through either the app or a voice command), and include what response was sent to Alexa. Finally, if you have the continuation message enabled for macros/extensions (see Ask_Alexa#Personalization) you will be presented with a final option to suppress the continuation message for the macro you are working on.

AAControl1.png

Below is additional information on the macros currently available: Control Macro, WebCoRE Triggers and Extension Groups.

Control Macro

Control.png

A control macro allows you to control various aspects of your SmartThings devices and settings with one command. For this macro, choose the routine, mode, Smart Home Monitor status you want to have enabled when the you speak the control macro name. You also have the option of turn on/off (or toggle) certain devices such as switches, dimmers and colored lights, change the status of room occupancy sensors and output text-speech audio (TTS) to speakers and voice synthesis devices via the Ask Alexa Message Queues. In addition, you have the ability to set the lock/unlock status of a door lock, or even open/close a garage door. Using a control macro and some of the options within the macro you can set up very natural speech request. For example, if you set up a macro called "It is too bright in here", you can actually have the macro react by simply saying <"Alexa, tell SmartThings it is too bright in here"> and have the lights dim by an amount you specify. You can even have the macro reply with a custom message that could say, "I have decreased the lights for you."

AAControl2.png

There is also an option to run an HTTP GET request when you activate the control macro. This is for advanced users and sends an HTTP GET request (External to your LAN or Internet facing) upon the Alexa Switch being triggered. If you wish to use this option with a SmartThings location, you may also install the Cloud Interface SmartApp (see Alexa Helper#Cloud Interface Code Installation and Alexa Helper#Cloud Interface Smart App Setup). This functionality may also be used with the IFTTT web site. On the HTTP configuration page, you will also be presented with other advanced options such as specifying an IP, port and command for LAN (internal) connected devices.

At the bottom of the section, you are given the option to have a message sent to a message when the scenario is triggered. This could be useful in situations where you delay the triggering of the control macro and want to be notified.

To activate a control macro, simple say, <"Alexa, Ask SmartThing to run MacroName"> or even <"Alexa, Ask SmartThing MacroName">. You also have the option of delaying the activation of the actions of the macro. You can do this either in the control macro through a default delay, or simply append your command with a number of minutes. This might be similar to <"Alexa, Ask SmartThing to run MacroName in 5 minutes">. If any verbal delay is given, the default delay will be ignored. If the default delay is set and no verbal delay is given, the default delay will be used. Be sure to specify whole minutes, even if the length is an hour (use "60 Minutes" in this specific case). If you inadvertently trigger a control macro and wish to cancel the timer, you can simply say <"Alexa, Ask SmartThing to cancel MacroName">. Once you set a timer the control macro will not allow you to run this again until it either executes or you cancel it. Please note, depending on your PIN setup (see Ask_Alexa#Password_PIN), you may also append your request with the required password. So, in the example above, the command would be <"Alexa, Ask SmartThing to run MacroName in 5 minutes password 1234">.

Finally, at the bottom of the page you can specific a unique response when you execute the control macro. You will lose the ability to get feedback on errors that occur when the macro runs; if your devices does not respond as you would expect, simply delete the text in the area labeled <<Acknowledgement Message>> and the default response or error message will be spoken. If you are using the control macro with a extension group you may also want to click the slider to completely eliminate any output from the individual macros.

WebCoRE Trigger

CoRE.png

Using the WebCoRE community SmartApp, you can create very complex, condition-based automations (pistons). Using the WebCoRE Trigger Macro within Ask Alexa, you can trigger these WebCoRE 'pistons' with your voice. Simply create a WebCoRE Trigger, choose the piston you want to run (typically a DO Piston), set a delay (if necessary) and an acknowledgement message, along with any restrictions that are appropriate (especially if you run this as part of a Ask_Alexa_-_Macros#Extension_Group). It is that simple. If you do have a PIN set up in the <<Settings>> area you will also be given the option of password protecting the macro from running.


AACoRE.png

   Please Note
   While you can specify a piston within Ask Alexa to trigger, you are 
   not limited to this method as the only integration into WebCoRE. Any macro is
   able to trigger a piston, however, this functionality is within WebCoRE. When
   creating a piston, you also have the ability to specify a macro from Ask
   Alexa as a condition. In other words, Ask Alexa can 'push' a trigger
   to run a piston, or WebCoRE can listen for any macro to run and then trigger.
Advanced features

With the power of WebCoRE, there are advanced features of this macro that allow you to take advantage of this power. The setup of these features is more manual, but when you set them up properly you will have a lot more control over your WebCoRE environment. To set up these features, you will need to do a little bit of planning about the various function you might do in WebCoRE. In the example linked below, the user wanted a single macro that would allow him to change channels on his television simply by saying the station's name. Previously, he would need to create multiple WebCoRE macros to accomplish this. However, he added additional parameters to his WebCore output to allow for just one macro and the channel names as an addition parameter sent along to the WebCoRE piston. The channel names were places into a slot of the Amazon Developer Site (under LIST_OF_WCP. This list can be maintained by going to <<Settings>><<xParams For WebCoRE Macros>>). He then simply says the macro name (Change Channel) and the additional parameter. This information is sent to a complex WebCoRE piston and the channel changes.

For more information, please see this excellent write up: http://thingsthataresmart.wiki/index.php?title=Using_Parameters_with_Ask_Alexa_and_webCoRE

As of version 2.3.6 you can pass both a number (through the mNum parameter) in addition to a word (xParam) to the WebCoRE piston.

Also, as of version 2.3.7 of Ask Alexa, you can maintain your xParam list via the main application. Simply go to <<Settings>> <<xParams For WebCoRE Macros>> to add these:

AASettings-1.png

In addition to running a WebCoRE Macro directly (by voice), you also have the ability to run it when a switch is triggered via voice. Simple expand the section called <<Switch trigger for this macro>> and you can have one switch action control the running of this macro. In addition, you can have an mNum (number) or xParam (verbal parameter) sent to WebCoRE with the activation of the piston. Please note that if the macro is password protected this WILL NOT prompt you for a password and will run freely. This activation method is perfect for Alexa native routines.

AAWebCoreSwitchTrigger.png

Extension Group

Extfolder.png

The extension group is somewhat analogous to a "box within a box". After setting up various controls, WebCoRE Triggers, weather and/or voice reports, you may find that you are running some of them in one at a time with multiple commands. As mentioned above, a good example of a use case is a multi-story home. While each level may have a control macro, you may have a need to run them all at once (for example, a good night action). To do this, you would simply include the extensions you want to run and then name this new extension something unique. Then, when you run the extension, the "child extensions" will run in order (the order determined by what order you select them we in the app). Other examples of how to use extension, along with restriction to create complex "if/then" routines, are included in the Ask_Alexa#Tips_and_Tricks section below. If you have a PIN set up under <<Settings>> in the parent app, you will be given the opportunity to enable a PIN for the extension group.

AAMacroGroup.png

Extension groups can be activated with a voice command, or with the Alexa Flash Briefing function (See: Ask_Alexa#Flash_Briefing)

   Please Note
   If you have control or WebCoRE Trigger macros as part of your Extension Group, and have PINs enabled
   for them, an unrestricted Extension Groups will still run these if you do not have a PIN on the
   Extension Group itself. If you have any concerns about running extension unprotected, you should
   enable the PIN on the Extension Group itself.

In addition to running control macros, you can also run a voice report or weather report as part of the extension group. Simply add the desired voice report at the bottom of the list of extensions to run and it will speak the results of the report.

   Please Note
   Running multiple voice/weather reports and macros in the same extension group
   can get VERY wordy. It is recommended to use the <<Custom Acknowledgment Message>>
   area within the extension groups to modify what is actually reported, or 
   to limit the amount of time the extension repeats back the results. Please note that  
   clicking items like <<Append...>> area will eliminate much of the output, but it
   WILL mask any errors that occur, so it is recommended you do this only after you confirm
   your extension group has the desired results. You may also customize the output
   of the individual extension themselves by using the control macro area's
   <<Acknowledgement Message>>. This, of course, is not recommended if you use the
   voice reports as this will also keep them from reporting out as well.

Advanced: Display REST URL For Certain Macros

As mentioned in the definitions (see Ask_Alexa#Definitions), a REST URL is the (secure) "path" to your devices through a web command. The <<REST URL>> will appear on the main Control Macro and Extension Group pages. This is an advanced function for those users that may want to control a separate location's (two SmartThings accounts, two Amazon accounts, etc) devices from a centralized location. Most users will not need to use this for a single home configuration. However, for those that need this feature, it allows you to run a Control Macros and Extension Groups (no other parameters) using a single URL. Please note that if you use this URL in another Control Macro (Run HTTP Request...) or Extension Group with and included voice macro, there is NO feedback from the GET command that is run to the Alexa (at either location). However, if you run the URL from a web page you will receive JSON output that would normally go to Amazon. The feature to allow this to pass through to the running Control Macro is being evaluated.

ControlMacroURL.png

Advanced: Switch trigger for this macro

If you have a need to trigger any of the macro types you have created, you can use a switch (typically a momentary switch/tile) to trigger the activation. An example of how this can be used is outlined here: Ask_Alexa#Good_Night_Weekdays.2FWeekends_.28Native.2C_Non-Invocation.29

Reminder About Amazon Developer Slots

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 macros to be reflected in the Amazon developer site. See Ask_Alexa#Setup_Variables for more information.