Robot API Service¶

The definition of Bear Robot API service.

Map¶

GetLocation¶

Request Type: GetLocationRequest
Response Type: GetLocationResponse
Description: Retrieve the current location data to which the robot is connected from the Universe. If the robot is offline, it uses the cached Location data.

GetMapContent¶

Request Type: GetMapContentRequest
Response Type: GetMapContentResponse
Description: Retrieve the current map content data, which is loaded on the robot.

SwitchMap¶

Request Type: SwitchMapRequest
Response Type: SwitchMapResponse
Description: Switches the current map to a specified map.
The request should specify a floor level and section index to be used. Returns the map_id of the switched map.

Mission¶

AppendMission¶

Request Type: AppendMissionRequest
Response Type: AppendMissionResponse
Description: Appends the given mission to the end of the queue.
The mission will be added in the order it is received.

ChargeRobot¶

Request Type: ChargeRobotRequest
Response Type: ChargeRobotResponse
Description: Create a mission to go charge a robot regardless of battery state.
The call will fail if the robot is already on a different mission. The current mission needs to be canceled before the robot can be charged.

CreateMission¶

Request Type: CreateMissionRequest
Response Type: CreateMissionResponse
Description: Creates a mission for a given type.
The call will fail if the robot cannot go on the requested mission.

SubscribeMissionStatus¶

Request Type: SubscribeMissionStatusRequest
Response Type: SubscribeMissionStatusResponse
Description: Subscribe to robot's mission status.
Upon subscription, the server immediately sends the latest known mission status, followed by updates whenever the mission status changes.

UpdateMission¶

Request Type: UpdateMissionRequest
Response Type: UpdateMissionResponse
Description: Updates the specified mission with the given command.
The call will fail if the robot is not on the specified mission or cannot execute the command.

DriveRobot¶

Request Type: DriveRobotRequest
Response Type: DriveRobotResponse
Description: Manually drive the robot.
A fine grained level manual drive control that allows the user to specify a desired linear and angular velocity. The command will be smoothed by the robot. The request message should be streamed at a rate of at least 5Hz for smooth operation. If the frequency doesn't meet the requirements, it will set the commanded velocity to zero.

LocalizeRobot¶

Request Type: LocalizeRobotRequest
Response Type: LocalizeRobotResponse
Description: Localize the robot to a localization goal.
If the goal is accepted, subcribe to SubscribeLocalizationStatus to get the localization status.

SetEmergencyStop¶

Request Type: SetEmergencyStopRequest
Response Type: SetEmergencyStopResponse
Description: Enable or disable the emergency stop.

SetPose¶

Request Type: SetPoseRequest
Response Type: SetPoseResponse
Description: Manually set the robot pose given a pose on the map and covariance matrix.

SubscribeEmergencyStopStatus¶

Request Type: SubscribeEmergencyStopStatusRequest
Response Type: SubscribeEmergencyStopStatusResponse
Description: Subscribe to the software emergency stop state.
Upon subscription, the server sends the current emergency stop state, followed by updates whenever the emergency stop state changes.

SubscribeLocalizationStatus¶

Request Type: SubscribeLocalizationStatusRequest
Response Type: SubscribeLocalizationStatusResponse
Description: Subscribe to the robot's localization status.
Upon subscription, the latest known localization status will be sent. If the robot is actively localizing, status will be published upon changes.

SubscribeOdometryStatus¶

Request Type: SubscribeOdometryStatusRequest
Response Type: SubscribeOdometryStatusResponse
Description: Subscribe to the robot's odometry status.
Upon subscription, the server provides regular updates (5Hz) of the odometry status.

SubscribeRobotPose¶

Request Type: SubscribeRobotPoseRequest
Response Type: SubscribeRobotPoseResponse
Description: Subscribe to the robot's pose.
Upon subscription, the server provides regular updates (5Hz) of the robot's estimated position.

Settings¶

SetSetting¶

Request Type: SetSettingRequest
Response Type: SetSettingResponse
Description: Set the specified setting.
The request will be rejected if the setting key does not exists.

SubscribeSettings¶

Request Type: SubscribeSettingsRequest
Response Type: SubscribeSettingsResponse
Description: Upon subscription, the latest setting states will be sent.
For every setting change, a full snapshot of the states will be sent.

Status¶

SubscribeBatteryStatus¶

Request Type: SubscribeBatteryStatusRequest
Response Type: SubscribeBatteryStatusResponse
Description: Subscribe to the robot's battery status.
Upon subscription, the server immediately sends the latest known battery status, followed by updates whenever the battery status changes.

SubscribeOperationStatus¶

Request Type: SubscribeOperationStatusRequest
Response Type: SubscribeOperationStatusResponse
Description: Subscribe to the robots's operation status.
Upon subscription, the server immediately sends the latest known operation status, followed by updates whenever the operation status changes.

