Add LevelControl out of band API

[hicklin]

This PR adds an out-of-band API to the LevelControl cluster. The API allows SDK consumers to notify the LevelControlHandler if the device's level has change out-of-band, allowing the handler to update the Matter state. Additionally, this API provides calling matter commands, allowing consistent behaviour between Matter and out-of-band interactions.

Further changes made in this PR

• set_level and write_remaining_time_quietly no longer notify Matter but return a boolean indicating if the caller should notify Matter. This enables only one Matter notification when these methods are used in the same execution.
• Improves the move_to_level_transition logic to handle transition_time = 0.
• move_to_level is split into a blocking and non-blocking version. This removes the need for the non-blocking version to be async, enabling calls from non-async methods, namely handle_out_of_band_message.
• Adds AttributeDefaults::with_optional_defaults.

[gemini-code-assist]

Summary of Changes

Hello @hicklin, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the LevelControl cluster by introducing an out-of-band API, allowing external device interactions to seamlessly update the Matter state and trigger Matter commands. It refactors internal notification mechanisms to optimize Matter attribute reporting and improves the flexibility of level transition handling by splitting core functions into blocking and non-blocking variants. Additionally, a new constructor simplifies the initialization of LevelControl attributes, making the API more robust and easier to use.

Highlights

• Out-of-Band API for LevelControl: Introduced a new API allowing external systems to notify the LevelControl cluster of level changes or to initiate Matter commands (MoveToLevel, Move, Step, Stop) out-of-band, ensuring the Matter state remains synchronized with physical device actions.
• Refactored Notification Logic: The set_level and write_remaining_time_quietly methods now return a boolean indicating whether a Matter notification is required, enabling consolidated notifications and preventing redundant updates when multiple state changes occur within a single execution.
• Split move_to_level Functionality: The move_to_level function has been split into a non-blocking version (for internal task signaling) and a new move_to_level_blocking (for direct, awaited calls), removing the async requirement from the non-blocking variant and improving flexibility.
• Improved Transition Handling: The move_to_level_transition logic has been enhanced to correctly handle cases where the transition_time is zero, ensuring immediate level changes when no transition period is specified.
• New AttributeDefaults Constructor: Added AttributeDefaults::with_optional_defaults to simplify the initialization of LevelControl attributes with sensible default values for optional fields.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable out-of-band API for the LevelControl cluster, allowing for better integration with non-Matter device state changes. The refactoring to separate state updates from notifications and the split of move_to_level into blocking and non-blocking versions are excellent design choices that improve the flexibility and robustness of the handler. My review includes a few suggestions to further enhance maintainability and safety, such as refactoring duplicated code and avoiding a potential panic.

[ivmarkov]

I have just a minor comment on the new AttributeDetails::with_optional_defaults.

The rest looks fine!