Skip to content

common-mavlink-mission-command-messages-mav_cmd.rst

Latest commit

 

History

History
4850 lines (4108 loc) · 125 KB

common-mavlink-mission-command-messages-mav_cmd.rst

File metadata and controls

4850 lines (4108 loc) · 125 KB
Raw

Mission Commands

This article describes the mission commands that are supported by Copter, Plane, Sub and Rover when switched into Auto mode.

Note

there are many other MAVLink commands that a GCS or other device can send to the autopilot. See the ArduPilot/navlink repository, or the documentation for your GCS.

[site wiki="copter"] A simpler list just for :ref:`Copter can be found here <copter:mission-command-list>` [/site]

Overview

The MAVLink protocol defines a large number of MAV_CMD waypoint command types (sent in a MAVLink_mission_item_message). ArduPilot implements handling for the subset of these commands and command parameters that are most relevant and meaningful for each of the vehicles. Unsupported commands that are sent to a particular autopilot will simply be dropped.

This article lists and describes the commands and command-parameters that are supported on each of the vehicle types. Any parameter that is "grey" is not supported by the autopilot and will be ignored. They are still documented to make it clear which properties are supported by the MAV_CMD protocol are not implemented by the vehicle.

Some commands and command parameters are not implemented because they are not relevant for particular vehicle types (for example "MAV_CMD_NAV_TAKEOFF" command makes sense for Plane and Copter but not Rover and the pitch parameter only makes sense for Plane). There are also some potentially useful command parameters that are not handled because there is a limit to the message size, and a decision has been made to prioritize some parameters over others.

Note

There is additional information about the supported commands on Copter (from a Mission Planner perspective) in the :ref:`Copter Mission Command List <copter:mission-command-list>`.

Types of commands

There are several different types of commands that can be used within missions:

  • Navigation commands are used to control the movement of the vehicle, including takeoff, moving to and around waypoints, changing altitude, and landing.
  • DO commands are for auxiliary functions and do not affect the vehicle’s position (for example, setting the camera trigger distance, or setting a servo value).
  • Condition commands are used to delay DO commands until some condition is met, for example, the UAV reaches a certain altitude or distance from the waypoint.

During a mission at most one “Navigation” command and one “Do” or "Condition" command can be running at one time. A typical mission might set a waypoint (NAV command), add a CONDITION command that doesn't complete until a certain distance from the destination (:ref:`MAV_CMD_CONDITION_DISTANCE <mav_cmd_condition_distance>`), and then add a number of DO commands that are executed sequentially (for example :ref:`MAV_CMD_DO_SET_CAM_TRIGG_DIST <mav_cmd_do_set_cam_trigg_dist>` to take pictures at regular intervals) when the condition completes.

Note

CONDITION and DO commands are associated with the preceding NAV command: if the UAV reaches the next waypoint before these commands are executed, the next NAV command is loaded and they will be skipped.

Frames of reference

Many of the commands (in particular the :ref:`NAV\_ commands <common-mavlink-mission-command-messages-mav_cmd_navigation_commands>`) include position/location information. The information is provided relative to a particular "frame of reference", which is specified in the message's :ref:`common-mavlink-mission-command-messages-mav_cmd_navigation_commands_frames` field. Copter and Rover Mission use :ref:`MAV_CMD_DO_SET_HOME <mav_cmd_do_set_home>` command to set the "home position" in the global coordinate frame (MAV_FRAME_GLOBAL), WGS84 coordinate system, where the altitude is relative to mean sea level. All other commands use the MAV_FRAME_GLOBAL_RELATIVE_ALT frame, which uses the same latitude and longitude, but sets altitude as relative to the home position (home altitude = 0).

Plane commands can additionally use MAV_FRAME_GLOBAL_TERRAIN_ALT frame of reference. This again has the same WGS84 frame of reference for latitude/longitude, but specifies altitude relative to ground height (as defined in a terrain database).

Note

The other frame types are defined in the MAVLink protocol (see MAV_FRAME) are not supported for mission commands.

How accurate is the information?

If a command or parameter is marked as supported then it is likely (but not guaranteed) that it will behave as indicated. If a command or parameter is not listed (or marked as not supported) then it is extremely likely that it is not supported on ArduPilot.

The reason for this is that the information was predominantly inferred by inspecting the command handlers for messages:

  • The switch statement in AP_Mission::mavlink_to_mission_cmd was inspected to determine which commands are handled by all vehicle platforms, and which parameters from the message are stored.
  • The command handler switch for each vehicle type (Plane, Copter, Rover) tells us which commands are likely to be supported in each vehicle and which parameters are passed to the handler.

The above checks give a very accurate picture of what commands and parameters are not supported. They give a fairly accurate picture of what commands/parameters are likely to be supported. However, this indication is not guaranteed to be accurate because a command handler could just throw away all the information (and we have not fully checked all of these).

In addition to the above checks, we have also merged information from the :ref:`Copter Mission Command List <copter:mission-command-list>`.

How to interpret the command parameters

The parameters for each command are listed in a table. The parameters that are "greyed out" are not supported. The command field column (param name) uses "bold" text to indicate those parameters that are defined in the protocol (normal text is used for "empty" parameters).

This allows users/developers to see both what is supported, and what protocol fields are not supported in ArduPilot.

Using this information with a GCS

Mission Planner (MP) exposes the full subset of commands and parameters supported by ArduPilot, filtered to display just those relevant to the currently connected vehicle. Mapping the MP commands to this documentation is easy, because it simply names commands using a cut-down version of the full command name (e.g. DO_SET_SERVO rather than the full command name: MAV_CMD_DO_SET_SERVO). In addition, this document conveniently lists the column label used by Mission Planner alongside each of the parameters.

Other GCSs (APM Planner 2, Tower etc.) may support some other subset of commands/parameters and use alternative names/labels for them. In most cases, the mapping should be obvious.

[site wiki="copter"] Commands supported by Copter ============================

This list of commands was inferred from the command handler in /ArduCopter/mode_auto.cpp.

[/site]

[site wiki="sub"] Commands supported by Sub =========================

This list of commands was inferred from the command handler in /ArduSub/commands_logic.cpp.

[/site]

[site wiki="plane"] Commands supported by Plane ===========================

This list of commands was inferred from the command handler in /ArduPlane/commands_logic.cpp.

[/site]

[site wiki="rover" heading="off"] .. _commands_supported_by_rover:

Commands supported by Rover

This list of commands was inferred from the command handler in /Rover/commands_logic.cpp.

[/site]

Navigation commands

Navigation commands are used to control the movement of the vehicle, including takeoff, moving to and around waypoints, and landing.

