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

[lsiepel]

Thanks, LGTM

Do we need to extend documentation for developers?

[andrewfg]

Do we need to extend documentation for developers?

Yes that makes sense. I am not sure where though..

EDIT: probably we need a whole new chapter to describe all the OH core utility functions. (Maybe also the OH standard channel types..)

EDIT2: or maybe in FrameWork Tools ?