ISY Portal Amazon Echo Integration

From Universal Devices, Inc. Wiki
Jump to: navigation, search

Please follow the instructions here to setup Echo to work with your ISY:

Short Video Tutorial

ISY Portal/Amazon Echo Video Tutorial

Instructions for Accessing ISY Portal

Please make sure you have ISY Portal Installed and Configured first.

Important Information

  • Smart Home API is now on V2 and V1 will be obsolete and non-functional by 08-01-2016. If you are still on V1, please follow the instructions Instructions for Migrating from V1 to V2 below
  • You need to follow the instructions under Instructions for Smart Home API below
  • Amazon Echo Connected API currently only supports on/off devices, thermostats, programs, and scenes
  • For programs, turn on/off <program name>:
    • On: runs the Then
    • Off: runs the Else
  • Currently, for door locks, you can either use programs or use Skills (video tutorial below)

Instructions for Migrating from V1 to V2

  • Login to the Echo app
  • Click on the Smart Home menu item on the left navigation bar
  • Look for ISY Optimized for Smart Home and then click on the Disable button
  • Click on Get More Smart Home Skills
  • Search for ISY
  • Click the Enable button next to ISY Optimized for Smart Home V2
  • Click on the Smart Home menu item on the left navigation bar again make sure ISY Optimized for Smart Home V2 shows up under Your Smart Home Skills
  • Click on Forget all devices and groups
  • Click on Discover Devices. This will bring in all the devices you have created a mapping for in your ISY Portal


Instructions for Smart Home API

  1. Make sure you have followed all the steps in In Instructions for Accessing ISY Portal above
  2. Log into ISY Portal (my.isy.io), click on My Profile at the top right corner
  3. Choose your ISY from Preferred ISY drop down
  4. Click on Link this profile to an Amazon account
  5. Under Select Tool choose Connectivity | Amazon Echo and enter mappings between your devices, scenes, programs, and state variables to their associated and desired spoken names
  6. Login to the Echo app
  7. Click on the Smart Home menu item on the left navigation bar
  8. Under Your Smart Home Skills, click on Get More Smart Home Skills
  9. Search for ISY
  10. Click the Enable button next to ISY Optimized for Smart Home V2
  11. Click on the Smart Home menu item on the left navigation bar again make sure ISY Optimized for Smart Home shows up under Your Smart Home Skills
  12. Click on Discover Devices. This will bring in all the devices you have created a mapping for in your ISY Portal
  13. Please note that every time you change spoken fields, you must redo the previous step
    1. Discover: “Alexa, discover my devices” - refreshes the devices, scenes, programs, and state variables from the ISY Portal