NAV commands have the highest priority. Any DO_ and CONDITION_ commands that have not executed when a NAV command is loaded are skipped (for example, if a waypoint completes and the NAV command for another waypoint is loaded, and unexecuted DO/CONDITION commands associated with the first waypoint are dropped.

MAV_CMD_NAV_WAYPOINT

Supported by: All vehicles.

Navigate to the specified position.

[site wiki="copter" heading="off"]

The Copter will fly a straight line to the specified latitude, longitude , and altitude. It will then wait at the point for a specified delay time and then proceed to the next waypoint.

Command parameters

Command Field Mission Planner Field Description
param1 Delay Hold time at mission waypoint in integer seconds - MAX 65535 seconds.
param2
param3
param4
param5 Lat Target latitude. If zero, the Copter will hold at the current latitude.
param6 Lon Target longitude. If zero, the Copter will hold at the current longitude.
param7 Alt Target altitude. If zero, the Copter will hold at the current altitude.

Mission Planner screenshots

../../../images/WayPoint.jpg

Copter: Mission Planner Settings for WAYPOINT command

[/site]

[site wiki="plane" heading="off"]

The vehicle will fly to the specified latitude, longitude and altitude. The waypoint is considered "complete" when Plane is within the specified radius of the target location, at which point Plane processes the next command.

The protocol additionally provides for the plane to circle the waypoint with a specified radius and direction for a specified time (Delay). These parameters are not supported by Copter.

Command parameters

Command Field Mission Planner Field Description
param1
param2 Acc radius Acceptance radius in meters (waypoint is complete when the plane is this close to the waypoint location
param3 Pass by 0 to pass through the WP, if > 0 radius in meters to pass by WP. Positive value for clockwise orbit, negative value for counter-clockwise orbit. Allows trajectory control.
param4
param5 Lat Target latitude
param6 Lon Target longitude
param7 Alt Target altitude

[/site]

[site wiki="rover" heading="off"]

Command parameters

param7
Command Field Mission Planner Field Description
param1 Delay Hold time at mission waypoint in integer seconds - MAX 65535 seconds.
param2
param3
param4
param5 Lat Target latitude. If zero, the Copter will hold at the current latitude.
param6 Lon Target longitude. If zero, the Copter will hold at the current longitude.
Alt Target altitude. If zero, the Copter will hold at the current altitude.

[/site]

[site wiki="copter,plane" heading="off"]

MAV_CMD_NAV_TAKEOFF

Supported by: Copter, Plane (not Rover).

Takeoff (either from the ground or by hand-launch). It should be the first command of nearly all Plane and Copter missions. [/site]

[site wiki="copter" heading="off"]

The vehicle will climb straight up from its current location to the specified altitude. If the mission is begun while the copter is already flying, the vehicle will climb straight up to the specified altitude, if the vehicle is already above the altitude the command will be ignored and the mission will move on to the next command immediately.

Command parameters

Command Field Mission Planner Field Description
param1 Grade % Pitch/climb angle (Plane only).
param2 Empty
param3 Empty
param4 Yaw angle (ignored if compass not present).
param5 Lat Latitude
param6 Lon Longitude
param7 Alt Altitude

Mission planner screenshots

../../../images/TakeOff.jpg

Copter: Mission Planner Settings for TAKEOFF command

[/site]

[site wiki="plane" heading="off"]

The plane climbs to the specified altitude (at the specified pitch/climb angle) before proceeding to the next waypoint.

The plane is only attempting to climb at this point and can be pushed off its heading by wind. The pitch value is the minimum climb angle when using an airspeed sensor, and maximum angle when not using an airspeed sensor.

Command Field Mission Planner Field Description
param1 Pitch Angle Pitch/climb angle in degrees
param2 Empty
param3 Empty
param4 Yaw angle (ignored if compass not present).
param5 Lat Latitude
param6 Lon Longitude
param7 Alt Altitude

MAV_CMD_NAV_VTOL_TAKEOFF

Supported by: Plane (not Copter or Rover). Specifically QuadPlanes.

Takeoff while in VTOL mode.

The vehicle will climb straight up from it’s current location to the specified altitude as a delta above its current altitude.

However, if :ref:`Q_OPTIONS<Q_OPTIONS>` bit 3 is set (use altitude reference frames for VTOL takeoff), then the altitude value (in the specified reference frame) will be used for the target altitude, instead of a delta above the current altitude. If the command is begun while the vehicle is already flying, the vehicle will climb straight up to the specified altitude, if the vehicle is already above the altitude the command will be ignored and the mission will move on to the next command immediately.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Empty
param4
param5 Lat Latitude
param6 Lon Longitude
param7 Alt Altitude

[/site]

MAV_CMD_NAV_LOITER_UNLIM

Supported by: All vehicles.

Loiter at the specified location for an unlimited amount of time.

[site wiki="copter,rover" heading="off"]

Fly/Drive to the specified location and then loiter there indefinitely — where loiter means "wait in place" (rather than "circle"). If zero is specified for a latitude/longitude/altitude parameter then the current location value for the parameter will be used.

The mission will not proceed past this command while in AUTO mode. In order to break out of this command you need to change the mode (i.e. to MANUAL). If there are subsequent commands then you can continue the mission at the next command, if the Copter MIS_RESTART parameter is set to resume, by switching back to AUTO mode (otherwise the mission will restart).

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Radius around MISSION, in meters. If positive loiter clockwise, else counter-clockwise
param4 Desired yaw angle.
param5 Lat Target latitude. If zero, the vehicle will loiter at the current latitude.
param6 Lon Target longitude. If zero, the vehicle will loiter at the current longitude.
param7 Alt Target altitude. If zero, the vehicle will loiter at the current altitude.

Mission planner screenshots

../../../images/MissionList_LoiterUnlimited.png

Copter: Mission Planner Settings for LOITER_UNLIM command

[/site]

[site wiki="plane" heading="off"]

Fly to the specified location and then loiter there indefinitely — where loiter means "circle the waypoint". If zero is specified for a latitude/longitude/altitude parameter then the current location value for the parameter will be used. You can also specify the radius and direction for the loiter.

The mission will not proceed past this command while in AUTO mode. In order to break out of this command you need to change the mode (i.e. to MANUAL). If there are subsequent commands then you can continue the mission at the next command, if the Copter MIS_RESTART parameter is set to resume, by switching back to AUTO mode (otherwise the mission will restart).

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Dir 1=CW Radius around waypoint, in meters. Specify as a positive value to loiter clockwise, as a negative to move counter-clockwise.
param4 Desired yaw angle.
param5 Lat Target latitude. If zero, the vehicle will loiter at the current latitude.
param6 Lon Target longitude. If zero, the vehicle will loiter at the current longitude.
param7 Alt Target altitude. If zero, the vehicle will loiter at the current altitude.

[/site]

[site wiki="copter,plane,rover"] MAV_CMD_NAV_LOITER_TURNS ------------------------

Supported by: Copter, Plane (not Rover).

[/site] [site wiki="copter" heading="off"]

Loiter (circle) the specified location for at least the specified number of complete turns, and then proceed to the next command upon intersection of the course to it with the circle's perimeter. If zero is specified for a latitude/longitude/altitude parameter then the current location value for the parameter will be used. Fractional turns between 0 and 1 are supported, while turns greater than 1 must be integers.

The radius of the circle is controlled by the command parameter. A radius of 0 will result in the copter loitering at the location and pirouetting the specified number of turns. Negative radius values result in counter-clockwise turns instead of clockwise turns. Radius values over 255 meters will be rounded down to the nearest 10 meter mark.

This is the command equivalent of the :ref:`Circle flight mode <copter:circle-mode>`.

Command parameters

Command Field Mission Planner Field Description
param1 Turns Number of turns (N x 360°)
param2 Empty
param3 Radius Loiter radius around the waypoint. Units are in meters. Values over 255 will be rounded to units of 10 meters. and values greater than 2550 will be clamped to 2550 m. Negative values indicate counter-clockwise turns. If zero, vehicle will pirouette at location
param4 Empty
param5 Lat Target latitude. If zero, the vehicle will loiter at the current latitude.
param6 Lon Target longitude. If zero, the vehicle will loiter at the current longitude.
param7 Alt Target altitude. If zero, the vehicle will loiter at the current altitude.

Mission planner screenshots

../../../images/MissionList_LoiterTurns.png

Copter: Mission Planner Settings for LOITER_TURNS command

[/site]

[site wiki="plane" heading="off"]

Loiter (circle) the specified location for at least the specified number of complete turns, and then proceed to the next command upon intersection of the course to it with the circle's perimeter. If zero is specified for a latitude/longitude/altitude parameter then the current location value for the parameter will be used. Fractional turns between 0 and 1 are supported, while turns greater than 1 must be integers.

The radius of the circle is controlled by the command parameter. A radius of 0 will result in :ref:`WP_LOITER_RAD<WP_LOITER_RAD>` being used as the radius. Negative radius values result in counter-clockwise turns instead of clockwise turns. Radius values over 255 meters will be rounded down to the nearest 10 meter mark. Once the number of turns is completed, continue to loiter until heading points to next nav waypoint. If XTrack Tangent param =1, proceed directly to next waypoint, otherwise, track to the path in a line between the waypoint centers. =1.

Command parameters

Command Field Mission Planner Field Description
param1 Turns Number of turns (N x 360°)
param2 Empty
param3 Radius Loiter radius around the waypoint. Units are in meters. Values over 255 will be rounded to units of 10 meters. and values greater than 2550 will be clamped to 2550 m. Negative values indicate counter-clockwise turns. A value of zero will use WP_LOITER_RAD
param4 XTrack Tangent Determines which line the aircraft will track after exiting the loiter. If 0, track the line from the center of the circle to the next waypoint. If 1, track the line tangent to the circle to the next waypoint.
param5 Lat Target latitude. If zero, the vehicle will loiter at the current latitude.
param6 Lon Target longitude. If zero, the vehicle will loiter at the current longitude.
param7 Alt Target altitude. If zero, the vehicle will loiter at the current altitude.

[/site]

MAV_CMD_NAV_LOITER_TIME

Supported by: Copter, Plane, Rover. [site wiki="copter,rover" heading="off"]

Fly/Drive to the specified location and then loiter there for the specified number of seconds — where loiter means "wait in place" (rather than "circle"). The timer starts when the waypoint is reached; when it expires the waypoint is complete. If zero is specified for a latitude/longitude/altitude parameter then the current location value for the parameter will be used.

This is the mission equivalent of the :ref:`Loiter flight mode <copter:loiter-mode>` or :ref:`Hold mode <rover:hold-mode>`.

Command parameters

Command Field Mission Planner Field Description
param1 Time s Time to loiter at waypoint (seconds - decimal)
param2 Empty
param3 Dir 1=CW Radius around waypoint, in meters. Specify as a positive value to loiter clockwise, as a negative to move counter-clockwise.
param4 Desired yaw angle.
param5 Lat Target latitude. If zero, the vehicle will loiter at the current latitude.
param6 Lon Target longitude. If zero, the vehicle will loiter at the current longitude.
param7 Alt Target altitude. If zero, the vehicle will loiter at the current altitude.

Mission planner screenshots

../../../images/MissionList_LoiterTime.png

Copter: Mission Planner Settings for LOITER_TIME command

[/site]

[site wiki="plane" heading="off"]

Fly to the specified location and then loiter there for the specified number of seconds — where loiter means "circle the waypoint". The timer starts when the waypoint is reached; when it expires the waypoint is complete. If zero is specified for a latitude/longitude/altitude parameter then the current location value for the parameter will be used. You can also specify the radius and direction for the loiter. Once time has elapsed, continue to loiter until heading points to next nav waypoint. If XTrack Tangent param = gb1, proceed directly to next waypoint, otherwise, track to the path in a line between the waypoint centers.

The radius of the loiter is set in the WP_LOITER_RAD parameter.

Command parameters

Command Field Mission Planner Field Description
param1 Time (s) Time to loiter at waypoint (seconds - decimal)
param2 Empty
param3 Dir 1=CW Radius around waypoint, in meters. Specify as a positive value to loiter clockwise, as a negative to move counter-clockwise.
param4 XTrack Tangent Determines which line the aircraft will track after exiting the loiter. If 0, track the line from the center of the circle to the next waypoint. If 1, track the line tangent to the circle to the next waypoint.
param5 Lat Target latitude. If zero, the vehicle will loiter at the current latitude.
param6 Lon Target longitude. If zero, the vehicle will loiter at the current longitude.
param7 Alt Target altitude. If zero, the vehicle will loiter at the current altitude.

[/site]

MAV_CMD_NAV_RETURN_TO_LAUNCH

Supported by: All vehicles.

Return to the home location or the nearest Rally Point, if closer. The home location is where the vehicle was last armed (or when it first gets GPS lock after arming if the vehicle configuration allows this).

[site wiki="copter" heading="off"]

Copter

Return to the home location (or the nearest :ref:`Rally Point <common-rally-points>` if closer) and then land. The home location is where the vehicle was last armed (or when it first gets GPS lock after arming if the vehicle configuration allows this).

This is the mission equivalent of the :ref:`RTL flight mode <copter:rtl-mode>`. The vehicle will first climb to the :ref:`RTL_ALT_M<RTL_ALT_M>` parameter's specified altitude (default is 15m) before returning home.

This command takes no parameters and generally should be the last command in the mission.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_RTL.png

Copter: Mission PlannerSettings for RETURN_TO_LAUNCH command

[/site]

[site wiki="plane" heading="off"]

Return to the home location (or the nearest :ref:`Rally Point <common-rally-points>` if closer) and then "Loiter" (circle the point). The home location is where the vehicle was last armed (or when it first gets GPS lock after arming if the vehicle configuration allows this).

If the return is to a rally point, the plane will loiter at the position and altitude set in the rally point. If the return is to the home location, then the parameter :ref:`RTL_ALTITUDE <RTL_ALTITUDE>` is used for the loiter height (default 100m). The radius of the loiter is defined in the parameter :ref:`WP_LOITER_RAD <WP_LOITER_RAD>`.

This command takes no parameters and generally should be the last command in the mission.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="rover" heading="off"]

Return to the home location and HOLD (non-boat) or LOITER (boat).

This command takes no parameters and generally should be the last command in the mission. Without using this command, end of mission behavior is set by the :ref:`MIS_DONE_BEHAVE<MIS_DONE_BEHAVE>` parameter.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="copter,plane"]

