[shelly] Consolidate light API component handling into ShellyApiLightUtil with type-safe enum

Replace scattered profile.device.profile string-equality checks
(SHELLY2_PROFILE_CCTX2.equals(...) etc.) and RPC-method-name
comparisons with static isColorComponent/isRgbComponent/
isRgbwComponent/isCctComponent/isLightComponent(tag) helpers backed
by the settings.lights[i].apiComponent tag rather than the whole-
profile string. Add profile.isProRgbwwPm to replace the local
isProRgbwwPmProfile() duplicate, and add profile.isCctComponent(idx)
alongside the existing isColorComponent(idx). Also collapse
ShellyUtils.buildControlGroupName/buildWhiteGroupName into
profile.getControlGroup(), removing the now-redundant duplicate group
resolution logic.

The tag itself moves from a raw String ("rgb"/"rgbw"/"cct"/"light")
to a ShellyLightApiComponent enum, making an invalid tag a
compile-time impossibility instead of a silent runtime fallback to
the LIGHT RPC methods in Shelly2ApiRpc.lightRpcMethods(). The field
stays transient and is set only in
Shelly2ApiClient.createRgbwLightSetting() (Gen2-only, never
Gson-(de)serialized), so this is not a breaking change.

Static logic doesn't belong on a DTO class, so the helpers land in a
new ShellyApiLightUtil in the api package rather than on the
component tag holder itself. While at it, fold in the other
light-specific group/id helpers (getLightIdFromGroup,
lightChannelGroupPrefix, buildWhiteGroupName) that were sitting in
the generic ShellyUtils for the same reason, and add missing coverage
for the tag-lookup helpers and lightChannelGroupPrefix.

Also:
- Rename ShellyDeviceProfile.isColorComponent(int) to hasColorTag(int)
  to resolve a name collision with the unrelated, differently-scoped
  ShellyApiLightUtil.isColorComponent(ShellyLightApiComponent).
- Restore the setLightParms() fail-fast guard for non-RGBW2 profiles
  and unify its RGB/RGBW/CCT/Light dispatch onto the same
  lightRpcMethods() lookup already used elsewhere in this class.
- Document on ShellyLightApiComponent that each settings.lights index
  is an independently addressed physical component, not a sub-channel
  of one combined light - relevant for PR openhab#21286's OH Core LightModel
  work, whose Pro RGBWW PM branch currently assumes one model per
  whole-device profile string.

Signed-off-by: Markus Michels <markus7017@gmail.com>

Author: markus7017

bundles/org.openhab.binding.shelly/src/main/java/org/openhab/binding/shelly/internal/api/ShellyApiLightUtil.java

