Robot Status¶

Endpoints that provide real-time information on the robot's health and operational state, including connectivity, battery, emergency stop, mission, pose, navigation, and error codes.

GetRobotStatus¶

Get the latest robot state.

Robot state includes connectivity and operational states.

Request¶

The request takes no parameters.

JSON Request Example¶

JSON

{}

Response¶

robot_state `RobotState`¶

The current robot state including connectivity, battery, emergency stop, mission, pose, error information, and velocity.

Field	Message Type	Description
`connection`	`RobotConnection`	Connection state of the robot.
`battery`	`BatteryState`	Battery state of the robot.
`emergency_stop`	`EmergencyStopState`	Emergency stop state of the robot.
`mission`	`MissionState`	Mission state of the robot.
`pose`	`Pose`	Current pose of the robot.
`error_codes`	`ErrorCodes`	Error codes returned by the robot.
`typed_status`	oneof	Robot type-specific state information. Only one type may be set at a time.
`twist`	`Twist`	Current linear and angular velocity of the robot. Omitted when not reported by the robot.
`localization_state`	`LocalizationState`	Localization state of the robot.
`navigation_state`	`NavigationState`	Navigation-related state of the robot, including whether it is currently stuck.

Twist¶

Represents the current velocity of the robot in 2D (linear along the forward axis, angular around the vertical axis). Omitted when the robot does not report velocity.

Field	Message Type	Description
`linear_velocity`	`float`	Current speed along the robot's forward axis, in m/s. Positive for forward, negative for reverse.
`angular_velocity`	`float`	Current rotation rate, in rad/s. Positive for clockwise when viewed from above.

NavigationState¶

Represents navigation-related state for the robot.

Field	Message Type	Description
`stuck_state`	`StuckState`	Whether the robot is currently stuck (unable to make navigation progress) and, when known, the reason.

StuckState¶

Represents whether the robot is currently unable to make navigation progress, and the reason for it when known. "Stuck" is distinct from a mission failure: it is a transient, recoverable navigation condition (e.g., obstruction, restricted area) in which the robot has stopped moving but is otherwise healthy.

Field	Message Type	Description
`state`	`State` enum	Current stuck state of the robot.
`reason`	`Reason` enum	Reason the robot is stuck. Only meaningful when `state` is `STATE_STUCK`; otherwise expect `REASON_UNKNOWN`.

(StuckState) State `enum`¶

Name	Number	Description
STATE_UNKNOWN	0	Default unset value. Treat as an error if received.
STATE_NOT_STUCK	1	The robot is operating normally and not stuck.
STATE_STUCK	2	The robot is unable to make navigation progress. See `reason` for the cause when available.

(StuckState) Reason `enum`¶

Name	Number	Description
REASON_UNKNOWN	0	No reason reported. Set when `state` != `STATE_STUCK`, or when the upstream stack did not provide a discrete cause.
REASON_PATH_BLOCKED	1	The planned path is blocked at runtime by a dynamic obstacle.
REASON_DESTINATION_OBSTRUCTED	2	The destination cell is occupied by an obstacle. Reserved for future use; not currently emitted by the robot.
REASON_DESTINATION_UNREACHABLE	3	No feasible path exists to the destination. Reserved for future use; not currently emitted by the robot.
REASON_INSIDE_RESTRICTED_AREA	4	The robot is inside a restricted/annotated area it cannot leave (e.g., a no-go zone it was placed into).

RobotConnection¶

Represents the online connection state between the cloud and the robot.

Field	Message Type	Description
`state`	`State` enum	Current connection state of the robot.

BatteryState¶

Represents the state of the robot's battery system.

Field	Message Type	Description
`charge_percent`	`int32`	State of charge, from 0 (empty) to 100 (fully charged).
`state`	`State` enum	High-level charging state of the battery.
`charge_method`	`ChargeMethod` enum	Method by which the robot is being charged.

EmergencyStopState¶

Represents the state of the robot's emergency stop system.

Field	Message Type	Description
`emergency`	`Emergency` enum	Whether the software level emergency stop is engaged.
`button_pressed`	`Emergency` enum	Whether the physical emergency stop button is engaged.

ErrorCodes¶

