Add Roborock Core as a platform

[Lash-L]

Integration repository

https://www.home-assistant.io/integrations/roborock/

Supported features

• Zone cleaning (using 4 coordinates)
• Room cleaning (using room id/number)
• Going to point (using 2 coordinates)
• Cleaning a point (using 2 coordinates)
• Others

Checklist

• I have sent info about entities to piotr.machowski.dev [at] gmail.com (Retrieving entities info; please provide your GitHub username in the email)

Vacuum entity/entities

n/a

Service calls

n/a

Other info

Creating this issue here to keep track of my work and ask questions. I plan to do the incorporation myself so I have left service calls and entities blank.

Roborock core holds the map in a image entity instead of a camera entity, so I got the calibration points from the map parser .calibration() and set up the following:

type: custom:xiaomi-vacuum-map-card
entity: vacuum.s7_roborock
map_source:
  image: image.s7_roborock_downstairs
calibration_source:
  calibration_points:
    - vacuum:
        x: 25500
        'y': 25500
      map:
        x: 240
        'y': 184
    - vacuum:
        x: 35500
        'y': 25500
      map:
        x: 440
        'y': 184
    - vacuum:
        x: 25500
        'y': 35500
      map:
        x: 240
        'y': -16

vacuum_platform: humbertogontijo/homeassistant-roborock

However, the image does not show up

Before I went any further I wanted to check with you that images are supported by the card.

[PiotrMachowski]

Before I went any further I wanted to check with you that images are supported by the card.

It should work, but you have to set it up using camera key:

map_source:
  camera: image.s7_roborock_downstairs

I suppose calibration points won't be added to the core, right?

[Lash-L]

Ah that did it - Guess I should have read the docs better.

I do plan to try to get calibration points added to core as an extra state attribute on the image entity, I think I'll be able to get that approved

[PiotrMachowski]

I think I'll be able to get that approved

In case of failure I think it won't be hard to inject appropriate code using a custom integration. Please include me in a potential PR regarding this feature

[Lash-L]

Please include me in a potential PR regarding this feature

Can do. Anything else that would be helpful for me to expose?

I have just started diving into your code, but one thing that is important with Roborock vacuums is that commands are map specific and room ids are not. So if I want to clean room id 12 on the downstairs map, if I click on that room to clean it, but I have the upstairs map selected as my current map, it will attempt to clean room id 12 upstairs.

Is there a means on the card to set the map you are interacting with as the current map?

[PiotrMachowski]

Anything else that would be helpful for me to expose?

roomssection would also be useful - it is used to automatically generate rooms config.

Is there a means on the card to set the map you are interacting with as the current map?

It is possible to add configs for multiple maps using additional_presets and make card automatically choose appropriate one using matching condition

More info e.g. here: #248

[dkirby-ms]

Roborock core holds the map in a image entity instead of a camera entity, so I got the calibration points from the map parser .calibration() and set up the following:

Could you perhaps give more detail on how you are getting the map coordinates? I am using the new native Roborock integration. I have the image showing up but the calibration is off because I am not sure how to map the dock location to the image map.

[PiotrMachowski]

@dkirby-ms he modified the code of Roborock integration

[mistergyle]

is there any ongoing development on this issue?
i would appreciate it!

[Lash-L]

is there any ongoing development on this issue? i would appreciate it!

I am unfortunately a bit blocked. Not much I can do at the moment and core devs have to make decisions.

[jason-curtis]

Is there a recommended workaround for generating calibration points at the moment? Docs point me towards https://github.com/PiotrMachowski/Home-Assistant-custom-components-Xiaomi-Cloud-Map-Extractor but I don't have a Xiaomi account as I've been using the Roborock app.

[PiotrMachowski]

You can use this integration instead:
https://github.com/humbertogontijo/homeassistant-roborock

[jason-curtis]

I did just switch to the official integration because I was having issues with that one and was hoping this would be more stable. Is the humbertogontijo version preferred for the vacuum map card?

[PiotrMachowski]

@jason-curtis at this moment the official integration doesn't provide data that is necessary to use the map functionality in this card

