usage
Create an emulated Hue Bridge by creating a new Indigo device:
New... > Type: Alexa-Hue Bridge, Model: Emulated Hue Bridge
See the ** Migration from Version 2 ** section for a description of Version 2 -> Version 3 migration.
-
Port
Default is Auto or specify a port. Normally leave as Auto and the plugin will select a port inthe range 8178 thru 8200 and will start from 8178. Once a port had been allocated the device properties will be updated with the allocated value and the port will assigned as the device's address. This can be subsequently changed if desired.
-
Auto Start
Tick this check box to automatically start discovery on Device start. If not ticked, diiscovery will be off.
-
Auto Start Discovery Expiration
This is for how long the auto-start discovery process will broadcast and Alexa devices will find Indigo devices when you say "Alexa, discover devices". It must be a whole number from 1 to 10 minutes or if you specify 'Discovery Permanently On', once auto-started, discovery will run until you explicitly stop it. You can start and stop discovery broadcasting by turning the Alexa-Hue Bridge device 'on' and 'off'. While discovery is running, other apps on your Mac may not be able to use UPNP. See later section for further detail on discovery.
-
Disable Alexa (by Variable)
If you want to disable Alexa commands from being able to control any devices or actions defined by this Alexa-Hue Bridge, select a pre-defined "Disable Alexa" variable that must have been previously set to 'false' (allow Alexa commands) or 'true' (disable Alexa commands). The plugin will check this variable and depending on its setting either enable or disable Alexa commands being actioned for this Alexa-Hue Bridge.
-
Hide
Hide Alexa Command ignored messages when the Disable Alexa variable is true (disable Alexa commands).
-
Allocated Alexa Names
The Assigned Alexa names menu can be used to check if the name is already assigned as an Alexa device.
The menu contains a list of all the Alexa names defined across all the Alexa_hue Bridge devices. These are shown in alphabetical order and are used to check for duplicate names which will be rejected if spotted (as Alexa doesn't like duplicate names!). Select the Alexa name to get further details. This will indicate which Alexa-Hue Bridge the Alexa Device is assigned to. In addition it will either show the associated Indigo device (see image above) or associated Indigo Actions and Variables. The Indigo Hash Key is the key used by Alexa to reference the relevant Device or Actions when a command is issued to Indigo.
-
Alexa Option
To add a new Alexa Device select -- Add New Alexa Device -- or select an existing Alexa Device from the list to update it.
-
New Alexa Device Name
If adding a new Alexa Device, enter the name that you want Alexa to respond to. If you are going to associate this new Alexa Device with an Indigo Device, you can leave the field blank and the plugin will use the Indigo device name as the Alexa name. Otherwise, if you are going to associate this new Alexa Device with Indigo Actions you have to provide a name. The name field is not allowed to contain a vertical bar character ('|'), a comma character (',') or a semicolon character (';'). You are not allowed to define duplicate Alexa Names (across all Alexa-Hue Bridges) and this will will be flagged as an error
-
Alexa Device Name
If updating an existing Alexa Device, you can enter a revised name that you want Alexa to respond to, otherwise just leave the existing value. The field can't be empty. You are not allowed to define duplicate Alexa Names (across al Alexa-Hue Bridges) and this will will be flagged as an error.
-
Indigo Device or Action(s)?
Select whether you want this Alexa Device to be associated with an Indigo Device or a set of Indigo Actions.
-
Indigo Device
If you selected to associate an Indigo Device, select the required device from this list. If adding a new Alexa Device and the New Alexa Device Name is empty, the Indigo device name will be input in that field.
-
Indigo Action fields
Select the actions and variables you want associated with this Alexa Device. As a minimum, you must specify an action for Indigo ON Action and Indigo OFF Action. You can specify NO ACTION if you don't want the Alexa Device to support dimming. You can assign an Indigo On/Off Action Variable and this variable will be pre-filled with the ON/OFF value returned by Alexa prior to invoking the ON/OFF Action. The value in this variable can therefore be accessed in the ON/OFF Action. You can also assign an Indigo Dim Action Variable and this variable will be pre-filled with the DIM value returned by Alexa prior to invoking the DIM Action. The value in this variable can therefore be accessed in the DIM Action.
-
Add New Alexa Device / Update Alexa Device
When you’re ready to add a new or update an existing Alexa Device, click either the Add New Alexa Device button or Update Alexa Device button. The device will be added into the Published Alexa Devices list (see below). If you try and add more than 20 devices you will get an error message: "You can't publish any more Alexa Devices - you've reached the maximum of 20 imposed by the plugin on behalf of Amazon Alexa."
Note: You must click the Save button to make the changes permanent; see below.
-
Published Alexa Devices
This is the list of devices currently published to this Alexa Hue Bridge (including any just added or updated). There is a limit of 27 devices currently imposed by the Amazon implementation for each bridge. If an Alexa name in the list is associated with an Indigo Device and the names are different, the list will show the Alexa Device name followed by an equals sign and then the associated Indigo Device name. Otherwise if an Alexa name in the list is associated with an Indigo Actions, the list will show the Alexa Device name followed by an equals sign and then ACTIONS
Note: This is the opposite way to how Version 2 of the plugin displayed the list.
-
Delete Devices
Select one or more devices from the Published Alexa Devices list and click the Delete Device(s) button. Note: You must click the Save button to make the changes permanent; see below.
-
Save
Once you’re finished adding/editing/deleting published devices, click the Save button to make the changes permanent. Click the Cancel button to discard all changes.
Note: The New Alexa Device Name / Alexa Device Name must be empty to be able to save. This is to avoid any loss of data i.e. you have entered new or updated Alexa Device details and have forgotten to do the add or update. If this occurs, you will get the following error, e.g. for a new Alexa Device:
Note: From version 3.0.10 onwards, the plugin has reduced the limit of Alexa Devices per Alexa-Hue Bridge to 20. If you have an existing Alexa-Hue Bridge (pre 3.0.10) and you edit it with with more than 20 devices you will get a warning.
'Alexa-Hue Bridge 1' updated and now has 25 Alexa Devices published [LIMIT OF 20 DEVICES EXCEEDED - DISCOVERY MAY NOT WORK!!!] Move excess Alexa devices to another existing or new Alexa-Hue Bridge
You will not be able to add any more devices to the Alexa-Hue bridge and should reduce the number of Alexa devices to 20 or less.
At this point, the plugin knows about the devices, but Alexa doesn’t. You need to tell Alexa to discover devices. By default, you can just tell Alexa to discover your devices either by saying that or by using the Alexa app.
Saying to Alexa "Alexa discover devices" appears to be more reliable than using the Alexa App to discover devices - Your mileage may vary. :)
If you enabled Log Discovery in the plugin configuration, you will now see a series of messages in the Event Log. Alexa will make multiple attempts to discover devices, so you may well see the discovery for each defined Emulated Hue Hub appearing to be repeated.
An example output is like this:
Alexa-Hue Bridge Alexa-Hue Bridge 'Test Hue Bridge Two' responding to Alexa discovery [request id: 1] ... Alexa-Hue Bridge + Publishing device 'Landing Lights' to Alexa Alexa-Hue Bridge ... One device discovered by Alexa on Alexa-Hue Bridge 'Test Hue Bridge Two'. Alexa-Hue Bridge Alexa-Hue Bridge 'Test Hue Bridge Two' responding to Alexa discovery [request id: 2] ... Alexa-Hue Bridge + Publishing device 'Landing Lights' to Alexa Alexa-Hue Bridge ... One device discovered by Alexa on Alexa-Hue Bridge 'Test Hue Bridge Two'. Alexa-Hue Bridge Alexa-Hue Bridge 'Test Hue Bridge One' responding to Alexa discovery [request id: 3] ... Alexa-Hue Bridge + Publishing device 'Testing lamp' to Alexa Alexa-Hue Bridge + Publishing device 'Virtual Camera ' to Alexa Alexa-Hue Bridge + Publishing device 'boiler switch' to Alexa Alexa-Hue Bridge + Publishing device 'macbook lamp' to Alexa Alexa-Hue Bridge ... 4 devices discovered by Alexa on Alexa-Hue Bridge 'Test Hue Bridge One'. Alexa-Hue Bridge Alexa-Hue Bridge 'Test Hue Bridge One' responding to Alexa discovery [request id: 5] ... Alexa-Hue Bridge + Publishing device 'Testing lamp' to Alexa Alexa-Hue Bridge + Publishing device 'Virtual Camera ' to Alexa Alexa-Hue Bridge + Publishing device 'boiler switch' to Alexa Alexa-Hue Bridge + Publishing device 'macbook lamp' to Alexa Alexa-Hue Bridge ... 4 devices discovered by Alexa on Alexa-Hue Bridge 'Test Hue Bridge One'.
In releases prior to Version 2 of the plugin, you needed to specifically start the discovery process i.e. the process in the plugin that will allow Alexa to discover devices when you tell "her" to.
This is now done automatically and it can run forever. Thanks to a comment from another Indigo user, we've added a switch which allows us to open the UPNP response port in a shared mode - so any other app that opens the same port in the same way will also work concurrently.
However, there may be other apps/plugins that don't open the port shared, and those may still require this plugin to not be in discover mode.
The Auto Start Discovery Expiration is defaulted to Discovery Permanently On which means discovery is always on. The status of discovery is shown in the state column of the Indigo device UI. A solid green dot means discovery is always on, a green timer means that it is on for a limited time (1 to 10 minutes), a grey timer means discovery is off.
Discovery can be turned on and off by using the Turn On and Turn Off controls in the UI.
Starting discovery (and stopping it) are also available as actions: As the The Alexa-Hue Bridge is defined to Indigo as a Relay device, the actions are Turn On/Off (Light/Appliance Controls). So you can start (and stop if necessary) discovery from Triggers, Schedules, etc.
A quick description of how discovery works: the Hue Bridge uses a technology called UPNP to broadcast its presence and information about its devices on your local network. This broadcast is what Alexa will look for when performing its device discovery. However, UPNP may be use by other apps and plugins on your Mac (the Sonos plugin uses it also). But different processes on the same Mac can’t run their own UPNP responders unless they open them in a special way. This may be the reason you'd need to stop/start discovery yourself.
You can find out if other plugins or applications have the UPNP port open by doing the following command in a terminal window:
sudo lsof -i :1900
The output will show you any processes (IndigoPluginHost or or otherwise) that have the port open. In order for discovery to work, you may need to temporarily quit those apps. You can start them back up after Alexa has discovered your devices.
That’s basically it. Once Alexa discovers your devices, you can control them with the standard Alexa commands for home automation:
-
Alexa, turn on Media Fan
-
Alexa, dim Office Wall Lamp to 50% (there is no corresponding brighten)
-
Alexa, turn Media Fan off
Alexa’s vocabulary for home automation is currently limited to turn on, turn off, and dim. We’re filtering the device list in the Manage Devices dialog to only show devices that have an on/off state, so things like thermostats and (most) sensors can’t be added. Although now largely superceded by the new Version 3 capability of defining actions, you can also use the Virtual On/Off Device type in the Virtual Devices interface to create your own custom on/off devices that can do pretty much anything you want. For example, you could create a Virtual On/Off Device with an ON action group that sets a thermostat in one way, and the OFF action group would set it another. You could then “turn on” and “turn off” the group to set the thermostat.
We've created a sub-forum on our forums for getting help with the plugin. Start by posting your question there to see if anyone can help before filing an issue here on GitHub. We're not closely monitoring the issues here but are monitoring the forums.
We've noticed that sometimes when we tapped the Discover devices button in the Alexa iOS app and it shows the progress bar, but when it's done Alexa herself says nothing on the Echo (she usually says either she didn't find or found devices). Using the voice command "Alexa, discover devices" when that happened results in an immediate reply that she couldn't and to try later. We've found that a force quit the Alexa app on the iOS device followed by started it back up and hitting the Discover devices button may get it working again.
So, there appears to be a bug with the Alexa iOS app (there are actually quite a few) that can cause discovery to fail, and once it gets into that state a force-quit restart cycle seems to clear it.
The primary issue that users experience is with port conflicts on the UPNP port (1900). Several Mac apps open that port as part of a UPNP process. The plugin only needs to use the port while the Alexa is discovering devices, but during that time other apps may have a problem. This is a list of things users have found on their Macs that use that port. It is by no means an exhaustive list.
-
The Sonos Indigo Plugin
-
The Squeezebox Indigo Plugin
-
MythTV
-
Sighthound Video
-
HDHomeRun
Feel free to add more, or report any other conflicts you find on the forum thread and we'll add it here.
If you want to contribute, just clone the repository in your account, make your changes, and issue a pull request. Make sure that you describe the change you're making thoroughly - this will help the repository managers accept your request more quickly.
We've documented the code fairly well, so please do the same for any changes that you make. This will ensure that future contributors can effectively contribute in the future.
Perceptive Automation (aka Indigo Domotics) is hosting this repository and will do minimal management. Unless a pull request has no description or upon cursory observation has some obvious issue, pull requests will be accepted without any testing by us. We may choose to delegate commit privileges to other users at some point in the future.
We (Perceptive Automation) don't guarantee anything about this plugin - that this plugin works or does what the description above states, so use at your own risk. We will attempt to answer questions about the plugin but given the nature of this plugin, which uses reverse-engineered information provided by other users out on the net, we can’t guarantee that it will always work since either Amazon or Philips can change the protocol at any time.
This plugin is a derivative work from a couple of different sources: the hueAndMe project, which is itself based loosely on work from the hue-upnp project. We’re grateful that these developers published these projects so that we could build upon them.
This project is licensed using Unlicense.
Here's the plugin ID in case you need to programmatically restart the plugin or start/stop discovery:
Plugin ID: com.indigodomo.opensource.alexa-hue-bridge
