[hue] Implement CLIP 2 / API v2

bundles/org.openhab.binding.hue/doc/readme_v2.md

@@ -0,0 +1,184 @@
+# Philips Hue Binding Configuration for API v2
+
+[Back to Overview](../README.md#philips-hue-binding)
+
+## Supported Things
+
+The binding supports `bridge-api2`, `device`, `room`, and `zone` thing types.
+The `bridge-api2` thing type represents the Hue Bridge which is the server for all other things.
+The `device` thing type represents a piece of physical equipment in the home.
+Such `device` things may contain either a *light*, a *button*, or (one or more) *sensors*.
+Lights can be of any type from a simple on/off light, through dimmable monochrome lights, to full colour dimmable lights.
+Buttons are devices having one or more push buttons.
+Sensors can be (for example) light level sensors, temperature sensors, or motion sensors.
+The `room` and `zone` thing type represents logical groupings of equipment in the home, either within a specific room, or a logical group of equipment.
+
+## Thing Configuration
+
+### Bridge
+
+The Hue Bridge requires the IP address as a configuration value in order for the binding to know where to access it.
+It requires an 'application key' to authenticate against the Hue Bridge.
+This may be copied from an API v1 installation, or it may be automatically generated (press button to authenticate).
+Please note that the generated application key cannot be written automatically to the `.things` file, and has to be set manually.
+The generated application key can be found, after pressing the authentication button on the bridge, with the following console command: `openhab:hue <bridgeUID> applicationkey`.
+The application key can be set using the `applicationKey` configuration value, e.g.:
+
+```java
+Bridge hue:bridge-api2:1 [ ipAddress="192.168.0.64", applicationKey="qwertzuiopasdfghjklyxcvbnm1234" ]
+```
+
+| Parameter                | Description                                                                                        |
+|--------------------------|----------------------------------------------------------------------------------------------------|
+| ipAddress                | Network address of the Hue Bridge. **Mandatory**.                                                  |
+| applicationKey           | A code generated by the bridge that allows to access the API. **Mandatory**                        |
+| checkMinutes             | Interval in minutes between retrying the HTTP 2 and SSE connections. Default is 60. **Advanced**   |
+| useSelfSignedCertificate | Use self-signed certificate for HTTPS connection to Hue Bridge. Default is `true`. **Advanced**    |
+
+### Devices, Rooms, and Zones
+
+Apart from the Bridge, there are three other types of thing -- namely `device`, `room`, and `zone`.
+Device things represent physical hardware devices in the system, whereas `room` and `zone` things represent sets of physical lights, either in a room or a zone.
+In addition to regular rooms and zones, there is a 'super' `zone` that allows you to control all of the lights in the system.
+
+All things are identified by a unique Resource Identifier string that the Hue Bridge assigns to them e.g. `d1ae958e-8908-449a-9897-7f10f9b8d4c2`.
+Thus, all it needs for manual configuration is this single value like
+
+```java
+device officelamp "Lamp 1" @ "Office" [ resourceId="d1ae958e-8908-449a-9897-7f10f9b8d4c2" ]
+..
+zone kitchenLights "Kitchen Down Lights" @ "Kitchen" [ resourceId="7f10f9b8-8908-449a-9897-d4c2d1ae958e" ]
+```
+
+You can get a list of all devices in the bridge and their respective Resource Ids by entering the following console command: `openhab:hue <bridgeUID> things`
+See [console command](#console-command-for-finding-resourceids)
+
+The configuration of all things (as described above) is the same regardless of whether it is a device containing a light, a button, or (one or more) sensors, or whether it is a room or zone.
+
+### Channels for Devices
+
+Device things support some of the following channels:
+
+| Channel Type ID     | Item Type          | Description                                                                           |
+|---------------------|--------------------|---------------------------------------------------------------------------------------|
+| switch              | Switch             | This channel supports switching the device on and off.                                |
+| color               | Color              | This channel supports full color control with hue, saturation and brightness values.  |
+| brightness          | Dimmer             | This channel supports adjusting the brightness value.                                 |
+| color-temperature   | Dimmer             | This channel supports adjusting the color temperature from cold (0%) to warm (100%).  |
+| color-temp-kelvin   | Number:Temperature | This channel supports adjusting the color temperature in Kelvin.                      |
+| alert               | String             | This channel allows setting an alert on a light e.g. flashing them.                   |
+| effect              | String             | This channel allows setting an effect on a light e.g. 'candle' effect.                |
+| button-last-event   | Number             | This channel shows which button was last pressed in the device.                       |
+| rotary-steps        | Number             | This channel shows the number of rotary steps of the last rotary dial movement.       |
+| motion              | Switch             | This channel shows if motion has been detected by the sensor.                         |
+| motion-enabled      | Switch             | This channel supports enabling / disabling the motion sensor.                         |
+| light-level         | Number             | This channel shows the current light level measured by the sensor.                    |
+| light-level-enabled | Switch             | This channel supports enabling / disabling the light level sensor.                    |
+| temperature         | Number:Temperature | This channel shows the current temperature measured by the sensor.                    |
+| temperature-enabled | Switch             | This channel supports enabling / disabling the temperature sensor.                    |
+| battery-level       | Number             | This channel shows the battery level.                                                 |
+| battery-low         | Switch             | This channel indicates whether the battery is low or not.                             |
+| zigbee-status       | String             | This channel provides information about the status of the Zigbee connection.          |
+| last-updated        | DateTime           | This channel the date and time when the thing state was last updated.                 |
+
+The exact list of channels in a given device is determined at run time when the system is started.
+Each device reports its own live list of capabilities, and the respective list of channels is created accordingly.
+
+The `zigbee-status` indicates the connectivity state of the device.
+If the device has connectivity issues, the thing state will change to 'OFFLINE'
+
+The `button-last-event` channel value is a number that is calculated from the following formula:
+
+```text
+value = (button_id * 1000) + event_id;
+```
+
+In a single button device, the `button_id` is 1, whereas in a multi- button device the `button_id` can be either 1, 2, 3, or 4 depending on which button was pressed.
+The `event_id` can have the following values:
+
+| Event                | Value |
+|----------------------|-------|
+| INITIAL_PRESS        | 0     |
+| REPEAT               | 1     |
+| SHORT_RELEASE        | 2     |
+| LONG_RELEASE         | 3     |
+| DOUBLE_SHORT_RELEASE | 4     |
+
+So (for example) the channel value `1002` ((1 * 1000) + 2) means that the second button in the device had a short release event.
+
+The `rotary-steps` channel value is the number of steps corresponding to the last movement of a rotary dial.
+A positive number means the dial was rotated clock-wise, whereas a negative number means it was roated counter-clockwise.
+
+### Channels for Rooms and Zones
+
+Room and Zone things allow you to control the lights in a given zone or room.
+They support the following channels:
+
+| Channel Type ID     | Item Type          | Description                                                                           |
+|---------------------|--------------------|---------------------------------------------------------------------------------------|
+| switch              | Switch             | This channel supports switching the lights on and off.                                |
+| brightness          | Dimmer             | This channel supports adjusting the brightness value.                                 |
+| scene<sup>1)</sup>  | String             | Setting the string to a valid scene friendly name activates the respective scene.     |
+| alert<sup>1)</sup>  | String             | This channel allows setting an alert on the lights e.g. flashing them.                |
+
+<sup>1)</sup> The scene and alert channels are optional.
+If the respective room or zone has no scenes or alerts associated with it, the respective channel will not be shown.
+
+## Console Command for finding ResourceIds
+
+The openHAB console has a command named `openhab:hue` that (among other things) lists the `resourceId` of all device things in the bridge.
+The console command usage is `openhab:hue <brigeUID> things`.
+An exampe of such a console command, and its respective output, is shown below..
+
+```text
+openhab> openhab:hue hue:bridge-api2:g24 things
+Bridge hue:bridge-api2:g24 "Philips Hue Bridge" [ipAddress="192.168.1.234", applicationKey="abcdefghijklmnopqrstuvwxyz0123456789ABCD"] {
+  Thing device 11111111-2222-3333-4444-555555555555 "Standard Lamp L" [resourceId="11111111-2222-3333-4444-555555555555"] // Hue color lamp
+  Thing device 11111111-2222-3333-4444-666666666666 "Kitchen Wallplate Switch" [resourceId="11111111-2222-3333-4444-666666666666"] // Hue wall switch module
+  ..
+}
+```
+
+The `openhab:hue <brigeUID> things` command produces an output that can be used to directly create a `.things' file, as shown below..
+
+```text
+openhab> openhab:hue hue:bridge-api2:g24 things > myThingsFile.things
+```
+
+## Full Example
+
+### demo.things:
+
+```java
+Bridge hue:bridge-api2:g24 "Philips Hue Hub" @ "Home" [ipAddress="192.168.1.234", applicationKey="abcdefghijklmnopqrstuvwxyz0123456789ABCD"] {
+    Thing device 11111111-2222-3333-4444-555555555555 "Living Room Standard Lamp Left" @ "Living Room" [resourceId="11111111-2222-3333-4444-555555555555"]
+    Thing device 11111111-2222-3333-4444-666666666666 "Kitchen Wallplate Switch" @ "Kitchen" [resourceId="11111111-2222-3333-4444-666666666666"]
+
+    Thing zone 11111111-2222-3333-4444-666666666666 "Kitchen Lights" @ "Kitchen" [resourceId="11111111-2222-3333-4444-666666666666"]
+}
+```
+
+### demo.items:
+
+```java
+Color Living_Room_Standard_Lamp_Left_Colour "Living Room Standard Lamp Left Colour" {channel="hue:device:g24:11111111-2222-3333-4444-555555555555:color"}
+Dimmer Living_Room_Standard_Lamp_Left_Brightness "Living Room Standard Lamp Left Brightness [%.0f %%]" {channel="hue:device:g24:11111111-2222-3333-4444-555555555555:brightness"}
+Switch Living_Room_Standard_Lamp_Left_Switch "Living Room Standard Lamp Left Switch" (g_Lights_On_Count) {channel="hue:device:g24:11111111-2222-3333-4444-555555555555:switch"}
+
+Number Kitchen_Wallplate_Switch_Last_Event "Kitchen Wallplate Switch Last Event" {channel="hue:device:g24:11111111-2222-3333-4444-666666666666:button-last-event"}
+Switch Kitchen_Wallplate_Switch_Battery_Low_Alarm "Kitchen Wallplate Switch Battery Low Alarm" {channel="hue:device:g24:11111111-2222-3333-4444-666666666666:battery-low"}
+```
+
+### demo.sitemap:
+
+```perl
+sitemap demo label="Hue" {
+  Frame label="Standard Lamp" {
+    Switch item=Living_Room_Standard_Lamp_Left_Switch
+    Slider item=Living_Room_Standard_Lamp_Left_Brightness
+    Colorpicker item=Living_Room_Standard_Lamp_Left_Colour
+  }
+}
+```
+
+[Back to Overview](../README.md#philips-hue-binding)

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/HueBindingConstants.java

@@ -12,6 +12,11 @@
  */
 package org.openhab.binding.hue.internal;
 
+import java.util.Map;
+import java.util.Set;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.openhab.core.thing.ThingTypeUID;
 
@@ -53,9 +58,14 @@ public class HueBindingConstants {
     public static final ThingTypeUID THING_TYPE_GEOFENCE_SENSOR = new ThingTypeUID(BINDING_ID, "geofencesensor");
     public static final ThingTypeUID THING_TYPE_TEMPERATURE_SENSOR = new ThingTypeUID(BINDING_ID, "0302");
     public static final ThingTypeUID THING_TYPE_LIGHT_LEVEL_SENSOR = new ThingTypeUID(BINDING_ID, "0106");
-
     public static final ThingTypeUID THING_TYPE_GROUP = new ThingTypeUID(BINDING_ID, "group");
 
+    public static final Set<ThingTypeUID> V1_THING_TYPE_UIDS = Set.of(THING_TYPE_COLOR_LIGHT,
+            THING_TYPE_COLOR_TEMPERATURE_LIGHT, THING_TYPE_DIMMABLE_LIGHT, THING_TYPE_EXTENDED_COLOR_LIGHT,
+            THING_TYPE_ON_OFF_LIGHT, THING_TYPE_ON_OFF_PLUG, THING_TYPE_DIMMABLE_PLUG, THING_TYPE_DIMMER_SWITCH,
+            THING_TYPE_TAP_SWITCH, THING_TYPE_PRESENCE_SENSOR, THING_TYPE_TEMPERATURE_SENSOR,
+            THING_TYPE_LIGHT_LEVEL_SENSOR, THING_TYPE_GROUP);
+
     // List all channels
     public static final String CHANNEL_COLORTEMPERATURE = "color_temperature";
     public static final String CHANNEL_COLORTEMPERATURE_ABS = "color_temperature_abs";
@@ -94,11 +104,22 @@ public class HueBindingConstants {
     // Thing configuration properties
     public static final String LIGHT_ID = "lightId";
     public static final String SENSOR_ID = "sensorId";
-    public static final String PRODUCT_NAME = "productName";
+    public static final String PROPERTY_PRODUCT_NAME = "productName";
     public static final String UNIQUE_ID = "uniqueId";
     public static final String FADETIME = "fadetime";
     public static final String GROUP_ID = "groupId";
 
+    // property names for API v2
+    public static final String PROPERTY_RESOURCE_ID = "resourceId";
+    public static final String PROPERTY_RESOURCE_TYPE = "resourceType";
+    public static final String PROPERTY_RESOURCE_NAME = "resourceName";
+    public static final String PROPERTY_RESOURCE_ARCHETYPE = "resourceArchetype";
+    public static final String PROPERTY_PRODUCT_ARCHETYPE = "productArchetype";
+    public static final String PROPERTY_PRODUCT_CERTIFIED = "productCertified";
+    public static final String PROPERTY_LEGACY_THING_UID = "legacyThingUID";
+    public static final String PROPERTY_OWNER = "owner";
+    public static final String PROPERTY_OWNER_TYPE = "ownerType";
+
     public static final String NORMALIZE_ID_REGEX = "[^a-zA-Z0-9_]";
 
     //
@@ -107,4 +128,54 @@ public class HueBindingConstants {
 
     // Config status messages
     public static final String IP_ADDRESS_MISSING = "missing-ip-address-configuration";
+
+    // thing types for API v2
+    public static final ThingTypeUID THING_TYPE_BRIDGE_API2 = new ThingTypeUID(BINDING_ID, "bridge-api2");
+    public static final ThingTypeUID THING_TYPE_DEVICE = new ThingTypeUID(BINDING_ID, "device");
+    public static final ThingTypeUID THING_TYPE_ZONE = new ThingTypeUID(BINDING_ID, "zone");
+    public static final ThingTypeUID THING_TYPE_ROOM = new ThingTypeUID(BINDING_ID, "room");
+
+    // channels for API v2
+    public static final String CHANNEL_2_BRIGHTNESS = CHANNEL_BRIGHTNESS;
+    public static final String CHANNEL_2_COLOR = CHANNEL_COLOR;
+    public static final String CHANNEL_2_COLOR_TEMPERATURE = "color-temperature";
+    public static final String CHANNEL_2_COLOR_TEMP_KELVIN = "color-temp-kelvin";
+    public static final String CHANNEL_2_SWITCH = CHANNEL_SWITCH;
+    public static final String CHANNEL_2_SCENE = CHANNEL_SCENE;
+    public static final String CHANNEL_2_ALERT = CHANNEL_ALERT;
+    public static final String CHANNEL_2_EFFECT = CHANNEL_EFFECT;
+    public static final String CHANNEL_2_BUTTON_LAST_EVENT = "button-last-event";
+    public static final String CHANNEL_2_ROTARY_STEPS = "rotary-steps";
+    public static final String CHANNEL_2_MOTION = "motion";
+    public static final String CHANNEL_2_MOTION_ENABLED = "motion-enabled";
+    public static final String CHANNEL_2_LIGHT_LEVEL = "light-level";
+    public static final String CHANNEL_2_LIGHT_LEVEL_ENABLED = "light-level-enabled";
+    public static final String CHANNEL_2_TEMPERATURE = CHANNEL_TEMPERATURE;
+    public static final String CHANNEL_2_TEMPERATURE_ENABLED = "temperature-enabled";
+    public static final String CHANNEL_2_BATTERY_LEVEL = "battery-level";
+    public static final String CHANNEL_2_BATTERY_LOW = "battery-low";
+    public static final String CHANNEL_2_ZIGBEE_STATUS = "zigbee-status";
+    public static final String CHANNEL_2_LAST_UPDATED = "last-updated";
+
+    /*
+     * Map of API v1 channel IDs against API v2 channel IDs where, if the v1 channel exists in the system, then we
+     * should try to replicate the channel/item links from the v1 channel into the respective v2 channel.
+     */
+    public static final Map<String, String> REPLICATE_CHANNEL_ID_MAP = Stream.of(new String[][] { //
+            { CHANNEL_BRIGHTNESS, CHANNEL_2_BRIGHTNESS }, //
+            { CHANNEL_COLOR, CHANNEL_2_COLOR }, //
+            { CHANNEL_SWITCH, CHANNEL_2_SWITCH }, //
+            { CHANNEL_SCENE, CHANNEL_2_SCENE }, //
+            { CHANNEL_COLORTEMPERATURE, CHANNEL_2_COLOR_TEMPERATURE }, //
+            { CHANNEL_COLORTEMPERATURE_ABS, CHANNEL_2_COLOR_TEMP_KELVIN }, //
+            { CHANNEL_DIMMER_SWITCH, CHANNEL_2_BUTTON_LAST_EVENT }, //
+            { CHANNEL_LIGHT_LEVEL, CHANNEL_2_LIGHT_LEVEL }, //
+            { CHANNEL_PRESENCE, CHANNEL_2_MOTION }, //
+            { CHANNEL_TEMPERATURE, CHANNEL_2_TEMPERATURE }, //
+            { CHANNEL_BATTERY_LEVEL, CHANNEL_2_BATTERY_LEVEL }, //
+            { CHANNEL_BATTERY_LOW, CHANNEL_2_BATTERY_LOW }, //
+            { CHANNEL_LAST_UPDATED, CHANNEL_2_LAST_UPDATED } //
+    }).collect(Collectors.toMap(entry -> entry[0], entry -> entry[1]));
+
+    public static final String ALL_LIGHTS_KEY = "discovery.group.all_lights.label";
 }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/config/Clip2BridgeConfig.java

@@ -0,0 +1,31 @@
+/**
+ * Copyright (c) 2010-2023 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.hue.internal.config;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * Configuration for the Clip2BridgeHandler.
+ *
+ * @author Andrew Fiddian-Green - Initial contribution
+ */
+@NonNullByDefault
+public class Clip2BridgeConfig {
+    public static final String APPLICATION_KEY = "applicationKey";
+
+    public @Nullable String ipAddress;
+    public @Nullable String applicationKey;
+    public int checkMinutes = 60;
+    public boolean useSelfSignedCertificate = true;
+}

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/config/Clip2ThingConfig.java

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) 2010-2023 Contributors to the openHAB project
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ */
+package org.openhab.binding.hue.internal.config;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+
+/**
+ * Configuration for CLIP V2 things.
+ *
+ * @author Andrew Fiddian-Green - Initial contribution
+ */
+@NonNullByDefault
+public class Clip2ThingConfig {
+    public @Nullable String resourceId;
+}