Represents the error codes returned by the robot.

Field	Message Type	Description
`codes`	repeated `ErrorCode`	List of error codes currently active on the robot. See SubscribeErrorCodes for the `ErrorCode` and `Severity` definitions.

typed_status `oneof`¶

Robot type-specific state information. Only one type may be set at a time.

Field (oneof)	Message Type	Description
`servi_state`	`ServiState`	Populated when the robot type is a Servi.
`carti_state`	`CartiState`	Populated when the robot type is a Carti.

ServiState¶

Represents the set of robot states specifically for Servi robots.

Field	Message Type	Description
`tray_states`	`TrayStates`	A collection of individual tray states from different trays.

CartiState¶

Represents the set of robot states specifically for Carti robots.

Field	Message Type	Description
`conveyor_state`	`ConveyorState` optional	Conveyor state, only available for robots with a conveyor installed.

(RobotConnection) State `enum`¶

Name	Number	Description
STATE_UNKNOWN	0	Default value. It means the `state` field is not returned.
STATE_CONNECTED	1	The robot is connected to Bear cloud services.
STATE_DISCONNECTED	2	The robot is offline or unreachable from the cloud.

(BatteryState) State `enum`¶

Name	Number	Description
STATE_UNKNOWN	0	Default value. It means the `state` field is not returned.
STATE_CHARGING	1	Battery is currently charging.
STATE_DISCHARGING	2	Robot is not connected to a charger and is consuming battery power.
STATE_FULL	3	Battery is fully charged while connected to a charger; no additional energy is being stored.

(BatteryState) ChargeMethod `enum`¶

Name	Number	Description
CHARGE_METHOD_UNKNOWN	0	Default value. It means the `charge_method` field is not returned.
CHARGE_METHOD_NONE	1	No charging method is currently active or applicable.
CHARGE_METHOD_WIRED	2	Charging via a wired connection.
CHARGE_METHOD_CONTACT	3	Charging via contact-based interface (e.g., docking station).

(EmergencyStopState) Emergency `enum`¶

Name	Number	Description
EMERGENCY_UNKNOWN	0	Default value. It means the `emergency` field is not returned.
EMERGENCY_ENGAGED	1	Triggers an emergency stop. Overrides and sets navigation-related velocity command to 0 to the motor.
EMERGENCY_DISENGAGED	2	Wheels will resume acting upon software navigation commands.

JSON Response Example¶

JSON

  {
    "robotState": {
      "connection": {
        "state": "STATE_CONNECTED"
      },
      "battery": {
        "chargePercent": 85,
        "state": "STATE_CHARGING",
        "chargeMethod": "CHARGE_METHOD_CONTACT"
      },
      "emergencyStop": {
        "emergency": "EMERGENCY_DISENGAGED",
        "buttonPressed": "EMERGENCY_DISENGAGED"
      },
      "mission": {
        "missionId": "mission-123",
        "state": "STATE_RUNNING",
        "goals": [],
        "currentGoalIndex": 0
      },
      "pose": {
        "xMeters": 1.5,
        "yMeters": 2.8,
        "headingRadians": 0.78
      },
      "errorCodes": {
        "codes": [
          { "code": 1001, "severity": "SEVERITY_MEDIUM", "message": "Low battery warning" },
          { "code": 2042, "severity": "SEVERITY_HIGH", "message": "Camera connection lost" }
        ]
      },
      "twist": {
        "linearVelocity": 0.5,
        "angularVelocity": 0.0
      },
      "localizationState": {
        "state": "STATE_SUCCEEDED"
      },
      "navigationState": {
        "stuckState": {
          "state": "STATE_NOT_STUCK",
          "reason": "REASON_UNKNOWN"
        }
      },
      "serviState": {
        "trayStates": {
          "trayStates": [
            {
              "trayName": "top",
              "loadState": "LOAD_STATE_LOADED",
              "weightKg": 2.5,
              "loadRatio": 0.8
            },
            {
              "trayName": "middle",
              "loadState": "LOAD_STATE_EMPTY",
              "weightKg": 0.0,
              "loadRatio": 0.0
            }
          ]
        }
      }
    }
  }

Errors¶

ErrorCode	Description
`INTERNAL`	Communication failure with the robot.

