Protocol Documentation

Table of Contents

Top

bosdyn/api/alerts.proto

AlertData

Structured data indicating an alert detected off the robot that can be stored in the DataBuffer and associated with with previously stored data.

Field Type Label Description
severity AlertData.SeverityLevel Severity of this alert.
title string Human readable alert title/summary.
source string The source that triggered the alert.
additional_data google.protobuf.Struct JSON data for any additional info attached to this alert.

AlertData.SeverityLevel

Name Number Description
SEVERITY_LEVEL_UNKNOWN 0 Do not use. If severity is unknown, must assume issue is
highest severity.
SEVERITY_LEVEL_INFO 1 Informational message that requires no action.
SEVERITY_LEVEL_WARN 2 An error may occur in the future if no action is taken, but no action
presently required.
SEVERITY_LEVEL_ERROR 3 Action required. Error fatal to operation.
SEVERITY_LEVEL_CRITICAL 4 Action required. Severe error that requires immediate
attention.

Top

bosdyn/api/arm_command.proto

ArmCartesianCommand

Command the end effector of the arm. Each axis in the task frame is allowed to be set to position mode (default) or Force mode. If the axis is set to position, the desired value is read from the pose_trajectory_in_task. If the axis is set to force, the desired value is read from the wrench_trajectory. This supports hybrid control of the arm where users can specify, for example, Z to be in force control with X and Y in position control.

ArmCartesianCommand.Feedback

Field Type Label Description
status ArmCartesianCommand.Feedback.Status Current status of the pose trajectory.
measured_pos_tracking_error double Current linear tracking error of the tool frame [meters].
measured_rot_tracking_error double Current rotational tracking error of the tool frame [radians].
measured_pos_distance_to_goal double Linear distance from the tool to the tool trajectory's end point [meters].
measured_rot_distance_to_goal double Rotational distance from the tool to the trajectory's end point [radians].

ArmCartesianCommand.Request

Field Type Label Description
root_frame_name string The root frame is used to set the optional task frame that all trajectories are
specified with respect to. If the optional task frame is left un-specified it defaults
to the identity transform and the root frame becomes the task frame.
wrist_tform_tool SE3Pose The tool pose relative to the parent link (wrist).
Defaults to
[0.19557 0 0]
[1 0 0 0]
a frame with it's origin slightly in front of the gripper's palm plate aligned with
wrist's orientation.
root_tform_task SE3Pose The fields below are specified in this optional task frame. If unset it defaults
to the identity transform and all quantities are therefore expressed in the
root_frame_name.
pose_trajectory_in_task SE3Trajectory A 3D pose trajectory for the tool expressed in the task frame, e.g. task_T_tool.
This pose trajectory is optional if requesting a pure wrench at the end-effector,
otherwise required for position or mixed force/position end-effector requests.
maximum_acceleration google.protobuf.DoubleValue Optional Maximum acceleration magnitude of the end-effector.
Valid ranges (0, 20]
max_linear_velocity google.protobuf.DoubleValue Optional Maximum linear velocity magnitude of the end-effector. (m/s)
max_angular_velocity google.protobuf.DoubleValue Optional Maximum angular velocity magnitude of the end-effector. (rad/s)
max_pos_tracking_error google.protobuf.DoubleValue Maximum allowable tracking error of the tool frame from the desired trajectory
before the arm will stop moving and cancel the rest of the trajectory. When this limit is
exceeded, the hand will stay at the pose it was at when it exceeded the tracking error,
and any other part of the trajectory specified in the rest of this message will be
ignored. max position tracking error in meters
max_rot_tracking_error google.protobuf.DoubleValue max orientation tracking error in radians
force_remain_near_current_joint_configuration bool
preferred_joint_configuration ArmJointPosition
x_axis ArmCartesianCommand.Request.AxisMode
y_axis ArmCartesianCommand.Request.AxisMode
z_axis ArmCartesianCommand.Request.AxisMode
rx_axis ArmCartesianCommand.Request.AxisMode
ry_axis ArmCartesianCommand.Request.AxisMode
rz_axis ArmCartesianCommand.Request.AxisMode
wrench_trajectory_in_task WrenchTrajectory A force/torque trajectory for the tool expressed in the task frame.
This trajectory is optional if requesting a pure pose at the end-effector,
otherwise required for force or mixed force/position end-effector requests.
disable_velocity_limiting google.protobuf.BoolValue Disables protection that prevents the arm from moving unexpectedly fast. If you are
commanding an especially aggressive arm trajectory, you may need to disable this
protection.
WARNING: setting disable_velocity_limiting to true may result in fast arm motions!

ArmCommand

The synchronized command message for commanding the arm to move. A synchronized commands is one of the possible robot command messages for controlling the robot.

ArmCommand.Feedback

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

Field Type Label Description
arm_cartesian_feedback ArmCartesianCommand.Feedback Feedback for the end-effector Cartesian command.
arm_joint_move_feedback ArmJointMoveCommand.Feedback Feedback for the joint move command.
named_arm_position_feedback NamedArmPositionsCommand.Feedback Feedback for the named position move command.
arm_velocity_feedback ArmVelocityCommand.Feedback
arm_gaze_feedback GazeCommand.Feedback Feedback for the gaze command.
arm_stop_feedback ArmStopCommand.Feedback
arm_drag_feedback ArmDragCommand.Feedback Feedback for the drag command.
arm_impedance_feedback ArmImpedanceCommand.Feedback Feedback for impedance command.
status RobotCommandFeedbackStatus.Status

ArmCommand.Request

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

Field Type Label Description
arm_cartesian_command ArmCartesianCommand.Request Control the end-effector in Cartesian space.
arm_joint_move_command ArmJointMoveCommand.Request Control joint angles of the arm.
named_arm_position_command NamedArmPositionsCommand.Request Move the arm to some predefined configurations.
arm_velocity_command ArmVelocityCommand.Request Velocity control of the end-effector.
arm_gaze_command GazeCommand.Request Point the gripper at a point in the world.
arm_stop_command ArmStopCommand.Request Stop the arm in place with minimal motion.
arm_drag_command ArmDragCommand.Request Use the arm to drag something held in the gripper.
arm_impedance_command ArmImpedanceCommand.Request Impedance control of arm (beta)
params ArmParams Any arm parameters to send, common across all arm commands

ArmImpedanceCommand

Specify impedance about the end-effector. Users can set up frames along with stiffness and damping parameters to control how the end-effector will respond to external contact as it moves along a specified trajectory

ArmImpedanceCommand.Feedback

Field Type Label Description
status ArmImpedanceCommand.Feedback.Status Current status of the pose trajectory.
transforms_snapshot FrameTreeSnapshot A tree-based collection of transformations relevant to the current impedance operation.
In addition to the common frames ("vision", "body", "odom"), this snapshot contains the
following:
"task": The task frame that the impedance action is specified in.
"desired_tool": The pose of the desired_tool frame at the current time.
"tool": The current measured pose of the tool.
"desired_tool_at_end": The desired tool pose at the end of the requested trajectory.
"measured_tool_at_start": The measured pose of the tool when this command was first sent.

While these poses can be used in any way the user sees fit, here are some useful ideas:
desired_tool_tform_tool: The current measured tool pose relative to the desired_tool
frame [meters, quaternion]. This is our "tracking error".
Multiplying this error by diagonal_stiffness_matrix should
yield commanded_wrench_from_stiffness_at_tool_in_desired_tool.
desired_tool_at_end_tform_tool: The current measured tool pose relative to the
desired_tool frame at the end of the user trajectory
[meters, quaternion]. This is our "distance to goal",
and can be used for checking when an impedance move is
"complete".
measured_tool_at_start_tform_tool_in_task: The current measured tool pose relative to
the measured tool frame at the start,
expressed in the task frame
[meters, quaternion]. This can be used to
see how far the tool has moved since the
beginning of the command.
commanded_wrench_from_stiffness_at_tool_in_desired_tool Wrench The component of our commanded wrench at the tool expressed with respect to the
desired_tool frame from our stiffness matrix [Newtons / Nm]
commanded_wrench_from_damping_at_tool_in_desired_tool Wrench The component of our commanded wrench at the tool expressed with respect to the
desired_tool frame from our damping matrix [Newtons / Nm]
commanded_wrench_from_feed_forward_at_tool_in_desired_tool Wrench The component of our commanded wrench at the tool expressed with respect to the
desired_tool frame from our feed forward wrench [Newtons / Nm]
total_commanded_wrench_at_tool_in_desired_tool Wrench The commanded total wrench at the tool expressed with respect to the desired_tool
frame. This wrench has been saturated to obey max_force_mag and max_torque_mag
[Newtons / Nm]
total_measured_wrench_at_tool_in_desired_tool Wrench Sometimes the arm cannot achieve the commanded wrench exactly because of the
underlying controller or arm pose. This looks at the joint torque sensors to
determine the actual force and torque being applied at the tool. [Newtons / Nm]

ArmImpedanceCommand.Request

Field Type Label Description
root_frame_name string Name of the frame relative to which the task frame is defined for this command.
Common frames for this include "odom", "vision", "body", and "flat_body".
root_tform_task SE3Pose This transform specifies the pose of the task frame relative to the root frame.
If unset, it defaults to identity, and the task frame coincides with the root frame.
The desired_tool frame will be specified relative to the task frame. For peg in
hole tasks for example, the task frame could be a frame attached to the top of the
hole with z-axis aligned with the hole axis, and the desired_tool frame could
move in z to direct the peg deeper into the hole.
wrist_tform_tool SE3Pose The tool pose relative to the parent link (link_wr1). This can also be thought of as the
"remote center" frame. For peg in hole tasks for example, one might put the tool frame
at the tip of the peg, or slightly below the tip floating in space, at the point on which
we want our virtual springs to pull.
Defaults to
[0.19557 0 0]
[1 0 0 0]
which is a frame aligned with the wrist frame, with its origin slightly in front of
the gripper's palm plate.
task_tform_desired_tool SE3Trajectory Trajectory of where we want the tool to be relative to the task frame. Note that this
desired_tool frame is not the same as the tool frame attached to the wrist link. If our
tool deviates from this desired_tool pose, it will be subject to a wrench determined by
our stiffness and damping matrices.
feed_forward_wrench_at_tool_in_desired_tool Wrench Feed forward wrench to apply at the tool, expressed with respect to the desired_tool
frame
diagonal_stiffness_matrix Vector Stiffness matrix in the desired_tool frame. The matrix is parameterized by a vector of
6 doubles, representing the diagonal of this 6x6 matrix: [x,y,z,tx,ty,tz] (N/m, N/m, N/m,
Nm/rad, Nm/rad, Nm/rad). All other entries will be set to 0. All stiffness values along
the diagonal should be non-negative.
diagonal_damping_matrix Vector Damping matrix in the desired_tool frame. The matrix is parameterized by a vector of 6
doubles, representing the diagonal of this 6x6 matrix: [x,y,z,tx,ty,tz] (Ns/m, Ns/m,
Ns/m, Nms/rad, Nms/rad, Nms/rad) All other entries will be set to 0. All damping values
along the diagonal should be non-negative.
max_force_mag google.protobuf.DoubleValue Maximum force magnitude in Newtons we're allowed to exert. If the tool deviates such that
the magnitude of the requested force would exceed this threshold, saturate the requested
force. If this value is not set, a default of 60N will be used.
max_torque_mag google.protobuf.DoubleValue Maximum torque magnitude in Newton meters we're allowed to exert. If the tool deviates
such that the magnitude of the requested torque would exceed this threshold, saturate the
requested torque. If this value is not set, a default of 15Nm will be used.
disable_safety_check google.protobuf.BoolValue Set to True to disable cancelling the trajectory for unsafe behaviors. NOTE: If
disable_safety_check is set to True, the robot may damage itself or the environment.
Extreme caution should be used when setting disable_safety_check to True.

ArmJointMoveCommand

Specify a set of joint angles to move the arm.

ArmJointMoveCommand.Feedback

Field Type Label Description
status ArmJointMoveCommand.Feedback.Status Current status of the request.
planner_status ArmJointMoveCommand.Feedback.PlannerStatus Current status of the trajectory planner.
planned_points ArmJointTrajectoryPoint repeated Based on the user trajectory, the planned knot points that obey acceleration and
velocity constraints. If these knot points don't match the requested knot points,
consider increasing velocity/acceleration limits, and/or staying further away from
joint position limits. In situations where we've modified you last point, we append
a minimum time trajectory (that obeys the velocity and acceleration limits) from the
planner's final point to the requested final point. This means that the length of
planned_points may be one point larger than the requested. The planner works on a
moving window of up to 10 points from the input trajectory, so the length of planned
points will be at most 10, and its contents will change over time for long trajectories.
time_to_goal google.protobuf.Duration Returns amount of time remaining until the joints are at the goal position. For
multiple point trajectories, this is the time remaining to the final point.

ArmJointMoveCommand.Request

Field Type Label Description
trajectory ArmJointTrajectory Note: Sending a single point empty trajectory will cause the arm to freeze in place. This
is an easy way to lock the arm in its current configuration.

ArmJointPosition

Position of our 6 arm joints in radians. If a joint angle is not specified, we will use the joint position at time the message is received on robot.

Field Type Label Description
sh0 google.protobuf.DoubleValue
sh1 google.protobuf.DoubleValue
el0 google.protobuf.DoubleValue
el1 google.protobuf.DoubleValue
wr0 google.protobuf.DoubleValue
wr1 google.protobuf.DoubleValue

ArmJointTrajectory

This allows a user to move the arm’s joints directly. Each of the arm’s joints will never move faster than maximum_velocity and never accelerate faster than maximum_acceleration. The user can specify a trajectory of joint positions and optional velocities for the arm to follow. The trajectory will be acted upon as follows. If a single trajectory point with no time is provided, the arm will take the joint currently furthest away from the goal pose and plan a minimum time trajectory such that the joint accelerates at maximum_acceleration, coasts at maximum_velocity, and decelerates at maximum_acceleration. The other joints will accelerate at maximum_acceleration, but then coast at a slower speed such that all joints arrive at the goal pose simultaneously with zero velocity. If the user provides trajectory times, the robot will fit a piece-wise cubic trajectory (continuous position and velocity) to the user’s requested positions and (optional) velocities. If the requested trajectory is not achievable because it will violate position limits or the maximum_velocity or maximum_acceleration, the robot will pick a trajectory that is as close as possible to the user requested without violating velocity or acceleration limits.

If the robot is not hitting the desired trajectory, try increasing the time between knot points, increasing the max velocity and acceleration, or only specifying joint position goals without a velocity

Field Type Label Description
points ArmJointTrajectoryPoint repeated The points in our trajectory. (positions, (optional) velocity, (optional) time)
reference_time google.protobuf.Timestamp All trajectory points 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.
maximum_velocity google.protobuf.DoubleValue The maximum velocity in rad/s that any joint is allowed to achieve.
If this field is not set, a default value will be used.
maximum_acceleration google.protobuf.DoubleValue The maximum acceleration in rad/s^2 that any joint is allowed to
achieve. If this field is not set, a default value will be used.

ArmJointTrajectoryPoint

A set of joint angles and velocities that can be used as a point within a joint trajectory.

Field Type Label Description
position ArmJointPosition Desired joint angles in radians
velocity ArmJointVelocity Optional desired joint velocities in radians / sec
time_since_reference google.protobuf.Duration The time since reference at which we wish to achieve this position / velocity

ArmJointVelocity

Velocity of our 6 arm joints in radians / second. If a velocity for a joint is specified, velocities for all joints we are trying to move must be specified.

Field Type Label Description
sh0 google.protobuf.DoubleValue
sh1 google.protobuf.DoubleValue
el0 google.protobuf.DoubleValue
el1 google.protobuf.DoubleValue
wr0 google.protobuf.DoubleValue
wr1 google.protobuf.DoubleValue

ArmParams

Parameters common across arm commands.

Field Type Label Description
disable_body_force_limiter google.protobuf.BoolValue Whether or not to disable the body force limiter running on the robot. By default, this is
/ on, and the chance that the body falls over because the arm makes contact in the world is
/ low. If this is purposely disabled (by setting disable_body_force_limiter to True), the arm
/ may be able to accelerate faster, and apply more force to the world and to objects than
/ usual, but there is also added risk of the robot falling over.

ArmStopCommand

Stop the arm applying minimal forces to the world. For example, if the arm is in the middle of opening a heavy door and a stop command is sent, the arm will comply and let the door close.

ArmStopCommand.Feedback

Stop command provides no feedback

ArmStopCommand.Request

Stop command takes no arguments.

ArmVelocityCommand

When controlling the arm with a joystick, because of latency it can often be better to send velocity commands rather than position commands. Both linear and angular velocity can be specified. The linear velocity can be specified in a cylindrical frame around the shoulder or with a specified frame.

ArmVelocityCommand.CartesianVelocity

Field Type Label Description
frame_name string The frame to express our velocities in
velocity_in_frame_name Vec3 The x-y-z velocity of the hand (m/s) with respect to the frame

ArmVelocityCommand.CylindricalVelocity

Field Type Label Description
linear_velocity CylindricalCoordinate The linear velocities for the end-effector are specified in unitless cylindrical
/ coordinates. The origin of the cylindrical coordinate system is the base of the arm
/ (shoulder). The Z-axis is aligned with gravity, and the X-axis is the unit vector from
/ the shoulder to the hand-point. This construction allows for 'Z'-axis velocities to
/ raise/lower the hand, 'R'-axis velocities will cause the hand to move towards/away from
/ the shoulder, and 'theta'-axis velocities will cause the hand to travel
/ clockwise/counter-clockwise around the shoulder. Lastly, the command is unitless, with
/ values for each axis specified in the range [-1, 1]. A value of 0 denotes no velocity
/ and values of +/- 1 denote maximum velocity (see max_linear_velocity).
max_linear_velocity google.protobuf.DoubleValue The maximum velocity in meters / second for the hand.
/ If unset and default value of 0 received, will set max_linear_velocity to 0.5 m/s.

ArmVelocityCommand.Feedback

ArmVelocityCommand provides no feedback

ArmVelocityCommand.Request

Field Type Label Description
cylindrical_velocity ArmVelocityCommand.CylindricalVelocity
cartesian_velocity ArmVelocityCommand.CartesianVelocity
angular_velocity_of_hand_rt_odom_in_hand Vec3 The angular velocity of the hand frame measured with respect to the odom frame, expressed
in the hand frame. A 'X' rate will cause the hand to rotate about its x-axis, e.g. the
final wrist twist joint will rotate. And similarly, 'Y' and 'Z' rates will cause the hand
to rotate about its y and z axis respectively. \
The units should be rad/sec.
maximum_acceleration google.protobuf.DoubleValue Optional maximum acceleration magnitude of the end-effector. (m/s^2)
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.

GazeCommand

Move the hand in such a way to point it at a position in the world.

GazeCommand.Feedback

Field Type Label Description
status GazeCommand.Feedback.Status Current status of the command.
gazing_at_target bool If we are gazing at the target
Rotation from the current gaze point to the trajectory's end [radians]
gaze_to_target_rotation_measured float
hand_position_at_goal bool If the hand's position is at the goal.
Distance from the hand's current position to the trajectory's end [meters]
hand_distance_to_goal_measured float
hand_roll_at_goal bool If the hand's roll is at the goal.
Rotation from the current hand position to the desired roll at the trajectory's end
[radians]
hand_roll_to_target_roll_measured float

GazeCommand.Request

Field Type Label Description
target_trajectory_in_frame1 Vec3Trajectory Point(s) to look at expressed in frame1.
frame1_name string
tool_trajectory_in_frame2 SE3Trajectory Optional, desired pose of the tool expressed in frame2. Will be constrained to 'look at'
the target regardless of the requested orientation.
frame2_name string
wrist_tform_tool SE3Pose The transformation of the tool pose relative to the parent link (wrist).
If the field is left unset, the transform will default to:
The position is wrist_tform_hand.position() [20 cm translation in wrist x].
The rotation is wrist_tform_hand_camera.rotation() [-9 degree pitch about wrist y].
target_trajectory_initial_velocity google.protobuf.DoubleValue Optional velocity to move the target along the shortest path from the gaze's starting
position to the first point in the target trajectory.
maximum_acceleration google.protobuf.DoubleValue Optional Maximum acceleration magnitude of the end-effector.
Valid ranges (0, 20]
max_linear_velocity google.protobuf.DoubleValue Optional Maximum linear velocity magnitude of the end-effector. (m/s)
max_angular_velocity google.protobuf.DoubleValue Optional Maximum angular velocity magnitude of the end-effector. (rad/s)

NamedArmPositionsCommand

Command the arm move to a predefined configuration.

NamedArmPositionsCommand.Feedback

Field Type Label Description
status NamedArmPositionsCommand.Feedback.Status Current status of the request.

NamedArmPositionsCommand.Request

Field Type Label Description
position NamedArmPositionsCommand.Positions

ArmCartesianCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_TRAJECTORY_COMPLETE 1 Tool frame has reached the end of the trajectory within tracking error bounds.
STATUS_IN_PROGRESS 2 Robot is attempting to reach the target.
STATUS_TRAJECTORY_CANCELLED 3 Tool frame exceeded maximum allowable tracking error from the desired trajectory.
STATUS_TRAJECTORY_STALLED 4 The arm has stopped making progress to the goal. Note, this does not cancel the
trajectory. For example, if the requested goal is too far away, walking the base
robot closer to the goal will cause the arm to continue along the trajectory once the
goal point is inside the workspace.

ArmCartesianCommand.Request.AxisMode

If an axis is set to position mode (default), read desired from SE3Trajectory trajectory command. If mode is set to Force, read desired from WrenchTrajectory wrench_trajectory command. This supports hybrid control of the arm where users can specify, for example, Z to be in force control with X and Y in position control. The elements are expressed in the same task_frame as the trajectories.

Name Number Description
AXIS_MODE_POSITION 0
AXIS_MODE_FORCE 1

ArmImpedanceCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_TRAJECTORY_COMPLETE 1 Tool frame has reached the end of the trajectory, and is close to the desired_tool
in directions with high stiffness and no feed forwards
STATUS_IN_PROGRESS 2 Robot is moving along the desired_tool trajectory
STATUS_TRAJECTORY_STALLED 3 The arm has stopped making progress to the goal and the measured tool frame is far
from the desired_tool along directions where we expect good tracking
STATUS_TRAJECTORY_CANCELLED 4 Detected an arm instability, so the commanded motion was cancelled. Consider lowering
stiffness or lowering both stiffness and damping to improve stability.

ArmJointMoveCommand.Feedback.PlannerStatus

Name Number Description
PLANNER_STATUS_UNKNOWN 0 PLANNER_STATUS_UNKNOWN should never be used. If used, an internal error has happened.
PLANNER_STATUS_SUCCESS 1 A solution passing through the desired points and obeying the constraints was found.
PLANNER_STATUS_MODIFIED 2 The planner had to modify the desired points in order to obey the constraints. For
example, if you specify a 1 point trajectory, and tell it to get there in a really
short amount of time, but haven't set a high allowable max velocity / acceleration,
the planner will do its best to get as close as possible to the final point, but
won't reach it. In situations where we've modified you last point, we append a
minimum time trajectory (that obeys the velocity and acceleration limits) from the
planner's final point to the requested final point.
PLANNER_STATUS_FAILED 3 Failed to compute a valid trajectory, will go to first point instead. It is possible
that our optimizer till fail to solve the problem instead of returning a sub-optimal
solution. This is un-likely to occur.

ArmJointMoveCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened
STATUS_COMPLETE 1 The arm is at the desired configuration.
STATUS_IN_PROGRESS 2 Robot is re-configuring arm to get to desired configuration.
STATUS_STALLED 3 The arm has stopped making progress towards the goal. This could be because it is
avoiding a collision or joint limit.

GazeCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_TRAJECTORY_COMPLETE 1 Robot is gazing at the target at the end of the trajectory.
STATUS_IN_PROGRESS 2 Robot is re-configuring arm to gaze at the target.
STATUS_TOOL_TRAJECTORY_STALLED 3 The arm has stopped making progress to the goal pose for the tool.
Note, this does not cancel the trajectory. For example, if the requested goal is too
far away, walking the base robot closer to the goal will cause the arm to continue
along the trajectory once it can continue.

NamedArmPositionsCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_COMPLETE 1 The arm is at the desired configuration.
STATUS_IN_PROGRESS 2 Robot is re-configuring arm to get to desired configuration.
STATUS_STALLED_HOLDING_ITEM 3 Some requests may not execute if the gripper is holding an item declared not
stowable, e.g. POSITIONS_STOW with carry_state == CARRY_STATE_CARRIABLE. In these
situations, Spot will instead run an ArmStopCommand request while the blocking
condition remains true. Clearing the condition will cause the request to proceed and
the arm will start moving.

NamedArmPositionsCommand.Positions

Name Number Description
POSITIONS_UNKNOWN 0 Invalid request; do not use.
POSITIONS_CARRY 1 The carry position is a damped, force limited position close to stow, with the hand
slightly in front of the robot.
POSITIONS_READY 2 Move arm to ready position. The ready position is defined with the hand directly in
front of and slightly above the body, with the hand facing forward in the robot body +X
direction.
POSITIONS_STOW 3 Stow the arm, safely. If the robot is holding something, it will freeze the arm instead
of stowing. Overriding the carry_state to CARRY_STATE_CARRIABLE_AND_STOWABLE, will allow
the robot to stow the arm while grasping an item.

Top

bosdyn/api/arm_surface_contact.proto

ArmSurfaceContact

ArmSurfaceContact lets you accurately move the robot’s arm in the world while having some ability to perform force control. This mode is useful for drawing, wiping, and other similar behaviors.

The message is similar to the ArmCartesianCommand message, which you can look at for additional details.

ArmSurfaceContact.Feedback

ArmSurfaceContact.Request

Field Type Label Description
root_frame_name string The root frame is used to set the optional task frame that all trajectories are
specified with respect to. If the optional task frame is left un-specified it defaults
to the identity transform and the root frame becomes the task frame.
wrist_tform_tool SE3Pose The tool pose relative to the parent link (wrist).
Defaults to
[0.19557 0 0]
[1 0 0 0]
a frame with it's origin slightly in front of the gripper's palm plate aligned with wrists orientation.
root_tform_task SE3Pose The fields below are specified in this optional task frame. If unset int defaults
to the identity transform and all quantities are therefore expressed in the root_frame_name.
pose_trajectory_in_task SE3Trajectory A 3D pose trajectory for the tool expressed in the task frame, e.g. task_T_tool.
This pose trajectory is optional if requesting a pure wrench at the end-effector,
otherwise required for position or mixed force/position end-effector requests.
maximum_acceleration google.protobuf.DoubleValue Optional Maximum acceleration magnitude of the end-effector.
Valid ranges (0, 20]
max_linear_velocity google.protobuf.DoubleValue Optional Maximum linear velocity magnitude of the end-effector. (m/s)
max_angular_velocity google.protobuf.DoubleValue Optional Maximum angular velocity magnitude of the end-effector. (rad/s)
max_pos_tracking_error google.protobuf.DoubleValue Maximum allowable tracking error of the tool frame from the desired trajectory
before the arm will stop moving and cancel the rest of the trajectory. When this limit is exceeded, the
hand will stay at the pose it was at when it exceeded the tracking error, and any other part of the
trajectory specified in the rest of this message will be ignored.
max position tracking error in meters
max_rot_tracking_error google.protobuf.DoubleValue max orientation tracking error in radians
force_remain_near_current_joint_configuration bool
preferred_joint_configuration ArmJointPosition
x_axis ArmSurfaceContact.Request.AxisMode
y_axis ArmSurfaceContact.Request.AxisMode
z_axis ArmSurfaceContact.Request.AxisMode
press_force_percentage Vec3 Amount of force to use on each axis, from 0 (no force) to 1.0 (maximum force), can also
be negative. Full range: [-1.0, 1.0]
xy_admittance ArmSurfaceContact.Request.AdmittanceSetting Admittance settings for each axis in the admittance frame.
z_admittance ArmSurfaceContact.Request.AdmittanceSetting
xy_to_z_cross_term_admittance ArmSurfaceContact.Request.AdmittanceSetting Cross term, making force in the XY axis cause movement in the z-axis.
By default is OFF
Setting this value will make the arm move in the negative Z-axis whenever it feels force in
the XY axis.
bias_force_ewrt_body 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 field, because if you lie to the robot, it can
fall over.
gripper_command ClawGripperCommand.Request Gripper control
is_robot_following_hand bool Set to true to have robot is walk around to follow the hand.

ArmSurfaceContact.Request.AdmittanceSetting

Parameters for controlling admittance. By default, the robot will stop moving the arm when it encounters resistance. You can control that reaction to make the robot stiffer or less stiff by changing the parameters.

