[hue] Improve support for third party lights (#21062)

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>

Author: andrewfg

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

@@ -18,6 +18,7 @@
 import java.util.Set;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.binding.hue.internal.api.dto.clip2.enums.ResourceType;
 import org.openhab.core.thing.ThingTypeUID;
 import org.openhab.core.thing.type.ChannelTypeUID;
 
@@ -225,4 +226,6 @@ public class HueBindingConstants {
 
     public static final String CHANNEL_GROUP_AUTOMATION = "automation";
     public static final ChannelTypeUID CHANNEL_TYPE_AUTOMATION = new ChannelTypeUID(BINDING_ID, "automation-enable");
+
+    public static final Set<ResourceType> LIGHT_TYPES = Set.of(ResourceType.LIGHT, ResourceType.GROUPED_LIGHT);
 }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/ColorTemperature.java

@@ -16,7 +16,6 @@
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
-import org.openhab.binding.hue.internal.exceptions.DTOPresentButEmptyException;
 import org.openhab.core.library.types.QuantityType;
 import org.openhab.core.library.unit.Units;
 
@@ -30,20 +29,20 @@
 @NonNullByDefault
 public class ColorTemperature {
     private @Nullable Long mirek;
+    private @Nullable @SerializedName("mirek_valid") Boolean mirekValid;
     private @Nullable @SerializedName("mirek_schema") MirekSchema mirekSchema;
 
     /**
      * Get the color temperature as a QuantityType value.
      *
      * @return a QuantityType value
-     * @throws DTOPresentButEmptyException to indicate that the DTO is present but empty.
      */
-    public @Nullable QuantityType<?> getAbsolute() throws DTOPresentButEmptyException {
+    public @Nullable QuantityType<?> getAbsolute() {
         Long mirek = this.mirek;
         if (Objects.nonNull(mirek)) {
             return QuantityType.valueOf(mirek, Units.MIRED).toInvertibleUnit(Units.KELVIN);
         }
-        throw new DTOPresentButEmptyException("'color_temperature' DTO is present but empty");
+        return null;
     }
 
     public @Nullable Long getMirek() {
@@ -54,33 +53,23 @@ public class ColorTemperature {
         return mirekSchema;
     }
 
-    /**
-     * Get the color temperature as a percentage based on the MirekSchema. Note: this method is only to be used on
-     * cached state DTOs which already have a defined mirek schema.
-     *
-     * @return the percentage of the mirekSchema range.
-     * @throws DTOPresentButEmptyException to indicate that the DTO is present but empty.
-     */
-    public @Nullable Double getPercent() throws DTOPresentButEmptyException {
-        Long mirek = this.mirek;
-        if (Objects.nonNull(mirek)) {
-            MirekSchema mirekSchema = this.mirekSchema;
-            mirekSchema = Objects.nonNull(mirekSchema) ? mirekSchema : MirekSchema.DEFAULT_SCHEMA;
-            double min = mirekSchema.getMirekMinimum();
-            double max = mirekSchema.getMirekMaximum();
-            double percent = 100f * (mirek.doubleValue() - min) / (max - min);
-            return Math.max(0, Math.min(100, percent));
-        }
-        throw new DTOPresentButEmptyException("'mirek_schema' DTO is present but empty");
+    public boolean isMirekValid() {
+        Boolean mirekValid = this.mirekValid;
+        return mirekValid != null ? mirekValid && (mirek != null) : false;
     }
 
-    public ColorTemperature setMirek(double mirek) {
-        this.mirek = Math.round(mirek);
+    public ColorTemperature setMirek(@Nullable Long mirek) {
+        this.mirek = mirek;
         return this;
     }
 
     public ColorTemperature setMirekSchema(@Nullable MirekSchema mirekSchema) {
         this.mirekSchema = mirekSchema;
         return this;
     }
+
+    @Override
+    public boolean equals(@Nullable Object obj) {
+        return (obj instanceof ColorTemperature c && mirek instanceof Long m) ? m.equals(c.getMirek()) : false;
+    }
 }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/ColorTemperatureDelta.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2010-2026 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.api.dto.clip2;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.hue.internal.api.dto.clip2.enums.ActionDeltaType;
+import org.openhab.core.library.types.IncreaseDecreaseType;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * DTO for color temperature delta of a light.
+ *
+ * @author Andrew Fiddian-Green - Initial contribution
+ */
+@NonNullByDefault
+public class ColorTemperatureDelta {
+    private @Nullable String action;
+    private @SerializedName("mirek_delta") int mirekDelta;
+
+    public @Nullable String getAction() {
+        return action;
+    }
+
+    public int getMirekDelta() {
+        return mirekDelta;
+    }
+
+    public ColorTemperatureDelta setAction(IncreaseDecreaseType action) {
+        this.action = ActionDeltaType.of(action).name().toLowerCase();
+        return this;
+    }
+
+    public ColorTemperatureDelta setDelta(int mirekDelta) {
+        this.mirekDelta = mirekDelta;
+        return this;
+    }
+}

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/ColorXy.java

@@ -16,7 +16,6 @@
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
-import org.openhab.binding.hue.internal.exceptions.DTOPresentButEmptyException;
 import org.openhab.core.util.ColorUtil.Gamut;
 
 /**
@@ -38,15 +37,8 @@ public class ColorXy {
         return this.gamut;
     }
 
-    /**
-     * @throws DTOPresentButEmptyException to indicate that the DTO is present but empty.
-     */
-    public double[] getXY() throws DTOPresentButEmptyException {
-        PairXy pairXy = this.xy;
-        if (Objects.nonNull(pairXy)) {
-            return pairXy.getXY();
-        }
-        throw new DTOPresentButEmptyException("'color' DTO is present but empty");
+    public @Nullable PairXy getXY() {
+        return xy;
     }
 
     public ColorXy setGamut(@Nullable Gamut gamut) {
@@ -61,4 +53,13 @@ public ColorXy setXY(double[] xyValues) {
         this.xy = pairXy;
         return this;
     }
+
+    public void setXY(@Nullable PairXy xy) {
+        this.xy = xy;
+    }
+
+    @Override
+    public boolean equals(@Nullable Object obj) {
+        return (this == obj) || ((xy instanceof PairXy p && obj instanceof ColorXy c) ? p.equals(c.getXY()) : false);
+    }
 }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/Dimming.java

@@ -16,7 +16,6 @@
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
-import org.openhab.binding.hue.internal.exceptions.DTOPresentButEmptyException;
 
 import com.google.gson.annotations.SerializedName;
 
@@ -30,33 +29,15 @@ public class Dimming {
     private @Nullable Double brightness;
     private @Nullable @SerializedName("min_dim_level") Double minimumDimmingLevel;
 
-    public static final double DEFAULT_MINIMUM_DIMMIMG_LEVEL = 0.5f;
-
-    /**
-     * @throws DTOPresentButEmptyException to indicate that the DTO is present but empty.
-     */
-    public double getBrightness() throws DTOPresentButEmptyException {
-        Double brightness = this.brightness;
-        if (Objects.nonNull(brightness)) {
-            return brightness;
-        }
-        throw new DTOPresentButEmptyException("'dimming' DTO is present but empty");
-    }
-
-    public @Nullable Double getMinimumDimmingLevel() {
-        return minimumDimmingLevel;
+    public @Nullable Double getBrightness() {
+        return brightness;
     }
 
     public Dimming setBrightness(double brightness) {
         this.brightness = brightness;
         return this;
     }
 
-    public Dimming setMinimumDimmingLevel(Double minimumDimmingLevel) {
-        this.minimumDimmingLevel = minimumDimmingLevel;
-        return this;
-    }
-
     public @Nullable String toPropertyValue() {
         Double minimumDimmingLevel = this.minimumDimmingLevel;
         if (Objects.nonNull(minimumDimmingLevel)) {

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/DimmingDelta.java

@@ -0,0 +1,49 @@
+/*
+ * Copyright (c) 2010-2026 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.api.dto.clip2;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.hue.internal.api.dto.clip2.enums.ActionDeltaType;
+import org.openhab.core.library.types.IncreaseDecreaseType;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * DTO for dimming delta of a light.
+ *
+ * @author Andrew Fiddian-Green - Initial contribution
+ */
+@NonNullByDefault
+public class DimmingDelta {
+    private @Nullable String action;
+    private @Nullable @SerializedName("brightness_delta") Double brightnessDelta;
+
+    public @Nullable String getAction() {
+        return action;
+    }
+
+    public @Nullable Double getBrightnessDelta() {
+        return brightnessDelta;
+    }
+
+    public DimmingDelta setAction(IncreaseDecreaseType action) {
+        this.action = ActionDeltaType.of(action).name().toLowerCase();
+        return this;
+    }
+
+    public DimmingDelta setDelta(Double delta) {
+        this.brightnessDelta = delta;
+        return this;
+    }
+}

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/Error.java

@@ -13,6 +13,9 @@
 package org.openhab.binding.hue.internal.api.dto.clip2;
 
 import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.openhab.binding.hue.internal.api.dto.clip2.enums.ErrorType;
+
+import com.google.gson.annotations.SerializedName;
 
 /**
  * DTO for CLIP 2 communication errors.
@@ -21,9 +24,14 @@
  */
 @NonNullByDefault
 public class Error {
+    private @SerializedName("error_code") @NonNullByDefault({}) String errorCode;
     private @NonNullByDefault({}) String description;
 
     public String getDescription() {
         return description;
     }
+
+    public ErrorType getErrorType() {
+        return ErrorType.of(errorCode);
+    }
 }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/MetaData.java

@@ -35,6 +35,10 @@ public Archetype getArchetype() {
         return Archetype.of(archetype);
     }
 
+    public String getArchetypeAsString() {
+        return getArchetype().toString();
+    }
+
     public @Nullable String getName() {
         return name;
     }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/MirekSchema.java

@@ -27,8 +27,11 @@
  */
 @NonNullByDefault
 public class MirekSchema {
-    private static final int MIN = 153;
-    private static final int MAX = 500;
+    private static final int MIN = 153; // ~6500K
+    private static final int MAX = 500; // ~2000K
+
+    private static final int MIN_ALLOWED = 50; // ~20000K
+    private static final int MAX_ALLOWED = 1000; // ~1000K
 
     public static final MirekSchema DEFAULT_SCHEMA = new MirekSchema();
 
@@ -49,6 +52,16 @@ private String toKelvin(int mirek) {
     }
 
     public String toPropertyValue() {
-        return String.format("%s .. %s", toKelvin(mirekMinimum), toKelvin(mirekMaximum));
+        return invalid() //
+                ? "%dMk .. %dMk (INVALID)".formatted(mirekMinimum, mirekMaximum)
+                : "%s .. %s".formatted(toKelvin(mirekMinimum), toKelvin(mirekMaximum));
+    }
+
+    public static int toMirek(double kelvinValue) {
+        return (int) Math.round(1000000.0 / kelvinValue);
+    }
+
+    public boolean invalid() {
+        return mirekMinimum < MIN_ALLOWED || mirekMaximum > MAX_ALLOWED || (mirekMaximum - mirekMinimum < 70);
     }
 }

bundles/org.openhab.binding.hue/src/main/java/org/openhab/binding/hue/internal/api/dto/clip2/OnState.java

@@ -12,11 +12,8 @@
  */
 package org.openhab.binding.hue.internal.api.dto.clip2;
 
-import java.util.Objects;
-
 import org.eclipse.jdt.annotation.NonNullByDefault;
 import org.eclipse.jdt.annotation.Nullable;
-import org.openhab.binding.hue.internal.exceptions.DTOPresentButEmptyException;
 
 /**
  * DTO for 'on' state of a light.
@@ -27,15 +24,8 @@
 public class OnState {
     private @Nullable Boolean on;
 
-    /**
-     * @throws DTOPresentButEmptyException to indicate that the DTO is present but empty.
-     */
-    public boolean isOn() throws DTOPresentButEmptyException {
-        Boolean on = this.on;
-        if (Objects.nonNull(on)) {
-            return on;
-        }
-        throw new DTOPresentButEmptyException("'on' DTO is present but empty");
+    public @Nullable Boolean getOn() {
+        return on;
     }
 
     public OnState setOn(boolean on) {