Copter Commands in Guided Mode

This article lists the MAVLink commands that Copter accepts. Normally these commands are sent by a ground station or Companion Computers often running DroneKit.

Note

The Copter code which processes these commands can be found here in GCS_Mavlink.cpp

Movement commands

These commands can be used to control the vehicle’s position, velocity or attitude while in Guided Mode

Movement Command Details

This section contains details of MAVLink commands to move the vehicle

SET_POSITION_TARGET_LOCAL_NED

Set the vehicle’s target position, velocity, heading or turn rate. The message definition can be found here

Command Field Description
time_boot_ms Sender's system time in milliseconds since boot
target_system System ID of vehicle
target_component Component ID of flight controller or just 0
coordinate_frame Valid options are listed below
type_mask

Bitmask to indicate which fields should be ignored by the vehicle (see POSITION_TARGET_TYPEMASK enum)

bit1:PosX, bit2:PosY, bit3:PosZ, bit4:VelX, bit5:VelY, bit6:VelZ, bit7:AccX, bit8:AccY, bit9:AccZ, bit11:yaw, bit12:yaw rate

When providing Pos or Vel all 3 axis must be provided

  • Use Position : 0b110111111000 / 0x0DF8 / 3576 (decimal)
  • Use Velocity : 0b110111000111 / 0x0DC7 / 3527 (decimal)
  • Use Pos+Vel : 0b110111000000 / 0x0DC0 / 3520 (decimal)

Acceleration not supported

x X Position in meters (positive is forward or North)
y Y Position in meters (positive is right or East)
z Z Position in meters (positive is down)
vx X velocity in m/s (positive is forward or North)
vy Y velocity in m/s (positive is right or East)
vz Z velocity in m/s (positive is down)
afx X acceleration not supported
afy Y acceleration not supported
afz Z acceleration not supported
yaw yaw or heading in radians (0 is forward or North)
yaw_rate yaw rate in rad/s

The co-ordinate frame field takes the following values:

Frame Description
MAV_FRAME_LOCAL_NED

Positions are relative to the vehicle’s EKF Origin in NED frame

I.e x=1,y=2,z=3 is 1m North, 2m East and 3m Down from the origin

The EKF origin is the vehicle’s location when it first achieved a good position estimate

Velocity are in NED frame

MAV_FRAME_LOCAL_OFFSET_NED

Positions are relative to the vehicle’s current position

I.e. x=1,y=2,z=3 is 1m North, 2m East and 3m below the current position.

Velocity are in NED frame.

MAV_FRAME_BODY_OFFSET_NED

Positions are relative to the vehicle’s current position and heading

I.e x=1,y=2,z=3 is 1m forward, 2m right and 3m Down from the current position

Velocities are relative to the current vehicle heading. Use this to specify the speed forward, right and down (or the opposite if you use negative values).

MAV_FRAME_BODY_NED

Positions are relative to the EKF Origin in NED frame

I.e x=1,y=2,z=3 is 1m North, 2m East and 3m Down from the origin

Velocities are relative to the current vehicle heading. Use this to specify the speed forward, right and down (or the opposite if you use negative values).

Tip

In frames, _OFFSET_ means “relative to vehicle position” while _LOCAL_ is “relative to home position” (these have no impact on velocity directions). _BODY_ means that velocity components are relative to the heading of the vehicle rather than the NED frame.

Note

If sending velocity commands, they should be resent every second (the vehicle will stop after 3 seconds if no command is received)

SET_POSITION_TARGET_GLOBAL_INT

Set the vehicle’s target position (in WGS84 coordinates), velocity, heading or turn rate. This is similar to the SET_POSITION_TARGET_LOCAL_NED message (see above) except positions are provided as latitude and longitude values and altitudes can be above sea-level, relative to home or relative to terrain.

The message definition can be found here

Command parameters

Command Field Description
time_boot_ms Sender's system time in milliseconds since boot
target_system System ID of vehicle
target_component Component ID of flight controller or just 0
coordinate_frame

Valid options are:

  • MAV_FRAME_GLOBAL_INT : alt is meters above sea level
  • MAV_FRAME_GLOBAL_RELATIVE_ALT: alt is meters above home
  • MAV_FRAME_GLOBAL_RELATIVE_ALT_INT: alt is meters above home
  • MAV_FRAME_GLOBAL_RELATIVE_TERRAIN_ALT: alt is meters above terrain
  • MAV_FRAME_GLOBAL_RELATIVE_TERRAIN_ALT_INT: alt is meters above terrain