MAV_CMD_NAV_LAND

Supported by: Copter, Plane (not Rover). [/site] [site wiki="copter"]

The copter will land at its current location or proceed at current altitude to the lat/lon coordinates provided (if non-zero) and land. This is the mission equivalent of the :ref:`LAND flight mode <copter:land-mode>`.

The motors will not stop on their own: you must exit AUTO mode to cut the engines.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Empty
param4 Desired yaw angle.
param5 Lat Target latitude. If zero, the Copter will land at the current latitude.
param6 Lon Longitude
param7 Alt Altitude

Mission planner screenshots

../../../images/MissionList_Land.png

Copter: Mission Planner Settings for LAND command

[/site]

[site wiki="plane" heading="off"]

The plane will land at its current location or proceed to the (non-zero) lat/lon coordinates provided beginning with current altitude. Information on the parameters used to control the landing is provided in :ref:`LAND flight mode <land-mode>`.

Command parameters

Command Field Mission Planner Field Description
param1 Abort Alt
param2 Empty
param3 Empty
param4 Desired yaw angle.
param5 Lat Latitude
param6 Long Longitude
param7 Alt Altitude to target for the landing. Unless you are landing at a location different than home, this should be zero

MAV_CMD_NAV_VTOL_LAND

Supported by: Plane (not Copter or Rover). Specifically QuadPlanes.

Land the vehicle at the current or a specified location.

If the :ref:`Q_OPTIONS<Q_OPTIONS>` bit 4 is not set (default),the vehicle will land at its current location or proceed at the current altitude to the lat/lon coordinates provided (if non-zero) and land. The ALT parameter is used to determine final landing phase initiation rather than :ref:`Q_LAND_FINAL_ALT<Q_LAND_FINAL_ALT>`. This is the mission equivalent of the :ref:`QLAND flight mode <qland-mode>`.

