Add vacuum.clean_area action

[arturpragacz]

2025.09.29: Changed async_get_segments to return a list of objects, for easier future expansion.
2025.10.02: Removed repeat parameter for now.
2025.12.18: Change SegmentIdType to str. Add group attribute to Segment class.

Context

Many modern robotic vacuums support cleaning specific areas, but Home Assistant currently lacks built-in support for this feature.

Integrations that could benefit include:

• Roborock
• Xiaomi Home
• Ecovacs
• Miele
• Matter

Proposal

Introduce a new action that instructs a vacuum to clean selected areas.

To provide the best user experience, the action will target native Home Assistant areas, instead of relying on vacuum's internal segment identifiers (room, area, segment - naming differs depending on the vacuum manufacturer, here we will use "segment" for this concept to avoid confusion with native Home Assistant areas).

Using native areas instead of internal segment identifiers provides several benefits:

• It is consistent with the semantic model of the world already present in Home Assistant.
• It can be leveraged to provide better UX in dashboards and other UI spaces.
• It will make it easier to introduce a possible native floor plan entity in the future.
• It makes integration with the voice control both easy to implement and feature-complete, with support for full functionality, including area aliases and advanced language grammar features currently under development/consideration.

To implement this proposal, two main components are required:

1. A mechanism to allow users to map Home Assistant areas to the vacuum’s internal segments.
2. The implementation of the new action itself, which will translate the areas targeted by the action back into internal identifiers.

Backend implementation

The VacuumEntityFeature enum will be extended:

class VacuumEntityFeature(IntFlag):
    ...
    CLEAN_AREA = 16384

The following methods will be available for integrations to implement in the StateVacuumEntity:

@dataclass(slots=True)
class Segment:
    id: str
    name: str
    group: str | None = None

async def async_get_segments(self) -> list[Segment]:
    """Get the segments that can be cleaned."""

async def async_clean_segments(
    self, segment_ids: list[str], **kwargs: Any
) -> None:
    """Perform an area clean."""

When the vacuum.clean_area action is called, the selected Home Assistant areas will be translated into the corresponding internal segment IDs and passed to async_clean_segments.

The translation will be done using the mapping stored in the vacuum entity options, that maps a Home Assistant area to one or more vacuum segments.

async_get_segments will power a new websocket endpoint, vacuum/get_segments. The frontend will use it to display vacuum options, enabling users to match Home Assistant areas with vacuum segment names. This configuration will then be persisted in the entity options mentioned above.

PR: home-assistant/core#149315

Frontend

Frontend will add a “Vacuum options” field in the vacuum entity settings for integrations that support this feature. It will behave similarly to existing helpers (e.g. templates, groups). Clicking it will open a dialog that allows users to map Home Assistant areas to vacuum segment names.

[MartinHjelmare]

How common is the repeat feature among existing integrations?

[tetele]

Roborock supports it, but it's limited to 1x, 2x or 3x.

[abmantis]

The Xiaomi Home app and Ecovacs app also support it.

[dxmnkd316]

Eufy also supports it.

[rohankapoorcom]

I would add MQTT as an integration that would use this since Valetudo (one of the commonly integrated MQTT Vacuums has support for cleaning areas). There's an example of how it's currently called today here (bottom of page).

It also supports 1-3x repeat when cleaning.

[joostlek]

We generally don't count mqtt or template as you can do anything with them. But knowing that Valetudo supports it is great

[gjohansson-ST]

Some comments

• It feels (as previously also discussed on discord) very driven by voice and linking it to the HA areas. I would expect the service parameter to be area names (as defined by the vacuum) and not some difficult to use segment id's. It should not make it impossible/hard to use without linking it to HA areas.
• Not sure why we would hide the repeat parameter in kwargs? I would expect "all" vacuums to support it.

[arturpragacz]

• Service takes Home Assistant area ids as a parameter, the internal segment ids are completely invisible from the user's perspective. Voice is a major, but not the only reason, there are multiple mentioned above.
• Matter does not seem to support repeat.

[gjohansson-ST]

Service takes Home Assistant area ids as a parameter, the internal segment ids are completely invisible from the user's perspective. Voice is a major, but not the only reason, there are multiple mentioned above.