Supported Commands

  • For Devices:
    • Turn On: “Alexa, turn on the kitchen light”
    • Turn Off: “Alexa, turn off the kitchen light”
    • Brighten: “Alexa, brighten the kitchen light”
    • Dim: “Alexa, dim the kitchen light”
    • Set: “Alexa, set the kitchen light to 50%”
  • For Thermostats only the following commands may be used:
    • Set [device] temperature to [##] degrees: "Alexa, set bedroom to 75 degrees"
    • Increase the [device] temperature: "Alexa, increase the bedroom temperature"
    • Decrease the [device] temperature: "Alexa, decrease the family room temperature"
    • Turn off [device]: "Alexa, turn off kitchen"
    • What is
      • "Alexa, what is the temperature of kitchen thermostat?"
      • "Alexa, what is the kitchen thermostat set to?"
    • Please see Thermostat Operations Through Echo for more details on how thermostats behave based on the given instructions
  • For Door locks only the following commands may be used:
    • Is Locked: "Alexa, is front door locked?"
    • Is Unlocked: "Alexa, is front door unlocked?"
    • Lock: "Alexa, lock the front door"
    • Please note that, for security reasons, Unlock is not supported
  • For Scenes:
    • Turn On: “Alexa, turn on the kitchen light”
    • Turn Off: “Alexa, turn off the kitchen light”
    • Brighten: “Alexa, brighten the kitchen light” -- will issue brighten command 3 times
    • Dim: “Alexa, dim the kitchen light” -- will issue dim command 3 times
  • For Programs:
    • Turn On: “Alexa, turn on the kitchen light” - runs Then
    • Turn Off: “Alexa, turn off the kitchen light” - runs Else
  • For State Variables:
    • Turn On: “Alexa, turn on X” - Sets the variable X to the <turn on> value (defined in the portal)
    • Turn On: “Alexa, turn on X to Y percent” - Sets the variable X to Y
    • Turn Off: “Alexa, turn off X” - Sets the variable X to the <turn off> value (defined in the portal)
    • Brighten: “Alexa, brighten X” - Increments variable X by 1
    • Brighten: “Alexa, brighten X by Y percent” - Increments variable X by Y
    • Dim: “Alexa, dim X” - Decrements variable X by 1
    • Dim: “Alexa, dim X by Y percent” - Decrements variable X by Y
    • Contrary to regular devices, you can use the same state variables multiple times. This allows you to have 2 different spokens for the same var, but with different turn on values.
    • The word "percent" is optional but recommended. Depending on your spoken and how well you pronounce, the word "percent" may be skipped. But it does facilitate proper recognition if you use it.
    • You can use "increase" and "decrease" instead of brighten and dim. But depending on your spoken and how well you pronounce, increase is often misunderstood as a volume adjustment.
    • You can assign turn on / turn off values with very high values. However, when you set it to a percentage, or use brighten/dim, the value can only be 0-100. For Alexa, it's a percentage after all.

Thermostat Operations Through Echo

A. Turn Off thermostat Thermostat mode is set to Off

B. Set temperature to X If mode is Heat: Set the heat setpoint to X If mode is Cool: Set the cool setpoint to X If mode is Auto

 - If requested temp is closer to current heat setpoint, set heat setpoint to X
 - If requested temp is closer to current cool setpoint, set cool setpoint to X
 - if requested temp is precisely between heat and cool setpoint, then
         - if requested temp is > than current temp, set heat setpoint to X
         - else set cool setpoint to X

If mode is Off

 - If current temp is above X, set to cool at X
 - else, I set to heat at X

C. Increase temperature by X If mode is Heat: Increase heat setpoint by X If mode is Cool: Increase cool setpoint by X If mode is Off: Set to heat at current temp plus X If mode is Off: Set mode to heat with heat setpoint at current temp plus X If mode is Auto

 - Increase both heat and cool setpoint by X

D. Decrease temperature by X If mode is Heat: Decrease heat setpoint by X If mode is Cool: Decrease cool setpoint by X If mode is Off: Set mode to cool with cool setpoint at current temp minus X If mode is Auto

 - Decrease both heat and cool setpoint by X


NOTE: When you are in Auto mode and increase or decrease temperature, Alexa will tell you that it is in Auto mode, aiming for Y

 - Y can be your new cool setpoint, or new heat setpoint. This depends if the current temp is closer to the heat or cool setpoint.
 - Alexa can't report both setpoints.


Instructions for using Multiple ISYs with one Echo Accout

  • The device discovery works only with the preferred ISY. So, if you want to control devices from 2 ISYs, you have to set the preferred ISY to the first ISY, run a device discovery, change the preferred ISY to the second ISY, then discover again.
  • Then, all devices from the 2 ISYs will be available in the echo app.
  • Please note that in the echo app, the devices from the first ISY will be shown as "offline". You can ignore this, the device will work. This just means that this particular device was not reported by the last device discovery, which is normal due to the fact that the device discovery works only with one ISY at a time.


Instructions for using Multiple Echos Smart Home

  • Have your echos tied to 2 different amazon accounts.
  • In the ISY Portal:
    • Login to your main account
    • Create a sub-account using the 2nd email address for your Echo account
    • Logout of your main account
    • Login to the second account using the 2nd email address
    • Add your ISY to this sub-account, and approve access to it in the admin console
    • Create a user profile in this sub-account for the second echo
    • Link this user profile with your second echo's amazon account
    • To edit spokens for your second echo, switch to your sub-account first
    • To edit spokens for your first echo, switch to your main account first

Of course, you can have as many echo as you want, with each their own sub-account, user profile and set of spokens.

Also, it is not required to have a primary echo in the primary account. All echos could be managed in sub-accounts only.

For those of you who already had sub-accounts, you will start with the same spokens in each accounts/sub-accounts for all of your echos. When you add/edit/delete your spokens, the change will be applicable to that account only. Including the Delete all.

NOTE: If your account selector is set to [All], you will see all of your ISYs, no matter which account/sub-account they belong to. When an ISY is in several account/sub-accounts, you will see it only once. When you edit your spokens, without explicitly choosing the account, you can't be sure of the context of which account you are working on. You should switch to the intended account first.

Instructions for Alexa Skill

  • You can use Alexa Skills (tell izzy to <do something> <name>) for thermostats, door locks, programs, and lights
  1. Login to the Echo app
  2. From the menu on the left, choose Skills
  3. Search for ISY or izzy
  4. Click on the Enable button
  • Since Skills use slots to identify patterns, the pattern of the name should be [pre device] [device name] [post device]: