Hue Motion Level

A Homebridge plugin for Philips Hue motion lighting. It is meant to give each room one light tile in Apple Home whose slider sets the brightness at which the room's Hue motion setup switches the lights on.

Status: early development. This version gives each motion setup you take over a light tile with a slider for its level, and gives the same level to other switch-ons. Making new motion setups, and removing them from the bridge, come in later versions. This is a personal project, shared as-is and without support.

What it is meant to do

• Level per room: a slider in Apple Home sets the brightness at which a room's Hue motion setup switches its lights on. Their colours stay as they are, and Hue's own warning dim stays.
• The same level for other switch-ons: switching the lights on with Siri, in Apple Home, in the Hue app or with a Hue switch set to plain on also gives the slider's level.
• A light tile that is always on: switching it off, also with "turn off all the lights", does nothing, so motion lighting is never switched off by accident. Apple Home treats it as a light, though: it counts it among the lights that are on, and "set the lights to 30 %" for the room or the home also sets the motion level.
• Taking over a motion setup you have: on your click in the plugin's settings page, the plugin takes over a Hue motion setup you already have, together with the light setting it switches on with, which then holds only the brightness; nothing else in the setup changes.
• Making a motion setup (planned): a later version is meant to make a new motion setup from lights and sensors you choose. Afterwards you change its times, sensors and lights in the Hue app, and the plugin follows.
• Removing a room: by default the motion setup on the bridge keeps working as it is; you can choose to delete it from the Hue bridge too, with its light setting. Either way the plugin keeps nothing about the room.
• Problems in the log and on the settings page: each problem gets one warning in the Homebridge log, with what to do, and the settings page lists the current ones. There is no extra tile for problems.

Everything stays on the home network: the plugin talks to the Hue bridge directly, with no Hue account and no cloud.

What this version does

• It finds the Hue bridge on the network, or uses the address you enter.
• Its settings page shows whether it is paired with a bridge. Press Pair there, then the round link button on the bridge while the page counts down; the bridge then gives the plugin a key. The plugin also remembers the bridge's certificate and from then on talks only to a device that shows that same certificate.
• It follows the bridge's events, reconnects by itself when the connection drops, and reads everything again every 15 minutes as a safety net.
• At each start it writes one line per Hue motion setup to the log: whether the plugin will be able to use it, what it does when motion starts, whether it is paused, and what to fix in the Hue app if something is wrong.
• Once paired, its settings page lists the bridge's motion setups. Take over… says what will change; Take over then makes the setup's light setting hold only on and one level (if it does not already), adds the room under Rooms in the settings and saves them. Restart the child bridge to get its tile. This version takes over setups that switch on with a light setting of their own; setups on 'last on', or sharing their light setting with another setup, come later.
• Each room's light tile: its slider rewrites the light setting, so the next switch-on by motion comes on at that level; lights that are on stay as they are. Switching the tile off does nothing.
• The same level for other switch-ons: after a room's lights go off, the plugin gives them the slider's level while they are off, so switching them on with Siri, Apple Home, the Hue app or a Hue switch set to plain on comes on at that level too; a switch-on that chooses its own level or scene keeps it. Tick Leave other switch-ons alone for a room to switch this off.
• It follows the bridge: a new level for every light set in the Hue app moves the slider, and a light setting that gained a colour, lost a light or got different levels per light is put back to only on and one level. Problems show in the log and on the settings page, including a hint for a motion setup that puts the lights back to how they were after motion: a walk-in right as they go off can leave a light on for good, so switching them off is the safer choice.

Requirements

• Homebridge 2.x, with Node.js 22 (22.10 or later), 24 or 26
• A Philips Hue bridge on the same network, and access to it to press its link button once

Installation

1. Install Hue Motion Level from the Plugins tab of the Homebridge UI (search for the exact name homebridge-hue-motion-level).
2. Open its settings and press Save once. Run it as a child bridge (Plugins → Hue Motion Level → Bridge settings) and restart when asked.
3. Open its settings again. The Hue bridge card at the top shows the pairing status. Press Pair, go to the bridge and press its round link button within two minutes; the card counts down and then shows the bridge it is paired with. If you miss it, press Pair again.
4. The log then lists the bridge's motion setups, and the settings page offers Take over for each one it can use.

If the plugin does not find the bridge, enter the bridge's IP address under Bridge address in the plugin's settings. The Hue app shows it under Settings → Bridges.

The key is a secret

The key the bridge hands out controls every light on it. The plugin keeps it in the file hue-motion-level/bridge.json in the Homebridge storage folder, readable only by Homebridge, and never writes it to the log or to the settings. Homebridge backups contain this file, so treat them as secret.

Pairing again

If the bridge refuses the plugin's key, or shows a different certificate (for example after a bridge reset or replacement), the Hue bridge card in the plugin's settings says so and offers Pair again: press it, then the link button on the bridge. The new key replaces the old one at once.

If the settings page cannot reach the plugin (the card says that the plugin is not running although it is), the plugin pairs through the log instead: it asks there for the link button at each start, and to pair again you delete the file hue-motion-level/bridge.json in the Homebridge storage folder and restart the plugin's child bridge.

Settings

• Rooms: added by Take over. Each has a name and an optional tile name; avoid words like light or lamp in it, so Siri does not take it for a light. Apple Home keeps the name a tile had when it was added, so rename it there too. To remove a room, remove it here, press Save and restart the child bridge: its tile goes, and Apple Home may also delete automations and scenes that use it; its motion setup keeps working at the last level.
• Bridge address (optional): only needed if the plugin cannot find the bridge by itself.
• Debug logging: writes every event from the bridge and every reconnect to the log, and at each start the bridge's behaviour scripts and the layout of each motion setup. These lines contain the bridge's address and resource ids, so remove them before you share a log.
• Advanced: how long pairing waits for the link button after you press Pair, the longest wait between reconnects, how often everything is read again, how long the bridge may be away before the tiles show No Response, how long a slider move waits for the bridge, how long the plugin waits after a switch-off before it gives the lights the level, and the gap between two light writes.

Removal

Uninstall the plugin in the Homebridge UI. The motion setups you took over keep working at their last level; their light settings stay as the plugin left them. If the Hue app lists connected apps, you can remove the plugin's key there (it is named hb_motion_level).

Licence

Apache-2.0. The full text, with this plugin's copyright notice, is in the LICENSE file that comes with the package.