Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		 Previous revision
indigo_2022.1_documentation:plugins:alexa [2022/03/11 20:28] – external edit 127.0.0.1indigo_2022.1_documentation:plugins:alexa [2025/04/14 20:10] (current) – external edit 127.0.0.1
Line 1: Line 1:
 +====== Alexa ======
 +
 +[[https://www.amazon.com/b?node=21576558011|Alexa]] is a smart assistant voice system from Amazon which is [[https://www.amazon.com/b?node=15443147011|integrated into many devices]], including the [[https://www.amazon.com/smart-home-devices/b/?ie=UTF8&node=9818047011&ref_=sv_devicesubnav_1|Echo devices from Amazon]], sound bars and smart speakers, watches, thermostats, TVs, headphones, etc., from a variety of manufacturers.
 +
 +Amazon has enabled integration with third parties like Indigo to integrate smart home devices so that you can use voice commands to control them (aka a //Smart Home Skill//). **In English speaking regions**, we've also created a way to execute action groups and have the value of variables read to you (aka a //Custom Skill//).
 +
 +<color blue>**Note**</color>: **this capability was added in Indigo 2021.1** so if you are using an older version you will need to upgrade. If your Indigo Up-to-Date Subscription is active and you have your Indigo Reflector configured and working, you just need to install **Indigo 2021.1** or later. You also **must have** OAuth enabled in the [[indigo_2022.1_documentation:getting_started#starting_indigo_server|Start Local Server dialog]] for Alexa to work.
 +
 +===== Smart Home Skill =====
 +
 +<color red>**__Note__**</color>: **the Alexa skill is currently available in the Alexa skill stores for most of the regions in which we sell Indigo (US, Canada, UK, the Netherlands, Australia, New Zealand, France, Germany, Spain, Italy).**
 +
 +We have implemented a skill which you can enable that will provide standard smart home device control. This enables an Alexa user to control devices in the exact same way regardless of how that device is connected to Alexa. This section will give you an overview of the device types in Indigo that you can publish to Alexa for control. We don't automatically publish your Indigo devices for a variety of reasons, but primarily as a security measure. You must make an explicit decision to enable voice control of a device.
 +
 +You must have your Indigo Reflector activated in order to proceed.
 +
 +You enable the Indigo Skill in the Alexa app (this is the iOS App as of June 2021, it may change):
 +
 +  - Open the Alexa App.
 +  - Go to the Devices list and click the link to Your Smart Home Skills.
 +  - Click Enable Smart Home Skills.
 +  - Tap the Search icon.
 +  - Search for "Indigo Smart Home". You should see a skill named **Indigo Smart Home Skill** in English speaking regions and **Indigo Smart Home** everywhere else, with an icon that matches the logo of the Mac Client.
 +  - Add the skill.
 +  - Link the skill to your Indigo Account & license (currently by clicking/tapping the Settings button).
 +    - Log in using your Indigo Account username and password.
 +    - On the next page (the authorization page), if you have multiple Indigo Licenses, make sure you have the correct one selected (you must have an active Indigo Up-to-Date subscription); you can link one license to one Alexa (Amazon) account. If you see something else or don't see a license you were expecting to see, check the [[#Account Linking Issues]] troubleshooting section below for help.
 +
 +==== Alexa Store Links ====
 +
 +Here are direct links to the skills in their respective Alexa stores:
 +
 +  * [[https://www.amazon.com.au/dp/B097GBHBZG|Australia]]
 +  * [[https://www.amazon.ca/dp/B097GBHBZG|Canada]]
 +  * [[https://www.amazon.fr/dp/B09DCZDRRS|France]]
 +  * [[https://www.amazon.de/dp/B09DCZDRRS|German]]
 +  * [[https://www.amazon.it/dp/B09DCZDRRS|Italy]]
 +  * [[https://www.amazon.es/dp/B09DCZDRRS|Spain]]
 +  * [[https://www.amazon.co.uk/dp/B097GBHBZG|United Kingdom]]
 +  * [[https://www.amazon.com/dp/B097GBHBZG|United States]]
 +==== Making a Device Available in Alexa ====
 +
 +To make a device available to Alexa, you must explicitly publish it. Use the''**Plugins->Alexa->Manage Device Publications...**'' menu item to open the publication dialog:
 +
 +{{:indigo_2022.1_documentation:plugins:alexa_manage_publications.png?nolink|Alexa Manage Publications Image}}
 +
 +In this dialog, you will select a device from the popup. Note that the popup is divided into two sections:
 +
 +{{:indigo_2022.1_documentation:plugins:alexa_manage_device_list.png?nolink|Alexa Manage Device List Image}}
 +
 +The top part of the list are Indigo devices that can be published to Alexa, but haven't yet. If you select one of these devices, the dialog will show you the appropriate options for that device. For all devices, you can specify an Alternate Name which will be used in Alexa when you operate it (i.e. Alexa, turn on //office lamp//). If you leave this field blank, the actual Indigo device name will be used. Note that Alexa device names can only contain letters, numbers, and spaces.
 +
 +Some devices will also show a Type popup:
 +
 +{{:indigo_2022.1_documentation:plugins:alexa_type_popup.png?nolink|Alexa Type Popup Image}}
 +
 +You will use this popup to tell Alexa more specifically what kind of device it is. We will attempt to look at various other characteristics of the device to select what we believe is the appropriate type, but you may select any from the list and we will relay that information to Alexa so you can control it using appropriate terminology (see below for specifics).
 +
 +The bottom part of the list are devices that you have already published to Alexa. If you select one of these devices, you can edit or unpublish the device.
 +
 +<color orange>**Warning**</color>: be sure to click the Save button before moving on or your changes won't be saved. Also, if you make any changes, __you will need to rerun discovery from an Alexa device or the Alexa app before those changes will be reflected__. As a reminder, you must either click the discover devices button in the Alexa apps or ask "Alexa, discover devices" of an Alexa enabled device.
 +==== Device Types Supported ====
 +
 +In this release, the following device types are supported:
 +
 +  * On/Off devices (sometimes referred to as relay) - simple appliance control plug-in modules, outlets, and switches are the most common type. This also includes Locks and Garage Doors.
 +  * Dimmer devices - dimmer switches and plug-in modules are the most common, though in Indigo there are a variety of other device types that Indigo sees as dimmers: Blinds/Drapes, Fans, Bulbs (including color), etc.
 +  * Thermostats
 +  * Fans - Indigo natively only supports the Insteon FanLinc fan as a proper fan device (with the right controls) - Z-Wave fan controllers are currently implemented as dimmers, but they will work as fans in Alexa if configured correctly.
 +
 +=== On/Off Devices ===
 +
 +This type of device has a boolean value, most often on/off or open/closed. To control from Alexa, you use phrases like:
 +
 +  * //Alexa, turn on office lamp//
 +  * //Alexa, turn off bedroom fan//
 +  * //Alexa, open garage door//
 +
 +When you select an Indigo device that is a standard On/Off device to publish, you will get a popup that will help us tell Alexa how to control your device:
 +
 +{{:indigo_2022.1_documentation:plugins:alexa_relay_subtypes.png?nolink|Alexa Relay Subtypes Image}}
 +
 +We will take a guess at what the specific type of the device is, but we won't always guess correctly. For instance, if there isn't anything about your device that Indigo can determine, it will just automatically select ''**Switch**''. You can override that setting however to make the device best match what it does.
 +
 +The options are:
 +  * Door Bell - as of this release, this will only allow you to turn on/off the doorbell, not accept ring events. We will look at adding that in a future release.
 +  * Door Controller - if you have a device that physically operates a door (but not a garage door), you can use this device type. You can then say things like:
 +    * //Alexa, open the front door//
 +    * //Alexa, what's the status of the front door//
 +  * Garage Controller - this is exactly what you think it is. You will be able to open/close (raise/lower) your garage door. Alexa uses this control type as a more secure option. When Alexa first discovers a garage door, it will not allow you to control the door by voice. Rather, it will tell you to control it manually or go to the Alexa app and configure the door for use with voice control. In the settings for the door in the Alexa app, you will be able to enter a 4 digit PIN for extra security. When you ask Alexa to open or raise the door, you will be prompted for your PIN code. If you have an automatic door controller (specified above) and want the extra security of a PIN code, you can select Garage Controller as well and it should work just like a garage door. PIN codes are set per device so each can be different. You can say things like:
 +    * //Alexa, open the garage door//
 +    * //Alexa, is the garage door open//
 +  * Lock - similar to a garage door, a lock device will need to have a PIN assigned for it in the Alexa app. Once that's done, when you attempt to unlock the door (//Alexa, unlock the back door//), it will prompt you for the PIN. You can say things like:
 +    * //Alexa, lock the back door//
 +    * //Alexa, is the back door locked//
 +  * All the rest of the types will simply respond to standard on/off commands. There is currently no distinction other than the icon that shows up in the Alexa app. You can say things like:
 +    * //Alexa, turn on bathroom exhaust fan//
 +    * //Alexa turn off desk lamp//
 +=== Dimmer Devices ===
 +
 +This type of device is most often a dimmable load, though there are some other options. Most of these device types will also respond to on/off commands like Relay Devices above. To control from Alexa, you use phrases like:
 +
 +  * //Alexa, brighten office lamp to 35%//
 +  * //Alexa, dim office lamp by 15%//
 +
 +If the devices supports color and/or white temperature, you can use phrases like:
 +
 +  * //Alexa, set color of office bulb to red// (color devices)
 +  * //Alexa, set office bulb to daylight// (white color temperature)
 +  * //Alexa, make office bulb warmer// (white color temperature)
 +
 +For white temperatures, the following table maps the names that Alexa expects to the color temp in kelvin:
 +
 +| **Shades of White** | **Temperature in Kelvin** |
 +| warm, warm white  | 2200  |
 +| incandescent, soft white  | 2700  |
 +| white  | 4000  |
 +| daylight, daylight white  | 5500  |
 +| cool, cool white  | 7000  |
 +
 +When you select an Indigo device that is a dimmer device to publish, you will get a popup that will help us tell Alexa how to control your device:
 +
 +{{:indigo_2022.1_documentation:plugins:alexa_dimmer_subtypes.png?nolink|Alexa Dimmer Subtypes Image}}
 +
 +We will take a guess at what the specific type of the device is, but we won't always guess correctly. For instance, if there isn't anything about your device that Indigo can determine, it will just automatically select ''**Dimmer**''. You can override that setting however to make the device best match what it does.
 +
 +The options are:
 +
 +  * ''**Blind**'' - use this type if your dimmer device actually controls blinds, shades, or drapes. You can say things like:
 +    * //Alexa, raise the blinds to twenty-five percent//
 +    * //Alexa, set the drapes to fifty percent//
 +    * //Alexa, close the shades//
 +    * //Alexa, what is the status of the shades//
 +  * ''**Fan**'' - use this type if your device actually controls a fan (as of this release Z-Wave fan controllers are treated as dimmers in Indigo). Fan devices from Indigo in Alexa will support 4 modes: **Off**, **Low**, **Medium**, **High**. You can say things like:
 +    * //Alexa, set ceiling fan to medium//
 +    * //Alexa, set ceiling fan to highest//
 +    * //Alexa, ceiling fan speed//
 +    * //Alexa, turn off ceiling fan//
 +  * ''**Valve**'' - use this type if your device controls a valve, or really any device that has a 0-100% range. You can say things like:
 +    * //Alexa, set set the valve to thirty percent//
 +    * //Alexa, increase valve by ten percent//
 +    * //Alexa, turn off the valve//
 +  * All the rest will support standard on/off and dim/brighten. If the device supports color and/or white color temperature, those commands will be added to the standard on/off and dim/brighten commands (see the examples above).  There is currently no distinction other than the icon that shows up in the Alexa app.
 +
 +=== Indigo Fan Devices ===
 +
 +Indigo has a native fan device type. Currently, the only built-in device using this type is the Insteon FanLinc. There are some other plugins which also support this device type. If you select a device of this type the only option will be the Alternative name as there are no other options. You can say things like:
 +    * //Alexa, set ceiling fan to medium//
 +    * //Alexa, set ceiling fan to highest//
 +    * //Alexa, increase ceiling fan speed//
 +    * //Alexa, turn off ceiling fan//
 +
 +=== Indigo Thermostat Devices ===
 +
 +Any Indigo thermostat device can be added to Alexa. Schedule/program mode isn't supported on thermostats that offer that feature.
 +
 +<color red>**NOTE**</color>: the Alexa implementation for thermostats is quite limited as it only fully supports thermostats that are in either heat or cool mode. In North America, most thermostats stay in //auto// mode, which allows (at least) two setpoints to be active at the same time to call for heat or cool depending on the temp. Alexa's support for //auto// mode is fundamentally read-only: you can't adjust either setpoint while in //auto//. Further, the error that Alexa will respond with implies that you have to manually set the mode on the thermostat itself to either //heat// or //cool// in order for you to adjust setpoints. This is incorrect in that you can say to Alexa "set the thermostat to heat", and that will correctly change mode from //auto// to //heat// (same applies to //cool//).
 +
 +
 +So, with that warning aside, you can say things like:
 +    * //Alexa, set the thermostat to cool//
 +    * //Alexa, what is my thermostat set to//
 +    * //Alexa, turn off the heat//  (<color orange>**Warning**</color>: this will turn the thermostat off regardless of mode)
 +    * //Alexa, set the AC to seventy-five//
 +    * //Alexa, make it warmer in here//
 +
 +
 +===== Custom Indigo Skill =====
 +
 +**<color red>NOTE</color>**: **the Custom Skill is available in English speaking regions only**.
 +
 +When you enable the **Indigo Smart Home Skill** in the Alexa app, you also gain access to some custom functionality that's specific to Indigo. In this release, we enable you to hear the value of a variable (complete with speech markup), hear a list of all of your variables, and run Action Groups.
 +
 +Custom skill requests require that you preface your requests by saying //Alexa, tell Indigo// or //Alexa, ask Indigo//. These are called **invocations** and are needed so that Alexa can know where to direct the request. It's not needed for Smart Home Skills (ones that deal with Indigo devices as described above as well as devices from other skills) because Alexa knows details about each individual device and where to send the request based on that information.
 +
 +**<color red>NOTE</color>**: Unfortunately, the invocation for the skill is currently different in different regions.
 +
 +  * US, UK - "indigo" is the invocation
 +  * CA, AU - "indigo home" is the invocation
 +
 +We are attempting to get Amazon to help us correct this, but we are unsure if it's going to be possible or not at this time.
 +
 +=== Speaking the Value of a Variable ===
 +
 +**<color blue>Note</color>**: When naming variables for use with Alexa, you should use underscores_to_separate_words. That is how the plugin will map separate words from Alexa onto variables (which can't contain spaces).
 +
 +To hear the value of a variable, just ask Indigo for it. There are a variety of ways to ask, here are a few (variable names are in quotes, underscores are treated as spaces):
 +
 +  * //Alexa, ask Indigo to get "current_weather_conditions"//
 +  * //Alexa, ask Indigo to look up "current_weather_conditions"//
 +  * //Alexa, ask Indigo to read "current_weather_conditions"//
 +  * //Alexa, ask Indigo to say "current_weather_conditions"//
 +  * //Alexa, ask Indigo to speak "current_weather_conditions"//
 +  * //Alexa, ask Indigo to tell me "the_status_of_the_house"//
 +  * //Alexa, ask Indigo for the value of variable "current_weather_conditions"//
 +  * //Alexa, ask Indigo the value of "current_weather_conditions"//
 +  * //Alexa, ask Indigo the current value of "weather_conditions"//
 +
 +You can also use //tell Indigo// interchangeably with //ask Indigo//.
 +
 +The default response (in the default voice) will be:
 +
 +//The value of variable "current weather conditions" is "mostly cloudy"//
 +
 +You can adjust how Alexa responds in a couple of ways:
 +
 +  * You can use [[https://developer.amazon.com/en-US/docs/alexa/custom-skills/speech-synthesis-markup-language-ssml-reference.html|Speech Synthesis Markup Language (SSML)]] to mark up the text in a variable to customize how Alexa reads back the value. Any variable value that begins with a less than sign (<), which we use as a key that the text contains SSML, will be read exactly as specified in the variable without any additional words (i.e. //The value of variable// won't be prepended). If your markup text doesn't naturally begin with a markup tag, wrap the entire string in ''<speak></speak>'' tags.
 +  * Variable values that contain the device (%%d:deviceId:deviceState%%) or variable (%%v:variableId%%) markup values will be correctly substituted by Indigo.
 +  * You may also specify in the plugin's config that all variable values should be read exactly as they are stored without the added verbiage.
 +
 +
 +=== Get a List of Variables ===
 +
 +You can hear a list of your variables as well. Here are a variety of ways to ask:
 +
 +  * //Alexa, ask Indigo to get my variable list//
 +  * //Alexa, ask Indigo to list my variables//
 +  * //Alexa, ask Indigo to list all variables//
 +  * //Alexa, ask Indigo what variables are available//
 +
 +You can also use //tell Indigo// interchangeably with //ask Indigo//.
 +
 +=== Execute an Action Group ===
 +
 +You can tell Indigo to execute an action group. Here are a variety of ways to ask (action group names are in quotes):
 +
 +  * //Alexa, tell Indigo to arm "the kitchen zone"//
 +  * //Alexa, tell Indigo to do "my favorite thing"//
 +  * //Alexa, tell Indigo to execute "toggle music"//
 +  * //Alexa, tell Indigo to launch "rocket"//
 +  * //Alexa, tell Indigo to make "the house secure"//
 +  * //Alexa, tell Indigo to perform "routine maintenance"//
 +  * //Alexa, tell Indigo to play "my favorite playlist"//
 +  * //Alexa, tell Indigo to reset "the alarm"//
 +  * //Alexa, tell Indigo to restart "the laundry timer"//
 +  * //Alexa, tell Indigo to restore "the standard speaker set"//
 +  * //Alexa, tell Indigo to run "routine maintenance"//
 +  * //Alexa, tell Indigo to start "the laundry timer"//
 +  * //Alexa, tell Indigo to set "the playlist to classic rock"//
 +
 +Action group names can contain letters, numbers, and spaces only. If you say "playlist eighties music", the action group name will need to be "playlist 80s music". If you are unsure how to name an action group, just attempt to execute it with one of the above utterances. If Indigo doesn't find an action group matching what you said, it will log it to the Event Log window like this:
 +
 +''<color red>Alexa Error                     an action group named 'kitchen zone' does not exist in your indigo server
 +</color>''
 +
 +That will tell you the text that Alexa sent to the plugin, so you can name your action group exactly what's in single quotes and the next time it will work.
 +
 +<color blue>**Note**</color>: what you say before the action group name will work for any action group name. We picked the above examples only because they are normal complete English sentences, but you could just as well say //Alexa, tell Indigo to arm "the laundry timer"// and the effect would be the same as saying //Alexa, tell Indigo to start "the laundry timer"//. You can also use //tell Indigo// interchangeably with //ask Indigo//.
 +
 +===== Alexa Plugin operations =====
 +
 +=== Plugin Startup ===
 +
 +When the plugin starts up, you will see a list of what's published to Alexa in the Event log. It will look something like this:
 +
 +   Started plugin "Alexa 2022.1.0"
 +   Alexa                           Finding devices to publish to Alexa...
 +   Alexa                           ... '010 - Smart Fan Control (14287)' published as 'office fan'
 +   Alexa                           ... '016 - Plug-In Appliance Module (ZL-PA-100)' published as 'office lamp'
 +   Alexa                           ... '038 - Lamp Module (AD130)' published as 'blinds'
 +   Alexa                           ... 'automatic door' published
 +   Alexa                           ... 'FanLinc - Fan' published as 'ceiling fan'
 +   Alexa                           ... 'FanLinc - Light' published as 'fan light'
 +   Alexa                           ... 'Fortrezz Strobe' published as 'strobe'
 +   Alexa                           ... 'Hue Bulb' published as 'office bulb'
 +   Alexa                           ... 'Insteon Dimmer' published as 'valve'
 +   Alexa                           ... 'Insteon On/Off' published as 'back door'
 +   Alexa                           ... 'Insteon Thermostat' published as 'thermostat'
 +   Alexa                           ... 'Kasa Plug' published as 'garage door'
 +   Alexa                           ... 'Office Siren' published
 +   Alexa                           ... 'outlet' published
 +   Alexa                           ... 'Simple Virtual On/Off' published as 'simple switch'
 +   Alexa                           A total of 15 devices are currently published to Alexa
 +   Alexa Warning                   If you can't control a device, rerun discover from your Alexa device.
 +
 +=== Showing Publications ===
 +
 +You can also select the ''**Plugins->Alexa->Show Device Publications**'' menu item to show this list with more details and sorted by the Alexa name:
 +
 +   Alexa                           Currently published devices (Alexa name first if different than Indigo name):
 +   Alexa                             'Office Siren' ('Office Siren') - Type: RelayDevice - Subtype: Siren
 +   Alexa                             'automatic door' ('automatic door') - Type: RelayDevice - Subtype: Door Controller
 +   Alexa                             'back door' ('Insteon On/Off') - Type: RelayDevice - Subtype: Lock
 +   Alexa                             'blinds' ('038 - Lamp Module (AD130)') - Type: DimmerDevice - Subtype: Blind
 +   Alexa                             'ceiling fan' ('FanLinc - Fan') - Type: SpeedControlDevice - Subtype: None
 +   Alexa                             'fan light' ('FanLinc - Light') - Type: DimmerDevice - Subtype: Dimmer
 +   Alexa                             'garage door' ('Kasa Plug') - Type: RelayDevice - Subtype: Garage Controller
 +   Alexa                             'office bulb' ('Hue Bulb') - Type: DimmerDevice - Subtype: Color Bulb
 +   Alexa                             'office fan' ('010 - Smart Fan Control (14287)') - Type: DimmerDevice - Subtype: Fan
 +   Alexa                             'office lamp' ('016 - Plug-In Appliance Module (ZL-PA-100)') - Type: RelayDevice - Subtype: Plug-In
 +   Alexa                             'outlet' ('outlet') - Type: RelayDevice - Subtype: Outlet
 +   Alexa                             'simple switch' ('Simple Virtual On/Off') - Type: RelayDevice - Subtype: Switch
 +   Alexa                             'strobe' ('Fortrezz Strobe') - Type: RelayDevice - Subtype: Plug-In
 +   Alexa                             'thermostat' ('Insteon Thermostat') - Type: ThermostatDevice - Subtype: None
 +   Alexa                             'valve' ('Insteon Dimmer') - Type: DimmerDevice - Subtype: Valve
 +
 +=== Discovery Requests from Alexa ===
 +
 +When the plugin receives a discover request from the Alexa servers, you will see something similar to this in the Event Log:
 +
 +   Alexa                           Alexa discovery request received, assembling reply...
 +   Alexa                           ...'ceiling fan' ('FanLinc - Fan') - Type: SpeedControlDevice - Subtype: None
 +   Alexa                           ...'simple switch' ('Simple Virtual On/Off') - Type: RelayDevice - Subtype: Switch
 +   Alexa                           ...'upstairs siren' ('Fortrezz Siren') - Type: RelayDevice - Subtype: Siren
 +   Alexa                           ...'outlet' - Type: RelayDevice - Subtype: Outlet
 +   Alexa                           ...'fan light' ('FanLinc - Light') - Type: DimmerDevice - Subtype: Dimmer
 +   Alexa                           ...'office fan' ('010 - Smart Fan Control (14287)') - Type: DimmerDevice - Subtype: Fan
 +   Alexa                           ...'back door' ('Insteon On/Off') - Type: RelayDevice - Subtype: Lock
 +   Alexa                           ...'automatic door' - Type: RelayDevice - Subtype: Door Controller
 +   Alexa                           ...'Office Siren' - Type: RelayDevice - Subtype: Siren
 +   Alexa                           ...'thermostat' ('Insteon Thermostat') - Type: ThermostatDevice - Subtype: None
 +   Alexa                           ...'blinds' ('038 - Lamp Module (AD130)') - Type: DimmerDevice - Subtype: Blind
 +   Alexa                           ...'office lamp' ('016 - Plug-In Appliance Module (ZL-PA-100)') - Type: RelayDevice - Subtype: Plug-In
 +   Alexa                           ...'office bulb' ('Hue Bulb') - Type: RelayDevice - Subtype: Plug-In
 +   Alexa                           ...'strobe' ('Fortrezz Strobe') - Type: RelayDevice - Subtype: Plug-In
 +   Alexa                           ...'garage door' ('Kasa Plug') - Type: RelayDevice - Subtype: Garage Controller
 +   Alexa                           ...'outside lights' ('Outdoor Appliance Module (45604)') - Type: RelayDevice - Subtype: Plug-In
 +   Alexa                           ...'valve' ('Insteon Dimmer') - Type: DimmerDevice - Subtype: Valve
 +   Alexa                           Found 17 devices to publish, replying
 +
 +=== Command Requests from Alexa ===
 +
 +When an Alexa command is received, you will see something similar to this in the Event Log:
 +
 +   Alexa                           turning on 'Hue Bulb'
 +   Sent Hue Lights                 "Hue Bulb" on to 100 at ramp rate 2.0 sec.
 +
 +This will allow you to easily see that the change was the result of an Alexa request. This will show for every change that the Alexa plugin makes.
 +
 +===== Migrating from the Alexa Hue Bridge plugin =====
 +
 +If you are using the Alexa-Hue Bridge plugin, you will definitely want to read through this section.
 +
 +We know there are users that have relied on the Alexa-Hue Bridge plugin even though it requires Echo hardware that is no longer available. It was a great stop-gap and we really appreciate everyone who contributed to maintaining it through the years, particularly forum user @Autolog.
 +
 +If you are migrating, we highly recommend that you do a full switch rather than try to use both while switching. While it's possible to use both, doing a full switch will help you avoid a variety of issues, including Alexa caching, device name conflicts, etc.
 +
 +=== Full Switch ===
 +
 +Doing a full switch is pretty simple, just follow these steps:
 +
 +  - Disable the Alexa-Hue Bridge plugin.
 +  - In the [[https://alexa.amazon.com/spa/index.html#appliances|Alexa web site]], remove all devices. The simplest way is to click the ''**Remove All**'' button at the bottom. Note, if you are using other smart home skills, using that button will also cause those devices to be forgotten, so when you do a discover later you'll need to perform any steps needed to make discover work on for that skill.
 +  - In Indigo, follow the directions above in the [[indigo_2022.1_documentation:plugins:alexa#making_a_device_available_in_alexa|Making a Device Available in Alexa]] to publish your devices.
 +  - Once you have all your devices published, you can confirm that they are all published by selecting the ''**Plugins->Alexa->Show Device Publications**'' menu item and it will print the list of publications in the Event Log window.
 +  - In the Alexa app, website, or using an Alexa enabled device, click/touch the Discover button or say "discover devices".
 +
 +This should make all of your devices available in Alexa. Whenever you ask an Alexa device to discover, you will see the following Event Log line followed by a summary of publications:
 +
 +<code>   Alexa                           Alexa discovery request received, assembling reply...</code>
 +
 +=== Partial Switch ===
 +
 +If you want to attempt to switch one at a time, the process is more complicated and somewhat error-prone. The general process is:
 +
 +  - Disable the device from the Alexa-Hue Bridge plugin (see [[https://github.com/IndigoDomotics/alexa-hue-bridge/wiki|the docs for the plugin]] for details). This is very critical in order to avoid complications/confusion later.
 +  - In the [[https://alexa.amazon.com/spa/index.html#appliances|Alexa web site]], remove that specific device.
 +  - In Indigo, follow the directions above in the [[indigo_2022.1_documentation:plugins:alexa#making_a_device_available_in_alexa|Making a Device Available in Alexa]] to publish your device. Be sure to confirm/select the appropriate subtype.
 +  - In the Alexa app, website, or using an Alexa enabled device, click/touch the Discover button or say "discover devices".
 +
 +Hopefully, Alexa will find your device and it will work properly. Unfortunately, sometimes that doesn't work. We believe that there are some caching issues within the Alexa environment where removing a device doesn't fully remove a device. If you experience this, you may need to remove the device again and wait a while before rerunning discovery. It may even require that you disable the Alexa plugin, rerun discovery, then enabling the Alexa plugin, and running discovery again. We haven't been able to find the silver bullet for this so it's a bit of trial and error.
 +
 +
 +===== Alexa Troubleshooting =====
 +
 +Because this integration is made up of a variety of parts, and because Alexa itself can talk to multiple smart home skills as well as allow the definition of custom "routines", there are a variety of places where things can go wrong. This section will hopefully cover many of those scenarios.
 +
 +If you don't find an answer to your problem in this section, post a detailed description of your issue and the steps you have taken (and any relevant Event Log entries) to the [[https://forums.indigodomo.com/viewforum.php?f=359|Alexa plugin support forum]].
 +
 +==== Device Caching ====
 +
 +The first and foremost issue that users experience with Alexa, device discovery and device changes, is that Amazon caches device definitions, and any changes (additions, changes, deletions) may take minutes to complete. Sometimes the changes don't propagate throughout their various caches at all.
 +
 +So, when making any changes, it's always a good idea to wait for maybe 10 minutes between any changes that you make. For instance, if you change the name of a device, run discovery as advised below, but wait for 10 minutes before looking for the change in the Alexa app or trying to control the device using the new name.
 +
 +Usually, when adding a new device, it happens pretty quickly. However, not always, and especially if it's combined with a change in another device. This seems not only to slowly propagate the change, but also slow the addition of a new device.
 +
 +If you want to delete a device (or all devices to start over), this seems to be the most problematic scenario for their caching scheme. You will want to wait 10 minutes to make sure that the deletion actually occurs before doing anything else. Users have reported that doing a Remove All from the Alexa website will continually fail and that the way to accomplish it is to delete a few at a time. While we haven't confirmed this behavior, it would not surprise us given all the caching issues we've experienced and read about.
 +==== Account Linking Issues ====
 +
 +When you enable the Indigo Smart Home Skill in the Alexa app, you're required to link it to a [[https://www.indigodomo.com/account/codes|license in your Indigo Account]]. You'll automatically be forwarded to the login page for your Indigo Account: log in using your normal credentials. You will then be forwarded to the skill authorization page which will have a popup that contains all of your licenses. Most users will only have a single license, but some will have multiple. You can only control a single Indigo Server from any given Alexa account.
 +
 +If you see an error page saying that you don't have any available licenses, this could be a result of a couple of things:
 +
 +  - You have previously linked your license to Alexa but haven't revoked it on the [[https://www.indigodomo.com/account/authorizations|Authorizations page in your Indigo Account]]. This may happen if you disable the Indigo Skill then attempt to re-enable it. Click on the Revoke button next to the Alexa authorization for your license to revoke the authorization then try linking again.
 +  - Your Indigo Up-to-Date subscription has expired. To use Alexa (and similar types of integrations), you need to have an active Indigo Up-to-Date subscription and your reflector must be active.
 +  - Your Indigo License doesn't have an active/working Indigo Reflector (included with your UTD subscription).  To use Alexa (and similar types of integrations), you need to have an active Indigo Up-to-Date subscription and [[https://www.indigodomo.com/docs/reflectors|your reflector must be active]].
 +
 +==== Changing a Published Device in Indigo ====
 +=== Changing the Indigo Name ===
 +
 +If you specified an alternate name for a device when publishing it, then changing the Indigo name won't make any difference and you won't need to do anything.
 +
 +If, however, you didn't specify an alternate name, then Indigo will use the Indigo device name. If you change it, then you will need to rerun discovery in the Alexa app or on an Alexa-enabled device. If discovering by voice command, Alexa will say that it couldn't find any new devices (which is technically correct), but the device will now respond to the new name.
 +
 +If it doesn't then the most likely scenario is that the new name conflicts with another device Alexa knows about. Check the list of devices in the Alexa app to ensure that there isn't a duplicate name. Also, when you check the list, make sure that the old device name is no longer in the list. If it is, confirm that you changed the name (and that you didn't specify an alternate name) then rerun discovery.
 +
 +Also, remember our discussion of device caches above: give Alexa at least 10 minutes for changes to propagate throughout their device caches.
 +
 +If you've made a change and waited and it's still not responding, one other possibility is that you have a routine defined in Alexa with the name or a similar name - that may cause conflicts when Alexa attempts to determine what it is you're asking.
 +=== Changing the Alternate (Alexa) Name ===
 +
 +If you change the alternate name, you will need to rerun discovery. If the new name doesn't work, try the troubleshooting tips in the [[indigo_2022.1_documentation:plugins:alexa#changing_the_indigo_name|Changing the Indigo Name]] section just above this one.
 +=== Changing the Device Type ===
 +
 +If you edit a device and change the type, protocol, or anything that changes the nature of the device, you will most likely want to follow this procedure:
 +
 +  - In the Alexa app, remove the device.
 +  - Go back to the [[indigo_2022.1_documentation:plugins:alexa#making_a_device_available_in_alexa|Publication Dialog]], select the device, and make sure that you are satisfied with the subtype (or change it as necessary).
 +  - Save any changes.
 +  - Rerun discovery in Alexa.
 +
 +It should say that it has found a new device (since you deleted it first) and you should now be able to control it based on the new type. Note that changing protocol might not require the process above (an Indigo dimmer device works the same no matter the protocol), but we have found that Alexa caches information about devices and just doing a discover after changing may not be enough to force Alexa to reset the device cache.
 +
 +==== General Issues ====
 +
 +Alexa uses some sophisticated caching mechanisms throughout their hosted systems in order to optimize performance/responsiveness. Unfortunately, sometimes that caching mechanism can lead to odd and misleading issues. Sometimes when you make changes (initial publishing, updating, removing publications) it can take a while for the change to propagate throughout their systems. The Indigo skill, which is hosted by Amazon (a requirement), does no caching of devices. The Alexa plugin does some local caching, but that has nothing to do with how Alexa interprets what you say and converts it into the command it sends to the plugin.
 +
 +The very first thing you want to check when troubleshooting any Alexa issues is the Event Log window. You will see various warnings and errors that will help you determine if there are issues. Those errors may help you to determine where to go next. First, ensure the following:
 +
 +  - Make sure that you have [[indigo_2022.1_documentation:plugins:alexa#smart_home_skill|enabled the Indigo Skill and linked it to your Indigo Account & license]] successfully
 +  - Make sure that your [[https://www.indigodomo.com/account/codes/|Indigo Up-to-Date subscription is active]].
 +  - Ensure that your Indigo Reflector is configured and connected. Check this by hitting your reflector URL in a browser: https://YOURREFLECTORNAME.indigodomo.net/
 +
 +Here are a few things to help you diagnose issues.
 +
 +=== Alexa can't find a device ===
 +
 +  - Make sure that you have [[indigo_2022.1_documentation:plugins:alexa#smart_home_skill|enabled the Indigo Skill and linked it to your Indigo Account]] & license successfully
 +  - Watch the Event Log window for [[indigo_2022.1_documentation:plugins:alexa#discovery_requests_from_alexa|discovery requests]]
 +    * If you don't see any discovery requests:
 +      * Make sure that your reflector is up and running
 +      * Make sure your Indigo Up-to-Date subscription hasn't lapsed
 +      * Make sure you have OAuth enabled in the [[indigo_2022.1_documentation:getting_started:#starting_indigo_server|Start Local Server dialog]]
 +
 +    * If you see a discovery request:
 +      * Make sure that the device you are publishing is in the list. Take note of the names of your published devices to ensure that they are unique - if you publish two devices with the same name Alexa will ignore or both of them.
 +      * If the above step is fine, then make sure that you aren't using a name that's used by a device in some other smart home skill (some users use the Hue skill to directly control Hue lights, if you have the Alexa-Hue Bridge plugin enabled that may also be publishing a device with the same name).
 +      * Make sure that you are giving Alexa enough time to update its caches - 10 minutes after a discovery is the recommended wait time.
 +    * If you have a slow or unreliable internet connection, Alexa can timeout a request rather quickly and will speak some error message. If you see inconsistent behavior, this may be a hint that there is some kind of internet connection issue between the Alexa hosted servers and your Indigo Server (see below for more details).
 +
 +=== Alexa can't control a device ===
 +
 +Some steps to try when Alexa says it can't find a device:
 +
 +  - Make sure you are clearly saying the device name. Alexa can sometimes hear something slightly different than what you're saying.
 +  - Make sure you have the device published in the plugin. You can do this by selecting the ''**Plugins->Alexa->Show Device Publications**'' menu item. Verify that you are saying the name that is published to Alexa if it's different than the name of the device in Indigo.
 +  - Rerun discovery from the Alexa app for an Alexa device.
 +  - Look in the Event Log window for errors when trying to control the device.
 +
 +=== Alexa can't speak a variable value ===
 +
 +Some steps to try when Alexa has a problem speaking the value of a variable:
 +
 +  - Make sure that the value doesn't contain any [[https://developer.amazon.com/en-US/docs/alexa/custom-skills/speech-synthesis-markup-language-ssml-reference.html|SSML markup]] symbols by themselves, like <, >, /, etc. Alexa will just throw a very unhelpful error (//"Sorry, I'm having trouble accessing your Indigo Skills skill right now"//) when it thinks that the string contains malformed SSML.
 +  - Make sure that the value of the variable is less than 8000 characters - that's the speech output limit for Alexa.
 +
 +=== Alexa can't speak the variable list ===
 +
 +Some steps to try when Alexa has a problem speaking the variable list:
 +
 +  - If you have too many variables, you may get the error //“There is a problem with the requested skill response”//. The issue is that the speech output sent to Alexa can't be longer than 8000 characters, so if you have a lot of variables or lots of variables with long names you may run into this situation. The next release of the plugin will only speak variables that have the "Remote Display" flag set for them, so you will be able to exclude variables using that mechanism without deleting them.
 +
 +=== Alexa can't speak the variable of a variable ===
 +
 +If the value of your variable contains an ampersand (&) or perhaps other special characters, you should replace them with the actual english word (and). Alternately, you can probably HTML encode the character as well (&amp;).
 +
 +=== Alexa says there are issues when you try various things ===
 +
 +Alexa skills are hosted on their servers, and must communicate with your Indigo server through your reflector. If you have a poor internet connection, you may see some odd issues: not being able to discover, errors when you ask Indigo for things even though it appears on the Indigo side that they have happened, etc. Their API is very picky about response times, as slow response times is a poor user experience. This does mean, however, that anyone with slow connections (Satellite) or unreliable internet connections will experience various error messages from Alexa. Unfortunately, there is nothing we can do about this issue.
 +
 +=== If All Else Fails ====
 +If every other troubleshooting step has been taken and you have multiple Indigo licenses, contact support (mentioning that you have multiple licenses) so we can more quickly determine if this is related to your problem.