System¶

ConnectWifi¶

Request Type: ConnectWifiRequest
Response Type: ConnectWifiResponse
Description: Connect to a specified Wi-Fi network.
SSID should be provided and nearby broadcasted networks may be scanned with ListWifiConnections.

ForgetWifi¶

Request Type: ForgetWifiRequest
Response Type: ForgetWifiResponse
Description: Forget a saved Wi-Fi network.
When called, it forgets a Wi-Fi network identified by its ssid. The call will fail if a network operation is in progress or the network is not found.

GetSystemInfo¶

Request Type: GetSystemInfoRequest
Response Type: GetSystemInfoResponse
Description: Get the overall robot system information.
When called, the server returns robot system information. The system info tends to be static and does not change often.

ListWifiConnections¶

Request Type: ListWifiConnectionsRequest
Response Type: ListWifiConnectionsResponse
Description: List available and remembered network connections.
When called, the server returns lists of remembered Wi-Fi networks, which may not necessarily be available, and returns lists of other available networks.

RunSystemCommand¶

Request Type: RunSystemCommandRequest
Response Type: RunSystemCommandResponse
Description: Execute a system command on the robot.
Runs a system command. e.g. initiate robot reboot. Refer to the SystemCommand proto for all available commands.

SubscribeNetworkStatus¶

Request Type: SubscribeNetworkStatusRequest
Response Type: SubscribeNetworkStatusResponse
Description: Subscribe to the robot's network status.
Upon subscription, the server immediately sends the latest known network status, followed by updates whenever the network status changes.

Message Types¶

AppendMissionRequest¶

Name	Type	Description
`mission`	Mission	The mission to append to the queue.

JSON Request Example¶

JSON

  {
    "mission": {
      "type": "TYPE_ONEOFF",
      "goals": [
        {
          "pose": {
            "xMeters": 2.5,
            "yMeters": 3.0,
            "headingRadians": 1.57
          }
        }
      ]
    }
  }

AppendMissionResponse¶

Name	Type	Description
`mission_id`	string	The unique identifier of the appended mission.

JSON Response Example¶

JSON

  {
    "missionId": "cbd47ab1-df21-479e-9f72-677b81ab55b0"
  }

ChargeRobotRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

ChargeRobotResponse¶

Name	Type	Description
`mission_id`	string	The ID of the mission created.

JSON Response Example¶

JSON

  {
    "missionId": "mission-xyz-001"
  }

ConnectWifiRequest¶

Name	Type	Description
`ssid`	string	SSID of Wi-Fi network.
`authentication`	Authentication	Security details for the network. This field can be omitted if the network is unsecure.
`connection_options`	ConnectionOptions	Optional parameters for static IP configuration.

JSON Request Example¶

JSON

  {
    "ssid": "MyWiFiNetwork",
    "authentication": {
      "password": "mypassword"
    }
  }

ConnectWifiResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

CreateMissionRequest¶

Name	Type	Description
`mission`	Mission	The mission to create.

JSON Request Example¶

JSON

  {
    "mission": {
      "type": "TYPE_ONEOFF",
      "goals": [
        {
          "pose": {
            "xMeters": 2.5,
            "yMeters": 3.0,
            "headingRadians": 1.57
          }
        }
      ]
    }
  }

CreateMissionResponse¶

Name	Type	Description
`mission_id`	string	The ID of the mission created.

JSON Response Example¶

JSON

  {
    "missionId": "cbd47ab1-df21-479e-9f72-677b81ab55b0"
  }

DriveRobotRequest¶

Name	Type	Description
`twist`	Twist	The desired max linear and angular velocity to travel.

JSON Request Example¶

JSON

  {
    "twist": {
      "linearVelocity": 0.5,
      "angularVelocity": 0.2
    }
  }

DriveRobotResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

ForgetWifiRequest¶

Name	Type	Description
`ssid`	string	SSID of the Wi-Fi network to forget.

JSON Request Example¶

JSON

  {
    "ssid": "MyWiFiNetwork"
  }

ForgetWifiResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

GetLocationRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

GetLocationResponse¶

Name	Type	Description
`location`	Location	The current location data to which the robot is connected.

JSON Response Example¶

JSON

  {
    "location": {
      "locationId": "4RVF",
      "displayName": "City Deli & Grill",
      "floors": {
        "0": {
          "displayName": "Ground",
          "sections": [
            {
              "displayName": "Main Floor",
              "mapIds": ["9578"],
              "currentMapId": "9578"
            }
          ]
        }
      }
    }
  }

GetMapContentRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

GetMapContentResponse¶

Name	Type	Description
`map_content`	MapContent	The current map content data loaded on the robot.

JSON Response Example¶

