RvcRunMode Cluster

Cluster ID: 0x0054 | Endpoint: Typically on Endpoint 1 (application endpoint) | Base Class: ModeBase (0x0050)

RvcRunMode is a Cluster defined in Matter for robot vacuum cleaners (RVC) to manage run modes. It inherits from ModeBase and specifically manages the robot vacuum's high-level operating states -- Idle, Cleaning, and Mapping. By switching run modes, users can control whether the robot starts cleaning, draws a map, or returns to standby.

Robot Vacuum Cluster Trio

Matter defines three cooperating Clusters for robot vacuums, each managing a different aspect:

RvcRunMode (this page) -- high-level operating state: Idle / Cleaning / Mapping
RvcCleanMode -- cleaning intensity: Quiet / Standard / Deep Clean
RvcOperationalState -- real-time operational state: seeking charger, charging, stuck, etc.

Typical flow: first set the cleaning intensity via RvcCleanMode, then switch to Cleaning mode via RvcRunMode to start work; real-time status during operation (charging, stuck, returning to dock) is reported by RvcOperationalState.

Commands

RvcRunMode inherits from ModeBase with only one command pair: send a mode switch request and the device returns the execution result.

ID	Name	Direction	Description
`0x00`	ChangeToMode	Client → Server	Request switch to specified run mode
`0x01`	ChangeToModeResponse	Server → Client	Return mode switch execution result

ChangeToMode -- Switch Run Mode (0x00)

Request the device to switch to a specified run mode. The mode number must be a valid value defined in SupportedModes. Upon receipt, the device validates whether the current state allows the switch (e.g. it may not be possible to start cleaning while charging), then returns the result via ChangeToModeResponse.

Parameter	Type	Description
NewMode	uint8	Target mode number; must be the Mode field value of a mode in the SupportedModes list

Usage Scenarios

The user taps "Start Cleaning" in the app. The app sends ChangeToMode(NewMode=1) to switch the robot from Idle to Cleaning mode. If the robot's battery is too low or the dust bin is not installed, the device returns the corresponding error status code in the response.

↑ Back to Commands

ChangeToModeResponse -- Switch Result (0x01)

The device's response to the ChangeToMode command. The Status field indicates whether the switch was successful; on failure, a text description is included.

Field	Type	Description
Status	uint8	`0x00` = Success; other values are error codes (see Status Codes section)
StatusText	string (optional)	Human-readable status description for debugging or displaying to the user

Generic Error Codes vs RVC-Specific Error Codes

The Status field's value space is divided into two ranges: 0x00-0x3F for ModeBase generic error codes (e.g. GenericFailure, InvalidInMode), and 0x40-0x7F for robot vacuum-specific error codes (e.g. stuck, dust bin missing). The app needs to handle both ranges.

↑ Back to Commands

Attributes

RvcRunMode inherits three attributes from ModeBase. Note: ModeBase defines StartUpMode (0x0002), but robot vacuums do not support this attribute -- the robot's power-on behavior is determined by OnMode.

ID	Name	Type	Description
`0x0000`	SupportedModes	list<ModeOptionStruct>	List of run modes supported by the device
`0x0001`	CurrentMode	uint8	Current run mode
`0x0003`	OnMode Removed in newer versions	uint8 / null	Mode automatically entered when device wakes up

SupportedModes -- Supported Mode List (0x0000)

All run modes supported by the device. Each mode contains a label name, mode number, and a set of mode tags (ModeTag). The list remains fixed throughout the device's lifecycle.

Field	Type	Description
Label	string	Display name of the mode, e.g. "Cleaning", "Mapping"
Mode	uint8	Mode number, unique within the list, used as the ChangeToMode parameter
ModeTags	list<ModeTagStruct>	Mode tag list identifying the semantic meaning (see Mode Tags section)

↑ Back to Attributes

CurrentMode -- Current Mode (0x0001)

The device's current run mode number. The value must be the Mode field of a mode in SupportedModes. Subscribe to this attribute to track the robot vacuum's operating state changes in real-time.

Subscription Recommendation

It is recommended that apps subscribe to CurrentMode changes rather than polling. When the robot finishes cleaning and automatically returns to Idle mode, or stops due to an error, subscriptions provide real-time notifications.

↑ Back to Attributes

OnMode -- Wake-Up Mode (0x0003) Removed in newer versions

Removed in newer Matter versions

OnMode is no longer part of newer Matter specifications (it is absent from the connectedhomeip v1.6 definitions this site checks against). Devices built to newer versions will not implement it; this section is kept only as a reference for older devices. In newer versions controllers switch modes with the ChangeToMode command.

The mode the device automatically enters when waking from an inactive state. The value is the Mode field of a mode in SupportedModes, or null meaning no automatic mode switch.

