client.py My model is not working with HA 2024.12 and newer

With Home Assistant 2024.12, I removed the fallback vacuum as it created more trouble than it solved. If your model is not already added to this library, you will get a similar log entry:

Device "[Name]" not supported. Please add support for it to https://github.com/DeebotUniverse/client.py: ...

Unfortunately, Ecovacs does not provide any API information, so the maintainers of this library can't add your model. To add your model, follow the instructions below: Write to Ecovacs support and ask them to provide API documentation. If enough people write it, they may release the API publicly.

Please check if a similar model has already been added to https://github.com/DeebotUniverse/client.py/tree/dev/deebot_client/hardware/deebot
- If yes, you are probably lucky, and you only need to check if your model has the same options.
  - If yes, create a symbolic link between your model and a similar one
  - If not, please copy and rename the file and update it to comply with your model
- If no similar model was added, then you need to reverse engineer your model by analyzing the traffic between the app and the Ecovacs servers. Sorry, but this cannot be avoided, as Ecovacs doesn't share any API information. You can try to contact the support, but in the past, Ecovacs did not help.
Check other PRs, maybe already someone is trying to add your model or is adding a similar model

Please also check https://github.com/DeebotUniverse/client.py/blob/dev/deebot_client/capabilities.py and other capabilities files to familiarize yourself with the schema of the required model file. Feel free to open a PR with your model and I'm happy to review it :)

I know that removing the fallback created troubles for affected users, but nobody checked the log entries in the past, or users silently ignored it until it broke. After removing the fallback in a single day, more models were added as in the last whole year. So, from the maintainer's perspective, this was the right path forward.

Dec 05 '24 08:12 edenhaus

I appreciate that reverse engineering support from an unpublished API is challenging, and supporting hardware you don't own yourself is frustrating. However, now that the generic device driver has been removed, the work-around offered is nearly inaccessible: Creating the symbolic link in a Home Assistant OS install (getting a docker bash prompt, etc) and testing is a high bar for most users.

Can the Home Assistant integration offer users to use one of the existing drivers with their model in a "may or may not work for you" basis? For me, I was able to link umwv6z to my model m1wkuw which restored most functionality, and perhaps for users whose vacuums "mostly work" they would be satisfied with one of the existing drivers, if the option to do so was made easier.

Dec 05 '24 09:12 slartibartfast11

@edenhaus I can understand the frustration that keep being asked to add support to different models while assistance from the official is limited.

As a two X1 Omni and a U2 Pro user I am using this integration to handle simple cleaning tasks with Bumper, I believe some of us are fully aware the situation that the support for "unsupported" models is limited, before we can come up with another solution do you think it is possible to have an option to choose to re-enable the fallback rather than just get rid of it?

If the above is not an option, please may I ask if we can have an interim hotfix for those who understand the idea why the option is being removed while this buy us some time to look for alternative solution?

Dec 05 '24 09:12 willliamchan

I removed the fallback for a reason and will not add it back.

The problem is the fallback was in for many years, and there was also a log saying that you were using the fallback device. But only a very few users did actually add their model to the library. Many more users complained that your model was added to HA but is not working correctly. It's really frustrating that I can't help you guys, as Ecovacs is not publishing any information. I also wrote to Ecovacs about it, but I only got back something like "If we are interested, we will contact you", and they never did.

Also, comment like https://github.com/home-assistant/core/issues/132335#issuecomment-2519705743 are frustrating as we are maintaining it in our free time for free and I don't saw any cent of that 600€

Can the Home Assistant integration offer users to use one of the existing drivers with their model in a "may or may not work for you" basis?

For testing, I would recommend to set up a core dev env with https://developers.home-assistant.io/docs/development_environment. It takes only a few minutes to download all (after vscode and docker are installed), and then there, you can edit and play with the capabilities files of your model. Having a different HA instance for testing will not break your prod one if you have a syntax or other errors. If you have tested your capabilities file, feel free to open a PR, and I'm happy to review and merge it. :) Home Assistant will release a new patch every Friday, and I bump the version of the lib if you add models. For example, https://github.com/DeebotUniverse/client.py/pull/613 will be included in tomorrow's patch release. Also please not all workaround with modifying files directly in the HA docker image, will be lost with the next update

Dec 05 '24 10:12 edenhaus

Thanks, I appreciate your reply.

On a practical note, my unsupported N10 appears to be substantially similar to the supported N10 Plus, and the driver appears to work fine. I'll do some more testing and then open a PR.

Dec 05 '24 10:12 slartibartfast11

Also, comment like home-assistant/core#132335 (comment) are frustrating as we are maintaining it in our free time for free and I don't saw any cent of that 600€

