Skip to content

Localization & Navigation

Provides controls and subscriptions related to a robot’s position within its environment, including localization and pose tracking.

LocalizeRobot

Localizes the robot to a known pose or destination.

If the request is accepted, subscribe to SubscribeLocalizationStatus to track localization progress.

Request

robot_id string required

The ID of the robot that the localization command is sent to.

goal Goal required

Goal represents a target destination or pose for the robot to localize to.

Field Message Type Description
destination_id string Unique identifier for the destination.
Pose Pose x_meters float X-coordinate in meters within the map.
x_meters float Y-coordinate in meters within the map.
heading_radians float The heading of the robot in radians. Ranges from -π to π, where 0.0 points along the positive x-axis.
JSON Request Example
  {
    "robotId": "pennybot-123123",
    "goal": {
      "pose": {
        "xMeters": 1.5,
        "yMeters": 2.8,
        "headingRadians": -0.52
      }
    }
  }

Response

(No fields defined)

JSON Response Example
  {}

Errors

ErrorCode Description
FAILED_PRECONDITION While the robot is localizing, any subsequent requests
to localize the robot will return a error until the process is completed.

SubscribeEmergencyStopStatus

A server side streaming RPC endpoint to Subscribe to the software emergency stop state. Upon subscription, the latest emergency stop state is sent immediately. State updates are streamed whenever the emergency stop state changes.

Request

robot_id string required

The ID of the robot that emergency stop subscription request is sent to.

JSON Request Example
  {
    "robotId": "pennybot-123123"
  }

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.
e_stop_state EmergencyStopState enum
Name Number Description
EMERGENCY_UNKNOWN 0 Default value. It means the state 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
{
  "metadata": {
    "timestamp": "2025-04-01T17:30:00Z",
    "sequence_number": 42
  },
  "e_stop_state": {
    "emergency": "EMERGENCY_ENGAGED"
  }
}

Errors

ErrorCode Description
PERMISSION_DENIED Attempting to request status for robot_id you don't own.
Tips: check the spelling of the robot_id.

SubscribeLocalizationStatus

A server side streaming RPC endpoint to get the robot’s localization state. Upon subscription, the latest localization state is sent immediately. State updates are streamed while localization is active.

Request

robot_id string required

The ID of the robot that subscription request is sent to.

JSON Request Example
  {
    "robotId": "pennybot-123123"
  }

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.
LocalizationState enum
Name Number Description
STATE_UNKNOWN 0 Default value. It means the state field is not returned.
STATE_FAILED 1 Localization failed.
STATE_SUCCEEDED 2 Localization completed successfully.
STATE_LOCALIZING 3 The robot is actively attempting to localize.
JSON Response Example
{
  "metadata": {
    "timestamp": "2025-04-01T17:30:00Z",
    "sequenceNumber": 98
  },
  "localizationState": {
    "state": "STATE_LOCALIZING"
  }
}

Errors

ErrorCode Description
PERMISSION_DENIED Attempting to request status for a robot_id you don't own.
Tips: check the spelling of all robot_id values.

SubscribeRobotPose

A server side streaming RPC endpoint to subscribe to the robot's pose estimates at a regular frequency. (~10Hz) Use this to track the robot's position in real time.

Request

selector RobotSelector required

RobotSelector is used to select specific robots.
It supports selection by a list of robot IDs OR all robots at a given location.

Field Message Type Description
robot_ids RobotIDs Selects robots by their specific IDs.
Example: ["pennybot-123abc", "pennybot-abc123"]
location_id string Selects all robots at the specified location.
JSON Request Example
  {
    "selector": {
      "robot_ids": {
        "ids": ["pennybot-abc123", "pennybot-123abc"]
      }
    }
  }

Response

PoseWithMetadata
Field Message Type Description
metadata EventMetadata Metadata associated with the event.
pose Pose Pose of the robot on the map.
Pose
Field Message Type Description
x_meters float X-coordinate in meters within the map.
y_meters float Y-coordinate in meters within the map.
heading_radians float The heading of the robot in radians.
Ranges from -π to π, where 0.0 points along the positive x-axis.
JSON Response Example
{
  "poses": {
    "pennybot-abc123": {
      "metadata": {
        "timestamp": "2025-04-01T17:45:00Z",
        "sequenceNumber": 201
      },
      "pose": {
        "xMeters": 1.5,
        "yMeters": 3.2,
        "headingRadians": 0.78
      }
    },
    "pennybot-123abc": {
      "metadata": {
        "timestamp": "2025-04-01T17:45:02Z",
        "sequenceNumber": 202
      },
      "pose": {
        "xMeters": 0.0,
        "yMeters": 0.0,
        "headingRadians": -3.14
      }
    }
  }
}

Errors

ErrorCode Description
PERMISSION_DENIED Attempting to request status for a robot_id or location_id you don't own.
Tip: check the spelling of all robot_id or location_id values.