@@ -0,0 +1,121 @@
+/*
+ * 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.shelly.internal.api;
+
+import static org.openhab.binding.shelly.internal.ShellyBindingConstants.*;
+import static org.openhab.binding.shelly.internal.util.ShellyUtils.substringAfter;
+
+import java.util.List;
+
+import org.eclipse.jdt.annotation.NonNullByDefault;
+import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.shelly.internal.api1.Shelly1ApiJsonDTO.ShellySettingsRgbwLight;
+
+/**
+ * The {@link ShellyApiLightUtil} provides light-specific helpers shared by Gen1 (api1) and Gen2+ (api2) code:
+ * the {@code settings.lights[i].apiComponent} tag values used to identify which light API component family (RGB,
+ * RGBW, CCT or plain Light) a {@code ShellySettingsRgbwLight} entry belongs to, and the light channel group/id
+ * resolution shared across handlers.
+ *
+ * @author Markus Michels - Initial contribution
+ */
+@NonNullByDefault
+public class ShellyApiLightUtil {
+    private ShellyApiLightUtil() {
+    }
+
+    /**
+     * The light API component family a {@code settings.lights[i]} entry belongs to. {@code NONE} marks an
+     * untagged entry (a Gen1 RGBW2/Bulb entry never sets apiComponent) or an out-of-range index.
+     * <p>
+     * Each index is an independently switchable/dimmable/metered physical component - not a sub-channel of one
+     * combined light. A hybrid Pro RGBWW PM profile (e.g. {@code rgbcct}, {@code rgbx2light}) reports its color
+     * component (RGB/RGBW) and its secondary CCT/Light component(s) as separate {@code settings.lights} indices,
+     * each with its own RPC methods and meter - never merged into a single multi-channel model.
+     */
+    public enum ShellyLightApiComponent {
+        RGB,
+        RGBW,
+        CCT,
+        LIGHT,
+        NONE
+    }
+
+    /**
+     * True when tag identifies an RGB/RGBW color component, as opposed to a CCT/Light one.
+     */
+    public static boolean isColorComponent(ShellyLightApiComponent apiComponent) {
+        return apiComponent == ShellyLightApiComponent.RGB || apiComponent == ShellyLightApiComponent.RGBW;
+    }
+
+    public static boolean isRgbComponent(ShellyLightApiComponent apiComponent) {
+        return apiComponent == ShellyLightApiComponent.RGB;
+    }
+
+    public static boolean isRgbwComponent(ShellyLightApiComponent apiComponent) {
+        return apiComponent == ShellyLightApiComponent.RGBW;
+    }
+
+    public static boolean isCctComponent(ShellyLightApiComponent apiComponent) {
+        return apiComponent == ShellyLightApiComponent.CCT;
+    }
+
+    public static boolean isLightComponent(ShellyLightApiComponent apiComponent) {
+        return apiComponent == ShellyLightApiComponent.LIGHT;
+    }
+
+    /**
+     * The apiComponent tag of {@code lights.get(idx)}, or {@code NONE} when lights is null, idx is out of range,
+     * or the entry is untagged (a Gen1 RGBW2/Bulb entry never sets apiComponent).
+     */
+    public static ShellyLightApiComponent tagAt(@Nullable List<ShellySettingsRgbwLight> lights, int idx) {
+        return lights != null && idx >= 0 && idx < lights.size() ? lights.get(idx).apiComponent
+                : ShellyLightApiComponent.NONE;
+    }
+
+    /**
+     * True when any entry in lights is an RGB/RGBW color component.
+     */
+    public static boolean hasColorComponent(List<ShellySettingsRgbwLight> lights) {
+        return lights.stream().map(l -> l.apiComponent).anyMatch(ShellyApiLightUtil::isColorComponent);
+    }
+
+    public static Integer getLightIdFromGroup(String groupName) {
+        if (groupName.startsWith(CHANNEL_GROUP_LIGHT_INDEX)) {
+            return Integer.parseInt(substringAfter(groupName, CHANNEL_GROUP_LIGHT_INDEX)) - 1;
+        }
+        if (groupName.startsWith(CHANNEL_GROUP_LIGHT_CHANNEL)) {
+            return Integer.parseInt(substringAfter(groupName, CHANNEL_GROUP_LIGHT_CHANNEL)) - 1;
+        }
+        return 0; // only 1 light, e.g. bulb or rgbw2 in color mode
+    }
+
+    // Gen2 RGBW PM ships on light1..n natively. A Gen1 RGBW2 Thing that already carries the
+    // deprecated channel1..n group (from before this Thing was migrated) keeps publishing there,
+    // dual-written to light1..n by ShellyBaseHandler.updateChannel(); a freshly discovered Gen1
+    // RGBW2 Thing goes straight to light1..n and never gets a channel1..n group.
+    public static String lightChannelGroupPrefix(ShellyDeviceProfile profile) {
+        return profile.isGen2 || !profile.hasLegacyLightChannels ? CHANNEL_GROUP_LIGHT_INDEX
+                : CHANNEL_GROUP_LIGHT_CHANNEL;
+    }
+
+    // Bulb/Duo report white/temp under a dedicated group, distinct from their color group; everything else
+    // (including a hybrid Pro RGBWW PM profile's secondary CCT/Light component) shares the same per-component
+    // group resolution as the color channels, so this just delegates to getControlGroup().
+    public static String buildWhiteGroupName(ShellyDeviceProfile profile, int lightId) {
+        if (profile.isBulb || profile.isDuo) {
+            return CHANNEL_GROUP_WHITE_CONTROL;
+        }
+        return profile.getControlGroup(lightId);
+    }
+}

