Device mapping 3: special devices

Special devices are the ones that build fine and still do not work

This group of domains spans completely different meanings: media_player has volume and playback, select has options, valve has an open and closed state, event has only events, and script triggers an action. Where Matter has no one-to-one device type, Home Assistant Matter Hub picks the closest thing it has: Mode Select, Generic Switch, On/Off Plug-in Unit or Robotic Vacuum Cleaner.

So you cannot decide that support is complete just because a tile turns up in the controller. Whether that tile stays on, whether it can only be pressed once, whether off really calls an HA action, whether the controller can render a Mode Select, and whether the device needs Server Mode are all separate questions.

Alarms, sirens, valves, water heating and robots act on the real world. Confirm them first with read-only state and low-risk commands, then decide whether to expose them to voice control or to a household with several people. Matter Hub is not a safety interlock or a personal-monitoring system.

The 17 HomeAssistantDomain values in this chapter

Stable 2.0.55 has 27 HomeAssistantDomain values in all: Chapter 9 covers 7 of them, Chapter 10 covers 3, and this chapter covers the remaining 17, so no rare domain is left out.

domainToDefaultMatterTypes is the candidate matrix for the picker, not the literal name of the final endpoint for every domain. The candidates for automation, scene and script say on_off_switch, while the legacy implementation builds on an On/Off Plug-in Unit device base and keeps the momentary off semantics. Documentation should describe observable behavior, and should not put type candidates and the underlying class on the same level.

Media players, speakers, valves, pumps and water heating

If a media_player has device_class TV, it automatically uses basic_video_player; an explicit speaker override bypasses the TV detection. A speaker drives OnOff as a power control only when it supports both TURN_ON and TURN_OFF; otherwise, where it has a mute capability, mute takes that place. VOLUME_SET adds a 0–254 compatibility volume control, SELECT_SOURCE adds input sources, and PLAY or PAUSE adds playback control.

A valve can add a Power Source from a battery attribute or from batteryEntity; open and close call the matching HA valve actions, and opening and closing show as Transitioning. When a pump comes from a switch override, the turn_on and turn_off behavior of the source integration is still what counts. Boost on a water heater involves energy use and a scalding risk, so whether the controller shows a button is not how you judge that it is safe.

select, alarm, event, doorbell and siren

select and input_select build a Mode Select out of a non-empty options list and find the current option case-insensitively; with no options, no endpoint is built. In the pinned matrix, mode_select is no for Apple, Google and Alexa, and unknown for Aqara. If the controller cannot render it, set selectExposeAsSwitch and name selectSwitchOnOption and selectSwitchOffOption explicitly, which folds two options into a persistent On/Off. Beyond two modes this workaround no longer fits.

alarm_control_panel has no dedicated Matter security panel type, so a Mode Select is used to carry the HA support bits: Disarmed, Armed Home, Away, Night, Vacation, Custom. The in-between states arming, pending and triggered do not map to a fixed mode. On platforms that do not support Mode Select there is an On/Off fallback: on arms in the order Away, Home, Night, and off disarms. That loses the extra modes, and if the real integration needs extra authentication, the controller command can fail.

event defaults to a Generic Switch and detects double, triple and multi press from the event_types names; in the pinned matrix, generic_switch is partial for Apple, no for Google, yes for Alexa and unknown for Aqara. The doorbell override is an experimental Matter 1.4 type inside Stable, and Apple, Google, Alexa and Aqara are all no; the source note says only SmartThings renders it today, and other platforms fall back to a plain Switch at best. It is not the Camera Plugin, and it carries no video.

siren is a persistent state: on and off call siren.turn_on and siren.turn_off, so do not confuse it with a momentary event. Testing a siren can disturb the neighbors or cause panic; check in HA first whether a silent test is possible, and if it is not, only cross-check the endpoint and do not start it remotely.

dishwasher, vacuum, lawn_mower and Service Area

dishwasher is an optional Matter override for switch with maturity stable, but Apple and Google are no and Alexa and Aqara are unknown; the pinned source note says platform support for appliances is thin. Labeling an arbitrary switch as a dishwasher adds no cycles, no door lock and no finish time — it only changes the device type.

vacuum builds a Robotic Vacuum Cleaner with an operational state, a run mode, a Power Source, Service Area and a clean mode that is always present. OnOff is not part of the standard RVC device type and is not added by default, because a non-conformant endpoint makes Alexa reject the device; it is added only when the vacuumOnOff feature flag is explicitly on. robot_vacuum_cleaner is yes for Apple, Google, Alexa and Aqara, but Apple voice control and Alexa discovery are better served by Server Mode in Chapter 12.

