Home AutomationHow-To

Managing Philips Hue Bridge Resources

Master the Hue REST API and Clean Up Unused Resources

Austen·

Philips Hue relies on a Zigbee bridge to communicate with and control lights and other Hue devices.

The Hue Bridge is a small computing device consisting of network antennae, a low-power processor and minimal memory and storage capacity. As such, the Bridge is significantly limited in the number of scenes, rules and devices it can support.

As the Hue environment grows and automations are created, it can become necessary to manage available resources. This article provides guidance on how to identify stale rules and remove them using the Hue REST API as well as other management methods.

See Also

Use the Table of Contents in the sidebar to navigate this post.

Skip to “Using the REST API to Manage Resources”

About the Hue Bridge

The Hue Bridge stores the configuration information for every light, sensor, rule and routine in the Hue environment.

The official Hue app, third party apps and voice assistants all interact with the lights via the Bridge, which listens for REST API commands from the IP network and passes them to Hue devices via the Zigbee network.

ℹ️ // Smart Home Networks

IP Networks

An IP Network is a computer network that uses the Internet Protocol to send and receive messages between one or more computers. Local Area Networks (LANs) and the Internet are both examples of IP Networks.

The Hue Bridge is a small computer attached to your network router. It has an IP address that is accessible from other devices in the same the LAN. External network access (over the Internet) can be enabled in the Hue App.

Zigbee Networks

Zigbee is a network specification that defines high level communication protocols to create networks between devices with small, low-power radios. Zigbee is commonly used by smart home devices for low-power and low-latency communication.

Hue bulbs and sensors are connected together in a Zigbee mesh network. The Hue Bridge enables communication within the Zigbee network to control Hue devices.

Hue Bridge Technical Specs

Signify does not share the technical specifications of the Philips Hue Bridge, but curious engineers have uncovered the details.

SoC / ISPQualcomm QCA4531-BL3A SoC/ISP, “Low-power Linux connectivity hub for IoE”
MemoryWinbond W9751G6KB — 8M x 4 banks x 16-bit DDR2 SDRAM
CPUMIPS 24Kc processor clocked at 650 MHz
Source: R. X. Seger

Resource Limits

Given these limited specs, Philips Hue recommends the following limits to ensure the Bridge is responsive to commands.

ResourceDescriptionLimit
LightsRefers to any light-generating device. The bridge will support up to 63 lights, but performance is impacted if there are more than 50.
This limit is in addition to the sensor limit.		50 Lights
SensorsRefers to switches (such as the Dimmer), motion sensors and other non-bulb Hue devices as well as software-based sensors like routines and timers.
This limit is in addition to the bulb limit.		12 Accessories
All Zigbee DevicesThe absolute limit on lights and accessories.126 Devices
ScenesThe total number of scenes that can be configured on the bridge.200 Scenes
GroupsGroups are represented as rooms and zones in the Hue App. Groups can also be created for use in automations.64 Groups
RulesRules consist of “conditions” and “actions”. Rules are used for switches to trigger an action when a button is pressed.200 Rules
Source: Philips Hue Developers – Application Design Guidance (free login required)

‼️ // Exceeding Limits

Some of the limits listed in the documentation are soft limits, meaning they can be exceeded.

Exceeding the soft limit defined in the Philips Hue documentation can cause significant impacts to system performance and should be avoided.

Managing Resources

There are two primary methods for managing the existing configuration of the Bridge.

Hue Labs: A Blunt Instrument

Besides adding and deleting routines, scenes and other elements using the Hue app, Philips enables direct editing of resources via Hue Labs.

Hue Labs is a web portal which allows users to install “formulas” for advanced lighting effects. Formulas use a lot of resources on the Bridge, making it necessary to manage space.

To access Hue Labs:

  1. Navigate to https://labs.meethue.com/ or;
  2. Open the Hue app, tap “Explore” and tap “Hue Labs”

The Hue Labs portal gives two main options for cleaning up the Bridge.

  • Cleanup: This option will completely remove all devices and configurations on the Bridge.
  • Manage Resources: This option allows users to browse the existing configuration and delete specific resources.

⚠️ // Warning

Any changes made using Hue Labs are considered destructive and cannot be undone.

Hue Labs does not make it clear which rules are active or recently used. Deleting a rule with this method may have unintended consequences.

Hue Labs does show “last used” timers for sensors. However, deleting an ‘old’ sensor that is linked to a recently used sensor may have unintended consequences.

