User Tools

Site Tools



Amazon Alexa Bridge

NOTE as of October 2019 Amazon pushed an update to their Alexa devices that broke every single non-cloud based home automation integration system, not just XTension. As of February 2020 there are three potential solutions to this problem since Amazon either wanted to do this or is not interested in fixing it.

  • the simplest solution is to find a generation 1 Echo device on ebay or elsewhere. Note that many that are labeled as such actually aren’t as people don’t really know what they are selling and are re-using descriptions from other similar devices. Please make sure you can identify a version 1 device! It will have the bezel that you can physically turn to change the volume. If if has buttons to adjust the volume then it is not a generation 1 device and will not solve your problem. These gen 1 devices are not eligible for the newer software updates and therefore will not automatically receive the update that breaks everything. Once you have one on your network you can do the discovery for new devices through it and not through one of your newer devices. When that is working all communications to the shared units will go through this older device even if you issue the command from a newer device also on your network. This works without having to make any other changes to your system usually though you may have to re-discover all your units through the new/old device.
  • If you do not require port 80 standard web services on your XTension server you can now run the new Alexa Plugin with Sudo to get around the limitations of the new Amazon software. This is limited to a single instance of the plugin running on the XTension server.
  • If you do require the standard web port on your XTension mac or you need multiple instances of the plugin to share all the units that you wish to then you can run more instances of the plugin on separate machines. This will work from extra Macs or more easily by putting the plugin code onto a Raspberry Pi. See the Alexa On Raspberry Pi page for more info.

With the Alexa Bridge you can control any of your XTension units via voice control through any compatible Amazon Alexa or Echo device. Since this works by pretending to be a phillips hue hub, the Alexa can control your units even without a working internet or cloud connection.

The direct Alexa interface limited to turning things on and off and setting a brightness for them. Each plugin instance is limited to sharing 20 units and/or scripts. If you wish to share more than that number of units create another interface instance and set it up with the remaining units.

The original Bridge was written by Dean Davis of Afterten Software. If you haven’t also checked out his WeatherMan app you should do so. We have a tutorial for getting all your local weather data and forecasts into XTension from that app.

As of XTension version 9.4.12 the Hue Bridge Plugin is included with the main XTension distribution so no other installation is needed.

XTension Setup

Create a new List in XTension and drag up to 20 units into it to be shared.

In the Interface list window click the New interface button and select “Alexa Hue Bridge” from the Device popup. In the server settings enter a unique port number that isn’t in use by any other server process on the server. If you create multiple instances to share more than 20 units they must each have a unique port number.

To setup which devices will be available to the Alexa either leave the default selection of Share Everything, which probably isn’t a good idea unless you only have 3 things in your database, or change to the Limit to selected Objects selection. Then click the Sharing Selection button. From that window you can choose the lists of units and scripts that you wish to share.

Once you’ve selected some items to share and saved the interface, or clicked “Apply,” the shared lists will show an icon in their toolbar that lets you know that they are being shared. The toolbar item will bring up a menu that shows all the interfaces that are sharing that list. If you select the item in the list it will open the edit interface dialog for that interface.

Sharing Scripts

If you choose to share scripts then you can run them by telling Alexa “turn on ’name of the script’” and XTension will run the global script. If you create a handler in the global script called “commandOn” then that will be called as well. If you create a handler called “commandOff” then that will be called when you ask Alexa to turn off the named script. If you do not create the commandOff handler then no action is taken if you try to turn off a script. At this moment there is no way to tell a script to dim to a specific level, only turn on and off.

Setting up Alexa

Once the interface is running and you have selected some items to share getting them into Alexa is easy. From your actual Alexa device you can simple ask her to “find new devices” or from the mobile app click the menu icon and then select “smart home” from the resultant menu. The first selection is to “find new devices” which will do a search that takes about 20 seconds and then all the shared devices should appear. Note that the Alexa and XTension need to be on the same network subnet in order for the discovery process to work. If you have multiple wifi routers and they are not setup properly then they might not be able to find each other.

Once the shared units are listed there you can edit them to change their name if you wish to call them by some more easily remembered name. This will not change the name of the Units or Global Scripts in XTension.

Now you can make voice commands to control devices.

  • Alexa, turn on “unit name“
  • Alexa, turn off “unit name”
  • Alexa, brighten “unit name” to 50%
  • Alexa, turn on “name of shared Global Script“


If you are using an echo plus that has a built in ZigBee hub those devices will not be available to XTension. You can control them via the built in Alexa voice commands of course, but this plugin will not let you control them from XTension. If you wish those ZigBee devices to be controllable both from XTension and Alexa you’ll need a real phillips hue hub, or a Vera or other device to add them to that we support and then share them to Alexa through the bridge.

It is not necessary to disable and re-enable the interface when making changes to what is shared. Simply remove a unit from a shared list and it will disappear from the bridge. You will still have to go into the Alexa app and remove it from your home automation devices tap or Alexa will simply think it’s offline for the moment.

There should be no confusion with making changes to the list of shared objects between XTension and Alexa. If you add or remove a shared object it will not be necessary to remove the entire list of them and re-add them to Alexa. If you’re adding new devices you will need to go back into the home automation setup in Alexa and ask her to discover new devices.

supported_hardware/alexa.txt · Last modified: 2020/02/29 14:58 by James Sentman