JSON

  {
    "mapContent": {
      "mapId": "9578",
      "data": {
        "data": "<base64_encoded_png_data>",
        "origin": {
          "xM": 0.0,
          "yM": 0.0,
          "yawRadians": 0.0
        },
        "mPerPixel": 0.05
      },
      "annotation": {
        "destinations": []
      }
    }
  }

GetSystemInfoRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

GetSystemInfoResponse¶

Name	Type	Description
`system_info`	SystemInfo	The robot system information.

JSON Response Example¶

JSON

  {
    "systemInfo": {
      "softwareVersion": "servi-24.03",
      "firmwareVersion": "3.2.4.1",
      "robotFamily": "ROBOT_FAMILY_SERVI",
      "robotId": "pennybot-abc123",
      "displayName": "Sir V",
      "localeLanguage": "en-US",
      "wifiInfo": {
        "currentSsid": "MyWiFiNetwork",
        "cidrIp": "192.168.1.123/24",
        "gatewayIp": "192.168.1.1",
        "macAddress": "aa:1a:a1:a1:1a:11",
        "dnsIps": ["8.8.8.8", "8.8.4.4"]
      }
    }
  }

ListWifiConnectionsRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

ListWifiConnectionsResponse¶

Name	Type	Description
`wifi_connections`	WifiConnections	Lists of remembered and available Wi-Fi networks.

JSON Response Example¶

JSON

  {
    "wifiConnections": {
      "savedNetworks": [
        {
          "ssid": "MyWiFiNetwork",
          "signalStrength": 85,
          "security": "SECURITY_PASSWORD_SECURED",
          "connectedState": "CONNECTION_BEAR_CONNECTED"
        }
      ],
      "availableNetworks": [
        {
          "ssid": "OtherNetwork",
          "signalStrength": 60,
          "security": "SECURITY_UNSECURED",
          "connectedState": "CONNECTION_UNKNOWN"
        }
      ]
    }
  }

LocalizeRobotRequest¶

Name	Type	Description
`goal`	LocalizationGoal	The localization goal. The robot must be placed within a 5x5 meter window from the localization goal.

JSON Request Example¶

JSON

  {
    "goal": {
      "pose": {
        "xMeters": 2.5,
        "yMeters": 3.0,
        "headingRadians": 1.57
      }
    }
  }

LocalizeRobotResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

RunSystemCommandRequest¶

Name	Type	Description
`system_command`	SystemCommand	The system command to execute.

JSON Request Example¶

JSON

  {
    "systemCommand": {
      "reboot": {}
    }
  }

RunSystemCommandResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

SetEmergencyStopRequest¶

Name	Type	Description
`e_stop_state`	EmergencyStopState	The emergency stop state to set.

JSON Request Example¶

JSON

  {
    "eStopState": {
      "emergency": "EMERGENCY_ENGAGED"
    }
  }

SetEmergencyStopResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

SetPoseRequest¶

Name	Type	Description
`pose_with_covariance`	PoseWithCovariance	A pose and a covariance matrix, if the covariance is not set, the internal default values will be applied.

JSON Request Example¶

JSON

  {
    "poseWithCovariance": {
      "pose": {
        "xMeters": 2.5,
        "yMeters": 3.0,
        "headingRadians": 1.57
      },
      "covariance": []
    }
  }

SetPoseResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

SetSettingRequest¶

Name	Type	Description
`setting`	Setting	The setting to set.

JSON Request Example¶

JSON

  {
    "setting": {
      "key": "robot-max-vel-x",
      "value": "0.8"
    }
  }

SetSettingResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

SubscribeBatteryStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeBatteryStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`battery_state`	BatteryState	The current battery state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "batteryState": {
      "chargePercent": 85,
      "state": "STATE_CHARGING",
      "chargeMethod": "CHARGE_METHOD_WIRELESS"
    }
  }

SubscribeEmergencyStopStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeEmergencyStopStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`e_stop_state`	EmergencyStopState	The current emergency stop state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "eStopState": {
      "emergency": "EMERGENCY_DISENGAGED"
    }
  }

SubscribeLocalizationStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeLocalizationStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`localization_state`	LocalizationState	The current localization state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "localizationState": {
      "state": "STATE_LOCALIZING"
    }
  }

SubscribeMissionStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeMissionStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`mission_state`	MissionState	The current mission state of the robot.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "missionState": {
      "missionId": "d6637a14-5f6b-43f6-bd86-cc1871a8322e",
      "state": "STATE_RUNNING",
      "goals": [
        {
          "pose": {
            "xMeters": 4.2,
            "yMeters": 7.8,
            "headingRadians": 1.57
          }
        }
      ],
      "currentGoalIndex": 1,
      "navigationStatus": "NAVIGATION_STATUS_NAVIGATING"
    }
  }

SubscribeNetworkStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeNetworkStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`network_state`	NetworkState	The current network state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "networkState": {
      "connectedWifi": {
        "ssid": "MyWiFiNetwork",
        "signalStrength": 85,
        "security": "SECURITY_PASSWORD_SECURED",
        "connectedState": "CONNECTION_BEAR_CONNECTED"
      }
    }
  }

SubscribeOdometryStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeOdometryStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`odometry_state`	OdometryState	The current odometry state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "odometryState": {
      "pose": {
        "xMeters": 2.5,
        "yMeters": 3.0,
        "headingRadians": 1.57
      },
      "twist": {
        "linearVelocity": 0.5,
        "angularVelocity": 0.2
      }
    }
  }

SubscribeOperationStatusRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeOperationStatusResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`operation_state`	OperationState	The current operation state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "operationState": {
      "system": "SYSTEM_OK",
      "systemMessage": "",
      "emergency": "EMERGENCY_DISENGAGED",
      "emergencyMessage": "",
      "charging": "CHARGING_DISCHARGING",
      "mission": "MISSION_IDLE"
    }
  }

SubscribeRobotPoseRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeRobotPoseResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`pose`	Pose	The current robot pose.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "pose": {
      "xMeters": 2.5,
      "yMeters": 3.0,
      "headingRadians": 1.57
    }
  }

SubscribeSettingsRequest¶

(No fields defined)

JSON Request Example¶

JSON

{}

SubscribeSettingsResponse¶

Name	Type	Description
`metadata`	EventMetadata	Event metadata including timestamp and sequence number.
`settings_state`	SettingsState	The current settings state.

JSON Response Example¶

JSON

  {
    "metadata": {
      "timestamp": "2025-04-01T15:30:00Z",
      "sequenceNumber": 128
    },
    "settingsState": {
      "settings": {
        "robot-max-vel-x": "0.8",
        "robot-enable-motors-coast-in-idle": "True"
      }
    }
  }

SwitchMapRequest¶

Name	Type	Description
`floor_level`	int32	The floor level to switch to.
`section_index`	int32	The section index to switch to.

JSON Request Example¶

JSON

  {
    "floorLevel": 0,
    "sectionIndex": 0
  }

SwitchMapResponse¶

Name	Type	Description
`map_id`	string	The ID of the switched map.

JSON Response Example¶

JSON

  {
    "mapId": "9578"
  }

UpdateMissionRequest¶

Name	Type	Description
`mission_command`	MissionCommand	Command to update the state of an active mission.

JSON Request Example¶

JSON

  {
    "missionCommand": {
      "missionId": "f842c8ac-62de-412e-90fb-bf37022db2f4",
      "command": "COMMAND_PAUSE"
    }
  }

UpdateMissionResponse¶

(No fields defined)

JSON Response Example¶

JSON

{}

Robot API Service¶

Map¶

GetLocation¶

GetMapContent¶

SwitchMap¶

Mission¶

AppendMission¶

ChargeRobot¶

CreateMission¶

SubscribeMissionStatus¶

UpdateMission¶

Navigation¶

DriveRobot¶

LocalizeRobot¶

SetEmergencyStop¶

SetPose¶

SubscribeEmergencyStopStatus¶

SubscribeLocalizationStatus¶

SubscribeOdometryStatus¶

SubscribeRobotPose¶

Settings¶

SetSetting¶

SubscribeSettings¶

Status¶

SubscribeBatteryStatus¶

SubscribeOperationStatus¶

System¶

ConnectWifi¶

ForgetWifi¶

GetSystemInfo¶

ListWifiConnections¶

RunSystemCommand¶

SubscribeNetworkStatus¶

Message Types¶

AppendMissionRequest¶

JSON Request Example¶

AppendMissionResponse¶

JSON Response Example¶

ChargeRobotRequest¶

JSON Request Example¶

ChargeRobotResponse¶

JSON Response Example¶

ConnectWifiRequest¶

JSON Request Example¶

ConnectWifiResponse¶

JSON Response Example¶

CreateMissionRequest¶

JSON Request Example¶

CreateMissionResponse¶

JSON Response Example¶

DriveRobotRequest¶

JSON Request Example¶

DriveRobotResponse¶

JSON Response Example¶

ForgetWifiRequest¶

JSON Request Example¶

ForgetWifiResponse¶

JSON Response Example¶

GetLocationRequest¶

JSON Request Example¶

GetLocationResponse¶

JSON Response Example¶

GetMapContentRequest¶

JSON Request Example¶

GetMapContentResponse¶

JSON Response Example¶

GetSystemInfoRequest¶

JSON Request Example¶

GetSystemInfoResponse¶

JSON Response Example¶

ListWifiConnectionsRequest¶

JSON Request Example¶

ListWifiConnectionsResponse¶

JSON Response Example¶

LocalizeRobotRequest¶

JSON Request Example¶

LocalizeRobotResponse¶

JSON Response Example¶

RunSystemCommandRequest¶

JSON Request Example¶