To manage Bridge resources using Hue Labs:

  1. Open Hue Labs
  2. Tap “Settings”
  3. Tap “Cleanup” to wipe the Bridge; or tap “Manage Resources” to make individual changes
  4. Tap a category to review
  5. Tap the “Delete” button to remove the resource

One nice thing about the Hue Labs portal is that it displays the remaining available space for resources. This can help you make decisions on which resources should be cleaned up.

Unfortunately, Hue Labs does not always make it clear when you are choosing to delete a resource that is actively used. I used the Hue Labs portal to delete some sensors that had not been used in over six months. This completely wiped the configuration of several of my Hue Dimmer Switches.

REST API: Surgical Precision

The Philips Hue REST API is a robust tool that enables direct interaction with the Hue Bridge. Compared to the hammer-like abilities of the Hue Labs resource management tool, the Hue REST API is a scalpel enabling you to make specific, informed decisions.

ℹ️ // REST APIs

An application programming interface, or API, is a software interface that defines interactions between different software services.

Representational State Transfer, or REST APIs, enable developer interactions using HTTP methods (GET, PUT, POST, and DELETE) to tell the end software what to do.

Using the Hue API, users can list resources, review every detail and dependency, and make surgical edits to the configuration.

See Also

Identify and Delete Unused Resources:

The following are recommended procedures for managing the following resources:

These procedures can be adapted for any other resources on the Bridge.

Managing Rules:

  1. Using your preferred REST API client, query the Hue Bridge IP for the list of rules using GET.
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/rules/
  • If the request is successful, you will get a return message with status code 200 (“OK”) and a list of rules.
  1. Review the list of rules, paying extra attention to the “lasttriggered” keys.
  2. If you find a rule that has not been used in some time, use the GET method to list the details of that rule by appending the rule ID to your previous GET request.

    In this example, rule 41 has not been used at all. Additionally, we see the “status” key has the value “resourcedeleted”.
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/rules/41
{
     "name": "L_04_QqDhg_Start",
     "owner": "42605c21-2f05-478d-a5d9-d3dadb0fcce3",
     "created": "2018-03-14T12:33:19",
     "lasttriggered": "none",
     "timestriggered": 0,
     "status": "resourcedeleted",
     "recycle": true,
     "conditions": [{
         "address": "/sensors/18/state/flag",
         "operator": "eq",
         "value": "true"
     }],
     "actions": [{
         "address": "/groups/4/action",
         "method": "PUT",
         "body": {
             "scene": "1miT4hlOPqeBKas"
         }
     }, {
         "address": "/groups/5/action",
         "method": "PUT",
         "body": {
             "scene": "1miT4hlOPqeBKas"
         }
     }, {
         "address": "/schedules/7",
         "method": "PUT",
         "body": {
             "status": "enabled"
         }
     }, {
         "address": "/sensors/18/state",
         "method": "PUT",
         "body": {
             "flag": false
         }
     }]
 }
  • Rules come in two parts: “conditions” and “actions”
  • This rule is looking at sensor 18 for the sensor flag to be “true”. That is the condition.
  • When the condition is met, this rule will perform 4 actions.

ℹ️ // Tip

Save the JSON output as a backup for later use. The JSON output can be used to recreate the rule using PUT if you make a mistake.

  1. To confirm that this rule is not used and is safe to be removed, look at the sensor it is attached to by querying the sensor ID with GET
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/sensors/18
{
     "error": {
         "type": 3,
         "address": "/sensors/18",
         "description": "resource, /sensors/18, not available"
     }
 }
  • Sensor 18 does not exist, so this means that rule 41 is completely useless.
  1. Delete the rule using the DELETE method:

⚠️ // Warning

This process is destructive. Proceed with caution.

DELETE http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/rules/41
{
  "success": "/rules/41 deleted"
}
  1. Repeat these steps to clean up any remaining excess rules.

