Skip to main content

Python API and tooling for Philips Hue.

Project description


Hueber is a fully type-checked Python API for the Philips Hue lighting system. Tooling is also included which enables you to declare update statements (also type-checked) and which can then be safely and efficiently pushed to a Philips Hue Bridge. You are free to use either parts of hueber together or seperately that is up to you (e.g. use the state builder tools with another API).

please note!

That as of now this does not cover the full Philips Hue API and only covers /lights, /groups and /config. It would not take much work to add them but its just not a prioritiy for me now.


  • Python 3.6 (re: static typing annotation)
  • Philips Hue bridge ver2 (I have not tested this with the first generation) connected to your local network

getting started.

Open a REPL and start with instantiating a Bridge() by passing it the local IP address:

>>> hue = Bridge("", "r3aLLy-L0nG-Us3RName-H3r3")
>>> print(Bridge)
Bridge(, xxxxx...-H3r3)


Philip’s providse documenation on how to find your bridge on your network. Please consult their documentation.

From here all your lights and groups are accessible via the Bridge type (I have only shown an abridged version of the output below):

>>> print(hue.lights)
{1: Light(1, Bedroom Dresser, ... ), 5: Light(5, Kitchen Cabinets, ... ) ... }
>>> print(hue.groups)
{1: Group(1, Kid's Bedroom, ...), 3: Group(3, Kitchen, ...) ... }

As you can see above the Bridge.lights and Bridge.groups attributes are a collection. An individual light or group can be accesed via its index which is the ID given to it by the Philips Hue Bridge:

>>> hue.lights[1]  # select light with id 1
Light(1, Coffee Station, Dimmable light)
>>> hue.lights[1].data  # return a dict of all its attributes
{'state': {'on': False, 'bri': 77, 'alert': 'select', 'reachable': True},
'type': 'Dimmable light', 'name': 'Coffee Station', 'modelid': 'LWB014',...

This is all well and good but what if you want to change the state or your light or group? Use the Light-/GroupBuilders to easily construct update strings:

>>> from hueber.lib import LightBuilder
>>> new_update = LightBuilder()
>>> new_update["on"] = True
>>> new_update["bri"] = 254
>>> hue.lights[1].push(new_update.update_str())
[{'success': {'/lights/1/state/on': True}}, {'success': {'/lights/1/state/bri': 254}}]

All *Builder types are just a dict underneath so all of the methods and idioms you use for a dict should be available to a Builder.

going further.

This code is particularly well documented (I think) so please dig into the source if you have any more questions or, if you think something really does need further explanation open an issue and I will do my best to updated the README.


I am happy to accept a pull request, look into the TODO.rst file for gaps or features I am looking to implement down the road. Please make sure any PRs are off of the dev branch otherwise it will just not be accepted and be sure to include your name/handle in the contributors file. Additionally, make sure you run mypy over the project directory.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for hueber, version 0.1.1
Filename, size File type Python version Upload date Hashes
Filename, size hueber-0.1.1.tar.gz (6.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page