Skip to main content

control_service

service Control​

Used for low-level control of a vehicle.

This service is hosted by the driver module and represents the global control interface for the vehicle. Most methods called here will result in actuation of the vehicle if it is armed (be careful!). Some methods, like TakeOff, may take some time to complete. For this reason, it is not advisable to set a timeout/deadline on the RPC call. However, to ensure that the service is progressing, a client can either check telemetry or listen for IN_PROGRESS response heartbeats which are streamed back from the RPC while executing an operation.

rpc Connect​

Connect to the vehicle.

Connects to the underlying vehicle hardware. Generally, this method is called by the law authority on startup and is not called by user code.

Accepts​

ConnectRequest

Returns​

Response

rpc Disconnect​

Disconnect from the vehicle.

Disconnects from the underlying vehicle hardware. Generally, this method is called by the law authority when it attempts a driver restart and is not called by user code.

Accepts​

DisconnectRequest

Returns​

Response

rpc Arm​

Order the vehicle to arm.

Arms the vehicle. This is required before any other commands are run, otherwise the methods will return FAILED_PRECONDITION. Once the vehicle is armed, all subsequent actuation methods will move the vehicle. Make sure to go over the manufacturer recommended vehicle-specific pre-operation checklist before arming.

Accepts​

ArmRequest

Returns​

Response

rpc Disarm​

Order the vehicle to disarm.

Disarms the vehicle. Prevents any further actuation methods from executing, unless the vehicle is re-armed.

Accepts​

DisarmRequest

Returns​

Response

rpc Joystick​

Send a joystick command to the vehicle.

Causes the vehicle to accelerate towards a provided velocity setpoint over a provided duration. This is useful for fine-grained control based on streamed datasink results or for tele-operating the vehicle from a remote commander.

Accepts​

JoystickRequest

Returns​

Response

rpc TakeOff​

Order the vehicle to take off.

Causes the vehicle to take off to a specified take off altitude. If the vehicle is not a UAV, this method will be unimplemented.

Accepts​

TakeOffRequest

Returns​

Response

rpc Land​

Order the vehicle to land.

Causes the vehicle to land at its current location. If the vehicle is not a UAV, this method will be unimplemented.

Accepts​

LandRequest

Returns​

Response

rpc Hold​

Order the vehicle to hold/loiter.

Causes the vehicle to hold at its current location and to cancel any ongoing movement commands (ReturnToHome e.g.).

Accepts​

HoldRequest

Returns​

Response

rpc Kill​

Orders an emergency shutdown of the vehicle motors.

Causes the vehicle to immediately turn off its motors. If the vehicle is a UAV, this will result in a freefall. Use this method only in emergency situations.

Accepts​

KillRequest

Returns​

Response

rpc SetHome​

Set the home location of the vehicle.

Changes the home location of the vehicle. Future ReturnToHome commands will move the vehicle to the provided location instead of its starting position.

Accepts​

SetHomeRequest

Returns​

Response

rpc ReturnToHome​

Order the vehicle to return to its home position.

Causes the vehicle to return to its home position. If the home position has not been explicitly set, this will be its start position (defined as its takeoff position for UAVs). If the home position has been explicitly set, by SetHome, the vehicle will return to that position instead.

Accepts​

ReturnToHomeRequest

Returns​

Response

rpc SetGlobalPosition​

Order the vehicle to move to a global position.

Causes the vehicle to transit to the provided global position. The vehicle will interpret the heading of travel according to heading_mode:

  • TO_TARGET -> turn to face the target position bearing
  • HEADING_START -> turn to face the provided heading in the global position object.

This will be the heading the vehicle maintains for the duration of transit. Generally only UAVs will support HEADING_START.

The vehicle will move towards the target at the specified maximum velocity until the vehicle has reached its destination. Error tolerance is determined by the driver. Maximum velocity is interpreted from max_velocity as follows:

  • x_vel -> maximum horizontal velocity
  • y_vel -> ignored
  • z_vel -> maximum vertical velocity (UAV only)

If no maximum velocity is provided, the driver will use a preset speed usually determined by the manufacturer or hardware settings.

(UAV only) During motion, the vehicle will also ascend or descend towards the target altitude, linearly interpolating this movement over the duration of travel. The vehicle will interpret altitude from altitude_mode as follows:

  • ABSOLUTE -> altitude is relative to MSL (Mean Sea Level)
  • RELATIVE -> altitude is relative to take off position

Accepts​

SetGlobalPositionRequest

Returns​

Response

rpc SetRelativePosition​

Order the vehicle to move to a relative position.

Causes the vehicle to transit to the provided relative position. The vehicle will interpret the input position according to frame as follows:

  • BODY -> (x, y, z) = (forward offset, right offset, up offset) from current position
  • NEU -> (x, y, z) = (north offset, east offset, up offset) from start position

The vehicle will move towards the target at the specified maximum velocity until the vehicle has reached its destination. Error tolerance is determined by the driver. Maximum velocity is interpreted from max_velocity as follows:

  • x_vel -> maximum horizontal velocity
  • y_vel -> ignored
  • z_vel -> maximum vertical velocity (UAV only)

If no maximum velocity is provided, the driver will use a preset speed usually determined by the manufacturer or hardware settings.

Accepts​

SetRelativePositionRequest

Returns​

Response

rpc SetVelocity​

Order the vehicle to accelerate to a velocity.