Name Number Description
ADMITTANCE_SETTING_UNKNOWN 0
ADMITTANCE_SETTING_OFF 1 No admittance.
ADMITTANCE_SETTING_NORMAL 2 Normal reaction to touching things in the world
ADMITTANCE_SETTING_LOOSE 3 Robot will not push very hard against objects
ADMITTANCE_SETTING_STIFF 4 Robot will push hard against the world
ADMITTANCE_SETTING_VERY_STIFF 5 Robot will push very hard against the world

ArmSurfaceContact.Request.AxisMode

If an axis is set to position mode (default), read desired from SE3Trajectory command. If mode is set to force, use the “press_force_percentage” field to determine force.

Name Number Description
AXIS_MODE_POSITION 0
AXIS_MODE_FORCE 1

Top

bosdyn/api/arm_surface_contact_service.proto

ArmSurfaceContactCommand

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

ArmSurfaceContactResponse

Field Type Label Description
header ResponseHeader Common response header.

ArmSurfaceContactService

Method Name Request Type Response Type Description
ArmSurfaceContact ArmSurfaceContactCommand ArmSurfaceContactResponse

Top

bosdyn/api/auth.proto

GetAuthTokenRequest

The GetAuthToken request message includes login information for the robot.

Field Type Label 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 necessary if token is set.
token string Token to authenticate with. Can be used in place of the password, to re-mint a token.

GetAuthTokenResponse

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

Field Type Label 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 happened.
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.

Top

bosdyn/api/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.

Top

bosdyn/api/auto_return/auto_return.proto

ConfigureRequest

Configure the AutoReturn system.

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
leases bosdyn.api.Lease repeated Leases that AutoReturn may use to accomplish its goals when AutoReturn automatically
triggers. If left empty, AutoReturn will not automatically trigger.
params Params Parameters to use when AutoReturn automatically triggers.
clear_buffer bool Forget any buffered locations the robot may be remembering. Defaults to false.
Set to true if the robot has just crossed an area it should not traverse in AutoReturn.

ConfigureResponse

Response to a configuration request.

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status ConfigureResponse.Status Return status for the request.
invalid_params Params If status is STATUS_INVALID_PARAMS, this contains the settings that were invalid.

GetConfigurationRequest

Ask for the current configuration.

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

GetConfigurationResponse

Response to a “get configuration” request.

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
enabled bool A simple yes/no, will AutoReturn automatically trigger.
request ConfigureRequest The most recent successful ConfigureRequest.
Will be empty if service has not successfully been configured.

Params

Parameters to AutoReturn actions.

Field Type Label Description
mobility_params google.protobuf.Any Robot-specific mobility parameters to use.
For example, see bosdyn.api.spot.MobilityParams.
max_displacement float Allow AutoReturn to move the robot this far in the XY plane from the location where
AutoReturn started. Travel along the Z axis (which is gravity-aligned) does not count.
Must be > 0.

meters
max_duration google.protobuf.Duration Optionally specify the maximum amount of time AutoReturn can take.
If this duration is exceeded, AutoReturn will stop trying to move the robot.
Omit to try indefinitely. Robot may become stuck and never take other comms loss actions!

StartRequest

Start AutoReturn behavior now.

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
leases bosdyn.api.Lease repeated Leases that AutoReturn may use to accomplish its goals.
If left empty, use the leases specified in ConfigureRequest.
If empty and no leases have been specified by ConfigureRequest, the response will have a
CODE_INVALID_REQUEST in the header.
params Params Parameters to use.
If left empty, use the params specified in ConfigureRequest.
If empty and no params have been specified by ConfigureRequest, the response will have a
CODE_INVALID_REQUEST in the header.

StartResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status StartResponse.Status
invalid_params Params If status is STATUS_INVALID_PARAMS, this contains the settings that were invalid.

ConfigureResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_INVALID_PARAMS 2

StartResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_INVALID_PARAMS 2

Top

bosdyn/api/auto_return/auto_return_service.proto

AutoReturnService

Method Name Request Type Response Type Description
Configure ConfigureRequest ConfigureResponse Configure the service.
GetConfiguration GetConfigurationRequest GetConfigurationResponse Get the current configuration.
Start StartRequest StartResponse Start AutoReturn now.

Top

bosdyn/api/autowalk/autowalk.proto

CompileAutowalkRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
walk Walk Walk to compile.
treat_warnings_as_errors bool If this is set to true, mission compilation will fail if the Walk contains parameters that
are set incorrectly. This can be useful during development to help the developer find issues
with their client (e.g., suppose the client UI allows a user to set a parameter incorrectly).
If this is set to false, mission compilation is more likely to succeed for the same Walk
because any parameters that are both incorrect and modifiable are modified during mission
compilation.

CompileAutowalkResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status CompileAutowalkResponse.Status Result of compiling the mission.
root bosdyn.api.mission.Node Root node of compiled walk.
element_identifiers ElementIdentifiers repeated There will be one ElementIdentifier for each Element in the input Walk.
The index of each ElementIdentifier corresponds to the index of the Element in the input
Walk. Skipped elements will have default values for id's. (0 and empty string)
failed_elements CompileAutowalkResponse.FailedElementsEntry repeated If certain elements failed compilation, they will be reported back in this field.
The map correlates the index of the Element in the input Walk to the FailedElement.
docking_node NodeIdentifier Final docking node.
loop_node NodeIdentifier Node that contains the main sequence of actions performed in the walk.
In continuous playback mode, the walk repeats when this node completes.

CompileAutowalkResponse.FailedElementsEntry

Field Type Label Description
key int32
value FailedElement

ElementIdentifiers

Field Type Label Description
root_id NodeIdentifier Deprecated. Identifiable data for the root node of the element.
Deprecated as of 4.0. Please use navigation_id instead.
action_id NodeIdentifier Identifiable data for action node of the element.
navigation_id NodeIdentifier Identifiable data for the navigation node of the element.

FailedElement

Field Type Label Description
errors string repeated The reasons why this element failed. May not be provided by all elements.
warnings string repeated Compile time modification that resolved error(s).

LoadAutowalkRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
walk Walk Walk to compile
leases bosdyn.api.Lease repeated Leases that will be needed to validate the mission.
Usually, no leases are necessary for validation, and this can be left empty.
treat_warnings_as_errors bool If this is set to true, mission compilation will fail if the Walk contains parameters that
are set incorrectly. This can be useful during development to help the developer find issues
with their client (e.g., suppose the client UI allows a user to set a parameter incorrectly).
If this is set to false, mission compilation is more likely to succeed for the same Walk
because any parameters that are both incorrect and modifiable are modified during mission
compilation.

LoadAutowalkResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status LoadAutowalkResponse.Status Result of loading the mission.
lease_use_results bosdyn.api.LeaseUseResult repeated 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 bosdyn.api.mission.FailedNode repeated If certain nodes failed compilation or validation, they will be reported back in this field.
element_identifiers ElementIdentifiers repeated There will be one ElementIdentifier for each Element in the input Walk.
The index of each ElementIdentifier corresponds to the index of the Element in the input
Walk. Skipped elements will have default values for id's. (0 and empty string)
failed_elements LoadAutowalkResponse.FailedElementsEntry repeated If certain elements failed compilation, they will be reported back in this field.
The map correlates the index of the Element in the input Walk to the FailedElement.
mission_id int64 Mission ID assigned by the mission service.
docking_node NodeIdentifier Final docking node.
loop_node NodeIdentifier Node that contains the main sequence of actions performed in the walk.
In continuous playback mode, the walk repeats when this node completes.

LoadAutowalkResponse.FailedElementsEntry

Field Type Label Description
key int32
value FailedElement

NodeIdentifier

Field Type Label Description
node_id int64 Unique integer set by the mission service when loading a mission.
user_data_id string Unique string set by the autowalk service when compiling a walk.

CompileAutowalkResponse.Status

Possible results of compiling a walk to mission.

Name Number Description
STATUS_UNKNOWN 0 Invalid status, do not use.
STATUS_OK 1 Compilation succeeded.
STATUS_COMPILE_ERROR 2 Compilation failed. The walk was malformed.

LoadAutowalkResponse.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 Compilation failed. The walk was malformed.
STATUS_VALIDATE_ERROR 3 Load-time validation failed. Some part of the mission was unable to initialize.

Top

bosdyn/api/autowalk/autowalk_service.proto

AutowalkService

Method Name Request Type Response Type Description
CompileAutowalk .bosdyn.api.DataChunk stream .bosdyn.api.DataChunk stream Compile a walk into a mission.
Input DataChunks should deserialize into a CompileAutowalkRequest.
Output DataChunks should deserialize into a CompileAutowalkResponse.
This rpc is stateless.
LoadAutowalk .bosdyn.api.DataChunk stream .bosdyn.api.DataChunk stream Compile a walk into a mission then load to mission service.
Input DataChunks should deserialize into a LoadAutowalkRequest.
Output DataChunks should deserialize into a LoadAutowalkResponse.

Top

bosdyn/api/autowalk/walks.proto

Action

An Action is what the robot should do at a location. For example, the user may desire that the robot perform a laser scan at a given waypoint.

Field Type Label Description
sleep Action.Sleep
data_acquisition Action.DataAcquisition
remote_grpc Action.RemoteGrpc
execute_choreography Action.ExecuteChoreography
node bosdyn.api.mission.Node This field can be used to specify a behavior tree as an action. If the user had
two callbacks they would like to run simultaneously at the waypoint this action
is associated with, they could use create a behavior tree inside Node with both
callbacks embedded in a simple parallel.
The downside of using node, is that editors might not support editing parameters
directly.

Action.DataAcquisition

For actions associated with the Data Acquisition Service.

Field Type Label Description
acquire_data_request bosdyn.api.AcquireDataRequest The autowalk service replaces the action_name field in the CaptureActionId with the
element name.
completion_behavior bosdyn.api.mission.DataAcquisition.CompletionBehavior
last_known_capabilities bosdyn.api.AcquisitionCapabilityList Last known Data Acquisition capabilities.
record_time_images bosdyn.api.ImageCaptureAndSource repeated Any images taken at action creation time. For DataAcquisition actions, this includes:
- Any images in the Data Acquisition capture.
- Any images that are inputs to NCB workers that are in the Data Acquisition capture.
- Any images that a Data Acquisition plugin in the Data Acquisition capture requests a
region of interest for.

Note that both this message and AcquisitionCapabilityList will contain the
Spec for images sources. This message will contain the spec at record time,
while last_known_capabilities should be updated as time progresses and services
evolve.

This data is meant to allow UI's to give users context about their actions, AND
provide them a canvas to edit region of interests with after the fact. It is
not used at mission playback time.

Action.ExecuteChoreography

Field Type Label Description
sequence_name string The name of the sequence to play.

Action.RemoteGrpc

Field Type Label Description
service_name string Name of the service in the directory.
rpc_timeout google.protobuf.Duration Timeout of any single RPC. If the timeout is exceeded, the RPC will fail. The mission
service treats each failed RPC differently:
- EstablishSession: An error is returned in LoadMission.
- Tick: The RPC is retried.
- Stop: The error is ignored, and the RPC is not retried.
Omit for a default of 60 seconds.
lease_resources string repeated Resources that we will need leases on.
inputs bosdyn.api.mission.KeyValue repeated Deprecated. 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.
DEPRECATED as of 3.3. Please use 'parameters' instead.
parameters bosdyn.api.CustomParamCollection All specifications and any values chosen at record time.
record_time_images bosdyn.api.ImageCaptureAndSource repeated Any images taken at action creation time. For RemoteGRPC's, this will only happen
if the RemoteGRPC advertises parameters that require a region of interest for a specific
camera.

This data is meant to allow UI's to give users context about their actions, AND
provide them a canvas to edit region of interests with after the fact. It is
not used at mission playback time.

Action.Sleep

The robot does nothing but wait while also performing its ActionWrapper(s). For example, if the user wants the robot to pose for some amount of time (while doing nothing else), they would populate an ActionWrapper with Pose and set the desired duration here accordingly.

Field Type Label Description
duration google.protobuf.Duration

ActionWrapper

An ActionWrapper is what the robot should do prior to and during an action. For example, the user may desire that the robot stand in such a way that its z-axis is aligned with the gravity vector, even though it is standing on an incline.

Field Type Label Description
robot_body_sit ActionWrapper.RobotBodySit
robot_body_pose ActionWrapper.RobotBodyPose
spot_cam_led ActionWrapper.SpotCamLed
spot_cam_ptz ActionWrapper.SpotCamPtz
arm_sensor_pointing ActionWrapper.ArmSensorPointing
spot_cam_alignment ActionWrapper.SpotCamAlignment
gripper_camera_params ActionWrapper.GripperCameraParams
gripper_command ActionWrapper.GripperCommand

ActionWrapper.ArmSensorPointing

Position the body and perform a joint move and cartesian command in target frame

Field Type Label Description
joint_trajectory bosdyn.api.ArmJointTrajectory Arm Joint Move Command
The joint trajectory to execute in the initial rough pointing joint move.
wrist_tform_tool bosdyn.api.SE3Pose Arm Cartesian Command
The tool pose relative to the parent link (wrist).
Defaults to a frame with it's origin slightly in front of the gripper's palm plate
aligned with the wrist's orientation.
pose_trajectory_rt_target bosdyn.api.SE3Trajectory A 3D pose trajectory for the tool expressed in target frame,
target_tform_measured_offset bosdyn.api.SE2Pose Robot desired stance relative to waypoint
This is taken by measuring the average of the footprints
in body frame at the time of waypoint creation.
This is used to generate the stance command.
Target == waypoint.
This assumes the waypoint is gravity aligned.
body_assist_params bosdyn.api.spot.BodyControlParams.BodyAssistForManipulation Body mobility params during cartesian move
force_stow_override bool If true, the arm will stow after this action no matter what.
If false, the arm will only stow if the next action is far away.

ActionWrapper.GripperCameraParams

Set the camera params of the gripper camera

Field Type Label Description
params bosdyn.api.GripperCameraParams

ActionWrapper.GripperCommand

Field Type Label Description
request bosdyn.api.GripperCommand.Request
disable_post_action_close bool By default, any action that includes a GripperCommand action wrapper will run
the specified command BEFORE the action is run. By default, after the action
is run the gripper will be closed. This behavior can be turned off by setting
this flag to true.

ActionWrapper.RobotBodyPose

Pose the robot prior to performing the action

Field Type Label Description
target_tform_body bosdyn.api.SE3Pose If your Target is a graph_nav waypoint, this pose will be relative
to the waypoint you are navigating to. If no target was specified,
this parameter will be ignored and the robot will stand in a generic
pose.

ActionWrapper.RobotBodySit

Sit the robot prior to performing the action

ActionWrapper.SpotCamAlignment

Align SpotCam to a waypoint. Cannot be used with SpotCamPtz or RobotBodyPose

Field Type Label Description
alignments ActionWrapper.SpotCamAlignment.Alignment repeated List of alignments to perform
target_tform_sensor bosdyn.api.SE3Pose Desired transform from the sensor to the target
final_zoom float Final zoom the camera should be after all alignments have finished
target_sensor_ids string repeated Optional list of sensor names which should be unobstructed after alignment

ActionWrapper.SpotCamAlignment.Alignment

Field Type Label Description
zoom float Camera zoom parameter
sensor_id string Sensor to use for alignment
scene_object_id string
is_skipped bool If true, this alignment will be skipped during playback
focus_state bosdyn.api.spot_cam.PtzFocusState Focus state used during alignment. Defaults to auto-focus.

ActionWrapper.SpotCamLed

Set the brightness of the LEDs on the SpotCam.

Field Type Label Description
brightnesses ActionWrapper.SpotCamLed.BrightnessesEntry repeated There are four LEDs at indices [0, 3]. The brightness for each LED
may be set between [0.0, 1.0], where 0 is off and 1 is full
brightness.

ActionWrapper.SpotCamLed.BrightnessesEntry

Field Type Label Description
key int32
value float

ActionWrapper.SpotCamPtz

Set the pan, tilt, and zoom of the SpotCam.

Field Type Label Description
ptz_position bosdyn.api.spot_cam.PtzPosition See bosdyn/api/spot_cam

BatteryMonitor

If your mission has docks, autowalk can pause the mission to return to the dock if the battery gets too low. Use this message to control when this behavior happens.

Field Type Label Description
battery_start_threshold float Once charging, the robot will continue to charge until the battery
level is greater than or equal to this threshold, at which point in
time, the mission will start.
battery_stop_threshold float If the battery level is less than or equal to this threshold, the
robot will stop what it is currently doing and return to the dock.
Once the battery level is greater than or equal to the battery start
threshold, the mission will resume.

ChoreographyItems

Choreography elements required for the mission.

Field Type Label Description
choreography_sequences bosdyn.api.spot.ChoreographySequence repeated Any sequences we need to play the mission.
animated_moves bosdyn.api.spot.Animation repeated Any animations we need if we want to play the sequence.

Dock

The dock itself and the target associated with it

Field Type Label Description
dock_id uint32 The docking station ID of the dock corresponds to the number printed on the
fiducial, below the part of the fiducial that looks like a QR code.
Only fiducial IDs greater than or equal to 500 should be
used here because they are reserved for docks.
docked_waypoint_id string To maximize reliability, at record time, the client should dock the robot
while graph_nav is still recording. When the robot is finished docking,
the client should create a waypoint on top of the dock, while the robot is
docked, and then stop recording. The waypoint created while the
robot is sitting on the dock should be specified here.
target_prep_pose Target When it is time for the robot to dock, it will approach this target
before issuing docking commands. If the user is using graph_nav, the
final waypoint in the NavigateRoute OR the waypoint ID in the
NavigateTo MUST be at the docking prep pose. To do this, send a docking
command to move the robot to the docking prep pose. Then, create a
waypoint at the docking prep pose location. Graph_nav is responsible for
navigating the robot to the docking prep pose. Once the robot is in the
docking prep pose, the docking service does the rest.
prompt_duration google.protobuf.Duration At mission playback, if the robot is unable to reach the dock OR successfully
dock, the mission will let the operator know with a user question. If the operator
does not answer, the robot will safely power off. This parameter controls
how long the operator has to answer.
This parameter also controls how long robot will wait to retry to undock on
a failed undock.

Element

An Element is the basic building block of the autowalk.

Field Type Label Description
name string The name of an element may be anything, but it is good practice to choose
something that describes the physical location and action that is occurring
(e.g., boiler room laser scan).
target Target Location the robot should navigate to.
target_failure_behavior FailureBehavior Describes what to do if the robot fails to navigate to target.
action Action Action performed at target destination
action_wrapper ActionWrapper Actions performed by the robot and/or payloads prior to and during an action.
action_failure_behavior FailureBehavior Describes what to do if the robot fails to execute the action.
is_skipped bool Set to true to skip element.
battery_monitor BatteryMonitor If the mission requires more than one battery, the robot needs to return
to the dock and charge before it can complete the mission.
This field defines the battery percentage thresholds that at which the robot
should pause and resume mission execution.
Considering using various thresholds depending on the target's distance from the dock
action_duration google.protobuf.Duration Maximum duration of action execution time, including all wrappers.
If they take longer than this duration, the action will be considered a failure.
Not including, or including a zero duration will set the action to NOT have a
timeout.
id string Unique identifier for this element. This will be embedded in various Data Acquisition
captures and various logging bundles. This should be globally unique across all elements.

FailureBehavior

Field Type Label Description
retry_count int32 The mission can automatically retry navigating to a waypoint or
performing an action. Automatic retries can increase the probability of
successfully navigating to a waypoint, but may cause the robot to take
an unexpected path. Similarly, they can increase the probability of
successfully collecting data for an action, but also increase the amount
of time a mission takes. If the client does not want the robot to
automatically retry navigating to a waypoint or performing an action,
set this to 0. If the client wants the robot to automatically retry
navigating to a waypoint or performing an action, set this to the
desired number of retries. For example, if the client would like the
action to be retried once, set this equal to 1. If this is unset or set
to 0, no retry will occur.
prompt_duration google.protobuf.Duration At mission playback, if something fails (e.g., the robot gets stuck,
an action fails), the user will get all possible actions as options
in a question to choose from. If the user does not answer, the mission
will fall back to the default behavior after this timeout. The default
behaviors are defined by the default_behavior one_of. A minimum
duration of 10 seconds is enforced.
safe_power_off FailureBehavior.SafePowerOff
proceed_if_able FailureBehavior.ProceedIfAble
return_to_start_and_try_again_later FailureBehavior.ReturnToStartAndTryAgainLater
return_to_start_and_terminate FailureBehavior.ReturnToStartAndTerminate

FailureBehavior.ProceedIfAble

If a failure occurs and the prompt has not been answered, the robot will proceed to the next action if able to do so. This may lead to different behavior at mission playback than at mission recording (e.g., the robot may take a different route, the robot may fail to collect the data for an action).

FailureBehavior.ReturnToStartAndTerminate

Only available in missions with a dock! If robot can get back to the dock, it will, and if it does, the mission will end.

FailureBehavior.ReturnToStartAndTryAgainLater

Only available in missions with a dock! If a failure occurs and the prompt has not been answered, the robot will return to the start of the mission. Once at the start of the mission, the robot will attempt to dock. If successfully, robot will try again later after the specified delay.

Field Type Label Description
try_again_delay google.protobuf.Duration How long to wait at start of mission (or on dock) before trying again.
A minimum duration of 60 seconds is enforced.

FailureBehavior.SafePowerOff

If a failure occurs and the prompt has not been answered, the robot will sit down and power off. This is the safest option.

Field Type Label Description
request bosdyn.api.SafePowerOffCommand.Request

GlobalParameters

These parameters apply to the entire autowalk.

Field Type Label Description
group_name string If the mission contains data acquisitions, this will be their group name.
The actual group name used will include the specified group name, and additional
qualifiers to ensure its unique for each start of this mission.
should_autofocus_ptz bool If the mission contains SpotCAM PTZ actions, set this to true. At the start of the
mission (or if the robot falls), the SpotCAM PTZ autofocus will be reset, thereby
improving the quality of the subsequent PTZ captures.
self_right_attempts int32 The mission can automatically self-right the robot. Autonomous self-rights
can damage the robot, its payloads, and its surroundings. If the user
does not want the robot to self-right on its own, set this number to 0.
If the user does want the robot to self-right itself, the user may set a
maximum number of attempts so that the robot does not destroy itself by
repeatedly falling and getting up and falling again.
post_mission_callbacks Action.RemoteGrpc repeated The callbacks that will be executed at the end of the mission. Functionality that
is often found in post-mission callbacks includes uploading data to the cloud or
sending an email. The callbacks will be executed serially (first in, first executed).
skip_actions bool It can be useful to have the robot run a walk without collecting data.
If this boolean is set to true, the compiled mission will still navigate to the
target of each element, however it will not actually perform the associated
action & action wrappers.

PlaybackMode

The playback mode governs how many times the mission is played back (once or more), at what interval the playbacks should occur (e.g., every 2 hours), and if docking is involved, the battery level thresholds at which the robot should either (1) stop and charge or (2) start the playback process again.

Field Type Label Description
once PlaybackMode.Once
periodic PlaybackMode.Periodic
continuous PlaybackMode.Continuous

PlaybackMode.Continuous

The mission should be played continuously only stopping if a battery monitor stop threshold is crossed.

PlaybackMode.Once

The mission should be played back once.

Field Type Label Description
skip_docking_after_completion bool Boolean to allow the robot to not dock after completing a mission.

PlaybackMode.Periodic

The mission should be played back periodically.

Field Type Label Description
interval google.protobuf.Duration The interval is the time that will elapse between the mission
finishing and starting again. It is applied relative to the time at
which the mission finishes. For example, if the user sets the
interval to 2 hours, starts the mission at 12:00, and the mission
takes one hour (finishes at 13:00), the next mission would start at
15:00, NOT 14:00.
Next mission start time = current mission end time + interval
repetitions int32 The number of times the mission should be played back. If set to 1,
the interval no longer applies and the mission will be played back
once. If set to two or more, the mission will run that number of
times, with the amount of time between playbacks equal to the
interval. If set to zero, the mission will run "forever".

Target

A Target is the location the robot should navigate to.

Field Type Label Description
navigate_to Target.NavigateTo
navigate_route Target.NavigateRoute
relocalize Target.Relocalize If set, upon reaching the target the robot will perform an explicit relocalization.
This should increase the accuracy of the robots belief of it's position on the map.
After relocalizing, the robot will re-navigate to the target.
target_stow_behavior Target.TargetStowBehavior

Target.NavigateRoute

Tell the robot to follow a route to a waypoint. If the robot is off the route (i.e., “far” from the route) when NavigateRoute is sent, the robot may navigate in unexpected ways.

Field Type Label Description
route bosdyn.api.graph_nav.Route A route for the robot to follow.
travel_params bosdyn.api.graph_nav.TravelParams Parameters that define how to traverse and end the route. For
example, the user may decide how close to the destination waypoint
the robot needs to be in order to declare success.

Target.NavigateTo

Tell the robot to navigate to a waypoint. It will choose its route.

Field Type Label Description
destination_waypoint_id string A unique string corresponding to the waypoint ID that the robot
should go to.
travel_params bosdyn.api.graph_nav.TravelParams Parameters that define how to traverse and end the route. For
example, the user may decide how close to the destination waypoint
the robot needs to be in order to declare success.

Target.Relocalize

Field Type Label Description
set_localization_request bosdyn.api.graph_nav.SetLocalizationRequest Some SetLocalizationRequests require that waypoint snapshots contain full images.
Make sure your client is downloading / storing / uploading full snapshots if you
plan on using this feature in your client.

Walk

Field Type Label Description
global_parameters GlobalParameters Parameters that apply to the entire mission.
playback_mode PlaybackMode Governs the mode and frequency at which playbacks occur.
map_name string The name of the map this mission corresponds to.
mission_name string The name of the mission.
elements Element repeated The list of actions and their associated locations.
docks Dock repeated The docks the mission can dock at.
AT THE MOMENT AUTOWALK ONLY SUPPORTS A SINGLE DOCK.
However, this is subject to change.
id string Unique identifier for this walk. This will be embedded in various Data Acquisition captures
and various logging bundles. This should be globally unique across all walks.
choreography_items ChoreographyItems Choreography related dependencies (any sequences and animations a robot needs to play this walk).

Target.TargetStowBehavior

Name Number Description
TARGET_STOW_BEHAVIOR_UNKNOWN 0 Will default to TARGET_STOW_BEHAVIOR_AUTO
TARGET_STOW_BEHAVIOR_AUTO 1 Compiler will do some heuristics to figure out if we should stow.
Headed back to dock = stow
Headed to another action that doesn't use arm sensor pointing = stow
Headed to another action that uses arm sensor pointing and is far away = stow
Headed to another action that uses arm sensor pointing and is close = don't stow
TARGET_STOW_BEHAVIOR_NEVER 2 Never ever stow the arm on the way to this action.
TARGET_STOW_BEHAVIOR_ALWAYS 3 Always stow the arm on the way to this action.

Top

bosdyn/api/basic_command.proto

ArmDragCommand

ArmDragCommand.Feedback

Field Type Label Description
status ArmDragCommand.Feedback.Status

ArmDragCommand.Request

BatteryChangePoseCommand

Get the robot into a convenient pose for changing the battery

BatteryChangePoseCommand.Feedback

Field Type Label Description
status BatteryChangePoseCommand.Feedback.Status

BatteryChangePoseCommand.Request

Field Type Label Description
direction_hint BatteryChangePoseCommand.Request.DirectionHint

ConstrainedManipulationCommand

ConstrainedManipulationCommand.Feedback

Field Type Label Description
status ConstrainedManipulationCommand.Feedback.Status
desired_wrench_odom_frame Wrench Desired wrench in odom world frame, applied at hand frame origin
estimation_activated google.protobuf.BoolValue A boolean signal indicating constrained manipulation has seen
enough motion to estimate the constraint and that the wrench
is being applied along the estimated directions.

ConstrainedManipulationCommand.Request

