State machine to model lights in Thing handlers

[andrewfg]

Resolves #4994

This PR adds a comprehensive state machine class for modelling the state of lights within Thing handlers by introducing a new LightModel state machine for managing light properties like brightness, color, and color temperature.

Key changes include:

• Implementation of a complete light state model with flexible capability configuration
• Support for various light types from simple on/off to full RGB with color temperature
• Command handling for different openHAB command types (HSB, OnOff, PercentType, etc.)
• Handles inter- dependencies between on/off and brightness commands and status, and the 'B' part of HSB
• Handles inter- dependencies between color temperature commands and status, and the 'HS' part of HSB

Signed-off-by: Andrew Fiddian-Green [email protected]

[andrewfg]

Ping @lsiepel ..

[jimtng]

I don't quite understand the background for this. Why not just add whatever is missing into ColorUtils, or into HSBType, or ColorItem?

[Copilot]

Pull Request Overview

This PR introduces a comprehensive state machine class LightModel for managing light properties in Thing handlers, providing support for various light types from simple on/off to full RGB with color temperature control. It includes mathematical utilities for RGB/RGBCW conversions and handles complex inter-dependencies between brightness, color, and color temperature states.

• Implementation of a flexible light state model with configurable capabilities
• Command handling for different openHAB command types (HSB, OnOff, PercentType, etc.)
• Mathematical conversion utilities between RGB, RGBW, and RGBCW color formats

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
LightModel.java	Core state machine implementation with configuration methods, runtime state management, and internal RGBCW math utilities
LightModelTest.java	Comprehensive test suite covering all light types, command handling, color conversions, and edge cases

Comments suppressed due to low confidence (1)

bundles/org.openhab.core/src/main/java/org/openhab/core/util/LightModel.java:1

• The magic number 25500 appears twice without explanation. This should be extracted to a named constant with a descriptive comment explaining that it's 255 * 100 for scaling normalized values to [0..255] range.

/*

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

Pull Request Overview

This PR introduces a comprehensive light state machine model to simplify light control in Thing handlers by providing a unified approach for managing different light capabilities and handling complex inter-dependencies between brightness, color, and color temperature commands.

• Implementation of a complete LightModel state machine with flexible capability configuration supporting various light types
• Support for complex RGB data types including RGBCW with mathematical conversion utilities
• Addition of abstract BaseLightThingHandler base class to standardize light Thing handler implementations

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
LightModelTest.java	Comprehensive unit tests covering all light capabilities, RGB conversions, and RGBCW mathematical operations
LightModel.java	Core state machine implementation with configuration, runtime state management, and color conversion utilities
BaseLightThingHandler.java	Abstract base class providing standardized structure for light Thing handlers using the LightModel

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[andrewfg]

@ccutrer thanks for the LGTM..

.. however having seen the PR for Wiz where he has lights that flip from color mode to color temperature mode (and I think I saw this also in Govee) .. probably I should tweak the code in this PR to address that.

[openhab-bot]

This pull request has been mentioned on openHAB Community. There might be relevant details there:

https://community.openhab.org/t/esphome-binding-for-the-native-api-4-0-0-6-0-0/146849/434

[andrewfg]

I am using a clone of this code this in my new HomeKit binding here. Note that once this PR will have been merged the clone in that binding can be deleted and instead linked to use this library.