From eeaf1d7959716af6736b464ff6ea286632049bf5 Mon Sep 17 00:00:00 2001 From: chfriedrich98 <125505139+chfriedrich98@users.noreply.github.com> Date: Wed, 20 Aug 2025 06:12:31 +0200 Subject: [PATCH] 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 --- docs/en/config_rover/basic_setup.md | 67 ++++++++++++++++++++----- docs/en/config_rover/velocity_tuning.md | 2 +- 2 files changed, 56 insertions(+), 13 deletions(-) diff --git a/docs/en/config_rover/basic_setup.md b/docs/en/config_rover/basic_setup.md index 735538168e..328e04950c 100644 --- 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 | [RO_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RO_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | $m/s$ | | [RO_ACCEL_LIM](../advanced_config/parameter_reference.md#RO_ACCEL_LIM) | (Optional) Maximum allowed acceleration | $m/s^2$ | | [RO_DECEL_LIM](../advanced_config/parameter_reference.md#RO_DECEL_LIM) | (Optional) Maximum allowed deceleration | $m/s^2$ | +| [RO_YAW_EXPO](../advanced_config/parameter_reference.md#RO_YAW_EXPO) | (Optional) Yaw rate expo factor | $-$ | +| [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 | -| ----------------------------------------------------------------------------------------------------- | ----------- | ---- | -| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | $m$ | +| [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 | -| ----------------------------------------------------------------------------------------------------- | ----------- | ---- | -| [RM_WHEEL_TRACK](../advanced_config/parameter_reference.md#RM_WHEEL_TRACK) | Wheel track | m | +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---- | +| [RM_WHEEL_TRACK](../advanced_config/parameter_reference.md#RM_WHEEL_TRACK) | Wheel track | $m$ | +| [RM_YAW_STK_GAIN](../advanced_config/parameter_reference.md#RM_YAW_STK_GAIN) | (Optional) Yaw stick gain for Manual mode | $-$ | diff --git a/docs/en/config_rover/velocity_tuning.md b/docs/en/config_rover/velocity_tuning.md index e3969ad102..04323e7413 100644 --- 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.