Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



6 Commits

Repository files navigation

Hue Bridge Client

An easy-to-use, MicroPython-compatible class to access and control lights on a Philips Hue Bridge.


  • Automatic bridge discovery using the UPnP SSDP protocol
  • Handles developer API username registration for API access
  • Stores bridge IP and username for instant access on restarts
  • Simple methods to get lists of lights and groups
  • Set one or many, light or group state parameters with a single call
  • Works equally well in micropython or python 2.7 and up
  • Easy to extend with new methods to access more bridge functionality


The first time the Bridge class is used, it will discovery the bridge and then initiate the necessary API username registration.

import hue
h = hue.Bridge()

You'll be prompted to press the link button on the Hue Bridge.

Bridge located at
>>> Press link button on Hue bridge to register <<<

If you are using the ESP8266, you'll need to disable the AP WLAN interface for the discovery process to work. This also requires that the STA WLAN (station) interface be connected to the same network as the bridge. Here's how to disable the AP WLAN interface.

import network

Once you've connected to the bridge, you can interact with lights and groups. Individual lights or groups are referenced by an ID number. You can get the list of IDs with the methods getLights and getGroups.

{1: 'Dining room', 2: 'Bedroom', ... , 9: 'Porch', 10: 'Spare bedroom'}

To get details about a specific light our group, use the getLight and getGroup methods.

{u'name': u'Dining 1', u'swversion': u'', u'manufacturername': u'Philips', u'state': {u'on': True, u'reachable': True, u'bri': 200, u'alert': u'none'}, u'uniqueid': u'00:17:88:01:10:40:2c:14-0b', u'type': u'Dimmable light', u'modelid': u'LWB006'}

Here's an example of how to access individual settings from the response:

light = h.getLight(1)

To set light or group state parameters use the setLight and setGroup methods.



Just download the file from this repository and place in a folder with your python code.

More In-Depth Info

If you'd like to know more about the Hue Bridge API, head over to []. You'll need to register as a developer to gain access, which is free.

To access other aspects of the bridge API, use the get() and put() methods. For example, to get bridge configuration along with the current whitelist of usernames, try the folowing:


The methods post() and delete() are not currently implemented, but can be easily added, by modelling them after the get and put methods. These methods are used to change bridge and device configurations.

When first instantiating this class, setup() runs, which locates the bridge's IP address and attempts to get an API username from the bridge. Both of these values will be stored to the file bridge.dat within the current working directory. The next time the Bridge class instantiated, it will load the saved IP and username values automatically. If the bridge changes IP, you can edit the bridge.dat file. It is recommended that you reserve the bridges IP address on your router, so it doesn't hop around. Alternatively, you can force a discover() whenever you connect to the bridge to get its current IP. To do this you'll need to disable autosetup when instantiating the Bridge class. Here's the steps necessary:

h = hue.Bridge(autosetup=False)
h.loadSettings()   #This will load the last known IP and API Username       #Find the bridge's current IP
h.saveSettings()   #Optionally, you can save the updated IP


If you are having trouble with the saved settings and would just like to start fresh, call the reset() method. The IP discovery and username process will take place, and the new settings will be saved.

h = hue.Bridge(autosetup=False)
h.reset()   #Clear saved settings

If you are having get the bridge to respond to commands, enable debug level 2 to get feedback from the method calls.

h = hue.Bridge(debug=2)    #Enable debug output

Be aware that issuing set commands too quickly can lead to the bridge refusing to process the request. Philips suggest that lights be updated no quicker than 10 times per second and groups be updated, at most, once per second. These are just guidelines to follow. It is also best practice to minimize how many state values you change in each call. For instance, once the light is 'on', you can adjust brightness, in successive calls, without setting 'on' again.


An easy-to-use, MicroPython-compatible class to access and control lights on a Philips Hue Bridge.








No releases published


No packages published