auth.proto

GetAuthTokenRequest

The GetAuthToken request message includes login information for the robot.

Field Type Description
header RequestHeader Common request header.
username string Username to authenticate with. Must be set if password is set.
password string Password to authenticate with. Not neccessary if token is set.
token string Token to authenticate with. Can be used in place of the password, to re-mint a token.
application_token string Deprecated as of 2.0.1. Application Token for authenticating with robots on older releases.

GetAuthTokenResponse

The GetAuthToken response message includes an authentication token if the login information is correct and succeeds.

Field Type Description
header ResponseHeader
status GetAuthTokenResponse.Status The status of the grpc GetAuthToken request.
token string Token data. Only specified if status == STATUS_OK.

GetAuthTokenResponse.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happend.
STATUS_OK 1 STATUS_OK indicates that authentication has succeeded. The 'token' field field will be populated with a session token that can be used to authenticate the user.
STATUS_INVALID_LOGIN 2 STATUS_INVALID_LOGIN indicates that authentication has failed since an invalid username and/or password were provided.
STATUS_INVALID_TOKEN 3 STATUS_INVALID_TOKEN indicates that authentication has failed since the 'token' provided in the request is invalid. Reasons for the token being invalid could be because it has expired, because it is improperly formed, for the wrong robot, the user that the token is for has changed a password, or many other reasons. Clients should use username/password-based authentication when refreshing the token fails.
STATUS_TEMPORARILY_LOCKED_OUT 4 STATUS_TEMPORARILY_LOCKED_OUT indicates that authentication has failed since authentication for the user is temporarily locked out due to too many unsuccessful attempts. Any new authentication attempts should be delayed so they may happen after the lock out period ends.
STATUS_INVALID_APPLICATION_TOKEN 5 STATUS_INVALID_APPLICATION_TOKEN indicates that the 'application_token' field in the request was invalid.
STATUS_EXPIRED_APPLICATION_TOKEN 6 STATUS_EXPIRED_APPLICATION_TOKEN indicates that the 'application_token' field in the request was valid, but has expired.

auth_service.proto

AuthService

The AuthService provides clients the ability to convert a user/password pair into a token. The token can then be added to the http2 headers for future requests in order to establish the identity of the requester.

Method Name Request Type Response Type Description
GetAuthToken GetAuthTokenRequest GetAuthTokenResponse Request to get the auth token for the robot.

basic_command.proto

FreezeCommand

Freeze all joints at their current positions (no balancing control).

FreezeCommand.Feedback

Freeze command provides no feedback.

FreezeCommand.Request

Freeze command request takes no additional arguments.

SE2TrajectoryCommand

Move along a trajectory in 2D space.

SE2TrajectoryCommand.Feedback

The SE2TrajectoryCommand will provide feedback on whether or not the robot has reached the final point of the trajectory.

Field Type Description
status SE2TrajectoryCommand.Feedback.Status Current status of the command.

SE2TrajectoryCommand.Request

Field Type Description
end_time google.protobuf.Timestamp The timestamp (in robot time) by which a command must finish executing. This is a required field and used to prevent runaway commands.
se2_frame_name string The name of the frame that trajectory is relative to. The trajectory must be expressed in a gravity aligned frame, so either "vision", "odom", or "flat_body". Any other provided se2_frame_name will be rejected and the trajectory command will not be exectuted.
trajectory SE2Trajectory The trajectory that the robot should follow, expressed in the frame identified by se2_frame_name.

SE2VelocityCommand

Move the robot at a specific SE2 velocity for a fixed amount of time.

SE2VelocityCommand.Feedback

Planar velocity commands provide no feedback.

SE2VelocityCommand.Request

Field Type Description
end_time google.protobuf.Timestamp The timestamp (in robot time) by which a command must finish executing. This is a required field and used to prevent runaway commands.
se2_frame_name string The name of the frame that velocity and slew_rate_limit are relative to. The trajectory must be expressed in a gravity aligned frame, so either "vision", "odom", or "flat_body". Any other provided se2_frame_name will be rejected and the velocity command will not be executed.
velocity SE2Velocity Desired planar velocity of the robot body relative to se2_frame_name.
slew_rate_limit SE2Velocity If set, limits how quickly velocity can change relative to se2_frame_name. Otherwise, robot may decide to limit velocities using default settings. These values should be non-negative.

SafePowerOffCommand

Get robot into a position where it is safe to power down, then power down. If the robot has fallen, it will power down directly. If the robot is not in a safe position, it will get to a safe position before powering down. The robot will not power down until it is in a safe state.

SafePowerOffCommand.Feedback

The SafePowerOff will provide feedback on whether or not it has succeeded in powering off the robot yet.

Field Type Description
status SafePowerOffCommand.Feedback.Status Current status of the command.

SafePowerOffCommand.Request

SafePowerOff command request takes no additional arguments.

SelfRightCommand

Move the robot into a “ready” position from which it can sit or stand up.

SelfRightCommand.Feedback

SelfRight command request provides no feedback.

SelfRightCommand.Request

SelfRight command request takes no additional arguments.

SitCommand

Sit the robot down in its current position.

SitCommand.Feedback

Field Type Description
status SitCommand.Feedback.Status Current status of the command.

SitCommand.Request

Sit command request takes no additional arguments.

StandCommand

The stand the robot up in its current position.

StandCommand.Feedback

The StandCommand will provide feedback on whether or not the robot has finished standing up.

Field Type Description
status StandCommand.Feedback.Status Current status of the command.

StandCommand.Request

Stand command request takes no additional arguments.

StopCommand

Stop the robot in place with minimal motion.

StopCommand.Feedback

Stop command provides no feedback.

StopCommand.Request

Stop command request takes no additional arguments.

SE2TrajectoryCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_AT_GOAL 1 The robot has arrived at the goal.
STATUS_GOING_TO_GOAL 2 The robot is attempting to go to a goal.

SafePowerOffCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_POWERED_OFF 1 Robot has powered off.
STATUS_IN_PROGRESS 2 Robot is trying to safely power off.

SitCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_IS_SITTING 1 Robot is currently sitting.
STATUS_IN_PROGRESS 2 Robot is trying to sit.

StandCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_IS_STANDING 1 Robot has finished standing up and has completed desired body trajectory. Robot is not attempting to move.
STATUS_IN_PROGRESS 2 Robot is trying to come to a steady stand.

data_chunk.proto

DataChunk

Represents a chunk of (possibly serialized) data. Chunks will be concatenated together to produce a datagram. This is to avoid size limit restrictions in grpc implementations.

Field Type Description
total_size uint64 The total size in bytes of the datagram that this chunk is a part of.
data bytes Bytes in this data chunk. Bytes are sent sequentially.

directory.proto

Endpoint

A message containing information that allows a client to identify a given endpoint host using an ip and a port.

Field Type Description
host_ip string The IP address of the computer hosting this endpoint.
port int32 The port number on which the endpoint is provided.

GetServiceEntryRequest

The GetServiceEntry request message sends the service name to the robot.

Field Type Description
header RequestHeader Common request header.
service_name string The unique user-friendly name of the service.

GetServiceEntryResponse

The GetServiceEntry response message returns a ServiceEntry for the desired service name.

Field Type Description
header ResponseHeader Common response Header.
status GetServiceEntryResponse.Status Current status of the request.
service_entry ServiceEntry The record for the discovered service. Only set if 'status' field == STATUS_OK.

ListServiceEntriesRequest

The ListServiceEntries request message will ask the robot for all services.

Field Type Description
header RequestHeader Common request header.

ListServiceEntriesResponse

The ListServiceEntries response message returns all known services at the time the request was recieved.

Field Type Description
header ResponseHeader Common response header.
service_entries ServiceEntry The resources managed by the LeaseService.

ServiceEntry

A message representing a discoverable service. By definition, all services discoverable by this system are expected to be grpc “services” provided by some server.

Field Type Description
name string The unique user-friendly name of this service.
type string The type of this service. Usually identifies the underlying implementation. Does not have to be unique among all ServiceEntry objects.
authority string Information used to route to the desired Service. Can either be a full address (aService.spot.robot) or just a DNS label that will be automatically converted to an address (aService).
last_update google.protobuf.Timestamp Last update time in robot timebase for this service record.
user_token_required bool If 'user_token_required' field is true, any requests to this service must contain a user token for the machine. Requests without a user token will result in a 401. Most services will want to require a user_token, but ones like auth_service do not.
permission_required string If 'permission_required' field is non-empty, any requests to this service must have the same string in the "per" claim of the user token.

GetServiceEntryResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal DirectoryService issue has happened if UNKNOWN is set.
STATUS_OK 1 GetService was successful. The service_entry field is filled out.
STATUS_NONEXISTENT_SERVICE 2 GetService failed because the requested service name does not exist.

directory_registration.proto

RegisterServiceRequest

The RegisterService request message sends the service’s entry and endpoint to the robot’s directory.

Field Type Description
header RequestHeader Common request header.
endpoint Endpoint The endpoint at which this service may be contacted.
service_entry ServiceEntry The service to create. The name must not match any existing service.

RegisterServiceResponse

The RegisterService response message has information of whether the service was registered correctly.

Field Type Description
header ResponseHeader Common response Header.
status RegisterServiceResponse.Status Return status for the request.

UnregisterServiceRequest

The UnregisterService request message will unregister a service based on name.

Field Type Description
header RequestHeader Common request header.
service_name string The unique user-friendly name of the service.

UnregisterServiceResponse

The UnregisterService response message has information of whether the service was unregistered.

Field Type Description
header ResponseHeader Common response Header.
status UnregisterServiceResponse.Status Return status for the request.

UpdateServiceRequest

The UpdateService request message will update a service based on name to include the new endpoint and service entry.

Field Type Description
header RequestHeader Common request header.
endpoint Endpoint The endpoint at which this service may be contacted.
service_entry ServiceEntry New record for service. The name field is used as lookup key.

UpdateServiceResponse

The UpdateService response message has information of whether the service was updated on robot.

Field Type Description
header ResponseHeader Common response Header.
status UpdateServiceResponse.Status Return status for the request.

RegisterServiceResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal DirectoryRegistrationService issue has happened if UNKNOWN is set.
STATUS_OK 1 Success. The new service record is available.
STATUS_ALREADY_EXISTS 2 RegisterService failed because a service with this name already exists.

UnregisterServiceResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal DirectoryRegistrationService issue has happened if UNKNOWN is set.
STATUS_OK 1 Success. The service record was deleted.
STATUS_NONEXISTENT_SERVICE 2 The provided service name was not found.

UpdateServiceResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal DirectoryRegistrationService issue has happened if UNKNOWN is set.
STATUS_OK 1 Success. The new service record is available.
STATUS_NONEXISTENT_SERVICE 2 The provided service name was not found.

directory_registration_service.proto

DirectoryRegistrationService

DirectoryRegistrationService is a private class that lets services be discovered by clients by adding them to a discovery database. Services can live on robot, payload, or other accessible cloud-based locations. Each service is responsible for registering itself with this service.

Method Name Request Type Response Type Description
RegisterService RegisterServiceRequest RegisterServiceResponse Called by a producer to register as a provider with the application. Returns the record for that provider. Requires unique name and correctly filled out service record in request.
UnregisterService UnregisterServiceRequest UnregisterServiceResponse Called by a producer to remove its registration from the DirectoryManager.
UpdateService UpdateServiceRequest UpdateServiceResponse Update the ServiceEntry for a producer on the server.

directory_service.proto

DirectoryService

DirectoryService lets clients discover which API services are available on a robot.

Method Name Request Type Response Type Description
GetServiceEntry GetServiceEntryRequest GetServiceEntryResponse Get information about a specific service.
ListServiceEntries ListServiceEntriesRequest ListServiceEntriesResponse List all known services at time of call.

estop.proto

DeregisterEstopEndpointRequest

Deregister the specified E-Stop endpoint registration.

Field Type Description
header RequestHeader Common request header
target_endpoint EstopEndpoint The endpoint to deregister.
target_config_id string ID of the configuration we are registering against.

DeregisterEstopEndpointResponse

Response to E-Stop endpoint deregistration request.

Field Type Description
header ResponseHeader Common resonse header.
request DeregisterEstopEndpointRequest Copy of the initial request.
status DeregisterEstopEndpointResponse.Status Status code for the response.

EstopCheckInRequest

Client request for setting/maintaining an E-Stop system level. After the first CheckIn, must include response to previous challenge.

Field Type Description
header RequestHeader Common request header.
endpoint EstopEndpoint The endpoint making the request.
challenge uint64 Challenge being responded to. Don't set if this is the first EstopCheckInRequest.
response uint64 Response to above challenge. Don't set if this is the first EstopCheckInRequest.
stop_level EstopStopLevel Assert this stop level.

EstopCheckInResponse

Server response to EstopCheckInRequest.

Field Type Description
header ResponseHeader Common response header.
request EstopCheckInRequest Copy of initial request.
challenge uint64 Next challenge to answer.
status EstopCheckInResponse.Status Status code for the response.

EstopConfig

Configuration of a root / server.

Field Type Description
endpoints EstopEndpoint EstopEndpoints that are part of this configuration. Unique IDs do not have to be filled out, but can be.
unique_id string Unique ID for this configuration.

EstopEndpoint

An to the robot software-E-Stop system.

Field Type Description
role string Role of this endpoint. Should be a user-friendly string, e.g. "OCU".
name string Name of this endpoint. Specifies a thing to fill the given role, e.g. "patrol-ocu01"
unique_id string Unique ID assigned by the server.
timeout google.protobuf.Duration Maximum delay between challenge and response for this endpoint prior to soft power off handling. After timeout seconds has passed, the robot will try to get to a safe state prior to disabling motor power. The robot response is equivalent to an ESTOP_LEVEL_SETTLE_THEN_CUT which may involve the robot sitting down in order to prepare for disabling motor power.
cut_power_timeout google.protobuf.Duration Optional maximum delay between challenge and response for this endpoint prior to disabling motor power. After cut_power_timeout seconds has passed, motor power will be disconnected immediately regardless of current robot state. If this value is not set robot will default to timeout plus a nominal expected duration to reach a safe state. In practice this is typically 3-4 seconds. The response is equivalent to an ESTOP_LEVEL_CUT.

EstopEndpointWithStatus

EstopEndpoint with some extra status data.

Field Type Description
endpoint EstopEndpoint The endpoint.
stop_level EstopStopLevel Stop level most recently requested by the endpoint.
time_since_valid_response google.protobuf.Duration Time since a valid response was provided by the endpoint.

EstopSystemStatus

Status of Estop system.

Field Type Description
endpoints EstopEndpointWithStatus Status for all available endpoints.
stop_level EstopStopLevel Current stop level for the system. Will be the most-restrictive stop level specified by an endpoint, or a stop level asserted by the system as a whole (e.g. if an endpoint timed out).
stop_level_details string Human-readable information on the stop level.

GetEstopConfigRequest

Get the active EstopConfig.

Field Type Description
header RequestHeader Common request header.
target_config_id string The 'unique_id' of EstopConfig to get.

GetEstopConfigResponse

Response to EstopConfigRequest.

Field Type Description
header ResponseHeader Common response header.
request GetEstopConfigRequest Copy of the request.
active_config EstopConfig The currently active configuration.

GetEstopSystemStatusRequest

Ask for the current status of the Estop system.

Field Type Description
header RequestHeader Common request header.

GetEstopSystemStatusResponse

Respond with the current Estop system status.

Field Type Description
header ResponseHeader Common response header.
status EstopSystemStatus Status of the Estop system.

RegisterEstopEndpointRequest

Register an endpoint. EstopEndpoints must be registered before they can send commands or request challenges.

Field Type Description
header RequestHeader Common request header
target_endpoint EstopEndpoint The endpoint to replace. Set the endpoint's unique ID if replacing an active endpoint.
target_config_id string ID of the configuration we are registering against.
new_endpoint EstopEndpoint The description of the new endpoint. Do not set the unique ID. It will be ignored.

RegisterEstopEndpointResponse

Response to registration request.

Field Type Description
header ResponseHeader Common response header
request RegisterEstopEndpointRequest Copy of the initial request.
new_endpoint EstopEndpoint The resulting endpoint on success.
status RegisterEstopEndpointResponse.Status Status code for the response.

SetEstopConfigRequest

Set a new active EstopConfig.

Field Type Description
header RequestHeader Common request header.
config EstopConfig New configuration to set.
target_config_id string The 'unique_id' of EstopConfig to replace, if replacing one.

SetEstopConfigResponse

Response to EstopConfigRequest.

Field Type Description
header ResponseHeader Common response header.
request SetEstopConfigRequest Copy of the request.
active_config EstopConfig The currently active configuration.
status SetEstopConfigResponse.Status

DeregisterEstopEndpointResponse.Status

Name Number Description
STATUS_UNKNOWN 0 An unknown / unexpected error occurred.
STATUS_SUCCESS 1 Request succeeded.
STATUS_ENDPOINT_MISMATCH 2 Target endpoint did not match.
STATUS_CONFIG_MISMATCH 3 Registered to wrong configuration.

EstopCheckInResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Unknown error occurred.
STATUS_OK 1 Valid challenge has been returned.
STATUS_ENDPOINT_UNKNOWN 2 The endpoint specified in the request is not registered.
STATUS_INCORRECT_CHALLENGE_RESPONSE 5 The challenge and/or response was incorrect.

EstopStopLevel

The state of the E-Stop system.

Name Number Description
ESTOP_LEVEL_UNKNOWN 0 Invalid stop level.
ESTOP_LEVEL_CUT 1 Immediately cut power to the actuators.
ESTOP_LEVEL_SETTLE_THEN_CUT 2 Prepare for loss of actuator power, then cut power.
ESTOP_LEVEL_NONE 4 No-stop level. The endpoint believes the robot is safe to operate.

RegisterEstopEndpointResponse.Status

Name Number Description
STATUS_UNKNOWN 0 An unknown / unexpected error occurred.
STATUS_SUCCESS 1 Request succeeded.
STATUS_ENDPOINT_MISMATCH 2 Target endpoint did not match.
STATUS_CONFIG_MISMATCH 3 Registered to wrong configuration.
STATUS_INVALID_ENDPOINT 4 New endpoint was invalid.

SetEstopConfigResponse.Status

Name Number Description
STATUS_UNKNOWN 0 An unknown / unexpected error occurred.
STATUS_SUCCESS 1 Request succeeded.
STATUS_INVALID_ID 2 Tried to replace a EstopConfig, but provided bad ID.

estop_service.proto

EstopService

The software robot E-Stop system:

  1. Uses challenge-style communication to enforce end user (aka “originators”) connection for Authority to Operate (ATO).

  2. Offers the ability to issue a direct denial of ATO. The EstopService provides a service interface for the robot EStop/Authority to operate the system.

Method Name Request Type Response Type Description
RegisterEstopEndpoint RegisterEstopEndpointRequest RegisterEstopEndpointResponse Register an Estop "originator" or "endpoint". This may be a replacement for another active endpoint.
DeregisterEstopEndpoint DeregisterEstopEndpointRequest DeregisterEstopEndpointResponse Deregister the requested estop endpoint.
EstopCheckIn EstopCheckInRequest EstopCheckInResponse Answer challenge from previous response (unless this is the first call), and request a stop level.
GetEstopConfig GetEstopConfigRequest GetEstopConfigResponse Request the current EstopConfig, describing the expected set of endpoints.
SetEstopConfig SetEstopConfigRequest SetEstopConfigResponse Set a new active EstopConfig.
GetEstopSystemStatus GetEstopSystemStatusRequest GetEstopSystemStatusResponse Ask for the current status of the estop system.

full_body_command.proto

FullBodyCommand

The robot command message to specify a basic command that requires full control of the entire robot to be completed.

FullBodyCommand.Feedback

The feedback for the fully body command that will provide information on the progress of the robot command.

Field Type Description
stop_feedback StopCommand.Feedback Feedback for the stop command request.
freeze_feedback FreezeCommand.Feedback Feedback for the freeze command request.
selfright_feedback SelfRightCommand.Feedback Feedback for the self-right command request.
safe_power_off_feedback SafePowerOffCommand.Feedback Feedback for the safe power off command request.

FullBodyCommand.Request

The full body request must be one of the basic command primitives.

Field Type Description
stop_request StopCommand.Request Command to stop the robot.
freeze_request FreezeCommand.Request Command to freeze all joints of the robot.
selfright_request SelfRightCommand.Request Command to self-right the robot to a ready position.
safe_power_off_request SafePowerOffCommand.Request Command to safely power off the robot.
params google.protobuf.Any Robot specific command parameters.

geometry.proto

Area

Represents an area in the XY plane.

Field Type Description
polygon Polygon
circle Circle

Box2

Geometric primitive describing a two-dimensional box.

Field Type Description
size Vec2

Box2WithFrame

Geometric primitive to describe a 2D box in a specific frame.

Field Type Description
box Box2 The box is specified with width (y) and length (x), and the full box is fixed at an origin, where it's sides are along the coordinate frame's axes.
frame_name string The pose of the axis-aligned box is in 'frame_name'.
frame_name_tform_box SE3Pose The transformation of the axis-aligned box into the desired frame (specified above).

Box3

Geometric primitive describing a three-dimensional box.

Field Type Description
size Vec3

Box3WithFrame

Geometric primitive to describe a 3D box in a specific frame.

Field Type Description
box Box3 The box width (y), length (x), and height (z) are interpreted in, and the full box is fixed at an origin, where it's sides are along the coordinate frame's axes.
frame_name string The pose of the axis-aligned box is in 'frame_name'.
frame_name_tform_box SE3Pose The transformation of the axis-aligned box into the desired frame (specified above).

Circle

Represents a circular 2D area.

Field Type Description
center_pt Vec2
radius double Dimensions in m from center_pt.

CylindricalCoordinate

