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)
• 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: Add documentation for new WMS WebControl pro integration home-assistant.io#34353

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]

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

[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:

core/homeassistant/components/wmspro/generic_entity.py

Lines 13 to 51 in 3a67cda

	class WebControlProGenericEntity(Entity):
	"""Foundation of all WMS based entities."""
	_attr_attribution = ATTRIBUTION
	_attr_has_entity_name = True
	_attr_name = None
	def __init__(self, dest: Destination) -> None:
	"""Initialize the entity with destination channel."""
	super().__init__()
	self._dest = dest
	async def async_update(self) -> None:
	"""Update the entity."""
	await self._dest.refresh()
	@property
	def unique_id(self) -> str:
	"""Return a unique ID."""
	return f"{self.__class__.__name__}_{self._dest.id}"
	@property
	def available(self) -> bool:
	"""Return if entity is available."""
	return self._dest.available
	@property
	def device_info(self) -> DeviceInfo | None:
	"""Return device specific attributes."""
	return DeviceInfo(
	identifiers={(DOMAIN, self.unique_id)},
	manufacturer=MANUFACTURER,
	model=self._dest.animationType.name,
	name=self._dest.name,
	serial_number=self._dest.id,
	suggested_area=self._dest.room.name,
	via_device=(DOMAIN, self._dest.host),
	configuration_url=f"http://{self._dest.host}/control",
	)

[mback2k]

The PR has reached 100% test coverage now 🎉

[home-assistant]

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

Learn more about our pull request process.

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

[joostlek]

Last comments

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