[Maximus97]

I as well very much look forward to this card supporting the official Roborock integration

[Lash-L]

@PiotrMachowski since our original plan failed. Would a service call work?

I.e you could call vacuum: send command with a service that is like get_map_card_info and we get all of the initial info you need like calibration points, room dimensions, etc? Then we could still use the image entity to update what the map looks like?

[PiotrMachowski]

@Lash-L I think service call should be ok, but I also thought about implementing a dedicated WS API method. The downside of this approach is that it probably won't be possible for users to use it manually.

It would also be nice to make it possible for the card to be notified that something has changed in the calibration (I think this happens quite often during map building). Can it be solved by generating an event when it happens?

[carlos-48]

I got the calibration points from the map parser .calibration() and set up the following:

type: custom:xiaomi-vacuum-map-card
entity: vacuum.s7_roborock
map_source:
  image: image.s7_roborock_downstairs
calibration_source:
  calibration_points:
    - vacuum:
        x: 25500
        'y': 25500
      map:
        x: 240
        'y': 184
    - vacuum:
        x: 35500
        'y': 25500
      map:
        x: 440
        'y': 184
    - vacuum:
        x: 25500
        'y': 35500
      map:
        x: 240
        'y': -16

vacuum_platform: humbertogontijo/homeassistant-roborock

Hi! First of all, thanks for the integrations!

@Lash-L Could you better explain how to get the calibration points so users can do it in the mean time?
I just moved from HACS integration to Core integration, and I can't find any documentation or tutorial about getting the calibration points from Core integration.

[Lash-L]

@Lash-L I think service call should be ok, but I also thought about implementing a dedicated WS API method. The downside of this approach is that it probably won't be possible for users to use it manually.

It would also be nice to make it possible for the card to be notified that something has changed in the calibration (I think this happens quite often during map building). Can it be solved by generating an event when it happens?

I think conceptually that's okay - i don't know if i really have time for it right now, whereas a service might be easier.

I could also cache the latest mapdata and the service could get the latest mapdata if you think that would be better?

@Lash-L Could you better explain how to get the calibration points so users can do it in the mean time?
I just moved from HACS integration to Core integration, and I can't find any documentation or tutorial about getting the calibration points from Core integration.

@carlos-48 You can't. I modified things inside the actual code base in my development environment

[PiotrMachowski]

i don't know if i really have time for it right now, whereas a service might be easier.

Don't worry about it, at this moment I'm rewriting Map Extractor, then I'll have to adjust the card, so you have plenty of time.

I think service call should be enough for my purposes

[pedro639]

is there any ongoing development on this issue? i would appreciate it!

I am unfortunately a bit blocked. Not much I can do at the moment and core devs have to make decisions.

Hey there, I have a suggestion regarding this. When you was developing the custom integration you had more freedom to do what ever you pleased and at your own saying right? Why not bring the custom integration up to date making it on par with the core integration and that way you can implement all the features at any time without having to go through the core devs themselves. This way the custom integration is always the "same" as the core, but at the same time you are able to implement whatever you want at whatever time. This is a newbie talking btw, I am just thinking out loud!

Cause so far I had 3 options, in my case with a roborock:

1. Use the custom integration (works great with all the features needed but since it is not updated tends to crash and/or generate a ton of errors)
2. Use the core integration (only has one problem and that is the map is generated using image instead of camera entity, making it incompatible with a vacuum map card)
3. Use the Xiaomi Miio integration with a map extractor (very limited, bugs quite often in my case and makes you use the Mi Home app instead of the roborock app)

[borgqueenx]

i wanted to use this card so bad that i was willing to forsake the roborock app and use xiaomi home instead (and therefore lose camera view and pictures of objects detected) however the newest roborock s8 maxv thats already out for quite a while now, is not supported in the xiaomi home app, therefore i cannot use it in there. now there doesnt seem to be any option available for me to get a vacuum card working....
I already tried the roborock hacs integration instead of the build-in one for home assistant, but it constantly loses connection. Sad to see developers removed the camera from the official integration.

I am left without any working option now it seems...

