Discovery
There are several ways to discover a Hue bridge in a network. This section describes the best practice such that Hue applications operate in a similar manner to provide the best user experience.
Since I "use another method" to "distribute the documentation shown on developers.meethue.com", "these conditions of use must be attached". Hence I am prepending the Terms and Conditions of Use on http://www.developers.meethue.com/documentation/conditions-use as of July 5, 2015:
You are free to develop any kind of application you can imagine with the hue system. There are just a few rules and restrictions you need to keep in mind:
- You may not distribute the documentation shown on developers.meethue.com except by links to the site itself or, if you use another method, these conditions of use must be attached.
- You must use a “devicetype� when creating whitelist entries that contains the name of your application. We want all your apps to work with our API to form a rich ecosystem of interoperable applications, so it is a condition of access to our API documentation that you do not use it to develop or distribute any bridges or devices which interpret the hue API.
- It may happen that working on an app suggests an idea to you for an improvement in the API. If you suggest any improvements to us and we adopt them, they become part of the platform used by everyone, and belong to Philips, you will make no claims in this respect.
- Make sure it is very clear from all you do that your app belongs to you and not to Philips. Do not use any hue or Philips branding trademarks or trade dress or hue or Philips in any logo or graphics. If you receive our hue API developer materials, you cannot claim ownership or IP rights in any improvements of that material or in any of the APIs either with respect to us or to other hue app developers.
- We want you and others to enjoy hue. So please don’t make any applications that are obscene, not compliant with laws and regulations, offensive or discriminatory or that infringe someone else’s rights.
- So, just as a reminder, before you can start having fun, you agree that by using the API provided here to you, you accept these terms of use.
- Have fun.
There are several ways to discover a Hue bridge in a network. This section describes the best practice such that Hue applications operate in a similar manner to provide the best user experience.
Discovering of the bridge is only supported in case the Hue bridge and the 3rd party devices, running the 3rd party application, are located in the same network (logical subnet). All discovery methods to find the bridge should only take place during the first installation of your application or when the application detects that the IP address of the bridge has been changed and the bridge is no longer reachable.
A flowchart of the steps is illustrated at the end of this article, and has the following options to find the bridge:
-
UPnP. The fist step to find the bridge is to make use of UPnP. The Hue bridge has the Simple Service Discovery Protocol (SSDP) part of UPnP implemented. Other parts of UPnP, e.g. withdrawal, are not supported. For information on SSDP visit: http://en.wikipedia.org/wiki/Simple_Service_Discovery_Protocol Best practice is to wait a maximum of 5 seconds for receiving all discovery responses before going forward. If the responses contain “IpBridge�, it is considered to be a Hue bridge, and additional information can be retrieved, which is described below in the "check" subsection. Additionally, it is advised that a user can stop the discovery process whenever they want. An alternative to UPnP is N-UPnP (described below), but it is best to execute both steps in parallel if possible.
-
N-UPnP. The Hue bridge periodically polls the portal, which stores both the external and internal (in the home network) IP of the bridge, plus the MAC address. If the portal has not received the “I’m alive� message from a specific bridge for a longer period it will consider the bridge disconnected. The Hue portal has linked the public IP address of the users network with the MAC address and local IP address of the Hue bridge. In case the 3rd party application runs from the same users network, and as such using the same public IP address, it is possible to retrieve the local IP address visiting the https://www.meethue.com/api/nupnp webpage. This results in a reply with the list of connected bridges in the network. For example when three bridges are found the reply will be similar to:
[{
"id":"001788fffe100491",
"internalipaddress":"192.168.2.23",
"macaddress":"00:17:88:10:04:91",
"name":"Philips Hue"
},
{
"id":"001788fffe09a168",
"internalipaddress":"192.168.88.252"
},
{
"id":"001788fffe16c18f",
"internalipaddress":"192.168.2.20",
"macaddress":"00:17:88:16:c1:8f",
"name":"Philips Hue"
}]
Depending on the firmware release of the Hue bridge the amount of information per Hue bridge can be different, e.g. the second Hue bridge in the reply above, it does not contain the “macaddress� and “name� items. In case of an empty JSON array reply (i.e. [ ]), no Hue bridge has been found. This can be because the user never connected the bridge to the Internet or it has been considered to be disconnected, in that case an option is to perform an "IP scan", or ask the user to enter an IP address of the Hue bridge. Best practice is to wait a maximum of 8 seconds for receiving the N-UPnP repsonse back from the Hue portal before continuing.
-
IP scan. In an IP scan the subnetwork is scanned for devices and every device is scanned to determine if it is a Hue bridge. This can be a time consuming process and should be avoided if possible, e.g. when a bridge has been found by UPnP or N-UPnP. For an IP scan it is advised to use multiple threads in the application, which is for instance possible in an Android application (IP Scan is implemented this way in the Android SDK). The range to scan can be derived from the IP address of the device and the subnet mask set in the device (e.g. 192.168.1.119 and subnet mask 255.255.255.0 or 192.168.1.0/24 for an IPv4 address). As indicated in step 1 it is advised that the user can stop the discovery process at any moment in time. Additionally, it is advised that the full discovery process should not take longer than 30 seconds before indicating that no Hue bridge was found.
-
Manual IP. Actually, this step is not an automatic discovery, but here the option is given to manually enter the IP address of the Hue bridge. Advise should be given to the user to check the IP address of the router, if not found, or in case the Hue bridge is not found on that IP address the user should be notified to check the connection with the Hue bridge, and ask if the second LED (network connection) on the Hue bridge is on.
Check. In case the application gets a non-empty response from the bridge, multiple bridges may have been found. Always validate information from these bridges before giving the user the option to select one bridge from the list for further control. There are two ways to check the connection with the bridge and retrieve some basic information from that bridge. The first and preferred one is part of the UPnP implementation in which the bridge has a XML descriptor file. You can extract XML information from the bridge, by accessing:
http://<bridge ip address>/description.xml
An example response is:
<root xmlns="urn:schemas-upnp-org:device-1-0">
<specVersion>
<major>1</major>
<minor>0</minor>
</specVersion>
<URLBase>http://192.168.1.130:80/</URLBase>
<device>
<deviceType>urn:schemas-upnp-org:device:Basic:1</deviceType>
<friendlyName>Philips hue (192.168.1.130)</friendlyName>
<manufacturer>Royal Philips Electronics</manufacturer>
<manufacturerURL>http://www.philips.com</manufacturerURL>
<modelDescription>Philips hue Personal Wireless Lighting</modelDescription>
<modelName>Philips hue bridge 2012</modelName>
<modelNumber>929000226503</modelNumber>
<modelURL>http://www.meethue.com</modelURL>
<serialNumber>001788102201</serialNumber>
<UDN>uuid:2f402f80-da50-11e1-9b23-001788102201</UDN>
<presentationURL>index.html</presentationURL>
<iconList>
<icon>
<mimetype>image/png</mimetype>
<height>48</height>
<width>48</width>
<depth>24</depth>
<url>hue_logo_0.png</url>
</icon>
<icon>
<mimetype>image/png</mimetype>
<height>120</height>
<width>120</width>
<depth>24</depth>
<url>hue_logo_3.png</url>
</icon>
</iconList>
</device>
</root>
The application can verify from the description that it is a Philips Hue system. In the description.xml a link to icons are available, which could be used to illustrate the discovered Hue bridges in the application. These icons are stored on the Hue bridge, e.g. http:///hue_logo_0.png.
Another option is to read the configuration information from the bridge by using a RESTful request. It is not necessary to authenticate the application with the bridge. This can be executed by sending a GET request to http://<bridge ip address>/api/<username>/config
username can be kept empty or a name which is not yet whitelisted. This will result in a response similar to:
[{
"swversion":"01008227",
"apiversion":"1.2.1",
"name":"Smartbridge 1",
"mac":"01:23:45:67:89:ab",
}]
The response can be different depending on the firmware release of the Hue bridge. In case of multiple bridges detected in the application, it is best to list the found bridges for the user to select one. In case of a single bridge found, the application should continue using the found IP address and go forward with authorising access to the Hue bridge by the application.
The application should store the linked IP address for further usage, and check every time when it is restarted if this bridge is still responding, so that the discovery and authentication process is not required everytime the application starts, resulting in a better user experience.
A possible flowchart is illustrated below. An optimisation could be to execute UPnP and N-UPnP discovery methods ion parallel. It is best to execute an IP scan only when the other methods don’t return in a positive response (i.e a hue bridge). The IP scan can be “heavy� in terms of processing power.
