Feature Request: Generic ServiceArea Mapping to Support Robotic Lawn Mowers via RoboticVacuumCleaner

[6fjdkhnj4c-droid]

Hello,

I would like to propose an enhancement to the Home Assistant Matter Hub regarding the implementation of the ServiceArea cluster for RoboticVacuumCleaner devices.

My primary goal is to integrate a robotic lawn mower (in my case, a Mammotion device) into Apple Home as if it were a robotic vacuum. Conceptually, both devices share the same functional model: they are autonomous robots that operate within defined zones or areas. Whether the robot vacuums dust or cuts grass, from a Matter and Apple Home perspective, it is still a robot performing a cleaning action in a selectable area.

Currently, devices such as Dreame or Roborock vacuums work well because their integrations expose structured room/segment data along with a native service like:

• vacuum.clean_segment(segment_id=XX)

This allows the Matter Hub to map:
SelectAreas([id]) → clean_segment(segment_id=id)

As a result, Apple Home displays:

• A Clean Mode selector (via RvcCleanMode)
• A list of “Rooms” (via ServiceArea)

However, other integrations such as Mammotion lawn mowers expose:

• Individual button entities per zone (e.g. button.start_magnolia_1)
• No structured rooms list
• No native start_zone(zone_id) service

Because of this, it is currently impossible to expose mowing zones as proper ServiceArea entries in Matter, even though the functional capability exists in Home Assistant.

Proposed Enhancement

I suggest adding a generic ServiceArea configuration mechanism in the Matter Hub that would allow users to:

1. Define supported areas manually in the bridge configuration.
2. Map each areaId to a Home Assistant service call.
3. Handle the SelectAreas command by forwarding the selected areaIds to the configured service.

For example:

customServiceAreas:

• id: 1
  name: Magnolia 1
  service: script.yuka_start_zone
  data:
  zone_id: 1
• id: 2
  name: Magnolia 2
  service: script.yuka_start_zone
  data:
  zone_id: 2

The hub would then:
• Expose a valid ServiceArea cluster with supportedAreas
• Implement SelectAreas
• Call the defined Home Assistant service with the appropriate parameters

This would make the feature generic and integration-agnostic, rather than tied to specific vacuum integrations.

Use Case

The main objective is to allow robotic lawn mowers to appear in Apple Home exactly like robotic vacuums:

• Bottom-left: Mowing mode (mapped to a select entity via RvcCleanMode)
• Bottom section: “Rooms” corresponding to mowing zones (via ServiceArea)

From a Matter perspective, this is entirely coherent: ServiceArea represents selectable operating zones, not exclusively vacuum rooms.

Benefits

• Enables structured zone control for any robot operating in defined areas
• Makes the add-on more flexible and device-agnostic
• Avoids custom forks and local patches
• Keeps the architecture clean by relying on Home Assistant service calls

I would be happy to help test or validate such a feature if needed.

Thank you for your work and for considering this proposal.

[6fjdkhnj4c-droid]

Adding a short clarification to my previous message.

The goal is not specifically about lawn mowers. The broader idea is to allow any zone-based autonomous robot to expose selectable areas in Apple Home via the Matter ServiceArea cluster.

Today this works for Dreame/Roborock because the integration provides:

• Structured segment metadata (id + name)
• A callable service like vacuum.clean_segment(segment_id=XX)

The Matter Hub maps SelectAreas to that service.

For other devices (e.g. lawn mowers, pool cleaners, window robots), the capability to operate per-zone exists in Home Assistant (often via buttons or scripts), but there is no structured segment service. As a result, ServiceArea cannot be exposed.

A generic solution would be to allow manual declaration of ServiceAreas in the bridge config, mapping:

• areaId + name
  → to a Home Assistant service call

Example:

customServiceAreas:
  - id: 1
    name: Magnolia 1
    service: script.yuka_start_zone
    data:
      zone_id: 1

The Hub would:

• Expose supportedAreas
• Implement SelectAreas
• Forward the selected IDs to the configured HA service

This would make ServiceArea integration-agnostic, not tied to specific vacuum integrations, and usable for any robot operating in predefined zones.

Happy to test if needed.

[6fjdkhnj4c-droid]