Managing Sensors:

  1. Query the Hue Bridge IP for the list of sensors using GET
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/sensors/
  • If the request is successful, you will get a return message with status code 200 (“OK”) and a list of sensors.
  1. Review the list of sensors, paying extra attention to the “lastupdated” keys.
  2. If you find a sensor that has not been used in some time, use the GET method to list the details of the sensor by appending the ID to your previous GET request.

    In this example, sensor 145 has not been used in 8 months.
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/sensors/145
 {
     "state": {
         "status": 1,
         "lastupdated": "2020-04-23T01:27:07"
     },
     "config": {
         "on": true,
         "reachable": true
     },
     "name": "cycling",
     "type": "CLIPGenericStatus",
     "modelid": "HUELABSENUM",
     "manufacturername": "Philips",
     "swversion": "1.0",
     "uniqueid": "2:0:8640-62b8-4b5b-9faf",
     "recycle": true
 }
  • Sensors include a variety of devices and virtual buttons, including Hue Dimmer Switches and Hue Labs Formula toggles.
  • This sensor is a virtual button that triggers a Hue Labs Formula. Note the “modelid” key with value “HUELABSENUM”
  • I have deleted all of my Hue Labs Formulas, but this sensor remains.

ℹ️ // Tip

To confirm the sensor is safe to remove, review the rules on the bridge for any conditions or actions that reference this sensor.

  1. If you are sure that the sensor is unused, delete it using the DELETE method:

⚠️ // Warning

This process is destructive. Proceed with caution.

DELETE http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/sensors/145
{
  "success": "/sensors/145 deleted"
}
  1. Repeat these steps to clean up any remaining sensors.

Managing Scenes:

  1. Query the Hue Bridge IP for the list of scenes using GET.
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/scenes/
  1. Review the list of scenes, paying extra attention to the “lastupdated” and “name” keys.
    Identifying unused scenes can be difficult. It may be helpful to compare the scenes you identify with the scenes displayed in the app.
  2. If you find a scene that you do not recognize, use the GET method to list the details of the scene by appending the ID to your previous GET request.

    In this example, scene ‘DfztBV2zuEbN9Oo’ has a name I don’t recognize (“Concentrate-Switch”) and was last updated over 18 months ago.
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/scenes/DfztBV2zuEbN9Oo
{
     "name": "Concentrate-Switch",
     "type": "LightScene",
     "lights": ["12", "13", "14", "15"],
     "owner": "d0be4d13-e994-4a63-a0ee-75e9789872cb",
     "recycle": false,
     "locked": false,
     "appdata": {
         "version": 1,
         "data": "G2cIO   :DA05000"
     },
     "picture": "",
     "lastupdated": "2018-05-19T20:15:50",
     "version": 2,
     "lightstates": {
         "12": {
             "on": true,
             "bri": 254,
             "ct": 232
         },
         "13": {
             "on": true,
             "bri": 254,
             "ct": 232
         },
         "14": {
             "on": true,
             "bri": 254,
             "ct": 232
         },
         "15": {
             "on": true,
             "bri": 254,
             "ct": 232
         }
     }
 }
  • Scenes come in two forms: GroupScene and LightScene
    • GroupScenes are assigned to a specific group of lights, like a room. The lights controlled by GroupScenes are managed by the owning group, and cannot be directly edited via the Scenes API resource.
    • LightScenes control lights irrespective of groups. The lights controlled are defined by ID in the array associated with the “lights” key.
  • This scene controls the lights in the “lights” array: ["12", "13", "14", "15"]
  1. To confirm that this scene is not used and is safe to be removed, look at the lights it is attached to by querying each light ID with GET
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/lights/12
{
     "state": {...},
     "swupdate": {...},
     "type": "Extended color light",
     "name": "Island3",
     "modelid": "LCT012",
     "manufacturername": "Signify Netherlands B.V.",
     "productname": "Hue color candle",
     "capabilities": {...},
     "config": {...},
     "uniqueid": "00:17:88:01:02:7d:da:eb-0b",
     "swversion": "1.50.2_r30933",
     "swconfigid": "A9AFB57A",
     "productid": "Philips-LCT012-1-E14ECLv1"
 }
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/lights/13
{
     "state": {...},
     "swupdate": {...},
     "type": "Color temperature light",
     "name": "Island1",
     "modelid": "LTW012",
     "manufacturername": "Signify Netherlands B.V.",
     "productname": "Hue ambiance candle",
     "capabilities": {...},
     "config": {...},
     "uniqueid": "00:17:88:01:03:56:a8:f1-0b",
     "swversion": "1.50.2_r30933",
     "swconfigid": "B2B0522E",
     "productid": "Philips-LTW012-1-E14CTv1"
 }
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/lights/14
{
     "state": {...},
     "swupdate": {...},
     "type": "Color temperature light",
     "name": "Island2",
     "modelid": "LTW012",
     "manufacturername": "Signify Netherlands B.V.",
     "productname": "Hue ambiance candle",
     "capabilities": {...},
     "config": {...},
     "uniqueid": "00:17:88:01:02:db:4b:ab-0b",
     "swversion": "1.50.2_r30933",
     "swconfigid": "B2B0522E",
     "productid": "Philips-LTW012-1-E14CTv1"
 }
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/lights/15
{
     "state": {...},
     "swupdate": {...},
     "type": "Extended color light",
     "name": "Cabinets",
     "modelid": "LST002",
     "manufacturername": "Signify Netherlands B.V.",
     "productname": "Hue lightstrip plus",
     "capabilities": {...},
     "config": {...},
     "uniqueid": "00:17:88:01:02:9d:1d:63-0b",
     "swversion": "1.50.2_r30933",
     "swconfigid": "59F2C3A3",
     "productid": "Philips-LST002-1-LedStripsv3"
 }
  • These lights are my kitchen lights
  • To verify that this is a duplicate scene, I will check the scenes list for any scene assigned to the Kitchen room – Group 5.
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/groups/5
{
     "name": "Kitchen",
     "lights": ["13", "14", "15", "12"],
     "sensors": [],
     "type": "Room",
     "state": {
         "all_on": false,
         "any_on": false
     },
     "recycle": false,
     "class": "Kitchen",
     "action": {
         "on": false,
         "bri": 77,
         "hue": 8402,
         "sat": 140,
         "effect": "none",
         "xy": [0.4575, 0.4099],
         "ct": 366,
         "alert": "select",
         "colormode": "xy"
     }
 }
  • I found scene “qGbDmym5nJ5GeUD” named “Concentrate” assigned to group 5
