En3rGy / 14100_Hue

Gira HS logic module to control Philips Hue
MIT License
7 stars 0 forks source link
home-automation hue smarthome

14100 Hue Group

Description

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).

Quick Start

Create a HUE API User

Follow the instruction to create a HUE bridge API user key.

Set-Up the Logic Module

Useage

Information Website and Set-up of logic module

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.

Switch on/off a Light

Note: If you want to switch on a room or a zone, use the rooms / zones ID on input 4

Command a scene

Inputs

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.

Outputs

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

Examples

Input Output
- -

Other

Change Log

Open Issues / Know Bugs

Support

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.

Code

The code of the module can be found within the hslz file or at github.

Development Environment

Requirements

Software Design Description

As far as possible, the module is developed object orientated. Two major objects exist:

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:

Used libraries:

Validation & Verification

Licence

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.