Thanks for your time on this — customServiceAreas is exactly what I needed to get my Mammotion lawn mower working in Apple Home ☺️ I've been using Claude AI to help me through the setup, got pretty far but hit a few bugs. Details below, hope it helps move things forward!
Maximilien

[RiDDiX]

Fixed the first two in the next alpha (28d59dd):

The custom service areas weren't being saved because the API endpoint was missing that field when constructing the request simple oversight on my end. Should persist properly now.

For the zone cleaning, the room mode handler was falling through to vacuum.send_command because it didn't know about custom service areas. Now when you select a zone and press play, it matches the room name to your configured custom area and calls the right script.

About the cleaning mode labels (Bug 3) that one's unfortunately a Matter limitation. Apple Home renders its own localized labels for RvcCleanMode based on the mode tags (Vacuum/Mop/DeepClean), not the custom labels we provide. The cleaningModeEntity is really meant for vacuum/mop type switching. For your mowing trajectories, you might have better luck using the suctionLevelEntity instead those modes show with their actual option names in Apple Home since they map to intensity tags, not cleaning type tags. Worth a try.

Give the next alpha a shot and let me know!

[6fjdkhnj4c-droid]

Update — Zone selection blocked by Mammotion HA integration limitation
Hey RiDDiX,
Quick update on the zone cleaning issue. The custom service areas fix from 28d59dd is working correctly on your end — the Matter Hub correctly identifies the zone, matches it to the configured script, and dispatches the right service. That part works.
The problem is upstream, in the Mammotion HA integration itself.
The zone switches (switch.yuka_yvd5xnzb_zone_zone_pin etc.) do not respond to switch.turn_on when the robot is docked. No error, no log — the action is silently ignored. The switches show as off in HA States but are effectively read-only from a scripting perspective. As a result, when lawn_mower.start_mowing is called right after, Mammotion throws error 1415 (“abnormal zone selection”) because no zone was actually activated.
I’ve opened an issue on the Mammotion HACS repo to ask:
∙ Whether the zone switches are writable by design
∙ Whether there’s a start_mowing service with a zone parameter
∙ Whether there’s another API path to select a zone programmatically
Once I get clarity from the Mammotion side, I’ll know what the script needs to call. Your side of the bridge is solid — it’s just waiting on the right HA action to trigger.
Thanks again for the quick turnaround on the fixes.
Maximilien

[6fjdkhnj4c-droid]

Mammotion Yuka 2000 — Full integration into Apple Home via HAMH Alpha ✅

Hey RiDDiX, it’s working end-to-end now. Here’s a full technical report that might be useful for the add-on documentation or future similar use cases.

---

Use case

Integrating a Mammotion Yuka 2000 robotic lawn mower into Apple Home via Home Assistant, with:

• Zone selection (Magnolia / Pin / Saule) directly from the Apple Home app
• Mowing start triggered by the Play button in Apple Home
• Battery level and charging state visible in Apple Home
• Full mowing parameters (trajectory, obstacle detection, perimeter laps, rain detection, blade height)

---

Stack

• Home Assistant with Mammotion HACS integration (v0.4.36)
• Home-Assistant-Matter-Hub Alpha (2.1.0-alpha.378)
• Template vacuum entity wrapping lawn_mower.yuka_yvd5xnzb
• 7 HA scripts calling mammotion.start_mow directly with areas parameter

---

HAMH Entity Mapping

Entity: vacuum.yuka_2000 (template vacuum)
Device Type Override: RoboticVacuumCleaner (0x0074)
Cleaning Mode Entity: select.yuka_angle_de_coupe (custom template select, cutting angles: 0°/45°/90°/135°/-45°/-90°)
Suction Level Entity: (empty)
Custom Service Areas:

Area Name	HA Service
Magnolia	script.yuka_zone_magnolia
Pin	script.yuka_zone_pin
Saule	script.yuka_zone_saule

---

What HAMH does

When the user selects a zone (e.g. Saule) and presses Play in Apple Home:

1. HAMH receives the cleanRoom command on the serviceArea cluster
2. Matches the selected area name to the configured Custom Service Area
3. Dispatches script.yuka_zone_saule via HA action
4. Script calls mammotion.start_mow with areas: [switch.yuka_yvd5xnzb_zone_zone_saule]
5. Yuka leaves the dock and starts mowing the selected zone

