Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-10 06:39:25 +08:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

docs(docs): MAV_CMD_NAV_LAND clarifications

Browse Source
This commit is contained in:
Hamish Willee
2026-05-06 17:32:58 +10:00
parent 466c70ec84
commit 2854b55f6b
4 changed files with 47 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/flight_modes_fw/land.md
+16 -4
View File
@@ -2,7 +2,7 @@
<img src="../../assets/site/position_fixed.svg" title="Position estimate required (e.g. GPS)" width="30px" />
The _Land_ flight mode causes the vehicle to descend at the position where the mode was engaged, following a circular path until touchdown.
The _Land_ flight mode causes the vehicle to land at the position where the mode was engaged, following a descending spiral path until touchdown.
After landing, vehicles will disarm after a short timeout (by default).
:::warning
@@ -19,9 +19,8 @@ Where possible, instead use [Return mode](../flight_modes_fw/return.md) with a p
- Flying vehicles can't switch to this mode without valid local position.
- Flying vehicles will failsafe if they lose the position estimate.
- Mode prevents arming (vehicle must be armed when switching to this mode).
- RC control switches can be used to change flight modes on any vehicle.
- RC stick movement is ignored.
- The mode can be triggered using the [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) MAVLink command, or by explicitly switching to Land mode.
- Manual control control switches can be used to change flight modes on any vehicle.
- Manual control stick movement is ignored.
<!-- https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/commander/ModeUtil/mode_requirements.cpp -->
@@ -33,10 +32,23 @@ Land mode causes the vehicle follow a descending circular path (corkscrew) until
When the mode is engaged, the vehicle starts to loiter around the current vehicle position with loiter radius [NAV_LOITER_RAD](#NAV_LOITER_RAD) and begins to descend with a constant descent speed.
The descent speed is calculated using [FW_LND_ANG](#FW_LND_ANG) and the set landing airspeed [FW_LND_AIRSPD](#FW_LND_AIRSPD).
The vehicle will flare if configured to do so (see [Flaring](../flight_modes_fw/mission.md#flaring-roll-out)), and otherwise proceed circling with the constant descent rate until landing is detected.
The flare requires a downward-facing distance sensor (it will only fire if the vehicle's [VehicleLocalPosition.dist_bottom_valid](../msg_docs/VehicleLocalPosition.md#fields) is `true`).
Without one [VehicleGlobalPosition.terrain_alt](../msg_docs/VehicleGlobalPosition.md#fields) falls back to 0 AMSL and the vehicle spirals into the ground.
[Manual nudging](../flight_modes_fw/mission.md#automatic-abort) and [automatic land abort](../flight_modes_fw/mission.md#nudging) are not available in land mode.
### Enabling the Mode
The mode can be selected using a switch or button mapped on a manual controller.
On a GCS you can similarly enable the mode from a **Land** button or by selecting _Land mode_ as the current mode.
Using MAVLink commands:
- [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) switches to this mode and lands at the current position. Latitude, longitude, and altitude information in the command are ingored.
- [MAV_CMD_DO_SET_STANDARD_MODE](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_SET_STANDARD_MODE) with mode set to [MAV_STANDARD_MODE_LAND](https://mavlink.io/en/messages/common.html#MAV_STANDARD_MODE_LAND) switches to land mode.
### Parameters
Land mode behaviour can be configured using the parameters below.
docs/en/flight_modes_fw/mission.md
+11 -9
View File
@@ -31,21 +31,21 @@ At high level all vehicle types behave in the same way when MISSION mode is enga
- If flying the vehicle will loiter.
- If landed the vehicle will "wait".
1. If a mission is stored and PX4 is flying it will execute the [mission/flight plan](../flying/missions.md) from the current step.
2. If a mission is stored and PX4 is flying it will execute the [mission/flight plan](../flying/missions.md) from the current step.
- A takeoff mission item will be treated as a normal waypoint.
1. If a mission is stored and the vehicle is landed it will only takeoff if the active waypoint is a `Takeoff`.
3. If a mission is stored and the vehicle is landed it will only takeoff if the active waypoint is a `Takeoff`.
If configured for catapult launch, the vehicle must also be launched (see [FW Takeoff/Landing in Mission](#mission-takeoff)).
1. If no mission is stored, or if PX4 has finished executing all mission commands:
4. If no mission is stored, or if PX4 has finished executing all mission commands:
- If flying the vehicle will loiter.
- If landed the vehicle will "wait".
1. You can manually change the current mission command by selecting it in _QGroundControl_.
5. You can manually change the current mission command by selecting it in _QGroundControl_.
::: info
If you have a _Jump to item_ command in the mission, moving to another item will **not** reset the loop counter.
One implication is that if you change the current mission command to 1 this will not "fully restart" the mission.
:::
1. The mission will only reset when the vehicle is disarmed or when a new mission is uploaded.
6. The mission will only reset when the vehicle is disarmed or when a new mission is uploaded.
:::tip
To automatically disarm the vehicle after it lands, in _QGroundControl_ go to [Vehicle Setup > Safety](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/safety.html), navigate to _Land Mode Settings_ and check the box labeled _Disarm after_.
@@ -126,10 +126,12 @@ Unless otherwise noted, the implementation is as defined in the MAVLink specific
Mission Items:
- [MAV_CMD_NAV_WAYPOINT](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_WAYPOINT)
- _Param3_ (flythrough) is ignored. Flythrough is always enabled if _param 1_ (time_inside) > 0.
- _Param3_ (flythrough) is ignored.
Flythrough is always enabled if _param 1_ (time_inside) > 0.
- [MAV_CMD_NAV_LOITER_UNLIM](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_UNLIM)
- [MAV_CMD_NAV_LOITER_TIME](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_TIME)
- [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND)
- [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) — defines the endpoint of a [landing sequence](../flight_modes_fw/mission.md#landing-sequence).
- Latitude, longitude, and altitude parameters are all used.
- [MAV_CMD_NAV_TAKEOFF](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_TAKEOFF)
- [MAV_CMD_NAV_LOITER_TO_ALT](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_TO_ALT)
- [MAV_CMD_DO_JUMP](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_JUMP)
@@ -252,7 +254,7 @@ The following sections describe the landing sequence, land abort and nudging, sa
### Landing Sequence
A landing pattern consists of a loiter waypoint ([MAV_CMD_NAV_LOITER_TO_ALT](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_TO_ALT)) followed by a land waypoint ([MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND)).
A landing pattern consists of a waypoint (typically a loiter waypoint: [MAV_CMD_NAV_LOITER_TO_ALT](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_TO_ALT)) followed by a land waypoint ([MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND)).
The positions of the two points define the start and end point of the landing approach, and hence the glide slope for the landing approach.
This pattern results in the following landing sequence:
@@ -323,7 +325,7 @@ Automatic abort logic is additionally available for several conditions, if confi
Available automatic abort criteria may be enabled via bitmask parameter [FW_LND_ABORT](#FW_LND_ABORT).
One example of an automatic abort criteria is the absence of a valid range measurement from a distance sensor.
:::warning
::: warning
Landing without a distance sensor is **strongly** discouraged.
Disabling terrain estimation with [FW_LND_USETER](#FW_LND_USETER) and select bits of [FW_LND_ABORT](#FW_LND_ABORT) will remove the default distance sensor requirement, but consequently falls back to GNSS altitude to determine the flaring altitude, which may be several meters too high or too low, potentially resulting in damage to the airframe.
:::
docs/en/flight_modes_mc/land.md
+12 -3
View File
@@ -12,9 +12,8 @@ The vehicle will disarm shortly after landing (by default).
- Flying vehicles can't switch to this mode without valid local position.
- Flying vehicles will failsafe if they lose the position estimate.
- Mode prevents arming (vehicle must be armed when switching to this mode).
- RC control switches can be used to change flight modes on any vehicle.
- RC stick movement in a multicopter (or VTOL in multicopter mode) will [by default](#COM_RC_OVERRIDE) change the vehicle to [Position mode](../flight_modes_mc/position.md) unless handling a critical battery failsafe.
- The mode can be triggered using the [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) MAVLink command, or by explicitly switching to Land mode.
- Manual control switches can be used to change flight modes on any vehicle.
- Manual stick movement in a multicopter (or VTOL in multicopter mode) will [by default](#COM_RC_OVERRIDE) change the vehicle to [Position mode](../flight_modes_mc/position.md) unless handling a critical battery failsafe.
<!-- https://github.com/PX4/PX4-Autopilot/blob/main/src/modules/commander/ModeUtil/mode_requirements.cpp -->
@@ -27,6 +26,16 @@ The vehicle descends at the rate specified in [MPC_LAND_SPEED](#MPC_LAND_SPEED)
RC stick movement will change the vehicle to [Position mode](../flight_modes_mc/position.md) (by [default](#COM_RC_OVERRIDE)).
### Enabling the Mode
The mode can be selected using a switch or button mapped on a manual controller.
On a GCS you can similarly enable the mode from a **Land** button or by selecting _Land mode_ as the current mode.
Using MAVLink commands:
- [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND) switches to this mode and lands at the current position. Latitude, longitude, and altitude information in the command are ignored.
- [MAV_CMD_DO_SET_STANDARD_MODE](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_SET_STANDARD_MODE) with mode set to [MAV_STANDARD_MODE_LAND](https://mavlink.io/en/messages/common.html#MAV_STANDARD_MODE_LAND) switches to land mode.
### Parameters
Land mode behaviour can be configured using the parameters below.
docs/en/flight_modes_mc/mission.md
+8 -6
View File
@@ -33,24 +33,24 @@ At high level all vehicle types behave in the same way when MISSION mode is enga
- If flying the vehicle will hold.
- If landed the vehicle will "wait".
1. If a mission is stored and PX4 is flying it will execute the [mission/flight plan](../flying/missions.md) from the current step.
2. If a mission is stored and PX4 is flying it will execute the [mission/flight plan](../flying/missions.md) from the current step.
- A `TAKEOFF` item is treated as a normal waypoint.
1. If a mission is stored and PX4 is landed:
3. If a mission is stored and PX4 is landed:
- PX4 will execute the [mission/flight plan](../flying/missions.md).
- If the mission does not have a `TAKEOFF` item then PX4 will fly the vehicle to the minimum altitude before executing the remainder of the flight plan from the current step.
1. If no mission is stored, or if PX4 has finished executing all mission commands:
4. If no mission is stored, or if PX4 has finished executing all mission commands:
- If flying the vehicle will hold.
- If landed the vehicle will "wait".
1. You can manually change the current mission command by selecting it in _QGroundControl_.
5. You can manually change the current mission command by selecting it in _QGroundControl_.
::: info
If you have a _Jump to item_ command in the mission, moving to another item will **not** reset the loop counter.
One implication is that if you change the current mission command to 1 this will not "fully restart" the mission.
:::
1. The mission will only reset when the vehicle is disarmed or when a new mission is uploaded.
6. The mission will only reset when the vehicle is disarmed or when a new mission is uploaded.
:::tip
::: tip
To automatically disarm the vehicle after it lands, in _QGroundControl_ go to [Vehicle Setup > Safety](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/safety.html), navigate to _Land Mode Settings_ and check the box labeled _Disarm after_.
Enter the time to wait after landing before disarming the vehicle.
:::
@@ -131,6 +131,8 @@ Mission Items:
- [MAV_CMD_NAV_LOITER_UNLIM](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_UNLIM)
- [MAV_CMD_NAV_LOITER_TIME](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_TIME)
- [MAV_CMD_NAV_LAND](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LAND)
- Latitude (param5) and longitude (param6) are used (the vehicle will fly to this location at the current altitude and then land).
- Altitude (param7) is not used.
- [MAV_CMD_NAV_TAKEOFF](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_TAKEOFF)
- [MAV_CMD_NAV_LOITER_TO_ALT](https://mavlink.io/en/messages/common.html#MAV_CMD_NAV_LOITER_TO_ALT)
- [MAV_CMD_DO_JUMP](https://mavlink.io/en/messages/common.html#MAV_CMD_DO_JUMP)