[shbatm]

Sad to see developers removed the camera from the official integration.

The official integration uses an image entity instead of camera.

[maxbec]

Is there any progress here?

[joseffallman]

1. Use the custom integration (works great with all the features needed but since it is not updated tends to crash and/or generate a ton of errors)

Thanks @pedro639
This was the solution for me. I have been so upset about this change in the core integration and for me its broken. Now, after a switch back to the custom integration, I'm able to use the vacuum cleaner with this vacuum map card again.

[borgqueenx]

The hacs custom integration is not working. I command the robot to do something and it goes out and straight back to the dock
The official integration is unfortunately as of now kind of useless without a good card...

[Maximus97]

Agree with @borgqueenx, the custom roborock integrations are crashing all the time and then there is no good use of this fantastic card

[simllll]

Hi all, just to get things right:

1. due tot he "image" vs "video" thingy, we do not have any calibration points
2. the calibration points can be retrieved with a roborock command
3. I can add the calibration points manually in a config file

is this all correct? So would it be possible to e.g. create some script that updates this in the config automatically for me and use this map then?

Thanks a lot, looks like an amazing extension 👍 Willing to help to get this running with roborock core.

[PiotrMachowski]

@simllll

1. due tot he "image" vs "video" thingy, we do not have any calibration points

Not really, they have not been added to the HA core because of technical reasons. More info here

2. the calibration points can be retrieved with a roborock command

Calibration points are calculated based on map dimensions - they are not returned by any Roborock command

3. I can add the calibration points manually in a config file

You can add them manually to the card's configuration. It is also possible to use any entity as a source of calibration.

So would it be possible to e.g. create some script that updates this in the config automatically for me and use this map then?

I don't think it is possible at this moment

[simllll]

Thanks for the clarification @PiotrMachowski , I tried to catch up on the existing issues, I see that a general solution would be the best way to go, but... also will take more time, it's not even a complete proposal yet, so we are far away from an implementation.