Causes the vehicle to accelerate until it reaches a provided velocity. Error tolerance is determined by the driver. The vehicle will interpret the input velocity according to frame as follows:

  • BODY -> (x_vel, y_vel, z_vel) = (forward velocity, right velocity, up velocity)
  • NEU -> (x_vel, y_vel, z_vel) = (north velocity, east velocity, up velocity)

Accepts​

SetVelocityRequest

Returns​

Response

rpc SetHeading​

Order the vehicle to set a new heading.

Causes the vehicle to turn to face the provided global position. The vehicle will interpret the final heading according to heading_mode:

  • TO_TARGET -> turn to face the target position bearing
  • HEADING_START -> turn to face the provided heading in the global position object.

Accepts​

SetHeadingRequest

Returns​

Response

rpc SetGimbalPose​

Order the vehicle to set the pose of a gimbal.

Causes the vehicle to actuate a gimbal to a new pose. The vehicle will interpret the new pose type from pose_mode as follows:

  • ABSOLUTE -> absolute angle
  • RELATIVE -> angle relative to current position
  • VELOCITY -> angular velocities

The vehicle will interpret the new pose angles according to frame as follows:

  • BODY -> (pitch, roll, yaw) = (body pitch, body roll, body yaw)
  • NEU -> (pitch, roll, yaw) = (body pitch, body roll, global yaw)

Accepts​

SetGimbalPoseRequest

Returns​

Response

rpc ConfigureImagingSensorStream​

Configure the vehicle imaging stream.

Sets which imaging sensors are streaming and sets their target frame rates.

Accepts​

ConfigureImagingSensorStreamRequest

Returns​

Response

rpc ConfigureTelemetryStream​

Configure the vehicle telemetry stream.

Sets the frequency of the telemetry stream.

Accepts​

ConfigureTelemetryStreamRequest

Returns​

Response

enum AltitudeMode​

Altitude mode switch.

Fields​

field  ABSOLUTE  (0) — meters above Mean Sea Level

field  RELATIVE  (1) — meters above takeoff position

enum HeadingMode​

Heading mode switch.

Fields​

field  TO_TARGET  (0) — orient towards the target location

field  HEADING_START  (1) — orient towards the given heading

enum ReferenceFrame​

Reference frame mode switch.

Fields​

field  BODY  (0) — vehicle reference frame

field  NEU  (1) — NEU (North, East, Up) reference frame

enum PoseMode​

Pose mode switch.

Fields​

field  ANGLE  (0) — absolute angle

field  OFFSET  (1) — request data // Offset from current

field  VELOCITY  (2) — rotational velocities

message ConnectRequest​

Fields​

field  request  (Request) — request data

message DisconnectRequest​

Fields​

field  request  (Request) — request data

message ArmRequest​

Fields​

field  request  (Request) — request data

message DisarmRequest​

Fields​

field  request  (Request) — request data

message JoystickRequest​

Fields​

field  request  (Request) — request data

field  velocity  (Velocity) — target velocity to move towards

field  duration  (/google/protobuf/Duration) — time of actuation after which the vehicle will Hold

message TakeOffRequest​

Fields​

field  request  (Request) — request data

field  take_off_altitude  (float) — take off height in relative altitude [meters]

message LandRequest​

Fields​

field  request  (Request) — request data

message HoldRequest​

Fields​

field  request  (Request) — request data

message KillRequest​

Fields​

field  request  (Request) — request data

message SetHomeRequest​

Fields​

field  request  (Request) — request data

field  location  (Location) — new home location

message ReturnToHomeRequest​

Fields​

field  request  (Request) — request data

message SetGlobalPositionRequest​

Fields​

field  request  (Request) — request data

field  location  (Location) — target global position

field  heading_mode  (HeadingMode) — determines how the vehicle will orient during transit (default: TO_TARGET)

field  altitude_mode  (AltitudeMode) — determines how the vehicle will interpret altitude (default: ABSOLUTE)

field  max_velocity  (Velocity) — maximum velocity during transit

message SetRelativePositionRequest​

Fields​

field  request  (Request) — request data

field  position  (Position) — target relative position

field  max_velocity  (Velocity) — maximum velocity during transit

field  frame  (ReferenceFrame) — frame of reference

message SetVelocityRequest​

Fields​

field  request  (Request) — request data

field  velocity  (Velocity) — target velocity

field  frame  (ReferenceFrame) — frame of reference

message SetHeadingRequest​

Fields​

field  request  (Request) — request data

field  location  (Location) — target heading or global location to look at

field  heading_mode  (HeadingMode) — determines how the drone will orient

message SetGimbalPoseRequest​

Fields​

field  request  (Request) — request data

field  gimbal_id  (uint32) — ID of the target gimbal

field  pose  (Pose) — target pose

field  pose_mode  (PoseMode) — specifies how to interpret the target pose

field  frame  (ReferenceFrame) — frame of reference

message ImagingSensorConfiguration​

Configuration for an imaging sensor.

Fields​

field  id  (uint32) — target imaging sensor ID

field  set_primary  (bool) — set this sensor as the primary stream

field  set_fps  (uint32) — target FPS for stream

message ConfigureImagingSensorStreamRequest​

Fields​

field  request  (Request) — request data

field  configurations  (ImagingSensorConfiguration) — list of configurations to be updated

message ConfigureTelemetryStreamRequest​

Fields​

field  request  (Request) — request data

field  frequency  (uint32) — target frequency of telemetry generation, in Hz