RvcOperationalState Cluster

Cluster ID: 0x0061  |  Endpoint: Typically on Endpoint 1 (application endpoint)  |  Derived from: OperationalState (0x0060)

RvcOperationalState is a OperationalState (0x0060) robot vacuum-specific derived Cluster. It inherits all attributes and event structures from the base state machine, but with important adjustments based on the actual usage scenarios of robot vacuums:

• Removed Start and Resume commands -- robot vacuums start by selecting a cleaning mode via the RvcRunMode Cluster, not by using Start directly
• Added GoHome command (0x80) -- instructs the robot to return to the charging dock
• Extended with 3 RVC-specific operational states -- SeekingCharger, Charging, and Docked
• Extended with 8 RVC-specific error codes -- covering common faults involving the charging dock, stuck conditions, dust bin, water tank, mop pad, etc.

Commands

The RvcOperationalState Cluster has 3 commands. Compared to the base OperationalState's 4 commands, Start (0x02) and Resume (0x03) are removed, because robot vacuum startup and mode switching are handled by the RvcRunMode Cluster. A new GoHome (0x80) command is added for instructing the robot to return to the charging dock. All commands return an OperationalCommandResponse after execution, containing an ErrorStateStruct indicating whether the operation succeeded.

Pause (0x00)

Pauses the robot's current operation (cleaning, returning to dock, etc.). On success, the OperationalState attribute changes to Paused (2). The robot stops in place and retains its current position and cleaning progress. No parameters required.

↑ Back to Commands

Stop (0x01) Removed in newer versions

Completely stops the robot's current operation. On success, the OperationalState attribute changes to Stopped (0). Unlike Pause, Stop terminates the current cleaning task, and a new mode must be selected via RvcRunMode to start a new cleaning session. No parameters required.

↑ Back to Commands

GoHome -- Return to Charging Dock (0x80)

RVC-specific command. Instructs the robot to stop its current operation and return to the charging dock. On success, the OperationalState attribute changes to SeekingCharger (0x40), and the robot begins automatically navigating back to the charging dock. Upon arrival, the state sequentially changes to Charging (0x41) → Docked (0x42). No parameters required.

↑ Back to Commands

OperationalCommandResponse -- Command Response

All three commands (Pause/Stop/GoHome) return this response after execution. It contains an ErrorStateStruct indicating whether the command succeeded.

↑ Back to Commands

Attributes

The RvcOperationalState Cluster inherits all 6 attributes from the base OperationalState, with identical definitions. Click an attribute ID in the summary table below to jump to its detailed description.

Phase Info (0x0000, 0x0001, 0x0002)

Describes the phase progress and remaining time of the robot's current cleaning task. Robot vacuum phases may include: main area sweeping, edge sweeping, mopping, returning to dock, etc.

↑ Back to Attributes

Operational State (0x0003, 0x0004, 0x0005)

Describes the robot's operational state and error information. OperationalStateList contains the base 4 states plus the 3 RVC-extended states (SeekingCharger/Charging/Docked).

↑ Back to Attributes

Enum Definitions

OperationalStateEnum -- Operational States

The RVC operational state enum inherits the 4 standard values (0~3) from the base OperationalState, and extends with 3 robot vacuum-specific states in the 0x40~0x42 range.

Base States (Inherited from OperationalState)

RVC Extended States

ErrorStateEnum -- Error Types

The RVC error state enum inherits the base 4 generic error codes (0~3), and extends with 8 robot vacuum-specific error codes in the 0x40~0x47 range, covering common issues with the charging dock, mechanical faults, consumables, etc.

Base Error Codes (Inherited from OperationalState)

RVC Extended Error Codes

Data Structures

ErrorStateStruct -- Error State Structure

Used to describe the robot's error information. Used for both the OperationalError attribute and command responses. The structure is identical to the base OperationalState.

OperationalStateStruct -- Operational State Structure

Used in the OperationalStateList attribute to describe each operational state supported by the robot.

Events