No StartUpMode

ModeBase defines the StartUpMode (0x0002) attribute, but RvcRunMode explicitly excludes it. The robot vacuum's power-on behavior is controlled solely by OnMode. If you find 0x0002 does not exist when reading attributes, this is normal.

↑ Back to Attributes

Mode Tags (ModeTag)

Each run mode is identified semantically through ModeTag. ModeTag enables different manufacturers' robots to use different Label text, while apps can still identify whether it's a Cleaning mode or Mapping mode through standardized Tag values.

0x4000

Idle The robot vacuum is in standby, not performing any task

0x4001

Cleaning The robot vacuum is performing a cleaning task

0x4002

Mapping The robot vacuum is scanning the environment and building a map without actual cleaning

Practical Usage of ModeTag

Manufacturer A's cleaning mode is called "Auto Clean" (Mode=1), Manufacturer B calls it "Smart Clean" (Mode=3), but both have 0x4001 (Cleaning) in their ModeTags. Apps should use ModeTag rather than Label or Mode number to determine mode semantics.

Status Codes

The ChangeToModeResponse Status field uses the following error codes. 0x00 indicates success; 0x01-0x03 are ModeBase generic error codes, and 0x41-0x48 are robot vacuum-specific error codes.

Generic Status Codes (ModeBase)

0x00

Success Mode switch successful

0x01

UnsupportedMode The requested mode number is not in SupportedModes

0x02

GenericFailure Generic failure; cannot be attributed to a specific cause

0x03

InvalidInMode Switching to the target mode is not allowed from the current mode

Robot Vacuum-Specific Status Codes

0x41

Stuck The robot is stuck on an obstacle and cannot move

0x42

DustBinMissing Dust bin not properly installed; cleaning start refused

0x43

DustBinFull Dust bin is full; must be emptied before continuing

0x44

WaterTankEmpty Water tank is empty; mopping function cannot start

0x45

WaterTankMissing Water tank not installed

0x46

WaterTankLidOpen Water tank lid not properly closed

0x47

MopCleaningPadMissing Mop / cleaning pad not installed

0x48

BatteryLow Battery level too low to start a task; charging required first

App-Side Error Handling Recommendations

These status codes all correspond to physical issues that users can resolve themselves. When the app receives an error code, it should display clear action guidance to the user, such as "Please empty the dust bin and try again" or "Please install the water tank", rather than a generic "Operation failed". The StatusText field can also serve as fallback display text.

Example Data

Read result of the RvcRunMode Cluster from a robot vacuum supporting three run modes, currently cleaning:

{
  // --- Supported run modes ---
  "0x0000": [                                    // SupportedModes (device supported modes list)
    {
      "Label": "Idle",
      "Mode": 0,
      "ModeTags": [{ "Value": 16384 }]           // 0x4000 = Idle
    },
    {
      "Label": "Cleaning",
      "Mode": 1,
      "ModeTags": [{ "Value": 16385 }]           // 0x4001 = Cleaning
    },
    {
      "Label": "Mapping",
      "Mode": 2,
      "ModeTags": [{ "Value": 16386 }]           // 0x4002 = Mapping
    }
  ],

  // --- Current state ---
  "0x0001": 1               // CurrentMode = 1 (currently cleaning)
}

About ModeTag Values

The ModeTags Value in the example uses decimal: 16384 = 0x4000 (Idle), 16385 = 0x4001 (Cleaning), 16386 = 0x4002 (Mapping). The actual protocol transmission uses integer values; the documentation commonly uses hexadecimal for easy reference against the specification.

Common Scenarios

Scenario 1: Start Cleaning

Read SupportedModes (0x0000), find the mode with 0x4001 (Cleaning) in its ModeTags, and note its Mode number
Send ChangeToMode (0x00) with NewMode set to the number obtained above
Check the ChangeToModeResponse Status:
- 0x00 -- Success, the vacuum starts cleaning
- 0x42 -- Dust bin not installed; prompt the user to install it
- 0x43 -- Dust bin full; prompt the user to empty it
- 0x48 -- Battery low; prompt the user to charge first
Subscribe to CurrentMode (0x0001); when the value returns to the Idle mode number, cleaning is complete

Scenario 2: Query Current Status and Display

Read SupportedModes (0x0000) to get the complete mode list
Read CurrentMode (0x0001) to get the current mode number
Find the matching mode in SupportedModes and display its Label in the app UI (e.g. "Cleaning")
Also check the Tag values in ModeTags to assist UI display with standardized semantics:
- 0x4000 (Idle) -- Display standby icon
- 0x4001 (Cleaning) -- Display cleaning animation
- 0x4002 (Mapping) -- Display map scanning progress