SubscribeRobotStatus¶

Streaming mode: event

A server side streaming RPC endpoint to get the robot's connectivity and operational state.

Upon subscription, the latest robot state is sent immediately. Updates are streamed as the robot's state changes.

Request¶

The request takes no parameters.

JSON Request Example¶

JSON

{}

Response¶

metadata `EventMetadata`¶

Field	Message Type	Description
`timestamp`	`Timestamp`	The time when the event was recorded.
`sequence_number`	`int64`	An incremental sequence number generated by the robot. The sequence number should never be negative and can be reset to 0. i.e. sequence is valid if it is larger than the previous number or 0.

robot_state `RobotState`¶

The current robot state including connectivity, battery, emergency stop, mission, pose, error information, and velocity.

Field	Message Type	Description
`connection`	`RobotConnection`	Connection state of the robot.
`battery`	`BatteryState`	Battery state of the robot.
`emergency_stop`	`EmergencyStopState`	Emergency stop state of the robot.
`mission`	`MissionState`	Mission state of the robot.
`pose`	`Pose`	Current pose of the robot.
`error_codes`	`ErrorCodes`	Error codes returned by the robot.
`typed_status`	oneof	Robot type-specific state information. Only one type may be set at a time.
`twist`	`Twist`	Current linear and angular velocity of the robot. Omitted when not reported by the robot.
`localization_state`	`LocalizationState`	Localization state of the robot.
`navigation_state`	`NavigationState`	Navigation-related state of the robot, including whether it is currently stuck.

JSON Response Example¶

JSON

{
  "metadata": {
    "timestamp": "2025-04-01T17:05:00Z",
    "sequenceNumber": 211
  },
  "robotState": {
    "connection": {
      "state": "STATE_CONNECTED"
    },
    "battery": {
      "chargePercent": 75,
      "state": "STATE_CHARGING",
      "chargeMethod": "CHARGE_METHOD_CONTACT"
    },
    "emergencyStop": {
      "emergency": "EMERGENCY_DISENGAGED",
      "buttonPressed": "EMERGENCY_DISENGAGED"
    },
    "mission": {
      "missionId": "mission-456",
      "state": "STATE_RUNNING",
      "goals": [
        {
          "goal": {
            "pose": {
              "xMeters": 5.2,
              "yMeters": 3.1,
              "headingRadians": 0.0
            }
          }
        }
      ],
      "currentGoalIndex": 1
    },
    "pose": {
      "xMeters": 2.1,
      "yMeters": 1.8,
      "headingRadians": 1.2
    },
    "errorCodes": {
      "codes": [
        { "code": 1001, "severity": "SEVERITY_MEDIUM", "message": "Low battery warning" },
        { "code": 2042, "severity": "SEVERITY_HIGH", "message": "Camera connection lost" }
      ]
    },
    "twist": {
      "linearVelocity": 0.3,
      "angularVelocity": 0.0
    },
    "localizationState": {
      "state": "STATE_SUCCEEDED"
    },
    "navigationState": {
      "stuckState": {
        "state": "STATE_STUCK",
        "reason": "REASON_PATH_BLOCKED"
      }
    }
  }
}

Errors¶

ErrorCode	Description
`INTERNAL`	Internal server error occurred while processing the request.

SubscribeNavigationStatus¶

Streaming mode: event

A server side streaming RPC endpoint to subscribe to the robot's navigation status.

Upon subscription, the latest known navigation state is sent immediately. Subsequent updates are streamed as the state changes.

The stuck state indicates the robot is unable to make navigation progress (e.g., blocked by an obstacle or inside a restricted area) and is distinct from a mission failure.

Tip

Prefer this RPC over SubscribeRobotStatus when only the navigation signal is of interest; the full robot status carries more data and updates more frequently.

Request¶

The request takes no parameters.

JSON Request Example¶

JSON

{}

Response¶

metadata `EventMetadata`¶

Field	Message Type	Description
`timestamp`	`Timestamp`	The time when the event was recorded.
`sequence_number`	`int64`	An incremental sequence number generated by the robot. The sequence number should never be negative and can be reset to 0. i.e. sequence is valid if it is larger than the previous number or 0.

