docs: Manual control updates to reflect prioritised selection (#25835)

2026-04-14 10:07:39 +08:00 · 2026-02-25 10:43:19 +11:00 · 2026-02-25 10:43:19 +11:00 · 4226b7d4ec
commit 4226b7d4ec
parent 04f4ca8966
10 changed files with 100 additions and 35 deletions
--- a/docs/en/SUMMARY.md
+++ b/docs/en/SUMMARY.md
@ -328,10 +328,11 @@
      - [Vertiq Motor/ESC Modules](peripherals/vertiq.md)
      - [VESC Project ESCs](peripherals/vesc.md)
      - [Zubax Telega ESCs](dronecan/zubax_telega.md)
-  - [Radio Control (RC)](getting_started/rc_transmitter_receiver.md)
-    - [Radio Setup](config/radio.md)
-    - [Flight Modes](config/flight_mode.md)
-  - [Joysticks](config/joystick.md)
+  - [Manual Control](config/manual_control.md)
+    - [Radio Control (RC)](getting_started/rc_transmitter_receiver.md)
+      - [Radio Setup](config/radio.md)
+      - [Flight Modes](config/flight_mode.md)
+    - [Joysticks](config/joystick.md)
  - [Data Links](data_links/index.md)
    - [MAVLink Telemetry (OSD/GCS)](peripherals/mavlink_peripherals.md)
    - [Telemetry Radios](telemetry/index.md)
--- a/docs/en/complete_vehicles_mc/crazyflie2.md
+++ b/docs/en/complete_vehicles_mc/crazyflie2.md
@ -212,13 +212,17 @@ make venv
 :::

 ::: info
-To use Joystick, set `COM_RC_IN_MODE` in QGroundControl to "Joystick/No RC Checks".
-Calibrate the Joystick and set the Joystick message frequency in QGroundControl to any value between 5 to 14 Hz (10 Hz is recommended).
-To be able to set the frequency, the advanced option should be enabled.
-This is the rate at which Joystick commands are sent from QGroundControl to Crazyflie 2.0 (to do this, you will need to follow the instructions [here](https://github.com/mavlink/qgroundcontrol) to obtain the latest QGroundControl source code (master) and build it).
-:::
+To use a [Joystick](../config/joystick.md):

-![](../../assets/hardware/joystick-message-frequency.png)
+- Make sure you're using a [`COM_RC_IN_MODE` that allows Joystick](../config/manual_control.md#px4-configuration).
+- Calibrate the Joystick and set the Joystick message frequency in QGroundControl if needed (25 Hz is the default).
+  To be able to set the frequency, the advanced option should be enabled.
+
+  ![QGC UI for setting message frequency](../../assets/hardware/joystick-message-frequency.png)
+
+  This is the rate at which Joystick commands are sent from QGroundControl to Crazyflie 2.0 (to do this, you will need to follow the instructions [here](https://github.com/mavlink/qgroundcontrol) to obtain the latest QGroundControl source code (master) and build it).
+
+:::

 ## Hardware Setup

--- a/docs/en/config/joystick.md
+++ b/docs/en/config/joystick.md
@ -23,8 +23,7 @@ Information about how to set up a joystick is covered in: [QGroundControl > Joys
 In summary:

 - Open _QGroundControl_
- Set the parameter [COM_RC_IN_MODE=1](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) - `Joystick`
-  - See [Parameters](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/parameters.html) for information about setting parameters
-  - Setting the parameter to `2` or `3` also enables Joystick under some circumstances.
+- [Enable a `COM_RC_IN_MODE` mode that allows Joystick](../config/manual_control.md#px4-configuration).
+  The default `RC or MAVLink keep first` should work if you plan to only have a Joystick connected.
 - Connect the joystick
 - Configure the connected joystick in: **Vehicle Setup > Joystick**.
--- a/docs/en/config/manual_control.md
+++ b/docs/en/config/manual_control.md
@ -0,0 +1,58 @@
+# Manual Control
+
+Pilots can control a vehicle manually using either a [Radio Control (RC) System](../getting_started/rc_transmitter_receiver.md) or a [Joystick/Gamepad](../config/joystick.md) controller connected via QGroundControl.
+PX4 also supports using RC and/or multiple Joysticks, with fallback from one type to the other.
+
+![Taranis X9D Transmitter](../../assets/hardware/transmitters/frsky_taranis_x9d_transmitter.jpg) <img src="../../assets/peripherals/joystick/micronav.jpg" alt="Photo of MicroNav, a ground controller with integrated joysticks" width="400px">
+
+## Overview
+
+_Joystick_ setups use QGroundControl to encode the control information from a "standard" computer gaming joystick into [MAVLink messages](https://mavlink.io/en/services/manual_control.html) that are sent to the vehicle over the (shared) telemetry radio channel.
+They are often used in integrated GCS/manual control systems because it is cheaper and easier to integrate a joystick than a separate radio system.
+
+Joysticks are suitable for most applications provided your telemetry channel has a high enough bandwidth/low latency.
+They are perfect for flying the PX4 simulator, because you can plug them directly into your ground control computer and start flying.
+
+_RC systems_ use a dedicated ground-based radio transmitter and vehicle-based receiver for sending control information.
+They offer lower latency than Joysticks, and are very highly recommended when first tuning/testing a new frame design, when flying racers/acrobatically, and in other cases where low latency is important.
+They can also be useful as a robust backup link for safety.
+Note RC systems usually require significantly more configuration and calibration, much of which may be brand or model-specific.
+
+::: info
+PX4 does not _require_ a manual control system for autonomous flight modes.
+:::
+
+## PX4 Configuration
+
+::: tip
+This section explains how to configure PX4 to use and prioritise various manual control sources (other configuration is covered in the guides for each type of manual control).
+:::
+
+If you only have one manual control system, either RC or Joystick, then by default no manual control selection is required.
+In this case PX4 locks to the first valid manual control source it detects and uses that source until the vehicle is rebooted.
+
+If you have multiple control sources, such as an RC system and/or one or more Joysticks, then you can use the [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) parameter to determine which source is active, specifying selection priorities and fallback behavior ([parameters can be set](../advanced_config/parameters.md#finding-a-parameter) using QGC):
+
+- `0`: RC only.
+- `1`: MAVLink only.
+- `2`: RC or MAVLink with fallback (switches if current source becomes invalid).
+- `3`: RC or MAVLink keep first (locks to the first valid source until reboot).
+- `4`: Disable manual control (ignores all sources).
+- `5`: RC priority, then MAVLink (lower instance before higher) — `RC > MAVLink 1 > MAVLink 2`
+- `6`: MAVLink priority (lower instance before higher), then RC — `MAVLink 1 > MAVLink 2 > RC`
+- `7`: RC priority, then MAVLink (higher instance before lower) — `RC > MAVLink 2 > MAVLink 1`
+- `8`: MAVLink priority (higher instance before lower), then RC — `MAVLink 2 > MAVLink 1 > RC`
+
+The [MAVLink instance](../peripherals/mavlink_peripherals.md#mavlink-instances) refers to an instance assigned to a serial port, such as [MAV_0_CONFIG](../advanced_config/parameter_reference.md#MAV_0_CONFIG).
+
+Notes:
+
+- RC checks are run for any option that uses RC (so not for `MAVLink only` or `Disable manual control`).
+- When using priority sources, sources are evaluated as soon as they become valid and may trigger an immediate switch (if higher priority than the currently active source).
+- A [Manual Control Loss Failsafe](../config/safety.md#manual-control-loss-failsafe) is triggered when none of the manual control inputs allowed by the `COM_RC_IN_MODE` mode are available for a time that is greater than the RC Loss Timeout.
+  As long as there is a fallback input source available, the failsafe is not triggered.
+
+## See Also
+
+- [Radio Control (RC)](../getting_started/rc_transmitter_receiver.md)
+- [Joysticks](../config/joystick.md)
--- a/docs/en/config/radio.md
+++ b/docs/en/config/radio.md
@ -1,10 +1,12 @@
 # Radio Control (RC) Setup

-The _Radio Setup_ screen is used to configure the mapping of your RC controller's main attitude control sticks (roll, pitch, yaw, throttle) to channels, and to calibrate the minimum, maximum, trim and reverse settings for all other transmitter controls/RC channels.
+The _Radio Setup_ screen is used to configure the mapping of your [RC controller's](../getting_started/rc_transmitter_receiver.md) main attitude control sticks (roll, pitch, yaw, throttle) to channels, and to calibrate the minimum, maximum, trim and reverse settings for all other transmitter controls/RC channels.

 ::: info
-A [Joystick](../config/joystick.md) can be used instead of RC for manual control.
-The [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) parameter [can be set](../advanced_config/parameters.md) to define what kind of manual controller(s) are enabled.
+A [Joystick](../config/joystick.md) can also be used for [Manual Control](../config/manual_control.md).
+
+By default PX4 will latch the first valid controller it discovers and use it until the vehicle reboots.
+If you have multiple controllers and you want to define their priority see [Manual Control > PX4 Configuration](../config/manual_control.md#px4-configuration).
 :::

 ## Binding the Receiver
--- a/docs/en/config/safety.md
+++ b/docs/en/config/safety.md
@ -111,19 +111,17 @@ The settings and underlying parameters are shown below.

 ## Manual Control Loss Failsafe

-The manual control loss failsafe may be triggered if the connection to the [RC transmitter](../getting_started/rc_transmitter_receiver.md) or [joystick](../config/joystick.md) is lost, and there is no fallback.
-If using an [RC transmitter](../getting_started/rc_transmitter_receiver.md) this is triggered if the RC [transmitter link is lost](../getting_started/rc_transmitter_receiver.md#set-signal-loss-behaviour).
-If using [joysticks](../config/joystick.md) connected over a MAVLink data link, this is triggered if the joysticks are disconnected or the data link is lost.
-
-::: info
-PX4 and the receiver may also need to be configured in order to _detect RC loss_: [Radio Setup > RC Loss Detection](../config/radio.md#rc-loss-detection).
-:::
+A [Manual Control Loss Failsafe](../config/safety.md#manual-control-loss-failsafe) is triggered after a [manual control loss timeout](#COM_RC_LOSS_T) in which none of the configured [Manual Controllers](../config/manual_control.md) are available.

 ![Safety - RC Loss (QGC)](../../assets/qgc/setup/safety/safety_rc_loss.png)

 The QGCroundControl Safety UI allows you to set the [failsafe action](#failsafe-actions) and [manual control loss timeout](#COM_RC_LOSS_T).
 Users that want to disable this failsafe in specific modes can do so using the parameter [COM_RCL_EXCEPT](#COM_RCL_EXCEPT).

+::: info
+PX4 and the receiver may also need to be configured in order to _detect RC loss_: [Radio Setup > RC Loss Detection](../config/radio.md#rc-loss-detection).
+:::
+
 Additional (and underlying) parameter settings are shown below.

 | Parameter                                                                                             | Setting                     | Description                                                                                                                                                                                                                                                                                                                                                                                              |
--- a/docs/en/flight_modes/offboard.md
+++ b/docs/en/flight_modes/offboard.md
@ -11,7 +11,7 @@ PX4 enables offboard control only after receiving the signal for more than a sec
 ::: info

 - This mode requires position or pose/attitude information - e.g. GPS, optical flow, visual-inertial odometry, mocap, etc.
- RC control is disabled except to change modes (you can also fly without any manual controller at all by setting the parameter [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) to 4: Stick input disabled).
+- Manual control is disabled except to change modes (you can also fly without any manual controller at all by setting the parameter [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) to `4: Disable manual control`).
 - The vehicle must be already be receiving a stream of MAVLink setpoint messages or ROS 2 [OffboardControlMode](../msg_docs/OffboardControlMode.md) messages before arming in offboard mode or switching to offboard mode when flying.
 - The vehicle will exit offboard mode if MAVLink setpoint messages or `OffboardControlMode` are not received at a rate of > 2Hz.
 - Not all coordinate frames and field values allowed by MAVLink are supported for all setpoint messages and vehicles.
--- a/docs/en/getting_started/rc_transmitter_receiver.md
+++ b/docs/en/getting_started/rc_transmitter_receiver.md
@ -3,13 +3,15 @@
 A Radio Control (RC) system can be used to _manually_ control your vehicle from a handheld RC controller.
 This topic provides an overview of how RC works, how to choose an appropriate radio system for your vehicle, and how to connect it to your flight controller.

-:::tip
-PX4 can also be manually controlled using a [Joystick](../config/joystick.md) or gamepad-like controller: this is different to an RC system!
-The [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) parameter [can be set](../advanced_config/parameters.md) to choose whether RC (default), Joystick, both, or neither, are enabled.
+::: info
+PX4 does not require a manual control system for autonomous flight modes.
 :::

-::: info
-PX4 does not require a remote control system for autonomous flight modes.
+:::tip
+PX4 can also be [manually controlled](../config/manual_control.md) using a [Joystick](../config/joystick.md) or gamepad-like controller.
+
+By default PX4 will latch the first valid controller it discovers and use it until the vehicle reboots.
+If you have multiple controllers and you want to define their priority see [Manual Control > PX4 Configuration](../config/manual_control.md#px4-configuration).
 :::

 ## How do RC Systems Work?
--- a/docs/en/releases/main.md
+++ b/docs/en/releases/main.md
@ -41,6 +41,7 @@ Please continue reading for [upgrade instructions](#upgrade-guide).
 ### Common

 - [QGroundControl Bootloader Update](../advanced_config/bootloader_update.md#qgc-bootloader-update-sys-bl-update) via the [SYS_BL_UPDATE](../advanced_config/parameter_reference.md#SYS_BL_UPDATE) parameter has been re-enabled after being broken for a number of releases. ([PX4-Autopilot#25032: build: romf: fix generation of rc.board_bootloader_upgrade](https://github.com/PX4/PX4-Autopilot/pull/25032)).
+- [Feature: Allow prioritization of manual control inputs based on their instance number in ascending or descending order](../config/manual_control.md#px4-configuration). ([PX4-Autopilot#25602: Ascending and descending manual control input priorities](https://github.com/PX4/PX4-Autopilot/pull/25602)).

 ### Control

--- a/docs/en/simulation/hitl.md
+++ b/docs/en/simulation/hitl.md
@ -101,16 +101,16 @@ make px4_fmu-v6x boardconfig
   2. Select a [compatible airframe](#compatible_airframe) you want to test.
      Then click **Apply and Restart** on top-right of the _Airframe Setup_ page.

-3. Calibrate your RC or Joystick, if needed.
+3. Calibrate your [Manual Controller](../config/manual_control.md) (RC or Joystick), if needed.
 4. Setup UDP
   1. Under the _General_ tab of the settings menu, uncheck all _AutoConnect_ boxes except for **UDP**.

      ![QGC Auto-connect settings for HITL](../../assets/gcs/qgc_hitl_autoconnect.png)

-5. (Optional) Configure Joystick and Failsafe.
-   Set the following [parameters](../advanced_config/parameters.md) in order to use a joystick instead of an RC remote control transmitter:
-   - [COM_RC_IN_MODE](../advanced_config/parameter_reference.md#COM_RC_IN_MODE) to "Joystick/No RC Checks". This allows joystick input and disables RC input checks.
-   - [NAV_RCL_ACT](../advanced_config/parameter_reference.md#NAV_RCL_ACT) to "Disabled". This ensures that no RC failsafe actions interfere when not running HITL with a radio control.
+5. (Optional) Configure your manual controller priority and failsafe:
+   - [Enable a mode in `COM_RC_IN_MODE` that enables and prioritises the controllers you want to use](../config/manual_control.md#px4-configuration).
+     The default `RC or MAVLink keep first` should work if you plan to only have a Joystick (no RC).
+   - You can set [NAV_RCL_ACT](../advanced_config/parameter_reference.md#NAV_RCL_ACT) to disable manual control loss failsafe while flying in a simulation.

   :::tip
   The _QGroundControl User Guide_ also has instructions on [Joystick](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/joystick.html) and [Virtual Joystick](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/settings_view/virtual_joystick.html) setup.
@ -131,7 +131,7 @@ Make sure _QGroundControl_ is not running!
 1. Build PX4 with [Gazebo Classic](../sim_gazebo_classic/index.md) (in order to build the Gazebo Classic plugins).

   ```sh
-   cd <Firmware_clone>
+   cd <PX4-Autopilot clone>
   DONT_RUN=1 make px4_sitl_default gazebo-classic
   ```