If the :ref:`Q_OPTIONS<Q_OPTIONS>` bit 4 is set (Use a fixed wind spiral approach), the it will fly in plane mode to the lat/lon coordinates provided (if non-zero), climbing or descending to the altitude set in the NAV_VTOL_LAND waypoint. When it reaches within :ref:`Q_FW_LND_APR_RAD<Q_FW_LND_APR_RAD>` of the landing location, it will perform a LOITER_TO_ALT to finish the climb or descent to that ALT set in the waypoint, then, turning into the wind, transition to VTOL mode and proceed to the landing location and land.

The motors will disarm on their own once landed

Note

param1 of the command acts just like :ref:`Q_OPTIONS<Q_OPTIONS>` bit 4 above, if that option bit is not set. This allows the use of different approaches for different VTOL_LAND commands within the same mission.

Command parameters

Command Field Mission Planner Field Description
param1 Option:if set to 1,forces FW spiral approach
param2 Empty
param3 Empty
param4 Desired yaw angle.
param5 Lat Target latitude. If zero, the QuadPlane will land at the current latitude.
param6 Lon Longitude
param7 Alt additional altitude above Q_LAND_FINAL_ALT to switch to final landing phase

[/site]

[site wiki="plane" heading="off"] MAV_CMD_NAV_CONTINUE_AND_CHANGE_ALT -----------------------------------

Supported by: Plane (not Copter, Rover).

Continue on the current course and climb/descend to a specified altitude. Move to the next command when the desired altitude is reached.

Note

The param1 value sets how close the vehicle altitude must be to target altitude for command completion.

Command parameters

Command Field Mission Planner Field Description
param1 TBD Climb or Descend (0 = Neutral, command completes when within 5m of this command's altitude, 1 = Climbing, command completes when at or above this command's altitude, 2 = Descending, command completes when at or below this command's altitude.
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Alt Target altitude

[/site]

[site wiki="copter"]

MAV_CMD_NAV_SPLINE_WAYPOINT

Supported by: Copter (not Plane or Rover).

Fly to the target location using a Spline path, then wait (hover) for a specified time before proceeding to the next command.

The Spline commands take all the same arguments are regular waypoints (lat, lon, alt, delay) but when executed the vehicle will fly smooth paths (both vertically and horizontally) instead of straight lines. Spline waypoints can be mixed with regular straight-line waypoints as shown in the screenshot below.

Command parameters

Command Field Mission Planner Field Description
param1 Delay Hold time at target, in decimal seconds.
param2 Empty
param3 Empty
param4 Empty
param5 Lat Latitude/X of goal
param6 Long Longitude/Y of goal
param7 Alt Altitude/Z of goal
../../../images/MissionList_SplineWaypoint.jpg

Copter: Mission Planner Settings for SPLINE_WAYPOINT command

The Mission Planner screenshot shows the path the vehicle will take.

  • The 1 second delay at the end of Waypoint #1 causes the vehicle to stop so Spline command #2 begins by taking a sharp 90degree turn
  • The direction of travel as the vehicle passes through Spline Waypoint #3 is parallel to an imaginary line drawn between waypoints #2 and #4
  • Waypoint #5 is a straight line so the vehicle lines itself up to point towards waypoint #5 even before reaching waypoint #4.

[/site]

[site wiki="copter,rover,sub"]

MAV_CMD_NAV_GUIDED_ENABLE

Supported by: Copter, Rover, Sub (not Plane).

Enable GUIDED mode to hand over control to an external controller/:ref:`common-companion-computers`. ee :ref:`Guided Mode <copter:ac2_guidedmode>` for more information. The :ref:`common-companion-computers` would then send MAVLink commands to control the vehicle.

See also :ref:`MAV_CMD_DO_GUIDED_LIMITS <mav_cmd_do_guided_limits>` for information on how to apply time, altitude and distance limits on the external control.

Command parameters

Command Field Mission Planner Field Description
param1 on=1/off=0 A value of > 0.5 enables GUIDED mode. Any value <= 0.5f turns it off.
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="plane"] MAV_CMD_NAV_ALTITUDE_WAIT -------------------------

Supported by: Plane (not Copter or Rover).

Mission command to wait for an altitude or downward vertical speed. This is meant for high-altitude balloon launches, allowing the aircraft to be idle until either an altitude is reached or a negative vertical speed is reached (indicating early balloon burst). The wiggle time is how often to wiggle the control surfaces to prevent them from seizing up.

Command parameters

Command Field Mission Planner Field Description
param1 ? Altitude (m)
param2 ? Descent speed (m/s)
param3 ? Wiggle Time (s)
param4 Empty
param5 Empty
param6 Empty
param7 Empty

MAV_CMD_NAV_LOITER_TO_ALT

Supported by: Plane (not Copter or Rover).

Loiter while climbing/descending to an altitude.

Begin loitering at the specified Latitude and Longitude. If Lat=Lon=0, then loiter at the current position. Don't consider the navigation command complete (don't leave loiter) until the altitude has been reached. Continue to loiter until heading points to next nav waypoint. If XTrack Tangent param =1, proceed directly to next waypoint, otherwise, track to the path in a line between the waypoint centers.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Radius Radius in meters. If positive loiter clockwise, negative counter-clockwise, 0 means no change to standard loiter.
param3 Empty
param4 XTrack Tangent Determines which line the aircraft will track after exiting the loiter. If 0, track the line from the center of the circle to the next waypoint. If 1, track the line tangent to the circle to the next waypoint.
param5 Lat Latitude.
param6 Long Longitude
param7 Alt Altitude

[/site]

MAV_CMD_NAV_DELAY

Supported by: Copter, Rover, Plane.

[site wiki="copter,rover"]

After reaching this waypoint, delay the execution of the next mission command until either the time in seconds has elapsed or the time entered(in the future) is reached. Execution of the next mission item then occurs. For Copters, they will loiter until then, and Rovers hold position.

Command parameters

Command Field Mission Planner Field Description
param1 Time (sec) Delay in seconds (integer)
param2 Time in hours(1-24) Delay until this hour
param3 Time in minutes(0-59) Delay until this minute
param4 Time in seconds (0-59) Delay until this second
param5 Empty
param6 Empty
param7 Empty

[/site] [site wiki="plane"]

After reaching this waypoint, if disarmed, delay the execution of the next mission command until the time in seconds has elapsed. This is used in a mission to allow a vehicle to land, disarm for a period (for a payload change for example), and then re-arm, and takeoff to resume the mission. If not disarmed, this mission item is skipped.

Command parameters

Command Field Mission Planner Field Description
param1 Time (sec) Delay in seconds (decimal).
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

MAV_CMD_NAV_PAYLOAD_PLACE

Supported by: Copter and Plane.

[site wiki="copter"]

After reaching this waypoint, the vehicle will descend up to the maximum descent value. If the payload has not touched the ground before this limit is reached, the vehicle will climb back up to the waypoint altitude and continue to the next mission item. If it reaches the ground, it will automatically release the gripper if enabled, and optionally wait a period, re-grip, and ascend back to the waypoint altitude and continue the mission. Numerous parameters that control the payload touch-down detection, wait period, etc. are prefaced with PLDP_. [/site] [site wiki="plane"] QUADPLANE ONLY, fixed wing planes will skip this command After reaching this waypoint, the vehicle will have transitioned to VTOL and will descend up to the maximum descent value. If the vehicle has not touched the ground before this limit is reached, the vehicle will climb back up to the waypoint altitude and continue to the next mission item. If it reaches the ground, it will stop its motors and wait for a LUA script command (see Package Place LUA applet ) to send an abort_landing command to ascend back to the waypoint altitude and continue to the next mission item, be sent a disarm command, or the pilot uses the RCx_OPTION = 173 to send the abort_landing command, instead of via a LUA script. This allows the gripper to be commanded to be released, packages replaced, etc. [/site] [wiki site="copter,plane"] Command parameters