while i understand that it can be frustrating to get such comments, please understand our user point of view, of having costly equipment that worked for a long time, being broken from a change made overnight (regardless of the reason, good or bad, it's not the point), with little warning, just a generic warning 'old device may no longer be supported' (while it turns out to be actually a LOT of devices, owned by a LOT of ppl).

and when asking for help being told "deal with it or do it yourself".

irony of it, on the update that claims to improve the integration quality scale to account for user friendliness

Dec 05 '24 11:12 sleveille4

Please check if a similar model has already been added to https://github.com/DeebotUniverse/client.py/tree/dev/deebot_client/hardware/deebot

If yes, you are probably lucky, and you only need to check if your model has the same options.

If yes, create a symbolic link between your model and a similar one

If not, please copy and rename the file and update it to comply with your model

If no similar model was added, then you need to reverse engineer your model by analyzing the traffic between the app and the Ecovacs servers. Sorry, but this cannot be avoided, as Ecovacs doesn't share any API information. You can try to contact the support, but in the past, Ecovacs did not help.

Check other PRs, maybe already someone is trying to add your model or is adding a similar model

Please also check https://github.com/DeebotUniverse/client.py/blob/dev/deebot_client/capabilities.py and other capabilities files to familiarize yourself with the schema of the required model file. Feel free to open a PR with your model and I'm happy to review it

Any clue you can give as to the path for the integration in the supervised Docker container where we need to create the symbolic link or copy the file from an existing model? I've been hunting through the container and can't find anything obvious and my Google foo is failing me.

Also, in the below log entry is the "class" attribute what I'm after? It looks to me that the X2 Omni is similar enough to the X1 Omni that I should be able to steal that one. I'm assuming changes won't survive an update of HASS Supervised?

Logger: homeassistant.components.ecovacs.controller
Source: components/ecovacs/controller.py:100
integration: Ecovacs (documentation, issues)
First occurred: December 4, 2024 at 6:21:39 PM (4 occurrences)
Last logged: 9:14:33 AM

Device "DEEBOT X1 OMNI" not supported. Please add support for it to https://github.com/DeebotUniverse/client.py: {'did': '91ef51f7-a9c1-4480-b18e-f173f725d44a', 'name': 'E0A915513D0K3C5X0100', 'class': '1vxt52', 'resource': 'iBxf', 'company': 'eco-ng', 'bindTs': 1698055755870, 'service': {'jmq': 'jmq-ngiot-na.dc.ww.ecouser.net', 'mqs': 'api-ngiot.dc-na.ww.ecouser.net'}, 'deviceName': 'DEEBOT X1 OMNI', 'icon': 'https://portal-ww.ecouser.net/api/pim/file/get/6225bd1c2af2127804f540e5', 'ota': True, 'UILogicId': 't10_ww_n_omni', 'materialNo': '110-2102-0300', 'pid': '6185e29610683da4d6a7a9cd', 'product_category': 'DEEBOT', 'model': 'EINSTEIN_INT', 'updateInfo': {'needUpdate': False, 'changeLog': ''}, 'nick': 'George ', 'homeId': '626dc4e437aa1204147f2f50', 'homeSort': 1, 'status': 1, 'offmap': True, 'otaUpgrade': {}}

Thanks, and I appreciate the work it takes to create and maintain these integrations when there is no documented API to work with.

Dec 05 '24 14:12 jayscovill

Creating the symbolic link in a Home Assistant OS install (getting a docker bash prompt, etc) and testing is a high bar for most users.

I had to learn how to do this today in order to test out one of the currently open PRs, but it wasn't intuitive. Here's how I did it, in case it helps anyone: https://github.com/DeebotUniverse/client.py/pull/611#issuecomment-2520390491

Dec 05 '24 15:12 mislav

#611 (comment)

Awesome, thank you my friend!

Dec 05 '24 15:12 jayscovill

For testing, I would recommend to set up a core dev env with https://developers.home-assistant.io/docs/development_environment. It takes only a few minutes to download all (after vscode and docker are installed), and then there, you can edit and play with the capabilities files of your model. Having a different HA instance for testing will not break your prod one if you have a syntax or other errors. If you have tested your capabilities file, feel free to open a PR, and I'm happy to review and merge it. :) Home Assistant will release a new patch every Friday, and I bump the version of the lib if you add models. For example, https://github.com/DeebotUniverse/client.py/pull/613 will be included in tomorrow's patch release. Also please not all workaround with modifying files directly in the HA docker image, will be lost with the next update

you are seriously suggesting that the users impacted by removing the working fallback vacuum will:

setup a dev environnement, with vscode / docker & git
create a fork
develop the model by reverse engineering (how?)

do you even hear yourself suggesting that? you really believe that everyone is a dev and know or even just simply understand what you are suggesting?

Dec 05 '24 16:12 sleveille4

The safest way is not to use your production system, and I don't imagine a simpler way to install it than this approach. For you, it's probably easier to SSH into HASSOS as root (so you need to copy over the SSH key first by USB-Stick) and then manually change some files. For me, that's a no-go, as in the worst case, a user can completely break HA, so it can't even restart, and that I want to avoid.

and when asking for help being told "deal with it or do it yourself".

I would help if I could, but most users will do nothing until something breaks and then complain. You can also write to Ecovacs and ask them to provide public API information. Maybe if many users write to them, they will change their minds.

For me, removing the fallback will help maintain this library in the future. Until now, a fallback vacuum has always been created for any mower, winbot, and all the other device types Ecovacs.

Please also understand that I do this side project in my free time and don't receive anything from Ecovacs. Please also note that the community, including me, has spent their free time over the last year to bring this integration to this point.

Dec 05 '24 17:12 edenhaus

So your best option was to actually, knowingly, break it for a lot of users.

Then asking for those user not to complain and become overnight dev capable of reverse engineering if they want it working again, cause it's not your problem.

Thanks. Really helpfull.

Dec 05 '24 17:12 sleveille4

So your best option was to actually, knowingly, break it for a lot of users.

Then asking for those user not to complain and become overnight dev capable of reverse engineering if they want it working again, cause it's not your problem.

Thanks. Really helpfull.

You need to dial back your sense of entitlement, my friend. These people do this work for the betterment of the community for free. Your attitude is the kind that discourages that selflessness.

Instead of complaining be thankful that there are others jumping in to help and trying to improve the support for other models.

And if all you have to contribute is complaints spare us and the author and unsub from the thread.

Dec 05 '24 18:12 jayscovill

So your best option was to actually, knowingly, break it for a lot of users. Then asking for those user not to complain and become overnight dev capable of reverse engineering if they want it working again, cause it's not your problem. Thanks. Really helpfull.

You need to dial back your sense of entitlement, my friend. These people do this work for the betterment of the community for free. Your attitude is the kind that discourages that selflessness.

Instead of complaining be thankful that there are others jumping in to help and trying to improve the support for other models.

And if all you have to contribute is complaints spare us and the author and unsub from the thread.

seriously? so I am the one to take flak for pointing out that breaking an integration for many ppl, on purpose, and then telling ppl asking for help to solve it themself is not acceptable?

you should dial it back "friend".

i asked politely about the issue i aksed how i could help fix it i aksed if it was possible, at least LOCALLY on MY session to reactivate the part removed (as i DO understand that for other it might be problematic to reactivate it globally)

and the only answer i got was "deal with it, rtfm and code it yourself".

but it's MY attitude the problem....sure.....

i sure am "thankfull" that someone CHOOSE on purpose to break this, no argument here

Dec 05 '24 18:12 sleveille4

If your model was working well with the previous default fallback vacuum, it should work well with the OZMO T8 AVI class x5d34r.py, which appears to be identical to the 8.4.1 fallback.py. Indeed the 920/950/960/T5/T8 models were the foundation of the original integration https://github.com/And3rsL/Deebot-for-Home-Assistant

So you should be able to do like #624 with your specific vacuum class, check HA 2024.12 logs for it. Create your new fork, add the symlink in deebot_client/hardware/deebot and edit the tests/hardware/test_init.py, then Contribute > Open pull request. Symlink is very tricky, check https://github.com/DeebotUniverse/client.py/pull/624#discussion_r1872361989, command ln -s x5d34r.py YOUR_CLASS.py to do in GitHub.dev terminal after you are in the proper folder with cd deebot_client/hardware/deebot. Or juste creat the text file with x5d34r.py in it and let an admin properly fix it to a Symlink.

Roll back HA to 2014.11 until the PR is deployed, or test the not recommended quick fix https://github.com/DeebotUniverse/client.py/pull/611#issuecomment-2518897374 with last command replaced by your custom ln -s x5d34r.py YOUR_CLASS.py

Dec 06 '24 01:12 Yterz

and the only answer i got was "deal with it, rtfm and code it yourself".

Bottom line: I've been on both sides of this debate, and I don't enjoy either, check https://github.com/DeebotUniverse/client.py/discussions/627 where I'm proposing a possible compromise to get everyone something useful.

@sleveille4 I totally hear your frustration. I think it was probably a good idea to make some kind of change to get things moving since the default was obviously causing real problems, but your horror at trying to learn all the complexities of HA integration development really resonated with me. And that's coming from someone learning it!

Anyway, since you seem to be the most vocally upset poster so far (understandably so) can you take a look at https://github.com/DeebotUniverse/client.py/discussions/627? I'm trying to find a balance between keeping the devs on this project sane and happy (and thus contributing, since we really appreciate them) and making sure folks like you don't feel abandoned.

Dec 06 '24 02:12 gdgib

@edenhaus are there any docs on reviewing API traffic? I assume we're talking about intercepting traffic between e.g. the iOS/android app and the ecovacs servers, right? That means we need a device level traffic proxy, possibly forged root certs, and wireshark, yes? If I guessed the process right, but there are no docs, can you point me to the right place to contribute some? I can't say I really need it for this code base, but I've done that kind of thing before and I'd be happy to make it easier for the next person if possible.

Dec 06 '24 02:12 gdgib

I marked some comments as off-topic to collapse them, as the log entry will now point to this issue.

We should all write Ecovacs support asking for public API documentation to improve this library and the experience in HA even more and add support for all features (a lot are currently missing). HA users have changed some manufacturers' opinions in the past, so I hope we can change the opinion of Ecovacs. It would be amazing if they could help improve it.

Dec 06 '24 10:12 edenhaus