Service Area can come from cleanAreaRooms, customServiceAreas, resolved rooms or roomEntities; with no rooms at all, a single default area is still created. vacuumIncludeUnnamedRooms controls whether unnamed rooms are included; vacuumRoomSwitches can create one momentary switch per area for platforms that do not render array commands. Linked options such as cleaningModeEntity, suctionLevelEntity and mopIntensityEntity decide the clean mode, and a similar name is not a reason to assume the right one was picked.

lawn_mower has no native Matter mower type; v2.0.55 represents it as a Robotic Vacuum Cleaner and uses the mower run and operational states. In the pinned matrix robotic_lawn_mower is yes for Apple and Alexa and unknown for Google and Aqara, and the UI will look like a robot vacuum. A Power Source is added only where a battery attribute or a mapping exists.

momentary, auto-reset and disableMomentaryFlip

A persistent state always reflects the device's current value — input_boolean, remote, siren, valve and select, for example. on and off usually each have an HA action, and after the controller changes something you should wait for the source state to be reported back.

A momentary action only fires: automation calls trigger, scene and script accept turn on only, and button and input_button only press. They normally stay off; when an on arrives they act once, and the controller should not treat that as something that keeps running.

The momentary behavior of script, scene, automation and input_button optimistically reports on and then returns to off after about a second, so the controller does not look stuck; button is different, and always reports off, never set to true. Some Echo devices get stuck on the unrequested on→off report pair. The entity mapping option disableMomentaryFlip genuinely skips the flip for the first four, but for button it only skips a timer that never changed the state anyway. The underlying HA action still fires. This is a workaround for one particular controller, not a way of turning a momentary action into a persistent one, and it should not be switched on globally without looking.

The smallest workflow for mapping a special device

1. Classify it as a state, a mode or an action

   In HA, first work out whether the entity is a persistent state, a Mode Select or a momentary action. Record it with a placeholder such as script.example_action, so live environment data does not end up in your notes.

2. Look at the default mapping in Devices

   Search for the entity on the Matter Hub Devices page and cross-check the domain against the automatic type. For a media player, also look at device_class and the supported features; for a vacuum, look at the room and mode attributes.

3. Compare it against the target controller

   Support for Mode Select, speaker, TV, valve, water heater and appliance types varies a lot. Check the matrix first, then decide whether you need a fallback or Server Mode.

4. Change one mapping at a time

   Set speaker, pump, water valve or select-as-switch where you need them; for momentary entities, turn on disableMomentaryFlip only once you have confirmed that an Echo is getting stuck. Write down the original value before you save.

5. Start with a read-only or low-risk check

   Compare modes, volume, areas and states; for buttons, use a test action that does no harm. Sirens, water heating, pumps, valves, vacuums and lawn mowers need someone present and a way to stop them.

6. Confirm the controller command and what HA reports back

   For persistent types, test on and off; for momentary ones, test a single on and confirm the action fired exactly once. If it fails, roll the mapping back rather than resetting the fabric first.

Special-device pitfalls and fallback points

1. Mode Select does not appear at all

   Apple, Google and Alexa are all no in the pinned matrix. Use select-as-switch when there are exactly two clear options; with more options, keep the control in HA rather than sacrificing the meaning to force it into a switch.

2. script, scene, automation or input_button is stuck on in the controller

   First confirm that the action fired only once, and that the state returns to off shortly afterwards. If a particular Echo is getting stuck on the on→off report, then turn on disableMomentaryFlip for that entity. A plain button always reports off, so the flip is not what you troubleshoot there.

3. off on an automation does not disable the automation

   That is the expected behavior: this mapping is a momentary trigger, not an enable switch for the automation. If you need a persistent enable and disable, build an explicit, safe input_boolean flow in HA.

4. A TV or speaker shows only some of the controls

   Cross-check the TURN_ON/OFF, VOLUME_MUTE, VOLUME_SET, SELECT_SOURCE, PLAY and PAUSE feature bits, then check whether the controller shows that cluster. An override never adds a capability the source device does not provide.

5. Alexa rejects the vacuum

   Confirm that vacuumOnOff is not on where it is not needed, since OnOff is not part of the RVC spec. Then consider building a dedicated node with Server Mode in Chapter 12, so it is not mixed into the same bridge as other unsupported types.

6. The lawn mower shows up as a robot vacuum

   That is the compatibility design in v2.0.55, because Matter has no mower type yet. If the name and the risk of a remote start are not acceptable, do not expose it to that controller and keep the control in HA.

FAQ

Stable 2.0.55 pinned sources

• The complete HomeAssistantDomain enum
• Special overrides, momentary settings and the controller matrix
• Every legacy domain endpoint implementation
• RVC, Service Area, Clean Mode and the OnOff limits
• Mode Select and the switch fallback
• Pinned add-on mirror

All of the above are pinned to the stated commit. The experimental doorbell and water heater management types are stated separately from controller support, so the Stable channel is not written up as full production support.