type_mask

Bitmask to indicate which fields should be ignored by the vehicle (see POSITION_TARGET_TYPEMASK enum)

bit1:PosX, bit2:PosY, bit3:PosZ, bit4:VelX, bit5:VelY, bit6:VelZ, bit7:AccX, bit8:AccY, bit9:AccZ, bit11:yaw, bit12:yaw rate

When providing Pos or Vel all 3 axis must be provided

  • Use Position : 0b110111111000 / 0x0DF8 / 3576 (decimal)
  • Use Velocity : 0b110111000111 / 0x0DC7 / 3527 (decimal)
  • Use Pos+Vel : 0b110111000000 / 0x0DC0 / 3520 (decimal)

Acceleration not supported

lat_int Latitude * 1e7
lon_int Longitude * 1e7
alt Alt in meters above sea level, home or terrain (see coordinate_frame field)
vx X velocity in m/s (positive is North)
vy Y velocity in m/s (positive is East)
vz Z velocity in m/s (positive is down)
afx X acceleration not supported
afy Y acceleration not supported
afz Z acceleration not supported
yaw yaw or heading in radians (0 is forward or North)
yaw_rate yaw rate in rad/s

Note

Velocity commands should be resent every second (the vehicle will stop after 3 seconds if no command is received)

SET_ATTITUDE_TARGET

Set the vehicle’s target attitude and climb rate. This message is accepted in Guided or Guided_NoGPS (this is the only message accepted by Guided_NoGPS). The message definition can be found here

Command parameters

Command Field Type Description
time_boot_ms uint32_t Sender's system time in milliseconds since boot
target_system uint8_t System ID of vehicle
target_component int8_t Component ID of flight controller or just 0
type_mask int8_t

Bitmask to indicate which fields should be ignored by the vehicle

bit1:body roll rate, bit2:body pitch rate, bit3:body yaw rate, bit7:throttle, bit8:attitude

Should always be 0b00000111 / 0x07 / 7 (decimal)

q float[4] Attitude quaternion (w, x, y, z order, zero-rotation is {1, 0, 0, 0})
Note that zero-rotation causes vehicle to rotate towards North.
body_roll_rate float Body roll rate not supported
body_pitch_rate float Body pitch rate not supported
body_yaw_rate float Body yaw rate not supported
thrust float Climb rate where 0.5 = no climb, 0 = WPNAV_SPEED_DN, 1 = WPNAV_SPEED_UP

SET_HOME_POSITION

The position the system will return to and land on. The position is set automatically by the system during the takeoff if it has not been explicitly set by the operator before or after.

The message definition can be found here

Command parameters

Command Field Type Description
target_system uint8_t System ID
latitude int32_t Latitude * 1e7
longitude int32_t Longitude * 1e7
altitude int32_t Altitude above sea level in millimeters (i.e. meters * 1000)
x float Local X position of this position in the local coordinate frame.
y float Local Y position of this position in the local coordinate frame
z float Local Z position of this position in the local coordinate frame
q float[4] World to surface normal and heading transformation of the takeoff position. Used to indicate the heading and slope of the ground.
approach_x float Local X position of the end of the approach vector. Multicopters should set this position based on their takeoff path. Grass-landing fixed wing aircraft should set it the same way as multicopters. Runway-landing fixed wing aircraft should set it to the opposite direction of the takeoff, assuming the takeoff happened from the threshold / touchdown zone.
approach_y float Local Y position of the end of the approach vector. Multicopters should set this position based on their takeoff path. Grass-landing fixed wing aircraft should set it the same way as multicopters. Runway-landing fixed wing aircraft should set it to the opposite direction of the takeoff, assuming the takeoff happened from the threshold / touchdown zone.
approach_z float Local Z position of the end of the approach vector. Multicopters should set this position based on their takeoff path. Grass-landing fixed wing aircraft should set it the same way as multicopters. Runway-landing fixed wing aircraft should set it to the opposite direction of the takeoff, assuming the takeoff happened from the threshold / touchdown zone.