The RvcOperationalState Cluster inherits 2 events from the base OperationalState, used to notify the controller of important state changes in the robot.

OperationalError Event

This event is triggered when the robot enters an error state. The event priority is CRITICAL, ensuring that apps receive timely error notifications (e.g. robot stuck, dust bin full, etc.).

OperationCompletion Event

This event is triggered when the robot completes a full cleaning cycle. The event priority is INFO. The event carries time statistics for the cleaning session, enabling apps to display cleaning reports.

Example Data

Read result of the RvcOperationalState Cluster from a robot vacuum currently cleaning:

{
  // --- Phase info ---
  "0x0000": ["Main Brush Sweep", "Edge Sweep", "Returning to Dock"],  // PhaseList (operation phase list)
  "0x0001": 0,                                    // CurrentPhase = 0 (currently in "Main Brush Sweep" phase)
  "0x0002": 2400,                                  // CountdownTime = 2400 seconds (approximately 40 minutes remaining)

  // --- Operational state ---
  "0x0003": [                                      // OperationalStateList (device-supported state list)
    { "OperationalStateID": 0, "OperationalStateLabel": "Stopped" },
    { "OperationalStateID": 1, "OperationalStateLabel": "Running" },
    { "OperationalStateID": 2, "OperationalStateLabel": "Paused" },
    { "OperationalStateID": 3, "OperationalStateLabel": "Error" },
    { "OperationalStateID": 64, "OperationalStateLabel": "Seeking Charger" },
    { "OperationalStateID": 65, "OperationalStateLabel": "Charging" },
    { "OperationalStateID": 66, "OperationalStateLabel": "Docked" }
  ],
  "0x0004": 1,                                     // OperationalState = Running (currently cleaning)
  "0x0005": {                                      // OperationalError (no current error)
    "ErrorStateID": 0,
    "ErrorStateLabel": "",
    "ErrorStateDetails": ""
  }
}

Common Scenarios

Scenario 1: Complete Cleaning Lifecycle

1. The robot is in Docked (0x42) state, parked on the charging dock on standby
2. The user sends a ChangeToMode command via the RvcRunMode Cluster, selecting the "Standard Cleaning" mode
3. The robot leaves the dock, its state changes to Running (1), and cleaning begins
4. The app subscribes to OperationalState, CurrentPhase, and CountdownTime to update cleaning progress and remaining time in real time
5. After cleaning is complete, the robot automatically enters SeekingCharger (0x40) state to return to dock
6. After reaching the dock, it changes to Charging (0x41), and to Docked (0x42) when fully charged
7. The OperationCompletion event is triggered; the app displays a cleaning report: "Cleaning complete, total duration 45 minutes"

Scenario 2: Error Handling During Cleaning

1. The robot is cleaning (Running (1)) and suddenly gets stuck on a carpet edge
2. The robot fails to free itself, its state changes to Error (3), and OperationalError updates to:
   • ErrorStateID = 0x41 (Stuck)
   • ErrorStateLabel = "Robot Stuck"
   • ErrorStateDetails = "Left wheel cannot rotate; please check for foreign objects"
3. The device triggers the OperationalError event (CRITICAL priority); the app shows a push notification
4. The app displays corresponding action guidance based on error code 0x41 (Stuck): "Please move the robot to an open area"
5. After the user resolves the issue, send Stop (0x01) Removed in newer versions to clear the error state
6. Restart the cleaning task via RvcRunMode

Scenario 3: Manual Return to Dock (GoHome)

1. The robot is cleaning (Running (1)) and the user wants it to return to dock early
2. The app sends the GoHome (0x80) command
3. The robot stops cleaning, its state changes to SeekingCharger (0x40), and it begins automatically navigating back to the dock
4. The app can display a "Returning to charging dock..." status message
5. After the robot arrives at the dock, its state changes to Charging (0x41)
6. If the dock cannot be found during navigation, the state changes to Error (3), with error code FailedToFindChargingDock (0x40)
7. The app displays: "Cannot find the charging dock. Please check that the dock is powered on and the area in front is clear."