GET http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/scenes/qGbDmym5nJ5GeUD
{
     "name": "Concentrate",
     "type": "GroupScene",
     "group": "5",
     "lights": ["12", "13", "14", "15"],
     "owner": "42605c21-2f05-478d-a5d9-d3dadb0fcce3",
     "recycle": false,
     "locked": true,
     "appdata": {
         "version": 1,
         "data": "G2cIO_r05_d03"
     },
     "picture": "",
     "image": "b90c8900-a6b7-422c-a5d3-e170187dbf8c",
     "lastupdated": "2018-03-08T05:46:19",
     "version": 2,
     "lightstates": {
         "12": {
             "on": true,
             "bri": 254,
             "ct": 233
         },
         "13": {
             "on": true,
             "bri": 254,
             "ct": 233
         },
         "14": {
             "on": true,
             "bri": 254,
             "ct": 233
         },
         "15": {
             "on": true,
             "bri": 254,
             "ct": 233
         }
     }
 }
  • By comparing the “Concentrate-Switch” and “Concentrate” scenes, I can see that these are duplicates.
{
     "name": "Concentrate-Switch",
     "type": "LightScene",
     "lights": ["12", "13", "14", "15"],
     ...
     ...
     "lightstates": {
         "12": {
             "on": true,
             "bri": 254,
             "ct": 232
         },
         "13": {
             "on": true,
             "bri": 254,
             "ct": 232
         },
         "14": {
             "on": true,
             "bri": 254,
             "ct": 232
         },
         "15": {
             "on": true,
             "bri": 254,
             "ct": 232
         }
     }
 }
{
     "name": "Concentrate",
     "type": "GroupScene",
     "group": "5",
     "lights": ["12", "13", "14", "15"],
     ...
     "lightstates": {
         "12": {
             "on": true,
             "bri": 254,
             "ct": 233
         },
         "13": {
             "on": true,
             "bri": 254,
             "ct": 233
         },
         "14": {
             "on": true,
             "bri": 254,
             "ct": 233
         },
         "15": {
             "on": true,
             "bri": 254,
             "ct": 233
         }
     }
 }
  1. Delete the duplicate or unused scene using the DELETE method:

⚠️ // Warning

This process is destructive. Proceed with caution.

DELETE http://192.168.1.20/api/J1F5xyzxyzxyRtJHN2touph9xyzxyzxyN178BK8/scenes/DfztBV2zuEbN9Oo
{
  "success": "/scenes/DfztBV2zuEbN9Oo deleted"
}

Conclusion

With limited resources available on the Philips Hue Bridge, the ability to manage the configuration becomes more valuable as the Hue system grows in complexity.

When used with care, the Hue REST API is a powerful tool enabling precision administration.

While the REST API is not the only method available to manage Bridge resources, its direct insight into the Bridge configuration makes it particularly useful.

The processes discussed in this article are also helpful for those looking to create advanced automations for their Philips Hue lighting system.