Field Type Label Description
frame_name string Frame that the initial wrench will be expressed in
init_wrench_direction_in_frame_name Wrench Direction of the initial wrench to be applied
Depending on the task, either the force vector or the
torque vector are required to be specified. The required
vector should not have a magnitude of zero and will be
normalized to 1. For tasks that require the force vector,
the torque vector can still be specified as a non-zero vector
if it is a good guess of the axis of rotation of the task.
(for e.g. TASK_TYPE_SE3_ROTATIONAL_TORQUE task types.)
Note that if both vectors are non-zero, they have to be perpendicular.
Once the constrained manipulation system estimates the
constraint, the init_wrench_direction and frame_name
will no longer be used.
tangential_speed double Recommended values are in the range of [-4, 4] m/s
rotational_speed double Recommended values are in the range of [-4, 4] rad/s
force_limit google.protobuf.DoubleValue The limit on the force that is applied on any translation direction
Value must be positive
If unspecified, a default value of 40 N will be used.
torque_limit google.protobuf.DoubleValue The limit on the torque that is applied on any rotational direction
Value must be positive
If unspecified, a default value of 4 Nm will be used.
task_type ConstrainedManipulationCommand.Request.TaskType
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.
enable_robot_locomotion google.protobuf.BoolValue Whether to enable the robot to take steps during constrained manip to keep the hand in
the workspace.
control_mode ConstrainedManipulationCommand.Request.ControlMode
target_linear_position double Desired linear position to travel for task type
TASK_TYPE_R3_LINEAR_FORCE
target_angle double Desired rotation in task space for all tasks other than
TASK_TYPE_R3_LINEAR_FORCE
This angle is about the estimated axis of rotation.
accel_limit google.protobuf.DoubleValue Acceleration limit for the planned trajectory in the free task DOF.
Note that the units of this variable will be m/(s^2) or rad/(s^2) depending
on the choice of target_linear_position vs. target_angle above.
reset_estimator google.protobuf.BoolValue Constrained manipulation estimates the task frame given the observed initial motion.
Setting this to false saves and uses the estimation state from the previous
constrained manipulation move. This is true by default.

FollowArmCommand

The base will move in response to the hand’s location, allow the arm to reach beyond its current workspace. If the hand is moved forward, the body will begin walking forward to keep the base at the desired offset from the hand.

FollowArmCommand.Feedback

FollowArmCommand commands provide no feedback.

FollowArmCommand.Request

Field Type Label Description
body_offset_from_hand Vec3 Optional body offset from the hand.
For example, to have the body 0.75 meters behind the hand, use (0.75, 0, 0)
disable_walking bool Deprecated. DEPRECATED as of 3.1.
To reproduce the robot's behavior of disable_walking == true,
issue a StandCommand setting the enable_body_yaw_assist_for_manipulation and
enable_hip_height_assist_for_manipulation MobilityParams to true. Any combination
of the enable_*_for_manipulation are accepted in stand giving finer control of
the robot's behavior.

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.

JointCommand

JointCommand.Feedback

Field Type Label Description
status JointCommand.Feedback.Status
num_messages_received uint64 Number of UpdateRequest messages received through the stream

JointCommand.Request

Empty message, no paramaters required to activate.

JointCommand.UpdateRequest

Field Type Label Description
end_time google.protobuf.Timestamp The timestamp (in robot time) when the command will stop executing. This is a
required field and used to prevent runaway commands.
reference_time google.protobuf.Timestamp (Optional) joint trajectory reference time. See extrapolation_time for detailed
explanation. If unspecified, this will default to the time the command is received.
If the time is in the future, no extrapolation will be performed until that time
(extrapolation never goes backwards in time)
extrapolation_duration google.protobuf.Duration (Optional) joint trajectory extrapolation time. If specified, the robot will extrapolate
desired position based on desired velocity, starting at reference_time for at most
extrapolation_duration (or until end_time, whichever is sooner)
position float repeated Commanded joint details
velocity float repeated
load float repeated
gains JointCommand.UpdateRequest.Gains Gains are required to be specified on the first message. After that can be optionally
updated by filling out the gains message again. Partial updates of gains are not
supported, a full gain set must be specified each time.
user_command_key uint32 user_command_key is optional, but it can be used for tracking when commands take effect
on the robot and calculating latencies. Avoid using 0
velocity_safety_limit google.protobuf.FloatValue (Optional) Joint velocity safety limit. Possibly useful during initial development or
gain tuning. If the magnitude of any joint velocity passes the threshold the robot will
trigger a behavior fault and go into a safety state. Client must power down the robot or
clear the behavior fault via the Robot Command Service. Values less than or equal to 0
will be considered invalid and must be sent in every UpdateRequest for use.

JointCommand.UpdateRequest.Gains

Field Type Label Description
k_q_p float repeated position error proportional coefficient
k_qd_p float repeated velocity error proportional coefficient

RobotCommandFeedbackStatus

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 Label Description
status SE2TrajectoryCommand.Feedback.Status Current status of the command.
body_movement_status SE2TrajectoryCommand.Feedback.BodyMovementStatus Current status of how the body is moving
final_goal_status SE2TrajectoryCommand.Feedback.FinalGoalStatus Flag indicating if the final requested position was achievable.

SE2TrajectoryCommand.Request

Field Type Label 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 "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 Label 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 standing, it will first sit then power down. With appropriate request parameters and under limited scenarios, the robot may take additional steps to move to a safe position. The robot will not power down until it is in a sitting state.

SafePowerOffCommand.Feedback

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

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

SafePowerOffCommand.Request

Field Type Label Description
unsafe_action SafePowerOffCommand.Request.UnsafeAction

SelfRightCommand

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

SelfRightCommand.Feedback

Field Type Label Description
status SelfRightCommand.Feedback.Status

SelfRightCommand.Request

SelfRight command request takes no additional arguments.

SitCommand

Sit the robot down in its current position.

SitCommand.Feedback

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

SitCommand.Request

Sit command request takes no additional arguments.

Stance

Field Type Label Description
se2_frame_name string The frame name which the desired foot_positions are described in.
foot_positions Stance.FootPositionsEntry repeated Map of foot name to its x,y location in specified frame.
Required positions for spot: "fl", "fr", "hl", "hr".
accuracy float Required foot positional accuracy in meters
Advised = 0.05 ( 5cm)
Minimum = 0.02 ( 2cm)
Maximum = 0.10 (10cm)

Stance.FootPositionsEntry

Field Type Label Description
key string
value Vec2

StanceCommand

Precise foot placement This can be used to reposition the robots feet in place.

StanceCommand.Feedback

Field Type Label Description
status StanceCommand.Feedback.Status

StanceCommand.Request

Field Type Label 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.
stance Stance

StandCommand

The stand the robot up in its current position.

StandCommand.Feedback

The StandCommand will provide two feedback fields: status, and standing_state. Status reflects if the robot has four legs on the ground and is near a final pose. StandingState reflects if the robot has converged to a final pose and does not expect future movement.

Field Type Label Description
status StandCommand.Feedback.Status Current status of the command.
standing_state StandCommand.Feedback.StandingState What type of standing the robot is doing currently.

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.

ArmDragCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_DRAGGING 1 Robot is dragging.
STATUS_GRASP_FAILED 2 Robot is not dragging because grasp failed.
This could be due to a lost grasp during a drag, or because the gripper isn't in a
good position at the time of request. You'll have to reposition or regrasp and then
send a new drag request to overcome this type of error. Note: When requesting drag,
make sure the gripper is positioned in front of the robot (not to the side of or
above the robot body).
STATUS_OTHER_FAILURE 3 Robot is not dragging for another reason.
This might be because the gripper isn't holding an item.
You can continue dragging once you resolve this type of error (i.e. by sending an
ApiGraspOverride request). Note: When requesting drag, be sure to that the robot
knows it's holding something (or use APIGraspOverride to OVERRIDE_HOLDING).

BatteryChangePoseCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_COMPLETED 1 Robot is finished rolling
STATUS_IN_PROGRESS 2 Robot still in process of rolling over
STATUS_FAILED 3 Robot has failed to roll onto its side

BatteryChangePoseCommand.Request.DirectionHint

Name Number Description
HINT_UNKNOWN 0 Unknown direction, just hold still
HINT_RIGHT 1 Roll over right (right feet end up under the robot)
HINT_LEFT 2 Roll over left (left feet end up under the robot)

ConstrainedManipulationCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_RUNNING 1 Constrained manipulation is working as expected
STATUS_ARM_IS_STUCK 2 Arm is stuck, either force is being applied in a direction
where the affordance can't move or not enough force is applied
STATUS_GRASP_IS_LOST 3 The grasp was lost. In this situation, constrained manipulation
will stop applying force, and will hold the last position.

ConstrainedManipulationCommand.Request.ControlMode

Name Number Description
CONTROL_MODE_UNKNOWN 0
CONTROL_MODE_POSITION 1 Position control mode, either a linear or angular position is specified
and constrained manipulation moves to that position with a trapezoidal
trajectory that has the max velocity specified in task_speed
CONTROL_MODE_VELOCITY 2 Velocity control mode where constrained manipulation applies forces to
maintain the velocity specified in task_speed

ConstrainedManipulationCommand.Request.TaskType

Geometrical category of a task. See the constrained_manipulation_helper function for examples of each of these categories. For e.g. SE3_CIRCLE_FORCE_TORQUE corresponds to lever type objects.

Name Number Description
TASK_TYPE_UNKNOWN 0
TASK_TYPE_SE3_CIRCLE_FORCE_TORQUE 1 This task type corresponds to circular tasks where
both the end-effector position and orientation rotate about a circle to manipulate.
The constrained manipulation logic will generate forces and torques in this case.
Example tasks are: A lever or a ball valve with a solid grasp
This task type will require an initial force vector specified
in init_wrench_direction_in_frame_name. A torque vector can be specified
as well if a good initial guess of the axis of rotation of the task is available.
TASK_TYPE_R3_CIRCLE_EXTRADOF_FORCE 2 This task type corresponds to circular tasks that have an extra degree of freedom.
In these tasks the end-effector position rotates about a circle
but the orientation does not need to follow a circle (can remain fixed).
The constrained manipulation logic will generate translational forces in this case.
Example tasks are: A crank that has a loose handle and moves in a circle
and the end-effector is free to rotate about the handle in one direction.
This task type will require an initial force vector specified
in init_wrench_direction_in_frame_name.
TASK_TYPE_SE3_ROTATIONAL_TORQUE 3 This task type corresponds to purely rotational tasks.
In these tasks the orientation of the end-effector follows a circle,
and the position remains fixed. The robot will apply a torque at the
end-effector in these tasks.
Example tasks are: rotating a knob or valve that does not have a lever arm.
This task type will require an initial torque vector specified
in init_wrench_direction_in_frame_name.
TASK_TYPE_R3_CIRCLE_FORCE 4 This task type corresponds to circular tasks where
the end-effector position and orientation rotate about a circle
but the orientation does always strictly follow the circle due to slips.
The constrained manipulation logic will generate translational forces in this case.
Example tasks are: manipulating a cabinet where the grasp on handle is not very rigid
or can often slip.
This task type will require an initial force vector specified
in init_wrench_direction_in_frame_name.
TASK_TYPE_R3_LINEAR_FORCE 5 This task type corresponds to linear tasks where
the end-effector position moves in a line
but the orientation does not need to change.
The constrained manipulation logic will generate a force in this case.
Example tasks are: A crank that has a loose handle, or manipulating
a cabinet where the grasp of the handle is loose and the end-effector is free
to rotate about the handle in one direction.
This task type will require an initial force vector specified
in init_wrench_direction_in_frame_name.
TASK_TYPE_HOLD_POSE 6 This option simply holds the hand in place with stiff impedance control.
You can use this mode at the beginning of a constrained manipulation task or to
hold position while transitioning between two different constrained manipulation
tasks. The target pose to hold will be the measured hand pose upon transitioning to
constrained manipulation or upon switching to this task type. This mode should only
be used during constrained manipulation tasks, since it uses impedance control to
hold the hand in place. This is not intended to stop the arm during position control
moves.

JointCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_ACTIVE 1 Command is still active and processing incoming joint requests
STATUS_ERROR 2 An error has occurred and joint requests are no longer being processed

RobotCommandFeedbackStatus.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.
STATUS_INCOMPATIBLE_HARDWARE 5 The request cannot be executed because the required hardware is missing.
/ For example, an armless robot receiving a synchronized command with an arm_command
/ request will return this value in the arm_command_feedback status.

SE2TrajectoryCommand.Feedback.BodyMovementStatus

Name Number Description
BODY_STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
BODY_STATUS_MOVING 1 The robot body is not settled at the goal.
BODY_STATUS_SETTLED 2 The robot is at the goal and the body has stopped moving.

SE2TrajectoryCommand.Feedback.FinalGoalStatus

Name Number Description
FINAL_GOAL_STATUS_UNKNOWN 0 FINAL_GOAL_STATUS_UNKNOWN should never be used. If used, an internal error has
happened.
FINAL_GOAL_STATUS_IN_PROGRESS 1 Robot is not stopped or stopping.
FINAL_GOAL_STATUS_ACHIEVABLE 2 Final position was achievable.
FINAL_GOAL_STATUS_BLOCKED 3 Final position was not achievable.

SE2TrajectoryCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_STOPPED 1 The robot has stopped. Either the robot has reached the end of the trajectory or it
believes that it cannot reach the desired position. Robot may start to move again if
a blocked path clears.
STATUS_STOPPING 3 The robot is nearing the end of the requested trajectory and is doing final
positioning.
STATUS_IN_PROGRESS 2 The robot is actively following the requested trajectory.
STATUS_AT_GOAL 1 The following enum values were possibly confusing in situations where the robot
cannot achieve the requested trajectory and are now deprecated.
STATUS_NEAR_GOAL 3
STATUS_GOING_TO_GOAL 2

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.

SafePowerOffCommand.Request.UnsafeAction

Robot action in response to a command received while in an unsafe position. If not specified, UNSAFE_MOVE_TO_SAFE_POSITION will be used

Name Number Description
UNSAFE_UNKNOWN 0
UNSAFE_MOVE_TO_SAFE_POSITION 1 Robot may attempt to move to a safe position (i.e. descends stairs) before sitting
and powering off.
UNSAFE_FORCE_COMMAND 2 Force sit and power off regardless of positioning. Robot will not take additional
steps

SelfRightCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_COMPLETED 1 Self-right has completed
STATUS_IN_PROGRESS 2 Robot is in progress of attempting to self-right

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.

StanceCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_STANCED 1 Robot has finished moving feet and they are at the specified position
STATUS_GOING_TO_STANCE 2 Robot is in the process of moving feet to specified position
STATUS_TOO_FAR_AWAY 3 Robot is not moving, the specified stance was too far away.
Hint: Try using SE2TrajectoryCommand to safely put the robot at the
correct location first.

StandCommand.Feedback.StandingState

Name Number Description
STANDING_UNKNOWN 0 STANDING_UNKNOWN should never be used. If used, an internal error has happened.
STANDING_CONTROLLED 1 Robot is standing up and actively controlling its body so it may occasionally make
small body adjustments.
STANDING_FROZEN 2 Robot is standing still with its body frozen in place so it should not move unless
commanded to. Motion sensitive tasks like laser scanning should be performed in this
state.

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.
STATUS_IN_PROGRESS 2 Robot is trying to come to a steady stand.

Top

bosdyn/api/bddf.proto

DataDescriptor

A DataDescriptor describes a data block which immediately follows it in the file. A corresponding SeriesDescriptor with a matching series_index must precede this in the file.

Field Type Label Description
series_index uint32 The series_index references the SeriesDescriptor to which the data following is associated.
timestamp google.protobuf.Timestamp The time at which the data is considered to be captured/sampled.
E.g., the shutter-close time of a captured image.
additional_indexes int64 repeated Sometimes a visualizer will want to organize message by data timestamp, sometimes by
the time messages were published or logged.
The additional_indexes field allows extra indexes or timestamps to be associated with
each data block for this purpose.
Other identifying information may also be used here, such as the PID of the process which
originated the data (e.g., for detecting if and when that process restarted).
The values in this field should correspond to the labels defined in "additional_index_names"
in the corresponding SeriesDescriptor.

DescriptorBlock

A Descriptor block typically describes a series of messages, but the descriptor at the start of the file describes the contents of the file as a whole, and the descriptor at the end of the file is an index structure to allow efficient access to the contents of the file.

Field Type Label Description
file_descriptor FileFormatDescriptor
series_descriptor SeriesDescriptor
series_block_index SeriesBlockIndex
file_index FileIndex

FileFormatDescriptor

The first block in the file should be a DescriptorBlock containing a FileFormatDescriptor. FileFormatDescriptor indicates the file format version and annotations. Annotations describe things like the robot from which the log was taken and the release id. The format of annotation keys should be {project-or-organization}/{annotation-name} For example, ‘bosdyn/robot-serial-number’.

Field Type Label Description
version FileFormatVersion The version number of the BDDF file.
annotations FileFormatDescriptor.AnnotationsEntry repeated File/stream-wide annotations to describe the content of the file.
checksum_type FileFormatDescriptor.CheckSumType The type of checksum supported by this stream.
For BDDF version 1.0.0 this should be SHA1.
checksum_num_bytes uint32 The number of bytes used for the BDDF checksum.
For BDDF version 1.0.0 this should always be 20, even if CHECKSUM_NONE is used.

FileFormatDescriptor.AnnotationsEntry

Field Type Label Description
key string
value string

FileFormatVersion

The current data file format is 1.0.0.

Field Type Label Description
major_version uint32
minor_version uint32
patch_level uint32

FileIndex

As a file is closed, a DescriptorBlock containing a FileIndex should be written. The FileIndex summarizes the data series stored in the file and the location of the block-indexes for each type in the file. Each series is assigned a “series_index” within the file, and this index may be used to index into the repeated fields in this message. E.g., for the series with series_index N, you can access its SeriesIdentifier by accessing element N the of the series_identifiers repeated field.

Field Type Label Description
series_identifiers SeriesIdentifier repeated SeriesIdentifier for each series in this file.
series_block_index_offsets uint64 repeated The offset from the start of the file of the SeriesBlockIndex block for each series.
series_identifier_hashes uint64 repeated The hash of the series_identifier for each series.

MessageTypeDescriptor

If a data series contains a sequence of binary messages, the encoding and format of these messages is described by a MessageTypeDescriptor.

Field Type Label Description
content_type string Description of the content type.
E.g., "application/protobuf", "image/jpeg", "text/csv", ...
type_name string If content_type is "application/protobuf", this is the full-name of the protobuf type.
is_metadata bool If true, message contents are necessary for interpreting other messages.
If the content of this file is split into multiple output files, these messages should be
copied into each.

PodTypeDescriptor

If a data series contains signals-style data of time-sampled “plain old datatypes”, this describes the content of the series. All POD data stored in data blocks is stored in little-endian byte order. Any number of samples may be stored within a given data block.

Field Type Label Description
pod_type PodTypeEnum The type of machine-readable values stored.
dimension uint32 repeated If empty, indicates a single POD per sample.
If one-element, indicates a vector of the given size per sample.
If two-elements, indicates a matrix of the given size, and so on.
An M x N x .. x P array of data is traversed from innermost (P) to outermost (M) dimension.

SeriesBlockIndex

This describes the location of the SeriesDescriptor DescriptorBlock for the series, and the timestamp and location in the file of every data block in the series.

Field Type Label Description
series_index uint32 The series_index for the series described by this index block.
descriptor_file_offset uint64 Offset of type descriptor block from start of file.
block_entries SeriesBlockIndex.BlockEntry repeated The timestamp and location of each data block for this series.
total_bytes uint64 The total size of the data stored in the data blocks of this series.

SeriesBlockIndex.BlockEntry

Field Type Label Description
timestamp google.protobuf.Timestamp The timestamp of data in this block.
file_offset uint64 The offset of the data block from the start of the file.
additional_indexes int64 repeated Values of the additional indexes for describing this block.

SeriesDescriptor

A description of a series of data blocks. These data blocks may either represent binary messages of a variable size, or they may represent a sequence of samples of POD data samples: single/vector/matrix/… of integer or floating-point values.

Field Type Label Description
series_index uint32 This index for the series is unique within the data file.
series_identifier SeriesIdentifier This is the globally unique {key -> value} mapping to identify the series.
identifier_hash uint64 This is a hash of the series_identifier.
The hash is the first 64 bits (read as a big-endian encoded uint64_t) of
SHA1(S K1 V1 K2 V2 ...) where,
- S is series identifier text,
- K1 and V1 are the key and value of the first key and value of the spec,
- K2 and V2 are the second key and value of the spec, etc...
Here, all strings are encoded as utf-8, and keys are sorted lexicographically using this
encoding (K1 < K2 < ...).
message_type MessageTypeDescriptor
pod_type PodTypeDescriptor
struct_type StructTypeDescriptor
annotations SeriesDescriptor.AnnotationsEntry repeated Annotations are a {key -> value} mapping for associating additional information with
the series.
The format of annotation keys should be
{project-or-organization}/{annotation-name}
For example, 'bosdyn/channel-name', 'bosdyn/protobuf-type'.
Annotation keys without a '/' are reserved.
The only current key in the reserved namespace is 'units': e.g., {'units': 'm/s2'}.
additional_index_names string repeated Labels for additional index values which should be attached to each DataDescriptor
in the series.
See the description of "additional_indexes" in DataDescriptor.
description string

SeriesDescriptor.AnnotationsEntry

Field Type Label Description
key string
value string

SeriesIdentifier

A key or description for selecting a message series. Because there may be multiple ways of describing a message series, we identify them by a unique mapping of {key -> value}. A series_type corresponds to a set of keys which are expected in the mapping. A ‘bosdyn:grpc:requests’ series_type, containing GRPC robot-id request messages, might thus be specified as: {’service’: ‘robot_id’, ‘message’: ‘bosdyn.api.RobotIdRequest’} A ‘bosdyn:logtick’ series_type, containing a signals data variable from LogTick annotations might be specified as: {’varname’: ‘tablet.wifi.rssi’, ‘schema’: ‘tablet-comms’, ‘client’: ‘bd-tablet’}

Field Type Label Description
series_type string This is the kind of spec, which should correspond to a set of keys which are expected
in the spec.
spec SeriesIdentifier.SpecEntry repeated This is the "key" for naming the series within the file.
A key->value description which should be unique for this series within the file
with this series_type.

SeriesIdentifier.SpecEntry

Field Type Label Description
key string
value string

StructTypeDescriptor

A struct series is a composite formed by a set of other series whose messages or signals-ticks are sampled at the same time. For example, all there may be a struct series for a set of signals variables, all from a process with an ‘update()’ function within which all all variables are sampled with the same timestamp. DataBlocks will not directly reference this series, but only child series of this series. Struct series may reference other struct series, but the series structure must be a directed acyclic graph (DAG): no circular reference structures.

Field Type Label Description
key_to_series_identifier_hash StructTypeDescriptor.KeyToSeriesIdentifierHashEntry repeated A map of a name-reference to a series, identified by its series_identifier_hash.

StructTypeDescriptor.KeyToSeriesIdentifierHashEntry

Field Type Label Description
key string
value uint64

FileFormatDescriptor.CheckSumType

Name Number Description
CHECKSUM_TYPE_UNKNOWN 0 Checksum type is unspecified. Should not be used.
CHECKSUM_TYPE_NONE 1 The writer of this stream is not computing a checksum.
The stream checksum at the end of the file will be 160 bits all set to 0.
CHECKSUM_TYPE_SHA1 2 A 160 bit SHA1 checksum will be included at the end of the stream.
This checksum will be computed over all data before digest itself at the
end of the stream, and can be used to verify the stream was received uncorrupted.

PodTypeEnum

“Plain old data” types which may be stored within POD data blocks.

Name Number Description
TYPE_UNSPECIFIED 0
TYPE_INT8 1
TYPE_INT16 2
TYPE_INT32 3
TYPE_INT64 4
TYPE_UINT8 5
TYPE_UINT16 6
TYPE_UINT32 7
TYPE_UINT64 8
TYPE_FLOAT32 9
TYPE_FLOAT64 10

Top

bosdyn/api/data_acquisition.proto

AcquireDataRequest

Field Type Label Description
header RequestHeader Common request header.
action_id CaptureActionId Define the unique action that all data should be saved with.
metadata Metadata Metadata to store with the data capture. The main Data Acquisition service saves it in the
DataBuffer.
acquisition_requests AcquisitionRequestList List of capability requests that should be collected as part of this capture action.
min_timeout google.protobuf.Duration Optional duration used to extend the amount of time that the data request may take, in
the event that a plugin is incorrectly specifying its timeout.
The amount of time allowed will be the maximum of this duration and any requests
made to plugins or other capture sources.

AcquireDataResponse

Field Type Label Description
header ResponseHeader Common response header
status AcquireDataResponse.Status Result of the AcquirePluginData RPC call. Further monitoring on the success of the
acquisition request can be done using the GetStatus RPC.
request_id uint32 Identifier which can be used to check the status of or cancel the acquisition action.

AcquirePluginDataRequest

Message sent by main Data Acquisition service to all data acquisition plugin services.

Field Type Label Description
header RequestHeader Common request header
data_id DataIdentifier repeated Metadata acquirers use these DataIdentifier objects to associate them with the acquired
metadata when storing them in the DataBuffer.
Data acquirers simply get the timestamp from these DataIdentifier objects to use when
storing the data in the DataBuffer.
metadata Metadata Metadata specified by the requestor.
action_id CaptureActionId Id to be associated with all the data buffered for this request. It will be stored
in the DataIdentifier field of each piece of data buffered from this request.
acquisition_requests AcquisitionRequestList List of capability requests specific for this Data Acquisition plugin.

AcquirePluginDataResponse

