The logic module provides an interface to specific Hue lights, groups, rooms, zones, etc. Registered devices can be controlled and the device status is provided via the modules output. The module registers itself at the hue bridge using the Hue Hue API v2 and the eventstream function. Using multiple instances of the logic module, just one will register for the eventstream and provides received date to the other ones.
One module provides an auto discovery on the Hue bridge in order to receive the bridges IP address. A HS reboot is necessary, if the bridge IP chances! Alternatively, a manual IP can be provided. In that case, no auto discovery is performed. The manual IP can be updated during runtime.
All outputs are configured as send-by-change (sbc).
Follow the instruction to create a HUE bridge API user key.
- Install module into HS and create a logic sheet using this help file
- Store the obtained API user key on the corresponding input of the logic module
- Upload the project
- Check the HS debug page, go to HSL 2.0 section, find the 14100_Hue heading and get the Server URL
- Open the obtained server URL, e.g.
http://<IP-Homeserver>:<port> - Identify the ID of the Hue device / group / room / etc. you want to control
- Copy the ID to the logic module
- Re-upload the project and restart the HS
Hue API v2 addresses each device using a non-readable ID.
This ID must be provided to the logic module instance of the corresponding Hue device (1 Hue Device : 1 Logic Module
Instance).
In oder to identify the Hue ID of a specific device, one logic module creates a webpage showing the IDs and the
corresponding rooms and device names (Information Website). The link to this page is shown on the debug page in the logic modules section
within the HSL 2.0 section and represents this scheme: http://<HS-IP>:<Port>
Create at least one instance of the logic module and identify the Hue IDs of the devices you would like to control.
Set up an instance of the logic module for each hue item you would like to control or monitor the status.
In general, use the light or grouped light ID.
- Identify the light ID on the info page
- Put the ID on input 4 (usually constant, the idea is to have one logic module per light/room/zone)
- Use input 8 to switch the light on or off
Note: If you want to switch on a room or a zone, use the rooms / zones ID on input 4
- Identify the scene ID on the info page. Caution! Each light has its own scene.
- Identify the tabel row of the light / room
- Identify the ID of the desired scene
- Write the scene ID on input 5 (this will switch on the light if it was off before)
- Set input 6 to one if you want to activate the dynamic behaviour of the scene
| Nr. | Name | Init. | Description |
|---|---|---|---|
| 1 | Get Status | A value =1 reads (manually) the full status of the device from the bridge | |
| 2 | Key | Hue Bridge User Key, see Create HUE Bridge API User | |
| 3 | Port Info Page | 0 | Port of Information Website: Website containing all Hue devices and the corresponding or associated Hue IDs. The web site is provided at http://<HS-IP>:<Port> |
| 4 | Item Id | 0 | ID of Hue device to be controlled. The ID can be identified via the Information Website described in the description / Usage section Use the specific ID, e.g. the Light ID or Grouped light Id.Use the light id to control a power socket |
| 5 | Scene ID | ID of the scene to be called. Providing a valid scene ID on this input will switch on the device also. | |
| 6 | Dynamic scene On/Off | 0 | True/False. Activates the scene of Input 5 as "dynamic scene" |
| 7 | Dyn. scene speed | 0.7 | Speed of dynamic palette for the sceen given on input 5 and activated as "dynamic" on input 6 (0-1) |
| 8 | On/Off (1/0) | 0 | Switches on (1) / off (0) the Hue device. |
| 9 | Brightness (%) | 0 | Brightness in 0-100% Device will be switched on if value is set |
| 10 | r | 0 | RGB red (0-100%) |
| 11 | g | 0 | RGB green (0-100%) |
| 12 | b | 0 | RGB blue (0-100%) |
| 13 | KNX rel. Dimm | 0 | Eingang für KNX-Dimm-Signal. Der zugh. Taster muss wie folgt parametrisiert werden: Relatives dimmen mit Stopp-Signal, ohne Telegramm-Wiederholung |
| 14 | KNX Dimm Ramp | 0.5 | KNX Dimm Rampe [s]; Zeit in Sekunden, in der der Dimmschritt wiederholt wird, bis ein Stopp-Signal empfangen wird. |
| 15 | Bridge IP (optional) | (Optional) IP der Hue Bridge. Wird dieser Wert gesetzt, wird keine auto-detection durchgeführt. |
| Nr. | Name | Init. | Description |
|---|---|---|---|
| 1 | RM On/Off | 0 | On/Off Status (1/0) |
| 2 | RM Brightness | 0 | Current Brightness 0-100% |
| 3 | r | 0 | RGB red 0-100% |
| 4 | g | 0 | RGB green 0-100% |
| 5 | b | 0 | RGB blue 0-100% |
| 6 | Light Reachable | 0 | Status is light is connected 0=not reachable, 1=reachable |
| Input | Output |
|---|---|
| - | - |
- Calculation on start: No
- Module is remanent: No
- Internal number: 14100
- Category: Datenaustausch
- v3.11: Debug output of bridge discovery reply
- v3.9:
- Fix for #29
- v3.8:
- Impr.: Using a sticky table header for the info table
- Impr.: Sorting the info table alphabetically
- v3.7: Identified group id for rooms on info page addressing #30
- v4.6: Improved unit tests
- v3.5:
- Work-around-fix of [0, 255, 0] results in yellow-green: Removed check if color in in reach of lamp (#27)
- v3.4:
- Refactoring
- v3.3:
- Detecting broken connections to Hue Bridge
- Corrected input IDs in docu
- v3.2: Fixed Bug #25
- v3.1: Update of documentation
- v3.0: Refactoring & Hue API v2
- see issue
Please use GitHub issue feature to report bugs or rise feature requests. Questions can be addressed as new threads at the knx-user-forum.de also. There might be discussions and solutions already.
The code of the module can be found within the hslz file or at github.
- Python 2.7.18
- Install python markdown module (for generating the documentation)
python -m pip install markdown
- Install python markdown module (for generating the documentation)
- Python editor PyCharm
- Gira Homeserver Interface Information
- Pairing of Hue Bridge via module, s. API v2 Getting started
- Light on/off #12
- Provide on/off status #16
- Dimming of lights and provision of status #17
- Set color and provide light color status #19
- Provide connection status #20
- Start of scenes #21
- Play dynamic scenes #22
- All for zones #14 / Räume #15 / Gruppen #13
- Manual trigger of requesting status data #18
- Auto-detect Hue Bridge #11
- Auto re-connect with Hue Bridge #10
- Using multiple module instances, just one shall connect to Hue Bridge #9
- Provision of web page with info regarding Hue IDs #8
- Shall not block the HS #23
As far as possible, the module is developed object orientated. Two major objects exist:
- Bridge Objekt
For communication with Hue Bridge, incl. Bridge Discovery - Hue Item Objekt
For commanding Hue-Objects, e.g. lights, rooms, scenes, etc. An essential element of the Hue API v2 is the Eventstream. Programmes can register for this and receive status changes from the Hue Bridge almost immediately.
With several Hue logic devices, only one of the devices connects to the event stream and forwards incoming messages to all other Hue devices. This is done via the common scope, a connection of the devices via iKO is not necessary.
In addition:
- Lamps / Scenes / Zones / Rooms / Groups are distinguished via the Id; query of the type via /resource {data{id, type}}.
- Depending on the action, the respective rid is searched for via the device id.
- Only one device connects to the Hue Bridge, the others use this connection via HS Instances
- The eventstream connection runs in a separate thread in a
while trueloop - If there is no network connection at initialisation time, signals on the device inputs will attempt to connect to the bridge.
Used libraries:
- https://github.com/benknight/hue-python-rgb-converter for Hue color conversion from/to rgb.
- Unit tests are performed.
Copyright 2023 T. Paul
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 NON INFRINGEMENT. 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.