Mode Requirements
INFO
This documentation was auto-generated from the source code (see docs/scripts/get_mode_requirements).
Mode requirements define the set of conditions that must be met in order to arm in a particular flight mode, or to switch to the mode if it is already armed.
Requirements are defined for internal modes in mode_requirements.cpp, and for ROS 2 external modes in requirement_flags.hpp (Github Auterion/px4-ros2-interface-lib repository). The mode requirements are the same in both cases.
The following sections provide an overview of the requirements and what modes they are used in.
Requirements Definitions
| Requirement | Example |
|---|---|
mode_req_angular_velocity | Angular velocity (gyroscope) |
mode_req_attitude | Attitude/pose (IMU, or theoretically a motion capture system) |
mode_req_local_position | Position relative to EKF2 origin ('0') point (GNSS, VIO, mocap) |
mode_req_local_position_relaxed | Position relative to EKF2 origin ('0') point but accepts poor accuracy (Optical flow) Typically optical flow. You set zero when you take off and just integrate up the flow. So the absolute position can be very inaccurate but better than nothing. Useful to not drift away quickly and roughly know where you are. |
mode_req_global_position | Position measurement updates in a global coordinate frame (GNSS, or local position and global reference to EKF 0) |
mode_req_global_position_relaxed | Position measurement updates in a global coordinate frame but accepts poor accuracy Local position and global reference to EKF2 origin |
mode_req_local_alt | Local altitude relative to EKF2 origin ('0') position (Barometer corrected by GNSS altitude over time, distance sensor) Usually not the distance sensor because if the ground shifts then the coordinate frame would shift with it (range aid problem). |
mode_req_mission | Valid mission in autopilot's storage (Mission mode only requirement) can be from last time no need to upload fresh |
mode_req_offboard_signal | Offboard heartbeat MAVLink messages SET_ATTITUDE_TARGET or SET_POSITION_TARGET_LOCAL_NED or SET_POSITION_TARGET_GLOBAL_INT not timing out. Offboard mode specific requirement. |
mode_req_home_position | Global home reference must be set Specific requirement for Return mode |
mode_req_wind_and_flight_time_compliance | Safety compliance limits on wind and flight time. Blocks arming or switching into the mode when the estimated wind speed exceeds COM_WIND_MAX (if COM_WIND_MAX_ACT is set to an action stronger than a warning), or when the flight time exceeds COM_FLT_TIME_MAX. Both limits are disabled by default. Modes commanded by a failsafe are exempt (see also COM_WIND_WARN). |
mode_req_prevent_arming | Mode prevents arming The vehicle cannot be armed while this mode is selected. Set for modes such as Land, Orbit, and Return that you can't take off in (they can only be entered in flight). |
mode_req_manual_control | Requires stick input Manual control can come from an RC system (RC driver -> channel mapping/calibration -> manual_control_input) or from a joystick (MAVLink MANUAL_CONTROL message -> manual_control_input). A selector configured with COM_RC_IN_MODE chooses which source is used and publishes it as manual_control_setpoint. The requirement is met while the selected source has not timed out. |
mode_req_other | Others requirement. This is used by external modes. It is intended to specify additional requirements not covered by the existing flags |
Naming Conventions
In general requirement flag names are abstracted from specific sensors. This is done because particular requirements can often be met by several sensors. For example, GNSS is the most common source of global position, but it isn't the only one.
The requirements include frame and accuracy information hints in their names:
globalmeans an absolute world frame, such as that provided by GNSS.localmeans a frame that relative to an initialization point, such as the position of an IMU on boot.relaxedmeans that the mode does not require or rely on accurate data: as long as sensors are providing some data the state is considered valid. Relaxed conditions are used for modes where some sensor data is considered more important than none at all, such as when calculating position via optical flow velocity measurements. By contrast, a position mode that is not relaxed requires reliable sensor data, and will block arming if inaccuracy is detected.
Note that a global position requirement can be met if you have a valid local position, by mapping the local frame to a global position. This can be done by setting the global position of the local origin using the MAVLink message SET_GPS_GLOBAL_ORIGIN, either directly or via a GCS (see External Position Estimate > Enabling Auto Modes with a Local Position). Similarly, if the vehicle has mode_req_local_position_relaxed, then you can map to a global position in order to meet the global_position_relaxed requirement. This allows PX4 automatic flight modes that require a global position to be used locally, such as Mission and Return.
Fixed-wing (VEHICLE_TYPE_FIXED_WING)
Manual Mode (NAVIGATION_STATE_MANUAL)
Stabilized Mode (NAVIGATION_STATE_STAB)
Acro Mode (NAVIGATION_STATE_ACRO)
Altitude Mode (NAVIGATION_STATE_ALTCTL)
Cruise Mode (NAVIGATION_STATE_POSCTL)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_position_relaxedmode_req_manual_control
Guided Course Mode (NAVIGATION_STATE_GUIDED_COURSE)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_position_relaxedmode_req_wind_and_flight_time_compliance
Hold Mode (NAVIGATION_STATE_AUTO_LOITER)
mode_req_angular_velocitymode_req_attitudemode_req_global_position_relaxedmode_req_local_altmode_req_local_position_relaxedmode_req_wind_and_flight_time_compliance
Takeoff Mode (NAVIGATION_STATE_AUTO_TAKEOFF)
Descend Mode (NAVIGATION_STATE_DESCEND)
Land Mode (NAVIGATION_STATE_AUTO_LAND)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_position_relaxedmode_req_prevent_arming
Return Mode (NAVIGATION_STATE_AUTO_RTL)
mode_req_angular_velocitymode_req_attitudemode_req_global_position_relaxedmode_req_home_positionmode_req_local_altmode_req_local_position_relaxedmode_req_prevent_arming
Mission Mode (NAVIGATION_STATE_AUTO_MISSION)
mode_req_angular_velocitymode_req_attitudemode_req_global_position_relaxedmode_req_local_altmode_req_local_position_relaxedmode_req_missionmode_req_wind_and_flight_time_compliance
Offboard Mode (NAVIGATION_STATE_OFFBOARD)
Modes Without a Dedicated Page
The following internal navigation states have no distinct user-facing behaviour or documentation page on this frame type:
- NAVIGATION_STATE_ALTITUDE_CRUISE — Behaves identically to Altitude Mode on fixed-wing frames — the control-mode flags are the same and there is no separate implementation.
- NAVIGATION_STATE_POSITION_SLOW — Behaves identically to Position Mode on fixed-wing frames — the control-mode flags are the same and there is no separate implementation.
- NAVIGATION_STATE_ORBIT — Not implemented for fixed-wing frames; Hold Mode is used instead for orbiting a point.
- NAVIGATION_STATE_AUTO_VTOL_TAKEOFF — VTOL-specific transition state used for vertical takeoff before transitioning to forward flight; not applicable to plain fixed-wing frames.
- NAVIGATION_STATE_AUTO_PRECLAND — Not implemented for fixed-wing frames (precision landing requires hover capability).
- NAVIGATION_STATE_AUTO_FOLLOW_TARGET — Not implemented for fixed-wing frames (Follow Me is a multicopter-only flight task).
- NAVIGATION_STATE_TERMINATION — Internal flight-termination failsafe state. Not user-selectable; entered automatically when a failsafe action escalates to termination.
Multicopter (VEHICLE_TYPE_ROTARY_WING)
Manual/Stabilized Mode (NAVIGATION_STATE_MANUAL)
Manual/Stabilized Mode (NAVIGATION_STATE_STAB)
Acro Mode (NAVIGATION_STATE_ACRO)
Altitude Mode (NAVIGATION_STATE_ALTCTL)
Altitude Cruise Mode (NAVIGATION_STATE_ALTITUDE_CRUISE)
Position Mode (NAVIGATION_STATE_POSCTL)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_position_relaxedmode_req_manual_control
Position Slow Mode (NAVIGATION_STATE_POSITION_SLOW)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_position_relaxedmode_req_manual_control
Hold Mode (NAVIGATION_STATE_AUTO_LOITER)
mode_req_angular_velocitymode_req_attitudemode_req_global_positionmode_req_local_altmode_req_local_positionmode_req_wind_and_flight_time_compliance
Orbit Mode (NAVIGATION_STATE_ORBIT)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_positionmode_req_prevent_armingmode_req_wind_and_flight_time_compliance
Takeoff Mode (NAVIGATION_STATE_AUTO_TAKEOFF)
Descend Mode (NAVIGATION_STATE_DESCEND)
Land Mode (NAVIGATION_STATE_AUTO_LAND)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_position_relaxedmode_req_prevent_arming
Precision Landing (NAVIGATION_STATE_AUTO_PRECLAND)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_positionmode_req_prevent_arming
Return Mode (NAVIGATION_STATE_AUTO_RTL)
mode_req_angular_velocitymode_req_attitudemode_req_global_positionmode_req_home_positionmode_req_local_altmode_req_local_positionmode_req_prevent_arming
Mission Mode (NAVIGATION_STATE_AUTO_MISSION)
mode_req_angular_velocitymode_req_attitudemode_req_global_positionmode_req_local_altmode_req_local_positionmode_req_missionmode_req_wind_and_flight_time_compliance
Follow Me Mode (NAVIGATION_STATE_AUTO_FOLLOW_TARGET)
mode_req_angular_velocitymode_req_attitudemode_req_local_altmode_req_local_positionmode_req_prevent_armingmode_req_wind_and_flight_time_compliance
Offboard Mode (NAVIGATION_STATE_OFFBOARD)
Modes Without a Dedicated Page
The following internal navigation states have no distinct user-facing behaviour or documentation page on this frame type:
- NAVIGATION_STATE_GUIDED_COURSE — Not implemented for multicopters (course-hold is a fixed-wing-only flight task).
- NAVIGATION_STATE_AUTO_VTOL_TAKEOFF — VTOL-specific transition state used for vertical takeoff before transitioning to forward flight; not applicable to plain multicopter frames.
- NAVIGATION_STATE_TERMINATION — Internal flight-termination failsafe state. Not user-selectable; entered automatically when a failsafe action escalates to termination.