Command Field Mission Planner Field Description
param1 Maximum Descent meters
param2 Empty
param3 Empty
param4 Empty
param5 Lat Latitude.
param6 Long Longitude
param7 Alt Altitude

[/site]

MAV_CMD_DO_JUMP

Supported by: All vehicles.

Jump to the specified command in the mission list. The jump command can be repeated either a specified number of times before continuing the mission, or it can be repeated indefinitely.

Tip

Despite the name, this command is really a "NAV_" command rather than a "DO_" command. Conditional commands like CONDITION_DELAY don't affect DO_JUMP (it will always perform the jump as soon as it reaches the command).

Note

  • There can be a maximum of 15 jump commands in a mission after which new DO_JUMP commands are ignored.

Command parameters

Command Field Mission Planner Field Description
param1 WP# The command index/sequence number of the command to jump to.
param2 Repeat# Number of times that the DO_JUMP command will execute before moving to the next sequential command. However, if MIS_OPTIONS bit 2 is not set, then the repeat count will be used again if the command is encountered again after the last repeat. If the value is zero the next command will execute immediately. A value of -1 will cause the command to repeat indefinitely.
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoJump.png

Mission Planner Settings for DO_JUMP command

In the example above the vehicle would fly back-and-forth between waypoints #1 and #2 a total of 3 times before flying on to waypoint #4.

MAV_CMD_JUMP_TAG

Supported by: Copter, Plane, Rover.

This is a location marker in the mission command sequence that can be used as a "jump to" location for the :ref:`MAV_CMD_DO_JUMP_TAG<MAV_CMD_DO_JUMP_TAG>` command. The tag id in its parameter field can be any arbitrary number between 1 and 65535.

Command parameters

Command Field Mission Planner Field Description
param1 Tag# The tag number for the DO_JUMP_TAG command.
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

MAV_CMD_DO_JUMP_TAG

Supported by: Copter, Plane, Rover.

Jump to the specified :ref:`MAV_CMD_JUMP_TAG<MAV_CMD_JUMP_TAG>` item in the mission list. The jump tag command can be repeated, either a specified number of times before continuing the mission, or it can be repeated indefinitely.

Tip

Despite the name, this command is really a "NAV_" command rather than a "DO_" command. Conditional commands like CONDITION_DELAY don't affect DO_JUMP (it will always perform the jump as soon as it reaches the command).

Note

  • There can be a maximum of 15 jump_tag commands in a mission after which new DO_JUMP_TAG commands are ignored.

Command parameters

Command Field Mission Planner Field Description
param1 WP# The tag number of the JUMP_TAG item to jump to.
param2 Repeat# Number of times that the DO_JUMP_TAG command will execute before moving to the next sequential command. If the value is zero the next command will execute immediately. A value of -1 will cause the command to repeat indefinitely.
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoJump_Tag.png

Mission Planner Settings for DO_JUMP_TAG command

In the example above, the vehicle would fly back-and-forth between waypoints #3 and #4 a total of 3 times before completing the mission. This is because the DO_JUMP_TAG redirects the vehicle to JUMP_TAG #565 twice.

Conditional commands

Conditional commands control the execution of _DO_ commands. For example, a conditional command can prevent DO commands from executing based on a time delay, until the vehicle is at a certain altitude, or at a specified distance from the next target position.

A conditional command may not be complete before reaching the next waypoint. In this case, any unexecuted _DO_ commands associated with the last waypoint will be skipped.

MAV_CMD_CONDITION_DELAY

Supported by: All vehicles.

After reaching a waypoint, delay the execution of the next conditional "_DO_" command for the specified number of seconds (e.g. :ref:`MAV_CMD_DO_SET_ROI <mav_cmd_do_set_roi>`).

Note

This command does not stop the vehicle. If the vehicle reaches the next waypoint before the delay timer completes, the delayed "_DO_" commands will never trigger.

Command parameters

Command Field Mission Planner Field Description
param1 Time (sec) Delay in seconds (decimal).
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_ConditionDelay.png

Mission Planner Settings for CONDITION_DELAY command

In the example above, Command #4 (DO_SET_ROI) is delayed so that it starts 5 seconds after the vehicle has passed Waypoint #2.

MAV_CMD_CONDITION_DISTANCE

Supported by: All vehicles.

Delays the start of the next "_DO_" command until the vehicle is within the specified number of meters of the next waypoint.

Note

This command does not stop the vehicle: it only affects DO commands.

Command parameters

Command Field Mission Planner Field Description
param1 Dist (m) Distance from the next waypoint before DO commands are executed (meters).
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_ConditionDistance.png

Mission PlannerSettings for CONDITION_DISTANCE command

In the example above, Command #4 (DO_SET_ROI) is delayed so that it only starts once the vehicle is within 50m of waypoint #5.

[site wiki="copter" heading="off"]

MAV_CMD_CONDITION_YAW

Supported by: Copter (not Plane or Rover).

Point (yaw) the nose of the vehicle towards a specified heading.

The parameters allow you to specify whether the target direction is absolute or relative to the current yaw direction. If the direction is relative you can also (separately) specify whether the value is added or subtracted from the current heading (note that the vehicle will always turn in the direction that most quickly gets it to the new target heading regardless of the param3 value).

Command parameters

Command Field Mission Planner Field Description
param1 Deg If param4=0 (absolute): Target heading in degrees [0-360] (0 is North). If param4=1 (relative): The change in heading (in degrees).
param2 Speed deg/s Speed during yaw change:[deg per second].
param3 Dir 1=CW Used to denote the direction of rotation to achieve the target angle (-1=CCW, 1=CW, 0=the vehicle will always turn in the direction that most quickly gets it to the new target heading, but only if param4=0 (absolute), otherwise 0 = CW).
param4 0=Abs 1=Rel Specify if param1 ("Deg" field) is an absolute direction (0) or a relative to the current yaw direction (1).
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_ConditionYaw.png

Copter: Mission Planner Settings for CONDITION_YAW command

[/site] [site wiki="copter" heading="off"]

Special Commands

This section is for commands that may be relevant to missions, but which are not mission commands (part of the mission).

MAV_CMD_MISSION_START

Supported by: Copter

This command can be used to start a mission when the Copter is on the ground in AUTO mode. If the vehicle is already in the air then the mission will start as soon as you switch into AUTO mode (so this command is not needed/ignored). This allows a GCS/companion computer to start a mission in AUTO without raising the throttle.

Note

Previously a mission would only start after the pilot engaged the throttle. This command makes it possible to start missions without directly controlling the throttle (though that approach is still available).