navigation_state `NavigationState`¶

The current navigation-related state of the robot. See NavigationState and StuckState for field and enum definitions.

JSON Response Example¶

JSON

{
  "metadata": {
    "timestamp": "2025-04-01T17:20:00Z",
    "sequenceNumber": 87
  },
  "navigationState": {
    "stuckState": {
      "state": "STATE_STUCK",
      "reason": "REASON_PATH_BLOCKED"
    }
  }
}

Errors¶

ErrorCode	Description
`INTERNAL`	Internal server error occurred while processing the request.

SubscribeErrorCodes¶

Streaming mode: event

A server side streaming RPC endpoint to subscribe to error codes returned by the robot.

Upon subscription, the latest known error codes are sent immediately. Updates are streamed when error codes change.

Request¶

The request takes no parameters.

JSON Request Example¶

JSON

{}

Response¶

error_codes `ErrorCodesWithMetadata`¶

The error codes reported by the robot, together with the event metadata.

Field	Message Type	Description
`metadata`	`EventMetadata`	Metadata associated with the event.
`codes`	repeated `ErrorCode`	Error codes returned by the robot during the event.

ErrorCode¶

Represents a single error reported by the robot.

Field	Message Type	Description
`code`	`int32`	Integer code indicating the type of error. Does not indicate severity.
`severity`	`Severity` enum	Level of criticality of an error.
`message`	`string`	Message about the error e.g. "Up camera process error."

(ErrorCode) Severity `enum`¶

Name	Number	Description
SEVERITY_UNKNOWN	0	Default value. It means the `severity` field is not returned.
SEVERITY_LOW	1	Low severity indicates an identified issue that is not visible.
SEVERITY_MEDIUM	2	Medium severity indicates an identified issue that does not block operation.
SEVERITY_HIGH	3	High severity indicates an identified issue that blocks operation.

JSON Response Example¶

JSON

{
  "errorCodes": {
    "metadata": {
      "timestamp": "2025-04-01T17:10:00Z",
      "sequenceNumber": 215
    },
    "codes": [
      {
        "code": 1001,
        "severity": "SEVERITY_MEDIUM",
        "message": "Low battery warning"
      },
      {
        "code": 2042,
        "severity": "SEVERITY_HIGH",
        "message": "Camera connection lost"
      }
    ]
  }
}

Errors¶

ErrorCode	Description
`INTERNAL`	Internal server error occurred while processing the request.

Robot Status¶

GetRobotStatus¶

Request¶

JSON Request Example¶

Response¶

robot_state RobotState¶

Twist¶

NavigationState¶

StuckState¶

(StuckState) State enum¶

(StuckState) Reason enum¶

RobotConnection¶

BatteryState¶

EmergencyStopState¶

ErrorCodes¶

typed_status oneof¶

ServiState¶

CartiState¶

(RobotConnection) State enum¶

(BatteryState) State enum¶

(BatteryState) ChargeMethod enum¶

(EmergencyStopState) Emergency enum¶

JSON Response Example¶

Errors¶

SubscribeRobotStatus¶

Request¶

JSON Request Example¶

Response¶

metadata EventMetadata¶

robot_state RobotState¶

JSON Response Example¶

Errors¶

SubscribeNavigationStatus¶

Request¶

JSON Request Example¶

Response¶

metadata EventMetadata¶

navigation_state NavigationState¶

JSON Response Example¶

Errors¶

SubscribeErrorCodes¶

Request¶

JSON Request Example¶

Response¶

error_codes ErrorCodesWithMetadata¶

ErrorCode¶

(ErrorCode) Severity enum¶

JSON Response Example¶

Errors¶

robot_state `RobotState`¶

(StuckState) State `enum`¶

(StuckState) Reason `enum`¶

typed_status `oneof`¶

(RobotConnection) State `enum`¶

(BatteryState) State `enum`¶

(BatteryState) ChargeMethod `enum`¶

(EmergencyStopState) Emergency `enum`¶

metadata `EventMetadata`¶

robot_state `RobotState`¶

metadata `EventMetadata`¶

navigation_state `NavigationState`¶

error_codes `ErrorCodesWithMetadata`¶

(ErrorCode) Severity `enum`¶