Added recognized options to Home Connect actions

[Diegorro98]

Breaking change

Proposed change

Actions in Home Connect now have recognized options that will allow the user to easily choose options for their programs when starting and selecting a program and changing options of a already selected and started program.

These options are grouped based on the options for each appliance type, just like API documentation.

There are also custom options key at services where the users can use option keys that are not recognized here, and can be multiple options (before only one option was available per service call). Also is an easy way to migrate from the old action payload. So old action keys key, value, and units are being deprecated (An issue will be generated).

Program keys can be still be used like always at start and select program actions, but the user can select one of the recognized programs from the selector.

Also ServiceValidationError exceptions have been added to give direct feedback to the user.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[home-assistant]

Hey there @DavidMStraub, mind taking a look at this pull request as it has been labeled with an integration (home_connect) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of home_connect can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign home_connect Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[Diegorro98]

I let this PR as a draft until #126157 is merged, as both use some common things

[Diegorro98]

The action options doesn't have descriptions because I was thinking to use the same descriptions than API documentation have, but I wanted to hear opinions about that.

[Diegorro98]

Because this services.yaml and strings have become huge, I though that for a future PR maybe start and select actions can be merged into just one action with an option that could allow to start or select the program.

Same for the services that allow to set options to selected and active programs.

[Diegorro98]

@boergegrunicke, these are the action changes I mentioned to you the other day. Please let me know your thoughts. :)

[boergegrunicke]

@Diegorro98 For my first try, I don't see anything anymore. From previous tests, I had a bunch of duplicated entities, so I completely reinitialized the HomeAssistant integration. My dishwasher is still not cooperative

2024-11-15 22:21:51.348 ERROR (MainThread) [homeassistant.components.home_connect.switch] An error occurred: {'description': 'HomeAppliance is offline', 'key': 'SDK.Error.HomeAppliance.Connection.Initialization.Failed'}

But also the coffee maker does not have any useful entities:

(That is all!)

[Diegorro98]

@boergegrunicke Well, despite that problem, you can check the how the actions look now.

But about the problem, because this unrelated to the PR, I'm going to answer you here once, but please if you need further discussion, use the already created issues or a new issue.
I can't diagnostic what is happening to your Coffeemaker without more info, we should get some diagnostics. Please, checkout the #130500, download the diagnostics, and send it to a new Issue or a related issue.

[boergegrunicke]

@Diegorro98 Sorry, I guess I was tired and searching for something completely wrong.

One small thing: In the select_program service, all options are translated, in the start_program, I see only the keys, but not the "translated" strings.

It is a little bit sad, that always all options are available for all devices (I could select a drying target for a coffee maker or a coffee-milk-ration for the dishwasher). Also, I could select features that my device does not have, like choosing the second bean tray, while my coffee maker has only one.
Anyway, I think it is much better to have all these options controllable than being limited like previously.

[Diegorro98]

One small thing: In the select_program service, all options are translated, in the start_program, I see only the keys, but not the "translated" strings.

My bad, because a previous version of this idea unified select and start program, I forgot to add start program translation keys again. I already fixed it.

It is a little bit sad, that always all options are available for all devices (I could select a drying target for a coffee maker or a coffee-milk-ration for the dishwasher). Also, I could select features that my device does not have, like choosing the second bean tray, while my coffee maker has only one.

Options could be filtered, but there are two problems that doesn't allow that:

1. To achieve that filtering, we should know which options are available for each program, because there are cases where not all programs have the same options, and that would require an API request.
2. Filters are only available for actions that use a target and the selected target is an entity. We would need filter by device type and program (and its options)

In the end, if any of the options are not supported by your device or by your program, you will get a direct feedback with info about the error thanks to the ServiceErrorValidation exceptions.
Also, the service UI is just a helper to help you to easily achieve the right program with the right options. Is not something that you will see always, you will use action calls that you know that work.

Anyway, I think it is much better to have all these options controllable than being limited like previously.

Thanks! 😊