Yes, exactly my point. Makes this rather impossible/hard to use if I don't want to link it to my HA areas (or they are not matching).

Matter does not seem to support repeat.

Just a matter of time I guess since it's quite a standard feature for segment cleaning and I hope we're considering this based on the major players on the market.

[abmantis]

• Since the action is able to clean multiple areas, it should be named clean_areas.

• How do we handle the vacuum segments being added/removed/updated, and how do we make the user aware of it?
  It will be a poor experience if the user has an automation to clean 2 rooms and after a while finds out that 1 room stopped being clean because the vacuum updated the room mappings.
  We should provide a way for users to know that segments changed, since vacuums can update the map automatically.

[arturpragacz]

• We are not really consistent in Home Assistant when we use plurals and when we don't. Going with clear_areas I think is fine too.
• Integrations can raise a repair issue, when they detect that the internal config has changed. We might want to provide either a recommendation for the language of that repair or even a common helper to ensure the experience is similar between integrations.

[allenporter]

This looks like a very good design, handling the assignment of internal vacuum segments to Areas with a UI. This seems to address the discussion started in #913 (comment) -- This seems like it will work for Roborock, and i'm supportive of this proposal.

Some tweaks I might suggest: The currently proposed async_get_segments interface is nice and minimal, though we may want to return an object instead of just simple types to allow for some future expansion:

@dataclass
class Segment:
    id: SegmentIdType

    name: str
    """The name of the room segment as identified by the vacuum. """

    # We can associate additional information in the future here.


async def async_get_segments(self) -> list[Segment]:
    """Get the segments that can be cleaned.

    Returns a mapping from segment IDs to their names.
    """

Future use case: This is not designing a solution now, but an example. Thinking through the floor plan idea, it could be built on top of your proposal by adding a polygon or rectangle on top of the current proposal. (In the future, clicking on a vacuum map card on top of an vacuum map image could trigger clean area command for that segment id. I haven't looked at the custom map cards closely, so just spitballing here)

[tetele]

Just something to keep in mind: in the Roborock app, editing a map sometimes changes the segment IDs, which will make some mapping work for some areas, while others not.

[abmantis]

That is related to the second point in #1284 (comment) right?

[dxmnkd316]

I would love to have this. The HACS integration "Eufy Robovacs" would also benefit from this.

One thing to note is that at least Eufy duplicates room IDs for different floors. So you can have areas 1,2,3,4 on floor 1 and areas 1,2,3,4 on floor 2. Not sure if the other integrations have a similar setup.

I would ask that a Current Floor selector also be added so that repeated room IDs can be mapped separately. Hopefully this makes sense the way I'm explaining it.

[abmantis]

The integration can abstract that by defining the segment id like segment_id=f"{floor_id}-{room_id}", so they are unique outside of the integration.

[lboue]

Has there been any progress on this?
We are waiting for this for Matter integration.

[lboue]

One thing to note is that at least Eufy duplicates room IDs for different floors. So you can have areas 1,2,3,4 on floor 1 and areas 1,2,3,4 on floor 2. Not sure if the other integrations have a similar setup.

With the Matter protocol, areas can only belong to one floor if there are several floors.

[dxmnkd316]

Yeah, this was also addressed by abmantis above.

[mtribiere]

Any progress on this? It would be a really powerful addition to HA Matter integration.

[emontnemery]

The proposal was discussed and approved in a core meeting December 18th 2025

[Tasshack]

Please do not name this as CLEAN_AREA for cleaning rooms.
There is already a service called clean_area on most of the vacuum integrations but it is for cleaning an actualy specified area that contains two coordinates instead of rooms.
If you are planning to add support for cleaning rooms is should be named as CLEAN_ROOM or CLEAN_SEGMENT to not interfere with existing services on existing projects.

[allenporter]

My impression is those would be <integration>.clean_area which won't interfere with vacuum.clean_area.

[Quentame]

HA core could get a dedicated vacuum.clean_zone (coordinates) in addition to a vacuum.clean_area (rooms/areas).

or maybe a vacuum.clean_area taking both coordinates and room parameters, but that could be odd.