This is not a "mission command" (it can't be used as a type of mission waypoint). It is run from the Action menu (see the screenshot below).

Command parameters

The parameters are all ignored.

Command Field Mission Planner Field Description
param1 The first mission item to run.
param2 The last mission item to run (after this item is run, the mission ends).
param3
param4
param5
param6
param7

Mission Planner screenshots

../../../images/MissionPlanner_MissionStartCommand.jpg

Mission Planner: MISSION_START command

MAV_CMD_COMPONENT_ARM_DISARM

Supported by: Copter

Disarm the motors.

The command supports disarming on the ground and in flight.

Note

The motors will disarm automatically after landing.

This is not a "mission command" (it can't be used as a type of mission waypoint).

Command parameters

Command Field Mission Planner Field Description
param1 1 to arm, 0 to disarm. This only works when the vehicle is on the ground.
param2 A value of 21196 will disarm the vehicle in flight.
param3
param4
param5
param6
param7

[/site]

DO commands

The "DO" or "Now" commands are executed once to perform some action. All the DO commands associated with a waypoint are executed immediately.

MAV_CMD_DO_CHANGE_SPEED

Supported by: Copter, Plane, Rover.

[site wiki="copter" heading="off"]

Sets the desired maximum speed in meters/second (only). Both the speed-type and throttle settings are ignored.

Command parameters

Command Field Mission Planner Field Description
param1 Type Speed type (0,1=Ground Speed, 2=Climb Speed, 3=Descent Speed).
param2 speed in m/s Target speed (m/s).
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoChangeSpeed.png

Copter: Mission Planner Settings for DO_CHANGE_SPEED command

[/site]

[site wiki="plane" heading="off"]

Change the target horizontal speed (airspeed or groundspeed) and/or the vehicle's throttle. If the airspeed option is selected, this changes the :ref:`AIRSPEED_CRUISE<AIRSPEED_CRUISE>` parameter during the flight until reboot or mode is changed to CRUISE or FBWB. If the groundspeed option is used, then :ref:`MIN_GROUNDSPEED<MIN_GROUNDSPEED>` parameter is changed to this value until rebooted or changed by this command again. If the throttle field is non-zero and equal to or below 100, then the :ref:`TRIM_THROTTLE<TRIM_THROTTLE>` parameter is changed until reboot or changed by this command again.

Note

Speed changes only have an effect if an airspeed sensor is present, healthy, and in use. :ref:`TRIM_THROTTLE<TRIM_THROTTLE>` changes impacts only flight with airspeed sensor not in use.

Command parameters

Command Field Mission Planner Field Description
param1 Type Speed type (0=Airspeed, 1=Ground Speed).
param2 Speed (m/s) Target speed (m/s). If airspeed, a value below or above min/max airspeed limits results in no change. a value of -2 uses :ref:`AIRSPEED_CRUISE`
param3 Throttle(%) Throttle as a percentage (0-100%). A value of 0 or negative indicates no change.
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="rover" heading="off"]

Change the target horizontal speed and/or the vehicle's throttle.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Speed (m/s) Target speed (m/s).
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

MAV_CMD_DO_SET_HOME

Supported by: All vehicles.

Sets the home location either as the current location or at the location specified in the command. For SITL work, altitude input here needs to be with reference to absolute altitude, taking into account SRTM elevation.

Note

  • For Plane and Rover, if a good GPS fix cannot be obtained the location specified in the command is used.
  • For Copter, the command will also try to use the current position if all the location parameters are set to 0. The location information in the command is only used if it is close to the EKF origin.

[site wiki="copter" heading="off"]

[/site]

Command parameters

Command Field Mission Planner Field Description
param1 Current Set home location: 1=Set home as current location. 0=Use location specified in message parameters.
param2 Empty
param3 Empty
param4 Empty
param5 Lat Target home latitude (if param1=0)
param6 Lon Target home longitude (if param1=0)
param7 Alt Target home altitude (if param1=0)

Mission planner screenshots

../../../images/MissionList_DoSetHome.png

Mission Planner Settings for DO_SET_HOME command

MAV_CMD_DO_SET_RELAY

Supported by: All vehicles.

Set a Relay pin's voltage high (on) or low (off).

Command parameters

Command Field Mission Planner Field Description
param1 Relay No Relay number.
param2 off(0)/on(1) Set relay state: 1: Set relay high/on (3.3V on Pixhawk, 5V on APM). 0: Set relay low/off (0v) any other value toggles the relay
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionPlanner_DO_SET_RELAY.png

MissionPlanner Settings for DO_SET_RELAY command

MAV_CMD_DO_REPEAT_RELAY

Supported by: All vehicles.

Toggle the :ref:`Relay <common-relay>` pin's voltage/state a specified number of times with a given period. Toggling the Relay will turn an off relay on and vice versa

Command parameters

Command Field Mission Planner Field Description
param1 Relay No Relay number.
param2 Repeat # Cycle count - the number of times the relay should be toggled
param3 Delay(s) Cycle time (seconds, decimal) - time between each toggle.
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoRepeatRelay.png

Mission Planner Settings for DO_RELAY_REPEAT command

In the example above, assuming the relay was off to begin with, it would be set high and then after 3 seconds, it would be toggled low again.

MAV_CMD_DO_SET_SERVO

Supported by: All vehicles.

Set a given :ref:`servo pin <common-servo>` output to a specific PWM value.

Command parameters

Command Field Mission Planner Field Description
param1 Ser No Servo number - target servo output pin/channel number.
param2 PWM PWM value to output, in microseconds (typically 1000 to 2000).
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoSetServo.png

Mission Planner Settingsfor DO_SET_SERVO command

In the example above, the servo attached to output channel 8 would be moved to PWM 1700 (servos generally accept PWM values between 1000 and 2000).

Note

as of firmware versions 4.0 and later, this command can be used on any output configured by its SERVOx_FUNCTION command as 0,1, or 51-66 (disabled or RC pass-throughs)

MAV_CMD_DO_REPEAT_SERVO

Supported by: All vehicles.

Cycle a :ref:`servo <common-servo>` PWM output pin between its mid-position value and a specified PWM value, for a given number of cycles and with a set period.

The mid-position value is specified in the RCn_TRIM parameter for the channel (RC8_TRIM in the screenshot below). The default value is 1500..

Command parameters

Command Field Mission Planner Field Description
param1 Ser No Servo number - target servo output pin/channel.
param2 PWM PWM value to output, in microseconds (typically 1000 to 2000).
param3 Repeat # Cycle count - number of times to move the servo to the specified PWM value
param4 Delay (s) Cycle time (seconds) - the delay in seconds between each servo movement.
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoRepeatServo.png

Mission Planner Settingsfor DO_REPEAT_SERVO command

In the example above, the servo attached to output channel 8 would be moved to PWM 1700, then after 4 second, back to mid, after another 4 seconds it would be moved to 1700 again, then finally after 4 more seconds it would be moved back to mid.

[site wiki="plane" heading="off"]

MAV_CMD_DO_LAND_START

Supported by: Plane (not Copter, Rover).

Mission command to prepare for a landing.

This is used as a marker in a mission to tell the autopilot where a sequence of mission items that represents a landing starts. It may also be sent via a COMMAND_LONG to trigger a landing, in which case the nearest (geographically) landing sequence in the mission will be used.

If RTL_AUTOLAND is set to 2, the plane will jump to the nearest DO_LAND_START in the mission table when RTL is initialized.

Note

General information on landing a plane is provided in the topic :ref:`Automatic Landing <automatic-landing>`.

Command parameters

Command Field Mission Planner Field Description
param1 Empty
param2 Empty
param3 Empty
param4 Empty
param5 Lat Latitude used to help find the closest landing sequence, or zero if not needed.
param6 Long Longitude used to help find the closest landing sequence, or zero if not needed.
param7 Empty

MAV_CMD_DO_VTOL_TRANSITION

Supported by: Plane (not Copter or Rover).Specifically QuadPlanes.

Mission command to change to/from VTOL and fixed wing mode of flight. The mode is changed based on the first parameter: 3 = change to VTOL flight, 4 = change to fixed wing flight.

Command parameters

Command Field Mission Planner Field Description
param1 Mode 3=VTOL,4=Fixed-Wing
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

MAV_CMD_DO_SET_ROI, MAV_CMD_DOE_SET_ROI_LOOCATION, MAV_CMD_DO_SET_ROI_NONE

Supported by: Copter, Plane, Rover,Sub. Currently, the DO_SET_ROI,DO_SET_ROI_LOCATION, and DO_SET_ROI_NONE commands all behave the same with DO_SET_ROI_NONE removing the ROI target, the same as setting the location to 0,0 in the other commands.

[site wiki="copter" heading="off"]

Points the :ref:`camera gimbal <common-cameras-and-gimbals>` at the "region of interest", and also rotates the nose of the vehicle if the mount type does not support a yaw feature.

After setting the ROI, the camera/vehicle will continue to follow it until the end of the mission, unless it is changed or cleared by setting another ROI. Clearing the ROI is achieved by setting a later DO_SET_ROI command with all zero for param5-param7 (Lat, Lon and Alt).

Command parameters

Command Field Mission Planner Field Description
param1 Region of interest mode. (see MAV_ROI enum) // 0 = no roi, 1 = next waypoint, 2 = waypoint number, 3 = fixed location, 4 = given target (not supported)
param2 MISSION index/ target ID. (see MAV_ROI enum)
param3 ROI index (allows a vehicle to manage multiple ROI's)
param4 Empty
param5 Lat Latitude (x) of the fixed ROI
param6 Long Longitude (y) of the fixed ROI
param7 Alt Altitude of the fixed ROI

Mission planner screenshots/video

../../../images/MissionList_DoSetRoi.jpg

Copter: Mission Planner Settings for DO_SET_ROI command

In the example above the nose and camera would be pointed at the red marker.

..  youtube:: W8NCFHrEjfU
    :width: 100%

[/site]

[site wiki="plane" heading="off"]

Points the :ref:`camera gimbal <common-cameras-and-gimbals>` at the "region of interest".

After setting the ROI, the camera will continue to follow it until the end of the mission, unless it is changed or cleared by setting another ROI. Clearing the ROI is achieved by setting a later DO_SET_ROI command with all zeros for param5-param7 (Lat, Lon and Alt).

Command parameters

Command Field Mission Planner Field Description
param1 Region of interest mode. (see MAV_ROI enum) // 0 = no roi, 1 = next waypoint, 2 = waypoint number, 3 = fixed location, 4 = given target (not supported)
param2 MISSION index/ target ID. (see MAV_ROI enum)
param3 ROI index (allows a vehicle to manage multiple ROI's)
param4 Empty
param5 Lat Latitude (x) of the fixed ROI
param6 Long Longitude (y) of the fixed ROI
param7 Alt Altitude of the fixed ROI

[/site]

[site wiki="rover" heading="off"]

Points the :ref:`camera gimbal <common-cameras-and-gimbals>` at the "region of interest".

After setting the ROI, the camera will continue to follow it until the end of the mission, unless it is changed or cleared by setting another ROI. Clearing the ROI is achieved by setting a later DO_SET_ROI command with all zeros for param5-param7 (Lat, Lon, and Alt).

Command parameters

Command Field Mission Planner Field Description
param1 Region of interest mode. (see MAV_ROI enum) // 0 = no roi, 1 = next waypoint, 2 = waypoint number, 3 = fixed location, 4 = given target (not supported)
param2 MISSION index/ target ID. (see MAV_ROI enum)
param3 ROI index (allows a vehicle to manage multiple ROI's)
param4 Empty
param5 Lat Latitude (x) of the fixed ROI
param6 Long Longitude (y) of the fixed ROI
param7 Alt Altitude of the fixed ROI

[/site]

MAV_CMD_DO_SET_ROI_WPNEXT_OFFSET

[site wiki="copter" heading="off"]

Points the :ref:`camera gimbal <common-cameras-and-gimbals>` at the location of the next waypoint in the mission, with an optional roll/pitch/yaw offset added on top of that pointing angle. This differs from DO_SET_ROI's "next waypoint" mode (param1 = 1), which has no offset capability.

Once set, the gimbal continues tracking the next waypoint -- re-aiming automatically as the vehicle advances through the mission and "next waypoint" changes -- until a later mount-targeting command changes the mode.

Note

This command is currently only implemented for Copter. Plane, Rover, and Sub accept it without error, but since those vehicles do not yet provide a "next waypoint" location to the mount, no new pointing angle is set and the gimbal simply continues doing whatever it was doing before.

Note

Requires a board with more than 2MB of flash; it is compiled out by default on smaller F4-class boards. On :ref:`custom firmware builds <common-custom-firmware>`, enable both the "MOUNT_WPNEXT_OFFSET" and "MISSION_WPNEXT_OFFSET" options.

Command parameters

Command Field Mission Planner Field Description
param1 Gimbal device ID. Currently not used by ArduPilot; the primary mount is always targeted regardless of this value.
param2 Empty
param3 Empty
param4 Empty
param5 Pitch offset in degrees, positive pitching up
param6 Roll offset in degrees, positive rolling to the right
param7 Yaw offset in degrees, positive yawing to the right

[/site]

MAV_CMD_DO_DIGICAM_CONFIGURE

Supported by: All vehicles.

Configure an on-board camera controller system.

The parameters are forwarded to an on-board camera controller system (like the 3DR Camera Control Board), if one is present.

Command parameters

Command Field Mission Planner Field Description
param1 Mode Set camera mode: 1: ProgramAuto 2: Aperture Priority 3: Shutter Priority 4: Manual 5: IntelligentAuto 6: SuperiorAuto
param2 Shutter Speed Shutter speed (seconds divisor). So if the speed is 1/60 seconds, the value entered would be 60. Slowest shutter trigger supported is 1 second.
param3 Aperture Aperture: F stop number
param4 ISO ISO number e.g. 80, 100, 200, etc.
param5 ExposureMode Exposure type enumerator
param6 CommandID Command Identity
param7 Engine Cut-Off Main engine cut-off time before camera trigger in seconds/10 (0 means no cut-off).

MAV_CMD_DO_DIGICAM_CONTROL

Supported by: All vehicles.

Trigger the :ref:`camera shutter <common-camera-shutter-with-servo>` once. This command takes no additional arguments.

Command parameters

In general, if a command field is set to 0 it is ignored.

Command Field Mission Planner Field Description
param1 On/Off Session control (on/off or show/hide lens): 0: Turn off the camera / hide the lens 1: Turn on the camera /Show the lens
param2 Zoom Position Zoom's absolute position. 2x, 3x, 10x, etc.
param3 Zoom Step Zooming step value to offset zoom from the current position
param4 Focus Lock Focus Locking, Unlocking or Re-locking: 0: Ignore 1: Unlock 2: Lock
param5 Shutter Cmd Shooting Command. Any non-zero value triggers the camera.
param6 CommandID Command Identity
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoDigicamControl.png

Mission PlannerSettings for DO_DIGICAM_CONTROL command.

MAV_CMD_DO_MOUNT_CONTROL

Supported by: All vehicles.

Mission command to control a camera or antenna mount.

This command allows you to specify a roll, pitch and yaw angle which will be sent to the :ref:`camera gimbal <common-cameras-and-gimbals>`. This can be used to point the camera in specific directions at various times in the mission.

Command parameters

Command Field Mission Planner Field Description
param1 Pitch, in degrees.
param2 Roll, in degrees.
param3 Yaw, in degrees.
param4 reserved
param5 reserved
param6 reserved
param7 `MAV_MOUNT_MODE `__ enum value.

Mission planner screenshots

../../../images/MissionList_DoMountControl.png

Mission Planner Settings for DO_MOUNT_CONTROL command

MAV_CMD_DO_GIMBAL_MANAGER_PITCHYAW

Supported by: All vehicles.

Mission command to move the gimbal to the desired pitch and yaw angles (in degrees).

This command allows you to specify a pitch and yaw angle which will be sent to the :ref:`camera gimbal <common-cameras-and-gimbals>`. This can be used to point the camera in specific directions at various times in the mission. Positive pitch angles are up, Negative are down. Positive yaw angles are clockwise, negative are counter clockwise.

Command parameters

Command Field Mission Planner Field Description
param1 Pitch, in degrees.
param2 Yaw, in degrees.
param3 PitchRate, in deg/s.
param4 YawRate, in deg/s
param5 Flags: 0=boddyframe, 16=earthframe
param6 reserved
param7 Gimbal instance ID

Mission planner screenshots

../../../images/mission-list-do-gimbal-manager-pitchyaw.png

Mission PlannerSettings for DO_GIMBAL_MANAGE_PITCHYAW command

MAV_CMD_DO_SET_CAM_TRIGG_DIST

Supported by: All vehicles.

Trigger the :ref:`camera shutter <common-camera-shutter-with-servo>` at regular distance intervals. This command is useful in :ref:`camera survey missions <common-camera-control-and-auto-missions-in-mission-planner>`. To trigger the camera once, immediately after passing the DO command, set param3 to 1.

Note

Providing a distance of zero will stop the camera shutter from being triggered.

Command parameters

Command Field Mission Planner Field Description
param1 Dist (m) Camera trigger distance interval (meters). Zero to turn off distance triggering.
param2 Empty
param3 ? Trigger once instantly. One is on, zero is off.
param4 Empty
param5 Empty
param6 Empty
param7 Empty

Mission planner screenshots

../../../images/MissionList_DoSetCamTriggDist.png

Mission PlannerSettings for DO_SET_CAM_TRIGG_DIST command

The above configuration will cause the camera shutter to trigger after every 5m that the vehicle travels.

MAV_CMD_DO_FENCE_ENABLE

Supported by: All vehicles.

Mission commands to enable the Plane :ref:`GeoFence <geofencing>`, Copter/Rover :ref:`common-ac2_simple_geofence` and/or :ref:`common-polygon_fence`.

Command parameters

Command Field Mission Planner Field Description
param1 Set GeoFence enable state (0=disable, 1=enable, 2= disable only floor (Plane only)).
param2 bitmask The target fence is specified by the bitmask value of FENCE_TYPE. 0 is ALL configured fences.
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

MAV_CMD_DO_AUX_FUNCTION

Supported by: All vehicles.

Mission command to control an :ref:`Auxiliary Function<common-auxiliary-functions>` in the same manner as an RC channel switch.

Command parameters

Command Field Mission Planner Field Description
param1 Aux Function Auxiliary Function code,same as RCx_OPTIONS
param2 Switch Position 0:Low, 1:Mid, 2:High
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[site wiki="copter" heading="off"]

MAV_CMD_DO_PARACHUTE

Supported by: Copter (not Plane or Rover).

Mission command to trigger a parachute (if enabled).

Command parameters

Command Field Mission Planner Field Description
param1 Enable/Release Parachute action (0=disable, 1=enable, 2=release).
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="plane" heading="off"]

MAV_CMD_DO_INVERTED_FLIGHT

Supported by: Plane (not Copter or Rover).

Change between normal and :ref:`inverted flight <inverted-flight>`.

Command parameters

Command Field Mission Planner Field Description
param1 0=normal, 1=inverted Set flight type: 0: normal 1: inverted
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="copter" heading="off"]

MAV_CMD_DO_GRIPPER

Supported by: Copter (not Plane or Rover).

Mission command to operate EPM gripper.

Note

The :ref:`instructions for integrating Copter with gripper <common-electro-permanent-magnet-gripper>` are out of date and use DO_SET_SERVO to activate the gripper (April 2015).

Command parameters

Command Field Mission Planner Field Description
param1 Gripper No Gripper number (from 1 to maximum number of grippers on the vehicle).
param2 drop(0)/grab(1) Gripper action: 0:Release 1:Grab
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

MAV_CMD_DO_GUIDED_LIMITS

Supported by: Copter (not Plane or Rover).

This command sets the time, altitude, and distance limits for external control (GUIDED mode). When these limits are exceeded, control will return from GUIDED mode to the mission. Setting any of these parameters to zero will remove the associated limit.

Command parameters

Command Field Mission Planner Field Description
param1 timeout S Maximum time (in seconds) that the external controller is allowed to control vehicle. Use 0 to remove time limits (unlimited time allowed).
param2 min alt Minimum allowed absolute altitude (in meters, AMSL), below which the command will be aborted and the mission will continue. Use 0 to indicate that there is no minimum altitude limit.
param3 max alt Maximum allowed absolute altitude (in meters, AMSL), above which the command will be aborted and the mission will continue. Use 0 to indicate that there is no maximum altitude limit.
param4 max dist Horizontal move limit (in meters, AMSL). If the vehicle moves more than this distance from its location at the moment the command was executed, the the command will be aborted and the mission will continue. Use 0 to indicate that there is no horizontal limit.
param5 Empty
param6 Empty
param7 Empty

[/site]

[site wiki="plane" heading="off"]

MAV_CMD_DO_AUTOTUNE_ENABLE

Supported by: Plane (not Copter or Rover).

Enable/disable :ref:`AUTOTUNE <autotune-mode>` mode.

Command parameters

Command Field Mission Planner Field Description
param1 na Enable/disable autotune (1: enable, 0:disable)
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

MAV_CMD_DO_ENGINE_CONTROL

Supported by: Plane (not Copter or Rover).

Stop or start the internal combustion engine (ICE)

This command can be used to start or stop the ICE before a NAV_VTOL_LAND or after a NAV_VTOL_TAKEOFF command for a QuadPlane to avoid potential prop strikes in the wind. It should be placed before either of those commands.Also can be used to allow a single engine start while disarmed if otherwise prohibited by :ref:`ICE_OPTIONS<ICE_OPTIONS>` bit 3 being set,

Command parameters

Command Field Mission Planner Field Description
param1 ? Start/Stop ICE (1: start, 0:stop)
param2 Cold Start (1: enables choke, currently not implemented)
param3 Altitude in meters. Altitude at which action is taken.
param4 Flags: 1 = allow a single start while disarmed even if :ref:`ICE_OPTIONS` bit 3 is set
param5 Empty
param6 Empty
param7 Empty

[/site]

MAV_CMD_DO_SET_RESUME_REPEAT_DIST

Supported by: All vehicles.

Set the distance that the mission will be rewound when resuming after an interrupt (switching modes). A full explanation of this feature can be found on the :ref:`Mission Rewind on Resume Page <common-mission-rewind>`. After setting a rewind distance in a mission, setting the distance to zero will switch off the rewind feature from that point on the mission.

Command parameters

Command Field Mission Planner Field Description
param1 ? Rewind distance in meters
param2 Empty
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

MAV_CMD_STORAGE_FORMAT

Supported by: All vehicles.

Format SD Card. Useful for vehicles where SD card is inaccessible. Param1 and Param2 must be set to 1.

Command parameters

Command Field Mission Planner Field Description
param1 ? Must be 1
param2 ? Must be 1
param3 Empty
param4 Empty
param5 Empty
param6 Empty
param7 Empty

[site wiki="copter" heading="off"] .. _mav_cmd_do_winch:

MAV_CMD_DO_WINCH

Supported by: Copter.

Control Winch operation.

Command parameters

Command Field Mission Planner Field Description
param1 Winch no Not currently used
param2 action 0 to relax the winch, 1 for Length control, 2 for Rate control
param3 length should be filled in with the meters of the line to release. Positive numbers release the line, negative retract the line. Note "action" should be "1"
param4 rate should be filled in with the speed (in m/s) to release the line. Positive numbers release the line, negative retract the line. Note "action" should be "2".
param5 Empty
param6 Empty
param7 Empty

[/site]

[copywiki destination="plane,copter,rover,sub,planner,dev"]