Emulates a Philips Hue Bridge (v2, BSB002) so that ioBroker devices appear as Hue lights to clients that only support the Hue API.
Use it if you want to control ioBroker states from an older device or app that only speaks the Hue API. Examples: Logitech Harmony Hub, Bosch Smart Home Controller, legacy Echo firmware, in-wall touch panels, abandoned dashboard apps, old control systems with a Hue plugin.
Modern voice assistants all support Matter directly. Use the ioBroker Matter adapter — it's the right tool for that. This adapter is only for clients that don't have a Matter option.
- Hue API v1 — Bridge model BSB002 (Hue Bridge v2)
- UPnP/SSDP Discovery — Automatic detection by any Hue-compatible client
- Direct state mapping — Point to any ioBroker state, no bridge scripts
- Light types — On/Off, Dimmable, Color Temperature, RGB
- Per-device value scale — pick how brightness and saturation are stored in your source state
- Persistent TLS certificate — clients only trust the bridge once, restarts keep the same identity
- Localized state names — admin labels follow the ioBroker system language
- Automatic migration — legacy
createLightsetups are converted to the admin configuration on first start
- Node.js >= 22
- ioBroker js-controller >= 7.0.7
- ioBroker Admin >= 7.8.23
| Port | Protocol | Purpose | Configurable |
|---|---|---|---|
| 8080 | TCP/HTTP | Hue Bridge API | Yes — clients are informed via SSDP |
| 1900 | UDP | SSDP/UPnP Discovery | No — fixed by the UPnP standard |
| — | TCP/HTTPS | Optional TLS (if configured) | Yes |
| Option | Description | Default |
|---|---|---|
| Host | IP address of the bridge (must be a real network IP) | — |
| HTTP Port | Port for the Hue API | 8080 |
| HTTPS Port | Only needed if a client insists on TLS; leave empty otherwise | — |
| MAC Address | Bridge MAC (auto-generated if empty) | — |
- Open the Device Configuration tab
- Click the
+button - Enter a Name (e.g. "Living Room Light")
- Select a Light Type
- Map States via the object browser (
...)
| Type | States | Hue Model |
|---|---|---|
| On/Off | on |
LWB007 |
| Dimmable | on, bri |
LWB010 |
| Color Temperature | on, bri, ct |
LTW001 |
| Color Light | on, bri, ct, hue, sat, xy |
LCT003 |
Before any client can connect, pairing must be activated:
- ioBroker Objects →
hueemu.0→ setstartPairingtotrue - Start the device search / pairing in your client app within 50 seconds
- After successful pairing a new entry appears under
hueemu.0.clients.*
If you have a current Echo, use the Matter adapter instead.
Tip: If Alexa cannot find the bridge, try changing the HTTP port to 80 in the adapter settings — some Alexa firmware versions only discover bridges on port 80.
- Activate pairing (see above)
- Alexa App → Devices →
+→ Philips Hue - The bridge is discovered automatically
- Activate pairing (see above)
- In the Harmony setup software: Add Device → Lighting → Philips Hue → search for bridge
- Confirm pairing within 50 seconds
hueemu.0.
├── startPairing — Enable pairing mode for 50 seconds (button)
├── disableAuth — Disable authentication (switch)
└── clients/ — Paired client devices
└── {username} — Client API key (created during pairing)
If you used the old createLight JSON state to define lights, your devices are automatically migrated on first start. The adapter reads your existing device objects, converts them to the new admin configuration format, and restarts once. No manual action required — your existing scripts and automations continue to work as before.
Optional improvement: The old system used internal adapter states as intermediaries, requiring separate scripts to control the actual devices. You can now open the adapter settings and change the state mappings to point directly to your device states (e.g. hm-rpc.0.dimmer.LEVEL instead of hueemu.0.1.state.bri).
- Ensure the UPnP port (1900) is not blocked by a firewall
- The Host IP must be the actual network IP, not
0.0.0.0 - Check firewall rules on the ioBroker host
- Set
startPairingtotruein ioBroker Objects →hueemu.0before starting the device search in your client — you have 50 seconds - Ensure at least one device is configured
- Check adapter logs for errors
- Verify state IDs in device configuration
- Pick the matching brightness/saturation scale per device in the admin — Auto, Percent (0..100), Normalized (0..1) or Hue-Raw (1..254). A
level.dimmerstoring 0..100 needs Percent. ctrange is 153–500 (Mireds)
- Debug log now traces previously silent paths: TLS certificate validity on reuse, every Hue API error response, SSDP discovery answers and device-binding scale decisions. Default log unchanged.
- Brightness and saturation now have an explicit scale option per device, so values stored as 0..100 are no longer misread as full brightness. Existing setups keep working on the default.
- TLS certificate is now stored and reused across restarts — clients only need to trust it once, and the adapter starts noticeably faster.
- Paired clients appear in Hue tools that read the bridge whitelist.
- HTTP API stays reachable even when SSDP port 1900 is already used by another adapter — the log explains how to add the bridge by IP.
- "Disable Auth" now reliably keeps its value across adapter restarts.
- Pairing window has a safety cap so a noisy network can't flood the bridge with new clients.
- Adapter log messages are now English only, in line with the ioBroker community standard. Localized state names are unchanged.
- Internal hardening. No user-facing changes.
Older entries are in CHANGELOG_OLD.md.
Original Author: Christopher Holomek (@holomekc)
Modernization: krobi
This adapter is free and open source. If you find it useful, consider buying me a coffee:
MIT License
Copyright (c) 2020-2024 Christopher Holomek holomekc.github@gmail.com
Copyright (c) 2026 krobi krobi@power-dreams.com
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Developed with assistance from Claude.ai
