diff --git a/docs/en/flight_modes_fw/guided_course.md b/docs/en/flight_modes_fw/guided_course.md new file mode 100644 index 0000000000..3dabbed11f --- /dev/null +++ b/docs/en/flight_modes_fw/guided_course.md @@ -0,0 +1,71 @@ +# Guided Course Mode (Fixed-Wing) + + + +_Guided Course mode_ maintains a constant ground track (course), altitude, and airspeed without any manual stick input. +The operator controls the vehicle entirely via GCS commands, making it the guided equivalent of [Position mode](../flight_modes_fw/position.md). + +:::tip +This mode is suited to situations where an operator wants to guide a fixed-wing vehicle from a GCS without manual control. +::: + +::: info + +- Requires a horizontal velocity estimate (e.g. GPS/dead-reckoning). Course commands will be rejected if the velocity estimate is unavailable. +- RC stick movement is ignored. + + + +::: + +## Overview + +On activation, the vehicle captures its current velocity vector as the initial course bearing and holds altitude and airspeed from the moment of activation. +The vehicle then flies that course indefinitely until the operator issues a new command. + +There is no waypoint sequencing or autonomous path planning: the GCS guides the vehicle in real time by sending individual commands. + +## In-flight commands + +The following commands are accepted while in Guided Course mode: + +| Command | Effect | +|---------|--------| +| `MAV_CMD_DO_CHANGE_COURSE` | Set a new course bearing (degrees, 0 = north). Rejected if horizontal velocity estimate is unavailable. | +| `MAV_CMD_DO_CHANGE_ALTITUDE` | Set a new target altitude (AMSL, metres). | +| `MAV_CMD_DO_REPOSITION` | Set a new target altitude via param7. | +| `MAV_CMD_DO_CHANGE_SPEED` | Set a new equivalent airspeed via param2 (m/s). If param2 ≤ 0, the default cruise speed is restored. | + + +## Technical Description + +The navigator mode (`course.cpp`) sets a position setpoint with `course` (ground track bearing) and `alt` fields populated, and `yaw = NAN`. + +The fixed-wing mode manager (`FixedWingModeManager`) detects the finite `course` field and bypasses normal waypoint sequencing, calling `navigateBearing()` from the directional guidance library to compute lateral acceleration and course setpoints. +Longitudinal control targets the altitude and airspeed from the setpoint. + +## Failsafe Behaviour + +Guided Course is classified as an `AUTO` mode for failsafe purposes. +The following failsafe exception parameters apply: + +| Parameter | Bit | Effect when set | +|-----------|-----|-----------------| +| [COM_RCL_EXCEPT](../advanced_config/parameter_reference.md#COM_RCL_EXCEPT) | 1 (Auto modes) | RC loss does not trigger a failsafe in this mode. | +| [COM_DLL_EXCEPT](../advanced_config/parameter_reference.md#COM_DLL_EXCEPT) | 1 (Auto modes) | GCS connection loss does not trigger a failsafe. | + +:::warning +Since Guided Course is driven entirely by GCS commands, operators should carefully consider the datalink loss failsafe setting (`COM_DLL_EXCEPT` bit 1). +If the GCS link drops, the vehicle will continue on its last commanded course indefinitely. +It is strongly recommended to either leave the datalink failsafe active or ensure a secondary safety mechanism (e.g. geofence, battery failsafe) is in place. +::: + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| [FW_AIRSPD_TRIM](../advanced_config/parameter_reference.md#FW_AIRSPD_TRIM) | Default cruise airspeed used on activation and when `MAV_CMD_DO_CHANGE_SPEED` is sent with value ≤ 0. | +| [FW_AIRSPD_MIN](../advanced_config/parameter_reference.md#FW_AIRSPD_MIN) | Minimum airspeed. Commanded airspeed is clamped to this value. | +| [FW_AIRSPD_MAX](../advanced_config/parameter_reference.md#FW_AIRSPD_MAX) | Maximum airspeed. Commanded airspeed is clamped to this value. | +| [COM_RCL_EXCEPT](../advanced_config/parameter_reference.md#COM_RCL_EXCEPT) | RC loss failsafe exceptions bitmask. Bit 1 covers all auto modes including Guided Course. | +| [COM_DLL_EXCEPT](../advanced_config/parameter_reference.md#COM_DLL_EXCEPT) | Datalink loss failsafe exceptions bitmask. Bit 1 covers all auto modes including Guided Course. | diff --git a/docs/en/flight_modes_fw/index.md b/docs/en/flight_modes_fw/index.md index 74a7fe66f0..ca77a42e41 100644 --- a/docs/en/flight_modes_fw/index.md +++ b/docs/en/flight_modes_fw/index.md @@ -39,6 +39,8 @@ Airspeed is actively controlled if an airspeed sensor is installed in any autono - [Hold](../flight_modes_fw/hold.md) — Vehicle circles around the GPS hold position at the current altitude. The mode can be used to pause a mission or to help regain control of a vehicle in an emergency. It can be activated with a pre-programmed RC switch or the QGroundControl Pause button. +- [Guided Course](../flight_modes_fw/guided_course.md) — Vehicle maintains a constant ground track, altitude, and airspeed. + The operator commands course, altitude, and airspeed changes in real time from the GCS. No manual stick input is required. - [Return](../flight_modes_fw/return.md) — Vehicle flies a clear path to land at a safe location. By default the destination is a mission landing pattern. The mode may be activated manually (via a pre-programmed RC switch) or automatically (i.e. in the event of a failsafe being triggered).