Cylindrical coordinates are a generalization of polar coordiates, adding a height axis. See (http://mathworld.wolfram.com/CylindricalCoordinates.html) for more details.

Field Type Description
r double Radial coordinate
theta double Azimuthal coordinate
z double Vertical coordiante

EulerZXYRate

Time derivative of Yaw-Roll-Pitch Euler angle, expressed in radians per second.

Field Type Description
yaw double
roll double
pitch double

FrameTreeSnapshot

A frame is a named location in space. For example, the following frames are defined by the API:

  • “body”: A frame centered on the robot’s body.

  • “vision”: A non-moving (inertial) frame that is the robot’s best estimate of a fixed location in the world. It is based on both dead reckoning and visual analysis of the world.

  • “odom”: A non-moving (inertial) frame that is based on the kinematic odometry of the robot only. Additional frames are available for robot joints, sensors, and items detected in the world.

The FrameTreeSnapshot represents the relationships between the frames that the robot knows about at a particular point in time. For example, with the FrameTreeSnapshot, an API client can determine where the “body” is relative to the “vision”.

To reduce data bandwidth, the FrameTreeSnapshot will typically contain a small subset of all known frames. By default, all services MUST include “vision”, “body”, and “odom” frames in the FrameTreeSnapshot, but additional frames can also be included. For example, an Image service would likely include the frame located at the base of the camera lens where the picture was taken.

Frame relationships are expressed as edges between “parent” frames and “child” frames, with an SE3Pose indicating the pose of the “child” frame expressed in the “child” frame. These edges are included in the edge_map field. For example, if frame “hand” is 1m in front of the frame “shoulder”, then the FrameTreeSnapshot might contain: edge_map { key: “hand” value: { parent_frame_name: “shoulder” parent_tform_child: { position: { x: 1.0 y: 0.0 z: 0.0 } } } }

Frame relationships can be inverted. So, to find where the “shoulder” is in relationship the “hand”, the parent_tform_child pose in the edge above can be inverted: hand_tform_shoulder = shoulder_tform_hand.inverse() Frame relationships can also be concatenated. If there is an additional edge specifying the pose of the “shoulder” relative to the “body”, then to find where the “hand” is relative to the “body” do: body_tform_hand = body_tform_shoulder * shoulder_tform_hand

The two properties above reduce data size. Instead of having to send N^2 edge_map entries to represent all relationships between N frames, only N edge_map entries need to be sent. Clients will need to determine the chain of edges to follow to get from one frame to another frame, and then do inversion and concatentation to generate the appropriate pose.

Note that all FrameTreeSnapshots are expected to be a single rooted tree. The syntax for FrameTreeSnapshot could also support graphs with cycles, or forests of trees - but clients should treat those as invalid representations.

Field Type Description
child_to_parent_edge_map FrameTreeSnapshot.ChildToParentEdgeMapEntry child_to_parent_edge_map maps the child frame name to the ParentEdge. In aggregate, this forms the tree structure.

FrameTreeSnapshot.ChildToParentEdgeMapEntry

Field Type Description
key string
value FrameTreeSnapshot.ParentEdge

FrameTreeSnapshot.ParentEdge

ParentEdge represents the relationship from a child frame to a parent frame.

Field Type Description
parent_frame_name string The name of the parent frame. Must be non-empty. If parent_frame_name is not a key in edge_map, it is the root of the tree.
parent_tform_child SE3Pose Transform representing the pose of the child frame in the parent's frame.

Plane

Plane primitive, described with a point and normal.

Field Type Description
point Vec3 A point on the plane.
normal Vec3 The direction of the planes normal.

PolyLine

Multi-part, 1D line segments defined by a series of points.

Field Type Description
points Vec2

Polygon

Polygon in the XY plane. May be concave, but should not self-intersect. Vertices can be specified in either clockwise or counterclockwise orders.

Field Type Description
vertexes Vec2

Quaternion

Quaternion primitive. A quaternion can be used to describe the rotation.

Field Type Description
x double
y double
z double
w double

SE2Pose

Geometric primitive to describe 2D position and rotation.

Field Type Description
position Vec2 (m)
angle double (rad)

SE2Velocity

Geometric primitive that describes a 2D velocity through it’s linear and angular components.

Field Type Description
linear Vec2 (m/s)
angular double (rad/s)

SE2VelocityLimit

Geometric primitive to couple minimum and maximum SE2Velocities in a single message.

Field Type Description
max_vel SE2Velocity If set, limits the maximum velocity.
min_vel SE2Velocity If set, limits the minimum velocity.

SE3Covariance

Represents the translation/rotation covariance of an SE3 Pose.

Field Type Description
cov_xx double 3x3 translation covariance. They have to be stored this way instead of having a repeated number of floats because otherwise MergeFrom would produce the wrong result.
cov_xy double
cov_xz double
cov_yx double
cov_yy double
cov_yz double
cov_zx double
cov_zy double
cov_zz double
yaw_variance double Variance of the yaw component of the SE3 Pose.

SE3Pose

Geometric primitive to describe 3D position and rotation.

Field Type Description
position Vec3 (m)
rotation Quaternion

SE3Velocity

Geometric primitive that describes a 3D velocity through it’s linear and angular components.

Field Type Description
linear Vec3 (m/s)
angular Vec3 (rad/s)

Vec2

Two dimensional vector primitive.

Field Type Description
x double
y double

Vec2Value

A 2D vector of doubles that uses wrapped values so we can tell which elements are set.

Field Type Description
x google.protobuf.DoubleValue
y google.protobuf.DoubleValue

Vec3

Three dimensional vector primitive.

Field Type Description
x double
y double
z double

Vec3Value

A 3D vector of doubles that uses wrapped values so we can tell which elements are set.

Field Type Description
x google.protobuf.DoubleValue
y google.protobuf.DoubleValue
z google.protobuf.DoubleValue

Volume

Represents a volume of space in an unspecified frame.

Field Type Description
box Vec3 Dimensions in m, centered on frame origin.

Wrench

Geometric primitive used to specify forces and torques.

Field Type Description
force Vec3 (N)
torque Vec3 (Nm)

graph_nav/graph_nav.proto

ClearGraphRequest

Clears the graph on the server.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease The Lease to show ownership of graph-nav service.

ClearGraphResponse

The results of the ClearGraphRequest.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.

DownloadEdgeSnapshotRequest

The DownloadEdgeSnapshot request asks for a specific edge snapshot id to be downloaded.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
edge_snapshot_id string ID of the data associated with an edge.

DownloadEdgeSnapshotResponse

The DownloadEdgeSnapshot response streams the data of the edge snapshot id currently being downloaded

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status DownloadEdgeSnapshotResponse.Status Return status for the request.
edge_snapshot_id string ID of the snapshot associated with an edge.
chunk bosdyn.api.DataChunk Chunk of data to download.

DownloadGraphRequest

The DownloadGraph request message requests for the current graph nav map to be downloaded.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

DownloadGraphResponse

The DownloadGraph response message includes the current graph on the robot.

Field Type Description
header bosdyn.api.ResponseHeader Common request header.
graph Graph The structure of the graph.

DownloadWaypointSnapshotRequest

The DownloadWaypointSnapshot request asks for a specific waypoint snapshot id to be downloaded and has parameters to decrease the amount of data downloaded.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
waypoint_snapshot_id string ID of the snapshot associated with a waypoint.
download_images bool If true, download the full images and point clouds from each camera.
compress_point_cloud bool If true, the point cloud will be compressed using the smallest available point cloud encoding. If false, three 32-bit floats will be used per point.

DownloadWaypointSnapshotResponse

The DownloadWaypointSnapshot response streams the data of the waypoint snapshot id currently being downloaded

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status DownloadWaypointSnapshotResponse.Status Return status for the request.
waypoint_snapshot_id string ID of the snapshot associated with a waypoint.
chunk bosdyn.api.DataChunk Chunk of data to download. Responses are sent in sequence until the data chunk is complete.

GetLocalizationStateRequest

The GetLocalizationState request message requests the current localization state and any other live data from the robot if desired.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
request_live_point_cloud bool If true, request the live edge-segmented point cloud that was used to generate this localization.
request_live_images bool If true, request the live images from realsense cameras at the time of localization.
request_live_terrain_maps bool If true, request the live terrain maps at the time of localization.
request_live_world_objects bool If true, reqeuest the live world objects at the time of localization.
request_live_robot_state bool If true, requests the full live robot state at the time of localization.
compress_live_point_cloud bool If true, the smallest available encoding will be used for the live point cloud data. If false, three 32 bit floats will be used per point in the point cloud.

GetLocalizationStateResponse

The GetLocalizationState response message returns the current localization and robot state, as well as any requested live data information.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
localization Localization Where the robot currently is.
robot_kinematics bosdyn.api.KinematicState Robot kinematic state at time of localization.
remote_cloud_status RemotePointCloudStatus Status of one or more remote point cloud services (such as velodyne).
live_data WaypointSnapshot Contains live data at the time of localization, with elements only filled out if requested.
lost_detector_state LostDetectorState If the robot drives around without a good localization for a while, eventually it becomes "lost." I.E. it has a localization, but it no longer trusts that the localization it has is accurate. Lost detector state is available through this message.

LostDetectorState

Message describing whether or not graph nav is lost, and if it is lost, how lost it is. If robot is lost, this state can be reset by either:

  • Driving to an area where the robot’s localization improves.

  • Calling SetLocalization RPC.

Field Type Description
is_lost bool Whether or not the robot is currently lost. If this is true, graph nav will reject NavigateTo or NavigateRoute RPC's.

RemotePointCloudStatus

Message describing the state of a remote point cloud service (such as a velodyne).

Field Type Description
service_name string The name of the point cloud service.
exists_in_directory bool Boolean indicating if the point cloud service was registered in the robot's directory with the provided name.
has_data bool Boolean indicating if the point cloud service is currently outputting data.

RouteGenParams

SetLocalizationRequest

The SetLocalization request message can trigger a manumal localization.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
initial_guess Localization Operator-supplied guess at localization.
ko_tform_body bosdyn.api.SE3Pose Robot pose when the initial_guess was made. This overcomes the race that occurs when the client is trying to initialize a moving robot. GraphNav will use its local ko_tform_body and this ko_tform_body to update the initial localization guess, if necessary.
max_distance double The max distance [meters] is how far away the robot is allowed to localize from the position supplied in the initial guess. If not specified, the offset is used directly. Otherwise it searches a neighborhood of the given size.
max_yaw double The max yaw [radians] is how different the localized yaw is allowed to be from the supplied yaw in the initial guess. If not specified, the offset is used directly. Otherwise it searches a neighborhood of the given size.
fiducial_init SetLocalizationRequest.FiducialInit Tells the initializer whether to use fiducials, and how to use them.
use_fiducial_id int32 If using FIDUCIAL_INIT_SPECIFIC, this is the specific fiducial ID to use for initialization.
refine_fiducial_result_with_icp bool If true, and we are using fiducials during initialization, will run ICP after the fiducial was used for an initial guess.
do_ambiguity_check bool If true, consider how nearby localizations appear (like turned 180).

SetLocalizationResponse

The SetLocalization response message contains the resulting localization of the robot.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Result of using the lease.
status SetLocalizationResponse.Status Return status for the request.
error_report string If set, describes the reason the status is not OK.
localization Localization Result of localization.
suspected_ambiguity SetLocalizationResponse.SuspectedAmbiguity Alternative information if the localization is ambiguous.

SetLocalizationResponse.SuspectedAmbiguity

Field Type Description
alternate_robot_tform_waypoint bosdyn.api.SE3Pose Example of a potentially ambiguous localization near the result of the initialization.

TravelParams

Parameters describing how to travel along a route.

Field Type Description
max_distance double Threshold for the maximum distance [meters] that defines when we have reached the final waypoint.
max_yaw double Threshold for the maximum yaw [radians] that defines when we have reached the final waypoint (ignored if ignore_final_yaw is set to true).
velocity_limit bosdyn.api.SE2VelocityLimit Speed the robot should use. Omit to let the robot choose.
ignore_final_yaw bool If true, the robot will only try to achieve the final translation of the route. Otherwise, it will attempt to achieve the yaw as well.

UploadEdgeSnapshotRequest

Used to upload waypoint data in chunks for a specific waypoint. Chunks will be streamed one at a time to the server.

Field Type Description
header bosdyn.api.RequestHeader Common response header.
chunk bosdyn.api.DataChunk Serialized bytes of a Edge.Data message.
lease bosdyn.api.Lease The Leases to show ownership of the graph-nav service.

UploadEdgeSnapshotResponse

One response for the entire Edge.Data after all chunks have been concatenated and deserialized.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.

UploadGraphRequest

Uploads a graph to the server. This graph will be appended to the graph that currently exists on the server.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
graph Graph Structure of the graph containing waypoints and edges without underlying sensor data.
lease bosdyn.api.Lease The Lease to show ownership of graph-nav service.

UploadGraphResponse

The UploadGraph response message returns mappings for the edge and waypoint ids for which id’s it had cached or not.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status UploadGraphResponse.Status Status for an upload request.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.
loaded_waypoint_snapshot_ids string The waypoint snapshot ids for which there was cached data.
unknown_waypoint_snapshot_ids string The waypoint snapshot ids for which there is no cached data.
loaded_edge_snapshot_ids string The edge snapshot ids for which there was cached data.
unknown_edge_snapshot_ids string The edge snapshot ids for which there was no cached data.
license_status bosdyn.api.LicenseInfo.Status Large graphs can only be uploaded if the license permits them.

UploadWaypointSnapshotRequest

Used to upload waypoint snapshot in chunks for a specific waypoint. Chunks will be streamed one at a time to the server.

Field Type Description
header bosdyn.api.RequestHeader Common response header.
chunk bosdyn.api.DataChunk Serialized bytes of a WaypointSnapshot message.
lease bosdyn.api.Lease The Leases to show ownership of the graph-nav service.

UploadWaypointSnapshotResponse

One response for the entire WaypointSnapshot after all chunks have been concatenated and deserialized.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.

DownloadEdgeSnapshotResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_SNAPSHOT_DOES_NOT_EXIST 2 Error where the given snapshot ID does not exist.

DownloadWaypointSnapshotResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_SNAPSHOT_DOES_NOT_EXIST 2 Error where the given snapshot ID does not exist.

SetLocalizationRequest.FiducialInit

Name Number Description
FIDUCIAL_INIT_UNKNOWN 0 It is a programming error to use this one.
FIDUCIAL_INIT_NO_FIDUCIAL 1 Ignore fiducials during initialization.
FIDUCIAL_INIT_NEAREST 2 Localize to the nearest fiducial in any waypoint.
FIDUCIAL_INIT_NEAREST_AT_TARGET 3 Localize to nearest fiducial at the target waypoint.
FIDUCIAL_INIT_SPECIFIC 4 Localize to the given fiducial at the target waypoint.

SetLocalizationResponse.Status

Name Number Description
STATUS_UNKNOWN 0 The status is unknown/unset.
STATUS_OK 1 Localization success.
STATUS_ROBOT_IMPAIRED 2 Robot is experiencing a condition that prevents localization.
STATUS_UNKNOWN_WAYPOINT 3 The given waypoint is unknown by the system. This could be due to a client error, or because the graph was changed out from under the client.
STATUS_ABORTED 4 Localization was aborted, likely because of a new request.
STATUS_FAILED 5 Failed to localize for some other reason; see the error_report for details. This is often because the initial guess was incorrect.

UploadGraphResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_MAP_TOO_LARGE_LICENSE 3 Can't upload the graph because it was too large for the license.

graph_nav/graph_nav_service.proto

GraphNavService

The GraphNav service service is a place-based localization and locomotion service. The service can be used to get/set the localization, upload and download the current graph nav maps, and send navigation requests to move around the map.

Method Name Request Type Response Type Description
SetLocalization SetLocalizationRequest SetLocalizationResponse Trigger a manual localization. Typically done to provide the initial localization.
NavigateRoute NavigateRouteRequest NavigateRouteResponse Tell GraphNav to navigate/traverse a given route.
NavigateTo NavigateToRequest NavigateToResponse Tell GraphNav to navigate to a waypoint along a route it chooses.
NavigationFeedback NavigationFeedbackRequest NavigationFeedbackResponse Get feedback on active navigation command.
GetLocalizationState GetLocalizationStateRequest GetLocalizationStateResponse Get the localization status and data.
ClearGraph ClearGraphRequest ClearGraphResponse Clears the local graph structure. Also erases any snapshots currently in RAM.
DownloadGraph DownloadGraphRequest DownloadGraphResponse Download the graph structure.
UploadGraph UploadGraphRequest UploadGraphResponse Upload the full list of waypoint IDs, graph topology and other small info.
UploadWaypointSnapshot UploadWaypointSnapshotRequest stream UploadWaypointSnapshotResponse Uploads large waypoint snapshot as a stream for a particular waypoint.
UploadEdgeSnapshot UploadEdgeSnapshotRequest stream UploadEdgeSnapshotResponse Uploads large edge snapshot as a stream for a particular edge.
DownloadWaypointSnapshot DownloadWaypointSnapshotRequest DownloadWaypointSnapshotResponse stream Download waypoint data from the server. If the snapshot exists in disk cache, it will be loaded.
DownloadEdgeSnapshot DownloadEdgeSnapshotRequest DownloadEdgeSnapshotResponse stream Download edge data from the server. If the snapshot exists in disk cache, it will be loaded.

graph_nav/map.proto

Edge

A base element of the graph nav map. Edges consist of a directed edge from one waypoint to another and a transform that estimates the relationship in 3D space between the two waypoints.

Field Type Description
id Edge.Id Identifier of this Edge. Edges are mutable -- the identifier does not have to be updated when other fields change.
snapshot_id string Identifier of this edge's Snapshot data.
from_tform_to bosdyn.api.SE3Pose Describes the transform between the "from" waypoint and the "to" waypoint.
annotations Edge.Annotations Annotations specific to the current edge.

Edge.Annotations

Annotations understood by BostonDynamics systems.

Field Type Description
vel_limit bosdyn.api.SE2VelocityLimit Velocity limits to use while traversing the edge. These are maxima and minima, NOT target speeds.
stairs Edge.Annotations.StairData Stairs information/parameters specific to the edge.
direction_constraint Edge.Annotations.DirectionConstraint Direction constraints for how the robot must move and the directions it can face when traversing the edge.
require_alignment google.protobuf.BoolValue If true, the robot must be aligned with the edge in yaw before traversing it.
flat_ground google.protobuf.BoolValue If true, the edge crosses flat ground and the robot shouldn't try to climb over obstacles.
ground_mu_hint google.protobuf.DoubleValue Terrain coefficient of friction user hint. This value must be postive and will clamped if necessary on the robot side. Best suggested values lie in the range between 0.4 and 0.8 (which is the robot's default.)
grated_floor google.protobuf.BoolValue If true, the edge crosses over grated metal. This changes some parameters of the robot's perception system to allow it to see grated floors bettter.

Edge.Annotations.StairData

Defines any parameters of the stairs

Field Type Description
state AnnotationState Check this before reading other fields.
straight_staircase Edge.Annotations.StairData.StraightStaircase Parameters describing a straight staircase.

Edge.Annotations.StairData.StraightStaircase

Field Type Description
from_ko_tform_stairs bosdyn.api.SE3Pose The staircase origin is the bottom-center of the first rise. It is expressed in ko frame of the from_waypoint.
stairs Edge.Annotations.StairData.StraightStaircase.Stair Each stair should be rise followed by run. The last stair will have zero run.

Edge.Annotations.StairData.StraightStaircase.Stair

A single stair from a staircase.

Field Type Description
rise float Height of each stair.
run float Depth of each stair.

Edge.Id

An edge is uniquely identified by the waypoints it connects. Two waypoints will only ever be connected by a single edge. That edge is traversable in either direction.

Field Type Description
from_waypoint string Identifier of the "from" waypoint.
to_waypoint string Identifier of the "to" waypoint.

EdgeSnapshot

Relevant data collected along the edge. May be used for automatically generating annotations, for example.

Field Type Description
id string Identifier of this snapshot. Snapshots are immutable -- if any of the other fields change, this ID must also change.
stances EdgeSnapshot.Stance Sampling of stances as robot traversed this edge.

EdgeSnapshot.Stance

Field Type Description
timestamp google.protobuf.Timestamp Timestamp of the stance.
foot_states bosdyn.api.FootState List of all the foot positions for a single stance.
ko_tform_body bosdyn.api.SE3Pose Body position corresponding to this stance.

Graph

This is an arbitrary collection of waypoints and edges. The edges and waypoints are not required to be connected. A waypoint may belong to multiple graphs. This message is used to pass around information about a graph’s topology, and is used to serialize map topology to and from files. Note that the graph does not contain any of the waypoint/edge data (which is found in snapshots). Snapshots are stored separately.

Field Type Description
waypoints Waypoint The waypoints for the graph (containing frames, annotations, and sensor data).
edges Edge The edges connecting the graph's waypoints.

Waypoint

A base element of the graph nav map. A waypoint consists of a reference frame, a name, a unique ID, annotations, and sensor data.

Field Type Description
id string Identifier of the waypoint. Unique across all maps. This identifier does not have to be updated when its fields change.
snapshot_id string Identifier of this waypoint's Snapshot data.
waypoint_tform_ko bosdyn.api.SE3Pose Transform from the KO frame (at time of recording) to the waypoint.
annotations Waypoint.Annotations Annotations specific to the current waypoint.

Waypoint.Annotations

Annotations understood by BostonDynamics systems.

Field Type Description
name string Human-friendly name of the waypoint. For example, "Kitchen Fridge"
icp_variance bosdyn.api.SE3Covariance Estimate of the variance of ICP when performed at this waypoint, collected at record time.
scan_match_region Waypoint.Annotations.LocalizeRegion Options for how to localize to a waypoint (if at all).

Waypoint.Annotations.LocalizeRegion

Field Type Description
state AnnotationState Check this before reading other fields.
default_region Waypoint.Annotations.LocalizeRegion.Default Oneof field that describes the waypoint's location as a default region (no special features/traits).
empty Waypoint.Annotations.LocalizeRegion.Empty Oneof field that describes the waypoint's location as a empty/featureless region.
circle Waypoint.Annotations.LocalizeRegion.Circle2D Oneof field that describes the waypoint's location as a circular region.

Waypoint.Annotations.LocalizeRegion.Circle2D

Indicates the number of meters away we can be from this waypoint we can be before scan matching.

  • If zero, the default value is used.

  • If less than zero, no scan matching will be performed at this waypoint.

  • If greater than zero, scan matching will only be performed if the robot is at most this far away from the waypoint. Distance calculation is done in the 2d plane with respect to the waypoint.

Field Type Description
dist_2d double meters.

Waypoint.Annotations.LocalizeRegion.Default

Use the default region to localize in.

Waypoint.Annotations.LocalizeRegion.Empty

Do not localize to this waypoint.

WaypointSnapshot

Relevant data collected at the waypoint. May be used for localization or automatically generating annotations, for example. Should be indexed by a waypoint’s “snapshot_id” field.

Field Type Description
id string Identifier of this snapshot. Snapshots are immutable -- if any of the other fields change, this ID must also change.
images bosdyn.api.ImageResponse Any images captured at the waypoint.
point_cloud bosdyn.api.PointCloud Aggregated point cloud data.
objects bosdyn.api.WorldObject Perception objects seen at snapshot time.
robot_state bosdyn.api.RobotState Full robot state during snapshot.
robot_local_grids bosdyn.api.LocalGrid Robot grid data.
is_point_cloud_processed bool If true, the point cloud of this snapshot has been processed.
version_id string If this snapshot is a modified version of the raw snapshot with the given ID (for example, it has been processed), a new unique ID will we assigned to this field. If the field is empty, this is the raw version of the snapshot.

AnnotationState

Indicator of whether or not the waypoint and edge annotations are complete and filled out.

Name Number Description
ANNOTATION_STATE_UNKNOWN 0 No assertions made about this annotation.
ANNOTATION_STATE_SET 1 This annotation and all of its fields have been deliberately set.
ANNOTATION_STATE_NONE 2 This annotation has been deliberately set to "no annotation" -- any subfields are unset.

Edge.Annotations.DirectionConstraint

Name Number Description
DIRECTION_CONSTRAINT_UNKNOWN 0 We don't know if there are direction constraints.
DIRECTION_CONSTRAINT_NO_TURN 1 The robot must not turn while walking the edge, but can face either waypoint.
DIRECTION_CONSTRAINT_FORWARD 2 Robot should walk the edge face-first.
DIRECTION_CONSTRAINT_REVERSE 3 Robot should walk the edge rear-first.
DIRECTION_CONSTRAINT_NONE 4 No constraints on which way the robot faces.

graph_nav/nav.proto

Localization

The localization state of the robot. This reports the pose of the robot relative to a particular waypoint on the graph nav map.

Field Type Description
waypoint_id string Waypoint we're localized to.
waypoint_tform_body bosdyn.api.SE3Pose Pose of body in waypoint frame.
timestamp google.protobuf.Timestamp Time (in robot time basis) that this localization was valid.

Route

Route that the robot should follow or is currently following.

Field Type Description
waypoint_id string Ordered list of waypoints to traverse, starting from index 0.
edge_id Edge.Id Ordered list of edges to traverse between those waypoints.

graph_nav/recording.proto

CreateEdgeRequest

The CreateEdge request message specifies an edge to create between two existing waypoints. The edge must not already exist in the map. This can be used to close a loop or to add any additional edges.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
edge Edge Create an edge between two existing waypoints in the map with the given parameters.
lease bosdyn.api.Lease The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.

CreateEdgeResponse

The CreateEdge response message contains the status of this request and any useful error information if the request fails.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status CreateEdgeResponse.Status Return status for the request.
error_existing_edge Edge If set, the existing edge that caused the STATUS_EXISTS error.
lease_use_result bosdyn.api.LeaseUseResult The results/status of the lease provided.

CreateWaypointRequest

The CreateWaypoint request message specifies a name and environment the robot should use to generate a waypoint in the graph at it’s current location.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
waypoint_name string Name of the waypoint to create. Overrides any naming prefix.
recording_environment RecordingEnvironment This will be merged into a copy of the existing persistent recording environment and used as the environment for the created waypoint and the edge from the previous waypoint to the new one. It will not affect the persistent environment.
lease bosdyn.api.Lease The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
require_fiducials int32 If filled out, asks that the record service verify that the given fiducial IDs are presently visible before creating a waypoint. This is useful for verifying that the robot is where the user thinks it is in an area with known fiducials.

CreateWaypointResponse

The CreateWaypoint response message contains the complete waypoint, and the associated edge connecting this waypoint to the graph when the request succeeds.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
created_waypoint Waypoint The waypoint that was just created.
created_edge Edge The edge connecting the waypoint just created with the last created waypoint in the map.
status CreateWaypointResponse.Status Return status for the request.
lease_use_result bosdyn.api.LeaseUseResult The results/status of the lease provided.
missing_fiducials int32 If the status is STATUS_MISSING_FIDUCIALS, the following fiducials were not visible to the robot when trying to create the waypoint.
license_status bosdyn.api.LicenseInfo.Status Large graphs can only be uploaded if the license permits them. Recording will stop automatically when the graph gets too large. If CreateWaypointResponse is requested after the graph gets too large, it will fail, and license status will be filled out.

GetRecordStatusRequest

The GetRecordStatus request message asks for the current state of the recording service.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetRecordStatusResponse

The GetRecordStatus response message returns whether the service is currently recording and what the persistent recording environment is at the time the request was recieved.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
is_recording bool If true, the record service is actively recording a chain.
recording_environment RecordingEnvironment The current persistent recording environment.
map_state GetRecordStatusResponse.MapState

RecordingEnvironment

The RecordingEnvironment is a set of annotation information and a name for the current environment that will persist for all edges and waypoints until it is changed or updated

Field Type Description
name_prefix string This will be prepended to the start of every waypoint name.
waypoint_environment Waypoint.Annotations Persistent waypoint annotation that will be merged in to all waypoints in this recording.
edge_environment Edge.Annotations Persistent edge annotation that will be merged in to all waypoints in this recording.

SetRecordingEnvironmentRequest

The SetRecordingEnvironment request message sets a persistent recording environment until changed with another SetRecordingEnvironment rpc.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
environment RecordingEnvironment Persistent environment to use while recording. This allows the user to specify annotations and naming prefixes for new waypoints and edges.
lease bosdyn.api.Lease The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.

SetRecordingEnvironmentResponse

The SetRecordingEnvironment response message includes the result and status of the request.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult The results/status of the lease provided.

StartRecordingRequest

The StartRecording request tells the recording service to begin creating waypoints with the specified recording_environment.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.
recording_environment RecordingEnvironment This will be merged into a copy of the existing persistent recording environment and used as the environment for the created waypoint and the edge from the previous waypoint to the new one. It will not affect the persistent environment.
require_fiducials int32 If filled out, asks that the record service verify that the given fiducial IDs are presently visible before starting to record. This is useful for verifying that the robot is where the user thinks it is in an area with known fiducials.

StartRecordingResponse

The StartRecording response messge returns the first created waypoint, which is made at the location the robot was standing when the request was made, in addition to any status information.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
created_waypoint Waypoint The waypoint that was just created.
lease_use_result bosdyn.api.LeaseUseResult The results/status of the lease provided.
status StartRecordingResponse.Status Return status for the request.
missing_fiducials int32 If the status is STATUS_MISSING_FIDUCIALS, these are the fiducials that are not currently visible.
license_status bosdyn.api.LicenseInfo.Status Large graphs can only be uploaded if the license permits them. Recording will stop automatically when the graph gets too large. If StartRecording is requested again after the graph gets too large, it will fail, and license status will be filled out.

StopRecordingRequest

The StopRecording request message tells the robot to no longer continue adding waypoints and edges to the graph.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease The recording service is protected by a lease. The client must have a lease to the recording service to modify its internal state.

StopRecordingResponse

The StopRecording response message contains the status of this request and any useful error information if the request fails.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status StopRecordingResponse.Status The return status for the request.
error_waypoint_localized_id string If not localized to end, specifies which waypoint we are localized to.
lease_use_result bosdyn.api.LeaseUseResult The results/status of the lease provided.

CreateEdgeResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status is unknown/unset.
STATUS_OK 1 The edge was successfully created.
STATUS_EXISTS 2 Edge already exists with the given ID.
STATUS_NOT_RECORDING 3 Clients can only create edges when recording.
STATUS_UNKNOWN_WAYPOINT 4 One or more of the specified waypoints aren't in the map.
STATUS_MISSING_TRANSFORM 5 Specified edge did not include a transform.

CreateWaypointResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status is unknown/unset.
STATUS_OK 1 The waypoint was successfully created.
STATUS_NOT_RECORDING 2 Clients can only create waypoints when recording.
STATUS_COULD_NOT_CREATE_WAYPOINT 3 An internal server error prevented the creation of the waypoint.
STATUS_MISSING_FIDUCIALS 4 Could not see the required fiducials.
STATUS_MAP_TOO_LARGE_LICENSE 5 The map was too big to create a waypoint based on the license.

GetRecordStatusResponse.MapState

Name Number Description
MAP_STATE_UNKNOWN 0
MAP_STATE_OK 1
MAP_STATE_TOO_LARGE_FOR_LICENSE 2

StartRecordingResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status is unknown/unset.
STATUS_OK 1 Recording has been started.
STATUS_COULD_NOT_CREATE_WAYPOINT 2 In this case we tried to start recording, but GraphNav was internally still waiting for some data from the robot.
STATUS_FOLLOWING_ROUTE 3 Can't start recording because the robot is following a route.
STATUS_NOT_LOCALIZED_TO_EXISTING_MAP 4 When recording branches, the robot is not localized to the existing map before starting to record a new branch.
STATUS_MISSING_FIDUCIALS 5 Can't start recording because the robot doesn't see the required fiducials.
STATUS_MAP_TOO_LARGE_LICENSE 6 Can't start recording because the map was too large for the license.

StopRecordingResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status is unknown/unset.
STATUS_OK 1 Recording is stopped.
STATUS_NOT_LOCALIZED_TO_END 2 In this case we tried to stop recording, but had an incorrect localization. graph_nav is expected to be localized to the final waypoint in the chain before we stop recording.
STATUS_NOT_READY_YET 3 The robot is still processing the map it created to where the robot is currently located. You can't stop recording until that processing is finished. You should not move the robot, then try to stop recording again after 1-2 seconds.

graph_nav/recording_service.proto

GraphNavRecordingService

The recording service can be used to record a Graph Nav map (containing waypoints and edges). The recorded map can consist of the following:

  • Chain: a topological arrangement of waypoints/edges where every waypoint has at least 1 but at most 2 edges attached to it.

  • Branch: separate Chains can be joined together into a Branch at exactly one waypoint. When recording a map using the recording service, a common pattern is:

  • Call StartRecording to begin recording a chain of waypoints.

  • Call SetRecordingEnvironment to define persistent annotations for the edges and waypoints.

  • While recording, call GetRecordStatus to get feedback on the state of the recording service.

  • While recording, call GetMapStatus to determine what waypoints have been created.

  • Optionally call CreateWaypoint to create waypoints in specific locations.

  • Call StopRecording to pause the recording service and create branches.

  • While recording (or after completing recording), call DownloadWaypoint/Edge Snapshot rpc’s from the GraphNavService to download the large sensor data with the map.

Method Name Request Type Response Type Description
StartRecording StartRecordingRequest StartRecordingResponse Start recording the map from the current localization. Creates a waypoint if you are starting to record. Otherwise, waits until you are sufficiently far away from the previous waypoint.
StopRecording StopRecordingRequest StopRecordingResponse Stop recording the map from the current localization.
CreateWaypoint CreateWaypointRequest CreateWaypointResponse Create a new waypoint at the current localization.
SetRecordingEnvironment SetRecordingEnvironmentRequest SetRecordingEnvironmentResponse Set the environmnent and name prefix to use for the recording.
CreateEdge CreateEdgeRequest CreateEdgeResponse Create an arbitrary edge between two waypoints.
GetRecordStatus GetRecordStatusRequest GetRecordStatusResponse Tells the client the internal state of the record service, and the structure of the map that has been recorded so far.

header.proto

CommonError

General error code are returned in the header to facilitate error-handling which is not message-specific. This can be used for generic error handlers, aggregation, and trend analysis.

Field Type Description
code CommonError.Code The different error codes that can be returned on a grpc response message.
message string Human-readable error description. Not for programmatic analysis.
data google.protobuf.Any Extra information that can optionally be provided for generic error handling/analysis.

RequestHeader

Standard header attached to all GRPC requests to services.

Field Type Description
request_timestamp google.protobuf.Timestamp Time that the request was sent, as measured by the client's local system clock.
client_name string Name of the client to identify itself. The name will typically include a symbolic string to identify the program, and a unique integer to identify the specific instance of the process running.

ResponseHeader

Standard header attached to all GRPC responses from services.

Field Type Description
request_header RequestHeader Echo-back the RequestHeader for timing information, etc....
request_received_timestamp google.protobuf.Timestamp Time that the request was received. The server clock is the time basis.
response_timestamp google.protobuf.Timestamp Time that the response was received. The server clock is the time basis.
error CommonError Common errors, such as invalid input or internal server problems. If there is a common error, the rest of the response message outside of the ResponseHeader will be invalid.
request google.protobuf.Any Echoed request message. In some cases it may not be present, or it may be a stripped down representation of the request.

CommonError.Code

Name Number Description
CODE_UNSPECIFIED 0 Code is not specified.
CODE_OK 1 Not an error. Request was successful.
CODE_INTERNAL_SERVER_ERROR 2 Service experienced an unexpected error state.
CODE_INVALID_REQUEST 3 Ill-formed request. Request arguments were not valid.

image.proto

GetImageRequest

The GetImage request message which can send multiple different image source requests at once.

Field Type Description
header RequestHeader Common request header.
image_requests ImageRequest The different image requests for this rpc call.

GetImageResponse

The GetImage response message which includes image data for all requested sources.

Field Type Description
header ResponseHeader Common response header.
image_responses ImageResponse The ordering of these image responses is defined by the order of the ImageRequests.

Image

Rectangular color/greyscale/depth images.

Field Type Description
cols int32 Number of columns in the image (in pixels).
rows int32 Number of rows in the image (in pixels).
data bytes Raw image data.
format Image.Format How the image is encoded.
pixel_format Image.PixelFormat If Format does not imply PixelFormat, this will be set.

ImageCapture

Rectangular color/greyscale images.

Field Type Description
acquisition_time google.protobuf.Timestamp The time at which the image data was acquired in the robot's time basis.
transforms_snapshot FrameTreeSnapshot A tree-based collection of transformations, which will include the transformations to each image's sensor in addition to transformations to the common frames ("vision", "body", "odom"). All transforms within the snapshot are at the acquistion time of the image.
frame_name_image_sensor string The frame name for the image's sensor source. This will be included in the transform snapshot.
image Image Image data.

ImageRequest

The image request specifying the image source and data format desired.

Field Type Description
image_source_name string The string name of the image source to get image data from.
quality_percent double Image quality: a number from 0 (worst) to 100 (highest). Note that jpeg quality 100 is still lossy.
image_format Image.Format Specify the desired image encoding (e.g. JPEG, RAW).

ImageResponse

The image response for each request, that includes image data and image source information.

Field Type Description
shot ImageCapture The image capture contains the image data and information about the state of the camera and robot at the time the image was collected.
source ImageSource The source describes general information about the camera source the image data was collected from.
status ImageResponse.Status Return status of the request.

ImageSource

Proto for a description of an image source on the robot.

Field Type Description
name string The name of this image source used to get images.
cols int32 Number of columns in the image (in pixels).
rows int32 Number of rows in the image (in pixels).
depth_scale double The depth scale for the image data. Typically 1000, which converts it from mm to m.
pinhole ImageSource.PinholeModel Rectilinear camera model.
image_type ImageSource.ImageType The kind of images returned by this image source.

ImageSource.PinholeModel

The camera can be modeled as a pinhole camera described with a matrix. Camera Matrix can be constructed by the camera intrinsics: [[focal_length.x, skew.x, principal_point.x], [[ skew.y, focal_length.y, principal_point.y], [[ 0, 0, 1]]

Field Type Description
intrinsics ImageSource.PinholeModel.CameraIntrinsics The camera intrinsics are necessary for descrbing the pinhole camera matrix.

ImageSource.PinholeModel.CameraIntrinsics

Intrinsic parameters are in pixel space.

Field Type Description
focal_length Vec2 The focal length of the camera.
principal_point Vec2 The optical center in sensor coordinates.
skew Vec2 The skew for the intrinsic matrix.

ListImageSourcesRequest

The ListImageSources request message for the robot image service.

Field Type Description
header RequestHeader Common request header.

ListImageSourcesResponse

The ListImageSources response message which contains all known image sources for the robot.

Field Type Description
header ResponseHeader Common response Header.
image_sources ImageSource The set of ImageSources available from this service. May be empty if the service serves no cameras (e.g., if no cameras were found on startup).

Image.Format

Name Number Description
FORMAT_UNKNOWN 0 Unknown image format.
FORMAT_JPEG 1 Color/greyscale formats. JPEG format.
FORMAT_RAW 2 Uncompressed. Requires pixel_format.
FORMAT_RLE 3 1 byte run-length before each pixel value.

Image.PixelFormat

Name Number Description
PIXEL_FORMAT_UNKNOWN 0 Unspecified value -- should not be used.
PIXEL_FORMAT_GREYSCALE_U8 1 One byte per pixel.
PIXEL_FORMAT_RGB_U8 3 Three bytes per pixel.
PIXEL_FORMAT_RGBA_U8 4 Four bytes per pixel.
PIXEL_FORMAT_DEPTH_U16 5 Little-endian uint16 z-distance from camera (mm).

ImageResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal ImageService issue has happened if UNKNOWN is set. None of the other fields are filled out.
STATUS_OK 1 Call succeeded at filling out all the fields.
STATUS_UNKNOWN_CAMERA 2 Image source name in request is unknown. Other fields are not filled out.
STATUS_SOURCE_DATA_ERROR 3 Failed to fill out ImageSource. All the other fields are not filled out.
STATUS_IMAGE_DATA_ERROR 4 There was a problem with the image data. Only the ImageSource is filled out.

ImageSource.ImageType

Name Number Description
IMAGE_TYPE_UNKNOWN 0 Unspecified image type.
IMAGE_TYPE_VISUAL 1 Color or greyscale intensity image.
IMAGE_TYPE_DEPTH 2 Pixel values represent distances to objects/surfaces.

image_service.proto

ImageService

An Image service provides access to one or more images, for example from cameras. It supports querying for the list of available images provided by the service and then supports requesting a latest given image by source name.

Method Name Request Type Response Type Description
ListImageSources ListImageSourcesRequest ListImageSourcesResponse Obtain the list of ImageSources. The name field keys access to individual images when calling GetImage.
GetImage GetImageRequest GetImageResponse Request an image by name, with optional parameters for requesting image quality level.

lease.proto

AcquireLeaseRequest

The AcquireLease request message which sends which resource the lease should be for.

Field Type Description
header RequestHeader Common request header.
resource string The resource to obtain a Lease for.

AcquireLeaseResponse

The AcquireLease response returns the lease for the desired resource if it could be obtained. If a client is returned a new lease, the client should initiate a RetainLease bidirectional streaming request immediately after completion of AcquireLease.

Field Type Description
header ResponseHeader Common response Header.
status AcquireLeaseResponse.Status Return status for the request.
lease Lease The lease for the resource. Only set if status field == STATUS_OK.
lease_owner LeaseOwner The owner for the lease. Set if status field == OK or status field == RESOURCE_ALREADY_CLAIMED.

Lease

Leases are used to verify that a client has exclusive access to a shared resources. Examples of shared resources are the motors for a robot, or indicator lights on a robot. Leases are initially obtained by clients from the LeaseService. Clients then attach Leases to Commands which require them. Clients may also generate sub-Leases to delegate out control of the resource to other services.

Field Type Description
resource string The resource that the Lease is for.
epoch string The epoch for the Lease. The sequences field are scoped to a particular epoch. One example of where this can be used is to generate a random epoch at LeaseService startup.
sequence uint32 Logical vector clock indicating when the Lease was generated.

LeaseOwner

Details about who currently owns the Lease for a resource.

Field Type Description
client_name string The name of the client application.
user_name string The name of the user.

LeaseResource

Describes all information about a sepcific lease: including the resource it covers, the active lease, and which application is the owner of a lease.

Field Type Description
resource string The resource name.
lease Lease The active lease, if any.
lease_owner LeaseOwner The Lease Owner, if there is a Lease.

LeaseUseResult

Result for when a Lease is used - for example, in a LeaseRetainer, or associated with a command.

Field Type Description
status LeaseUseResult.Status
owner LeaseOwner The current lease owner.
attempted_lease Lease The lease which was attempted for use.
previous_lease Lease The previous lease, if any, which was used.

ListLeasesRequest

The ListLease request message asks for information about any known lease resources.

Field Type Description
header RequestHeader Common request header.

ListLeasesResponse

The ListLease response message returns all known lease resources from the LeaseService.

Field Type Description
header ResponseHeader Common response header.
resources LeaseResource The resources managed by the LeaseService.

RetainLeaseRequest

The RetainLease request will inform the LeaseService that the application contains to hold ownership of this lease. Lease holders are expected to be reachable and alive. If enough time has passed since the last RetainLeaseRequest, the LeaseService will revoke the lease.

Field Type Description
header RequestHeader Common request header.
lease Lease The Lease to retain ownership over. May also be a "super" lease of the lease to retain ownership over.

RetainLeaseResponse

The RetainLease response message sends the result of the attempted RetainLease request, which contains whether or not the lease is still owned by the application sending the request.

Field Type Description
header ResponseHeader Common response header.
lease_use_result LeaseUseResult Result of using the lease.

ReturnLeaseRequest

The ReturnLease request message will be sent to the LeaseService. If the lease is currently active for the resource, the LeaseService will invalidate the lease. Future calls to AcquireLease by any client will now succeed.

Field Type Description
header RequestHeader Common request header.
lease Lease The Lease to return back to the LeaseService.

ReturnLeaseResponse

The ReturnLease response message

Field Type Description
header ResponseHeader Common response header.
status ReturnLeaseResponse.Status Return status for the request.

TakeLeaseRequest

The TakeLease request message which sends which resource the lease should be for.

Field Type Description
header RequestHeader Common request header.
resource string The resource to obtain a Lease for.

TakeLeaseResponse

The TakeLease response returns the lease for the desired resource if it could be obtained. In most cases if the resource is managed by the LeaseService, TakeLease will succeed. However, in the future policies may be introduced which will prevent TakeLease from succeeding and clients should be prepared to handle that case. If a client obtains a new lease, the client should initiate a RetainLease bidirectional streaming request immediately after completion of TakeLease.

Field Type Description
header ResponseHeader Common response header.
status TakeLeaseResponse.Status Return status for the request.
lease Lease The lease for the resource. Only set if status field == STATUS_OK.
lease_owner LeaseOwner The owner for the lease. Set if status field == STATUS_OK.

AcquireLeaseResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal LeaseService issue has happened if UNKNOWN is set.
STATUS_OK 1 AcquireLease was successful.The lease field will be populated with the new lease for the resource. The client is expected to call the RetainLease method immediately after.
STATUS_RESOURCE_ALREADY_CLAIMED 2 AcquireLease failed since the resource has already been claimed. The TakeLease method may be used to forcefully grab the lease.
STATUS_INVALID_RESOURCE 3 AcquireLease failed since the resource is not known to LeaseService. The ListLeaseResources method may be used to list all known resources.
STATUS_NOT_AUTHORITATIVE_SERVICE 4 The LeaseService is not authoritative - so Acquire should not work.

LeaseUseResult.Status

Name Number Description
STATUS_UNKNOWN 0 An internal issue occurred.
STATUS_OK 1 The Lease was accepted.
STATUS_INVALID_LEASE 2 The Lease is invalid.
STATUS_OLDER 3 The Lease is older than the current lease, and rejected.
STATUS_REVOKED 4 The Lease holder did not check in regularly enough, and the Lease is stale.
STATUS_UNMANAGED 5 The Lease was for an unmanaged resource.
STATUS_WRONG_EPOCH 6 The Lease was for the wrong epoch.

ReturnLeaseResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal LeaseService issue has happened if UNKNOWN is set.
STATUS_OK 1 ReturnLease was successful.
STATUS_INVALID_RESOURCE 2 ReturnLease failed because the resource covered by the lease is not being managed by the LeaseService.
STATUS_NOT_ACTIVE_LEASE 3 ReturnLease failed because the lease was not the active lease.
STATUS_NOT_AUTHORITATIVE_SERVICE 4 The LeaseService is not authoritative - so Acquire should not work.

TakeLeaseResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal LeaseService issue has happened if UNKNOWN is set.
STATUS_OK 1 TakeLease was successful. The lease field will be populated with the new lease for the resource. The client is expected to call the RetainLease method immediately after.
STATUS_INVALID_RESOURCE 2 TakeLease failed since the resource is not known to LeaseService. The ListLeaseResources method may be used to list all known resources.
STATUS_NOT_AUTHORITATIVE_SERVICE 3 The LeaseService is not authoritative - so Acquire should not work.

lease_service.proto

LeaseService

LeaseService provides Leases of shared resources to clients. An example of a shared resource is the set of leg motors on Spot, which has the resource name of “body”. Clients can delegate out the Leases they receive from the LeaseService to additional clients or services by generating sub-leases. Leases obtained from the LeaseService may be revoked if the Lease holder does not check in frequently to the LeaseService, or if another client force-acquires a Lease.

Method Name Request Type Response Type Description
AcquireLease AcquireLeaseRequest AcquireLeaseResponse Acquire a lease to a specific resource if the resource is available.
TakeLease TakeLeaseRequest TakeLeaseResponse Take a lease for a specific resource even if another client has a lease.
ReturnLease ReturnLeaseRequest ReturnLeaseResponse Return a lease to the LeaseService.
ListLeases ListLeasesRequest ListLeasesResponse List state of all leases managed by the LeaseService.
RetainLease RetainLeaseRequest RetainLeaseResponse Retain possession of a lease.

license.proto

GetLicenseInfoRequest

Field Type Description
header RequestHeader Common request header.

GetLicenseInfoResponse

Field Type Description
header ResponseHeader Common response header
license LicenseInfo

LicenseInfo

Field Type Description
status LicenseInfo.Status
id string Unique license number
robot_serial string Serial number of the robot this license covers
not_valid_before google.protobuf.Timestamp
not_valid_after google.protobuf.Timestamp
licensed_features string Human readable list of licensed features

LicenseInfo.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_VALID 1
STATUS_EXPIRED 2
STATUS_NOT_YET_VALID 3
STATUS_MALFORMED 4
STATUS_SERIAL_MISMATCH 5
STATUS_NO_LICENSE 6

license_service.proto

LicenseService

The LicenseService allows clients to query the currently installed license on robot.

Method Name Request Type Response Type Description
GetLicenseInfo GetLicenseInfoRequest GetLicenseInfoResponse

local_grid.proto

GetLocalGridTypesRequest

The GetLocalGridTypes request message asks to the local grid types.

Field Type Description
header RequestHeader Common request header.

GetLocalGridTypesResponse

The GetLocalGridTypes response message returns to get all known string names for local grid types.

Field Type Description
header ResponseHeader Common response header.
local_grid_type LocalGridType The list of available local grid types.

GetLocalGridsRequest

The GetLocalGrid request message can request for multiple different types of local grids at one time.

Field Type Description
header RequestHeader Common request header.
local_grid_requests LocalGridRequest Specifications of the requested local grids.

GetLocalGridsResponse

The GetLocalGrid response message replies with all of the local grid data for the requested types, and a numerical count representing the amount of status errors that occurred when getting this data.

Field Type Description
header ResponseHeader Common response header.
local_grid_responses LocalGridResponse Response of local grid or error status for each requested local grid.
num_local_grid_errors int32 The number of individual local grids requests which could not be satisfied.

LocalGrid

A grid-based local grid structure, which can represent different kinds of data, such as terrain or obstacle data.

Field Type Description
local_grid_type_name string The human readable string name that is used to identify the type of local grid data.
acquisition_time google.protobuf.Timestamp The time at which the local grid data was computed and last valid at.
transforms_snapshot FrameTreeSnapshot A tree-based collection of transformations, which will include the transformations to each of the returned local grids in addition to transformations to the common frames ("vision", "body", "odom"). All transforms within the snapshot are at the acquistion time of the local grid.
frame_name_local_grid_data string The frame name for the local grid object. The frame will describe the top, left corner of the topmost, leftmost cell of the local grid. This will be included in the transform snapshot. The (x,y) position specified by the local grid frame's SE3Pose transform represents the (x,y)- offsets for the location of the grid's top left corner. The cell data is packed in x-y order, so the cell at: cell[i + num_cells_x * j] has position: {x_offset + i * extent.cell_size, y_offset + j * extent.cell_size}.
extent LocalGridExtent Location, size and resolution of the local grid.
cell_format LocalGrid.CellFormat The data type of all individual cells in the local grid.
encoding LocalGrid.Encoding The encoding for the 'data' field of the local grid message.
data bytes The encoded local grid representation. Cells are encoded according to the encoding enum, and are stored in in row-major order (x-major). This means that the data field has data entered row by row. The grid cell located at (i, j) will be at the (index = i * num_cells_x + j) within the data array.
rle_counts int32 RLE pixel repetition counts: use data[i] repeated rle_counts[i] times when decoding the bytes data field.
cell_value_scale double The scale for the cell value data; only valid if it is a non-zero number.
cell_value_offset double A fixed value offset that is applied to each value of the cell data. Actual values in local grid are: (({value from data} * cell_value_scale) + cell_value_offset).

LocalGridExtent

Information about the dimensions of the local grid, including the number of grid cells and the size of each cell.

Field Type Description
cell_size double Size of each side of the individual cells in the local grid (in meters). The area of a grid cell will be (cell_size x cell_size).
num_cells_x int32 Number of cells along x extent of local grid (number of columns in local grid/ the local grid width). Note, that the (num_cells_x)x(num_cells_y) represents the total number of grid cells in the local grid.
num_cells_y int32 Number of cells along y extent of local grid (number of rows in local grid). Note, that the (num_cells_x)x(num_cells_y) represents the totla number of grid cells in the local grid.

LocalGridRequest

LocalGrids are requested by LocalGridType string name.

Field Type Description
local_grid_type_name string

LocalGridResponse

The local grid response message will contain either the local grid or an error status.

Field Type Description
local_grid_type_name string The type name of the local grid included in this response.
status LocalGridResponse.Status Status of the request for the individual local grid.
local_grid LocalGrid The requested local grid data.

LocalGridType

Representation of an available type of local grid.

Field Type Description
name string

LocalGrid.CellFormat

Describes the data type of a cell.

Name Number Description
CELL_FORMAT_UNKNOWN 0 Not specified -- not a valid value.
CELL_FORMAT_FLOAT32 1 Each cell of the local grid is encoded as a little-endian 32-bit floating point number.
CELL_FORMAT_FLOAT64 2 Each cell of the local grid is encoded as a little-endian 64-bit floating point number.
CELL_FORMAT_INT8 3 Each cell of the local grid is encoded as a signed 8-bit integer.
CELL_FORMAT_UINT8 4 Each cell of the local grid is encoded as an unsigned 8-bit integer.
CELL_FORMAT_INT16 5 Each cell of the local grid is encoded as a little-endian signed 16-bit integer.
CELL_FORMAT_UINT16 6 Each cell of the local grid is encoded as a little-endian unsigned 16-bit integer.

LocalGrid.Encoding

Encoding used for storing the local grid.

Name Number Description
ENCODING_UNKNOWN 0 Not specified -- not a valid value.
ENCODING_RAW 1 Cells are stored packed uncompressed.
ENCODING_RLE 2 Run-length encoding: repeat counts stored in rle_counts.

LocalGridResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Not specified -- not a valid value.
STATUS_OK 1 LocalGrid was returned successfully.
STATUS_NO_SUCH_GRID 2 The requested local grid-type is unknown.
STATUS_DATA_UNAVAILABLE 3 The request local grid data is not available at this time.
STATUS_DATA_INVALID 4 The local grid data was not valid for some reason.

local_grid_service.proto

LocalGridService

The map service provides access multiple kinds of cell-based map data. It supports querying for the list of available types of local grids provided by the service, and supports requesting a set of the latest local grids by map type name.

Method Name Request Type Response Type Description
GetLocalGridTypes GetLocalGridTypesRequest GetLocalGridTypesResponse Obtain the list of available map types. The name field keys access to individual local grids when calling GetLocalGrids.
GetLocalGrids GetLocalGridsRequest GetLocalGridsResponse Request a set of local grids by type name.

log_annotation.proto

AddLogAnnotationRequest

The AddLogAnnotation request sends the information that should be added into the log.

Field Type Description
header RequestHeader Common request/response header.
annotations LogAnnotations The annotations to be aded into the log (can be text messages, blobs or robot operator messages).

AddLogAnnotationResponse

The AddLogAnnotation response message, which is empty except for any potential header errors/warnings.

Field Type Description
header ResponseHeader Common request/response header.

LogAnnotationLogBlob

A unit of binary data to be entered in a log.

Field Type Description
timestamp google.protobuf.Timestamp Timestamp of data in robot clock time.
channel string A general label for this blob. This is distinct from type_id, which identifies how the blob is to be parsed.
type_id string A description of the data's content and its encoding. This should be sufficient for deciding how to deserialize the data. For example, this could be the full name of a protobuf message type.
data bytes Raw data to be included as the blob log.

LogAnnotationOperatorMessage

An operator message to be added to the robot’s logs. These are notes especially intended to mark when logs should be preserved and reviewed to ensure that robot hardware and/or software is working as intended.

Field Type Description
message string String annotation message to add to the log.
timestamp google.protobuf.Timestamp The timestamp of the annotation. This must be in robot time.

LogAnnotationTextMessage

A text message to add to the robot’s logs. These could be internal text-log messages from a client for use in debugging, for example.

Field Type Description
message string String annotation message to add to the log.
timestamp google.protobuf.Timestamp The timestamp of the annotation. This must be in robot time.
service string The service responsible for the annotation. May be omitted.
level LogAnnotationTextMessage.Level Level of significance of the text message.
tag string Optional tag to identify from what code/module this message originated from.
filename string Optional source file name originating the log message.
line_number int32 Optional source file line number originating the log message.

LogAnnotations

A container for elements to be added to the robot’s logs.

Field Type Description
text_messages LogAnnotationTextMessage Text messages to be added to the log.
operator_messages LogAnnotationOperatorMessage Messages from the robot operator to be added to the log.
blob_data LogAnnotationLogBlob One or more binary blobs to add to the log.

LogAnnotationTextMessage.Level

Name Number Description
LEVEL_UNKNOWN 0 Invalid, do not use.
LEVEL_DEBUG 1 Events likely of interest only in a debugging context.
LEVEL_INFO 2 Informational message during normal operation.
LEVEL_WARN 3 Information about an unexpected but recoverable condition.
LEVEL_ERROR 4 Information about an operation which did not succeed.

log_annotation_service.proto

LogAnnotationService

LogAnnotationService allows adding information to the robot’s log files. This service is a mechanism for adding information to the robot’s log files.

Method Name Request Type Response Type Description
AddLogAnnotation AddLogAnnotationRequest AddLogAnnotationResponse Add the specified information to the robot's log files.

mission/mission.proto

AnswerQuestionRequest

Answer one of the outstanding questions.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
question_id int64 Identifier of the question being answered.
code int64 The answer_code from the Question, corresponding to the user's choice.

AnswerQuestionResponse

Response from the server after a client has answered one of its questions.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status AnswerQuestionResponse.Status The result of the AnswerQuestionRequest.

FailedNode

General message describing a node that has failed, for example as part of a PlayMission or LoadMission RPC.

Field Type Description
name string Human-readable name of this node, e.g. "Goto waypoint 1", or "Power On".
error string The reason why this node failed. May not be provided by all nodes.

GetInfoRequest

Request mission information. This covers information that stays static until a new mission is loaded.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetInfoResponse

Provides the currently loaded mission’s information.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
mission_info MissionInfo Description of the loaded mission's structure.

GetMissionRequest

For requesting the mission as it was loaded in LoadMission.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetMissionResponse

Responding with the mission as it was loaded in LoadMission.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
root Node Root node of the mission loaded. Unset if no mission has been loaded.
id int64 Mission ID as reported in MissionInfo. -1 if no mission has been loaded.

GetStateRequest

Get the state of the mission.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
history_upper_tick_bound google.protobuf.Int64Value Upper bound on the node state to retrieve, inclusive. Leave unset for the latest data.
history_lower_tick_bound int64 Tick counter for the lower bound of per-node state to retrieve.
history_past_ticks int64 Number of ticks to look into the past from the upper bound.

GetStateResponse

Response to a GetStateRequest.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
state State The requested mission state.

LoadMissionRequest

The LoadMission request specifies a root node for the mission that should be used.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
root Node Root node of the mission to load.
leases bosdyn.api.Lease Leases that will be needed to validate the mission.

LoadMissionResponse

The LoadMission response returns the mission info generated by the service if successfully loaded, and a status and other inforamtion if the request fails.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status LoadMissionResponse.Status Result of loading the mission.
lease_use_results bosdyn.api.LeaseUseResult Results from any leases that may have been used. As part of mission validation, some of the non-mission leases may have been used.
mission_info MissionInfo Provides the structure of the mission. Set when loading succeeds.
failed_nodes FailedNode If certain nodes failed compilation or validation, they will be reported back in this field.

MissionInfo

Static information about the mission. Used to interpret the mission state.

Field Type Description
id int64 Mission ID assigned by the server.
root NodeInfo The root node of the mission.

NodeInfo

Provides children and metadata of a single node within the mission.

Field Type Description
id int64 Unique to each node within the LOADED mission. Not guaranteed to be consistent between loads of the same mission. Used to identify the nodes in the State message.
name string Human-readable name of this node, e.g. "Goto waypoint 1", or "Power On".
user_data UserData Any UserData that was associated with this node.
children NodeInfo Info on all children of this node, if any are present.

PauseMissionRequest

The PauseMission request message will pause the mission that is currently executing, if there is one.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease Lease on the mission service.

PauseMissionResponse

The PauseMission response message will return the status of the request.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status PauseMissionResponse.Status Result of the pause request.
lease_use_result bosdyn.api.LeaseUseResult Result of the lease in the pause request.

PlayMissionRequest

A request to play the currently loaded mission for a fixed amount of time.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
pause_time google.protobuf.Timestamp Run the mission until this time. Pause the mission at that time if we have not received a new PlayMissionRequest. This ensures the mission stops relatively quickly if there is an unexpected client drop-out. Clients should regularly send PlayMissionRequests with a pause_time that reflects how often they expect to check in with the mission service.
leases bosdyn.api.Lease Leases that the mission will need, plus the lease on the mission service.
settings PlaySettings Settings active until the next PlayMission or RestartMission request.

PlayMissionResponse

The PlayMission response message will return the status of the play mission request.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status PlayMissionResponse.Status The result of the play request.
lease_use_results bosdyn.api.LeaseUseResult Results from any leases that may have been provided with the play request.

PlaySettings

“Global” settings to use while a mission is running. Some of these settings are not globally applicable. For example, the velocity_limit does not change the speed at which the robot poses the body.

Field Type Description
velocity_limit bosdyn.api.SE2VelocityLimit Velocity limits on the robot motion. Example use: limit velocity in "navigate to" nodes.

Question

A question posed by a Prompt node, or by the internal operation of another node.

Field Type Description
id int64 Identifier of this question, unique across all missions executing on a single host.
source string What's asking the question. Should be unique in the active mission.
text string The text of the question itself.
options Prompt.Option Options to choose from. Uses the submessage from the "prompt" node message.
for_autonomous_processing bool Set to true if this question was meant to be answered by some automated system, not a human. Clients should usually avoid generating a UI element to ask such a question.

RestartMissionRequest

A request to restart the currently loaded mission.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
pause_time google.protobuf.Timestamp Run the mission until this time. Pause the mission at that time if we have not received a new PlayMissionRequest. This ensures the mission stops relatively quickly if there is an unexpected client drop-out. Clients should regularly send PlayMissionRequests with a pause_time that reflects how often they expect to check in with the mission service.
leases bosdyn.api.Lease Leases that the mission will need, plus the lease on the mission service.
settings PlaySettings Settings active until the next PlayMission or RestartMission request.

RestartMissionResponse

The RestartMission response includes the status and any failed nodes for the request.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status RestartMissionResponse.Status The result of the restart request.
lease_use_results bosdyn.api.LeaseUseResult Results from any leases that may have been used. As part of mission validation, some of the non-mission leases may have been used.
failed_nodes FailedNode If certain nodes failed validation, they will be reported back in this field.

State

State of the mission service.

Field Type Description
questions Question What questions are outstanding?
answered_questions State.AnsweredQuestion History of questions that have been answered. The server will set some limit on the available history.
history State.NodeStatesAtTick Node states ordered from newest to oldest. history[0] will always be the data from this tick.
status State.Status Current status of the mission.
error string Describes the unexpected error encountered by the mission service. Only filled out if STATUS_ERROR is set.
tick_counter int64 The mission's tick counter when this state was generated. -1 indicates no mission has been started.
mission_id int64 The mission's ID. -1 indicates no mission has been loaded.

State.AnsweredQuestion

A question that has been answered already.

Field Type Description
question Question The question that this state information is related to.
accepted_answer_code int64 The answer that was provided.

State.NodeStatesAtTick

Field Type Description
tick_counter int64 The tick counter when this state was produced.
tick_start_timestamp google.protobuf.Timestamp Time at which this tick started, in host time basis.
node_states State.NodeStatesAtTick.NodeState At this tick, the state of every node that was ticked, in the order they were ticked.

State.NodeStatesAtTick.NodeState

Field Type Description
result Result The result of this node's tick.
error string May be set when the 'result' is RESULT_FAILURE or RESULT_ERROR, this describes why the node failed. Not all nodes will have an error explaining why they failed.
id int64 ID from NodeInfo.

AnswerQuestionResponse.Status

Possible results for answering a question.

Name Number Description
STATUS_UNKNOWN 0 Invalid; do not use.
STATUS_OK 1 Answer accepted.
STATUS_INVALID_QUESTION_ID 2 Question ID is not valid / unknown by the mission service.
STATUS_INVALID_CODE 3 Answer code is not applicable for the question indicated.
STATUS_ALREADY_ANSWERED 4 Question was already answered.

LoadMissionResponse.Status

Possible results of loading a mission.

Name Number Description
STATUS_UNKNOWN 0 Invalid status, do not use.
STATUS_OK 1 The mission was loaded successfully.
STATUS_COMPILE_ERROR 2 Load-time compilation failed. The mission was malformed.
STATUS_VALIDATE_ERROR 3 Load-time validation failed. Some part of the mission was unable to initialize.

PauseMissionResponse.Status

Possible results of a pause request.

Name Number Description
STATUS_UNKNOWN 0 Invalid status, do not use.
STATUS_OK 1 Mission is paused or finished running.
STATUS_NO_MISSION_PLAYING 2 No mission has started playing. NOT returned when two PauseMissionRequests are received back-to-back. In that case, you will get STATUS_OK.

PlayMissionResponse.Status

Possible results for a play request.

Name Number Description
STATUS_UNKNOWN 0 Invalid status, do not use.
STATUS_OK 1 Mission is playing, or the mission has already completed. Use GetStateResponse to tell the difference.
STATUS_NO_MISSION 2 Call LoadMission first.

RestartMissionResponse.Status

Possible results of requesting a restart.

Name Number Description
STATUS_UNKNOWN 0 Invalid status, do not use.
STATUS_OK 1 Mission has restarted.
STATUS_NO_MISSION 2 Call LoadMission first.
STATUS_VALIDATE_ERROR 3 Validation failed.

State.Status

Possible overall status states of the mission.

Name Number Description
STATUS_UNKNOWN 0 Invalid status, do not use.
STATUS_FAILURE 1 The mission has failed due to a node failure.
STATUS_RUNNING 2 The mission is still running.
STATUS_SUCCESS 3 The mission succeeded!
STATUS_PAUSED 4 Execution has been paused.
STATUS_ERROR 5 The mission service itself encountered an unexpected error, outside of a node failing.
STATUS_NONE 6 No mission has been loaded.

mission/mission_service.proto

MissionService

The MissionService can be used to specify high level autonomous behaviors for Spot using behavior trees.

Method Name Request Type Response Type Description
LoadMission LoadMissionRequest LoadMissionResponse Load a mission to run later.
PlayMission PlayMissionRequest PlayMissionResponse Start executing a loaded mission. Will not restart a mission that has run to completion. Use RestartMission to do that.
PauseMission PauseMissionRequest PauseMissionResponse Pause mission execution.
RestartMission RestartMissionRequest RestartMissionResponse Start executing a loaded mission from the beginning. Does not need to be called after LoadMission.
GetState GetStateRequest GetStateResponse Get the state of the mission.
GetInfo GetInfoRequest GetInfoResponse Get static information regarding the mission. Used to interpret mission state.
GetMission GetMissionRequest GetMissionResponse Download the mission as it was uploaded to the service.
AnswerQuestion AnswerQuestionRequest AnswerQuestionResponse Specify an answer to the question asked by the mission.

mission/nodes.proto

BosdynGraphNavLocalize

Tell GraphNav to re-localize the robot to the nearest visible fiducial.

Field Type Description
service_name string Name of the service to use.
host string Host machine the service is running on.

BosdynGraphNavState

Get GraphNav state from the robot and save it to the blackboard.

Field Type Description
service_name string Name of the service to use.
host string Host machine the service is running on.
child Node Child node. Children will have access to the state gathered by this node.
state_name string Name of the bosdyn.api.GetLocalizationStateResponse object in the blackboard. For example, if this is set to "nav", children can look up "nav.localization.waypoint_id" in the blackboard to get the waypoint the robot is localized to.

BosdynNavigateTo

Tell the robot to navigate to a waypoint.

Field Type Description
service_name string Name of the service to use.
host string Host machine the service is running on.
destination_waypoint_id string ID of the waypoint to go to.
route_gen_params bosdyn.api.graph_nav.RouteGenParams Preferences on how to pick the route.
travel_params bosdyn.api.graph_nav.TravelParams Parameters that define how to traverse and end the route.

BosdynPowerRequest

Make a robot power request

Field Type Description
service_name string Name of the service to use.
host string Host machine the service is running on.
request bosdyn.api.PowerCommandRequest.Request The request to make. See the PowerCommandRequest documentation for details.

BosdynRobotCommand

Execute a RobotCommand. These nodes will “succeed” once a feedback response is received indicating success. Any commands that require an “end time” will have that information set based on the end time of the mission.

Field Type Description
service_name string Name of the service to use.
host string Host machine the directory is running on.
command bosdyn.api.RobotCommand The command to execute. See the RobotCommand documentation for details.

BosdynRobotState

Get state from the robot.

Field Type Description
service_name string Name of the service to use.
host string Host machine the service is running on.
child Node Child node. Children will have access to the state gathered by this node.
state_name string Name of the bosdyn.api.RobotState object in the blackboard. For example, if this is set to "robot", children can look up "robot.power_state.motor_power_state" in the blackboard.

Condition

Checks a simple comparison statement.

Field Type Description
lhs Condition.Operand Left-hand side of the comparison.
rhs Condition.Operand Right-hand side of the comparison.
operation Condition.Compare Comparison operator to compare lhs and rhs.

Condition.Operand

Options for where to retrieve values from.

Field Type Description
var VariableDeclaration Reference an existing variable.
const ConstantValue Use a constant value.

ConstantResult

Just returns a constant when calling tick().

Field Type Description
result Result This result is always returned when calling tick().

DefineBlackboard

Defines new blackboard variables within the scope of the child. Shadows blackboard variables in the parent scope.

Field Type Description
blackboard_variables KeyValue The list of variables that should be defined for this subtree, with initial values.
child Node The blackboard variables will only persist in the subtree defined by this child node. The child's tick() will be called on the child until it returns either SUCCESS or FAILURE.

ForDuration

Run this child for a maximum amount of mission execution time. Will exit with child’s status if the child finishes early, FAILURE if the child remains in RUNNING state for too long.

Field Type Description
duration google.protobuf.Duration Maximum duration of mission execution time.
child Node Child to execute for the duration.

Node

Wrapper for a mission node. Contains the basics common to all mission nodes. Specifics of what the node does are contained in the “impl” field.

Field Type Description
name string Human-readable name of this node, e.g. "Goto waypoint 1", or "Power On".
user_data UserData Collection of user data associated with this node.
reference_id string Reference identifier of this node. Set iff another node references this one.
impl google.protobuf.Any Implementation of this node. For example, this may be a Sequence.
node_reference string Unique identifier of another node. If this is filled out, rather than the "impl", then the referenced node will be used in place of this one.
parameter_values KeyValue Defines parameters, used by this node or its children. The "key" in KeyValue is the name of the parameter being defined. The value can be a constant or another parameter value.
overrides KeyValue Overwrites a protobuf field in this node's implementation. The "key" in KeyValue is the name of the field to override. The value to write can be sourced from a constant, or a parameter value.
parameters VariableDeclaration Declares parameters needed at compile time by this node, or children of this node. This is a way for a node to communicate what parameters its implementation and/or children require, without unpacking the entire subtree.

Prompt

Prompt the world at large to answer a question. This node represents a request for information from ANY listeners that may be out there.

Field Type Description
always_reprompt bool Should we always re-prompt when this node is started? If false, this node will only ever prompt if it is started and its question is unanswered. This may be used, for example, to ask the user to check the robot after any self-right. If true, this node will prompt whenever it is started. This may be used, for example, to tell the user to perform some one-time action, like open a door for the robot.
text string The text of the question itself.
source string Metadata describing the source of the question. The answer will be written into the state blackboard with this as the variable name.
options Prompt.Option The set of options that can be chosen for this prompt.
child Node Child node, run after the prompt has been responded to. Children will have access to the answer code provided by the response.
for_autonomous_processing bool Hint that Question posed by this Prompt is meant to be answered by some automated system. See the Question message for details.

Prompt.Option

Data about the options to choose from.

Field Type Description
text string Text associated with this option. Should be displayed to the user.
answer_code int64 Numeric code corresponding to this option. Passed as part of the answer.

RemoteGrpc

Call out to another system using the RemoteMission service.

Field Type Description
host string Host that is running the directory server. Usually, this is just the robot.
service_name string Name of the service in the directory.
timeout float Timeout of the RPC. If the timeout is exceeded, the node will indicate FAILURE.
lease_resources string Resources that we will need leases on.
inputs KeyValue The list of variables the remote host should receive. Variables given can be available at either run-time or compile-time. The "key" in KeyValue is the name of the variable as used by the remote system.

Repeat

Repeat a child node.

Field Type Description
max_starts int32 Start the child node exactly this many times. Note that a value of 1 makes the Repeat node a no-op.
child Node Child to repeat max_starts times.

Retry

Retry a child node until it succeeds, or exceeds a number of attempts.

Field Type Description
max_attempts int32 Only allow this many attempts. Note that a value of 1 makes this Retry node a no-op.
child Node Child to retry up to max_attempts.

Selector

Run all children in order until a child succeeds.

Field Type Description
always_restart bool Forces the execution to always begin with the first child. If false, and the Selector ran last tick, it will continue with the node it was ticking.
children Node List of all children to iterate through.

Sequence

Run all children in order until a child fails.

Field Type Description
always_restart bool Forces the execution to always begin with the first child. If false, and the Sequence ran last tick, it will continue with the node it was ticking.
children Node List of all children to iterate through.

SetBlackboard

Sets existing blackboard variables within this scope to specific values, returning SUCCESS.

Field Type Description
blackboard_variables KeyValue The key of the KeyValue is the name of the blackboard variable. The value will be dereferenced and converted into a value type at runtime inside this node's tick function. For example, if the value is a runtime variable, that variable will be evaluated at tick time, and then stored into the blackboard. If the value is another blackboard variable, that blackboard variable's value will be copied into the variable specified by the key.

SimpleParallel

Run two child nodes together, returning the primary child’s result when it completes.

Field Type Description
primary Node Primary node, whose completion will end the execution of SimpleParallel.
secondary Node Secondary node, which will be ticked as long as the primary is still running.

Sleep

When started, begins a sleep timer for X seconds. Returns “success” after the timer elapses, “running” otherwise.

Field Type Description
seconds float Number of seconds to sleep for.
restart_after_stop bool If this node is stopped, should it restart the timer?

SpotCamStoreMedia

Store media using the Spot CAM.

Field Type Description
service_name string Name of the service to use.
host string Host machine of the directory server that the Spot CAM registered with.
camera bosdyn.api.spot_cam.Camera The rest of the fields are from bosdyn.api.spot_cam.logging.StoreRequest, see that message for details.
type bosdyn.api.spot_cam.Logpoint.RecordType What type of media should be stored from this action.
tag string Extra metadata to store alongside the captured media.

Condition.Compare

Comparison operator.

Name Number Description
COMPARE_UNKNOWN 0 Invalid, do not use.
COMPARE_EQ 1 Equal.
COMPARE_NE 2 Not equal.
COMPARE_LT 3 Less than.
COMPARE_GT 4 Greater than.
COMPARE_LE 5 Less than or equal.
COMPARE_GE 6 Greater than or equal.

mission/remote.proto

EstablishSessionRequest

Information to initialize a session to the remote service for a particular mission node.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
leases bosdyn.api.Lease All leases that the remote service may need.
inputs VariableDeclaration Use this to provide other data (e.g. from the blackboard). The RemoteGrpc node will provide the name of the node automatically.

EstablishSessionResponse

Provide the id to use for the particular mission node to tick this remote service.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status EstablishSessionResponse.Status Result of this establish session request.
session_id string On success, contains an ID for this session.
missing_lease_resources string Need to provide leases on these resources.
lease_use_results bosdyn.api.LeaseUseResult Details about how any leases were used. Allowed to be empty, if leases were not actually used.
missing_inputs VariableDeclaration The inputs required by the contacted node that were not mentioned in the request.

StopRequest

Used to stop a node that was previously ticked, so that it knows that the next Tick represents a restart rather than a continuation.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
session_id string Session ID as returned by the EstablishSessionResponse. Used to guarantee coherence between a single client and a servicer.

StopResponse

Results of attempting to stop a remote node.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status StopResponse.Status Result of the stop request.

TeardownSessionRequest

End the session originally established by an EstablishSessionRequest.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
session_id string Session ID as returned by the EstablishSessionResponse. Used to guarantee coherence between a single client and a servicer.

TeardownSessionResponse

Results of ending a session.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status TeardownSessionResponse.Status The result of a TeardownSessionRequest.

TickRequest

Request that the remote tick itself for a particular node in the mission.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
session_id string Session ID as returned by the EstablishSessionResponse. Used to guarantee coherence between a single client and a servicer.
leases bosdyn.api.Lease All leases that the remote service may need.
inputs KeyValue Inputs provided to the servicer.

TickResponse

Response with the results of the tick. Remote services should strive to return quickly, even if only returning RUNNING.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status TickResponse.Status Result of the current tick.
missing_lease_resources string Need to provide leases on these resources.
lease_use_results bosdyn.api.LeaseUseResult Details about how any leases were used. Allowed to be empty, if leases were not actually used.
missing_inputs VariableDeclaration Filled out when status is STATUS_MISSING_INPUTS, indicating what inputs were not in the request.
error_message string If you need to report other error details, you can use this field.

EstablishSessionResponse.Status

Possible results of establishing a session.

Name Number Description
STATUS_UNKNOWN 0 Status unknown/unset.
STATUS_OK 1 Provided inputs / outputs are compatible.
STATUS_MISSING_LEASES 2 Remote service needs leases on additional resources. If set, the missing_lease_resources field should contain the resources needed but not provided.
STATUS_MISSING_INPUTS 3 Remote service needs additional inputs.

StopResponse.Status

Possible results for a StopRequest.

Name Number Description
STATUS_UNKNOWN 0 Status unknown/unset.
STATUS_OK 1 Service stopped.
STATUS_INVALID_SESSION_ID 2 The request provided an invalid session ID.

TeardownSessionResponse.Status

Possible results of ending a session.

Name Number Description
STATUS_UNKNOWN 0 Status unknown/unset.
STATUS_OK 1 Session was torn down -- servicer has probably wiped all associated data / state.
STATUS_INVALID_SESSION_ID 2 The request provided an invalid session ID. This may mean the session was already torn down.

TickResponse.Status

Possible results from the node. The FAILURE, RUNNING, and SUCCESS statuses map to the behavior tree terms, all others indicate an error in the TickRequest.

Name Number Description
STATUS_UNKNOWN 0 Invalid; do not use.
STATUS_FAILURE 1 Node completed but failed.
STATUS_RUNNING 2 Node is processing and may finish in a future tick.
STATUS_SUCCESS 3 Node completed and succeeded.
STATUS_INVALID_SESSION_ID 4 The request provided an invalid session ID.
STATUS_MISSING_LEASES 5 The request was missing required leases.
STATUS_MISSING_INPUTS 6 The request was missing required inputs.

mission/remote_service.proto

RemoteMissionService

Interface for mission callbacks. Mission RemoteGrpc nodes will act as clients to this service type, calling out to this service when loaded, ticked, or unloaded.

Method Name Request Type Response Type Description
EstablishSession EstablishSessionRequest EstablishSessionResponse Call this once at mission load time, once for each node that references this remote service.
Tick TickRequest TickResponse Call this every time the RemoteGrpc node is ticked.
Stop StopRequest StopResponse Call this every time the RemoteGrpc node WAS ticked in the previous cycle, but was NOT ticked in this cycle. Signals that the next tick will be a restart, rather than a continuation.
TeardownSession TeardownSessionRequest TeardownSessionResponse Tells the service it can forget any data associated with the given session ID. Should be called once for every EstablishSession call.

mission/util.proto

ConstantValue

A constant value. Corresponds to the VariableDeclaration Type enum.

Field Type Description
float_value double
string_value string
int_value int64
bool_value bool
msg_value google.protobuf.Any

KeyValue

Key/Value pair, used in other messages.

Field Type Description
key string
value Value

UserData

Data a user can associate with a node.

Field Type Description
id string Identifier. Enables matching the Node uploaded to the MissionService with the NodeInfo downloaded from the MissionService.
bytestring bytes Arbitrary data. We recommend keeping it small, to avoid bloating the size of the mission.

Value

A value of a run-time or compile-time variable.

Field Type Description
constant ConstantValue A constant value.
runtime_var VariableDeclaration Look up a variable provided at run-time.
parameter VariableDeclaration Look up a Node Parameter.

VariableDeclaration

Declaration of a run-time or compile-time variable.

Field Type Description
name string Name of the variable, to be used as the key in KeyValue pairs.
type VariableDeclaration.Type Type that this variable is expected to have. Used to verify assignments and comparisons.

Result

Results from executing / ticking / running a single node.

Name Number Description
RESULT_UNKNOWN 0 Invalid, should not be used.
RESULT_FAILURE 1 The node completed running, but failed.
RESULT_RUNNING 2 The node is still in process and has not completed.
RESULT_SUCCESS 3 The node completed, and succeeded.
RESULT_ERROR 4 The node encountered an operational error while trying to execute.

VariableDeclaration.Type

Supported types for blackboard or parameter values.

Name Number Description
TYPE_UNKNOWN 0
TYPE_FLOAT 1
TYPE_STRING 2
TYPE_INT 3
TYPE_BOOL 4
TYPE_MESSAGE 5

mobility_command.proto

MobilityCommand

The robot command message to specify a basic command that moves the robot.

MobilityCommand.Feedback

The feedback for the mobility command that will provide information on the progress of the robot command.

Field Type Description
se2_trajectory_feedback SE2TrajectoryCommand.Feedback Feedback for the trajectory command.
se2_velocity_feedback SE2VelocityCommand.Feedback Feedback for the velocity command.
sit_feedback SitCommand.Feedback Feedback for the sit command.
stand_feedback StandCommand.Feedback Feedback for the stand command.

MobilityCommand.Request

The mobility request must be one of the basic command primitives.

Field Type Description
se2_trajectory_request SE2TrajectoryCommand.Request Command to move the robot along a trajectory.
se2_velocity_request SE2VelocityCommand.Request Command to move the robot at a fixed velocity.
sit_request SitCommand.Request Command to sit the robot down.
stand_request StandCommand.Request Command to stand up the robot.
params google.protobuf.Any Robot specific command parameters.

parameter.proto

Parameter

A generic parameter message used by the robot state service to describe different, parameterized aspects of the robot.

Field Type Description
label string Name of parameter.
units string Units of parameter value.
int_value int64 Value of a countable measure.
float_value double Value of a continuous measure.
timestamp google.protobuf.Timestamp A point in time.
duration google.protobuf.Duration A time duration.
string_value string Value as a string.
bool_value bool Value as true/false.
notes string Description of the parameter or its value.

payload.proto

JointLimits

JointLimits contain hip joint angles where limb to payload collisions occur.

Field Type Description
label string Label identifying the respective limb to which these apply [fr,fl,hr,hl]
hy float (hy, hx) coordinates outlining the hip joint limits where collisions occur between robot hip and payload. Paired vectors must be of equal length. Angles are measured with actual contact. Appropriate margin will be provided in software. Radians. Left legs must have hx > 0. Right legs must have hx < 0.
hx float All legs must have hy > 1.3.

ListPayloadsRequest

The ListPayloads request message sent to the robot to get all known payloads.

Field Type Description
header RequestHeader Common request header.

ListPayloadsResponse

The ListPayloads response message returns all payloads registered in the robot’s directory.

Field Type Description
header ResponseHeader Common response header.
payloads Payload The returned list of payloads registered in the directory.

MomentOfIntertia

Structure describing the moment of intertia of a body. The xx, yy, zz fields are the diagonal of the MOI tensor, and the xy, xz, and yz fields are the off diagonal terms.

Field Type Description
xx float
yy float
zz float
xy float
xz float
yz float

Payload

A Payload describes a single payload installed on the Spot platform. It includes all external information necessary to represent the payload to the user as a single record.

Field Type Description
GUID string A unique id provided by the payload or auto-generated by the website.
name string A human readable name describing this payload. It is provided by the payload as part of the payload announcement system.
description string A human-readable description string providing more context as to the function of this payload. It is displayed in UIs.
label_prefix string A list of labels used to indicate what type of payload this is.
is_authorized bool Set true once the payload is authorized by the administrator in the payload webpage. Must be set to false at registration time.
is_enabled bool Set true if the payload is attached to the robot. Must be set to false at registration time.
is_noncompute_payload bool Set true for payloads registered without their own computers. These records are all manually entered.
version SoftwareVersion Payload version details.
body_tform_payload SE3Pose The pose of the payload relative to the body frame.
mount_tform_payload SE3Pose The pose of the payload relative to the mount frame.
mass_volume_properties PayloadMassVolumeProperties The mass and volume properties of the payload.
preset_configurations PayloadPreset A list of possible physical configurations for the payload.

PayloadMassVolumeProperties

PayloadMassVolumeProperties contain mass and volume information for the payload in the format that the user interacts with it. It is transmitted to the control and perception systems and processed there to inform those systems.

Field Type Description
total_mass float Total mass of payload in kg.
com_pos_rt_payload Vec3 Position of the center of mass of the payload in the payload frame. Meters.
moi_tensor MomentOfIntertia The moment of inertia of the payload, represented about the payload center of mass, in the payload frame. Units in [kg*m^2].
bounding_box Box3WithFrame Zero or more bounding boxes indicating the occupied volume of the payload. These boxes must be represented in the payload frame by specifying Must have Box3WithFrame.frame_name == "payload".
joint_limits JointLimits Joint limits defining limits to range of motion of the hips of the robot, in order to prevent collisions with the payload. This field is optional and is only recommended for advanced development purposes.

PayloadPreset

The physical configurations for the payload.

Field Type Description
preset_name string A human readable name describing this configuration. It is displayed in the admin console, but will not overwrite the top level payload name.
description string A human-readable description providing context on this configuration. It is displayed in the admin console.
mount_tform_payload SE3Pose The pose of the payload relative to the body frame.
mass_volume_properties PayloadMassVolumeProperties The mass and volume properties of the payload.
label_prefix string A list of labels used to indicate what type of payload this is.

payload_registration.proto

GetPayloadAuthTokenRequest

Request a user token from the robot A token will only be provided after the registered payload has been enabled by an admin. The returned user token will have limited access to the services necessary for a simple payload.

Field Type Description
header RequestHeader Common request header.
payload_guid string The GUID to identify which payload to get the auth token for.
payload_secret string The payload secret for the specified payload.

GetPayloadAuthTokenResponse

The GetPayloadAuthToken response message that returns the token for the payload.

Field Type Description
header ResponseHeader Common response header.
status GetPayloadAuthTokenResponse.Status Return status for the request.
token string A limited-access user token provided on successful payload registration

RegisterPayloadRequest

The RegisterPayload request message contains the payload information and secret to be able to register it to the directory.

Field Type Description
header RequestHeader Common request header.
payload Payload The payload to register, which must have, at minimum, GUID specified correctly. The admin console can be used to verify that the payload definition is valid after registration.
payload_secret string A private string provided by the payload to verify identity for auth.

RegisterPayloadResponse

The RegisterPayload response message contains the status of whether the payload was successfully registered to the directory.

Field Type Description
header ResponseHeader Common response header.
status RegisterPayloadResponse.Status Return status for the request.

UpdatePayloadVersionRequest

Update the payload definition of the payload with matching GUID. The existing payload must have a secret set and the request must provide the secret for access. GUID, is_authorized, and is_enabled fields are immutable and cannot be updated.

Field Type Description
header RequestHeader Common request header.
payload_guid string The GUID of the payload to be updated.
payload_secret string The payload secret for the specified payload.
updated_version SoftwareVersion The new software version that the payload is being updated to.

UpdatePayloadVersionResponse

The UpdatePayloadVersion response message contains the status of whether the update was successful.

Field Type Description
header ResponseHeader Common response header.
status UpdatePayloadVersionResponse.Status Return status for the request.

GetPayloadAuthTokenResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal PayloadRegistrationService issue has happened if UNKNOWN is set.
STATUS_OK 1 Success. The token is available.
STATUS_INVALID_CREDENTIALS 2 GetPayloadAuthToken failed because the paylod guid & secret do not match any registered payloads.
STATUS_PAYLOAD_NOT_AUTHORIZED 3 GetPayloadAuthToken failed because the paylod has not been authorized by an admin.

RegisterPayloadResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal PayloadRegistrationService issue has happened if UNKNOWN is set.
STATUS_OK 1 Success. The new service record is available.
STATUS_ALREADY_EXISTS 2 RegisterPayload failed because a payload with this GUID already exists.

UpdatePayloadVersionResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal PayloadRegistrationService issue has happened if UNKNOWN is set.
STATUS_OK 1 Success. The payload version has been updated.
STATUS_DOES_NOT_EXIST 2 UpdatePayload failed because a payload with this GUID does not yet exist.
STATUS_INVALID_CREDENTIALS 3 UpdatePayload failed because the paylod guid & secret do not match any registered payloads.

payload_registration_service.proto

PayloadRegistrationService

This service provides a way to register new payloads.

Method Name Request Type Response Type Description
RegisterPayload RegisterPayloadRequest RegisterPayloadResponse Register a payload with the directory.
UpdatePayloadVersion UpdatePayloadVersionRequest UpdatePayloadVersionResponse Update the version for the registered payload.
GetPayloadAuthToken GetPayloadAuthTokenRequest GetPayloadAuthTokenResponse Get the authentication token information associated with a given payload.

payload_service.proto

PayloadService

This service provides a way to query for the currently-registered payloads.

Method Name Request Type Response Type Description
ListPayloads ListPayloadsRequest ListPayloadsResponse List all payloads the robot knows about.

point_cloud.proto

GetPointCloudRequest

The GetPointCloud request message to ask a specific point cloud service for data.

Field Type Description
header RequestHeader Common request header.

GetPointCloudResponse

The GetPointCloud response message which returns any point cloud data associated with that service.

Field Type Description
header ResponseHeader Common response header.
status GetPointCloudResponse.Status Return status for the request.
point_cloud PointCloud The current point cloud from the service.

PointCloud

Data from a point-cloud producing sensor or process.

Field Type Description
source PointCloudSource The sensor or process that produced the point cloud.
num_points int32 The number of points in the point cloud.
encoding PointCloud.Encoding Representation of the underlying point cloud data.
encoding_parameters PointCloud.EncodingParameters Constants needed to decode the point cloud.
data bytes Raw byte data representing the points.

PointCloud.EncodingParameters

Parameters needed to decode the point cloud.

Field Type Description
scale_factor int32 Used in the remapping process from bytes to metric units. (unitless)
max_x double In XYZ_4SC and XYZ_5SC, the point cloud is assumed to lie inside a box centered in the data frame. max_x, max_y, max_z are half the dimensions of that box. These dimensions should be assumed to be meters.
max_y double max_y is half the dimensions of the assumed box (for XYZ_4SC and XYZ_5SC). These dimensions should be assumed to be meters.
max_z double max_z is half the dimensions of the assumed box (for XYZ_4SC and XYZ_5SC). These dimensions should be assumed to be meters.
remapping_constant double Used in the remapping process from bytes to metric units. (unitless) For XYZ_4SC and XYZ_5C, this should equal 127.
bytes_per_point int32 Number of bytes in each point in this encoding.

PointCloudSource

Information about a sensor or process that produces point clouds.

Field Type Description
name string The name of the point cloud source. This is intended to be unique accross all point cloud sources, and should be human readable.
frame_name_sensor string The frame name of the sensor. The transformation from vision_tform_sensor can be computed by traversing the tree in the FrameTreeSnapshot.
acquisition_time google.protobuf.Timestamp Time that the data was produced on the sensor in the robot's clock.
transforms_snapshot FrameTreeSnapshot A tree-based collection of transformations, which will include the transformations to the point cloud data frame and the point cloud sensor frame.

GetPointCloudResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used. An internal PointCloudService issue has happened if UNKNOWN is set. None of the other fields are filled out.
STATUS_OK 1 Call succeeded at filling out all the fields.
STATUS_SOURCE_DATA_ERROR 2 Failed to fill out PointCloudSource. All the other fields are not filled out.
STATUS_POINT_CLOUD_DATA_ERROR 3 There was a problem with the point cloud data. Only the PointCloudSource is filled out.

PointCloud.Encoding

Point clouds may be encoded in different ways to preserve bandwidth or disk space.

Name Number Description
ENCODING_UNKNOWN 0 The point cloud has an unknown encoding.
ENCODING_XYZ_32F 1 Each point is x,y,z float32 value (12 bytes, little-endian) stored sequentially. This allows the point cloud to be expressed in any range and resolution represented by floating point numbers, but the point cloud will be larger than if one of the other encodings is used.
ENCODING_XYZ_4SC 2 Each point is 3 signed int8s plus an extra shared signed int8s (4 byte). byte layout: [..., p1_x, p1_y, p1_z, x, ...] Each coordinate is mapped to a value between -1 and +1 (corresponding to a minimum and maximum range). The resulting point is: P = remap(p1 * f + p2, c * f, m) Where: p1 = the highest byte in each dimension of the point. p2 = a vector of "extra" bytes converted to metric units. = [mod (x, f), mod(x/f, f), mod(x/(f^2), f)] - f/2 x = the "extra" byte for each point. f = An integer scale factor. m = [max_x, max_y, max_z], the point cloud max bounds in meters. c = a remapping constant. And: remap(a, b, c) = (a + b)/(2 * b) - c Point clouds use 1/3 the memory of XYZ_32F, but have limits on resolution and range. Points must not lie outside of the box of size [-m, m]. Within that box, the resolution of the point cloud will depend on the encoding parameters. For example if m = [10, 10, 10], and f = 5 with c = 127 the resolution is approximately 1.5 cm per point.
ENCODING_XYZ_5SC 3 Each point is 3 signed int8s plus two extra shared signed int8s (5 byte). The encoding is the same as XYZ_4SC, except the "extra" value x is a 16 bit integer. This encoding has roughly double the resolution of XYZ_4SC, but takes up an additional byte for each point.

power.proto

PowerCommandFeedbackRequest

The PowerCommandFeedback request message, which can get the feedback for a specific power command id number.

Field Type Description
header RequestHeader Common request header.
power_command_id uint32 Unique identifier for the command of which feedback is desired.

PowerCommandFeedbackResponse

The PowerCommandFeedback response message, which contains the progress of the power command.

Field Type Description
header ResponseHeader Common response header.
status PowerCommandStatus Current status of specified command.

PowerCommandRequest

The PowerCommand request which specifies a change in the robot’s motor power.

Field Type Description
header RequestHeader Common request header.
lease Lease The Lease to show ownership of the robot.
request PowerCommandRequest.Request

PowerCommandResponse

The PowerCommand response message which contains a unique identifier that can be used to get feedback on the progress of a power command from the power service.

Field Type Description
header ResponseHeader Common response header.
lease_use_result LeaseUseResult Details about how the lease was used.
status PowerCommandStatus Current feedback of specified command.
power_command_id uint32 Unique identifier for the command, If empty, was not accepted.
license_status LicenseInfo.Status License check status

PowerCommandRequest.Request

Commands for the robot to execute.

Name Number Description
REQUEST_UNKNOWN 0 Invalid request; do not use.
REQUEST_OFF 1 Cut power to motors immediately.
REQUEST_ON 2 Turn on power to the robot.

PowerCommandStatus

Feedback on the current state of a power command on the robot.

Name Number Description
STATUS_UNKNOWN 0 Status is not specified.
STATUS_IN_PROGRESS 1 Power command is executing.
STATUS_SUCCESS 2 Power command succeeded.
STATUS_SHORE_POWER_CONNECTED 3 ERROR: Robot cannot be powered on while on wall power.
STATUS_BATTERY_MISSING 4 ERROR: Battery not inserted into robot.
STATUS_COMMAND_IN_PROGRESS 5 ERROR: Power command cant be overwritten.
STATUS_ESTOPPED 6 ERROR: Cannot power on while estopped. A robot may have multiple estops. Inspect EStopState for additional info.
STATUS_FAULTED 7 ERROR: Cannot power due to a fault.Inspect FaultState for more info.
STATUS_INTERNAL_ERROR 8 ERROR: Internal error occurred, maybe clear-able by issuing a power off command.
STATUS_LICENSE_ERROR 9 ERROR: License check failed. Check license_status field for details.

power_service.proto

PowerService

The power service for the robot that can power on/off the robot’s motors.

Method Name Request Type Response Type Description
PowerCommand PowerCommandRequest PowerCommandResponse Starts a power command on the robot. A robot can only accept one power command at once. Power commands, are not interruptible. Once a command is issued, it must complete before another command can be issued.
PowerCommandFeedback PowerCommandFeedbackRequest PowerCommandFeedbackResponse Check the status of a power command.

robot_command.proto

ClearBehaviorFaultRequest

A ClearBehaviorFault request message has the associated behavior fault id to be cleared.

Field Type Description
header RequestHeader Common request header.
lease Lease The Lease to show ownership of the robot.
behavior_fault_id uint32 Unique identifier for the error

ClearBehaviorFaultResponse

A ClearBehaviorFault response message has status indicating whether the service cleared the fault or not.

Field Type Description
header ResponseHeader Common response header.
lease_use_result LeaseUseResult Details about how the lease was used.
status ClearBehaviorFaultResponse.Status Return status for a request.

RobotCommand

A command for a robot to execute. The server decides if a set of commands is valid for a given robot and configuration.

Field Type Description
full_body_command FullBodyCommand.Request Commands which require control of entire robot.
mobility_command MobilityCommand.Request A mobility command for a robot to execute.

RobotCommandFeedback

Command specific feedback. Distance to goal, estimated time remaining, probability of success, etc. Note that the feedback should directly mirror the command request.

Field Type Description
full_body_feedback FullBodyCommand.Feedback Commands which require control of entire robot.
mobility_feedback MobilityCommand.Feedback Command to control mobility system of a robot.

RobotCommandFeedbackRequest

The RobotCommandFeedback request message, which can get the feedback for a specific robot command id number.

Field Type Description
header RequestHeader Common request header.
robot_command_id uint32 Unique identifier for the command, provided by StartRequest.

RobotCommandFeedbackResponse

The RobotCommandFeedback response message, which contains the progress of the robot command.

Field Type Description
header ResponseHeader Common response header.
status RobotCommandFeedbackResponse.Status General status whether or not command is still processing.
message string Human-readable status message. Not for programmatic analysis.
feedback RobotCommandFeedback Command specific feedback.

RobotCommandRequest

A RobotCommand request message includes the lease and command as well as a clock identifier to ensure timesync when issuing commands with a fixed length.

Field Type Description
header RequestHeader Common request header.
lease Lease The Lease to show ownership of the robot.
command RobotCommand A command for a robot to execute. A command can be comprised of several subcommands.
clock_identifier string Identifier provided by the time sync service to verify time sync between robot and client.

RobotCommandResponse

The RobotCommand response message contains a robot command id that can be used to poll the robot command service for feedback on the state of the command.

Field Type Description
header ResponseHeader Common response header.
lease_use_result LeaseUseResult Details about how the lease was used.
status RobotCommandResponse.Status Return status for a request.
message string Human-readable error description. Not for programmatic analysis.
robot_command_id uint32 Unique identifier for the command, If empty, command was not accepted.

ClearBehaviorFaultResponse.Status

Name Number Description
STATUS_UNKNOWN 0 An unknown / unexpected error occurred.
STATUS_CLEARED 1 The BehaviorFault has been cleared.
STATUS_NOT_CLEARED 2 The BehaviorFault could not be cleared.

RobotCommandFeedbackResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Behavior execution is in an unknown / unexpected state.
STATUS_PROCESSING 1 The robot is actively working on the command
STATUS_COMMAND_OVERRIDDEN 2 The command was replaced by a new command
STATUS_COMMAND_TIMED_OUT 3 The command expired
STATUS_ROBOT_FROZEN 4 The robot is in an unsafe state, and will only respond to known safe commands.

RobotCommandResponse.Status

Name Number Description
STATUS_UNKNOWN 0 An unknown / unexpected error occurred.
STATUS_OK 1 Request was accepted.
STATUS_INVALID_REQUEST 2 [Programming Error] Request was invalid / malformed in some way.
STATUS_UNSUPPORTED 3 [Programming Error] The robot does not understand this command.
STATUS_NO_TIMESYNC 4 [Timesync Error] Client has not done timesync with robot.
STATUS_EXPIRED 5 [Timesync Error] The command was received after its end_time had already passed.
STATUS_TOO_DISTANT 6 [Timesync Error] The command end time was too far in the future.
STATUS_NOT_POWERED_ON 7 Robot state errors.

[Hardware Error] The robot must be powered on to accept a command. | | STATUS_BEHAVIOR_FAULT | 9 | The robot must not have behavior faults. | | STATUS_UNKNOWN_FRAME | 8 | [Frame Error] The frame_name for a command was not a known frame. |

robot_command_service.proto

RobotCommandService

The robot command service allows a client application to control and move the robot.

Method Name Request Type Response Type Description
RobotCommand RobotCommandRequest RobotCommandResponse Starts a behavior command on the robot. Issuing a new command overrides the active command. Each command is issued a UID for feedback retrieval.
RobotCommandFeedback RobotCommandFeedbackRequest RobotCommandFeedbackResponse A client queries this RPC to determine a robot's progress towards completion of a command. This updates the client with metrics like "distance to goal." The client should use this feedback to determine whether the current command has succeeeded or failed, and thus send the next command.
ClearBehaviorFault ClearBehaviorFaultRequest ClearBehaviorFaultResponse Clear robot behavior fault.

robot_id.proto

RobotId

Robot identity information, which should be static while robot is powered-on.

Field Type Description
serial_number string A unique string identifier for the particular robot.
species string Type of robot. E.g., 'spot'.
version string Robot version/platform.
software_release RobotSoftwareRelease Version information about software running on the robot.
nickname string Optional, customer-supplied nickname.
computer_serial_number string Computer Serial Number. Unlike serial_number, which identifies a complete robot, the computer_serial_number identifies the computer hardware used in the robot.

RobotIdRequest

The RobotId request message sent to a robot to learn it’s basic identification information.

Field Type Description
header RequestHeader Common request/response header.

RobotIdResponse

The RobotId response message, including the ID information for a robot.

Field Type Description
header ResponseHeader Common request/response header.
robot_id RobotId The requested RobotId information.

RobotSoftwareRelease

Description of the software release currently running on the robot.

Field Type Description
version SoftwareVersion The software version, e.g., 2.0.1
name string The name of the robot, e.g., '20190601'
type string Kind of software release.
changeset_date google.protobuf.Timestamp Timestamp of the changeset.
changeset string Changeset hash.
api_version string API version. E.g., 2.14.5.
build_information string Extra information associated with the build.
install_date google.protobuf.Timestamp Date/time when release was installed.
parameters Parameter Other information about the build.

SoftwareVersion

The software versioning number for a release.

Field Type Description
major_version int32 Signficant changes to software.
minor_version int32 Normal changes to software.
patch_level int32 Fixes which should not change intended capabilities or affect compatibility.

robot_id_service.proto

RobotIdService

RobotIdService provides mostly static identifying information about a robot. User authentication is not required to access RobotIdService to assist with early robot discovery.

Method Name Request Type Response Type Description
GetRobotId RobotIdRequest RobotIdResponse Get the robot id information. The ID contains basic information about a robot which is made available over the network as part of robot discovery without requiring user authentication.

robot_state.proto

BatteryState

The battery state for the robot. This includes information about the charge or the battery temperature.

Field Type Description
timestamp google.protobuf.Timestamp Robot clock timestamp corresponding to these readings.
identifier string An identifier for this battery (could be a serial number or a name. subject to change).
charge_percentage google.protobuf.DoubleValue Number from 0 (empty) to 100 (full) indicating the estimated state of charge of the battery.
estimated_runtime google.protobuf.Duration An estimate of remaining runtime. Note that this field might not be populated.
current google.protobuf.DoubleValue Measured current into (charging, positive) or out of (discharging, negative) the battery in Amps.
voltage google.protobuf.DoubleValue Measured voltage of the entire battery in Volts.
temperatures double Measured temperature measurements of battery, in Celsius. Temperatures may be measured in many locations across the battery.
status BatteryState.Status Current state of the battery.

BehaviorFault

The details of what the behavior fault consistents of, and the id for the fault. The unique behavior_fault_id can be used to clear the fault in robot command service ClearBehaviorFault rpc.

Field Type Description
behavior_fault_id uint32 Behavior fault unique id
onset_timestamp google.protobuf.Timestamp Time of robot local clock at time of the error
cause BehaviorFault.Cause The potential cause of the fault.
status BehaviorFault.Status Information about the status/what can be done with the fault.

BehaviorFaultState

This describes any current behaviror faults on the robot, which would block any robot commands from going through. These can be cleared using the ClearBehaviorFault rpc in the robot command service.

Field Type Description
faults BehaviorFault Current errors potentially blocking commands on robot

CommsState

The current comms information, including what comms the robot is using and the current status of the comms network.

Field Type Description
timestamp google.protobuf.Timestamp Robot timestamp corresponding to these readings.
wifi_state WiFiState The communication state is WiFi.

EStopState

The robot’s current E-Stop states and endpoints. A typical robot has several different E-Stops, all which must be “NOT_ESTOPPED” in order to run the robot.

Field Type Description
timestamp google.protobuf.Timestamp Robot clock timestamp corresponding to these readings.
name string Name of the E-Stop
type EStopState.Type What kind of E-Stop this message describes.
state EStopState.State The state of the E-Stop (is it E-Stopped or not?)
state_description string Optional description of E-Stop status.

FootState

Information about the foot positions and contact state, on a per-foot basis.

Field Type Description
foot_position_rt_body Vec3 The foot position described relative to the body.
contact FootState.Contact Is the foot in contact with the ground?

HardwareConfiguration

Robot Hardware Configuration, described with the robot skeleton.

Field Type Description
skeleton Skeleton Robot link and joint description.

JointState

Proto containing the state of a joint on the robot. This can be used with the robot skeleton to update the current view of the robot.

Field Type Description
name string This name maps directly to the joints in the URDF.
position google.protobuf.DoubleValue This is typically an angle in radians as joints are typically revolute. However, for translational joints this could be a distance in meters.
velocity google.protobuf.DoubleValue The joint velocity in [m/s].
acceleration google.protobuf.DoubleValue The joint acceleration in [m/s^2].
load google.protobuf.DoubleValue This is typically a torque in Newton meters as joints are typically revolute. However, for translational joints this could be a force in Newtons.

KinematicState

The kinematic state of the robot describes the current estimated positions of the robot body and joints throughout the world. It includes a transform snapshot of the robot’s current known frames as well as joint states and the velocity of the body.

Field Type Description
joint_states JointState Joint state of all robot joints.
acquisition_timestamp google.protobuf.Timestamp Robot clock timestamp corresponding to these readings.
transforms_snapshot FrameTreeSnapshot A tree-based collection of transformations, which will include the transformations to the robot body ("body") in addition to transformations to the common frames ("world", "dr") and ground plane estimate "gpe". All transforms within the snapshot are at the acquisition time of kinematic state.
velocity_of_body_in_vision SE3Velocity Velocity of the body frame with respect to vision frame and expressed in vision frame. The linear velocity is applied at the origin of the body frame.
velocity_of_body_in_odom SE3Velocity Velocity of the body frame with respect to odom frame and expressed in odom frame. Again, the linear velocity is applied at the origin of the body frame.

PowerState

The power state for the robot. If a robot is not in the POWER OFF state, if is not safe to approach. The robot must not be E-Stopped to enter the POWER_ON state.

Field Type Description
timestamp google.protobuf.Timestamp Robot clock timestamp corresponding to these readings.
motor_power_state PowerState.MotorPowerState The motor power state of the robot.
shore_power_state PowerState.ShorePowerState The shore power state of the robot.
locomotion_charge_percentage google.protobuf.DoubleValue Number from 0 (empty) to 100 (full) indicating the estimated state of charge. This field provides a summary of the BatteryStates that provide power for motor and/or base compute power, both of which are required for locomotion.
locomotion_estimated_runtime google.protobuf.Duration An estimate of remaining runtime. Note that this field might not be populated. This field provides a summary of the BatteryStates that provide power for motor and/or base compute power, both of which are required for locomotion.

RobotHardwareConfigurationRequest

The RobotHardwareConfiguration request message to get hardware configuration, described by the robot skeleton and urdf.

Field Type Description
header RequestHeader Common request header.

RobotHardwareConfigurationResponse

The RobotHardwareConfiguration response message, which returns the hardware config from the time the request was received.

Field Type Description
header ResponseHeader Common response header.
hardware_configuration HardwareConfiguration The requested RobotState.

RobotLinkModelRequest

The RobotLinkModel request message uses a link name returned by the RobotHardwareConfiguration response to get the associated OBJ file.

Field Type Description
header RequestHeader Common request header.
link_name string The link name of which the OBJ file shoould represent.

RobotLinkModelResponse

The RobotLinkModel response message returns the OBJ file for a specifc robot link.

Field Type Description
header ResponseHeader Common response header.
link_model Skeleton.Link.ObjModel The requested RobotState skeleton obj model.

RobotMetrics

Key robot metrics (e.g., Gait cycles (count), distance walked, time moving, etc…).

Field Type Description
timestamp google.protobuf.Timestamp Robot timestamp corresponding to these metrics.
metrics Parameter Key tracked robot metrics, such as distance walked, runtime, etc.

RobotMetricsRequest

The RobotMetrics request message to get metrics and parameters from the robot.

Field Type Description
header RequestHeader Common request header.

RobotMetricsResponse

The RobotMetrics response message, which returns the metrics information from the time the request was received.

Field Type Description
header ResponseHeader Common response header.
robot_metrics RobotMetrics The requested robot metrics.

RobotState

The current state of the robot.

Field Type Description
power_state PowerState Power state (e.g. motor power).
battery_states BatteryState Battery state (e.g. charge, temperature, current).
comms_states CommsState Communication state (e.g. type of comms network).
system_fault_state SystemFaultState Different system faults for the robot.
estop_states EStopState Because there may be multiple E-Stops, and because E-Stops may be supplied with payloads, this is a repeated field instead of a hardcoded list.
kinematic_state KinematicState Kinematic state of the robot (e.g. positions, velocities, other frame information).
behavior_fault_state BehaviorFaultState Robot behavior fault state.
foot_state FootState

RobotStateRequest

The RobotState request message to get the current state of the robot.

Field Type Description
header RequestHeader Common request header.

RobotStateResponse

The RobotState response message, which returns the robot state information from the time the request was received.

Field Type Description
header ResponseHeader Common response header.
robot_state RobotState The requested RobotState.

Skeleton

Kinematic model of the robot skeleton.

Field Type Description
links Skeleton.Link The list of links that make up the robot skeleton.
urdf string URDF description of the robot skeleton.

SystemFault

The current system faults for a robot. A fault is an indicator of a hardware or software problem on the robot. An active fault may indicate the robot may fail to comply with a user request. The exact response a fault may vary, but possible responses include: failure to enable motor power, loss of perception enabled behavior, or triggering a fault recovery behavior on robot.

Field Type Description
name string Name of the fault.
onset_timestamp google.protobuf.Timestamp Time of robot local clock at fault onset.
duration google.protobuf.Duration Time elapsed since onset of the fault.
code int32 Error code returned by a fault. The exact interpretation of the fault code is unique to each variety of fault on the robot. The code is useful for Boston Dynamics support staff to diagnose hardware/software issues on robot.
uid uint64 Fault UID
error_message string User visible description of the fault (and possibly remedies.)
attributes string Fault attributes Each fault may be flagged with attribute metadata (strings in this case.) These attributes are useful to communicate that a particular fault may have significant effect on robot operations. Some potential attributes may be "robot", "imu", "vision", or "battery". These attributes would let us flag a fault as indicating a problem with the base robot hardware, gyro, perception system, or battery respectively. A fault may have, zero, one, or more attributes attached to it, i.e. a "battery" fault may also be considered a "robot" fault.
severity SystemFault.Severity Fault severity, how bad is the fault? The severity level will have some indication of the potential robot response to the fault. For example, a fault marked with "battery" attribute and severity level SEVERITY_WARN may indicate a low battery state of charge. However a "battery" fault with severity level SEVERITY_CRITICAL likely means the robot is going to shutdown immediately.

SystemFaultState

The current state of each system fault the robot is experiencing. An “active” fault indicates a hardware/software currently on the robot. A “historical” faults indicates a, now cleared, hardware/software problem. Historical faults are useful to diagnose robot behavior subject to intermittent failed states.

Field Type Description
faults SystemFault Currently active faults
historical_faults SystemFault Inactive faults that cleared within the last 10 minutes
aggregated SystemFaultState.AggregatedEntry Aggregated fault data. This provides a very quick way of determining if there any "battery" or "vision" faults above a certain severity level.

SystemFaultState.AggregatedEntry

Field Type Description
key string
value SystemFault.Severity

WiFiState

Field Type Description
current_mode WiFiState.Mode Current WiFi mode.
essid string Essid of robot (master mode) or connected network.

BatteryState.Status

Name Number Description
STATUS_UNKNOWN 0 The battery is in an unknown / unexpected state.
STATUS_MISSING 1 The battery is not plugged in or otherwise not talking.
STATUS_CHARGING 2 The battery is plugged in to shore power and charging.
STATUS_DISCHARGING 3 The battery is not plugged into shore power and discharging.
STATUS_BOOTING 4 The battery was just plugged in and is booting up= 3;

BehaviorFault.Cause

Name Number Description
CAUSE_UNKNOWN 0 Unknown cause of error
CAUSE_FALL 1 Error caused by mobility failure or fall
CAUSE_HARDWARE 2 Error caused by robot hardware malfunction

BehaviorFault.Status

Name Number Description
STATUS_UNKNOWN 0 Unknown clearable status
STATUS_CLEARABLE 1 Fault is clearable
STATUS_UNCLEARABLE 2 Fault is currently not clearable

EStopState.State

Name Number Description
STATE_UNKNOWN 0 No E-Stop information is present. Only happens in an error case.
STATE_ESTOPPED 1 E-Stop is active -- robot cannot power its actuators.
STATE_NOT_ESTOPPED 2 E-Stop is released -- robot may be able to power its actuators.

EStopState.Type

Name Number Description
TYPE_UNKNOWN 0 Unknown type of E-Stop. Do not use this field.
TYPE_HARDWARE 1 E-Stop is a physical button
TYPE_SOFTWARE 2 E-Stop is a software process

FootState.Contact

Name Number Description
CONTACT_UNKNOWN 0 Unknown contact. Do not use.
CONTACT_MADE 1 The foot is currently in contact with the ground.
CONTACT_LOST 2 The foot is not in contact with the ground.

PowerState.MotorPowerState

Name Number Description
STATE_UNKNOWN 0 Unknown motor power state. Do not use this field.
STATE_OFF 1 Motors are off, the robot is safe to approach.
STATE_ON 2 The motors are powered.
STATE_POWERING_ON 3 The robot has received an ON command, and is turning on.
STATE_POWERING_OFF 4 In the process of powering down, not yet safe to approach.
STATE_ERROR 5 The robot is in an error state and must be powered off before attempting to re-power.

PowerState.ShorePowerState

State describing if robot is connected to shore (wall) power. Robot can’t be powered on while on shore power

Name Number Description
STATE_UNKNOWN_SHORE_POWER 0 Unknown shore power state. Do not use this field.
STATE_ON_SHORE_POWER 1 The robot is connected to shore power. The robot will not power on while connected to shore power.
STATE_OFF_SHORE_POWER 2 The robot is disconnected from shore power and motors can be powered up.

SystemFault.Severity

Name Number Description
SEVERITY_UNKNOWN 0 Unknown severity
SEVERITY_INFO 1 No hardware problem
SEVERITY_WARN 2 Robot performance may be degraded
SEVERITY_CRITICAL 3 Critical fault

WiFiState.Mode

Name Number Description
MODE_UNKNOWN 0 The robot's comms state is unknown, or no user requested mode.
MODE_ACCESS_POINT 1 The robot is acting as an access point.
MODE_CLIENT 2 The robot is connected to a network.

robot_state_service.proto

RobotStateService

The robot state service tracks all information about the measured and computed states of the robot at the current time.

Method Name Request Type Response Type Description
GetRobotState RobotStateRequest RobotStateResponse Get robot state information (such as kinematic state, power state, or faults).
GetRobotMetrics RobotMetricsRequest RobotMetricsResponse Get different robot metrics and parameters from the robot.
GetRobotHardwareConfiguration RobotHardwareConfigurationRequest RobotHardwareConfigurationResponse Get the hardware configuration of the robot, which describes the robot skeleton and urdf.
GetRobotLinkModel RobotLinkModelRequest RobotLinkModelResponse Returns the OBJ file for a specifc robot link. Intended to be called after GetRobotHardwareConfiguration, using the link names returned by that call.

spot/robot_command.proto

BodyControlParams

Parameters for offsetting the body from the normal default.

Field Type Description
base_offset_rt_footprint bosdyn.api.SE3Trajectory Desired base offset relative to the footprint pseudo-frame. The footprint pseudo-frame is a gravity aligned frame with its origin located at the geometric center of the feet in the X-Y axis, and at the nominal height of the hips in the Z axis. The yaw of the frame (wrt the world) is calcuated by the average foot locations, and is aligned with the feet.
rotation_setting BodyControlParams.RotationSetting The rotation setting for the robot body.

BodyExternalForceParams

External Force on robot body parameters. This is a beta feature and still can have some odd behaviors. By default, the external force estimator is disabled on the robot.

Field Type Description
external_force_indicator BodyExternalForceParams.ExternalForceIndicator The type of external force described by the parameters.
frame_name string The frame name for which the external_force_override is defined in. The frame must be known to the robot.
external_force_override bosdyn.api.Vec3 Specifies a force that the body should expect to feel. This allows the robot to "lean into" an external force. Be careful using this override, since incorrect information can cause the robot to fall over. For example, if the robot is leaning against a wall in front of it, the force override would be in the negative x dimension. If the robot was pulling something directly behind it, the force override would be in the negative x dimension as well.

MobilityParams

Params common across spot movement and mobility.

Field Type Description
vel_limit bosdyn.api.SE2VelocityLimit Max allowable velocity at any point in trajectory.
body_control BodyControlParams Parameters for controlling Spot's body during motion.
locomotion_hint LocomotionHint Desired gait during locomotion
stair_hint bool Stairs are only supported in trot gaits. Using this hint will override some user defaults in order to optimize stair behavior.
allow_degraded_perception bool Allow the robot to move with degraded perception when there are perception faults.
obstacle_params ObstacleParams Control of obstacle avoidance.
swing_height SwingHeight Swing height setting
terrain_params TerrainParams Ground terrain parameters.
disallow_stair_tracker bool Prevent the robot from using StairTracker even if in stairs mode.
external_force_params BodyExternalForceParams Robot Body External Force parameters
disallow_non_stairs_pitch_limiting bool Prevent the robot from pitching to get a better look at rearward terrain except in stairs mode.
disable_nearmap_cliff_avoidance bool Disable the secondary nearmap-based cliff avoidance that runs while on stairs.

ObstacleParams

Parameters for obstacle avoidance types.

Field Type Description
disable_vision_foot_obstacle_avoidance bool Use vision to make the feet avoid obstacles by swinging higher?
disable_vision_foot_constraint_avoidance bool Use vision to make the feet avoid constraints like edges of stairs?
disable_vision_body_obstacle_avoidance bool Use vision to make the body avoid obstacles?
obstacle_avoidance_padding double Desired padding around the body to use when attempting to avoid obstacles. Described in meters. Must be >= 0.

TerrainParams

Ground contact parameters that describe the terrain.

Field Type Description
ground_mu_hint google.protobuf.DoubleValue Terrain coefficient of friction user hint. This value must be postive and will clamped if necessary on the robot side. Best suggested values lie in the range between 0.4 and 0.8 (which is the robot's default.)
enable_grated_floor bool When true, the robot will assume the ground below it is made of grated metal.

BodyControlParams.RotationSetting

Setting for how the robot interprets base offset pitch & roll components. In the default case (ROTATION_SETTING_OFFSET) the robot will naturally align the body to the pitch of the current terrain. In some circumstances, the user may wish to override this value and try to maintain alignment with respect to gravity. Be careful with this setting as it may likely degrade robot performance in complex terrain, e.g. stairs, platforms, or slopes of sufficiently high grade.

Name Number Description
ROTATION_SETTING_UNKNOWN 0 Invalid; do not use.
ROTATION_SETTING_OFFSET 1 Pitch & Roll are offset with respect to orientation of the footprint.
ROTATION_SETTING_ABSOLUTE 2 Pitch & Roll are offset with respect to gravity.

BodyExternalForceParams.ExternalForceIndicator

Indicates what external force estimate/override the robot should use. By default, the external force estimator is disabled on the robot.

Name Number Description
EXTERNAL_FORCE_NONE 0 No external forces considered.
EXTERNAL_FORCE_USE_ESTIMATE 1 Use external forces estimated by the robot
EXTERNAL_FORCE_USE_OVERRIDE 2 Use external forces specified in an override vector.

LocomotionHint

The locomotion hint specifying the gait of the robot.

Name Number Description
HINT_UNKNOWN 0 Invalid; do not use.
HINT_AUTO 1 No hint, robot chooses an appropriate gait (typically trot.)
HINT_TROT 2 Most robust gait which moves diagonal legs together.
HINT_SPEED_SELECT_TROT 3 Trot which comes to a stand when not commanded to move.
HINT_CRAWL 4 Slow and steady gait which moves only one foot at a time.
HINT_SPEED_SELECT_CRAWL 10 Crawl which comes to a stand when not commanded to move.
HINT_AMBLE 5 Four beat gait where one foot touches down at a time.
HINT_SPEED_SELECT_AMBLE 6 Amble which comes to a stand when not commanded to move.
HINT_JOG 7 Demo gait which moves diagonal leg pairs together with an aerial phase.
HINT_HOP 8 Demo gait which hops while holding some feet in the air.
HINT_AUTO_TROT 3 HINT_AUTO_TROT is deprecated due to the name being too similar to the Spot Autowalk feature. It has been replaced by HINT_SPEED_SELECT_TROT. Keeping this value in here for now for backwards compatibility, but this may be removed in future releases.
HINT_AUTO_AMBLE 6 HINT_AUTO_AMBLE is deprecated due to the name being too similar to the Spot Autowalk feature. It has been replaced by HINT_SPEED_SELECT_AMBLE. Keeping this value in here for now for backwards compatibility, but this may be removed in future releases.

SwingHeight

The type of swing height for a step.

Name Number Description
SWING_HEIGHT_UNKNOWN 0 Invalid; do not use.
SWING_HEIGHT_LOW 1 Low-stepping. Robot will try to only swing legs a few cm away from ground.
SWING_HEIGHT_MEDIUM 2 Default for most cases, use other values with caution.
SWING_HEIGHT_HIGH 3 High-stepping. Possibly useful with degraded vision operation.

spot/spot_check.proto

CameraCalibrationCommandRequest

Request for the CameraCalibrationCommand service.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease The Lease to show ownership of the robot. Lease is required for all cal commands.
command CameraCalibrationCommandRequest.Command Command to start/stop the calibration.

CameraCalibrationCommandResponse

Response for the CameraCalibrationCommand service.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.

CameraCalibrationFeedbackRequest

Request for the CameraCalibrationFeedback service.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

CameraCalibrationFeedbackResponse

Response for the CameraCalibrationFeedback service.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status CameraCalibrationFeedbackResponse.Status Status of camera calibration procedure.
progress float The approximate progress of the calibration routine, range [0-1]. Status takes precedence over progress value.

DepthPlaneSpotCheckResult

Results from camera check.

Field Type Description
status DepthPlaneSpotCheckResult.Status Return status for the request.
severity_score float Higher is worse. Above 100 means the camera is severely out of calibration.

FootHeightCheckResult

Results from foot height checks.

Field Type Description
status FootHeightCheckResult.Status Return status for the request.
foot_height_error_from_mean float The difference between foot height and mean feet height (m).

JointKinematicCheckResult

Kinematic calibration results

Field Type Description
error JointKinematicCheckResult.Error A flag to indicate if results has an error.
offset float The current offset [rad]
old_offset float The previous offset [rad]
health_score float Joint calibration health score. range [0-1] 0 indicates an unhealthy kinematic joint calibration 1 indicates a perfect kinematic joint calibration Typically, values greater than 0.8 should be expected.

LegPairCheckResult

Results from leg pair checks..

Field Type Description
status LegPairCheckResult.Status Return status for the request.
leg_pair_distance_change float The change in estimated distance between two feet from tall to short stand (m)

LoadCellSpotCheckResult

Results from load cell check.

Field Type Description
error LoadCellSpotCheckResult.Error A flag to indicate if results has an error.
zero float The current loadcell zero as fraction of full range [0-1]
old_zero float The previous loadcell zero as fraction of full range [0-1]

PayloadCheckResult

Results of payload check.

Field Type Description
error PayloadCheckResult.Error A flag to indicate if configuration has an error.
extra_payload float Indicates how much extra payload (in kg) we think the robot has Positive indicates robot has more payload than it is configured. Negative indicates robot has less payload than it is configured.

SpotCheckCommandRequest

Request for the SpotCheckCommand service.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease The Lease to show ownership of the robot. Lease required to issue any SpotCheck command.
command SpotCheckCommandRequest.Command The describing what the spot check service should do.

SpotCheckCommandResponse

Response for the SpotCheckCommand service.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.

SpotCheckFeedbackRequest

Request for the SpotCheckFeedback service.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

SpotCheckFeedbackResponse

Response for the SpotCheckFeedback service.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
state SpotCheckFeedbackResponse.State The state of the spot check routine.
last_command SpotCheckCommandRequest.Command The last command executed by Spotcheck. When SpotCheck is in state WAITING_FOR_COMMAND, the last command has completed.
error SpotCheckFeedbackResponse.Error The specifics of the error for the SpotCheck service.
camera_results SpotCheckFeedbackResponse.CameraResultsEntry Results from camera check. The key string is the location of the camera (e.g. frontright, frontleft, left, ...)
load_cell_results SpotCheckFeedbackResponse.LoadCellResultsEntry Results from load cell calibration. The key string is the location of the joint (e.g. fl.hxa, fl.hya, fl.kna, ...)
kinematic_cal_results SpotCheckFeedbackResponse.KinematicCalResultsEntry Results from output position sensor calibration. The key string is the location of the joint (e.g. fl.hx, fl.hy, fl.kn, ...)
payload_result PayloadCheckResult Result from the payload check
foot_height_results SpotCheckFeedbackResponse.FootHeightResultsEntry Results of foot height validation. The key string is the name of the leg (e.g. fl, fr, hl, ...)
leg_pair_results SpotCheckFeedbackResponse.LegPairResultsEntry Results of leg pair validation. The key string is the name of the leg pair (e.g. fl-fr, fl-hl, ...)
progress float The approximate progress of the spot check routine, range [0-1].
last_cal_timestamp google.protobuf.Timestamp Timestamp for the most up-to-date calibration

SpotCheckFeedbackResponse.CameraResultsEntry

Field Type Description
key string
value DepthPlaneSpotCheckResult

SpotCheckFeedbackResponse.FootHeightResultsEntry

Field Type Description
key string
value FootHeightCheckResult

SpotCheckFeedbackResponse.KinematicCalResultsEntry

Field Type Description
key string
value JointKinematicCheckResult

SpotCheckFeedbackResponse.LegPairResultsEntry

Field Type Description
key string
value LegPairCheckResult

SpotCheckFeedbackResponse.LoadCellResultsEntry

Field Type Description
key string
value LoadCellSpotCheckResult

CameraCalibrationCommandRequest.Command

Name Number Description
COMMAND_UNKNOWN 0 Unused enum.
COMMAND_START 1 Start calibration routine.
COMMAND_CANCEL 2 Cancel calibration routine.

CameraCalibrationFeedbackResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Unused enum.
STATUS_PROCESSING 1 The robot is actively running calibration routine.
STATUS_SUCCESS 2 The robot successfully ran calibration routine and is ready to use again.
STATUS_USER_CANCELED 3 API client canceled calibration.
STATUS_POWER_ERROR 4 The robot is not powered on.
STATUS_LEASE_ERROR 5 Ownership error during calibration.
STATUS_ROBOT_COMMAND_ERROR 7 Robot encountered an error while trying to move around the calibration target. Robot possibly encountered a fault. Check robot state for more details
STATUS_CALIBRATION_ERROR 8 Calibration procedure produced an invalid result. This may occur in poor lighting conditions or if calibration target moved during calibration procedure.
STATUS_INTERNAL_ERROR 9 Something extraordinary happened. Try power cycling robot or contact BD.
STATUS_CAMERA_FOCUS_ERROR 14 Camera focus issue detected. This is a hardware issue.
STATUS_TARGET_NOT_CENTERED 6 Target partially, but not fully, in view when starting calibration.
STATUS_TARGET_NOT_IN_VIEW 11 Target not visible when starting calibration.
STATUS_TARGET_NOT_GRAVITY_ALIGNED 12 Target not aligned with gravity when starting calibration.
STATUS_TARGET_UPSIDE_DOWN 13 Target upside down when starting calibration.
STATUS_NEVER_RUN 10 Calibration routine has never been run. No feedback to give.

DepthPlaneSpotCheckResult.Status

Errors reflect an issue with camera hardware.

Name Number Description
STATUS_UNKNOWN 0 Unused enum.
STATUS_OK 1 No detected calibration error.
STATUS_WARNING 2 Possible calibration error detected.
STATUS_ERROR 3 Error with robot calibration.

FootHeightCheckResult.Status

Errors reflect an issue with robot calibration.

Name Number Description
STATUS_UNKNOWN 0 Unused enum.
STATUS_OK 1 No detected calibration error.
STATUS_WARNING 2 Possible calibration error detected.
STATUS_ERROR 3 Error with robot calibration.

JointKinematicCheckResult.Error

Errors reflect an issue with robot hardware.

Name Number Description
ERROR_UNKNOWN 0 Unused enum.
ERROR_NONE 1 No hardware error detected.
ERROR_CLUTCH_SLIP 2 Error detected in clutch performance.

LegPairCheckResult.Status

Name Number Description
STATUS_UNKNOWN 0 Unused enum.
STATUS_OK 1 No detected calibration error.
STATUS_WARNING 2 Possible calibration error detected.
STATUS_ERROR 3 Error with robot calibration.

LoadCellSpotCheckResult.Error

Errors reflect an issue with robot hardware.

Name Number Description
ERROR_UNKNOWN 0 Unused enum.
ERROR_NONE 1 No hardware error detected.
ERROR_ZERO_OUT_OF_RANGE 2 Load cell calibration failure.

PayloadCheckResult.Error

Errors reflect an issue with payload configuration.

Name Number Description
ERROR_UNKNOWN 0 Unused enum.
ERROR_NONE 1 No error found in the payloads.
ERROR_MASS_DISCREPANCY 2 There is a mass discrepancy between the registered payload and what is estimated.

SpotCheckCommandRequest.Command

Name Number Description
COMMAND_UNKNOWN 0 Unused enum.
COMMAND_START 1 Start spot check joint calibration and camera checks.
COMMAND_ABORT 2 Abort spot check joint calibration and camera check.
COMMAND_REVERT_CAL 3 Revert joint calibration back to the previous values.

SpotCheckFeedbackResponse.Error

If SpotCheck experienced an error, specific error details reported here. This reflects an error in the routine.

Name Number Description
ERROR_UNKNOWN 0 Unused enum.
ERROR_NONE 1 No error has occurred.
ERROR_UNEXPECTED_POWER_CHANGE 2 Unexpected motor power state transition.
ERROR_INIT_IMU_CHECK 3 Robot body is not flat on the ground.
ERROR_INIT_NOT_SITTING 4 Robot body is not close to a sitting pose
ERROR_LOADCELL_TIMEOUT 5 Timeout during loadcell calibration.
ERROR_POWER_ON_FAILURE 6 Error enabling motor power.
ERROR_ENDSTOP_TIMEOUT 7 Timeout during endstop calibration.
ERROR_FAILED_STAND 8 Robot failed to stand.
ERROR_CAMERA_TIMEOUT 9 Timeout during camera check.
ERROR_GROUND_CHECK 10 Flat ground check failed.
ERROR_POWER_OFF_FAILURE 11 Robot failed to power off.

SpotCheckFeedbackResponse.State

Name Number Description
STATE_UNKNOWN 0 Unused enum.
STATE_USER_ABORTED 1 SpotCheck is aborted by the user.
STATE_STARTING 2 SpotCheck is initializing.
STATE_LOADCELL_CAL 3 Load cell calibration underway.
STATE_ENDSTOP_CAL 4 Endstop calibration underway.
STATE_CAMERA_CHECK 5 Camera check underway.
STATE_BODY_POSING 6 Body pose routine underway.
STATE_FINISHED 7 Spot check successfully finished.
STATE_REVERTING_CAL 8 Reverting calibration to previous values.
STATE_ERROR 9 Error occurred while running spotcheck. Inspect error for more info.
STATE_WAITING_FOR_COMMAND 10 Waiting for user command.

spot/spot_check_service.proto

SpotCheckService

RPCs for monitoring robot health and recalibration various sensors. These procedures should be run periodically in order to keep the system running in the best possible condition.

Method Name Request Type Response Type Description
SpotCheckCommand SpotCheckCommandRequest SpotCheckCommandResponse Send a command to the SpotCheck service. The spotcheck service is responsible to both recalibrating actuation sensors and checking camera health.
SpotCheckFeedback SpotCheckFeedbackRequest SpotCheckFeedbackResponse Check the status of the spot check procedure. After procedure completes, this reports back results for specific joints and cameras.
CameraCalibrationCommand CameraCalibrationCommandRequest CameraCalibrationCommandResponse Send a camera calibration command to the robot. Used to start or abort a calibration routine.
CameraCalibrationFeedback CameraCalibrationFeedbackRequest CameraCalibrationFeedbackResponse Check the status of the camera calibration procedure.

spot_cam/LED.proto

GetLEDBrightnessRequest

Request the current state of LEDs on the SpotCam.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetLEDBrightnessResponse

Describes the current brightnesses of all LEDs.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
brightnesses float Brightness [0, 1] of the LED located at indices [0, 3].

SetLEDBrightnessRequest

Set individual LED brightnesses.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
brightnesses SetLEDBrightnessRequest.BrightnessesEntry Brightness [0, 1] to assign to the LED located at indices [0, 3].

SetLEDBrightnessRequest.BrightnessesEntry

Field Type Description
key int32
value float

SetLEDBrightnessResponse

Response with any errors setting LED brightnesses.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

spot_cam/audio.proto

DeleteSoundRequest

Remove a loaded sound from the library of loaded sounds.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
sound Sound The sound identifier as uploaded by LoadSoundRequest or listed in ListSoundsResponse.

DeleteSoundResponse

Result of deleting a sound from the library.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

GetVolumeRequest

Query the current volume level of the system.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetVolumeResponse

Provides the current volume level of the system.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
volume float volume, as a percentage of maximum.

ListSoundsRequest

Request for all sounds present on the robot.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

ListSoundsResponse

List of all sounds present on the robot.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
sounds Sound All sounds currently loaded.

LoadSoundRequest

Load a new sound onto the robot for future playback.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
sound Sound Identifier for the sound. If the same identifier is used as a previously loaded sound, that sound will be overwritten with the new data.
data bosdyn.api.DataChunk WAV bytes to be joined.

LoadSoundResponse

Result of uploading a sound.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

PlaySoundRequest

Begin playing a loaded sound from the robot’s speakers.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
sound Sound The sound identifier as uploaded by LoadSoundRequest or listed in ListSoundsResponse.
gain google.protobuf.FloatValue If the gain field is populated, then volume of the sound is multiplied by this value. Does not modify the system volume level.

PlaySoundResponse

Result of staring playback of a sound.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

SetVolumeRequest

Set the desired volume level of the system.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
volume float volume, as a percentage of maximum.

SetVolumeResponse

Result of changing the system volume level.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

Sound

Identifier for a playable sound.

Field Type Description
name string internally, sounds are stored in a flat table. This name is the identifier of a sound effect

spot_cam/camera.proto

Camera

Description of the details of a particular camera.

Field Type Description
name string Identifier for the camera.
resolution bosdyn.api.Vec2 Resolution of the sensor, where x = width and y = height.
base_frame_name string The frame name for the image sensor source. This frame will show up in the FrameTreeSnapshot grabbed from the payload registration service.
base_tfrom_sensor bosdyn.api.SE3Pose The transform from the base of spot cam to this specific camera.
pinhole Camera.PinholeIntrinsics Physical cameras
spherical Camera.SphericalLimits Only synthetic spherical panoramas

Camera.PinholeIntrinsics

Parameters for a pinhole model of distortion.

Field Type Description
focal_length bosdyn.api.Vec2 Focal_length in pixels
center_point bosdyn.api.Vec2 Center point in pixels
k1 float The following 4 parameters are radial distortion coefficeints to 4 orders. See https://en.wikipedia.org/wiki/Distortion_(optics)#Software_correction If all 4 of these values are 0, do not apply any correction.
k2 float
k3 float
k4 float

Camera.SphericalLimits

Spherical limits are the minimum and maximum angle of the image; IE the upper left pixel is at min_angle.x, min_angle.y and the lower right pixel is at max_angle.x, max_angle.y for a full-FOV image this will be (-180, 90) and (180, -90)

Field Type Description
min_angle bosdyn.api.Vec2 Upper left pixel location in degrees.
max_angle bosdyn.api.Vec2 Lower right pixel location in degrees.

spot_cam/compositor.proto

GetScreenRequest

Request the current screen in use.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetScreenResponse

Specify which screen is currently being displayed in the video stream.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
name string Identifier of the current screen.

GetVisibleCamerasRequest

Request information about the current cameras in the video stream.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetVisibleCamerasResponse

Description of the parameters and locations of each camera in the current video stream.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
streams GetVisibleCamerasResponse.Stream List of all camera streams visible in the current video stream.

GetVisibleCamerasResponse.Stream

The location and camera parameters for a single camera.

Field Type Description
window GetVisibleCamerasResponse.Stream.Window The location of this camera stream within the larger stream.
camera Camera The name field in this camera member is of the form 'c:w', where c is the name of the camera and w is the name of the window that's projecting it.

GetVisibleCamerasResponse.Stream.Window

The location of a sub-image within a larger image.

Field Type Description
xoffset int32
yoffset int32
width int32 The image should be cropped out of the stream at this resolution, and then scaled to the resolution described in the 'camera' member, below. once that scaling takes place, the intrinsics will be valid.
height int32

ListScreensRequest

Request the different screen layouts available.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

ListScreensResponse

Response with all screen layouts available.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
screens ScreenDescription List of all screen layouts that can be selected.

ScreenDescription

A “Screen” represents a particular layout of camera images used by the video stream.

Field Type Description
name string Unique identifer for a screen.

SetScreenRequest

Switch the camera layout in the video stream to the one specified.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
name string Identifier as specified in ListScreensResponse.

SetScreenResponse

Result of setting the camera layout.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
name string Identifier of the screen used.

spot_cam/health.proto

ClearBITEventsRequest

Clear Built-in Test events.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

ClearBITEventsResponse

Response to clearing built-in test events.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

GetBITStatusRequest

Request the status of all built-in tests.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetBITStatusResponse

Data on the current status of built-in tests.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
events bosdyn.api.SystemFault Fault events that have been reported.
degradations GetBITStatusResponse.Degradation List of system states that may effect performance.

GetBITStatusResponse.Degradation

Degredations are not necessesarily faults; a unit with no installed mechanical PTZ will behave differently, but nothing’s actually wrong.

Field Type Description
type GetBITStatusResponse.Degradation.DegradationType System affected.
description string Description of the kind of degradation being experienced.

GetTemperatureRequest

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetTemperatureResponse

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
temps Temperature List of all temperatures measured.

Temperature

The temperature of a particular component.

Field Type Description
channel_name string Identifier of the hardware measured.
temperature int64 Temperature is expressed in millidegrees C.

GetBITStatusResponse.Degradation.DegradationType

Systems that can experience performance degredations.

Name Number Description
STORAGE 0
PTZ 1
LED 2

spot_cam/logging.proto

DebugRequest

Change debug logging settings on the SpotCam.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
enable_temperature bool Set true to enable logging of temperature data;
enable_humidity bool Set true to enable logging of humidity data;
enable_BIT bool Set true to enable logging of BIT events; BIT events are always recorded to volatile memory and can be viewed (and cleared) with the Health service, but this enables writing them to disk.
enable_shock bool Set true to enable logging of Shock data; this is on by default.
enable_system_stat bool Set to true to enable logging of system load stats cpu, gpu, memory, and network utilization

Nowow a BIT, set true to enable logging of led driver status. bool enable_led_stat = 7; |

DebugResponse

Response with any errors for debug setting changes.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

DeleteRequest

Delete a log point from the store.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
point Logpoint Log point to delete. Only the name is used.

DeleteResponse

Response to a deletion with any errors that occurred.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

GetStatusRequest

Request for status about the current stage of data acquisition.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
point Logpoint Log point to query. Only the name is used.

GetStatusResponse

Provide an update on the stage of data acquisition.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
point Logpoint The logpoint returned here can be used to add a tag to the Logpoint later

ListCamerasRequest

Request the available cameras.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

ListCamerasResponse

Provide the list of available cameras.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
cameras Camera List of all cameras which can be used in a StoreRequest.

ListLogpointsRequest

List all available log points, whether they have completed or not.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

ListLogpointsResponse

Provide all log points in the system.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
logpoints Logpoint List of log points. Concatenate with all streamed ListLogpointsResponses to recover the full list.

Logpoint

A representation of a stored data acquisition.

Field Type Description
name string Unique identifier for a data acquisition event.
type Logpoint.RecordType Type of data held in this log point.
status Logpoint.LogStatus Current stage of acquisition.
tag string An arbitrary string to be stored with the log data.
timestamp google.protobuf.Timestamp Time of acquisition.
image_params Logpoint.ImageParams Image format of the stored data.
calibration Logpoint.Calibration Camera data for all sub-images contained within the image data.

Logpoint.Calibration

Data describing the camera intrinsics and extrinsics for a window of the image.

Field Type Description
xoffset int32
yoffset int32
width int32
height int32
base_frame_name string
base_tfrom_sensor bosdyn.api.SE3Pose
intrinsics Camera.PinholeIntrinsics

Logpoint.ImageParams

Description of image format.

Field Type Description
width int32
height int32
format bosdyn.api.Image.PixelFormat

RetrieveRawDataRequest

Retrieve the binary data associated with a log point, with no processing applied. Storing a panorama will retrieve tiled individual images.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
point Logpoint Log point to retrieve. Only the name is used.

RetrieveRawDataResponse

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
logpoint Logpoint Log point retrieved.
data bosdyn.api.DataChunk Data chunk bytes field should be concatenated together to recover the binary data.

RetrieveRequest

Retrieve the binary data associated with a log point.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
point Logpoint Log point to retrieve. Only the name is used.

RetrieveResponse

Provide the data stored at a log point. Store() dictates what processing happens in this response. c0 -> c4 will return the raw (rgb24) fisheye image of the camera at that index. Storing a panorama will process the data into a stitched image.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
logpoint Logpoint Log point retrieved.
data bosdyn.api.DataChunk Data chunk bytes field should be concatenated together to recover the binary data.

SetPassphraseRequest

Set encryption for the disk.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
passphrase string After setting the passphrase, please reboot the system to remount the encrypted filesystem layer.

SetPassphraseResponse

Response from setting the disk encryption. After setting the passphrase, please reboot the system to remount the encrypted filesystem layer.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

StoreRequest

Trigger a data acquisition.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
camera Camera Which camera to capture.
type Logpoint.RecordType Type of data capture to perform.
tag string Metadata to associate with the store.

StoreResponse

Result of data acquisition trigger.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
point Logpoint The log point returned here can be used to add a tag to the Logpoint later It will very likely be in th 'QUEUED' state.

TagRequest

Add tag metadata to an existing log point.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
point Logpoint Logpoint to add metadata to. Name and tag are used.

TagResponse

Result of adding tag metadata to a log point.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

Logpoint.LogStatus

Possible stages of data acquisition.

Name Number Description
FAILED 0
QUEUED 1
COMPLETE 2
UNKNOWN -1

Logpoint.RecordType

Possible types of media that can be stored.

Name Number Description
STILLIMAGE 0

spot_cam/network.proto

GetICEConfigurationRequest

Request the servers used for ICE resolution.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetICEConfigurationResponse

Provides the ICE resolution servers.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
servers ICEServer List of servers used for ICE resolution.

GetNetworkSettingsRequest

Retrieve current network configuration.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetNetworkSettingsResponse

Provides the current network configuration.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
settings NetworkTuple Current network configuration.

GetSSLCertRequest

Request the SSL certificate currently in use.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetSSLCertResponse

Provides the SSL certificate currently in use.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
certificate string An ASCII-armored representation of the SSL certificate

ICEServer

Servers used in the ICE resolution process.

Field Type Description
type ICEServer.servertype STUN or TURN server.
address string Network address of the server.
port uint32 Only the least significant 16 bits are used.

NetworkTuple

Network configuration data.

Field Type Description
address google.protobuf.UInt32Value a big-endian representation of an IPv4 address
netmask google.protobuf.UInt32Value The mask used for defining the system's subnet
gateway google.protobuf.UInt32Value A global routing is set up for the address defined below (if present)
mtu google.protobuf.UInt32Value If MTU is present, and <16 bits wide, then it is set for the ethernet interface's MTU if not, the MTU is set to 1500

SetICEConfigurationRequest

Modify the ICE configuration. Note: this configuration replaces any configuration currently present. It is not appended.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
servers ICEServer List of servers used for ICE resolution.

SetICEConfigurationResponse

Result of modifying the ICE configuration.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.

ICEServer.servertype

Possible types of servers

Name Number Description
UNKNOWN 0
STUN 1
TURN 2

spot_cam/power.proto

GetPowerStatusRequest

Request component power status.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetPowerStatusResponse

Provides the power status of all components.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status PowerStatus Current power on or off of each component.

PowerStatus

Power on or off of components of the SpotCam.

Field Type Description
ptz google.protobuf.BoolValue these switches are 'true' for power-on, 'false' for power-off
aux1 google.protobuf.BoolValue
aux2 google.protobuf.BoolValue

SetPowerStatusRequest

Turn components on or off.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
status PowerStatus Set the individual messages for the components that should be changed.

SetPowerStatusResponse

Result of turning components on or off.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
status PowerStatus Resulting power status of components.

spot_cam/ptz.proto

GetPtzPositionRequest

Request the current position of a ptz.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
ptz PtzDescription Only the name is used.

GetPtzPositionResponse

Provides the current measured position.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
position PtzPosition Current position of the mechanism.

GetPtzVelocityRequest

Request the velocity of a ptz

Field Type Description
header bosdyn.api.RequestHeader Common request header.
ptz PtzDescription Only the name is used.

GetPtzVelocityResponse

Provides the current measured velocity.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
velocity PtzVelocity Current velocity of the mechanism.

ListPtzRequest

Request all available ptzs on the SpotCam.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

ListPtzResponse

Provide all available ptz on the SpotCam.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
ptzs PtzDescription List of ptzs, real and virtual.

PtzDescription

PtzDescription provides information about a given PTZ. The name is usually all that’s required to describe a PTZ, but ListPtzResponse will include more information.

Field Type Description
name string Identifier of a particular controllable PTZ mechanism (real or virtual).

maybe we want to filter by type or dimentionality in the future | | pan_limit | PtzDescription.Limits | Limits in degrees. | | tilt_limit | PtzDescription.Limits | Limits in degrees. | | zoom_limit | PtzDescription.Limits | Limits in zoom level. |

PtzDescription.Limits

Limits for a single axis.

Field Type Description
min google.protobuf.FloatValue Units depend on the axis being controlled.
max google.protobuf.FloatValue Units depend on the axis being controlled.

PtzPosition

Doubles as a description of current state, or a command for a new position.

Field Type Description
ptz PtzDescription The "mech" ptz can pan [0, 360] degrees, tilt [-20, 217] degrees where 0 is the horizon, and zoom between 1x and 30x.
pan google.protobuf.FloatValue degrees
tilt google.protobuf.FloatValue degrees
zoom google.protobuf.FloatValue zoom level

PtzVelocity

Doubles as a description of current state, or a command for a new velocity.

Field Type Description
ptz PtzDescription The "mech" ptz cannot be used with Velocity.
pan google.protobuf.FloatValue degrees/second
tilt google.protobuf.FloatValue degrees/second
zoom google.protobuf.FloatValue zoom level/second

SetPtzPositionRequest

Command the ptz to move to a position.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
position PtzPosition Desired position to achieve.

SetPtzPositionResponse

Result of a SetPtzPositionRequest.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
position PtzPosition Applied desired position.

SetPtzVelocityRequest

Command a velocity for a ptz.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
velocity PtzVelocity Desired velocity to achieve.

SetPtzVelocityResponse

Result of a SetPtzVelocityRequest.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
velocity PtzVelocity Applied desired position.

spot_cam/service.proto

AudioService

Upload and play sounds over the SpotCam’s speakers.

Method Name Request Type Response Type Description
PlaySound PlaySoundRequest PlaySoundResponse Given a soundRequest that identifies a single sound present in the system's sound effects table, PlaySound executes the sound effect.
LoadSound LoadSoundRequest stream LoadSoundResponse LoadSound loads a sound effect into the system's sound table. The stream must contain a wav file, with a RIFF header describing it. The arguement is a stream, to allow for sounds that are bigger then the MTU of the network; in this case, the complete stream must contain the entire sound. If the stream ends early, an error will be returned. The header and sound fields of the entire stream must be the same.
DeleteSound DeleteSoundRequest DeleteSoundResponse Delete the sound identified in the argument from the system's sound table.
ListSounds ListSoundsRequest ListSoundsResponse ListSounds returns a list of all of the sound effects that the system knows about.
SetVolume SetVolumeRequest SetVolumeResponse Set the overall volume level for playing sounds.
GetVolume GetVolumeRequest GetVolumeResponse Set the overall volume level for playing sounds.

CompositorService

Change the layout of of the video stream between available presets.

Method Name Request Type Response Type Description
SetScreen SetScreenRequest SetScreenResponse SetScreen changes the current view that is streamed over the network
GetScreen GetScreenRequest GetScreenResponse GetScreen returns the currently-selected screen
ListScreens ListScreensRequest ListScreensResponse ListScreens returns a list of available screens
GetVisibleCameras GetVisibleCamerasRequest GetVisibleCamerasResponse GetVisibleCameras returns a list of currently visible windows, with any available metadata

HealthService

Query temperature and built-in test results.

Method Name Request Type Response Type Description
GetTemperature GetTemperatureRequest GetTemperatureResponse GetTemperature returns a list of thermometers in the system, and the temperature that they measure.
GetBITStatus GetBITStatusRequest GetBITStatusResponse GetBitStatus returns two lists; a list of system events, and a list of ways that the system is degraded; for instance, a degredation may include a missing PTZ unit, or a missing USB storage device.
ClearBITEvents ClearBITEventsRequest ClearBITEventsResponse ClearBitEvents clears out the events list of the BITStatus structure.

LightingService

Change the brightness level of individual LEDs.

Method Name Request Type Response Type Description
SetLEDBrightness SetLEDBrightnessRequest SetLEDBrightnessResponse
GetLEDBrightness GetLEDBrightnessRequest GetLEDBrightnessResponse

MediaLogService

Trigger data acquisitions, and retrieve resulting data.

Method Name Request Type Response Type Description
Store StoreRequest StoreResponse Store queues up a Logpoint, which is a bit of media that the user wishes to store to disk (still images are supported for now, more media types will be supported in the future)
GetStatus GetStatusRequest GetStatusResponse GetStatus reads the 'name' field of the Logpoint contained in GetStatusRequest, and fills in the rest of the fields. Mainly useful for getting the 'state' of the logpoint.
Tag TagRequest TagResponse Tag updates the 'tag' field of the Logpoint that's passed, which must exist.
EnableDebug DebugRequest DebugResponse EnableDebug starts the periodic logging of health data to the database; this increases disk utilization, but will record data that is useful post-mortum
ListCameras ListCamerasRequest ListCamerasResponse ListCameras returns a list of strings that identify valid cameras for logging
RetrieveRawData RetrieveRawDataRequest RetrieveRawDataResponse stream Retrieve returns all raw data associated with a given logpoint
Retrieve RetrieveRequest RetrieveResponse stream Retrieve returns all data associated with a given logpoint
Delete DeleteRequest DeleteResponse Delete removes a Logpoint from the system
ListLogpoints ListLogpointsRequest ListLogpointsResponse stream ListLogpoints returns a list of all logpoints in the database. Warning: this may be a lot of data.
SetPassphrase SetPassphraseRequest SetPassphraseResponse SetPassphrase sets the eCryptFS passphrase used by the filesystem. there is no symmetry here, because key material is write-only

NetworkService

Modify or query network settings of the SpotCam and ICE resolution servers.

Method Name Request Type Response Type Description
SetICEConfiguration SetICEConfigurationRequest SetICEConfigurationResponse SetICEConfiguration sets up parameters for ICE, including addresses for STUN and TURN services
GetICEConfiguration GetICEConfigurationRequest GetICEConfigurationResponse GetICEConfiguration retrieves currently set parameters for ICE, including addresses for STUN and TURN services

PowerService

Turn hardware components’ power on or off.

Method Name Request Type Response Type Description
SetPowerStatus SetPowerStatusRequest SetPowerStatusResponse
GetPowerStatus GetPowerStatusRequest GetPowerStatusResponse

PtzService

Control real and virtual ptz mechanisms.

Method Name Request Type Response Type Description
SetPtzPosition SetPtzPositionRequest SetPtzPositionResponse SetPosition points the referenced camera to a given vector (in PTZ-space)
GetPtzPosition GetPtzPositionRequest GetPtzPositionResponse GetPosition returns the current settings of the referenced camera
SetPtzVelocity SetPtzVelocityRequest SetPtzVelocityResponse
GetPtzVelocity GetPtzVelocityRequest GetPtzVelocityResponse
ListPtz ListPtzRequest ListPtzResponse

StreamQualityService

Set quality parameters for the stream, such as compression and image postprocessing settings.

Method Name Request Type Response Type Description
SetStreamParams SetStreamParamsRequest SetStreamParamsResponse
GetStreamParams GetStreamParamsRequest GetStreamParamsResponse

VersionService

Query the version of the software release running on the SpotCam.

Method Name Request Type Response Type Description
GetSoftwareVersion GetSoftwareVersionRequest GetSoftwareVersionResponse

spot_cam/streamquality.proto

GetStreamParamsRequest

Request the current video stream parameters.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetStreamParamsResponse

Provides the current video stream parameters.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
params StreamParams Current video stream parameters.

SetStreamParamsRequest

Modify the video stream parameters.

Field Type Description
header bosdyn.api.RequestHeader Common request header.
params StreamParams Set only the fields that should be modified.

SetStreamParamsResponse

Result of setting video stream parameters.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
params StreamParams Applied video stream parameters.

StreamParams

Parameters for how the video stream should be processed and compressed.

Field Type Description
targetbitrate google.protobuf.Int64Value The compression level in target BPS
refreshinterval google.protobuf.Int64Value How often should the entire feed be refreshed? (in frames) Note: the feed is refreshed on a macroblock level; there are no full I-frames
idrinterval google.protobuf.Int64Value How often should an IDR message get sent? (in frames)
awb StreamParams.AwbMode Optional setting of automatic white balancing mode.

StreamParams.AwbMode

Wrapper for AwbModeEnum to allow it to be optionally set.

Field Type Description
awb StreamParams.AwbModeEnum

StreamParams.AwbModeEnum

Options for automatic white balancing mode.

Name Number Description
OFF 0
AUTO 1
INCANDESCENT 2
FLUORESCENT 3
WARM_FLUORESCENT 4
DAYLIGHT 5
CLOUDY 6
TWILIGHT 7
SHADE 8
DARK 9

spot_cam/version.proto

GetSoftwareVersionRequest

Request the software version running on the SpotCam.

Field Type Description
header bosdyn.api.RequestHeader Common request header.

GetSoftwareVersionResponse

Provide the SpotCam’s software release version.

Field Type Description
header bosdyn.api.ResponseHeader Common response header.
version bosdyn.api.SoftwareVersion Version of the software currently running on the SpotCam.

time_sync.proto

TimeSyncEstimate

Estimate of network speed and clock skew. Both for the last complete sample and a recent average. Populated by the server.

Field Type Description
round_trip_time google.protobuf.Duration Observed network delay (excludes processing between server_rx and server_tx). If zero, this estimate is unpopulated.
clock_skew google.protobuf.Duration Add the skew to the client system clock to get the server clock.

TimeSyncRoundTrip

Timestamp information from a full GRPC call round-trip. These are used to estimate the round-trip communication time and difference between client and server clocks.

Field Type Description
client_tx google.protobuf.Timestamp Client system time when the message was sent, if not zero.
server_rx google.protobuf.Timestamp Server system time when the message was received, if not zero.
server_tx google.protobuf.Timestamp Server system time when the response was sent, if not zero.
client_rx google.protobuf.Timestamp Client time when the response was received, if not zero.

TimeSyncState

Current best estimate status of time sync.

Field Type Description
best_estimate TimeSyncEstimate Best clock synchronization estimate currently available, if any.
status TimeSyncState.Status STATUS_OK once time sync is established.
measurement_time google.protobuf.Timestamp Time of best estimate, in server time.

TimeSyncUpdateRequest

Request message for a time-sync Update RPC.

Field Type Description
header RequestHeader Common request header.
previous_round_trip TimeSyncRoundTrip Round-trip timing information from the previous Update request.
clock_identifier string Identifier to verify time sync between robot and client. If unset, server will assign one to client.

TimeSyncUpdateResponse

Request message for a time-sync Update RPC.

Field Type Description
header ResponseHeader Common response header.
previous_estimate TimeSyncEstimate Clock synchronization estimate from the previous RPC round-trip, if available.
state TimeSyncState Current best clock synchronization estimate according to server.
clock_identifier string Identifier to verify time sync between robot and client. Assigned upon first Request and echoed with each subsequent request.

TimeSyncState.Status

Name Number Description
STATUS_UNKNOWN 0 Invalid, do not use.
STATUS_OK 1 Clock skew is available.
STATUS_MORE_SAMPLES_NEEDED 2 More updates are required to establish a synchronization estimate.
STATUS_SERVICE_NOT_READY 3 Server still establishing time sync internally.

time_sync_service.proto

TimeSyncService

The time-sync service estimates the difference between server and client clocks. Time synchronization is a tool which allows applications to work in a unified timebase with precision. It is useful in cases where a precise time must be set, independently of network communication lag. In distributed systems and robotics, hardware, system-level, and per-process approaches can be used to obtain synchronization. This service implements a stand alone time synchronization service. It enables clients to establish a per-process offset between two processes which may be on separate systems.

Method Name Request Type Response Type Description
TimeSyncUpdate TimeSyncUpdateRequest TimeSyncUpdateResponse See the exchange documentation in time_sync.proto. This call makes one client/server round trip toward clock synchronization.

trajectory.proto

SE2Trajectory

A 2D pose trajectory, which specified multiple points and the desired times the robot should reach these points.

Field Type Description
points SE2TrajectoryPoint The points in trajectory
reference_time google.protobuf.Timestamp All trajectories specify times relative to this reference time. The reference time should be in robot clock. If this field is not included, this time will be the receive time of the command.
interpolation PositionalInterpolation Parameters for how trajectories will be interpolated on robot.

SE2TrajectoryPoint

A SE2 pose that can be used as a point within a trajectory.

Field Type Description
pose SE2Pose Required pose the robot will try and achieve.
time_since_reference google.protobuf.Duration The duration to reach the point relative to the trajectory reference time.

SE3Trajectory

A 3D pose trajectory, which specified multiple poses (and velocities for each pose) and the desired times the robot should reach these points.

Field Type Description
points SE3TrajectoryPoint The points in trajectory
reference_time google.protobuf.Timestamp All trajectories specify times relative to this reference time. The reference time should be in robot clock. If this field is not included, this time will be the receive time of the command.
pos_interpolation PositionalInterpolation Parameters for how trajectories will be interpolated on robot.
ang_interpolation AngularInterpolation

SE3TrajectoryPoint

A SE3 pose and velocity that can be used as a point within a trajectory.

Field Type Description
pose SE3Pose Required pose the robot will try and achieve.
velocity SE3Velocity Optional velocity (linear and angular) the robot will try and achieve.
time_since_reference google.protobuf.Duration The duration to reach the point relative to the trajectory reference time.

Vec3Trajectory

A 3D point trajectory, described by 3D points, a starting and ending velocity, and a reference time.

Field Type Description
points Vec3TrajectoryPoint The points in trajectory.
reference_time google.protobuf.Timestamp All trajectories specify times relative to this reference time. The reference time should be in robot clock. If this field is not included, this time will be the receive time of the command.
pos_interpolation PositionalInterpolation Parameters for how trajectories will be interpolated on robot.
starting_velocity Vec3 Velocity at the starting point of the trajectory.
ending_velocity Vec3 Velocity at the ending point of the trajectory.

Vec3TrajectoryPoint

A 3D point (and linear velocity) that can be used as a point within a trajectory.

Field Type Description
point Vec3 The point 3D position.
linear_speed double These are all optional. If nothing is specified, good defaults will be chosen server-side.
time_since_reference google.protobuf.Duration The duration to reach the point relative to the trajectory reference time.

AngularInterpolation

Parameters for how angular trajectories will be interpolated on robot.

Name Number Description
ANG_INTERP_UNKNOWN 0 Unknown interpolation, do not use.
ANG_INTERP_LINEAR 1 Linear interpolation for angular data.
ANG_INTERP_CUBIC_EULER 2 Cubic interpolation (using Euler method) for angular data.

PositionalInterpolation

Parameters for how positional trajectories will be interpolated on robot.

Name Number Description
POS_INTERP_UNKNOWN 0 Unknown interpolation, do not use.
POS_INTERP_LINEAR 1 Linear interpolation for positional data.
POS_INTERP_CUBIC 2 Cubic interpolation for positional data.

world_object.proto

AprilTagProperties

World object properties describing a fiducial object.

Field Type Description
tag_id int32 Consistent integer id associated with a given apriltag. April Tag detections will be from the tag family 36h11.
dimensions Vec2 Apriltag size in meters, where x is the row/width length and y is the height/col length of the tag
frame_name_fiducial string The frame name for the raw version of this fiducial. This will be included in the transform snapshot.
frame_name_fiducial_filtered string The frame name for the filtered version of this fiducial. This will be included in the transform snapshot.

DrawableArrow

A directed arrow drawing object.

Field Type Description
direction Vec3
radius double

DrawableBox

A three dimensional box drawing object.

Field Type Description
size Vec3

DrawableCapsule

A oval-like capsule drawing object.

Field Type Description
direction Vec3
radius double

DrawableCylinder

A cylinder drawing object.

Field Type Description
direction Vec3
radius double

DrawableFrame

A coordinate frame drawing object, describing how large to render the arrows.

Field Type Description
arrow_length double
arrow_radius double

DrawableLineStrip

A line strip drawing object.

Field Type Description
points Vec3

DrawablePoints

A set of points drawing object.

Field Type Description
points Vec3

DrawableProperties

The drawing and visualization information for a world object.

Field Type Description
color DrawableProperties.Color Color of the object.
label string Label to be drawn at the origin of the object.
wireframe bool Drawn objects in wireframe.
frame DrawableFrame A drawable frame (oneof drawable field).
sphere DrawableSphere A drawable sphere (oneof drawable field).
box DrawableBox A drawable box (oneof drawable field).
arrow DrawableArrow A drawable arrow (oneof drawable field).
capsule DrawableCapsule A drawable capsule (oneof drawable field).
cylinder DrawableCylinder A drawable cylinder (oneof drawable field).
linestrip DrawableLineStrip A drawable linestrip (oneof drawable field).
points DrawablePoints A drawable set of points (oneof drawable field).
frame_name_drawable string The frame name for the drawable object. This will optionally be included in the frame tree snapshot.

DrawableProperties.Color

RGBA values for color ranging from [0,255] for R/G/B, and [0,1] for A.

Field Type Description
r int32 Red value ranging from [0,255].
g int32 Green value ranging from [0,255].
b int32 Blue value ranging from [0,255].
a double Alpha (transparancy) value ranging from [0,1].

DrawableSphere

A sphere drawing object.

Field Type Description
radius double

ImageProperties

World object properties describing image coordinates associated with an object.

Field Type Description
camera_source string Camera Source of such as "back", "frontleft", etc.
coordinates Polygon Image Coordinates (pixels of x[row], y[col]) in either clockwise/counter clockwise order
frame_name_image_coordinates string Frame name for the object described by image coordinates.

ListWorldObjectRequest

The ListWorldObject request message, which can optionally include filters for the object type or timestamp.

Field Type Description
header RequestHeader Common request header
object_type WorldObjectType Optional filters to apply to the world object request Specific type of object; can request multiple different properties
timestamp_filter google.protobuf.Timestamp Timestamp to filter objects based on. The time should be in robot time All objects with header timestamps after (>) timestamp_filter will be returned

ListWorldObjectResponse

The ListWorldObject response message, which contains all of the current world objects in the robot’s perception scene.

Field Type Description
header ResponseHeader Common response header
world_objects WorldObject The currently perceived world objects.

MutateWorldObjectRequest

The MutateWorldObject request message, which specifies the type of mutation and which object the mutation should be applied to.

Field Type Description
header RequestHeader Common request header
mutation MutateWorldObjectRequest.Mutation The mutation for this request.

MutateWorldObjectRequest.Mutation

Field Type Description
action MutateWorldObjectRequest.Action The action (add, change, or delete) to be applied to a world object.
object WorldObject World object to be mutated. If an object is being changed/deleted, then the world object id must match a world object id known by the service.

MutateWorldObjectResponse

The MutateWorldObject response message, which includes the world object id for the object that the mutation was applied to if the request succeeds.

Field Type Description
header ResponseHeader Common response header
status MutateWorldObjectResponse.Status Return status for the request.
mutated_object_id int32 ID set by the world object service for the mutated object

WorldObject

The world object message is used to describe different objects seen by a robot. It contains information about the properties of the object in addition to a unique id and the transform snapshot. The world object uses “properties” to describe different traits about the object, such as image coordinates associated with the camera the object was detected in. A world object can have multiple different properties that are all associated with the single object.

Field Type Description
id int32 Unique integer identifier that will be consistent for the duration of a robot's battery life The id is set internally by the world object service.
name string A human readable name for the world object. Note that this differs from any frame_name's associated with the object (since there can be multiple frames describing a single object).
acquisition_time google.protobuf.Timestamp Time in robot time clock at which this object was most recently detected and valid.
transforms_snapshot FrameTreeSnapshot A tree-based collection of transformations, which will include the transformations to each of the returned world objects in addition to transformations to the common frames ("vision", "body", "odom"). All transforms within the snapshot are at the acquistion time of the world object. Note that each object's frame names are defined within the properties submessage. For example, the apriltag frame name is defined in the AprilTagProperties message as "frame_name_fiducial"
drawable_properties DrawableProperties The drawable properties describe geometric shapes associated with an object.
apriltag_properties AprilTagProperties The apriltag properties describe any fiducial identifying an object.
image_properties ImageProperties The image properties describe any camera and image coordinates associated with an object.
additional_properties google.protobuf.Any An extra field for application-specific object properties.

MutateWorldObjectRequest.Action

Name Number Description
ACTION_UNKNOWN 0 Invalid action.
ACTION_ADD 1 Add a new object.
ACTION_CHANGE 2 Change an existing objected (ID'd by integer ID number). This is only allowed to change objects added by the API-user, and not objects detected by Spot's perception system.
ACTION_DELETE 3 Delete the object, ID'd by integer ID number. This is only allowed to change objects added by the API-user, and not objects detected by Spot's perception system.

MutateWorldObjectResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status of request is unknown. Check the status code of the response header.
STATUS_OK 1 Request was accepted; GetObjectListResponse must still be checked to verify the changes.
STATUS_INVALID_MUTATION_ID 2 The mutation object's ID is unknown such that the service could not recognize this object. This error applies to the CHANGE and DELETE actions, since it must identify the object by it's id number given by the service.
STATUS_NO_PERMISSION 3 The mutation request is not allowed because it is attempting to change or delete an object detected by Spot's perception system.

WorldObjectType

A type for the world object, which is associated with whatever properties the world object includes. This can be used to request specific kinds of objects; for example, a request for only fiducials.

Name Number Description
WORLD_OBJECT_UNKNOWN 0
WORLD_OBJECT_DRAWABLE 1
WORLD_OBJECT_APRILTAG 2
WORLD_OBJECT_IMAGE_COORDINATES 5

world_object_service.proto

WorldObjectService

The world object service provides a way to track and store objects detected in the world around the robot.

Method Name Request Type Response Type Description
ListWorldObjects ListWorldObjectRequest ListWorldObjectResponse Request a list of all the world objects in the robot's perception scene.
MutateWorldObjects MutateWorldObjectRequest MutateWorldObjectResponse Mutate (add, change, or delete) the world objects.

Standard Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)