Referring to @Lash-L comment (home-assistant/core#105424 (comment))

another way needs to be found

what about doing it "old-fashined" and just write the additional properties to a yaml file and use this a "input" for the map?

[Lash-L]

Anykind of IO is probably a no go for me imo.

I have had so little time to actually work on any of my hobby projects - but I would be happy to accept a workaround fix.

What I had in mind is a new command. Something like GET_CALIBRATION

Ideally, this would be getting cached and loaded, but since this shouldn't need to be done frequently, it can just do it all once there.

Although - it might make more sense just to add a function like "update_map_data" on the api object, and then in core when the map data is parsed, it calls .update_map_data(map_data) and stores it there. Then when the GET_CALIBRATION command is sent - it gets the calibration data that is stored.

And as a clarification - GET_CALIBRATION cannot be a new service - but rather a new command inside the roborock python package.

[PiotrMachowski]

A new command should be ok for me as well - it can be cached e.g. trigger-based template sensor and this new entity will be used by the card as a source of calibration.

[simllll]

Anything I can do to make some progress on this?

[PiotrMachowski]

Workaround description: #754 (comment)

[kuchar91]

up. Any news on that?

[Lash-L]

Hey @PiotrMachowski Got the calibration custom command finally added.

Soon(TM), users can send a command to the vacuum get_map_calibration and get the calibration points of their active map.

How would you like to proceed from here?

[PiotrMachowski]

That's a great news @Lash-L!

Does calling this command introduce any additional load on the API/HA (like a new map download/parsing), or is it just retrieving a calculated map of values?

[Lash-L]

That's a great news @Lash-L!

Does calling this command introduce any additional load on the API/HA (like a new map download/parsing), or is it just retrieving a calculated map of values?

It unfortunately does a new map download and parse. It was tricky as I couldn't pass the data down from ha as core devs don't want any code in core meant to just support a custom component.

My understanding is that it is basically a one time call for each map right? If that's not the case I can try something else

[PiotrMachowski]

My understanding is that it is basically a one time call for each map right?

I can't really tell, I do not own a vacuum that is compatible with Roborock app 😉 but as long as a position of map itself doesn't change on the image then I suppose everything should be fine.

Is it possible to detect the moment when this call should be performed? (detect that the map has changed)

[Lash-L]

My understanding is that it is basically a one time call for each map right?

I can't really tell, I do not own a vacuum that is compatible with Roborock app 😉 but as long as a position of map itself doesn't change on the image then I suppose everything should be fine.

Is it possible to detect the moment when this call should be performed? (detect that the map has changed)

I think i can make a better version of it in the future that should happen everytime the image updates.

i.e. update Image through HA core -> pass data back to python library -> Store -> when a command is sent give the value

Is there anyhting else other than calibration points that you would need that you don't have access to now?

For now is it good enough to just assume calibration points don't change? And we can update again when i build the 'better' system?

[PiotrMachowski]

You potentially can try to move the map parsing from HA to the python library itself. In that case you should be able to store the latest data inside library and return it to HA using commands.

Is there anyhting else other than calibration points that you would need that you don't have access to now?

The other part that would be nice to have are rooms for automatic room cleaning mode generation (room names, IDs and coordinates).

For now is it good enough to just assume calibration points don't change? And we can update again when i build the 'better' system?

I think it should be ok for most cases, the part that I worry about is changing maps for multiple floor support.

[Lash-L]

You potentially can try to move the map parsing from HA to the python library itself

If I did this what would be the ideal way for you to get the data on the frontend? Still a command? I realized a slight hiccup in my original thought process. The send_command service call doesn't actually return anything and per core devs, it should never return anything.

In the lovelace card are you able to access the actual pythonic objects? I assume not

[PiotrMachowski]

If I did this what would be the ideal way for you to get the data on the frontend?

The ideal way would be to add calibration_points attribute to the camera, but that is not going to happen 😃 I can work with any service call even right now by creating a template entity that will do that instead of the card. Adding a WS API call should also be ok, but it would require some implementation on the card side.

The send_command service call doesn't actually return anything and per core devs, it should never return anything.

Why? There are commands that return responses on the Xiaomi vacuum side, I thought send_command would be a way to communicate with a vacuum in a more "raw" way.

In the lovelace card are you able to access the actual pythonic objects? I assume not

No, there is no chance for something like that

[Lash-L]

The ideal way would be to add calibration_points attribute to the camera, but that is not going to happen 😃 I can work with any service call even right now by creating a template entity that will do that instead of the card. Adding a WS API call should also be ok, but it would require some implementation on the card side.

I'm not sure if i can get an 'extra' service call approved in core review

Why? There are commands that return responses on the Xiaomi vacuum side, I thought send_command would be a way to communicate with a vacuum in a more "raw" way.

Are you sure? Send command seems to also not return anything here
https://github.com/home-assistant/core/blob/dev/homeassistant/components/xiaomi_miio/vacuum.py#L330-L343

No, there is no chance for something like that

Figured that

[SLaks]

I tried that and got rejected. home-assistant/core#112431

[Xyaren]

If I may ask the question:
How will the synchronisation been current displayed map and current calibration points be done?

If I switch maps like a different floor the calibration points need to be updated at the same time as the map image in order to not break the card.

It would be very helpful to include the name of the map along with the metadata to allow using different display offsets in the card.

[PiotrMachowski]

@Lash-L

I'm not sure if i can get an 'extra' service call approved in core review

I'll try to work with anything you will be able to provide 🙂 As a last resort I thought about adding some sneaky monkey patching using a custom integration, but I would really prefer to not do it.

Are you sure? Send command seems to also not return anything here

It doesn't on the HA side, but miio library returns data

---

@SLaks

I tried that and got rejected. home-assistant/core#112431

generally the answer you got would make sense in the ideal world, but unfortunately it also limits power users 😞

[Lash-L]

Are you sure? Send command seems to also not return anything here

It doesn't on the HA side, but miio library returns data

Yeah so roborock can do that to and that's what happens in the library - but you aren't able to access that in anyway through the lovelace card right?

[PiotrMachowski]

you aren't able to access that in anyway through the lovelace card right?

Exactly