bundles/org.openhab.binding.shelly/src/main/java/org/openhab/binding/shelly/internal/api/ShellyDeviceProfile.java

@@ -14,6 +14,7 @@
 
 import static org.openhab.binding.shelly.internal.ShellyBindingConstants.*;
 import static org.openhab.binding.shelly.internal.ShellyDevices.*;
+import static org.openhab.binding.shelly.internal.api.ShellyApiLightUtil.*;
 import static org.openhab.binding.shelly.internal.api1.Shelly1ApiJsonDTO.*;
 import static org.openhab.binding.shelly.internal.util.ShellyUtils.*;
 
@@ -95,6 +96,8 @@ public class ShellyDeviceProfile {
     public boolean isBulb; // true only if it is a Bulb
     public boolean isDuo; // true only if it is a Duo
     public boolean isRGBW2; // true only if it a RGBW2
+    public boolean isProRgbwwPm; // true only for a Shelly Pro RGBWW PM (device.profile alone can't tell it apart
+                                 // from a Plus RGBW PM running the same rgb/rgbw/light profile)
     public boolean inColor; // true if bulb/rgbw2 is in color mode
     public boolean hasLegacyLightChannels; // true if Thing already has deprecated Gen1 RGBW2 channel1..n groups
 
@@ -214,6 +217,7 @@ public void initFromThingType(ThingTypeUID thingTypeUID) {
         isBulb = THING_TYPE_SHELLYBULB.equals(thingTypeUID);
         isDuo = GROUP_DUO_THING_TYPES.contains(thingTypeUID);
         isRGBW2 = GROUP_RGBW2_THING_TYPES.contains(thingTypeUID);
+        isProRgbwwPm = THING_TYPE_SHELLYPRORGBWWPM.equals(thingTypeUID);
         isLight = GROUP_LIGHT_THING_TYPES.contains(thingTypeUID);
         if (isLight) {
             minTemp = isBulb ? MIN_COLOR_TEMP_BULB : MIN_COLOR_TEMP_DUO;
@@ -366,13 +370,17 @@ public int getColorComponentCount() {
      * because a hybrid profile's (rgbcct, rgbx2light) secondary component(s) are not color even though the
      * whole-profile inColor flag is true. Untagged (Gen1 RGBW2) entries fall back to that whole-profile flag.
      */
-    public boolean isColorComponent(int idx) {
-        List<ShellySettingsRgbwLight> lights = settings.lights;
-        if (lights == null || idx < 0 || idx >= lights.size()) {
-            return inColor;
-        }
-        String tag = lights.get(idx).apiComponent;
-        return tag.isEmpty() ? inColor : ("rgb".equals(tag) || "rgbw".equals(tag));
+    public boolean hasColorTag(int idx) {
+        ShellyLightApiComponent tag = tagAt(settings.lights, idx);
+        return tag == ShellyLightApiComponent.NONE ? inColor : ShellyApiLightUtil.isColorComponent(tag);
+    }
+
+    /**
+     * True when settings.lights[idx] is a CCT (color temperature) component - Gen2 only, untagged Gen1 entries are
+     * never CCT.
+     */
+    public boolean isCctComponent(int idx) {
+        return ShellyApiLightUtil.isCctComponent(tagAt(settings.lights, idx));
     }
 
     public String getInputGroup(int i) {

bundles/org.openhab.binding.shelly/src/main/java/org/openhab/binding/shelly/internal/api1/Shelly1ApiJsonDTO.java

@@ -16,6 +16,7 @@
 import java.util.List;
 
 import org.eclipse.jdt.annotation.Nullable;
+import org.openhab.binding.shelly.internal.api.ShellyApiLightUtil.ShellyLightApiComponent;
 import org.openhab.binding.shelly.internal.api1.Shelly1ApiJsonDTO.ShellyStatusSensor.ShellyMotionSettings;
 import org.openhab.binding.shelly.internal.api2.Shelly2ApiJsonDTO.Shelly2APClientList;
 import org.openhab.core.thing.CommonTriggerEvents;
@@ -522,8 +523,8 @@ public static class ShellySettingsRgbwLight {
         @SerializedName("out_off_url")
         public String outOffUrl; // output is deactivated
 
-        // Gen2 (Pro RGBWW PM) only: which RPC component this entry maps to, see Shelly2ApiRpc.API_COMPONENT_*
-        public transient String apiComponent = "";
+        // Gen2 (Pro RGBWW PM) only: which RPC component this entry maps to, see ShellyApiLightUtil
+        public transient ShellyLightApiComponent apiComponent = ShellyLightApiComponent.NONE;
     }
 
     public static class ShellyFavPos { // FW 1.9.2+ in roller mode

bundles/org.openhab.binding.shelly/src/main/java/org/openhab/binding/shelly/internal/api1/Shelly1CoIoTProtocol.java

@@ -13,6 +13,7 @@
 package org.openhab.binding.shelly.internal.api1;
 
 import static org.openhab.binding.shelly.internal.ShellyBindingConstants.*;
+import static org.openhab.binding.shelly.internal.api.ShellyApiLightUtil.*;
 import static org.openhab.binding.shelly.internal.api1.Shelly1ApiJsonDTO.*;
 import static org.openhab.binding.shelly.internal.util.ShellyUtils.*;
 

bundles/org.openhab.binding.shelly/src/main/java/org/openhab/binding/shelly/internal/api2/Shelly2ApiClient.java

@@ -14,6 +14,7 @@
 
 import static org.openhab.binding.shelly.internal.ShellyBindingConstants.CHANNEL_INPUT;
 import static org.openhab.binding.shelly.internal.ShellyDevices.THING_TYPE_SHELLYPRORGBWWPM;
+import static org.openhab.binding.shelly.internal.api.ShellyApiLightUtil.*;
 import static org.openhab.binding.shelly.internal.api1.Shelly1ApiJsonDTO.*;
 import static org.openhab.binding.shelly.internal.api2.Shelly2ApiJsonDTO.*;
 import static org.openhab.binding.shelly.internal.util.ShellyUtils.*;
@@ -854,12 +855,6 @@ private void updateComponentMeter(ShellySettingsStatus status, int meterIdx, @Nu
         updateMeter(status, meterIdx, emeter, channelUpdate);
     }
 
-    private boolean isProRgbwwPmProfile(ShellyDeviceProfile profile) {
-        String p = profile.device.profile;
-        return SHELLY2_PROFILE_RGBCCT.equals(p) || SHELLY2_PROFILE_CCTX2.equals(p)
-                || SHELLY2_PROFILE_RGBX2LIGHT.equals(p);
-    }
-
     /**
      * Convert aenergy.by_minute (mWh per complete minute, up to 3 slots) to Wh.
      * Returns null when the device did not report a usable slot 0 (e.g. clock not synced).
@@ -1222,13 +1217,17 @@ protected void fillRgbwSettings(ShellyDeviceProfile profile, Shelly2GetConfigRes
             return;
         }
 
-        record Candidate(String apiComponent, @Nullable Shelly2GetConfigLight config) {
+        record Candidate(ShellyLightApiComponent apiComponent, @Nullable Shelly2GetConfigLight config) {
         }
-        List<Candidate> candidates = List.of(new Candidate(API_COMPONENT_RGBW, dc.rgbw0),
-                new Candidate(API_COMPONENT_RGB, dc.rgb0), new Candidate(API_COMPONENT_CCT, dc.cct0),
-                new Candidate(API_COMPONENT_CCT, dc.cct1), new Candidate(API_COMPONENT_LIGHT, dc.light0),
-                new Candidate(API_COMPONENT_LIGHT, dc.light1), new Candidate(API_COMPONENT_LIGHT, dc.light2),
-                new Candidate(API_COMPONENT_LIGHT, dc.light3), new Candidate(API_COMPONENT_LIGHT, dc.light4));
+        List<Candidate> candidates = List.of(new Candidate(ShellyLightApiComponent.RGBW, dc.rgbw0),
+                new Candidate(ShellyLightApiComponent.RGB, dc.rgb0),
+                new Candidate(ShellyLightApiComponent.CCT, dc.cct0),
+                new Candidate(ShellyLightApiComponent.CCT, dc.cct1),
+                new Candidate(ShellyLightApiComponent.LIGHT, dc.light0),
+                new Candidate(ShellyLightApiComponent.LIGHT, dc.light1),
+                new Candidate(ShellyLightApiComponent.LIGHT, dc.light2),
+                new Candidate(ShellyLightApiComponent.LIGHT, dc.light3),
+                new Candidate(ShellyLightApiComponent.LIGHT, dc.light4));
 
         ArrayList<ShellySettingsRgbwLight> lights = new ArrayList<>();
         for (Candidate c : candidates) {
@@ -1240,12 +1239,12 @@ record Candidate(String apiComponent, @Nullable Shelly2GetConfigLight config) {
         if (lights.isEmpty()) {
             lights.add(new ShellySettingsRgbwLight());
         }
-        profile.inColor = lights.stream()
-                .anyMatch(l -> API_COMPONENT_RGB.equals(l.apiComponent) || API_COMPONENT_RGBW.equals(l.apiComponent));
+        profile.inColor = hasColorComponent(lights);
         profile.settings.lights = lights;
     }
 
-    private ShellySettingsRgbwLight createRgbwLightSetting(Shelly2GetConfigLight src, String apiComponent) {
+    private ShellySettingsRgbwLight createRgbwLightSetting(Shelly2GetConfigLight src,
+            ShellyLightApiComponent apiComponent) {
         ShellySettingsRgbwLight ls = new ShellySettingsRgbwLight();
         ls.autoOn = src.autoOnDelay;
         ls.autoOff = src.autoOffDelay;
@@ -1304,7 +1303,7 @@ private boolean updateRGBWStatus(int id, ShellySettingsStatus status, @Nullable
         ds.ison = value.output;
 
         status.lights.set(rgbwId, ds);
-        if (isProRgbwwPmProfile(profile)) {
+        if (profile.isProRgbwwPm) {
             // the color component always sits at settings.lights[0]
             updateComponentMeter(status, 0, value.apower, value.aenergy, value.voltage, value.current, channelUpdate);
         }
@@ -1344,7 +1343,7 @@ private boolean updateLightModeStatus(int id, ShellySettingsStatus status, @Null
             ds.temp = ct;
         }
         lights.set(lightId, ds);
-        if (isProRgbwwPmProfile(profile)) {
+        if (profile.isProRgbwwPm) {
             // Plus RGBW PM's white-mode light0..3 channels also reach this point but must not be metered here
             updateComponentMeter(status, lightId, value.apower, value.aenergy, value.voltage, value.current,
                     channelUpdate);

bundles/org.openhab.binding.shelly/src/main/java/org/openhab/binding/shelly/internal/api2/Shelly2ApiJsonDTO.java

@@ -114,13 +114,6 @@ public class Shelly2ApiJsonDTO {
     public static final String SHELLY2_PROFILE_CCTX2 = "cctx2"; // Pro RGBWW PM: CCT:0 + CCT:1
     public static final String SHELLY2_PROFILE_RGBX2LIGHT = "rgbx2light"; // Pro RGBWW PM: RGB:0 + Light:0/1
 
-    // Pro RGBWW PM: settings.lights[i].apiComponent tag, selects which RPC component family (and thus which
-    // Light.*/RGB.*/RGBW.*/CCT.* method) an index maps to - see Shelly2ApiRpc.LIGHT_RPC_METHODS
-    public static final String API_COMPONENT_RGB = "rgb";
-    public static final String API_COMPONENT_RGBW = "rgbw";
-    public static final String API_COMPONENT_CCT = "cct";
-    public static final String API_COMPONENT_LIGHT = "light";
-
     // Button types/modes
     public static final String SHELLY2_BTNT_MOMENTARY = "momentary";
     public static final String SHELLY2_BTNT_FLIP = "flip";