---

Matter cluster state (endpoint 2)

Cluster	Key attribute	Value
rvcRunMode	supportedModes	5 items (Idle + Cleaning + 3 zones)
rvcCleanMode	supportedModes	8 items (cutting angles)
serviceArea	supportedAreas	3 items (Magnolia/Pin/Saule)
powerSource	batPercentRemaining	200 = 100%
rvcOperationalState	operationalState	65 = docked

---

Issues encountered and resolved

Issue 1 — vacuum.send_command not supported on template vacuum

Fixed by your commit 28d59dd: before this fix, HAMH was dispatching vacuum.send_command on the template vacuum, which doesn’t support it. Your fix routing cleanRoom to the configured service script resolved this completely.

Issue 2 — Custom Service Areas not persisting in UI

Fixed by your commit 28d59dd: the customServiceAreas field wasn’t being persisted to the API. Fixed in entity-mapping-api.ts.

Issue 3 — rvcCleanMode labels showing “Vacuum/Mop” instead of custom names

Known limitation: Apple Home renders rvcCleanMode mode labels based on Matter mode tags, not on custom strings. Confirmed limitation of the Matter spec / Apple Home implementation. Workaround: use a non-cleaning-type entity for Cleaning Mode (e.g. a cutting angle select) — the labels then display the actual HA option names correctly.

---

Known remaining issue

Zone switches (switch.yuka_yvd5xnzb_zone_zone_*) do not respond to switch.turn_on from HA when the robot is docked. They appear as off (not unavailable) but silently ignore the action. Not blocking since mammotion.start_mow with areas handles zone selection directly, but worth noting.

---

What could be documented

This integration pattern — wrapping a non-vacuum device as a RoboticVacuumCleaner with Custom Service Areas mapping to HA scripts — works well for any device that has zone-based operation but no native Matter support. The key insight: Custom Service Areas don’t need to map to vacuum rooms, they can map to arbitrary HA scripts that do anything.

Thanks again for the quick fixes and for maintaining this add-on. It’s genuinely the only way to get non-Matter devices into Apple Home with real functionality.

Maximilien

[6fjdkhnj4c-droid]

Fixed the first two in the next alpha (28d59dd):

The custom service areas weren't being saved because the API endpoint was missing that field when constructing the request simple oversight on my end. Should persist properly now.

For the zone cleaning, the room mode handler was falling through to vacuum.send_command because it didn't know about custom service areas. Now when you select a zone and press play, it matches the room name to your configured custom area and calls the right script.

About the cleaning mode labels (Bug 3) that one's unfortunately a Matter limitation. Apple Home renders its own localized labels for RvcCleanMode based on the mode tags (Vacuum/Mop/DeepClean), not the custom labels we provide. The cleaningModeEntity is really meant for vacuum/mop type switching. For your mowing trajectories, you might have better luck using the suctionLevelEntity instead those modes show with their actual option names in Apple Home since they map to intensity tags, not cleaning type tags. Worth a try.

Give the next alpha a shot and let me know!

Bug: Custom Service Areas dispatching wrong script — areaId mismatch

Add-on version: 2.1.0-alpha.378
Entity: vacuum.yuka_2000 (template vacuum wrapping a Mammotion Yuka 2000 lawn mower)
Device Type: RoboticVacuumCleaner (0x0074)

---

Description

When selecting a zone in Apple Home and pressing Play, the wrong Custom Service Area script is dispatched. The areaId sent by Apple Home does not map correctly to the configured customServiceAreas array — there appears to be an off-by-one or index mismatch between the Matter areaId (1-based) and the internal customServiceAreas index (0-based).

---

Reproduction

Configuration — Custom Service Areas in HAMH entity mapping:

Position	Name	Service
0	Magnolia	script.yuka_zone_magnolia
1	Pin	script.yuka_zone_pin
2	Saule	script.yuka_zone_saule

Matter cluster state (serviceArea):

supportedAreas: [
  {"areaId": 1, "locationName": "Magnolia"},
  {"areaId": 2, "locationName": "Pin"},
  {"areaId": 3, "locationName": "Saule"}
]

Observed behavior:

Apple Home selection	selectedAreas (Matter cluster)	Script actually dispatched
Magnolia	[1]	script.yuka_zone_magnolia + script.yuka_zone_saule ❌ (two scripts called)
Saule	[3]	script.yuka_zone_magnolia ❌ (wrong script)

Expected behavior:

Apple Home selection	Expected script dispatched
Magnolia	script.yuka_zone_magnolia only
Pin	script.yuka_zone_pin only
Saule	script.yuka_zone_saule only

---

Hypothesis

It looks like HAMH is using the areaId value (1, 2, 3) as a direct array index into customServiceAreas, rather than matching by name or by position. Since the array is 0-indexed, areaId: 3 resolves to customServiceAreas[3] which doesn’t exist → fallback to index 0 (Magnolia). And areaId: 1 somehow triggers both index 0 and index 2.

Could also be that selectedAreas is being iterated and each value is used as an index — which would explain why areaId: 1 triggers two calls (index 0 = Magnolia, and something else).

---

Additional context

• selectedAreas: [3] is correctly set in the Matter cluster when Saule is selected in Apple Home ✅
• The customServiceAreas configuration persists correctly after save (fixed in 28d59dd) ✅
• The bug only affects which script is called — the bridge correctly receives the command and attempts to dispatch

---

Related

This follows on from issue #177 and the fixes in 28d59dd. The zone selection pipeline is working — just the areaId → script resolution is off.

Thanks again for your work on this.

[6fjdkhnj4c-droid]

Hey RiDDiX — sorry, I need to correct something.

The actual bug: when I select a zone in the Apple Home app and press Play, HAMH does not dispatch the selected zone — it dispatches a different zone (I believe the last one that was active in the official Mammotion app, but I'm not 100% sure of the source of that default).

Looking at the serviceArea cluster in the HAMH endpoint detail view, selectedAreas is always [] regardless of which zone I select in Apple Home. It never updates.

supportedAreas:      [Magnolia (id:1), Pin (id:2), Saule (id:3)]  ✅
selectedAreas:       []   ← never changes after zone selection
currentArea:         null
acceptedCommandList: [0, 2]  ← SelectAreas (0) is advertised as accepted

My hypothesis: the SelectAreas command handler receives the command from Apple Home but does not write back to selectedAreas. So when Start fires, it reads [] and falls back to a default zone instead of the one the user selected.

Tested on:

• HAMH Stable (latest) and Alpha v2.0.27 — same behavior on both
• Apple Home controller: Apple TV
• HA 2026.2.3
• Entity: vacuum.yuka_2000 (template vacuum wrapping lawn_mower.yuka_yvd5xnzb)

Happy to provide logs or test any build. And again, sorry for the incorrect report on the Mammotion side.

[6fjdkhnj4c-droid]

[RiDDiX]

1ff6a80

fix: register custom service areas as RvcRunMode room modes for Apple Home zone dispatch
Apple Home does not call ServiceArea.selectAreas before changeToMode. It uses RvcRunMode room modes to trigger zone-specific cleaning. Custom service areas were only registered in the ServiceArea cluster but had no corresponding RvcRunMode entries, causing Apple Home to fall back to generic vacuum.start instead of dispatching the configured HA service.

[6fjdkhnj4c-droid]

✅ Working — Mammotion Yuka 2000 fully operational with zone dispatch

Environment

• Home Assistant 2026.3.x
• HAMH Alpha 2.1.0-alpha.429
• Mammotion integration 0.4.37
• Apple Home (TVOS)

---

What works

Zone selection from Apple Home → correct script dispatched → mower leaves dock and mows the right zone. Tested on 3 zones (Magnolia, Pin, Saule), all working correctly.

The fix registering custom service areas as RvcRunMode room modes was the key — Apple Home uses changeToMode not SelectAreas, and once zones appeared in rvcCleanMode.supportedModes, dispatch worked immediately.

---

Final working configuration

Template vacuum with 3 fan_speeds (one per zone) → HAMH maps them to rvcCleanMode entries → Apple Home sends changeToMode(zone) → HAMH calls set_fan_speed → script triggers native firmware button (button.press on pre-configured task).

---

Thanks for the fast iteration on the selectedAreas / RvcRunMode fixes. The alpha is solid.

[RiDDiX]

Thanks for the detailed feedback and reports! Should also be in main (stable) version since today 2.0.28 :-)