Add new integration for WMS WebControl pro using local API

[mback2k]

Proposed change

Warema recently released a new local API for their WMS hub called "WebControl pro". This integration makes use of the new local API via a new dedicated Python library pywmspro.

For now this integration only supports awnings as covers, but pywmspro is device-agnostic to ease extensions. I will try to add support for more devices in future PRs. I have already developed and tested lights and scenes locally.

Python library: https://github.com/mback2k/pywmspro and https://pypi.org/project/pywmspro/ Official API documentation, unfortunately only available in German at the moment: https://media.warema.com/dokumente/anleitungen-handbuecher/966664/warema_2064534_alhb_de_v0.pdf

Type of change

• [ ] Dependency upgrade
• [ ] Bugfix (non-breaking change which fixes an issue)
• [x] 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

• This PR fixes or closes issue: fixes #
• This PR is related to issue:
• Link to documentation pull request: https://github.com/home-assistant/home-assistant.io/pull/34353

Checklist

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

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

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

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

• [x] The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• [x] 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.

[mback2k]

When adding new integrations, limit included platforms to a single platform. Please reduce this PR to a single platform

Is this a must or a should? I am asking this, because I tried to limit the amount of platforms/devices to a useful minimum for the initial PR. Which platform should I keep to introduce this integration to Home Assistant?

Human reviewers, please consider that the WMS WebControl pro is a hub/gateway with support for various devices types, similar to Homematic IP for example.

[mback2k]

When adding new integrations, limit included platforms to a single platform. Please reduce this PR to a single platform

Is this a must or a should? I am asking this, because I tried to limit the amount of platforms/devices to a useful minimum for the initial PR. Which platform should I keep to introduce this integration to Home Assistant?

Human reviewers, please consider that the WMS WebControl pro is a hub/gateway with support for various devices types, similar to Homematic IP for example.

Okay, I just updated this PR to only include support for scenes for now.

[joostlek]

I'd recommend using a stateful platform first like light or cover

[mback2k]

I will follow up with cover and light in separate PRs since I have it ready locally, but scenes would allow at least versatile indirect control already.

[joostlek]

Yes, but handling a state in your integration is probably the most interesting part which also defines how your data flows between entities, while a scene is just something you can turn on. So I'd rather pick a more complex one to make sure we make the best choices to keep the integration extendable and efficient

[mback2k]

Ok, will do the change then. Adding more than one platform is not an option right? Because I have lights, awnings and scenes fully working. Rotating PR content and documentation is quite cumbersome.

[mback2k]

Switched the PR from scenes to awnings as covers now.

Yes, but handling a state in your integration is probably the most interesting part which also defines how your data flows between entities

The cover platform now shows how pywmspro is used and that I followed the rules described in the developer docs. Communication to the hub is only done to perform actions or on an async_update call, otherwise entity/device information is retrieved from the local object in pywmspro. The class WebControlProGenericEntity is going to be the base for all entities/devices and illustrates this approach: https://github.com/home-assistant/core/blob/3a67cda74f314150c2a82d27e3dd232e286355bd/homeassistant/components/wmspro/generic_entity.py#L13-L51

[mback2k]

The PR has reached 100% test coverage now 🎉

[home-assistant[bot]]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks :+1:

Learn more about our pull request process.

[joostlek]

Main code is almost complete, few remarks there, now had a first look at the tests

[mback2k]

I must say: This is starting to become a little bit frustrating, it feels like chasing a moving target...

[joostlek]

I am also becoming a bit frustrated because I somehow always end up in a defending mode and I don't want to be in that mode

[mback2k]

I am just trying to understand the reasoning behind your comments, especially since I tried to follow the developer documentation and examples available in the codebase. I am going to push a few updates soon, hopefully this will bring us closer, but I guess the biggest gap will be the mocking part now.

[joostlek]

I think one thing to understand is that the dev docs are quite shit and not completely up to date, In the last year I learnt a lot of the codebase and I do want to update the docs, but it's on my todo list.

[mback2k]

Okay, I tried to incorporate more feedback. Can you please elaborate which of the parts regarding a) different mocking, b) parameterized tests and c) snapshot tests would be important/required to get this merged?

And of course I am now also curious why the cover component needs to be explicitly loaded/setup.

But I am done for today.

[joostlek]

Understandable, have a good night, I will probably check the code out tomorrow. Do you have discord?

[mback2k]

Yes, I am on Discord with the same username, just pinged you there. Have a good night, too.

Question to consider regarding the mocking for tomorrow: would it be okay if pywmspro provided a demo mock mode?

With that I mean, I could move the JSON fixtures there (since I will need to develop tests there anyway), add a simulation mode to the library classes and then use that during testing in HA.

[mback2k]

I have now implemented everything except the requested complete change of mocking approach.

If the main reason for the requested mock style is to not touch library internals in HA tests, I would suggest to move this type of simulated mocking into the library as described above. This way end-to-end tests could be simulated.

[mback2k]

Thanks a lot @joostlek !

[joostlek]

Ugh, I always realize this too late. Let me double check if others think wmspro is a good domain name. It could be that others have a better opinion on it

[mback2k]

Ugh, I always realize this too late. Let me double check if others think wmspro is a good domain name. It could be that others have a better opinion on it

Ah, good point. Alternatives could be "wmswebcontrolpro", "webcontrolpro", "warema_wms" or any more detailed combination of "Warema" as vendor, "WMS" as protocol and "WebControl pro" as required hub.