Field Type Label Description
header ResponseHeader Common response header
status AcquirePluginDataResponse.Status Result of the AcquirePluginData RPC call. Further monitoring on the success of the
acquisition request can be done using the GetStatus RPC.
request_id uint32 Identifier which can be used to check the status of or cancel the acquisition action..
timeout_deadline google.protobuf.Timestamp Time (in the robot's clock) by which this capture should definitely be complete.
If it is not complete by this time, something has gone wrong.
custom_param_error CustomParamError Filled out if status is STATUS_CUSTOM_PARAMS_ERROR.

AcquisitionCapabilityList

A list of all capabilities (data and images) that a specific data acquisition plugin service can successfully acquire and save the data specified in each capability.

Field Type Label Description
data_sources DataAcquisitionCapability repeated List of non-image data acquisition capabilities.
image_sources ImageAcquisitionCapability repeated List of image data acquisition capabilities.
network_compute_sources NetworkComputeCapability repeated List of network compute capabilities.

AcquisitionRequestList

The grouping of all individual image and data captures for a given capture action.

Field Type Label Description
image_captures ImageSourceCapture repeated List of image requests.
data_captures DataCapture repeated List of non-image data and metadata requests.
network_compute_captures NetworkComputeCapture repeated List of Network Compute Bridge requests

AssociatedAlertData

This message can be stored as a DataBlob in the data buffer in order to be recognized as AlertData that is associated with previously stored data.

Field Type Label Description
reference_id DataIdentifier The data that this AlertData refers to.
The timestamp field is ignored.
If only the action_id is filled out, this AlertData is associated with the entire capture
action.
alert_data AlertData AlertData message to be stored.

AssociatedMetadata

This message can be stored as a DataBlob in the data buffer in order to be recognized as metadata that is associated with previously stored data.

Field Type Label Description
reference_id DataIdentifier The data that this metadata refers to.
The timestamp field is ignored.
If only the action_id is filled out, this metadata is associated with the entire capture
action.
metadata Metadata Metadata message to be stored.

CancelAcquisitionRequest

Field Type Label Description
header RequestHeader Common request header
request_id uint32 Which acquisition request to cancel.

CancelAcquisitionResponse

Field Type Label Description
header ResponseHeader Common response header
status CancelAcquisitionResponse.Status The status of the Cancellation RPC. Further monitoring on the success of the cancellation
request can be done using the GetStatus RPC.

CaptureActionId

The CaptureActionId describes the entire capture action for an AcquireData request and will be used to uniquely identify that full request’s set of stored data.

Field Type Label Description
action_name string The action name is used to group all pieces of data associated with a single AcquireData
request. The action name must be unique for the given group name, meaning no two actions
with the same group name can have the same action name.
group_name string The group name is used to group a "session" of data, such as a mission or a teleop capture
session, which includes multiple capture actions (from multiple AcquireData RPCs).
timestamp google.protobuf.Timestamp Time (in the robot's clock) at which this capture was triggered. If the timestamp is not
specified in the AcquireData RPC, the main data acquisition service on robot will populate
the timestamp field with the timestamp of when the RPC was received.

DataAcquisitionCapability

Description of a data acquisition capability. A data acquisition plugin service will have a set of capabilities for which it can acquire and save the appropriate data.

Field Type Label Description
name string Unique identifier for the data acquisition capability. Used for identification purposes
when making acquire data requests.
description string A human readable name of the data acquisition capability that will be shown on the tablet.
channel_name string Channel name that will be associated with all data stored in the data buffer through
each data acquisition plugin. Metadata acquirers do not specify this field.
service_name string The data acquisition plugin service's service name used in directory registration.
custom_params DictParam.Spec Custom parameters supported by this instance of the service.
has_live_data bool Capability has live data available via GetLiveData RPC.

DataCapture

An individual capture which can be specified in the AcquireData or LiveData request to identify a piece of non-image data to be collected.

Field Type Label Description
name string Name of the data to be captured. This should match the uniquely identifying name from
the DataAcquisitionCapability.
custom_params DictParam Values passed to the service at capture time.
See the DictParam.Spec in DataAcquisitionCapability.

DataError

An error associated with a particular capture action and piece of data.

Field Type Label Description
data_id DataIdentifier Identifier for the data to be saved.
error_message string Human-readable message describing the error.
If a capability was misconfigured, e.g. by an invalid CustomParam in one of the requests,
it should show up here.
error_data google.protobuf.Any Custom plugin-specific data about the problem.

DataIdentifier

A way to identify an individual piece of data stored in the data buffer.

Field Type Label Description
action_id CaptureActionId The action where the data was acquired.
channel string Data buffer channel associated with the DataBlob. The channel is used to group data across
actions by a specific source, and it can be used in queries to retrieve some subset of data.
For example, the channel could be "ptz" and queries can be made for all PTZ images.
data_name string Data-specific identifier that can optionally be used to disambiguate cases where the
action_id and channel are insufficient. For example, you save cropped SpotCAM pano image that
are detected as gauges to a "detected_gauges" channel, but want a way to further individually
identify them as each specific gauge, so you give each detection a unique data_name.
id uint64 Unique identifier specified by the Data Acquisition Store service for this individual piece
of data. It is a monotonically-increasing value that is incremented for each stored capture.
This value is intended to be unique to a robot and not globally unique. We do not guarantee
uniqueness pre and post software upgrades or factory resets. This id does not necessarily
start at 0.

GetServiceInfoRequest

Field Type Label Description
header RequestHeader Common request header

GetServiceInfoResponse

Field Type Label Description
header ResponseHeader Common response header.
capabilities AcquisitionCapabilityList List of capabilities that the data acquisition (plugin) service can
collect and save data for.

GetStatusRequest

Field Type Label Description
header RequestHeader Common request header
request_id uint32 Which acquisition to check the status of.

GetStatusResponse

Field Type Label Description
header ResponseHeader Common response header
status GetStatusResponse.Status
data_saved DataIdentifier repeated Data that has been successfully saved into the data buffer for the capture action.
data_errors DataError repeated A list of data captures which have failed in some way during the action.
For example, the data acquisition plugin is unable to communicate to a sensor and responds
with a data error for that specific data capture.
service_errors PluginServiceError repeated Services which failed independent of a particular data id.
For example, if a plugin times out or crashes, it could be reported here.
network_compute_errors NetworkComputeError repeated Network compute services which failed independent of a particular data id.
For example, if a worker times out or crashes, it could be reported here.

ImageAcquisitionCapability

Description of an image acquisition capability. The image acquisition capabilities will be available through the main data acquisition service on robot and are populated based on all bosdyn.api.ImageService services registered to the robot’s directory.

Field Type Label Description
service_name string The image service's service name used in directory registration.
image_source_names string repeated Deprecated. DEPRECATED as of 3.1.0. Please use "image_sources" below for information regarding the image
source associated with the service.
image_sources ImageSource repeated List of image sources reported by the image service (through the ListImageSources RPC).

ImageSourceCapture

An individual capture which can be specified in the AcquireData request to identify a piece of image data to be collected.

Field Type Label Description
image_service string Name of the image service that the data should be requested from.
image_request ImageRequest Options for requesting this particular image.
image_source string Deprecated. DEPRECATED as of 3.2.0. Use image_request instead.
Specific image source to use from the list reported by the image service within the
ImageAcquisitionCapability message.
pixel_format Image.PixelFormat Deprecated. DEPRECATED as of 3.2.0. Use image_request instead.
Specific pixel format to capture reported by the ImageAcquisitionCapability message.

LiveDataRequest

Request live data from a DAQ plugin service by DataCapture capability name.

Field Type Label Description
header RequestHeader Common request header.
data_captures DataCapture repeated Include capability name and parameter values.

LiveDataResponse

Live data response of a DAQ plugin service for a single capability.

Field Type Label Description
header ResponseHeader Common response header.
live_data LiveDataResponse.CapabilityLiveData repeated One entry for each data capture in the request. Order matches LiveDataRequest order.

LiveDataResponse.CapabilityLiveData

Field Type Label Description
signals LiveDataResponse.CapabilityLiveData.SignalsEntry repeated Map of signal id to signal specification and data.
name string Unique name of the data that is captured.
status LiveDataResponse.CapabilityLiveData.Status
custom_param_error CustomParamError Filled out if status is STATUS_CUSTOM_PARAMS_ERROR.

LiveDataResponse.CapabilityLiveData.SignalsEntry

Field Type Label Description
key string
value Signal

Metadata

Structured data that can be included within a AcquireData RPC and saved in association with that capture action.

Field Type Label Description
data google.protobuf.Struct JSON representation of metadata.

NetworkComputeCapability

Field Type Label Description
server_config NetworkComputeServerConfiguration Service information.
available_models string repeated Deprecated. Provide list of available models.
DEPRECATED as of 3.3. Replaced by AvailableModels.
labels ModelLabels repeated Deprecated. Information about available classes for each model.
DEPRECATED as of 3.3. Replaced by AvailableModels.
models AvailableModels Envelope message for repeated ModelData.

NetworkComputeCapture

Field Type Label Description
input_data NetworkComputeInputData Deprecated. DEPRECATED as of 3.3. Please use input_data_bridge instead.
input_data_bridge NetworkComputeInputDataBridge
server_config NetworkComputeServerConfiguration Which service to use.

NetworkComputeError

Field Type Label Description
service_name string Name of the service with the error
error NetworkComputeError.ErrorCode General type of error that occurred.
network_compute_status NetworkComputeStatus Any particular failure mode reported.
message string Description of the error.

PluginServiceError

An error associated with a particular data acquisition plugin service that was

Field Type Label Description
service_name string Name of the service with the error
error PluginServiceError.ErrorCode Failure mode.
message string Description of the error.

AcquireDataResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1 The capture action has successfully started acquiring the data.
STATUS_UNKNOWN_CAPTURE_TYPE 2 One of the capability requests in the AcquisitionRequestList is unknown.

AcquirePluginDataResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1 The capture action has successfully started acquiring the data.
STATUS_UNKNOWN_CAPTURE_TYPE 2 One of the capability requests in the AcquisitionRequestList is unknown.
STATUS_CUSTOM_PARAMS_ERROR 3 See custom_param_error field for details.

CancelAcquisitionResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1 Successfully cancelled the data acquisition request.
STATUS_FAILED_TO_CANCEL 2 Unable to stop the data acquisition request.
STATUS_REQUEST_ID_DOES_NOT_EXIST 3 [Error] The request_id does not exist.

GetStatusResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_ACQUIRING 1 [Status]

Data acquisition is still in progress.
STATUS_SAVING 2 Data has been acquired, processing and storage is now in progress.
STATUS_COMPLETE 3 Data acquisition is complete.
STATUS_CANCEL_IN_PROGRESS 4 The data acquisition service is cancelling the request.
STATUS_ACQUISITION_CANCELLED 5 The data acquisition request was cancelled manually.
STATUS_DATA_ERROR 10 [Error - AcquireData]

An error occurred while acquiring, processing, or saving data.
STATUS_TIMEDOUT 11 The data collection has passed the deadline for completion.
STATUS_INTERNAL_ERROR 12 An error occurred such that we don't even know our status.
STATUS_CANCEL_ACQUISITION_FAILED 30 [Error - CancelAcquisition]

The cancellation request failed to complete.
STATUS_REQUEST_ID_DOES_NOT_EXIST 20 [Error - GetStatus]

The request_id does not exist.

LiveDataResponse.CapabilityLiveData.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_UNKNOWN_CAPTURE_TYPE 2 The capability name is unknown.
STATUS_CUSTOM_PARAMS_ERROR 3 See custom_param_error field for details.
STATUS_INTERNAL_ERROR 4 Some other problem occurred.

NetworkComputeError.ErrorCode

Name Number Description
STATUS_UNKNOWN 0
STATUS_REQUEST_ERROR 1 The request was rejected.
STATUS_NETWORK_ERROR 2 The request had an error reaching the worker.
STATUS_INTERNAL_ERROR 3 Some other problem prevented the request from succeeding.

PluginServiceError.ErrorCode

Possible ways a plugin can fail.

Name Number Description
STATUS_UNKNOWN 0
STATUS_REQUEST_ERROR 1 The initial RPC to the plugin failed
STATUS_GETSTATUS_ERROR 2 The GetStatus request to the plugin failed with a data error or timeout.
STATUS_INTERNAL_ERROR 3 The plugin reported an internal error.

Top

bosdyn/api/data_acquisition_plugin_service.proto

DataAcquisitionPluginService

The DataAcquisitionPluginService is a gRPC service that a payload developer implements to retrieve data from a sensor (or more generally perform some payload action) and optionally store that data on the robot via the DataAcquisitionStore service.

Method Name Request Type Response Type Description
AcquirePluginData AcquirePluginDataRequest AcquirePluginDataResponse Trigger a data acquisition to save metadata and non-image data to the data buffer.
Sent by the main Data Acquisition service as a result of a data acquisition request from the
tablet or a client.
GetStatus GetStatusRequest GetStatusResponse Query the status of a data acquisition.
GetServiceInfo GetServiceInfoRequest GetServiceInfoResponse Get information from a Data Acquisition service; lists acquisition capabilities.
CancelAcquisition CancelAcquisitionRequest CancelAcquisitionResponse Cancel an in-progress data acquisition.
GetLiveData LiveDataRequest LiveDataResponse Request live data available from this plugin during teleoperation.
Please use the other RPCs for typical data acquisition.

Top

bosdyn/api/data_acquisition_service.proto

DataAcquisitionService

The DataAcquisitionService is the main data acquisition service run on robot, which receives incoming requests and sends queries to all directory-registered DataAcquisitionPluginServices.

Method Name Request Type Response Type Description
AcquireData AcquireDataRequest AcquireDataResponse Trigger a data acquisition to save data and metadata to the data buffer.
Sent by the tablet or a client to initiate a data acquisition and buffering process.
GetStatus GetStatusRequest GetStatusResponse Query the status of a data acquisition.
GetServiceInfo GetServiceInfoRequest GetServiceInfoResponse Get information from a Data Acquisition service; lists acquisition capabilities.
CancelAcquisition CancelAcquisitionRequest CancelAcquisitionResponse Cancel an in-progress data acquisition.
GetLiveData LiveDataRequest LiveDataResponse Request live data available from DAQ plugins during teleoperation.
Please use the other RPCs for typical data acquisition.

Top

bosdyn/api/data_acquisition_store.proto

ActionIdQuery

A query parameter which filters the possible set of data identifiers to those which contain the same action/group names matching any of the names in the set of CaptureActionIds.

Field Type Label Description
action_ids CaptureActionId repeated The action ids to filter with.

DataQueryParams

The message containing the different query parameters which can be applied to the ListData requests.

Field Type Label Description
time_range TimeRangeQuery Time range to query.
action_ids ActionIdQuery List of action ids to query.

ListCaptureActionsRequest

Field Type Label Description
header RequestHeader Common request header.
query DataQueryParams Query parameters for finding action ids.

ListCaptureActionsResponse

Field Type Label Description
header ResponseHeader Common response header.
action_ids CaptureActionId repeated List of action ids that satisfied the query parameters.

ListStoredAlertDataRequest

Field Type Label Description
header RequestHeader Common request header.
query DataQueryParams Query parameters for finding AlertData.

ListStoredAlertDataResponse

Field Type Label Description
header ResponseHeader Common response header.
data_ids DataIdentifier repeated List of AlertData data identifiers that satisfied the query parameters.

ListStoredDataRequest

Field Type Label Description
header RequestHeader Common request header.
query DataQueryParams Query parameters for finding data.

ListStoredDataResponse

Field Type Label Description
header ResponseHeader Common response header.
data_ids DataIdentifier repeated List of data identifiers that satisfied the query parameters.

ListStoredImagesRequest

Field Type Label Description
header RequestHeader Common request header.
query DataQueryParams Query parameters for finding images.

ListStoredImagesResponse

Field Type Label Description
header ResponseHeader Common response header.
data_ids DataIdentifier repeated List of image data identifiers that satisfied the query parameters.

ListStoredMetadataRequest

Field Type Label Description
header RequestHeader Common request header.
query DataQueryParams Query parameters for finding metadata.

ListStoredMetadataResponse

Field Type Label Description
header ResponseHeader Common response header.
data_ids DataIdentifier repeated List of metadata data identifiers that satisfied the query parameters.

QueryMaxCaptureIdRequest

Field Type Label Description
header RequestHeader Common request header.
query QueryParameters Query parameters for finding data.

QueryMaxCaptureIdResponse

Field Type Label Description
header ResponseHeader
max_capture_id uint64

QueryParameters

Field Type Label Description
time_range TimeRangeQuery Time range to query.
action_ids CaptureActionId repeated List of action ids to query. The constructed query statement will have an OR relation
between the action_ids specified in this list, with an AND relation for the fields inside
each action_id. For example, specifying
[{action_name="action1", group_name="group1"}, {action_name="action2", group_name="group2"}]
will insert the following in the WHERE part of the query:
(action_name="action1" AND group_name="group1") OR (action_name="action2" AND
group_name="group2").
channels string repeated Channels to include in the query results. The constructed query statement will have an OR
relation for all the channel values listed in this field.
captures_from_id uint64 Query for captures with id higher or equal to this value. Specifying 0 means that the
Data Acquisition Store will return all captured data it has. Otherwise, it will return new
captures stored with an id greater than the value specified in this field.
only_include_identifiers bool Setting this field to true only returns the DataIdentifiers in the response and not the
actual captures.
include_images bool The following fields specify which capture types to include in the results. If none of the
following fields is specified, then all capture types will be included in the results.
include_data bool
include_metadata bool
include_alerts bool

QueryStoredCaptureResult

Field Type Label Description
data_id DataIdentifier
image ImageCapture
metadata AssociatedMetadata
alert_data AssociatedAlertData
data StoredCapturedData

QueryStoredCapturesRequest

Field Type Label Description
header RequestHeader Common request header.
query QueryParameters Query parameters for finding data.

QueryStoredCapturesResponse

Field Type Label Description
header ResponseHeader Common response header.
action_ids CaptureActionId repeated CaptureActionIds that match the query parameters and are included in the results.
results QueryStoredCaptureResult repeated Results that match the query parameters.
max_capture_id uint64 Max capture_id in the database matching the query parameters.

StoreAlertDataRequest

Field Type Label Description
header RequestHeader Common request header.
alert_data AssociatedAlertData AlertData to store.
data_id DataIdentifier Data identifier of the alert.

StoreAlertDataResponse

Field Type Label Description
header ResponseHeader Common response header.
id uint64

StoreDataRequest

Field Type Label Description
header RequestHeader Common request header.
data bytes Data to store.
data_id DataIdentifier Data identifier of the data.
file_extension string File extension to use when writing the data to file.

StoreDataResponse

Field Type Label Description
header ResponseHeader Common response header.
id uint64

StoreImageRequest

Field Type Label Description
header RequestHeader Common request header.
image ImageCapture Image to store.
data_id DataIdentifier Data identifier of the image.

StoreImageResponse

Field Type Label Description
header ResponseHeader Common response header.
id uint64

StoreMetadataRequest

Field Type Label Description
header RequestHeader Common request header.
metadata AssociatedMetadata Metadata to store.
data_id DataIdentifier Data identifier of the metadata.

StoreMetadataResponse

Field Type Label Description
header ResponseHeader Common response header.
id uint64

StoredCapturedData

Field Type Label Description
data bytes
file_extension string File extension to use for writing the data to a file.

TimeRangeQuery

A query parameter which filters the possible set of data identifiers to those with timestamps within the specified range.

Field Type Label Description
from_timestamp google.protobuf.Timestamp Start of the time range to query.
to_timestamp google.protobuf.Timestamp End of the time range to query.

Top

bosdyn/api/data_acquisition_store_service.proto

DataAcquisitionStoreService

The DataAcquisitionStoreService is used to store data (images, data, metadata) on the robot in association with the DataIdentifiers specified by the DataAcquisitionService. Additionally, requests can be made to the DataAcquisitionStoreService to identify different pieces of data or entire capture actions which match query parameters, such as time ranges or action/group names.

Method Name Request Type Response Type Description
ListCaptureActions ListCaptureActionsRequest ListCaptureActionsResponse List all CaptureActionIds (which identify an entire AcquireData RPC's data captures)
that match the query parameters provided in the request.
ListStoredData ListStoredDataRequest ListStoredDataResponse List data identifiers (which identify specific pieces of data from
an action) for stored data that satisfy the query parameters in the request.
StoreData StoreDataRequest StoreDataResponse Store arbitrary data associated with a DataIdentifier.
ListStoredImages ListStoredImagesRequest ListStoredImagesResponse Type-safe to images: list data identifiers (which identify specific images
from an action) for stored images that satisfy the
query parameters in the request.
StoreImage StoreImageRequest StoreImageResponse Type-safe to images: store image data associated with a DataIdentifier.
ListStoredMetadata ListStoredMetadataRequest ListStoredMetadataResponse Type-safe to JSON metadata: list data identifiers (which identify specific metadata from
an action) for stored metadata that satisfy the query parameters in the request.
StoreMetadata StoreMetadataRequest StoreMetadataResponse Type-safe to JSON metadata: store metadata associated with a DataIdentifier.
ListStoredAlertData ListStoredAlertDataRequest ListStoredAlertDataResponse List data identifiers (which identify specific AlertData from
an action) for stored AlertData that satisfy the query parameters in the request.
StoreAlertData StoreAlertDataRequest StoreAlertDataResponse Store AlertData associated with a DataIdentifier.
QueryStoredCaptures QueryStoredCapturesRequest DataChunk stream Query the Data Acquisition Store for captured data. This streaming RPC returns a single
QueryStoredCapturesResponse message, encoded as a list of DataChunk messages.

If the first capture matching the query is larger than an internal size limit set in the
service, the QueryStoredCapturesResponse message contains only that first capture matching
the query.

Otherwise, the QueryStoredCapturesResponse message contains as many matching captures as can
fit within the internal size limit, without breaking the results order.

To get all captures that match a query, you must make this RPC until it returns an empty
QueryStoredCapturesResponse with no elements in its "results" field.
QueryMaxCaptureId QueryMaxCaptureIdRequest QueryMaxCaptureIdResponse

Top

bosdyn/api/data_buffer.proto

DataBlob

Message-style data to add to the log.

Field Type Label Description
timestamp google.protobuf.Timestamp Timestamp of data in robot clock time. This is required.
channel string A general label for this blob.
This is distinct from type_id, which identifies how the blob is to be parsed.
In practice, this is often the same as the type_id.
type_id string A description of the data's content and its encoding. This is required.
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.
For example, jpeg data or a serialized protobuf.

Event

This message contains event data for logging to the public timeline.

Field Type Label Description
type string Type of event, typically prefixed with a project or organization, e.g. "bosdyn:startup"
description string Event description.
This is optional.
source string A description of the source of this event. May be the client name.
- Not required to be unique.
- Disambiguates the source of similar event types.
id string Unique identifier. Used to link start and end messages for events with a duration.
- Long running events may have separate messages at the start and end, in case the message
for the end of the event is lost.
- For events without a separate start and end message (in which case both start_time and
end time should be specified), the 'id' field will be set by the service during upload,
unless the user has already set it.
- This id is not tracked internally by the service. It is only used to consume the event
timeline.
- To be effective, the id value should be generated randomly by the client.
start_time google.protobuf.Timestamp Start and end times for the event:
- Some events are instantaneous. For these, set start_timestamp and end_timestamp to the
same value and send a single message (without an id).
- Some events take time. At the onset, send a message with a unique id, the start time, and
type. The end message should include all data from the start message, any
additional data, and an end time. If you have the end message, you should not need
the start message since it is a strict subset.
end_time google.protobuf.Timestamp
level Event.Level The relative importance of the event.
parameters Parameter repeated Optional set of event parameters.
log_preserve_hint Event.LogPreserveHint Optionally request that the robot try to preserve data near this time for a service log.

OperatorComment

An operator comment to be added to the log. 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 Label 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.
If this is not specified, this will default to the time the server received the message.

RecordDataBlobsRequest

Field Type Label Description
header RequestHeader Common request header.
blob_data DataBlob repeated The data blobs to be logged.
sync bool When set, the data blob is committed to the log synchronously. The RPC does not return until
the data is written.

RecordDataBlobsResponse

Field Type Label Description
header ResponseHeader Common response header.
errors RecordDataBlobsResponse.Error repeated Errors which occurred when logging data blobs.

RecordDataBlobsResponse.Error

DataBlob recording error.

Field Type Label Description
type RecordDataBlobsResponse.Error.Type The type of error: if it was caused by the client or the service.
message string An error message.
index uint32 The index to identify the data being stored.

RecordEventsRequest

Field Type Label Description
header RequestHeader Common request header.
events Event repeated The events to be logged.

RecordEventsResponse

Field Type Label Description
header ResponseHeader Common response header.
errors RecordEventsResponse.Error repeated Errors which occurred when logging events.

RecordEventsResponse.Error

Event recording error.

Field Type Label Description
type RecordEventsResponse.Error.Type The type of error: if it was caused by the client, the service, or something else.
message string An error message.
index uint32 The index to identify the data being stored.

RecordOperatorCommentsRequest

Field Type Label Description
header RequestHeader Common request header.
operator_comments OperatorComment repeated The operator comments to be logged.

RecordOperatorCommentsResponse

Field Type Label Description
header ResponseHeader Common response header.
errors RecordOperatorCommentsResponse.Error repeated Errors which occurred when logging operator comments.

RecordOperatorCommentsResponse.Error

Operator comment recording error.

Field Type Label Description
type RecordOperatorCommentsResponse.Error.Type The type of error: if it was caused by the client or the service.
message string An error message.
index uint32 The index to identify the data being stored.

RecordSignalTicksRequest

Field Type Label Description
header RequestHeader Common request header.
tick_data SignalTick repeated The signals data to be logged.

RecordSignalTicksResponse

Field Type Label Description
header ResponseHeader Common response header.
errors RecordSignalTicksResponse.Error repeated Errors which occurred when logging signal ticks.

RecordSignalTicksResponse.Error

Signal tick recording error.

Field Type Label Description
type RecordSignalTicksResponse.Error.Type The type of error: if it was caused by the client, the service, or something else.
message string An error message.
index uint32 The index to identify the data being stored.

RecordTextMessagesRequest

Field Type Label Description
header RequestHeader Common request header.
text_messages TextMessage repeated The text messages to be logged.

RecordTextMessagesResponse

Field Type Label Description
header ResponseHeader Common response header.
errors RecordTextMessagesResponse.Error repeated Errors which occurred when logging text message data.

RecordTextMessagesResponse.Error

Text message recording error.

Field Type Label Description
type RecordTextMessagesResponse.Error.Type The type of error: if it was caused by the client or the service.
message string An error message.
index uint32 The index to identify the data being stored.

RegisterSignalSchemaRequest

Field Type Label Description
header RequestHeader Common request/response header.
schema SignalSchema Defines a schema for interpreting SignalTick data containing packed signals-type data.

RegisterSignalSchemaResponse

Field Type Label Description
header ResponseHeader Common request/response header.
schema_id uint64 Server returns a unique ID based on the client ID and schema definition.
Always greater than zero.

SignalSchema

A description of a set of signals-style variables to log together as timestamped samples.

Field Type Label Description
vars SignalSchema.Variable repeated A SignalTick using this schema contains the values of this ordered list of variables.
schema_name string The name of the schema.

SignalSchema.Variable

A variable of signals-style data, which will be sampled in time.

Field Type Label Description
name string The name of the variable.
type SignalSchema.Variable.Type The type of the data.
is_time bool Zero or one variable in 'vars' may be specified as a time variable.
A time variable must have type TYPE_FLOAT64.

SignalSchemaId

Field Type Label Description
schema_id uint64 {schema, id} pair
schema SignalSchema

SignalTick

A timestamped set of signals variable values.

Field Type Label Description
sequence_id int64 Successive ticks should have successive sequence_id's.
The robot uses this to determine if a tick was somehow lost.
timestamp google.protobuf.Timestamp Timestamp at which the variable values were sampled.
source string The client name.
This may be used to segregate data for the same variables to different parts of the buffer.
schema_id uint64 This specifies the SignalSchema to be used in interpreting the
encoding SignalTick.Encoding Format describing how the data bytes array is encoded.
data bytes The encoded data representing a tick of multiple values of signal-styles data.

TextMessage

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

Field Type Label Description
message string String annotation message.
timestamp google.protobuf.Timestamp The timestamp of the annotation. This must be in robot time.
If this is not specified, this will default to the time the server received the message.
source string The client name.
This may be used to segregate data for the same variables to different parts of the buffer.
level TextMessage.Level The relative importance of the 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.

Event.Level

Level, or similarly “visibility,” “importance,” or “weight” of event.

  • Higher level events will increase the visibility on the event timeline, relative to other events.

  • In general, higher level events should be more consequential with respect to the robot operation on a per-occurrence basis.

  • Lower level events should be less consequential on a per-occurrence basis.

  • Non-critical events may be one of LOW, MEDIUM, or HIGH. UNSET is logically equivalent to LOW level.

  • Critical events may be either mission or system critical.

  • System-critical is quasi-reserved for internal robot use, and is used to identify events that directly affect robot status or capability, such as the onset of a critical fault or start of an enabling capability.

  • Mission-critical is quasi-reserved client use, and is intended for events that directly affect the ability of the robot to “do what the user wants,” such as the onset of a service fault or start of an enabling capability.

Name Number Description
LEVEL_UNSET 0
LEVEL_LOW 1 Non-critical events
LEVEL_MEDIUM 2
LEVEL_HIGH 3
LEVEL_MISSION_CRITICAL 4 Critical events
LEVEL_SYSTEM_CRITICAL 5

Event.LogPreserveHint

LogPreserveHint may encode a hint to the robot’s logging system for whether to preserve internal log data near the time of this event. This could be useful in saving data to be used in a service log to send to Boston Dynamics.

Name Number Description
LOG_PRESERVE_HINT_UNSET 0 If this this is unset, it is equivalent to LOG_PRESERVE_HINT_NORMAL.
LOG_PRESERVE_HINT_NORMAL 1 Do not change the robot's default log data preservation behavior in response to this
event.
LOG_PRESERVE_HINT_PRESERVE 2 Request that the robot try to preserve data near the time of this event.
Log space on the robot is limited, so this does not guarantee that the data will be
preserved.

RecordDataBlobsResponse.Error.Type

Name Number Description
NONE 0
CLIENT_ERROR 1
SERVER_ERROR 2

RecordEventsResponse.Error.Type

Name Number Description
NONE 0
CLIENT_ERROR 1
SERVER_ERROR 2

RecordOperatorCommentsResponse.Error.Type

Name Number Description
NONE 0
CLIENT_ERROR 1
SERVER_ERROR 2

RecordSignalTicksResponse.Error.Type

Name Number Description
NONE 0
CLIENT_ERROR 1
SERVER_ERROR 2
INVALID_SCHEMA_ID 3

RecordTextMessagesResponse.Error.Type

Name Number Description
NONE 0
CLIENT_ERROR 1
SERVER_ERROR 2

SignalSchema.Variable.Type

Name Number Description
TYPE_UNKNOWN 0
TYPE_INT8 1
TYPE_INT16 2
TYPE_INT32 3
TYPE_INT64 4
TYPE_UINT8 5
TYPE_UINT16 6
TYPE_UINT32 7
TYPE_UINT64 8
TYPE_FLOAT32 9
TYPE_FLOAT64 10

SignalTick.Encoding

Name Number Description
ENCODING_UNKNOWN 0
ENCODING_RAW 1 Bytes array is a concatenation of little-endian machine representations of
the variables from the SignalSchema, in order listed in that schema.

TextMessage.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.

Top

bosdyn/api/data_buffer_service.proto

DataBufferService allows adding information to the robot’s log files.

DataBufferService

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

Method Name Request Type Response Type Description
RecordTextMessages RecordTextMessagesRequest RecordTextMessagesResponse Add text messages to the log.
RecordOperatorComments RecordOperatorCommentsRequest RecordOperatorCommentsResponse Add a set of operator messages to the log.
RecordDataBlobs RecordDataBlobsRequest RecordDataBlobsResponse Add message-style data to the log.
RecordEvents RecordEventsRequest RecordEventsResponse Add event data to the log.
RegisterSignalSchema RegisterSignalSchemaRequest RegisterSignalSchemaResponse Register a log tick schema, allowing client to later log tick data.
RecordSignalTicks RecordSignalTicksRequest RecordSignalTicksResponse Add signal data for registered signal schema to the log.

Top

bosdyn/api/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 Label 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.

Top

bosdyn/api/data_index.proto

BlobPage

A set of blob messages of a given channel/msgtype within a given data page.

Field Type Label Description
spec BlobSpec
page PageInfo

BlobPages

A set of pages of data which contain specified Blob messages from the data-buffer.

Field Type Label Description
time_range TimeRange
pages BlobPage repeated

BlobSpec

Specification for selecting of blob messages.

Field Type Label Description
source string If set, require the message source to match this.
message_type string If set, require the message type to match this value.
channel string If set, require the channel to match this value (or channel_glob, if set).
channel_glob string Optionally require the channel to match a glob (or channel, if set)..
For example, 'gps/*' will match all channels starting with 'gps/'.

DataBufferStatus

Field Type Label Description
num_data_buffer_pages int64
data_buffer_total_bytes int64
num_comments int64
num_events int64
blob_specs BlobSpec repeated

DataIndex

Description of data matching a given DataQuery.

Field Type Label Description
time_range TimeRange
blobs BlobPages repeated
text_messages PagesAndTimestamp
events PagesAndTimestamp
comments PagesAndTimestamp

DataQuery

A query for pages containing the desired data.

Field Type Label Description
time_range TimeRange Timespan for data we want to query
blobs BlobSpec repeated Request for pages containing different kinds of data.
text_messages bool return pages of text-messages during the specified timespan
events bool return pages of events
comments bool return pages of operator comments during the specified timespan

DeleteDataPagesRequest

GRPC request to delete pages. Both time_range and page_ids can be set.

Field Type Label Description
header RequestHeader
time_range TimeRange Delete all pages in this time range
page_ids string repeated Delete all pages with matching ids

DeleteDataPagesResponse

Field Type Label Description
header ResponseHeader
bytes_deleted int64
status DeletePageStatus repeated

DeletePageStatus

Field Type Label Description
page_id string
status DeletePageStatus.Status

EventSpec

Specification for selecting Events.

Field Type Label Description
source string
type string
level google.protobuf.Int32Value
log_preserve_hint Event.LogPreserveHint

EventsComments

Requested Events and/or OperatorComments.

Field Type Label Description
time_range TimeRange Timespan for data
events Event repeated
operator_comments OperatorComment repeated
events_limited bool True if the number of events returned was limited by query maximum.
operator_comments_limited bool True if the number of comments returned was limited by query maximum.

EventsCommentsSpec

A request for Events and/or OperatorComments over a given time range.

Field Type Label Description
time_range TimeRange Timespan for data we want to query
events EventSpec repeated Return events which match the request.
comments bool Return operator comments which match the request.
max_events uint32 Maximum number of events to return (limited to 1024).
max_comments uint32 Maximum number of comments to return (limited to 1024).

GetDataBufferStatusRequest

Field Type Label Description
header RequestHeader
get_blob_specs bool

GetDataBufferStatusResponse

Field Type Label Description
header ResponseHeader
data_buffer_status DataBufferStatus

GetDataIndexRequest

GRPC response with requested data index information.

Field Type Label Description
header RequestHeader
data_query DataQuery

GetDataIndexResponse

GRPC request for data index information.

Field Type Label Description
header ResponseHeader
data_index DataIndex

GetDataPagesRequest

Field Type Label Description
header RequestHeader
time_range TimeRange

GetDataPagesResponse

Field Type Label Description
header ResponseHeader
pages PageInfo repeated

GetEventsCommentsRequest

GRPC request for Events and OperatorComments.

Field Type Label Description
header RequestHeader
event_comment_request EventsCommentsSpec

GetEventsCommentsResponse

GRPC response with requested Events and OperatorComments.

Field Type Label Description
header ResponseHeader
events_comments EventsComments

GrpcPages

A set of pages of data which contain specied GRPC request and response messages.

Field Type Label Description
time_range TimeRange
spec GrpcSpec
pages PageInfo repeated

GrpcSpec

Specification for selecting of GRPC logs.

Field Type Label Description
service_name string

PageInfo

A unit of data storage. This may be a bddf data file. Like a file, this data may be downloaded or deleted all together for example.

Field Type Label Description
id string Identifier unique to robot.
path string Relative path to file, if file storage.
source string Name of service/client which provided the data.
time_range TimeRange Time range of the relevant data in the page.
num_ticks int64 Number of time samples or blobs.
total_bytes int64 Total size of data in the page.
format PageInfo.PageFormat
compression PageInfo.Compression
is_open bool True if data is still being written into this page, false if page is complete.
is_downloaded bool True if data is marked as having been downloaded.
deleted_timestamp google.protobuf.Timestamp If this exists, the page was deleted from the robot at the specified time.
download_started_timestamp google.protobuf.Timestamp If this exists, download from this page was started at the specified time.
request_preserve bool True if data has been requested to be preserved.

PagesAndTimestamp

A set of pages and the associated time range they cover.

Field Type Label Description
time_range TimeRange
pages PageInfo repeated

DeletePageStatus.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_DELETED 1
STATUS_DELETION_FAILED 2
STATUS_NOT_FOUND 3

PageInfo.Compression

Name Number Description
COMPRESSION_UNKNOWN 0 Not set -- do not use.
COMPRESSION_NONE 1 Data is not compressed.
COMPRESSION_GZIP 2 Data uses gzip compression.
COMPRESSION_ZSTD 3 Data uses zstd compression.

PageInfo.PageFormat

Name Number Description
FORMAT_UNKNOWN 0 Unset -- do not use.
FORMAT_BDDF_FILE 1 Data is stored in a .bddf file

Top

bosdyn/api/data_service.proto

DataBufferService allows adding information to the robot’s log files.

DataService

The DataService is a mechanism for querying and managing data stored on robot.

Method Name Request Type Response Type Description
GetDataIndex GetDataIndexRequest GetDataIndexResponse Get index of current data matching a given DataQuery.
GetEventsComments GetEventsCommentsRequest GetEventsCommentsResponse Get events and comments.
GetDataBufferStatus GetDataBufferStatusRequest GetDataBufferStatusResponse Get basic stats on data buffer storage.
GetDataPages GetDataPagesRequest GetDataPagesResponse Get a list pf pages matching a given time range
DeleteDataPages DeleteDataPagesRequest DeleteDataPagesResponse Delete a list of pages matching a given time range or page ids

Top

bosdyn/api/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 Label Description
host_ip string The IP address of the computer hosting this endpoint.
port int32 The port number on which the endpoint is provided, between 0 and 65535.

GetServiceEntryRequest

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

Field Type Label 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 Label 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 Label Description
header RequestHeader Common request header.

ListServiceEntriesResponse

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

Field Type Label Description
header ResponseHeader Common response header.
service_entries ServiceEntry repeated 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 Label 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. This serves as the time of
the last heartbeat to the robot.
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.
liveness_timeout_secs double Number of seconds to wait between heartbeats before assuming service in no longer live
If unset (0) liveness checks will be disabled for this service.
host_payload_guid string The GUID of the payload that this service was registered from. An empty string represents a
service that was registered via a client using standard user credentials or internal to the
robot. This value is set automatically based on the user token and cannot be set or updated
via the API, so it should not be populated by the client at registration time.

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.

Top

bosdyn/api/directory_registration.proto

RegisterServiceRequest

The RegisterService request message sends the service’s entry and endpoint to the robot’s directory. This Request serves as a heartbeat to the Directory.

Field Type Label 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 Label 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 Label 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 Label 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. This Request serves as a heartbeat to the Directory.

Field Type Label 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 Label 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.

Top

bosdyn/api/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.

Top

bosdyn/api/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.

Top

bosdyn/api/docking/docking.proto

ConfigRange

The configuration of a range of dock ID’s

Field Type Label Description
id_start uint32 Starting ID
id_end uint32 Ending ID
type DockType Type of dock for this range

DockState

Message describing the overall dock state of the robot, including power & comms connections.
Not tied to any particular DockingCommand ID.
Note: [*] indicates fields which are only valid if the status is DOCK_STATUS_DOCKED or DOCK_STATUS_DOCKING
or DOCK_STATUS_UNDOCKING.
Note: [^] indicates fields which are only valid if the status is DOCK_STATUS_DOCKED. \

Field Type Label Description
status DockState.DockedStatus Status of if the robot is on dock
dock_type DockType [*] Type of the dock
dock_id uint32 [*] ID of the dock
power_status DockState.LinkStatus [^] Status of power detection from the dock

DockingCommandFeedbackRequest

Message to get the status of a previously issued DockingCommand

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
docking_command_id uint32 Unique identifier of the command to get feedback for.
update_docking_params UpdateDockingParams [optional] Update parameters relating to the specified command ID

DockingCommandFeedbackResponse

Response to a DockingCommandFeedbackRequest for a particualar docking command ID

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used (unset if unknown).
status DockingCommandFeedbackResponse.Status Current feedback of specified command ID.

DockingCommandRequest

Message to command the robot to dock.
Note: If the robot is docked, you can undock the robot by issuing a command with prep_pose_behavior=PREP_POSE_UNDOCK. If undocking, docking_station_id is not required.

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
lease bosdyn.api.Lease The Lease to show ownership of the robot.
docking_station_id uint32 ID of docking station to dock at.
This is ignored if undocking the robot, the current dock is used.
clock_identifier string Identifier provided by the time sync service to verify time sync between robot and client.
end_time google.protobuf.Timestamp The timestamp (in robot time) at which a command will stop executing.
This can be updated by other RPCs
This is a required field and used to prevent runaway commands.
prep_pose_behavior PrepPoseBehavior [Optional] Specify the prep pose behavior
require_fiducial bool Require the detection of the dock's fiducial

DockingCommandResponse

Response to a DockingCommandRequest

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.
status DockingCommandResponse.Status Result of issued command.
docking_command_id uint32 Unique identifier for the command (if accepted, status=STATUS_OK).

GetDockingConfigRequest

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

GetDockingConfigResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
dock_configs ConfigRange repeated A series of ConfigRange specifying details for dock ID numbers.

GetDockingStateRequest

Message to get the overall docking state

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

GetDockingStateResponse

Response of a GetDockingStateRequest

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
dock_state DockState

UpdateDockingParams

Field Type Label Description
end_time google.protobuf.Timestamp The new timestamp (in robot time) at which a command will stop executing.

DockState.DockedStatus

Name Number Description
DOCK_STATUS_UNKNOWN 0 Unknown
DOCK_STATUS_DOCKED 1 Robot is detected as on a dock
DOCK_STATUS_DOCKING 2 Robot is currently running a docking command
DOCK_STATUS_UNDOCKED 3 Robot is not detected as on dock
DOCK_STATUS_UNDOCKING 4 Robot is currently running an undocking command

DockState.LinkStatus

Name Number Description
LINK_STATUS_UNKNOWN 0 Unknown or Not applicable
LINK_STATUS_DETECTING 3 The link status is being detected
LINK_STATUS_CONNECTED 1 The link is detected as connected
LINK_STATUS_ERROR 2 The link could not be detected

DockType

Type of dock

Name Number Description
DOCK_TYPE_UNKNOWN 0 Unknown type of dock
DOCK_TYPE_CONTACT_PROTOTYPE 2 Prototype version SpotDock
DOCK_TYPE_SPOT_DOCK 3 Production version SpotDock
DOCK_TYPE_SPOT_DOGHOUSE 4 Production version SpotDock located in the dog house.

DockingCommandFeedbackResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status is not specified.
STATUS_IN_PROGRESS 1 Docking command is executing.
STATUS_DOCKED 2 Docking command succeeded, the robot is docked.
STATUS_AT_PREP_POSE 11 Final success state for PREP_POSE_ONLY_POSE or PREP_POSE_UNDOCK.
STATUS_MISALIGNED 10 Misaligned was detected between the robot and the dock.
The docking command was aborted to save an ending up in an unrecoverable state, please try again.
STATUS_OLD_DOCKING_COMMAND 3 This DockingCommand overridden by new docking command.
STATUS_ERROR_DOCK_LOST 4 ERROR: The sensed dock has been lost and is no longer found.
STATUS_ERROR_LEASE 5 ERROR: Lease rejected.
STATUS_ERROR_COMMAND_TIMED_OUT 6 ERROR: End time has been reached.
STATUS_ERROR_NO_TIMESYNC 7 ERROR: No Timesync with system.
STATUS_ERROR_TOO_DISTANT 8 ERROR: Provided end time too far in the future.
STATUS_ERROR_NOT_AVAILABLE 12 ERROR: The dock is not available for docking.
STATUS_ERROR_UNREFINED_PRIOR 13 ERROR: The prior could not be confirmed as a real dock
STATUS_ERROR_STUCK 14 ERROR: The robot could not make progress towards docking.
For example, there may be an obstacle in the way.
STATUS_ERROR_SYSTEM 9 ERROR: Internal system error during execution
This error cannot be resolved by issuing a new DockingCommand
Check the returned message for details

DockingCommandResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Status is not specified.
STATUS_OK 1 Docking command accepted
STATUS_ERROR_LEASE 4 ERROR: Lease rejected
STATUS_ERROR_DOCK_NOT_FOUND 5 ERROR: Dock fiducial not found.
STATUS_ERROR_NOT_DOCKED 6 ERROR: Trying to undock while not docked
STATUS_ERROR_GRIPPER_HOLDING_ITEM 8 ERROR: Trying to dock when the arm is holding an object.
STATUS_ERROR_NOT_AVAILABLE 9 ERROR: The dock is not available for docking.
STATUS_ERROR_SYSTEM 7 ERROR: Internal system error during execution
This error cannot be resolved by issuing a new DockingCommand
Check the returned message for details

PrepPoseBehavior

Defines how and whether we use the “pre-docking” pose.

Name Number Description
PREP_POSE_UNKNOWN 0 Default behavior, equivalent to PREP_POSE_USE_POSE.
PREP_POSE_USE_POSE 1 Goes to the pre-docking pose before docking.
PREP_POSE_SKIP_POSE 2 Docks before going to the pre-docking pose.
PREP_POSE_ONLY_POSE 3 Goes to the pre-docking pose, and then returns SUCCESS without docking.
PREP_POSE_UNDOCK 4 Use this enum to undock a currently docked robot.

Top

bosdyn/api/docking/docking_service.proto

DockingService

The DockingService provides an interface to dock and undock the robot from Spot Docks, as well as get feedback on command status, and get the current docked status of the robot.

Method Name Request Type Response Type Description
DockingCommand DockingCommandRequest DockingCommandResponse Starts a docking command on the robot.
DockingCommandFeedback DockingCommandFeedbackRequest DockingCommandFeedbackResponse Check the status of a docking command.
GetDockingConfig GetDockingConfigRequest GetDockingConfigResponse Get the configured dock ID ranges.
GetDockingState GetDockingStateRequest GetDockingStateResponse Get the robot's docking state

Top

bosdyn/api/estop.proto

DeregisterEstopEndpointRequest

Deregister the specified E-Stop endpoint registration.

Field Type Label 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 Label 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 Label 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 Label 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 Label Description
endpoints EstopEndpoint repeated 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 Label 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 Label 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 Label Description
endpoints EstopEndpointWithStatus repeated 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 Label Description
header RequestHeader Common request header.
target_config_id string The 'unique_id' of EstopConfig to get.

GetEstopConfigResponse

Response to EstopConfigRequest.

Field Type Label 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 Label Description
header RequestHeader Common request header.

GetEstopSystemStatusResponse

Respond with the current Estop system status.

Field Type Label 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 Label 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 Label 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 Label 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 Label 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.
STATUS_MOTORS_ON 4 You cannot deregister an endpoint while the motors are on.

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.
STATUS_MOTORS_ON 4 You cannot set a configuration while the motors are on.

Top

bosdyn/api/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.

Top

bosdyn/api/fault_service.proto

FaultService

The service fault service enables modification of the robot state ServiceFaultState.

Method Name Request Type Response Type Description
TriggerServiceFault TriggerServiceFaultRequest TriggerServiceFaultResponse Sends a ServiceFault to be reporting in robot state.
ClearServiceFault ClearServiceFaultRequest ClearServiceFaultResponse Clears an active ServiceFault from robot state.

Top

bosdyn/api/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 Label 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.
battery_change_pose_feedback BatteryChangePoseCommand.Feedback Feedback for the battery change pose command request.
payload_estimation_feedback PayloadEstimationCommand.Feedback Feedback for the payload estimation command request.
constrained_manipulation_feedback ConstrainedManipulationCommand.Feedback Feedback for the constrained manipulation command request
joint_feedback JointCommand.Feedback Feedback for joint level control
status RobotCommandFeedbackStatus.Status

FullBodyCommand.Request

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

Field Type Label 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.
battery_change_pose_request BatteryChangePoseCommand.Request Command to put the robot in a position to easily change the battery.
payload_estimation_request PayloadEstimationCommand.Request Command to perform payload mass property estimation
constrained_manipulation_request ConstrainedManipulationCommand.Request Command to perform full body constrained manipulation moves
joint_request JointCommand.Request Activate joint level control
params google.protobuf.Any Robot specific command parameters.

Top

bosdyn/api/geometry.proto

Area

Represents an area in the XY plane.

Field Type Label Description
polygon Polygon
circle Circle

Bounds

Represents bounds on a value, such that lower < value < upper. If you do not want to specify one side of the bound, set it to an appropriately large (or small) number.

Field Type Label Description
lower double
upper double

Box2

Geometric primitive describing a two-dimensional box.

Field Type Label Description
size Vec2

Box2WithFrame

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

Field Type Label 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 Label Description
size Vec3

Box3WithFrame

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

Field Type Label 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 Label 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 Label Description
r double Radial coordinate
theta double Azimuthal coordinate
z double Vertical coordiante

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 “parent” 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 frae, 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 Label Description
child_to_parent_edge_map FrameTreeSnapshot.ChildToParentEdgeMapEntry repeated child_to_parent_edge_map maps the child frame name to the ParentEdge.
In aggregate, this forms the tree structure.

FrameTreeSnapshot.ChildToParentEdgeMapEntry

Field Type Label Description
key string
value FrameTreeSnapshot.ParentEdge

FrameTreeSnapshot.ParentEdge

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

Field Type Label Description
parent_frame_name string The name of the parent frame. If a frame has no parent (parent_frame_name is empty),
it is the root of the tree.
parent_tform_child SE3Pose Transform representing the pose of the child frame in the parent's frame.

Matrix

Represents a row-major order matrix of doubles.

Field Type Label Description
rows int32
cols int32
values double repeated

MatrixInt32

Represents a row-major order matrix of int32.

Field Type Label Description
rows int32
cols int32
values int32 repeated

MatrixInt64

Represents a row-major order matrix of int64.

Field Type Label Description
rows int32
cols int32
values int64 repeated

Matrixf

Represents a row-major order matrix of floats.

Field Type Label Description
rows int32
cols int32
values float repeated

Plane

Plane primitive, described with a point and normal.

Field Type Label 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 Label Description
points Vec2 repeated

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 Label Description
vertexes Vec2 repeated

PolygonWithExclusions

Represents a region in the XY plane that consists of a single polygon from which polygons representing exclusion areas may be subtracted.

A point is considered to be inside the region if it is inside the inclusion polygon and not inside any of the exclusion polygons.

Note that while this can be used to represent a polygon with holes, that exclusions are not necessarily holes: An exclusion polygon may not be completely inside the inclusion polygon.

Field Type Label Description
inclusion Polygon
exclusions Polygon repeated

Quad

A square oriented in 3D space.

Field Type Label Description
pose SE3Pose The center of the quad and the orientation of the normal.
The normal axis is [0, 0, 1].
size double The side length of the quad.

Quaternion

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

Field Type Label Description
x double
y double
z double
w double

Ray

A ray in 3D space.

Field Type Label Description
origin Vec3 Base of ray.
direction Vec3 Unit vector defining the direction of the ray.

SE2Pose

Geometric primitive to describe 2D position and rotation.

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

SE2Velocity

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

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

SE2VelocityLimit

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

Field Type Label 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. The 6x6 matrix can be viewed as the covariance among 6 variables:
rx ry rz x y z
rx rxrx rxry rxrz rxx rxy rxz
ry ryrx ryry ryrz ryx ryy ryz
rz rzrx rzry rzrz rzx rzy rzz
x xrx xry xrz xx xy xz
y yrx yry yrz yx yy yz
z zrx zry zrz zx zy zz
where x, y, z are translations in meters, and rx, ry, rz are rotations around the x, y and z axes in radians.
The matrix is symmetric, so, for example, xy = yx. \

Field Type Label Description
matrix Matrix Row-major order representation of the covariance matrix.
yaw_variance double Deprecated. Variance of the yaw component of the SE3 Pose.
Warning: DEPRECATED as of 2.1. This should equal cov_rzrz, inside matrix. Will be removed
in a future release.
FIXME(sberard): https://bostondynamics.atlassian.net/browse/SPOT-12523
cov_xx double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_xy double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_xz double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_yx double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_yy double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_yz double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_zx double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_zy double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.
cov_zz double Deprecated. Warning: DEPRECATED as of 2.1. Use 'matrix.' Will be removed in a future release.

SE3Pose

Geometric primitive to describe 3D position and rotation.

Field Type Label Description
position Vec3 (m)
rotation Quaternion

SE3Velocity

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

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

Vec2

Two dimensional vector primitive.

Field Type Label 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 Label Description
x google.protobuf.DoubleValue
y google.protobuf.DoubleValue

Vec3

Three dimensional vector primitive.

Field Type Label 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 Label Description
x google.protobuf.DoubleValue
y google.protobuf.DoubleValue
z google.protobuf.DoubleValue

Vector

Represents a vector of doubles

Field Type Label Description
values double repeated

Volume

Represents a volume of space in an unspecified frame.

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

Wrench

Geometric primitive used to specify forces and torques.

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

Top

bosdyn/api/gps/aggregator.proto

NewGpsDataRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
data_points GpsDataPoint repeated GPS Measurements. GPS units that generate data at a high rate
can bundle multiple measurements together in a single message.
gps_device GpsDevice Describer for what device is generating GPS data.

NewGpsDataResponse

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

Top

bosdyn/api/gps/aggregator_service.proto

AggregatorService

The AggregatorService is an endpoint that clients should send GPS data too. Data dumped into the AggregatorService is used by the RegistrationService. In practice: - A GPS will be connected to a peripheral computer - The peripheral computer should establish timesync with the robot - The peripheral computer should read data from the GPS hardware - The peripheral computer should send timestamped data to the AggregatorService

Method Name Request Type Response Type Description
NewGpsData NewGpsDataRequest NewGpsDataResponse

Top

bosdyn/api/gps/gps.proto

GpsDataPoint

Field Type Label Description
llh LLH The GPS measurement as Latitude, Longitude, Height.
ecef bosdyn.api.Vec3 The GPS measurement with respect to the Earth Centered Earth Fixed frame
yaw google.protobuf.DoubleValue Magnetometer yaw. 0 is north. Processes counter clockwise. We did this to match Spot's
body coordinate system, where Z is up.
heading google.protobuf.DoubleValue Movement heading. 0 is north. Processes counter clockwise. We did this to match Spot's
body coordinate system, where Z is up.
accuracy GpsDataPoint.Accuracy
satellites GpsDataPoint.Satellite repeated Satellites used in the location solution.
mode GpsDataPoint.FixMode The current fix, if any.
timestamp_gps google.protobuf.Timestamp GPS timestamp. This will not match robot time.
filter GpsDataPoint.Filter
timestamp_client google.protobuf.Timestamp Optional field corresponding the timestamp of the computer the GPS is connected
to (if any).
timestamp_robot google.protobuf.Timestamp Robot timestamp.
body_tform_gps bosdyn.api.SE3Pose How the GPS is mounted relative to the robots body.

GpsDataPoint.Accuracy

Estimated accuracy is measured in meters

Field Type Label Description
horizontal double
vertical double

GpsDataPoint.FixMode

Field Type Label Description
value GpsDataPoint.FixMode.Mode The current type of fix.

GpsDataPoint.Satellite

Information about a GNSS satellite measurement.

Field Type Label Description
prn uint32 satellite identifier
elevation float Degrees from -90 to 90
azimuth float Degrees from true north
snr float in dB
constellation GpsDataPoint.Satellite.Constellation

GpsDevice

Field Type Label Description
name string A human readable name for this GPS unit. "Piksi" or "Duro" or "Microstrain"

LLH

Latitude/longitude location representation.

Field Type Label Description
latitude double Latitude value in degrees.
longitude double Longitude value in degrees.
height double Height value in meters. The reference system from where the height is
calculated is controlled by the application generating this structure.

LocationAndGpsDevice

Field Type Label Description
data_point GpsDataPoint
device GpsDevice

GpsDataPoint.Filter

Name Number Description
FILTER_UNKNOWN 0
FILTER_NONE 1
FILTER_DURO_INS 2

GpsDataPoint.FixMode.Mode

Types of fixes possible.

Name Number Description
Invalid 0
SPP 1 Single Point Positioning
DGNSS 2 Differential Global Navigation Satellite System
PPS 3 Precise Positioning System Fix
FIXED_RTK 4 Fixed-Point Real-Time Kinematics
FLOAT_RTK 5 Floating-Point Real-Time Kinematics
DEAD_RECKONING 6
FIXED_POSITION 7
SIMULATED 8
SBAS 9 Satellite Based Augmentation System

GpsDataPoint.Satellite.Constellation

Name Number Description
UNKNOWN 0
GPS_L1CA 1
GPS_L2CM 2
SBAS_L1CA 3
GLONASS_L1CA 4
GLONASS_L2CA 5
GPS_L1P 6
GPS_L2P 7
BDS2_B1 8 BDS stands for the BeiDou Navigation Satellite System
BDS2_B2 9
GALILEO_E1B 10
GALILEO_E7I 11

Top

bosdyn/api/gps/registration.proto

GetLocationRequest

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

GetLocationResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status GetLocationResponse.Status
registration Registration

GpsState

Field Type Label Description
latest_data GpsDataPoint Latest data from the GPS device.
gps_device GpsDevice What GPS device generated the latest data
ecef_p_body bosdyn.api.Vec3 Estimate of where the robot's body is in the ECEF frame given this measurement. Note this must be a position
and not a pose because of the lack of orientation data.
historical_data GpsDataPoint repeated Collection of all GPS data received by this device within some window.

Registration

Field Type Label Description
status Registration.Status
timestamp google.protobuf.Timestamp Time stamp of latest registration.
transforms_snapshot bosdyn.api.FrameTreeSnapshot Includes all normal robots frames ("body", "odom", etc) AND
"ecef" frame, which you can read about here: https://wikipedia.org/wiki/ECEF
robot_body_location LLH The estimated position of the robot's body frame in LLH form. This position is filtered.
gps_states GpsState repeated Most recent data from each GPS. Note that the LLH the GPS is reporting
won't exactly match robot_body_location, because robot_body_location is
filtered, and the GPS might have some offset relative to the robot's body.

ResetRegistrationRequest

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

ResetRegistrationResponse

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

GetLocationResponse.Status

Quality of registration status.

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_NEED_DEVICE 2

Registration.Status

Quality of registration status.

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_NEED_DATA 2 No data has been reported to perform registration.
STATUS_NEED_MORE_DATA 3 Data has been reported, but not enough to get a fix.
STATUS_STALE 4 We have a registration, but it is based on old data.

Top

bosdyn/api/gps/registration_service.proto

RegistrationService

The RegistrationService consumes data sent to the Gps/AggregatorService. It calculates where the robot is in the world, and the transfroms from the robots internal frames to the world frame.

Method Name Request Type Response Type Description
GetLocation GetLocationRequest GetLocationResponse
ResetRegistration ResetRegistrationRequest ResetRegistrationResponse

Top

bosdyn/api/graph_nav/area_callback.proto

AreaCallbackError

Error reporting for things that can go wrong with calls.

Field Type Label Description
service_name string
error AreaCallbackError.CallError
begin_callback BeginCallbackResponse
begin_control BeginControlResponse
update_callback UpdateCallbackResponse
end_callback EndCallbackResponse

AreaCallbackInformation

Specific information about how a AreaCallback implementation should be called. All fields are optional, and need only be filled out if the desired behavior is different from the default.

Field Type Label Description
required_lease_resources string repeated A area callback can request to be in control of one or more resources at runtime.
custom_params bosdyn.api.DictParam.Spec Parameters this area callback supports that do not match any of the other fields.
blockage AreaCallbackInformation.Blockage
impairment_check AreaCallbackInformation.Impairment
entity_waiting AreaCallbackInformation.EntityWaiting
default_stop StopConfiguration How the robot should stop at waypoints by default.
map_config AreaCallbackMapConfig Configuration to store in the map about how to treat the region edges.

AreaCallbackInformationRequest

Message for requesting information about a area callback implementation.

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

AreaCallbackInformationResponse

Message for providing information about a area callback implementation.

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
info AreaCallbackInformation Information about how the AreaCallback should be called.

BeginCallbackRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
region_info RegionInformation Description of the region we are going to cross.
end_time google.protobuf.Timestamp The timestamp (in robot time) by which a command must finish executing.
If unset, a AreaCallback implementation may pick a reasonable value.
recorded_data AreaCallbackData Configuration data associated with this area callback region
custom_params bosdyn.api.DictParam Any other custom parameters to the callback.

BeginCallbackResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status BeginCallbackResponse.Status Return status for the request.
command_id uint32 Unique identifier for the AreaCallback, used to update the callback in subsequent calls. If
empty, the request was not accepted.
custom_param_error bosdyn.api.CustomParamError Filled out if status is STATUS_CUSTOM_PARAMS_ERROR.

BeginControlRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
leases bosdyn.api.Lease repeated Leases that a AreaCallback uses once it takes control of the robot. This list should match
AreaCallbackInformation required_lease_resources.
command_id uint32 The command id associated with a single execution of a navigation callback.

BeginControlResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_results bosdyn.api.LeaseUseResult repeated Details about how the lease was used.
status BeginControlResponse.Status Return status for the request.

EndCallbackRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
command_id uint32 The command id associated with a single execution of a navigation callback.

EndCallbackResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status EndCallbackResponse.Status Return status for the request.

RegionInformation

Description of an Area Callback region at the time of crossing

Field Type Label Description
region_id string The unique id of the region we are entering.
description string Human-readable description of the region we are entering.
route Route The planned route through the region.

RouteChangeRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
command_id uint32 The command id for which the route is changing.
route Route The new planned route through the region.
unfinished_route Route The remaining old route that was not completed.

RouteChangeResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status RouteChangeResponse.Status

StopConfiguration

Information about how the robot should behave when stopping at a location.

Field Type Label Description
face_direction StopConfiguration.FaceDirection Which direction the robot should face when lining up at a waypoint.
face_stairs_if_present bool If true, always align to stairs at the start of the callback.
Overrides face_direction if stairs are found.
face_yaw_offset google.protobuf.DoubleValue Offset applied to the above facing direction (radians).
max_distance google.protobuf.DoubleValue How close the robot needs to be to the desired pose (meters).
max_yaw google.protobuf.DoubleValue How close the robot needs to be to the desired pose (radians).

UpdateCallbackRequest

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
command_id uint32 The command id associated with a single execution of a navigation callback.
end_time google.protobuf.Timestamp If set, update the end time (in robot time) by which a command must finish executing.
stage UpdateCallbackRequest.Stage

UpdateCallbackResponse

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
status UpdateCallbackResponse.Status Return status for the request.
policy UpdateCallbackResponse.NavPolicy Set the control policy that Graph Nav should use when crossing this region, and
how and when Graph Nav should delegate control to or wait for the callback.
This is the expected way to respond, and changing the policy is how a callback
instructs graph nav to wait or continue on.
error UpdateCallbackResponse.Error An error has occurred. Graph Nav will stop calling UpdateCallback and will call
EndCallback.
complete UpdateCallbackResponse.Complete The area callback is complete. Graph Nav will stop calling UpdateCallback and will call
EndCallback.
localization UpdateCallbackResponse.UpdateLocalization Localization changes inform Graph Nav when the callback has moved the robot,
and are ignored unless callback has control of the robot.

UpdateCallbackResponse.Complete

UpdateCallbackResponse.Error

Field Type Label Description
error UpdateCallbackResponse.Error.ErrorType
lease_use_results bosdyn.api.LeaseUseResult repeated Details about how the lease was used. Only set when error == ERROR_LEASE.

UpdateCallbackResponse.NavPolicy

Field Type Label Description
at_start UpdateCallbackResponse.NavPolicy.Option Policy for what Graph Nav should do at the start of the region.
at_end UpdateCallbackResponse.NavPolicy.Option Policy for what Graph Nav should do at the end of the region.
end_config StopConfiguration Override the default settings for how the robot should behave at the end.
Does not apply for OPTION_CONTINUE.

UpdateCallbackResponse.UpdateLocalization

Field Type Label Description
change UpdateCallbackResponse.UpdateLocalization.LocalizationChange Change the localization within GraphNav.

AreaCallbackError.CallError

Name Number Description
ERROR_UNKNOWN 0
ERROR_TRANSPORT 1 Unable to communicate with the callback.
ERROR_RESPONSE 2 The callback responded with an error.
ERROR_SERVICE 3 The service was not registered.

AreaCallbackInformation.Blockage

Specify what graph nav should expect to detect for blockages in this region. For example, if the callback can open doors, the region may initially look blocked due to a closed door, but Graph Nav should still expect it to be traversable.

Name Number Description
BLOCKAGE_UNKNOWN 0
BLOCKAGE_SKIP 1 (Default) The region may appear blocked to Graph Nav, but the callback will still be able
to traverse it. If the region is blocked, Graph Nav should consider it passable unless
it actually gets stuck trying to navigate it.
BLOCKAGE_CHECK 2 Graph Nav should expect the region to be clear. If the region is blocked, Graph Nav can
treat that as impassable.

AreaCallbackInformation.EntityWaiting

Control whether Graph Nav will stop and wait for nearby entities when crossing the region. Entity waiting is normally on for regular Graph Nav, but is by default turned off inside Area callback regions.

Name Number Description
ENTITY_WAITING_UNKNOWN 0
ENTITY_WAITING_DISABLE 1 (Default) Disable waiting for entities when crossing the region.
ENTITY_WAITING_ENABLE 2 Enable waiting for entities when crossing the region.

AreaCallbackInformation.Impairment

Specify whether graph nav should check for impairment when the callback is in control of the robot. Certain failures may make Graph Nav unable to navigate, but may not affect the callback. If the callback is in control of the robot, it may be preferable to let it finish and return control to Graph Nav before reporting any impaired error instead of interrupting the callback.

Name Number Description
IMPAIRMENT_UNKNOWN 0
IMPAIRMENT_SKIP 1 (Default) Do not check Graph Nav impairment when the callback is in control.
IMPAIRMENT_CHECK 2 Continue to check Graph Nav impairment when the callback is in control. If Graph Nav
detects that it is impaired, it will stop the callback immediately.

BeginCallbackResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used.
STATUS_OK 1 The area callback successfully began.
STATUS_INVALID_CONFIGURATION 2 The area callback failed to start due to some problem with the supplied
configuration_data.
STATUS_EXPIRED_END_TIME 3 The area callback end time already expired.
STATUS_CUSTOM_PARAMS_ERROR 8 One or more keys or values in custom_params are unsupported by the area callback.
See the custom_param_error for details.

BeginControlResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used.
STATUS_OK 1 The AreaCallback has successfully taken control of the robot.
STATUS_INVALID_COMMAND_ID 2 The request command id does not exist or is no longer executing.
STATUS_MISSING_LEASE_RESOURCES 3 The supplied lease does not match the leases requested in AreaCallbackInformation.
STATUS_LEASE_ERROR 4 A lease use error occurred.

EndCallbackResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used.
STATUS_OK 1 The AreaCallback has cleanly ended.
STATUS_INVALID_COMMAND_ID 2 The request command id does not exist or is no longer executing.
STATUS_SHUTDOWN_CALLBACK_FAILED 3 Shutting down the callback failed. The callback worker thread did not respond to shutdown
signal.

RouteChangeResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used.
STATUS_OK 1 The AreaCallback has acknowledged the route change.
STATUS_INVALID_COMMAND_ID 2 The request command id does not exist or is no longer executing.

StopConfiguration.FaceDirection

What direction robot should face.

Name Number Description
FACE_DIRECTION_UNKNOWN 0
FACE_DIRECTION_ALONG_ROUTE 1 (Default) Face along the direction of the next edges in the route,
regardless of the waypoint orientation.
FACE_DIRECTION_WAYPOINT_EXACT 2 Face in the direction of the recorded waypoint.
FACE_DIRECTION_WAYPOINT_AUTO 3 Face in the direction of the recorded waypoint, but if traversing the region in the
opposite direction to how it was recorded, flip the orientation 180 degrees.
FACE_DIRECTION_REGION_END 4 Face in the direction of the end of the region.

UpdateCallbackRequest.Stage

Name Number Description
STAGE_UNKNOWN 0
STAGE_TO_START 1 Traveling to the start of the region.
STAGE_AT_START 2 Waiting at the start of the region.
STAGE_TO_END 3 Traveling to the end of the region.
STAGE_AT_END 4 Waiting at the end of the region.

UpdateCallbackResponse.Error.ErrorType

Name Number Description
ERROR_UNKNOWN 0 UNKNOWN should never be used.
ERROR_BLOCKED 1 The callback has determined that this way is impassable.
ERROR_CALLBACK_FAILED 2 Something went wrong with the callback.
ERROR_LEASE 3 A lease error occurred while executing commands.
ERROR_TIMED_OUT 4 The callback has exceeded allowed execution time.

UpdateCallbackResponse.NavPolicy.Option

Name Number Description
OPTION_UNKNOWN 0
OPTION_CONTINUE 1 Continue past the waypoint. If not already stopped at it, do not stop.
OPTION_STOP 2 Stop at the waypoint.
OPTION_CONTROL 3 Stop at the waypoint and transfer control to the callback.

UpdateCallbackResponse.Status

Name Number Description
STATUS_UNKNOWN 0 UNKNOWN should never be used.
STATUS_OK 1 The AreaCallback is actively updating. If an execution error does occur, that is reported
via the response oneof.
STATUS_INVALID_COMMAND_ID 2 The request command id does not exist or is no longer executing.
STATUS_EXPIRED_END_TIME 3 The area callback end time already expired.

UpdateCallbackResponse.UpdateLocalization.LocalizationChange

Name Number Description
LOCALIZATION_UNKNOWN 0 When unset, Graph Nav will not change the localization.
LOCALIZATION_AT_END 1 The robot is now at the end of the region.

Top

bosdyn/api/graph_nav/area_callback_data.proto

AreaCallbackData

Data for a AreaCallback to be stored in the map

Field Type Label Description
config_data google.protobuf.Any Custom config data used by the service to do its job.
custom_params bosdyn.api.DictParam Any other custom parameters to the callback. This will be copied into
custom_params inside the BeginCallback RPC if it exists.
map_config AreaCallbackMapConfig Configuration data for how this area callback should be treated in the map.

AreaCallbackMapConfig

Configuration data for how an area callback should be treated in a map.

Top

bosdyn/api/graph_nav/area_callback_service.proto

AreaCallbackService

Method Name Request Type Response Type Description
AreaCallbackInformation AreaCallbackInformationRequest AreaCallbackInformationResponse Retrieve information about how to operate the service, including what lease resources are
required by the navigation callback.
BeginCallback BeginCallbackRequest BeginCallbackResponse BeginCallback is called once as the robot enters a AreaCallback region of a map. This call
initializes the navigation callback for operation.
BeginControl BeginControlRequest BeginControlResponse BeginControl is called once after the area callback implementation requests control. Control
is handed off (via a lease) from the caller to the area callback.
UpdateCallback UpdateCallbackRequest UpdateCallbackResponse UpdateCallback is called periodically while the callback is running. Area callback
implementations use UpdateCallback to dictate how caller should operate while callback is
running (pause, continue, etc.)
RouteChange RouteChangeRequest RouteChangeResponse Called only if the route changes in the middle of the region (for example, if the robot is
blocked by an obstacle and re-routes).
EndCallback EndCallbackRequest EndCallbackResponse EndCallback is called once when the caller decides the navigation callback is over. This
might be because the robot exited the callback region or might be because the callback
reported that it finished doing work.

Top

bosdyn/api/graph_nav/gps.proto

GPSLocalization

Info about GPS localization if the robot has this capability.

Field Type Label Description
live_gps_state GPSLocalization.State State of the live GPS data.
map_gps_state GPSLocalization.State State of GPS data at the current waypoint.
ecef_tform_body bosdyn.api.SE3Pose Estimate of where the robot body is in the Earth-Centered-Earth-Fixed (ECEF) frame at the time
of localization.
latitude_longitude_height bosdyn.api.gps.LLH Estimate of the latitude/longitude/height of the robot at the time of localization.

GPSLocalization.State

Name Number Description
STATE_UNKNOWN 0
STATE_OK 1 Using GPS.
STATE_BAD_FRAMES 2 Error getting frames (ko, etc.)
STATE_NO_GPS_OBJECTS 3 No GPS available.
STATE_REGISTRATION_NOT_OK 4 GPS registration isn't ready.
STATE_NO_GPS_STATES 5 No GPS state measurements.
STATE_NOT_ENOUGH_SATELLITES 6 Too few satellites to localize.
STATE_NO_ECEF_FRAME 7 GPS registration is missing a frame.
STATE_HIGH_ERROR 8 The GPS data exists, but is high error.
STATE_STALE 9 The GPS data exists, and we have not used it yet, but it is too old to use.
STATE_INTERNAL_ERROR 10 Internal error (e.g. missing waypoints).

Top

bosdyn/api/graph_nav/graph_nav.proto

AreaCallbackServiceError

Information about problems Area Callback services specifified in a map or on a route.

Field Type Label Description
missing_services string repeated Area Callback services that were requested but could not be contacted by graph nav.
A service is considered missing if it is either not registered, or if it is registered
but does not respond to a AreaCallbackInformation request.
faulted_services bosdyn.api.ServiceFault repeated Area Callback services that were requested but are reporting critical faults.

ClearGraphRequest

Clears the graph on the server. Also clears GraphNav’s localization to the graph. Note that waypoint and edge snapshots may still be cached on the server after this operation. This RPC may not be used while recording a map.

Field Type Label 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 Label Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.
status ClearGraphResponse.Status Status of the ClearGraphResponse.

DownloadEdgeSnapshotRequest

The DownloadEdgeSnapshot request asks for a specific edge snapshot id to be downloaded. Edge snapshots contain the large sensor data stored in each edge.

Field Type Label 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 in data chunks no larger than 4MB in size. It is necessary to stream these data to avoid overwhelming gRPC with large http requests.

Field Type Label 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. Responses are sent in sequence until the
data chunk is complete. After receiving all chunks, concatenate them
into a single byte string. Then, deserialize the byte string into an
EdgeSnapshot object.

DownloadGraphRequest

The DownloadGraphRequest requests that the server send the graph (waypoints and edges) to the client. Note that the returned Graph message contains only the topological structure of the map, and not any large sensor data. Large sensor data should be downloaded using DownloadWaypointSnapshotRequest and DownloadEdgeSnapshotRequest. Both snapshots and the graph are required to exist on the server for GraphNav to localize and navigate.

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

DownloadGraphResponse

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

Field Type Label 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. After recording a map, first call the DownloadGraph RPC. Then, for each waypoint snapshot id, request the waypoint snapshot from the server using the DownloadWaypointSnapshot RPC.

Field Type Label 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.
do_not_download_point_cloud bool Skip downloading the point cloud, and only download other data such as images or world
objects.

DownloadWaypointSnapshotResponse

The DownloadWaypointSnapshot response streams the data of the waypoint snapshot id currently being downloaded in data chunks no larger than 4MB in size. It is necessary to stream these data to avoid overwhelming gRPC with large http requests.

Field Type Label 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. After receiving all chunks, concatenate them
into a single byte string. Then, deserialize the byte string into a
WaypointSnapshot object.

GPSNavigationParams

Parameters controlling how the robot will navigate to a GPS coordinate.

Field Type Label Description
goal_llh bosdyn.api.gps.LLH The goal position as latitude/longitude. Height is ignored.
goal_yaw google.protobuf.DoubleValue Counter-clockwise rotation in radians around the "up" axis that the robot will try to achieve at the goal. This is a bearing
around the "up" axis such that East points to zero yaw, and West is pi radians yaw. If not provided, the robot will try to
achieve any allowable orientation at the goal.
max_distance_from_map google.protobuf.DoubleValue The maximum distance we are willing to accept for the LLH coordinate from the mapped data in meters. This
is a 2 dimensional measurement (height is not considered). If not filled out, Spot will decide based on
internal defaults.

GetLocalizationStateRequest

The GetLocalizationState request message requests the current localization state and any other live data from the robot if desired. The localization consists of a waypoint ID and the relative pose of the robot with respect to that waypoint.

Field Type Label Description
header bosdyn.api.RequestHeader Common request header.
waypoint_id string Return the localization relative to this waypoint, if specified.
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.
request_gps_state bool If true, request data about the robot's GPS localization.

GetLocalizationStateResponse

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

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
localization Localization Where the robot currently is. If a waypoint_id was specified in the request, this localization
will be relative to that waypoint.
robot_kinematics bosdyn.api.KinematicState Robot kinematic state at time of localization.
remote_cloud_status RemotePointCloudStatus repeated 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.
gps GPSLocalization If the robot has GPS capability and the map was recorded with GPS, this message will show graph nav's estimate of
the robot location in earth-centered frames. To see the raw GPS data, look at the WorldObject list.

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 Label 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.

ModifyNavigationResponse

Field Type Label Description
header bosdyn.api.ResponseHeader
lease_use_results bosdyn.api.LeaseUseResult repeated Results of using the various leases.
status ModifyNavigationResponse.Status Status code specific to the ModifyNavigationResponse.

RemotePointCloudStatus

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

Field Type Label 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.

RouteFollowingParams

These parameters are specific to how the robot follows a specified route in NavigateRoute.

For each enum in this message, if UNKNOWN is passed in, we default to one of the values (indicated in the comments). Passing UNKNOWN is not considered a programming error.

Field Type Label Description
new_cmd_behavior RouteFollowingParams.StartRouteBehavior
existing_cmd_behavior RouteFollowingParams.ResumeBehavior
route_blocked_behavior RouteFollowingParams.RouteBlockedBehavior

RouteGenParams

SensorCompatibilityStatus

Info on whether the robot’s current sensor setup is compatible with the recorded data in the map.

Field Type Label Description
map_has_lidar_data bool If true, the loaded map has LIDAR data in it.
robot_configured_for_lidar bool If true, the robot is currently configured to use LIDAR data.

SetLocalizationRequest

The SetLocalization request is used to initialize or reset the localization of GraphNav to a map. A localization consists of a waypoint ID, and a pose of the robot relative to that waypoint. GraphNav uses the localization to decide how to navigate through a map. The SetLocalizationRequest contains parameters to help find a correct localization. For example, AprilTags (fiducials) may be used to set the localization, or the caller can provide an explicit guess of the localization. Once the SetLocalizationRequest completes, the current localization to the map will be modified, and can be retrieved using a GetLocalizationStateRequest.

Field Type Label 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.
If no detection of this fiducial exists, the service will return STATUS_NO_MATCHING_FIDUCIAL.
If detections exist, but are low quality, STATUS_FIDUCIAL_TOO_FAR_AWAY, FIDUCIAL_TOO_OLD, or FIDUCIAL_POSE_UNCERTAIN will be returned.
do_ambiguity_check bool If true, consider how nearby localizations appear (like turned 180).
restrict_fiducial_detections_to_target_waypoint bool If using FIDUCIAL_INIT_SPECIFIC and this is true, the initializer will only consider
fiducial detections from the target waypoint (from initial_guess). Otherwise, if the
target waypoint does not contain a good measurement of the desired fiducial, nearby waypoints
may be used to infer the robot's location.
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.
refine_with_visual_features VisualRefinementOptions Improve localization based on images from body cameras

SetLocalizationResponse

The SetLocalization response message contains the resulting localization to the map.

Field Type Label 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.
impaired_state bosdyn.api.RobotImpairedState If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
sensor_status SensorCompatibilityStatus This status determines whether the robot has compatible sensors for the
map that was recorded. Note that if sensors aren't working, STATUS_IMPAIRED
will be returned, rather than STATUS_INCOMPATIBLE_SENSORS.
quality_check_result SetLocalizationResponse.QualityCheckResult Graph Nav will check the quality of the resulting localization and report the status
here. Note that to preserve backwards compatability with 3.2 and earlier, a poor quality check
does not result in this RPC failing.

SetLocalizationResponse.SuspectedAmbiguity

Field Type Label 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 Label 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.
feature_quality_tolerance TravelParams.FeatureQualityTolerance
disable_directed_exploration bool Disable directed exploration to skip blocked portions of route
disable_alternate_route_finding bool Disable alternate-route-finding; overrides the per-edge setting in the map.
path_following_mode Edge.Annotations.PathFollowingMode Path following mode
blocked_path_wait_time google.protobuf.Duration Time to wait for blocked path to clear (seconds)
ground_clutter_mode Edge.Annotations.GroundClutterAvoidanceMode Ground clutter avoidance mode.

UploadEdgeSnapshotRequest

Used to upload edge data in chunks for a specific edge snapshot. Edge snapshots contain large sensor data associated with each edge. Chunks will be streamed one at a time to the server. Chunk streaming is required to prevent overwhelming gRPC with large http requests.

Field Type Label Description
header bosdyn.api.RequestHeader Common response header.
chunk bosdyn.api.DataChunk Serialized bytes of a EdgeSnapshot message, restricted to a chunk no larger than 4MB in size.
To break the data into chunks, first serialize it to bytes. Then, send the bytes in order as DataChunk objects.
The chunks will be concatenated together on the server, and deserialized
lease bosdyn.api.Lease The Leases to show ownership of the graph-nav service.

UploadEdgeSnapshotResponse

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

Field Type Label Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.
map_stats MapStats General map statistics after upload.

UploadGraphRequest

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

Field Type Label 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.
generate_new_anchoring bool If this is true, generate an (overwrite the) anchoring on upload.
treat_validation_warnings_as_errors bool If true, validation warnings will be treated as errors, and STATUS_INVALID_GRAPH will be returned. This is false by
default.

UploadGraphResponse

Response to the UploadGraphRequest. After uploading a graph, the user is expected to upload large data at waypoints and edges (called snapshots). The response provides a list of snapshot IDs which are not yet cached on the server. Snapshots with these IDs should be uploaded by the client.

Field Type Label 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 repeated The waypoint snapshot ids for which there was cached data.
unknown_waypoint_snapshot_ids string repeated The waypoint snapshot ids for which there is no cached data.
loaded_edge_snapshot_ids string repeated The edge snapshot ids for which there was cached data.
unknown_edge_snapshot_ids string repeated 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.
sensor_status SensorCompatibilityStatus
area_callback_error AreaCallbackServiceError Errors about Area Callbacks in the map.
map_stats MapStats General map statistics.
validation_status UploadGraphResponse.ValidationStatus If the returned status is STATUS_INVALID_GRAPH, this contains the detailed information about why the
graph was invalid. Note that some graph validation errors are warnings and the robot will be able to navigate
on the graph even when they are present.

UploadGraphResponse.ValidationStatus

Detailed information about why STATUS_INVALID_GRAPH was returned. This will only contain information if the UploadGraph request could not be validated.

Field Type Label Description
missing_waypoint_ids_in_edges string repeated One or more edges references a waypoint that doesn't exist. There are the waypoint IDs
referenced by edges that do not exist. This is an error. Fix the graph and re-upload.
missing_waypoint_ids_in_anchors string repeated The anchoring uploaded referenced waypoint IDs that do not exist. These
are the missing IDs. This is a warning. The anchorings will be ignored.
edge_ids_invalid_transform Edge.Id repeated One or more edges had an invalid from_tform_to transform. These are the edge IDs uploaded
that have an invalid transform. Valid transforms have quaternion rotations that are normalized.
This is a warning. Edges with invalid transforms will be fixed on upload.
waypoint_anchors_invalid_transform string repeated One or more waypoint anchors in the anchoring have an invalid transform. These are the waypoint IDs
that have an invalid transform. Valid transforms have quaternion rotations that are normalized.
This is a warning. Anchors with invalid transforms will be fixed on upload.
object_anchors_invalid_transform string repeated One or more of the object achors in the anchoring have an invalid transform. These are the object IDs
that have an invalid transform. Valid transforms have quaternion rotations that are normalized.
This is a warning. Anchors with invalid transforms will be fixed on upload.
duplicate_waypoint_ids string repeated The Graph in the UploadGraph request contained more than one waypoint with the same ID. These are the
waypoint IDs which occur in the UploadGraph request more than once. Note that IDs are duplicated in this list
the same number of times they are duplicated in the request.
This is an error. Fix the graph and re-upload.
duplicate_waypoint_anchor_ids string repeated The anchoring contains one or more anchor IDs that are duplicated. Note that IDs are duplicated in this list
the same number of times they are duplicated in the request. This is a warning. Only the first anchor will be used.
duplicate_object_anchor_ids string repeated The anchoring contains one or more object anchor IDs that are duplicated. Note that IDs are duplicated in this list
the same number of times they are duplicated in the request. This is a warning. Only the first anchor will be used.
duplicate_edge_ids Edge.Id repeated The Graph in the UploadGraph request contained more than one edge with the equivalent ID. These are the edge IDs
which occur in the UploadGraph request more than once. Note that IDs are duplicated in this list the same number
of times that they are duplicated in the request. Note that edges are not directional, and it is impossible
to have both a->b and b->a in the same map. This is an error. Fix the graph and re-upload.
invalid_waypoint_ids_self_edges string repeated Edges are not allowed to have the same "from" and "to" waypoint. These are the waypoint IDs which have self
edges in the UploadGraph request. This is an error. Fix the graph and re-upload.
has_empty_waypoint_ids bool At least one waypoint in the graph has an empty ID. This is an error. Fix the graph and re-upload.
has_empty_edge_ids bool At least one edge in the graph references a waypoint with an empty ID.
This is an error. Fix the graph and re-upload.
has_empty_waypoint_anchor_ids bool At least one waypoint anchor in the anchoring has an empty ID. This is a warning. Empty anchors will be ignored.
has_empty_object_anchor_ids bool At least one object anchor in the anchoring has an empty ID. This is a warning. Empty anchors will be ignored.
malformed_staircase_edge_ids Edge.Id repeated One or more edges had a malformed staircase annotation. This is an error. Remove, rerecord, or fix the annotation.

UploadWaypointSnapshotRequest

Used to upload waypoint snapshot in chunks for a specific waypoint snapshot. Waypoint snapshots consist of the large sensor data at each waypoint. Chunks will be streamed one at a time to the server. Chunk streaming is required to prevent overwhelming gRPC with large http requests.

Field Type Label Description
header bosdyn.api.RequestHeader Common response header.
chunk bosdyn.api.DataChunk Serialized bytes of a WaypointSnapshot message, restricted to a chunk no larger than 4MB in size.
To break the data into chunks, first serialize it to bytes. Then, send the bytes in order as DataChunk objects.
The chunks will be concatenated together on the server, and deserialized.
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 Label Description
header bosdyn.api.ResponseHeader Common response header.
lease_use_result bosdyn.api.LeaseUseResult Details about how the lease was used.
status UploadWaypointSnapshotResponse.Status
sensor_status SensorCompatibilityStatus
map_stats MapStats General map statistics after upload.

ValidateGraphRequest

Run a check on the currently loaded map.

Field Type Label Description
header bosdyn.api.RequestHeader

ValidateGraphResponse

Report possible errors with the loaded map.

Field Type Label Description
header bosdyn.api.ResponseHeader
status ValidateGraphResponse.Status Status of the currently loaded map.
sensor_status SensorCompatibilityStatus
area_callback_error AreaCallbackServiceError Errors about Area Callbacks in the map.

VisualRefinementOptions

Field Type Label Description
verify_refinement_quality bool Whether to return a STATUS_VISUAL_ALIGNMENT_FAILED if refine_with_visual_features fails.

ClearGraphResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_RECORDING 2 Graph Nav is currently recording a map. You must call
StopRecording from the recording service to continue.

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.

ModifyNavigationResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1 Modify request was accepted.
STATUS_UNRECOGNIZED_COMMAND 2 The command ID wasn't the ID of the last command.

RouteFollowingParams.ResumeBehavior

This setting applies when a NavigateRoute command is issued with the same route and final-waypoint-offset. It is not necessary that command_id indicate the same command. The expected waypoint is the last waypoint that GraphNav was autonomously navigating to.

Name Number Description
RESUME_UNKNOWN 0 The mode is unset.
RESUME_RETURN_TO_UNFINISHED_ROUTE 1 The robot will find the shortest path to any point on the route after the
furthest-along traversed edge, and go to the point that gives that shortest path.
Then, the robot will follow the rest of the route from that point.
This is the default.
RESUME_FAIL_WHEN_NOT_ON_ROUTE 2 The robot will fail the command with status STATUS_NOT_LOCALIZED_TO_ROUTE.

RouteFollowingParams.RouteBlockedBehavior

This setting applies when the robot discovers that the route is blocked.

Name Number Description
ROUTE_BLOCKED_UNKNOWN 0 The mode is unset.
ROUTE_BLOCKED_REROUTE 1 For NavigateToRequests, the robot will find the shortest path to the desination
that avoids the blockage.
For NavigateRouteRequests, the robot will find the shortest path to any point
after the furthest-along blockage, and after the furthest-along traversed edge,
and go to the point that gives that shortest path. Then, the robot will follow
the rest of the route from that point. If multiple points on the route are
similarly close to the robot, the robot will prefer the earliest on the route.
This is the default.
ROUTE_BLOCKED_FAIL 2 The robot will fail the command with status STATUS_STUCK;

RouteFollowingParams.StartRouteBehavior

This setting applies when a new NavigateRoute command is issued (different route or final-waypoint-offset), and command_id indicates a new command.

Name Number Description
START_UNKNOWN 0 The mode is unset.
START_GOTO_START 1 The robot will find the shortest path to the start of the route, possibly using
edges that are not in the route. After going to the start, the robot will follow the
route.
START_GOTO_ROUTE 2 The robot will find the shortest path to any point on the route, and go to the point
that gives that shortest path. Then, the robot will follow the rest of the route from
that point.
If multiple points on the route are similarly close to the robot, the robot will
prefer the earliest on the route.
This is the default.
START_FAIL_WHEN_NOT_ON_ROUTE 3 The robot will fail the command with status STATUS_NOT_LOCALIZED_TO_ROUTE.

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 (from initial_guess).
FIDUCIAL_INIT_SPECIFIC 4 Localize to the given fiducial at the target waypoint (from initial_guess) if it exists, or any waypoint otherwise.

SetLocalizationResponse.QualityCheckResult

Name Number Description
QUALITY_CHECK_UNKNOWN 0 Unset. Note that the quality check is only performed if the overall Status
enum returns STATUS_SUCCESS, and will be unset otherwise.
QUALITY_CHECK_SUCCESS 1 The quality check passed.
QUALITY_CHECK_POOR_POINT_CLOUD_MATCH 2 After applying the localization, a poor point cloud match to the map was detected.
This can happen if, for example, the map has changed, or the starting location
of the robot is now very different than it was at recording time.
QUALITY_CHECK_POOR_GRAVITY_ALIGNMENT 3 After applying the localization, Graph Nav checked the localization, and found that
the robot's gravity vector does not align with the map's. This can happen if a fiducial
being used to align to the map was detected wrongly during recording, or if the robot's
IMU is miscalibrated. It can also occur when the inital guess passed in to the SetLocalization
RPC is in the incorrect reference frame.
QUALITY_CHECK_SKIPPED 4 There wasn't enough data to make a determination about quality.
QUALITY_CHECK_BAD_HEIGHT 5 The prior passed in is too different from the expected height of the robot e.w.r.t the 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.
STATUS_FIDUCIAL_TOO_FAR_AWAY 6 Failed to localize because the fiducial requested by 'use_fiducial_id' was too far away from
the robot.
STATUS_FIDUCIAL_TOO_OLD 7 Failed to localize because the fiducial requested by 'use_fiducial_id' had a detection time that was too
far in the past.
STATUS_NO_MATCHING_FIDUCIAL 8 Failed to localize because the fiducial requested by 'use_fiducial_id' did not exist in the map at
the required location.
STATUS_FIDUCIAL_POSE_UNCERTAIN 9 Failed to localize because the fiducial requested by 'use_fiducial_id' had an unreliable
pose estimation, either in the current detection of that fiducial, or in detections that
were saved in the map. Note that when using FIDUCIAL_INIT_SPECIFIC, fiducial detections at
the target waypoint will be used so long as they are not uncertain -- otherwise, detections
at adjacent waypoints may be used. If there exists no uncertain detection of the fiducial
near the target waypoint in the map, the service returns this status.
STATUS_INCOMPATIBLE_SENSORS 10 The localization could not be set, because the map was recorded using a different sensor
setup than the robot currently has onboard. See SensorStatus for more details.
STATUS_VISUAL_ALIGNMENT_FAILED 11 Visual feature based alignment failed or the pose solution was considered unreliable.

TravelParams.FeatureQualityTolerance

Indicates whether robot will navigate through areas with poor quality features

Name Number Description
TOLERANCE_UNKNOWN 0 Unknown value
TOLERANCE_DEFAULT 1 Navigate through default number of waypoints with poor quality features
TOLERANCE_IGNORE_POOR_FEATURE_QUALITY 2 Navigate through unlimited number of waypoints with poor quality features

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.
STATUS_INVALID_GRAPH 4 The graph or its anchoring are invalid. See the ValidationStatus for more details.
STATUS_INCOMPATIBLE_SENSORS 5 The sensor data associated with this graph is incompatible with the current robot. A common example
would be trying to upload a map recorded on a robot that had LIDAR to a robot that did not, or vice
versa.
STATUS_AREA_CALLBACK_ERROR 6 There is an error associated with one of the area callbacks in this graph.

UploadWaypointSnapshotResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Unset.
STATUS_OK 1 Success.
STATUS_INCOMPATIBLE_SENSORS 2 The data in this waypoint snapshot is not compatible with the
current configuration of the robot. Check sensor_status for
more details.

ValidateGraphResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_INCOMPATIBLE_SENSORS 5
STATUS_AREA_CALLBACK_ERROR 6

Top

bosdyn/api/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.
NavigateToAnchor NavigateToAnchorRequest NavigateToAnchorResponse Tell GraphNav to navigate to a goal with respect to the current anchoring.
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.
ValidateGraph ValidateGraphRequest ValidateGraphResponse Verify that the graph is still valid and all required external services are still available.
A map that was valid at upload time may not still be valid if required services are no longer running.

Top

bosdyn/api/graph_nav/map.proto

Anchor

This associates a waypoint with a common reference frame, which is not necessarily metric.

Field Type Label Description
id string Identifier of the waypoint.
seed_tform_waypoint bosdyn.api.SE3Pose Pose of the waypoint in the seed frame.

AnchoredWorldObject

This associates a world object with a common reference frame, which is not necessarily metric.

Field Type Label Description
id string Identifier of the world object.
seed_tform_object bosdyn.api.SE3Pose Pose of the object in the seed frame.

Anchoring

Field Type Label Description
anchors Anchor repeated The waypoint ids for the graph, expressed in a common reference frame, which is not
necessarily metric. If there is no anchoring, this is empty.
objects AnchoredWorldObject repeated World objects, located in the common reference frame.

AreaCallbackRegion

Data for a AreaCallback in the annotation.

Field Type Label Description
service_name string This service must be used in a given region to safely traverse it.
description string Human-readable description of this region.
recorded_data AreaCallbackData Configuration data associated with this area callback.

ClientMetadata

Optional metadata to attach to waypoints that are being recorded.

Field Type Label Description
session_name string User-provided name for this recording "session". For example, the user
may start and stop recording at various times and assign a name to a region
that is being recorded. Usually, this will just be the map name.
client_username string If the application recording the map has a special user name,
this is the name of that user.
client_software_version string Version string of any client software that generated this object.
client_id string Identifier of any client software that generated this object.
client_type string Special tag for the client software which created this object.
For example, "Tablet", "Scout", "Python SDK", etc.

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 Label 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 Label Description
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 Deprecated. If true, the edge crosses flat ground and the robot shouldn't try to climb over
obstacles.
DEPRECATED as of 3.3. Replaced by ground_clutter_mode.
override_mobility_params google.protobuf.FieldMask Overrides the following fields of the mobility parameters to whatever is
stored in the map. For example, if this FieldMask contains "stairs_mode" and
"terrain_params.enable_grated_floor", then the map will be
annotated with "stairs_mode" and "enable_grated_floor" settings. An empty FieldMask means
all fields are active annotations. Note that the more conservative of the velocity limit
stored in the mobility parameters and the TravelParams of the entire route will be used
for this edge (regardless of what override_mobility_params says).
mobility_params bosdyn.api.spot.MobilityParams Contains terrain parameters, swing height, obstacle avoidance parameters, etc.
When the robot crosses this edge, it will use the mobility parameters here.
cost google.protobuf.DoubleValue Assign edges a cost; used when finding the "shortest" (lowest cost) path.
edge_source Edge.EdgeSource How this edge was made.
disable_alternate_route_finding bool If true, disables alternate-route-finding for this edge.
path_following_mode Edge.Annotations.PathFollowingMode Path following mode for this edge.
disable_directed_exploration bool Disable directed exploration for this edge.
area_callbacks Edge.Annotations.AreaCallbacksEntry repeated Reference to area callback regions needed to cross this edge.
The string is a unique id for this region, which may be shared
across multiple edges.
ground_clutter_mode Edge.Annotations.GroundClutterAvoidanceMode

Edge.Annotations.AreaCallbacksEntry

Field Type Label Description
key string
value AreaCallbackRegion

Edge.Annotations.StairData

Defines any parameters of the stairs

Field Type Label Description
state AnnotationState Check this before reading other fields.
straight_staircase bosdyn.api.StraightStaircase Deprecated. Parameters describing a straight staircase.
DEPRECATED as of 3.3. Please use staircase_with_landings.
staircase_with_landings bosdyn.api.StaircaseWithLandings Parameters describing an arbitrary staircase.
descent_preference Edge.Annotations.StairData.DescentPreference
traversal_y_offset google.protobuf.DoubleValue The Y position with respect to the staircase frame to align to when traversing this
staircase. Regardless of how the recorded waypoints are distributed on the staircase,
when traversing the staircase all navigation goals will have this Y position with
respect to the staircase in order to guide the robot over the stairs in a straight
line.

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 Label 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 Label 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 repeated Sampling of stances as robot traversed this edge.
area_callbacks EdgeSnapshot.AreaCallbacksEntry repeated Data used by area callback services to perform their action.

EdgeSnapshot.AreaCallbacksEntry

Field Type Label Description
key string
value AreaCallbackData

EdgeSnapshot.Stance

Field Type Label Description
timestamp google.protobuf.Timestamp Timestamp of the stance.
foot_states bosdyn.api.FootState repeated List of all the foot positions for a single stance.
ko_tform_body bosdyn.api.SE3Pose KO Body position corresponding to this stance.
vision_tform_body bosdyn.api.SE3Pose Vision Body position corresponding to this stance.
planar_ground google.protobuf.BoolValue Does this stance correspond to a planar ground region.

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 Label Description
waypoints Waypoint repeated The waypoints for the graph (containing frames, annotations, and sensor data).
edges Edge repeated The edges connecting the graph's waypoints.
anchoring Anchoring The anchoring (mapping from waypoints to their pose in a shared reference frame).

MapStats

General statistics on the map that is loaded into GraphNav on the robot, including information on the graph topology and snapshot data.

Field Type Label Description
waypoints MapStats.Stat Waypoints (including alternate route finding waypoints).
waypoint_snapshots MapStats.Stat Waypoint snapshots.
alternate_waypoints MapStats.Stat The alternate route finding waypoints (used for alternate path planning).
edges MapStats.Stat Edges (including alternate route finding edges).
edge_snapshots MapStats.Stat Edge snapshots.
alternate_edges MapStats.Stat Alternate edges (used for alternate path planning).
waypoint_anchors MapStats.Stat Anchors for waypoints. (For computing anchorings to fixed reference frames).
object_anchors MapStats.Stat Anchors for world objects (fiducials).
total_path_length double The total distance travelled along recorded edges by the robot in the loaded
map.

MapStats.Stat

Statistics from a particular type of object stored in the GraphNav map.

Field Type Label Description
count int32 The number of elements.
num_bytes int64 Lower bound on the number of bytes allocated for these elements on RAM
inside the GraphNav server.

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 Label 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 Label Description
name string Human-friendly name of the waypoint. For example, "Kitchen Fridge"
creation_time google.protobuf.Timestamp The time that the waypoint was created while recording a map.
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_source Waypoint.WaypointSource How this waypoint was made.
client_metadata ClientMetadata Information about the state of the client when this waypoint was created.
loop_closure_settings Waypoint.Annotations.LoopClosureSettings This waypoint may have specific settings to help with loop closure. This
Is useful for example when trying to ensure that a loop closure occurs at
a particular intersection or near a dock.
gps_settings Waypoint.Annotations.GPSSettings Optional GPS navigation settings for this waypoint.

Waypoint.Annotations.GPSSettings

Waypoints can optionally define where they are in an Earth-Centered-Earth-Fixed (ECEF) frame, which can aid in localization.

Field Type Label Description
state AnnotationState If the annotation state is set, the GPS settings will be applied. Otherwise, they will be ignored.
If ignored, GPS will only be used at this waypoint if data from a GPS exists in the waypoint snapshot, and the
robot has a GPS payload installed and running. Set the annotation state to override this behavior.
ecef_tform_waypoint bosdyn.api.SE3Pose This defines the pose of the waypoint in the Earth-Centered-Earth-Fixed (ECEF) frame.
disable_gps_localization bool If true, GPS localization will be disabled at this waypoint. If false, the robot will use GPS when available
to localize to this waypoint.

Waypoint.Annotations.LocalizeRegion

Field Type Label 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 Label 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.

Waypoint.Annotations.LoopClosureSettings

Field Type Label Description
disable_loop_closure bool If true, loop closure will be fully disabled at this waypoint.
disable_collision_check bool If true, collision checking will be disabled for loop closures
from or to this waypoint.
max_edge_length double If nonzero, edges are allowed to be this long when making loop
closures to this waypoint. If zero, global/default settings will
be used.
max_odometry_path_length double If nonzero, loop closures to this waypoint may shortcut this amount
of path length. If zero, global/default settings will be used.

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 Label 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 repeated Any images captured at the waypoint.
point_cloud bosdyn.api.PointCloud Aggregated point cloud data.
objects bosdyn.api.WorldObject repeated Perception objects seen at snapshot time.
robot_state bosdyn.api.RobotState Full robot state during snapshot.
robot_local_grids bosdyn.api.LocalGrid repeated 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.
has_remote_point_cloud_sensor bool If true, the point cloud contains data from a remote point cloud service,
such as LIDAR.
body_tform_remote_point_cloud_sensor bosdyn.api.SE3Pose Transform from the robot body to the remote point cloud sensor's
reference frame.
payloads bosdyn.api.Payload repeated Defines the payloads attached to the robot at this waypoint.
robot_id bosdyn.api.RobotId Identifiers (software, nickname, etc.) of the robot that created this waypoint.
recording_started_on google.protobuf.Timestamp Information about when the recording session started in robot time basis.
This will be filled out by the recording service when StartRecording is called.

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.

Edge.Annotations.GroundClutterAvoidanceMode

Ground clutter avoidance mode. This enables detection and avoidance of low obstacles.

Name Number Description
GROUND_CLUTTER_UNKNOWN 0 The mode is unset.
GROUND_CLUTTER_OFF 1 The mode is explicitly off.
GROUND_CLUTTER_FROM_FOOTFALLS 2 Enable detection of ground clutter using recorded footfalls.
Objects that were not stepped on during map recording are obstacles.

Edge.Annotations.PathFollowingMode

Path following mode

Name Number Description
PATH_MODE_UNKNOWN 0 Unknown value
PATH_MODE_DEFAULT 1 Use default path following parameters
PATH_MODE_STRICT 2 Use strict path following parameters

Edge.Annotations.StairData.DescentPreference

Name Number Description
DESCENT_PREFERENCE_UNKNOWN 0 Unknown value, default to DESCENT_PREFERENCE_ALWAYS_REVERSE.
DESCENT_PREFERENCE_PREFER_REVERSE 1 Robot will prefer to descend in reverse, but may descend forwards if the route
could not otherwise be executed. This could be due to conflicting constraints
created by an annotation or by another staircase.
DESCENT_PREFERENCE_ALWAYS_REVERSE 2 Robot will always attempt to descend stairs in reverse, even if it causes
navigation to fail.
DESCENT_PREFERENCE_NONE 3 Robot may descend in any order. The exact order it chooses will be decided by
the lowest cost path found by the local trajectory optimizer and adjacent
constraints, if they exist.
NOTE: If a staircase which is difficult for the robot to descend in the forward
direction is marked with this option, it may cause the robot to fall.

Edge.EdgeSource

Name Number Description
EDGE_SOURCE_UNKNOWN 0
EDGE_SOURCE_ODOMETRY 1 Edges with transforms from odometry.
EDGE_SOURCE_SMALL_LOOP_CLOSURE 2 Edges with transforms from a short chain of other edges.
EDGE_SOURCE_FIDUCIAL_LOOP_CLOSURE 3 Edges with transforms from multiple fiducial observations.
EDGE_SOURCE_ALTERNATE_ROUTE_FINDING 4 Edges that may help find alternate routes.
EDGE_SOURCE_USER_REQUEST 5 Created via a CreateEdge RPC.
EDGE_SOURCE_LOCALIZATION 6 Created when we start recording after recording has been paused.
For example, an "extension" of a graph will start with an edge
of type EDGE_SOURCE_LOCALIZATION.

Waypoint.WaypointSource

Name Number Description
WAYPOINT_SOURCE_UNKNOWN 0
WAYPOINT_SOURCE_ROBOT_PATH 1 Waypoints from the robot's location during recording.
WAYPOINT_SOURCE_USER_REQUEST 2 Waypoints with user-requested placement.
WAYPOINT_SOURCE_ALTERNATE_ROUTE_FINDING 3 Waypoints that may help find alternate routes.

Top

bosdyn/api/graph_nav/map_processing.proto

AnchorHintUncertainty

Controls how certain the user is of an anchor’s pose. If left empty, a reasonable default will be chosen.

Field Type Label Description
se3_covariance bosdyn.api.SE3Covariance A full 6x6 Gaussian covariance matrix representing uncertainty of an anchoring.
confidence_bounds PoseBounds Represents the 95 percent confidence interval on individual axes. This
will be converted to a SE3Covariance internally by creating a diagonal
matrix whose elements are informed by the confidence bounds.

AnchoringHint

The user may assign a number of world objects and waypoints a guess at where they are in the seed frame. These hints will be respected by the ProcessAnchoringRequest.

Field Type Label Description
waypoint_anchors WaypointAnchorHint repeated List of waypoints and hints as to where they are in the seed frame.
world_objects WorldObjectAnchorHint repeated List of world objects and hints as to where they are in the seed frame.

PoseBounds

Represents an interval in x, y, z and yaw around some center. Some value x will be within the bounds if center - x_bounds <= x >= center + x_bounds. If the values are left at zero, the bounds are considered to be unconstrained. The center of the bounds is left implicit, and should be whatever this message is packaged with.

Field Type Label Description
x_bounds double Bounds on the x position in meters.
y_bounds double Bounds on the y position in meters.
z_bounds double Bounds on the z position in meters.
yaw_bounds double Bounds on the yaw (rotation around z axis) in radians.

ProcessAnchoringRequest

Causes the server to optimize an existing anchoring, or generate a new anchoring for the map using the given parameters. In general, if parameters are not provided, reasonable defaults will be used. The new anchoring will be streamed back to the client, or modified on the server if desired.

Field Type Label Description
header bosdyn.api.RequestHeader Standard request header.
params ProcessAnchoringRequest.Params
initial_hint AnchoringHint Initial guess at some number of waypoints and world objects and their anchorings.
modify_anchoring_on_server bool If true, the map currently uploaded to the server will have its anchoring modified.
Otherwise, the user is expected to re-upload the anchoring.
stream_intermediate_results bool If true, the anchoring will be streamed back to the user after every iteration.
This is useful for debug visualization.
apply_gps_result_to_waypoints_on_server bool If true, the GPSSettings inside waypoint annotations will be modified based on the optimization.
Every waypoint will have waypoint.gps_settings set, with ecef_tform_waypoint applied form this
optimization. To get these results, call the DownloadGraph RPC. Alternatively, the ecef_tform_waypoint
can be found using: response.gps_result.ecef_tform_seed * seed_tform_waypoint[waypoint_id].
Note that after this operation completes successfully, all waypoints in the graph can be used to navigate
using GPS, even if they didn't have GPS data in their waypoint snapshots.

ProcessAnchoringRequest.Params

Parameters for procesing an anchoring.

Field Type Label Description
optimizer_params ProcessAnchoringRequest.Params.OptimizerParams
measurement_params ProcessAnchoringRequest.Params.MeasurementParams
weights ProcessAnchoringRequest.Params.Weights
optimize_existing_anchoring google.protobuf.BoolValue If true, the anchoring which already exists on the server will be used as the initial
guess for the optimizer. Otherwise, a new anchoring will be generated for every waypoint
which doesn't have a value passed in through initial_hint. If no hint is provided,
and this value is false, every waypoint will be given a starting anchoring based on
the oldest waypoint in the map.
gravity_ewrt_seed bosdyn.api.Vec3 The optimizer will try to keep the orientation of waypoints consistent with gravity.
If provided, this is the gravity direction expressed with respect to the seed. This
will be interpreted as a unit vector. If not filled out, a default of (0, 0, -1) will be
used.

ProcessAnchoringRequest.Params.MeasurementParams

Parameters which affect the measurements the optimzier uses to process the anchoring.

Field Type Label Description
use_kinematic_odometry google.protobuf.BoolValue If true, waypoints which share the same kinematic odometry
frame will be constrained to one another using it.
use_visual_odometry google.protobuf.BoolValue If true, waypoints which share the same visual odometry frame
will be constrained to one another using it.
use_gyroscope_measurements google.protobuf.BoolValue If true, waypoints will be constrained so that the apparent pose of the
robot w.r.t the waypoint at the time of recording is consistent with gravity.
use_loop_closures google.protobuf.BoolValue If true, edges which were created by topology processing via loop closures will
be used as constraints.
use_world_objects google.protobuf.BoolValue If true, world object measurements will be used to constrain waypoints to one another
when those waypoints co-observe the same world object.
use_gps google.protobuf.BoolValue If true, GPS measurements stored in waypoint snapshots will be used to
help constrain the anchoring.

ProcessAnchoringRequest.Params.OptimizerParams

Parameters affecting the underlying optimizer.

Field Type Label Description
max_iters google.protobuf.Int32Value Maximum iterations of the optimizer to run.
max_time_seconds google.protobuf.DoubleValue Maximum time the optimizer is allowed to run before giving up.

ProcessAnchoringRequest.Params.Weights

Relative weights to use for each of the optimizer’s terms. These can be any positive value. If set to zero, a reasonable default will be used. In general, the higher the weight, the more the optimizer will care about that particular measurement.

Field Type Label Description
kinematic_odometry_weight double
visual_odometry_weight double
world_object_weight double
hint_weight double
gyroscope_weight double
loop_closure_weight double
gps_weight double

ProcessAnchoringResponse

Streamed response from the ProcessAnchoringRequest. These will be streamed until optimization is complete. New anchorings will be streamed as they become available.

Field Type Label Description
header bosdyn.api.ResponseHeader
status ProcessAnchoringResponse.Status
waypoint_results Anchor repeated Contains new anchorings for waypoint(s) processed by the server.
These will be streamed back to the user as they become available.
world_object_results AnchoredWorldObject repeated Contains new anchorings for object(s) (e.g april tags) processed by the server.
These will be streamed back to the user as they become available
anchoring_on_server_was_modified bool If modify_anchoring_on_server was set to true in the request, then the anchoring currently on the server
was modified using map processing. If this is set to false, then either an error occurred during
processing, or modify_anchoring_on_server was set to false in the request.
When anchoring_on_server_was_modified is set to false, the client is expected to upload the results
back to the server to commit the changes.
iteration int32 The current optimizer iteration that produced these data.
cost double The current nonlinear optimization cost.
final_iteration bool If true, this is the result of the final iteration of optimization.
This will always be true when stream_intermediate_results in the request is false.
violated_waypoint_constraints WaypointAnchorHint repeated On failure due to constraint violation, these hints were violated by the optimization.
Try increasing the pose bounds on the constraints of these hints.
violated_object_constraints WorldObjectAnchorHint repeated On failure due to constraint violation, these hints were violated by the optimization.
Try increasing the pose bounds on the constraints of these hints.
missing_snapshot_ids string repeated When there are missing waypoint snapshots, these are the IDs of the missing snapshots.
Upload them to continue.
missing_waypoint_ids string repeated When there are missing waypoints, these are the IDs of the missing waypoints. Upload them
to continue.
invalid_hints string repeated Unorganized list of waypoints and object IDs which were invalid (missing from the map).
inconsistent_edges Edge.Id repeated List of edges that are inconsistent with the optimized result. This can happen when incorrect
loop closures have been made before optimization, when inconsistent anchoring hints were passed in,
or because the optmizer ended up in a local minimum.
gps_result ProcessAnchoringResponse.GPSResult If GPS embedding optimzation was enabled, this is the result of that process.

ProcessAnchoringResponse.GPSResult

Field Type Label Description
status ProcessAnchoringResponse.GPSResult.GPSStatus Overall status of the GPS embedding optimization.
ecef_tform_seed bosdyn.api.SE3Pose Pose of the "seed" frame of this optimization in the Earth-Centered-Earth-Fixed (ECEF) frame.
This can be used to estimate the pose of every waypoint in the ECEF frame via:
ecef_tform_waypoint = ecef_tform_seed * anchoring.waypoints[waypoint_id].seed_tform_waypoint
num_measurements_used int32 This is the number of GPS measurements actually used to compute the GPS embedding.

ProcessTopologyRequest

Processes a GraphNav map by creating additional edges. After processing, a new subgraph is created containing additional edges to add to the map. Edges are created between waypoints that are near each other. These waypoint pairs are called “loop closures”, and are found by different means. In general, if parameters are not provided, reasonable defaults will be used. Note that this can be used to merge disconnected subgraphs from multiple recording sessions so long as they share fiducial observations.

Field Type Label Description
header bosdyn.api.RequestHeader Standard message header.
params ProcessTopologyRequest.Params Parameters. If not filled out, reasonable defaults will be used.
modify_map_on_server bool If true, any processing should directly modify the map on the server.
Otherwise, the client is expected to upload the processing results (newly created edges)
back to the server. The processing service shares memory with a map container service
(e.g the GraphNav service).

ProcessTopologyRequest.CollisionCheckingParams

Parameters for how to check for collisions when creating loop closures. The system will avoid creating edges in the map that the robot cannot actually traverse due to the presence of nearby obstacles.

Field Type Label Description
check_edges_for_collision google.protobuf.BoolValue By default, this is true.
collision_check_robot_radius google.protobuf.DoubleValue Assume that the robot is a sphere with this radius. Only accept a
loop closure if this spherical robot can travel in a straight line
from one waypoint to the other without hitting obstacles.
collision_check_height_variation google.protobuf.DoubleValue Consider significant height variations along the edge (like stairs or ramps)
to be obstacles. The edge will not be created if there is a height change along
it of more than this value according to the nearby sensor data.

ProcessTopologyRequest.FiducialLoopClosureParams

Parameters for how to close a loop using fiducials (AprilTags). This infers which waypoints should be connected to one another based on shared observations of AprilTags. Note that multiple disconnected subgraphs (for example from multiple recording sessions) can be merged this way.

Field Type Label Description
min_loop_closure_path_length google.protobuf.DoubleValue The minimum distance between waypoints found by walking a path from
one waypoint to the other using only the existing edges in the map.
Set this higher to avoid creating small shortcuts along the existing path.
Note that this is a 2d path length.
max_loop_closure_edge_length google.protobuf.DoubleValue Once a loop closure candidate is found, the system creates an edge between the
candidate waypoints. Only create the edge if it is shorter than this value.
Note that this is a 3d edge length.
max_fiducial_distance google.protobuf.DoubleValue Maximum distance to accept between a waypoint and a fiducial detection to
use that fiducial detection for generating loop closure candidates.
max_loop_closure_height_change google.protobuf.DoubleValue The maximum apparent height change of the created edge that we are
willing to accept between waypoints. This avoids closing loops up ramps,
stairs, etc. or closing loops where there is significant odometry drift.
prune_edges google.protobuf.BoolValue If true, redundant edges will be ignored, and only the "best" in a small area
will be selected (true by default).

ProcessTopologyRequest.ICPParams

Parameters for how to refine loop closure edges using iterative closest point matching.

Field Type Label Description
icp_iters google.protobuf.Int32Value The maximum number of iterations to run. Set to zero to skip ICP processing.
max_point_match_distance google.protobuf.DoubleValue The maximum distance between points in the point cloud we are willing to
accept for matches.

ProcessTopologyRequest.OdometryLoopClosureParams

Parameters for how to close loops using odometry. This infers which waypoints should be connected to one another based on the odometry measurements in the map.

Field Type Label Description
max_loop_closure_path_length google.protobuf.DoubleValue The maximum distance between waypoints found by walking a path from one
waypoint to the other using only the existing edges in the map. Beyond
this distance, we are unwilling to trust odometry.
min_loop_closure_path_length google.protobuf.DoubleValue The minimum distance between waypoints found by walking a path from
one waypoint to the other using only the existing edges in the map.
Set this higher to avoid creating small shortcuts along the existing path.
Note that this is a 2d path length.
max_loop_closure_height_change google.protobuf.DoubleValue The maximum apparent height change of the created edge that we are
willing to accept between waypoints. This avoids closing loops up ramps,
stairs, etc. or closing loops where there is significant odometry drift.
max_loop_closure_edge_length google.protobuf.DoubleValue Once a loop closure candidate is found, the system creates an edge between the
candidate waypoints. Only create the edge if it is shorter than this value.
Note that this is a 3d edge length.
num_extra_loop_closure_iterations google.protobuf.Int32Value Use prior loop closures to infer new odometry based loop closures. This is
useful when other sources of loop closures (like fiducials) are being used.
The existence of those loop closures allows the system to infer other nearby
loop closures using odometry. Alternatively, the user may call the ProcessTopology
RPC multiple times to achieve the same effect.
prune_edges google.protobuf.BoolValue If true, redundant edges will be ignored, and only the "best" in a small area
will be selected (true by default).

ProcessTopologyRequest.Params

Parameters which control topology processing. In general, anything which isn’t filled out will be replaced by reasonable defaults.

Field Type Label Description
do_odometry_loop_closure google.protobuf.BoolValue True by default -- generate loop closure candidates using odometry.
odometry_loop_closure_params ProcessTopologyRequest.OdometryLoopClosureParams Parameters for generating loop closure candidates using odometry.
icp_params ProcessTopologyRequest.ICPParams Parameters for refining loop closure candidates using iterative closest point
cloud matching.
do_fiducial_loop_closure google.protobuf.BoolValue True by default -- generate loop closure candidates using fiducials.
fiducial_loop_closure_params ProcessTopologyRequest.FiducialLoopClosureParams Parameters for generating loop closure candidates using fiducials.
collision_check_params ProcessTopologyRequest.CollisionCheckingParams Parameters which control rejecting loop closure candidates which
collide with obstacles.
timeout_seconds double Causes the processing to time out after this many seconds. If not set, a default of 45 seconds
will be used. If this timeout occurs before the overall RPC timeout, a partial result will be
returned with ProcessTopologyResponse.timed_out set to true. Processing can be continued by
calling ProcessTopology again.

ProcessTopologyResponse

Result of the topology processing RPC. If successful, contains a subgraph of new waypoints or edges created by this process.

Field Type Label Description
header bosdyn.api.ResponseHeader Standard message header.
status ProcessTopologyResponse.Status Result of the processing.
new_subgraph Graph This graph contains the new edge(s) created by map processing. Note that these edges will be
annotated with their creation method. Note that several subgraphs may be returned via
streaming as the map is processed.
map_on_server_was_modified bool If modify_map_on_server was set to true in the request, then the map currently on the server
was modified using map processing. If this is set to false, then either an error occurred during
processing, or modify_map_on_server was set to false in the request.
When map_on_server_was_modified is set to false, the client is expected to upload the results
back to the server to commit the changes.
missing_snapshot_ids string repeated When there are missing waypoint snapshots, these are the IDs of the missing snapshots.
Upload them to continue.
missing_waypoint_ids string repeated When there are missing waypoints, these are the IDs of the missing waypoints. Upload them
to continue.
timed_out bool If true, the processing timed out. Note that this is not considered an error. Run topology processing again
to continue adding edges.

WaypointAnchorHint

Waypoints may be anchored to a particular seed frame. The user may request that a waypoint be anchored in a particular place with some Gaussian uncertainty. Note on gravity alignment: optimization is sensitive to bad alignment with respect to gravity. By default, the orientation of the seed frame assumes gravity is pointing in the negative z direction. Take care to ensure that the orientation of the waypoint is correct with respect to gravity. By convention, waypoints’ orientation is defined as: Z up, X forward, Y left. So, if the robot is flat on the ground, the waypoint’s z axis should align with the seed frame’s z axis. z z ^ ^ | | | | | | +——>x | Waypoint Seed

Field Type Label Description
waypoint_anchor Anchor This is to be interpreted as the mean of a Gaussian distribution, representing
the pose of the waypoint in the seed frame.
seed_tform_waypoint_uncertainty AnchorHintUncertainty This is the uncertainty of the anchor's pose in the seed frame.
If left empty, a reasonable default uncertainty will be generated.
seed_tform_waypoint_constraint PoseBounds Normally, the optimizer will move the anchorings of waypoints based on context, to minimize the
overall cost of the optimization problem. By providing a constraint on pose, the user can ensure
that the anchors stay within a certain region in the seed frame.
Leaving this empty will allow the optimizer to move the anchoring from the hint as far as it likes.

WorldObjectAnchorHint

World objects (such as fiducials) may be anchored to a particular seed frame. The user may request that an object be anchored in a particular place with some Gaussian uncertainty. Note on gravity alignment: optimization is sensitive to bad alignment with respect to gravity. By default, the orientation of the seed frame assumes gravity is pointing in the negative z direction. Take care to ensure that the orientation of the world object is correct with respect to gravity. By convention, fiducials’ orientation is defined as: Z out of the page, X up and Y left (when looking at the fiducial). So, if a fiducial is mounted perfectly flat against a wall, its orientation w.r.t the seed frame would have the top of the fiducial facing positive Z. +———–+ z | ^x | ^ | | | | | | | | | <—-+ | | | y | Seed | | +———–+ Fiducial (on wall)

Field Type Label Description
object_anchor AnchoredWorldObject This is to be interpreted as the mean of a Gaussian distribution, representing
the pose of the object in the seed frame.
seed_tform_object_uncertainty AnchorHintUncertainty This is the uncertainty of the anchor's pose in the seed frame.
If left empty, a reasonable default uncertainty will be generated.
seed_tform_object_constraint PoseBounds Normally, the optimizer will move the anchorings of object based on context, to minimize the
overall cost of the optimization problem. By providing a constraint on pose, the user can ensure
that the anchors stay within a certain region in the seed frame.
Leaving this empty will allow the optimizer to move the anchoring from the hint as far as it likes.

ProcessAnchoringResponse.GPSResult.GPSStatus

Status of the GPS embedding optimization.

Name Number Description
GPS_STATUS_UNKNOWN 0
GPS_STATUS_OK 1 Managed to find an ECEF transform.
GPS_STATUS_NOT_ENOUGH_MEASUREMENTS 2 Not enough high quality GPS measurements in the map.

ProcessAnchoringResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Programming error.
STATUS_OK 1 Success.
STATUS_MISSING_WAYPOINT_SNAPSHOTS 2 Not all of the waypoint snapshots exist on the server. Upload them to continue.
STATUS_INVALID_GRAPH 3 The graph is invalid topologically, for example containing missing waypoints referenced by edges.
STATUS_OPTIMIZATION_FAILURE 4 The optimization failed due to local minima or an ill-conditioned problem definition.
STATUS_INVALID_PARAMS 5 The parameters passed to the optimizer do not make sense (e.g negative weights).
STATUS_CONSTRAINT_VIOLATION 6 One or more anchors were moved outside of the desired constraints.
STATUS_MAX_ITERATIONS 7 The optimizer reached the maximum number of iterations before converging.
STATUS_MAX_TIME 8 The optimizer timed out before converging.
STATUS_INVALID_HINTS 9 One or more of the hints passed in to the optimizer are invalid (do not correspond to real waypoints or objects).
STATUS_MAP_MODIFIED_DURING_PROCESSING 10 Tried to write the anchoring after processing, but another client may have modified the map. Try again.
STATUS_INVALID_GRAVITY_ALIGNMENT 11 An anchor hint (waypoint or fiducial) had an invalid orientation with respect to gravity.

ProcessTopologyResponse.Status

Name Number Description
STATUS_UNKNOWN 0 Programming error.
STATUS_OK 1 Success.
STATUS_MISSING_WAYPOINT_SNAPSHOTS 2 Not all of the waypoint snapshots exist on the server. Upload them to continue.
STATUS_INVALID_GRAPH 3 The graph is invalid topologically, for example containing missing waypoints referenced by edges.
STATUS_MAP_MODIFIED_DURING_PROCESSING 4 Tried to write the anchoring after processing, but another client may have modified the map. Try again

Top

bosdyn/api/graph_nav/map_processing_service.proto

MapProcessingService

Defines services for processing an existing GraphNav map.

Method Name Request Type Response Type Description
ProcessTopology ProcessTopologyRequest ProcessTopologyResponse stream Processes a GraphNav map by creating additional edges or waypoints. After processing,
a new subgraph is created containing additional waypoints or edges to add to the map.
ProcessAnchoring ProcessAnchoringRequest ProcessAnchoringResponse stream Processes a GraphNav map by modifying the anchoring of waypoints and world objects in the map
with respect to a seed frame. After processing, a new anchoring is streamed back.

Top

bosdyn/api/graph_nav/nav.proto

CompletedRoute

Information about the route that a robot has followed during a command.

Field Type Label Description
waypoint_ids string repeated List of waypoints reached in the order they were reached.
edges CompletedRoute.CompletedEdge repeated Information about the completed edges, in the order they were completed.

CompletedRoute.CompletedEdge

Field Type Label Description
edge_id Edge.Id
not_in_map bool If true, this edge was specially constructed to bypass a blockage, and does not exist
in the map.

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 Label Description
waypoint_id string Waypoint this localization is relative to.
waypoint_tform_body bosdyn.api.SE3Pose Pose of body in waypoint frame.
seed_tform_body bosdyn.api.SE3Pose Pose of body in a common reference frame. The common reference frame defaults to the starting
fiducial frame, but can be changed. See Anchoring for more info.
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 Label Description
waypoint_id string repeated Ordered list of waypoints to traverse, starting from index 0.
edge_id Edge.Id repeated Ordered list of edges to traverse between those waypoints.

Top

bosdyn/api/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 Label 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 Label 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.
map_stats MapStats General statistics of the map loaded in GraphNav.

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 Label 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 repeated 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.
world_objects bosdyn.api.WorldObject repeated Additional world objects to insert into this waypoint.

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 Label 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 repeated If the status is STATUS_MISSING_FIDUCIALS, the following fiducials
were not visible to the robot when trying to create the waypoint.
bad_pose_fiducials int32 repeated If the status is STATUS_FIDUCIAL_POSE_NOT_OK, these are the fiducials that could not be
localized confidently.
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.
map_stats MapStats General statistics of the map loaded in GraphNav.

GetRecordStatusRequest

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

Field Type Label 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 Label 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
status GetRecordStatusResponse.Status
impaired_state bosdyn.api.RobotImpairedState If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
session_start_time google.protobuf.Timestamp This is the robot local timestamp that graph_nav began recording on.
If the Start Recording Request's session start time is provided, this should
be the same as the request's session start time.
map_stats MapStats General statistics of the map loaded in GraphNav.

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 Label 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
edges in this recording.

SetRecordingEnvironmentRequest

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

Field Type Label 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 Label 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 Label 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 repeated 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.
session_start_time google.protobuf.Timestamp If provided, this timestamp will be used in every waypoint snapshot as the
"started_recording_on" timestamp. Otherwise, a new timestmap will be generated
after "StartRecording" is called. This is to allow association between waypoint
snapshots based on recording session time.

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 Label 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 repeated If the status is STATUS_MISSING_FIDUCIALS, these are the fiducials that are not currently
visible.
bad_pose_fiducials int32 repeated If the status is STATUS_FIDUCIAL_POSE_NOT_OK, these are the fiducials that could not be
localized confidently.
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.
impaired_state bosdyn.api.RobotImpairedState If the status is ROBOT_IMPAIRED, this is why the robot is impaired.
session_start_time google.protobuf.Timestamp This is the robot local timestamp that graph_nav began recording on. If the Start Recording
Request's session start time is provided, this should be the same as the request's session
start time.
map_stats MapStats General statistics of the map loaded in GraphNav.

StopRecordingRequest

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

Field Type Label 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 Label 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.
session_start_time google.protobuf.Timestamp This is the robot local timestamp that graph_nav began recording on. If the
StartRecordingRequest's session start time is provided, this should be the same as the
request's session start time.
map_stats MapStats General statistics of the map loaded in GraphNav.

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.
STATUS_REMOTE_CLOUD_FAILURE_NOT_IN_DIRECTORY 6 A required remote cloud did not exist in the service directory.
STATUS_REMOTE_CLOUD_FAILURE_NO_DATA 7 A required remote cloud did not have data.
STATUS_FIDUCIAL_POSE_NOT_OK 8 All fiducials are visible but their pose could not be determined accurately.

GetRecordStatusResponse.MapState

Name Number Description
MAP_STATE_UNKNOWN 0
MAP_STATE_OK 1 Successfully started recording.
MAP_STATE_TOO_LARGE_FOR_LICENSE 2 Unable to continue recording because a larger map requires an upgraded license.

GetRecordStatusResponse.Status

Name Number Description
STATUS_UNKNOWN 0
STATUS_OK 1
STATUS_ROBOT_IMPAIRED 2 Unable to record waypoints because the robot is impaired. When this happens,
the system will not create new waypoints until the robot is no longer impaired.
See impaired_state for more details.

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.
STATUS_REMOTE_CLOUD_FAILURE_NOT_IN_DIRECTORY 7 A required remote cloud did not exist in the service directory.
STATUS_REMOTE_CLOUD_FAILURE_NO_DATA 8 A required remote cloud did not have data.
STATUS_FIDUCIAL_POSE_NOT_OK 9 All fiducials are visible but at least one pose could not be determined accurately.
STATUS_TOO_FAR_FROM_EXISTING_MAP 10 When recording branches, the robot is too far from the existing map when starting
to record a new branch.
STATUS_ROBOT_IMPAIRED 11 Unable to start recording because the robot is impaired.
See impaired_state for more details.

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.

Top

bosdyn/api/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.

Top

bosdyn/api/gripper_camera_param.proto

GripperCameraGetParamRequest

The GripperCameraGetParam request message queries the robot for the current gripper sensor parameters.

Field Type Label Description
header RequestHeader Common request header.

GripperCameraGetParamResponse

The GripperCameraGetParam response message contains the current gripper sensor parameters. Gripper sensor parameters do not persist across reboots.

Field Type Label Description
header ResponseHeader Common request header.
params GripperCameraParams

GripperCameraParamRequest

The GripperCameraParam request message sets new gripper sensor parameters. Gripper sensor parameters do not persist across reboots.

Field Type Label Description
header RequestHeader Common request header.
params GripperCameraParams

GripperCameraParamResponse

Field Type Label Description
header ResponseHeader Common response header.

GripperCameraParams

Field Type Label Description
camera_mode GripperCameraParams.CameraMode CameraMode sets the resolution, frame rate and image format.
brightness google.protobuf.FloatValue Set the image brightness level.
Min 0, max 1
contrast google.protobuf.FloatValue Set the image contrast level.
Min 0, max 1
saturation google.protobuf.FloatValue Set the image saturation level.
Min 0, max 1
gain google.protobuf.FloatValue Set the image gain level.
This paramater is only effective when manual exposure is used.
Min 0, max 1
exposure_auto google.protobuf.BoolValue Whether the camera should use auto exposure.
Unset is equivalent to setting exposure_auto = true
exposure_absolute google.protobuf.FloatValue Manually set the image exposure level. This value is only used if exposure_auto is false.
Min 0, max 1
exposure_roi RoiParameters Region of interest for exposure. Specify a spot exposure on a
certain part of the image. Only used in auto-exposure mode.
focus_auto google.protobuf.BoolValue Whether the camera should automatically focus the image.
Unset is equivalent to setting focus_auto = true
focus_absolute google.protobuf.FloatValue Manually set the image focus. This value is only used if focus_auto is false.
If focus_auto is true, this value will be populated with the current focus value.
Min 0, max 1
0 corresponds to focus at infinity, 1 corresponds to a focal point close to the camera.
focus_roi RoiParameters Region of interest for focus. Only used when in auto-focus mode.
draw_focus_roi_rectangle google.protobuf.BoolValue Set to true to draw a rectangle in the image where the focus ROI is.
Unset is equivalent to setting draw_focus_roi_rectangle = false
hdr HdrParameters High dynamic range (HDR) mode sets the camera to take multiple frames to get exposure
in a large range. HDR will reduce framerate in high-framerate modes.
led_mode GripperCameraParams.LedMode Set the LED mode.
led_torch_brightness google.protobuf.FloatValue Brightness of the LED in torch mode. Min = 0, max = 1.
Note: A brightness value of 0 is not off, but is the minimum brightness.
To turn off the LED, set the led_mode to LED_MODE_OFF
white_balance_temperature_auto google.protobuf.BoolValue Whether the camera should use auto white balance
Unset is equivalent to setting white_balance_temperature_auto = true
gamma google.protobuf.FloatValue Set the image gamma level.
Min 0, max 1
white_balance_temperature google.protobuf.FloatValue Manually set the white balance focus. This value is only used if white_balance_temperature_auto is false.
Min 0, max 1
0 corresponds to focus at infinity, 1 corresponds to a focal point close to the camera.
sharpness google.protobuf.FloatValue Set the image sharpness level.
Min 0, max 1

RoiParameters

Region of interest (ROI) indicates the region within the image that should be used for determination of automatic focus or exposure.

Field Type Label Description
roi_percentage_in_image Vec2 Center point of the ROI in the image. The upper lefthand corner of the image is (0, 0) and
the lower righthand corner is (1, 1). The middle of the image is (0.5, 0.5).
window_size RoiParameters.RoiWindowSize Size of the region of interest.

GripperCameraParams.CameraMode

Name Number Description
MODE_UNKNOWN 0 MODE_UNKNOWN should not be used.
MODE_640_480 11 640x480 pixels.
MODE_640_480_120FPS_UYVY 11
MODE_1280_720 1 1280x720 pixels.
MODE_1280_720_60FPS_UYVY 1
MODE_1920_1080 14 1920x1080 pixels.
MODE_1920_1080_60FPS_MJPG 14
MODE_3840_2160 15 3840x2160 pixels.
MODE_3840_2160_30FPS_MJPG 15
MODE_4096_2160 17 4096x2160 pixels.
MODE_4096_2160_30FPS_MJPG 17
MODE_4208_3120 16 4208x3120 pixels.
MODE_4208_3120_20FPS_MJPG 16

GripperCameraParams.LedMode

Name Number Description
LED_MODE_UNKNOWN 0 LED_MODE_UNKNOWN should not be used.
LED_MODE_OFF 1 Off
LED_MODE_TORCH 2 Constantly on. Brightness level can be set in the led_torch_brightness field.

HdrParameters

High dynamic range (HDR) modes available. HDR sets the camera to take multiple frames to get exposure in a large range. HDR will reduce framerate in high-framerate modes.

Name Number Description
HDR_UNKNOWN 0 (or not set): will not change HDR settings.
HDR_OFF 1 HDR disabled
HDR_AUTO 2 Camera's on-board processor determines how much HDR is needed
HDR_MANUAL_1 3 Manual HDR enabled (minimum)
HDR_MANUAL_2 4
HDR_MANUAL_3 5
HDR_MANUAL_4 6 Manual HDR enabled (maximum)

RoiParameters.RoiWindowSize

Name Number Description
ROI_WINDOW_SIZE_UNKNOWN 0 ROI window size, 1 is the smallest, 8 is the largest.
ROI_WINDOW_SIZE_1 1
ROI_WINDOW_SIZE_2 2
ROI_WINDOW_SIZE_3 3
ROI_WINDOW_SIZE_4 4
ROI_WINDOW_SIZE_5 5
ROI_WINDOW_SIZE_6 6
ROI_WINDOW_SIZE_7 7
ROI_WINDOW_SIZE_8 8

Top

bosdyn/api/gripper_camera_param_service.proto

GripperCameraParamService

Method Name Request Type Response Type Description
SetParams GripperCameraParamRequest GripperCameraParamResponse
GetParams GripperCameraGetParamRequest GripperCameraGetParamResponse

Top

bosdyn/api/gripper_command.proto

ClawGripperCommand

Command to open and close the gripper.

ClawGripperCommand.Feedback

Field Type Label Description
status ClawGripperCommand.Feedback.Status Current status of the command.

ClawGripperCommand.Request

Field Type Label Description
trajectory ScalarTrajectory Scalar trajectory for opening/closing the gripper. If 1 point is specified
with no end time, we will execute a minimum time trajectory that observes
velocity and acceleration constraints. Otherwise, we will use piecewise
cubic interpolation, meaning there will be a cubic polynomial between each
trajectory point, with continuous position and velocity at each trajectory
point. If the requested trajectory violates the velocity or acceleration
constraints below, a trajectory that is as close as possible but still
obeys the constraints will be executed instead.
position is radians: 0 is fully closed -1.5708 (-90 degrees) is fully open
velocity is radians / sec.
maximum_open_close_velocity google.protobuf.DoubleValue If unspecified, a default value of 10 (rad/s) will be used.
maximum_open_close_acceleration google.protobuf.DoubleValue If unspecified, a default value of 40 (rad/s/s) will be used.
maximum_torque google.protobuf.DoubleValue Maximum torque applied. If unspecified, a default value of 5.5 (Nm) will be used.
disable_force_on_contact bool By default the gripper transitions to force control when it detects an object closing.
Setting this field to true disables the transition to force control on contact detection
and always keeps the gripper in position control.

GripperCommand

The synchronized command message for commanding the gripper to move. A synchronized commands is one of the possible robot command messages for controlling the robot.

GripperCommand.Feedback

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

Field Type Label Description
claw_gripper_feedback ClawGripperCommand.Feedback Feedback for the claw gripper command.
status RobotCommandFeedbackStatus.Status

GripperCommand.Request

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

Field Type Label Description
claw_gripper_command ClawGripperCommand.Request Control opening and closing the gripper.

ClawGripperCommand.Feedback.Status

Name Number Description
STATUS_UNKNOWN 0 STATUS_UNKNOWN should never be used. If used, an internal error has happened.
STATUS_IN_PROGRESS 1 The gripper is opening or closing.
STATUS_AT_GOAL 2 The gripper is at the final point of the trajectory.
STATUS_APPLYING_FORCE 3 During a close, detected contact and transitioned to force control.

Top

bosdyn/api/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 Label 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 Label 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.
disable_rpc_logging bool If Set to true, request that request and response messages for this call are not recorded
in the GRPC log.

ResponseHeader

Standard header attached to all GRPC responses from services.

Field Type Label 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.

Top

bosdyn/api/image.proto

CaptureParameters

Sensor parameters associated with an image capture.

Field Type Label Description
exposure_duration google.protobuf.Duration The duration of exposure in microseconds.
gain double Sensor gain in dB.
custom_params DictParam Any other custom parameters used in the image capture.

GetImageRequest

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

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

GetImageResponse

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

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

Image

Rectangular color/greyscale/depth images.

Field Type Label 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 Pixel format of the image; this will be set even when the Format implies
the pixel format.

ImageCapture

Rectangular color/greyscale images.

Field Type Label 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.
capture_params CaptureParameters Sensor parameters associated with this image capture.

ImageCaptureAndSource

This message is a subset of the ImageResponse message with only the information needed to pass captured images to other services.

Field Type Label 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.
image_service string Image service. If blank, it is assumed to be the robot's default image service.

ImageRequest

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

Field Type Label 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). If no format is specified (e.g. FORMAT_UNKNOWN), the image
service will choose the best format for the data.
resize_ratio double Optional specification of the desired image dimensions.
If the original image is 1920x1080, a resize_ratio of (2/3) will return an image with size 1280x720
The range is clipped to [0.01, 1] while maintaining the original aspect ratio.
For backwards compatibliity, a value of 0 means no resizing.
Note: this field is not supported by the robot body cameras image service (image).
pixel_format Image.PixelFormat Specify the desired pixel format (e.g. GREYSCALE_U8, RGB_U8). If no format is specified
(e.g. PIXEL_FORMAT_UNKNOWN), the image service will choose the best format for the data.
custom_params DictParam Parameters unique to the servicer that do not match any of the above fields.
Whether or not these are valid may depend on the values of the above fields.

ImageResponse

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

Field Type Label 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.
custom_param_error CustomParamError Filled out if status is STATUS_CUSTOM_PARAMS_ERROR.

ImageSource

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

Field Type Label 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 For depth images, the pixel value that represents a depth of one meter.
Depth in meters can be computed by dividing the raw pixel value by this scale factor.
pinhole ImageSource.PinholeModel Rectilinear camera model.
image_type ImageSource.ImageType The kind of images returned by this image source.
pixel_formats Image.PixelFormat repeated The pixel formats a specific image source supports.
image_formats Image.Format repeated The image formats a specific image source supports.
custom_params DictParam.Spec ImageRequest parameters unique to this source that do not match any of the above fields.

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 Label 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 Label 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 Label Description
header RequestHeader Common request header.

ListImageSourcesResponse

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

Field Type Label Description
header ResponseHeader Common response Header.
image_sources ImageSource repeated 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).
PIXEL_FORMAT_GREYSCALE_U16 6 Big-endian uint16

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.
STATUS_UNSUPPORTED_IMAGE_FORMAT_REQUESTED 5 The requested image format is unsupported for the image-source named. The image data will
not be filled out. Note, if an image request has "FORMAT_UNKNOWN", the service should choose the
best format to provide the data in.
STATUS_UNSUPPORTED_PIXEL_FORMAT_REQUESTED 6 The requested pixel format is unsupported for the image-source named. The image data will
not be filled out. Note, if an image request has "PIXEL_FORMAT_UNKNOWN", the service
should choose the best format to provide the data in.
STATUS_UNSUPPORTED_RESIZE_RATIO_REQUESTED 7 The requested ratio is out of bounds [0,1] or unsupported by the image service
STATUS_CUSTOM_PARAMS_ERROR 8 One or more keys or values in custom_params are unsupported by the image service.
See the custom_param_error for details.

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.

Top

bosdyn/api/image_geometry.proto

AreaI

Represents an area in the XY plane, with integer indices

Field Type Label Description
rectangle RectangleI

RectangleI

Represents a rectangle, with integer indices.

Field Type Label Description
x int32 Distance from the left
y int32 Distance from the top
cols int32 Width of the rectangle in pixels
rows int32 Height of the rectangle in pixels

Top

bosdyn/api/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 for this given service.
Note that there may be multiple ImageServices running, each with their own set of sources
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.

Top

bosdyn/api/ir_enable_disable.proto

IREnableDisableRequest

Field Type Label Description
header RequestHeader < Common request header.
request IREnableDisableRequest.Request

IREnableDisableResponse

Field Type Label Description
header ResponseHeader < Common response header.

IREnableDisableRequest.Request

Name Number Description
REQUEST_UNKNOWN 0 Unspecified value -- should not be used.
REQUEST_OFF 1 Disable emissions.
REQUEST_ON 2 Enable emissions.

Top

bosdyn/api/ir_enable_disable_service.proto

IREnableDisableService

Method Name Request Type Response Type Description
IREnableDisable IREnableDisableRequest IREnableDisableResponse

Top

bosdyn/api/keepalive/keepalive.proto

ActionAfter

Field Type Label Description
record_event ActionAfter.RecordEvent
auto_return ActionAfter.AutoReturn
controlled_motors_off ActionAfter.ControlledMotorsOff
immediate_robot_off ActionAfter.ImmediateRobotOff
lease_stale ActionAfter.LeaseStale
after google.protobuf.Duration Take the specified action after not hearing from the associated policy_id in this long.

ActionAfter.AutoReturn

Robot triggers AutoReturn.

Field Type Label Description
leases bosdyn.api.Lease repeated Leases that AutoReturn may use to accomplish its goals when it triggers.
This field is required.
This should be a newer lease than the last one used to control the robot.
For example, if you have acquired lease [6] from the robot, you should begin controlling
the robot with [6, 0, 1] and pass [6, 1] here.
If you have added an associated lease, it should be the [6] lease.
params bosdyn.api.auto_return.Params Parameters to AutoReturn. See that message's documentation for details.

ActionAfter.ControlledMotorsOff

After coming to a halt, robot sits and powers off its motors. Takes priority over AutoReturn and HaltRobot actions.

ActionAfter.ImmediateRobotOff

Robot powers off its computer immediately. WARNING: This will cause loss of recent data, and may damage the robot or its payloads if done while the robot is not sitting.

ActionAfter.LeaseStale

The leases are marked as stale, making the resource available for other clients. See the LeaseResource message for details.

Field Type Label Description
leases bosdyn.api.Lease repeated

ActionAfter.RecordEvent

Record an event.

Field Type Label Description
events bosdyn.api.Event repeated The events to be logged.

CheckInRequest

Field Type Label Description
header bosdyn.api.RequestHeader
policy_id uint64 Specify the policy whose timer should be refreshed.

CheckInResponse

Field Type Label Description
header bosdyn.api.ResponseHeader
last_checkin google.protobuf.Timestamp Time the robot recorded the check in. Specified in robot's clock.
status CheckInResponse.Status