docs: new rover stick input scaling parameters (#25427)

* docs: new rover stick input scaling parameters * docs: clarify rover basic setup * Update docs/en/config_rover/basic_setup.md * Minor subedit --------- Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
2025-12-09 15:58:31 +08:00 · 2025-08-20 06:12:31 +02:00
parent 35ff853f76
commit eeaf1d7959
2 changed files with 56 additions and 13 deletions
--- a/docs/en/config_rover/basic_setup.md
+++ b/docs/en/config_rover/basic_setup.md
@@ -26,10 +26,18 @@

 That is the minimum setup to use the rover in [Manual mode](../flight_modes_rover/manual.md#manual-mode).

+::: info
+The rest of the tuning on this page is not mandatory for [Manual mode](../flight_modes_rover/manual.md#manual-mode), but it will have an effect on the behaviour of the rover.
+:::
+
+::: warning
+Do not skip the rest of this setup if you intend to use more sophisticated modes!
+All parameters will be mandatory for all subsequent modes, except those tagged as `(Optional)`.
+:::
+
 ## Geometric Parameters

-Manual mode is also affected by (optional) acceleration/deceleration limits set using the geometric described below.
-These limits are mandatory for all other modes.
+First, we set up the geometric parameters of the rover:

 ![Geometric parameters](../../assets/config/rover/geometric_parameters.png)

@@ -41,7 +49,7 @@ Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and
 2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle.
 3. (Optional) [RA_STR_RATE_LIM](#RA_STR_RATE_LIM) [deg/s]: Maximum steering rate you want to allow for your rover.

-   :::tip
+   ::: tip
   This value depends on your rover and use case.
   For bigger rovers there might be a mechanical limit that is easy to identify by steering the rover at a standstill and increasing
   [RA_STR_RATE_LIM](#RA_STR_RATE_LIM) until you observe the steering rate to no longer be limited by the parameter.
@@ -49,7 +57,7 @@ Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and
   Increase the parameter until you reach the maximum steering rate you are comfortable with.
   :::

-   :::warning
+   ::: warning
   A low maximum steering rate makes the rover worse at tracking steering setpoints, which can lead to a poor performance in the subsequent modes.
   :::

@@ -79,14 +87,12 @@ Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and
   This may or may not be appropriate for your vehicle and use case.

   One approach to determine an appropriate value is:
-
   1. From a standstill, give the rover full throttle until it reaches the maximum speed.
   2. Disarm the rover and plot the `measured_speed_body_x` from [RoverVelocityStatus](../msg_docs/RoverVelocityStatus.md).
   3. Divide the maximum speed by the time it took to reach it and set this as the value for [RO_ACCEL_LIM](#RO_ACCEL_LIM).

   Some RC rovers have enough torque to lift up if the maximum acceleration is not limited.
   If that is the case:
-
   1. Set [RO_ACCEL_LIM](#RO_ACCEL_LIM) to a low value, give the rover full throttle from a standstill and observe its behaviour.
   2. Increase [RO_ACCEL_LIM](#RO_ACCEL_LIM) until the rover starts to lift up during the acceleration.
   3. Set [RO_ACCEL_LIM](#RO_ACCEL_LIM) to the highest value that does not cause the rover to lift up.
@@ -102,6 +108,39 @@ Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and
   This parameter is also used for the calculation of the speed setpoint in modes that are [position controlled](position_tuning.md).
   :::

+## (Optional) Stick Input Mapping
+
+Input shaping can be used to adjust the default linear mapping from stick inputs $\in [-1, 1]$ to normalized setpoints $\in [-1, 1]$. Applying this specifically to the steering input, can provide a smoother driving experience, by enabling the user to make small adjustments when the stick is close to the center, but still send large inputs when moving them to the edges.
+We provide this input shaping through the super exponential function:
+
+$$
+\delta = \frac{(f \cdot x^3 + x(1-f)) \cdot (1-g)}{1-g \cdot |x|}
+$$
+
+with:
+
+- $\delta \in [-1, 1]=$ Normalized steering setpoint.
+- $x \in [-1, 1]=$ Normalized stick input.
+- $f=$ [RO_YAW_EXPO](#RO_YAW_EXPO): `0` Purely linear input curve, `1` Purely cubic input curve.
+- $g=$ [RO_YAW_SUPEXPO](#RO_YAW_SUPEXPO): `0` Pure Expo function, `0.7` reasonable shape enhancement for intuitive stick feel, `0.95` very strong bent input curve only near maxima have effect.
+
+In [Manual mode](../flight_modes_rover/manual.md#manual-mode) we can additionally scale $\delta$ with an additional parameter $r$:
+
+- Differential Rover: $r=$ [RD_YAW_STK_GAIN](#RD_YAW_STK_GAIN), which enables adjusting the slope of the input mapping. This leads to a normalized steering input $\hat{\delta} = \delta \cdot r \in$ [-[RD_YAW_STK_GAIN](#RD_YAW_STK_GAIN), [RD_YAW_STK_GAIN](#RD_YAW_STK_GAIN)].
+- Mecanum Rover: $r=$ [RM_YAW_STK_GAIN](#RM_YAW_STK_GAIN), which enables adjusting the slope of the input mapping. This leads to a normalized steering input $\hat{\delta} = \delta \cdot r \in$ [-[RM_YAW_STK_GAIN](#RM_YAW_STK_GAIN), [RM_YAW_STK_GAIN](#RM_YAW_STK_GAIN)].
+
+This scaling is useful to limit the normalized steering setpoint, if it is too aggresive for your rover in manual mode.
+
+You can experiment with the relationships graphically using the [PX4 SuperExpo Rover calculator](https://www.desmos.com/calculator/gwm8lrlanx).
+
+::: info
+In [Acro](../flight_modes_rover/manual.md#acro-mode), [Stabilized](../flight_modes_rover/manual.md#stabilized-mode) and [Position](../flight_modes_rover/manual.md#position-mode) Mode, $\delta$ is instead scaled by $r=$ [RO_YAW_RATE_LIM](../advanced_config/parameter_reference.md#RO_MAX_THR_SPEED) for all rovers. This leads to a yaw rate setpoint $\dot{\psi} = \delta \cdot r \in$ [-[RO_YAW_RATE_LIM](../advanced_config/parameter_reference.md#RO_MAX_THR_SPEED), [RO_YAW_RATE_LIM](../advanced_config/parameter_reference.md#RO_MAX_THR_SPEED)]. This parameter is setup during [rate tuning](rate_tuning.md).
+:::
+
+::: info
+The input shaping through [RO_YAW_EXPO](#RO_YAW_EXPO) and [RO_YAW_SUPEXPO](#RO_YAW_SUPEXPO) applies for all manual modes, while [RD_YAW_STK_GAIN](#RD_YAW_STK_GAIN)/[RM_YAW_STK_GAIN](#RM_YAW_STK_GAIN) only affects full manual mode.
+:::
+
 You can now continue the configuration process with [rate tuning](rate_tuning.md).

 ## Parameter Overview
@@ -111,6 +150,8 @@ You can now continue the configuration process with [rate tuning](rate_tuning.md
 | <a id="RO_MAX_THR_SPEED"></a>[RO_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RO_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | $m/s$   |
 | <a id="RO_ACCEL_LIM"></a>[RO_ACCEL_LIM](../advanced_config/parameter_reference.md#RO_ACCEL_LIM)             | (Optional) Maximum allowed acceleration    | $m/s^2$ |
 | <a id="RO_DECEL_LIM"></a>[RO_DECEL_LIM](../advanced_config/parameter_reference.md#RO_DECEL_LIM)             | (Optional) Maximum allowed deceleration    | $m/s^2$ |
+| <a id="RO_YAW_EXPO"></a>[RO_YAW_EXPO](../advanced_config/parameter_reference.md#RO_YAW_EXPO)                | (Optional) Yaw rate expo factor            | $-$     |
+| <a id="RO_YAW_SUPEXPO"></a>[RO_YAW_SUPEXPO](../advanced_config/parameter_reference.md#RO_YAW_SUPEXPO)       | (Optional) Yaw rate super expo factor      | $-$     |

 ### Ackermann Specific

@@ -122,12 +163,14 @@ You can now continue the configuration process with [rate tuning](rate_tuning.md

 ### Differential Specific

-| Parameter                                                                                             | Description | Unit |
-| ----------------------------------------------------------------------------------------------------- | ----------- | ---- |
-| <a id="RD_WHEEL_TRACK"></a>[RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m    |
+| Parameter                                                                                                | Description                               | Unit |
+| -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---- |
+| <a id="RD_WHEEL_TRACK"></a>[RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK)    | Wheel track                               | $m$  |
+| <a id="RD_YAW_STK_GAIN"></a>[RD_YAW_STK_GAIN](../advanced_config/parameter_reference.md#RD_YAW_STK_GAIN) | (Optional) Yaw stick gain for Manual mode | $-$  |

 ### Mecanum Specific

-| Parameter                                                                                             | Description | Unit |
-| ----------------------------------------------------------------------------------------------------- | ----------- | ---- |
-| <a id="RM_WHEEL_TRACK"></a>[RM_WHEEL_TRACK](../advanced_config/parameter_reference.md#RM_WHEEL_TRACK) | Wheel track | m    |
+| Parameter                                                                                                | Description                               | Unit |
+| -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---- |
+| <a id="RM_WHEEL_TRACK"></a>[RM_WHEEL_TRACK](../advanced_config/parameter_reference.md#RM_WHEEL_TRACK)    | Wheel track                               | $m$  |
+| <a id="RM_YAW_STK_GAIN"></a>[RM_YAW_STK_GAIN](../advanced_config/parameter_reference.md#RM_YAW_STK_GAIN) | (Optional) Yaw stick gain for Manual mode | $-$  |
--- a/docs/en/config_rover/velocity_tuning.md
+++ b/docs/en/config_rover/velocity_tuning.md
@@ -86,7 +86,7 @@ These steps are only necessary if you are tuning/want to unlock the manual [Posi

 The rover is now ready to drive in [Position mode](../flight_modes_rover/manual.md#position-mode) and the configuration can be continued with [position tuning](position_tuning.md).

-## Attitude Controller Structure (Info Only)
+## Velocity Controller Structure (Info Only)

 This section provides additional information for developers and people with experience in control system design.