From aaffec9d5b07f2b68f0f05e3c057fa4cd0764d4c Mon Sep 17 00:00:00 2001 From: PX4 Build Bot Date: Wed, 20 Nov 2024 15:16:39 +1100 Subject: [PATCH] New Crowdin updates (#3462) * New translations summary.md (German) * New translations summary.md (Japanese) * New translations summary.md (Korean) * New translations summary.md (Russian) * New translations summary.md (Turkish) * New translations summary.md (Ukrainian) * New translations summary.md (Chinese Simplified) * New translations index.md (German) * New translations index.md (Japanese) * New translations index.md (Korean) * New translations index.md (Russian) * New translations index.md (Turkish) * New translations index.md (Ukrainian) * New translations index.md (Chinese Simplified) * New translations main.md (German) * New translations main.md (Japanese) * New translations main.md (Korean) * New translations main.md (Russian) * New translations main.md (Turkish) * New translations main.md (Ukrainian) * New translations main.md (Chinese Simplified) * New translations ackermann.md (German) * New translations differential.md (German) * New translations ackermann.md (Japanese) * New translations differential.md (Japanese) * New translations ackermann.md (Korean) * New translations differential.md (Korean) * New translations ackermann.md (Russian) * New translations differential.md (Russian) * New translations ackermann.md (Turkish) * New translations differential.md (Turkish) * New translations ackermann.md (Ukrainian) * New translations differential.md (Ukrainian) * New translations ackermann.md (Chinese Simplified) * New translations differential.md (Chinese Simplified) * New translations ackermann.md (German) * New translations differential.md (German) * New translations ackermann.md (German) * New translations differential.md (German) * New translations ackermann.md (Japanese) * New translations differential.md (Japanese) * New translations ackermann.md (Japanese) * New translations differential.md (Japanese) * New translations ackermann.md (Korean) * New translations differential.md (Korean) * New translations ackermann.md (Korean) * New translations differential.md (Korean) * New translations ackermann.md (Russian) * New translations differential.md (Russian) * New translations ackermann.md (Russian) * New translations differential.md (Russian) * New translations ackermann.md (Turkish) * New translations differential.md (Turkish) * New translations ackermann.md (Turkish) * New translations differential.md (Turkish) * New translations ackermann.md (Ukrainian) * New translations differential.md (Ukrainian) * New translations ackermann.md (Ukrainian) * New translations differential.md (Ukrainian) * New translations ackermann.md (Chinese Simplified) * New translations differential.md (Chinese Simplified) * New translations ackermann.md (Chinese Simplified) * New translations differential.md (Chinese Simplified) --- de/SUMMARY.md | 10 +- de/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ de/config_rover/differential.md | 314 +++++++++++++++++++ de/flight_modes_rover/ackermann.md | 94 +++++- de/flight_modes_rover/differential.md | 4 +- de/frames_rover/ackermann.md | 14 + de/frames_rover/differential.md | 11 + de/frames_rover/index.md | 15 +- de/releases/main.md | 12 +- ja/SUMMARY.md | 10 +- ja/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ ja/config_rover/differential.md | 314 +++++++++++++++++++ ja/flight_modes_rover/ackermann.md | 94 +++++- ja/flight_modes_rover/differential.md | 4 +- ja/frames_rover/ackermann.md | 14 + ja/frames_rover/differential.md | 11 + ja/frames_rover/index.md | 15 +- ja/releases/main.md | 12 +- ko/SUMMARY.md | 10 +- ko/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ ko/config_rover/differential.md | 314 +++++++++++++++++++ ko/flight_modes_rover/ackermann.md | 94 +++++- ko/flight_modes_rover/differential.md | 4 +- ko/frames_rover/ackermann.md | 14 + ko/frames_rover/differential.md | 11 + ko/frames_rover/index.md | 15 +- ko/releases/main.md | 12 +- ru/SUMMARY.md | 10 +- ru/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ ru/config_rover/differential.md | 314 +++++++++++++++++++ ru/flight_modes_rover/ackermann.md | 94 +++++- ru/flight_modes_rover/differential.md | 4 +- ru/frames_rover/ackermann.md | 14 + ru/frames_rover/differential.md | 11 + ru/frames_rover/index.md | 15 +- ru/releases/main.md | 12 +- tr/SUMMARY.md | 10 +- tr/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ tr/config_rover/differential.md | 314 +++++++++++++++++++ tr/flight_modes_rover/ackermann.md | 94 +++++- tr/flight_modes_rover/differential.md | 4 +- tr/frames_rover/ackermann.md | 14 + tr/frames_rover/differential.md | 11 + tr/frames_rover/index.md | 15 +- tr/releases/main.md | 12 +- uk/SUMMARY.md | 10 +- uk/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ uk/config_rover/differential.md | 314 +++++++++++++++++++ uk/flight_modes_rover/ackermann.md | 94 +++++- uk/flight_modes_rover/differential.md | 4 +- uk/frames_rover/ackermann.md | 14 + uk/frames_rover/differential.md | 11 + uk/frames_rover/index.md | 15 +- uk/releases/main.md | 12 +- zh/SUMMARY.md | 10 +- zh/config_rover/ackermann.md | 420 ++++++++++++++++++++++++++ zh/config_rover/differential.md | 314 +++++++++++++++++++ zh/flight_modes_rover/ackermann.md | 94 +++++- zh/flight_modes_rover/differential.md | 4 +- zh/frames_rover/ackermann.md | 14 + zh/frames_rover/differential.md | 11 + zh/frames_rover/index.md | 15 +- zh/releases/main.md | 12 +- 63 files changed, 6041 insertions(+), 217 deletions(-) create mode 100644 de/config_rover/ackermann.md create mode 100644 de/config_rover/differential.md create mode 100644 de/frames_rover/ackermann.md create mode 100644 de/frames_rover/differential.md create mode 100644 ja/config_rover/ackermann.md create mode 100644 ja/config_rover/differential.md create mode 100644 ja/frames_rover/ackermann.md create mode 100644 ja/frames_rover/differential.md create mode 100644 ko/config_rover/ackermann.md create mode 100644 ko/config_rover/differential.md create mode 100644 ko/frames_rover/ackermann.md create mode 100644 ko/frames_rover/differential.md create mode 100644 ru/config_rover/ackermann.md create mode 100644 ru/config_rover/differential.md create mode 100644 ru/frames_rover/ackermann.md create mode 100644 ru/frames_rover/differential.md create mode 100644 tr/config_rover/ackermann.md create mode 100644 tr/config_rover/differential.md create mode 100644 tr/frames_rover/ackermann.md create mode 100644 tr/frames_rover/differential.md create mode 100644 uk/config_rover/ackermann.md create mode 100644 uk/config_rover/differential.md create mode 100644 uk/frames_rover/ackermann.md create mode 100644 uk/frames_rover/differential.md create mode 100644 zh/config_rover/ackermann.md create mode 100644 zh/config_rover/differential.md create mode 100644 zh/frames_rover/ackermann.md create mode 100644 zh/frames_rover/differential.md diff --git a/de/SUMMARY.md b/de/SUMMARY.md index cad1e060646e..08fb9de97ef4 100644 --- a/de/SUMMARY.md +++ b/de/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/de/config_rover/ackermann.md b/de/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/de/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/de/config_rover/differential.md b/de/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/de/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/de/flight_modes_rover/ackermann.md b/de/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/de/flight_modes_rover/ackermann.md +++ b/de/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/de/flight_modes_rover/differential.md b/de/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/de/flight_modes_rover/differential.md +++ b/de/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/de/frames_rover/ackermann.md b/de/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/de/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/de/frames_rover/differential.md b/de/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/de/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/de/frames_rover/index.md b/de/frames_rover/index.md index 6ed450e9a3ab..15d5b08b320c 100644 --- a/de/frames_rover/index.md +++ b/de/frames_rover/index.md @@ -10,9 +10,11 @@ Support for rover is [experimental](../airframes/index.md#experimental-vehicles) PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/de/releases/main.md b/de/releases/main.md index 2a17e2b07754..cbdcea2bcc1f 100644 --- a/de/releases/main.md +++ b/de/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules. diff --git a/ja/SUMMARY.md b/ja/SUMMARY.md index 74a4ccb65240..7544728a5ad2 100644 --- a/ja/SUMMARY.md +++ b/ja/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/ja/config_rover/ackermann.md b/ja/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/ja/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/ja/config_rover/differential.md b/ja/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/ja/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/ja/flight_modes_rover/ackermann.md b/ja/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/ja/flight_modes_rover/ackermann.md +++ b/ja/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/ja/flight_modes_rover/differential.md b/ja/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/ja/flight_modes_rover/differential.md +++ b/ja/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/ja/frames_rover/ackermann.md b/ja/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/ja/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/ja/frames_rover/differential.md b/ja/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/ja/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/ja/frames_rover/index.md b/ja/frames_rover/index.md index a4c6285639e1..acc6fd938c1d 100644 --- a/ja/frames_rover/index.md +++ b/ja/frames_rover/index.md @@ -10,9 +10,11 @@ Support for rover is [experimental](../airframes/index.md#experimental-vehicles) PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/ja/releases/main.md b/ja/releases/main.md index 2a17e2b07754..cbdcea2bcc1f 100644 --- a/ja/releases/main.md +++ b/ja/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules. diff --git a/ko/SUMMARY.md b/ko/SUMMARY.md index d10d111373b5..837e80fb56d7 100644 --- a/ko/SUMMARY.md +++ b/ko/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/ko/config_rover/ackermann.md b/ko/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/ko/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/ko/config_rover/differential.md b/ko/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/ko/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/ko/flight_modes_rover/ackermann.md b/ko/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/ko/flight_modes_rover/ackermann.md +++ b/ko/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/ko/flight_modes_rover/differential.md b/ko/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/ko/flight_modes_rover/differential.md +++ b/ko/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/ko/frames_rover/ackermann.md b/ko/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/ko/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/ko/frames_rover/differential.md b/ko/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/ko/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/ko/frames_rover/index.md b/ko/frames_rover/index.md index a4c6285639e1..acc6fd938c1d 100644 --- a/ko/frames_rover/index.md +++ b/ko/frames_rover/index.md @@ -10,9 +10,11 @@ Support for rover is [experimental](../airframes/index.md#experimental-vehicles) PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/ko/releases/main.md b/ko/releases/main.md index 2a17e2b07754..cbdcea2bcc1f 100644 --- a/ko/releases/main.md +++ b/ko/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules. diff --git a/ru/SUMMARY.md b/ru/SUMMARY.md index cad1e060646e..08fb9de97ef4 100644 --- a/ru/SUMMARY.md +++ b/ru/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/ru/config_rover/ackermann.md b/ru/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/ru/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/ru/config_rover/differential.md b/ru/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/ru/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/ru/flight_modes_rover/ackermann.md b/ru/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/ru/flight_modes_rover/ackermann.md +++ b/ru/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/ru/flight_modes_rover/differential.md b/ru/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/ru/flight_modes_rover/differential.md +++ b/ru/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/ru/frames_rover/ackermann.md b/ru/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/ru/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/ru/frames_rover/differential.md b/ru/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/ru/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/ru/frames_rover/index.md b/ru/frames_rover/index.md index a4c6285639e1..acc6fd938c1d 100644 --- a/ru/frames_rover/index.md +++ b/ru/frames_rover/index.md @@ -10,9 +10,11 @@ Support for rover is [experimental](../airframes/index.md#experimental-vehicles) PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/ru/releases/main.md b/ru/releases/main.md index 2a17e2b07754..cbdcea2bcc1f 100644 --- a/ru/releases/main.md +++ b/ru/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules. diff --git a/tr/SUMMARY.md b/tr/SUMMARY.md index cad1e060646e..08fb9de97ef4 100644 --- a/tr/SUMMARY.md +++ b/tr/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/tr/config_rover/ackermann.md b/tr/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/tr/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/tr/config_rover/differential.md b/tr/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/tr/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/tr/flight_modes_rover/ackermann.md b/tr/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/tr/flight_modes_rover/ackermann.md +++ b/tr/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/tr/flight_modes_rover/differential.md b/tr/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/tr/flight_modes_rover/differential.md +++ b/tr/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/tr/frames_rover/ackermann.md b/tr/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/tr/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/tr/frames_rover/differential.md b/tr/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/tr/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/tr/frames_rover/index.md b/tr/frames_rover/index.md index a4c6285639e1..acc6fd938c1d 100644 --- a/tr/frames_rover/index.md +++ b/tr/frames_rover/index.md @@ -10,9 +10,11 @@ Support for rover is [experimental](../airframes/index.md#experimental-vehicles) PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/tr/releases/main.md b/tr/releases/main.md index 2a17e2b07754..cbdcea2bcc1f 100644 --- a/tr/releases/main.md +++ b/tr/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules. diff --git a/uk/SUMMARY.md b/uk/SUMMARY.md index d1d43dbf3ec0..4da116857762 100644 --- a/uk/SUMMARY.md +++ b/uk/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/uk/config_rover/ackermann.md b/uk/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/uk/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/uk/config_rover/differential.md b/uk/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/uk/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/uk/flight_modes_rover/ackermann.md b/uk/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/uk/flight_modes_rover/ackermann.md +++ b/uk/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/uk/flight_modes_rover/differential.md b/uk/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/uk/flight_modes_rover/differential.md +++ b/uk/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/uk/frames_rover/ackermann.md b/uk/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/uk/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/uk/frames_rover/differential.md b/uk/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/uk/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/uk/frames_rover/index.md b/uk/frames_rover/index.md index 24f5d2c402de..68caf43a6747 100644 --- a/uk/frames_rover/index.md +++ b/uk/frames_rover/index.md @@ -10,9 +10,11 @@ PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/uk/releases/main.md b/uk/releases/main.md index 14c96229fb33..a4299418546a 100644 --- a/uk/releases/main.md +++ b/uk/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules. diff --git a/zh/SUMMARY.md b/zh/SUMMARY.md index b287a01409f2..d88d72db50d8 100644 --- a/zh/SUMMARY.md +++ b/zh/SUMMARY.md @@ -399,14 +399,14 @@ - [Helicopter (experimental)](frames_helicopter/index.md) - [Helicopter Config/Tuning](config_heli/index.md) - [Rovers (experimental)](frames_rover/index.md) - - [Differential Rover](frames_rover/differential.md) + - [Ackermann Rovers](frames_rover/ackermann.md) + - [Drive Modes](flight_modes_rover/ackermann.md) + - [Configuration/Tuning](config_rover/ackermann.md) + - [Differential Rovers](frames_rover/differential.md) - [Drive Modes](flight_modes_rover/differential.md) - [Configuration/Tuning](config_rover/differential.md) - [Aion Robotics R1](frames_rover/aion_r1.md) - - [Ackermann Rover](frames_rover/ackermann.md) - - [Drive Modes](flight_modes_rover/ackermann.md) - - [Configuration/Tuning](config_rover/ackermann.md) - - [Mecanum Rover](frames_rover/mecanum.md) + - [Mecanum Rovers](frames_rover/mecanum.md) - [Drive Modes](flight_modes_rover/mecanum.md) - [Configuration/Tuning](config_rover/mecanum.md) - [(Deprecated) Rover Position Control](frames_rover/rover_position_control.md) diff --git a/zh/config_rover/ackermann.md b/zh/config_rover/ackermann.md new file mode 100644 index 000000000000..a5e1d0226db2 --- /dev/null +++ b/zh/config_rover/ackermann.md @@ -0,0 +1,420 @@ +# Configuration/Tuning (Ackermann Rover) + +This topic provides a step-by-step guide for setting up your [Ackermann rover](../frames_rover/ackermann.md). + +Successive steps enable [drive modes](../flight_modes_rover/ackermann.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the Ackermann rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select the _Generic Rover Ackermann_: + + ![QGC screenshot showing selection of the airframe 'Generic ackermann rover'](../../assets/config/airframe/airframe_generic_rover_ackermann.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `51000`. + +::: + +3. Open the [Actuators Configuration & Testing](../config/actuators.md) to map the steering and throttle functions to flight controller outputs. + +## Manual Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +The basic setup already covers the minimum setup required to use the rover in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + +However, this mode is also affected by the steering slew rate and acceleration/deceleration limits. This configuration becomes mandatory for subsequent modes, which is why we do this setup here. +Navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RA_WHEEL_BASE](#RA_WHEEL_BASE) [m]: Measure the distance from the back to the front wheels. + +2. [RA_MAX_STR_ANG](#RA_MAX_STR_ANG) [deg]: Measure the maximum steering angle. + + ![Geometric parameters](../../assets/airframes/rover/rover_ackermann/geometric_parameters.png) + +3. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: Drive the rover at full throttle and set this parameter to the observed value of the ground speed. + + :::info + This parameter is also used for the feed-forward term of the speed control. It will be further tuned in the configuration of [Position mode](#position-mode). + +::: + +4. [RA_MAX_ACCEL](#RA_MAX_ACCEL) [m/s^2]: Maximum acceleration you want to allow for your rover. + + + + :::tip + Your rover has a maximum possible acceleration which is determined by the maximum torque the motor can supply. + 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_forward_speed` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md). + 3. Divide the maximum speed by the time it took to reach it and set this as the value for [RA_MAX_ACCEL](#RA_MAX_ACCEL). + + Some RC rovers have enough torque to lift up if the maximum acceleration is not limited. + If that is the case: + + 1. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to a low value, give the rover full throttle from a standstill and observe its behaviour. + 2. Increase [RA_MAX_ACCEL](#RA_MAX_ACCEL) until the rover starts to lift up during the acceleration. + 3. Set [RA_MAX_ACCEL](#RA_MAX_ACCEL) to the highest value that does not cause the rover to lift up. + +::: + +5. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2]: Maximum deceleration you want to allow for your rover. + + :::tip + The same [considerations](#RA_MAX_ACCEL_CONSIDERATIONS) as in the configuration of [RA_MAX_ACCEL](#RA_MAX_ACCEL) apply. + +::: + + :::info + This parameter is also used for the calculation of the speed setpoint during [Auto modes](#auto-modes). + +::: + +6. (Optional) [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) [deg/s]: Maximum steering rate you want to allow for your rover. + + :::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_MAX_STR_RATE](#RA_MAX_STR_RATE) until you observe the steering rate to no longer be limited by the parameter. + For smaller rovers you might observe the steering to be too aggressive. Set [RA_MAX_STR_RATE](#RA_MAX_STR_RATE) to a low value and steer the rover at a standstill. + Increase the parameter until you reach the maximum steering rate you are comfortable with. + +::: + + :::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. + +::: + +## Acro Mode + +:::warning +For this mode to work properly [Manual mode](#acro-mode) must've already been configured! +::: + +To set up [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) configure the following [parameters](../advanced_config/parameters.md) in QGroundControl: + +1. [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL): Maximum lateral acceleration you want to allow for your rover. + + :::tip + Limiting the lateral acceleration is necessary if the rover is prone rolling over, loosing traction at high speeds or if passenger comfort is important. + Small rovers especially can be prone to rolling over when steering aggressively at high speeds. + + If this is the case: + + 1. In [Acro mode](../flight_modes_rover/ackermann.md#acro-mode), set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to a small value and drive the rover at full throttle and with the right stick all the way to the left or right. + 2. Increase [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) until the wheels of the rover start to lift up. + 3. Set [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL) to the highest value that does not cause the rover to lift up. + + If you see no need to limit the lateral acceleration, set this parameter to the maximum lateral acceleration the rover can achieve: + + 1. In [Manual mode](#manual-mode) drive the rover at full throttle and with the maximum steering angle. + 2. Plot the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) and enter the highest observed value for [RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL). + + +::: + +2. [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) [-]: Proportional gain of the closed loop lateral acceleration controller. + The closed loop acceleration control will compare the lateral acceleration setpoint with the measured lateral acceleration and adapt the motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. This way disturbances like uneven grounds or external forces can be compensated. + + :::tip + To tune this parameter: + + 1. Put the rover in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode) and hold the throttle stick and the right stick at a few different levels for a couple of seconds each. + 2. Disarm the rover and from the flight log plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + 3. Increase [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) if the measured value does not track the setpoint fast enough or decrease it if the measurement overshoots the setpoint by too much. + 4. Repeat until you are satisfied with the behaviour. + + Note that the lateral acceleration measurement is very noisy and therefore needs to be heavily filtered. + This means that the measurement is slightly delayed, so if you observe a slight offset in time between the setpoint and measurement, that is not something that can be fixed with tuning. + +::: + +3. (Optional) [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I) [-]: Integral gain of the closed loop lateral acceleration controller. + The integral gain accumulates the error between the desired and actual lateral acceleration scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the lateral acceleration setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/ackermann.md#acro-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/ackermann.md#position-mode) is the most advanced manual mode, utilizing closed loop lateral acceleration and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RA_MAX_SPEED](#RA_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + As mentioned in the [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) configuration , a good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode). + + + + ::: tip + To further tune this parameter: + + 1. Set [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + 3. Disarm the rover and from the flight log plot the `adjusted_forward_speed_setpoint` and the `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + 4. If the actual speed of the rover is higher than the speed setpoint, increase [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/ackermann.md#position-mode), set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/ackermann.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RA_SPEED_P](#RA_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RA_MAX_THR_SPEED](#RA_SPEED_TUNING). + If you tuned [RA_MAX_THR_SPEED](#RA_MAX_THR_SPEED) well, you might only need a very small value. + +::: + +4. [RA_SPEED_I](#RA_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (right stick centered) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + + To tune this: + + 1. Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) + 2. Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + 3. If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + 4. Repeat until you are satisfied with the behaviour. + + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/ackermann.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/ackermann.md#position-mode). + +## Auto Modes + +:::warning +For auto modes to work properly [Manual Mode](#manual-mode), [Acro mode](#acro-mode)and [Position mode](#position-mode) must already be configured! +::: + + + +In [auto modes](../flight_modes_rover/ackermann.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_ackermann/ackermann_rover_guidance_structure.png) + +The required parameter configuration is discussed in the following sections. + +### Speed + +1. [RA_MAX_DECEL](#RA_MAX_DECEL) [m/s^2] and [RA_MAX_JERK](#RA_MAX_JERK) [m/s^3] are used to calculate a speed trajectory such that the rover reaches the next waypoint with the correct [cornering speed](#cornering-speed). + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RA_MAX_DECEL](#RA_MAX_DECEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RA_MAX_JERK](#RA_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RA_MAX_DECEL](#RA_MAX_DECEL). + + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +2. Plot the `adjusted_forward_speed_setpoint` and `measured_forward_speed` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_SPEED_P](#RA_SPEED_P) and [RA_SPEED_I](#RA_SPEED_I). + +### Corner Cutting + +The module employs a special cornering logic causing the rover to "cut corners" to achieve a smooth trajectory. +This is done by scaling the acceptance radius based on the corner the rover has to drive (for geometric explanation see [Cornering logic](#mission-cornering-logic-info-only)). + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_comparison.png) + +The degree to which corner cutting is allowed can be tuned, or disabled, with the following parameters: + +:::info +The corner cutting effect is a tradeoff between how close you get to the waypoint and the smoothness of the trajectory. +::: + +1. [NAV_ACC_RAD](#NAV_ACC_RAD) [m]: Default acceptance radius. This is also used as a lower bound for the acceptance radius scaling. +2. [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX) [m]: The maximum the acceptance radius can be scaled to. Set equal to [NAV_ACC_RAD](#NAV_ACC_RAD) to disable the corner cutting effect. +3. [RA_ACC_RAD_GAIN](#RA_ACC_RAD_GAIN) [-]: This tuning parameter is a multiplicand on the [calculated ideal acceptance radius](#corner-cutting-logic) to account for dynamic effects. + + :::tip + Initially set this parameter to `1`. + If you observe the rover overshooting the corner, increase this parameter until you are satisfied with the behaviour. + Note that the scaling of the acceptance radius is limited by [RA_ACC_RAD_MAX](#RA_ACC_RAD_MAX). + +::: + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a lateral acceleration setpoint for the vehicle that is then close loop controlled. +The close loop lateral acceleration was tuned in the configuration of the [Acro mode](#acro-mode), and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. + +If you are unsatisfied with the path following, there are 2 steps to take: + +1. Plot the `lateral_acceleration_setpoint` from [RoverAckermannSetpoint](../msg_docs/RoverAckermannSetpoint.md) and the `measured_lateral_acceleration` from the [RoverAckermannStatus](../msg_docs/RoverAckermannStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RA_LAT_ACCEL_P](#RA_LAT_ACCEL_P) and [RA_LAT_ACCEL_I](#RA_LAT_ACCEL_I). +2. Step 1 ensures accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm. + +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint. + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look-ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Mission Cornering Logic (Info only) + +### Corner Cutting Logic + +To enable a smooth trajectory, the acceptance radius of waypoints is scaled based on the angle between a line segment from the current-to-previous and current-to-next waypoints. +The ideal trajectory would be to arrive at the next line segment with the heading pointing towards the next waypoint. +For this purpose the minimum turning circle of the rover is inscribed tangentially to both line segments. + +![Cornering Logic](../../assets/airframes/rover/rover_ackermann/cornering_logic.png) + +The acceptance radius of the waypoint is set to the distance from the waypoint to the tangential points between the circle and the line segments: + +$$ +\begin{align*} +r_{min} &= \frac{L}{\sin\left( \delta_{max}\right) } \\ +\theta &= \frac{1}{2}\arccos\left( \frac{\vec{a}*\vec{b}}{|\vec{a}||\vec{b}|}\right) \\ +r_{acc} &= \frac{r_{min}}{\tan\left( \theta\right) } +\end{align*} +$$ + +| Symbol | Description | Unit | +| ----------------------------------- | ---------------------------------- | ---- | +| $\vec{a}$ | Vector from current to previous WP | m | +| $\vec{b}$ | Vector from current to next WP | m | +| $r_{min}$ | Minimum turn radius | m | +| $\delta_{max}$ | Maximum steer angle | m | +| $r_{acc}$ | Acceptance radius | m | + +### Cornering Speed + +To smoothen the trajectory further and reduce the risk of the rover rolling over, the rover speed is regulated as follows: + +1. During cornering the rover drives at the following speed: + + + + $$v_{cor, max} = \sqrt{r \cdot a_{lat, max}}$$ + + with $r:$ Turning radius for the upcoming corner and $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)). + +2. In between waypoints (straight line) the rover speed is regulated such that it will arrive at the acceptance radius of the waypoint with the desired cornering speed. + +The rover is constrained between the maximum speed [RA_MAX_SPEED](#RA_MAX_SPEED) and the speed where the maximum steering angle does not cause the rover to exceed the lateral acceleration limit: + + + +$$v_{min} = \sqrt{\frac{w_b \cdot a_{lat, max}}{tan(\theta_{max})}}$$ + +with $w_b:$ Wheel base ([RA_WHEEL_BASE](#RA_WHEEL_BASE)), $a_{lat, max}:$ Maximum lateral acceleration ([RA_MAX_LAT_ACCEL](#RA_MAX_LAT_ACCEL)) and $\theta_{max}:$ Maximum steering angle ([RA_MAX_STR_ANG](#RA_MAX_STR_ANG)). + +## Parameter Overview + +List of all parameters of the ackermann rover module: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------- | +| [RA_WHEEL_BASE](../advanced_config/parameter_reference.md#RA_WHEEL_BASE) | Wheel base | m | +| [RA_MAX_STR_ANG](../advanced_config/parameter_reference.md#RA_MAX_STR_ANG) | Maximum steering angle | deg | +| [RA_MAX_THR_SPEED](../advanced_config/parameter_reference.md#RA_MAX_THR_SPEED) | Speed the rover drives at maximum throttle | m/s | +| [RA_MAX_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_ACCEL) | Maximum allowed acceleration | m/s^2 | +| [RA_MAX_DECEL](../advanced_config/parameter_reference.md#RA_MAX_DECEL) | Maximum allowed deceleration | m/s^2 | +| [RA_MAX_JERK](../advanced_config/parameter_reference.md#RA_MAX_JERK) | Maximum allowed jerk for the rover | $m/s^3$ | +| [RA_MAX_STR_RATE](../advanced_config/parameter_reference.md#RA_MAX_STR_RATE) | Maximum allowed steering rate | deg/s | +| [RA_MAX_LAT_ACCEL](../advanced_config/parameter_reference.md#RA_MAX_LAT_ACCEL) | Maximum allowed lateral acceleration | m/s^2 | +| [RA_LAT_ACCEL_P](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_P) | Proportional gain for lateral acceleration controller | - | +| [RA_LAT_ACCEL_I](../advanced_config/parameter_reference.md#RA_LAT_ACCEL_I) | Integral gain for lateral acceleration controller | - | +| [RA_MAX_SPEED](../advanced_config/parameter_reference.md#RA_MAX_SPEED) | Maximum allowed speed | m/s | +| [RA_SPEED_P](../advanced_config/parameter_reference.md#RA_SPEED_P) | Proportional gain for speed controller | - | +| [RA_SPEED_I](../advanced_config/parameter_reference.md#RA_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [NAV_ACC_RAD](../advanced_config/parameter_reference.md#NAV_ACC_RAD) | Default acceptance radius | m | +| [RA_ACC_RAD_MAX](../advanced_config/parameter_reference.md#RA_ACC_RAD_MAX) | Maximum radius the acceptance radius can be scaled to | m | +| [RA_ACC_RAD_GAIN](../advanced_config/parameter_reference.md#RA_ACC_RAD_GAIN) | Tuning parameter | - | + +## See Also + +- [Drive Modes (Ackermann Rover)](../flight_modes_rover/ackermann.md). diff --git a/zh/config_rover/differential.md b/zh/config_rover/differential.md new file mode 100644 index 000000000000..22b8870745c9 --- /dev/null +++ b/zh/config_rover/differential.md @@ -0,0 +1,314 @@ +# Configuration/Tuning (Differential Rover) + +This topic provides a step-by-step guide for setting up your [Differential rover](../frames_rover/differential.md). +Successive steps enable [drive modes](../flight_modes_rover/differential.md) with more autopilot support and features. + +:::warning +Each step is dependent on the previous steps having been completed. +Modes will only work properly if the preceding modes have been configured. +::: + +## Basic Setup + +To configure the differential rover frame and outputs: + +1. Enable Rover support by flashing the [PX4 rover build](../frames_rover/index.md#flashing-the-rover-build) onto your flight controller. + Note that this is a special build that contains rover-specific modules. + +2. In the [Airframe](../config/airframe.md) configuration select _Generic Rover Differential_ frame: + + ![QGC screenshot showing selection of the airframe 'Generic Rover Differential'](../../assets/config/airframe/airframe_generic_rover_differential.png) + + Select the **Apply and Restart** button. + + ::: info + If this airframe is not displayed and you have checked that you are using rover firmware (not the default), you can alternatively enable this frame by setting the [SYS_AUTOSTART](../advanced_config/parameter_reference.md#SYS_AUTOSTART) parameter to `50000`. + +::: + +3. Use [Actuators Configuration & Testing](../config/actuators.md) to map the motor functions to flight controller outputs. + +## Manual Mode + +The basic setup (above) is all that is required to use the rover in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + +## Acro Mode + +:::warning +For this mode to work properly the [Basic Setup](#basic-setup) must've already been completed! +::: + +To set up [Acro mode](../flight_modes_rover/differential.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters: + +1. [RD_WHEEL_TRACK](#RD_WHEEL_TRACK) [m]: Measure the distance from the centre of the right wheel to the centre of the left wheel. + + ![Wheel track](../../assets/airframes/rover/rover_differential/wheel_track.png) + +2. [RD_MAX_YAW_RATE](#RD_MAX_YAW_RATE) [deg/s]: This is the maximum yaw rate you want to allow for your rover. + This will define the stick-to-yaw-rate mapping for all manual modes using closed loop yaw control and set an upper limit for the yaw rate setpoint for all [auto modes](#auto-modes). + +3. [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop yaw rate control. + The controller calculates the required speed difference between the left and right motor to achieve the desired yaw rate. + This desired speed difference is then linearly mapped to normalized motor commands. + To get a good starting value for this parameter drive the rover in manual mode forwards at full throttle and note the ground speed of the vehicle. + Then enter _twice_ this value for the parameter. + + ::: tip + To further tune this parameter, first make sure you set [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I) to zero. + This way the yaw rate is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Acro mode](../flight_modes_rover/differential.md#acro-mode) and then move the right-stick of your controller to the right and/or left and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) over each other. + If the actual yaw rate of the rover is higher than the yaw rate setpoint, increase [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + +4. [RD_YAW_RATE_P](#RD_YAW_RATE_P) [-]: Proportional gain of the closed loop yaw rate controller. + Unlike the feed-forward part of the controller, the closed loop yaw rate control will compare the yaw rate setpoint with the measured yaw rate and adapt to motor commands based on the error between them. + The proportional gain is multiplied with this error and that value is added to the motor command. + This way disturbances like uneven grounds or external forces can be compensated. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_YAW_R](#RD_YAW_RATE_P_TUNING). + If you tuned [RD_MAX_THR_YAW_R](#RD_MAX_YAW_RATE) well, you might only need a very small value. + +::: + +5. (Optional) [RD_YAW_RATE_I](#RD_YAW_RATE_I) [-]: Integral gain of the closed loop yaw controller. + The integral gain accumulates the error between the desired and actual yaw rate scaled by the integral gain over time and that value is added to the motor command. + + ::: tip + The integrator gain is usually not necessary for the yaw rate setpoint as this is usually a fast changing value. + Leave this parameter at zero unless necessary, as it can have negative side effects such as overshooting or oscillating around the setpoint. + +::: + +The rover is now ready to drive in [Acro mode](../flight_modes_rover/differential.md#acro-mode). + +## Stabilized Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) must've already been configured! +::: + +For [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode) the controller utilizes a closed loop yaw controller, which creates a yaw rate setpoint to control the yaw when it is active: + +![Cascaded PID for yaw control](../../assets/airframes/rover/rover_differential/cascaded_pid_for_yaw.png) + +Unlike the closed loop yaw rate, this controller has no feed-forward term. +Therefore you only need to tune the closed loop gains: + +1. [RD_YAW_P](#RD_YAW_P) [-]: Proportional gain for the closed loop yaw controller. + + ::: tip + In stabilized mode the closed loop yaw control is only active when driving a straight line (no yaw rate input). + To tune it set [RD_YAW_I](#RD_YAW_I) to zero and start with a value of 1 for [RD_YAW_P](#RD_YAW_P). + Put the rover into stabilized mode and move the left stick of your controller up and/or down to drive forwards/backwards. + Disarm the rover and from the flight log plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + Increase/Decrease the parameter until you are satisfied with the setpoint tracking. + +::: + +2. [RD_YAW_I](#RD_YAW_I) [-]: Integral gain for the closed loop yaw controller. + + ::: tip + For the closed loop yaw control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + In [Auto Modes](#auto-modes) there will be a further elaboration on why an integrator is necessary for the yaw controller. + +::: + +The rover is now ready to drive in [Stabilized mode](../flight_modes_rover/differential.md#stabilized-mode). + +## Position Mode + +:::warning +For this mode to work properly [Acro mode](#acro-mode) and [Stabilized mode](#stabilized-mode) must already be configured! +::: + +[Position mode](../flight_modes_rover/differential.md#position-mode) is the most advanced manual mode, utilizing closed loop yaw rate, yaw and speed control and leveraging position estimates. + +To configure set the following parameters: + +1. [RD_MAX_SPEED](#RD_MAX_SPEED) [m/s]: This is the maximum speed you want to allow for your rover. + This will define the stick-to-speed mapping for position mode and set an upper limit for the speed setpoint for all [auto modes](#auto-modes). + +2. [RD_MAX_THR_SPD](#RD_MAX_SPEED) [m/s]: This parameter is used to calculate the feed-forward term of the closed loop speed control which linearly maps desired speeds to normalized motor commands. + A good starting point is the observed ground speed when the rover drives at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode). + + + + ::: tip + To further tune this parameter, first make sure you set [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I) to zero. + This way the speed is only controlled by the feed-forward term, which makes it easier to tune. + Now put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and then move the left stick of your controller up and/or down and hold it at a few different levels for a couple of seconds each. + Disarm the rover and from the flight log plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the actual speed of the rover is higher than the speed setpoint, increase [RD_MAX_THR_SPD](#RD_MAX_THR_SPD). + If it is the other way around decrease the parameter and repeat until you are satisfied with the setpoint tracking. + +::: + + ::: info + If your rover oscillates when driving a straight line in [Position mode](../flight_modes_rover/differential.md#position-mode) just set this parameter to the observed ground speed at maximum throttle in [Manual mode](../flight_modes_rover/differential.md#manual-mode) and complete steps 5-7 first before continuing the tuning of the closed loop speed control (Steps 2-4). + +::: + +3. [RD_SPEED_P](#RD_SPEED_P) [-]: Proportional gain of the closed loop speed controller. + + ::: tip + This parameter can be tuned the same way as [RD_MAX_THR_SPD](#RD_SPEED_P_TUNING). + If you tuned [RD_MAX_THR_SPD](#RD_MAX_THR_SPD) well, you might only need a very small value. + +::: + +4. [RD_SPEED_I](#RD_SPEED_I) [-]: Integral gain for the closed loop speed controller. + + ::: tip + For the closed loop speed control an integrator gain is useful because this setpoint is often constant for a while and an integrator eliminates steady state errors that can cause the rover to never reach the setpoint. + +::: + +5. [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN): When driving in a straight line (no yaw rate input) position mode leverages the same path following algorithm used in [auto modes](#auto-modes) called [pure pursuit](#pure-pursuit-guidance-logic) to achieve the best possible straight line driving behaviour ([Illustration of control architecture](#pure_pursuit_controller)). + This parameter determines how aggressive the controller will steer towards the path. + + ::: tip + Decreasing the parameter makes it more aggressive but can lead to oscillations. + Start with a value of 1 for [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN), put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and while driving a straight line at approximately half the maximum speed observe its behaviour. + If the rover does not drive in a straight line, reduce the value of the parameter, if it oscillates around the path increase the value. + Repeat until you are satisfied with the behaviour. + +::: + +6. [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN): Minimum threshold for the lookahead distance used by the [pure pursuit algorithm](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very low speeds, if the rover starts to oscillate even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then increase the value of [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +::: + +7. [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX): Maximum threshold for the lookahead distance used by [pure pursuit](#pure-pursuit-guidance-logic). + + ::: tip + Put the rover in [Position mode](../flight_modes_rover/differential.md#position-mode) and drive at very high speeds, if the rover does not drive in a straight line even though the tuning of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) was good for medium speeds, then decrease the value of [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX). + +::: + +The rover is now ready to drive in [Position mode](../flight_modes_rover/differential.md#position-mode). + +## Auto Modes + +:::warning +For this mode to work properly [Acro mode](#acro-mode), [Stabilized mode](#stabilized-mode) and [Position mode](#position-mode) must already be configured! +::: + + +In [auto modes](../flight_modes_rover/differential.md#auto-modes) the autopilot takes over navigation tasks using the following control architecture: + +![Pure Pursuit Controller](../../assets/airframes/rover/rover_differential/pure_pursuit_controller.png) + +The required parameters are separated into the following sections: + +### Speed + +These parameters are used to calculate the speed setpoint in auto modes: + +1. [RD_MISS_SPD_DEF](#RD_MISS_SPD_DEF): Sets the default velocity ($m/s$) for the rover during the mission. + +2. [RD_MAX_ACCEL](#RD_MAX_ACCEL) ($m/s^2$) and [RD_MAX_JERK](#RD_MAX_JERK) ($m/s^3$) are used to calculate a velocity trajectory such that the rover comes to a smooth stop as it reaches a waypoint. + + ::: tip + Plan a mission for the rover to drive a square and observe how it slows down when approaching a waypoint. + If the rover decelerates too quickly decrease the [RD_MAX_ACCEL](#RD_MAX_ACCEL) parameter, if it starts slowing down too early increase the parameter. + If you observe a jerking motion as the rover slows down, decrease the [RD_MAX_JERK](#RD_MAX_JERK) parameter otherwise increase it as much as possible as it can interfere with the tuning of [RD_MAX_ACCEL](#RD_MAX_ACCEL). + These two parameters have to be tuned as a pair, repeat until you are satisfied with the behaviour. + +::: + +3. Plot the _forward_speed_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_speed_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_SPEED_P](#RD_SPEED_P) and [RD_SPEED_I](#RD_SPEED_I). + +The rover only slows down when approaching the waypoint if the angle between the line segment between the previous/current waypoint and current/next waypoint is smaller than 180° - [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). +In other words: The rover slows down only if the expected heading error towards the next waypoint when arriving at the current waypoint is below [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN). + +![Illustration of the activation threshold of the slow down effect](../../assets/airframes/rover/rover_differential/differential_slow_down_effect.png) + +For more information on the [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) parameter see [State Machine](#state-machine). + +### State Machine + +The module employs the following state machine to make full use of a differential rovers ability to turn on the spot: + +![Differential state machine](../../assets/airframes/rover/rover_differential/differential_state_machine.png) + +These transition thresholds can be set with [RD_TRANS_DRV_TRN](#RD_TRANS_DRV_TRN) and [RD_TRANS_TRN_DRV](#RD_TRANS_TRN_DRV). + +### Path Following + +The [pure pursuit](#pure-pursuit-guidance-logic) algorithm is used to calculate a desired yaw for the vehicle that is then close loop controlled. +The close loop yaw rate was tuned in the configuration of the [Stabilized mode](#stabilized-mode) and the pure pursuit was tuned when setting up the [Position mode](#position-mode). +During any auto navigation task observe the behaviour of the rover. +If you are unsatisfied with the path following, there are 3 steps to take: + +1. Plot the _yaw_rate_setpoint_ and _actual_yaw_rate_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialStatus.md) over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_RATE_P](#RD_YAW_RATE_P) and [RD_YAW_RATE_I](#RD_YAW_RATE_I). +2. Plot the _yaw_setpoint_ from the [RoverDifferentialSetpoint](../msg_docs/RoverDifferentialSetpoint.md) message and the _actual_yaw_ from the [RoverDifferentialStatus](../msg_docs/RoverDifferentialStatus.md) message over each other. + If the tracking of these setpoints is not satisfactory adjust the values for [RD_YAW_P](#RD_YAW_P) and [RD_YAW_I](#RD_YAW_P). +3. Steps 1 and 2 ensure accurate setpoint tracking, if the path following is still unsatisfactory you need to further tune the [pure pursuit](#pure-pursuit-guidance-logic) parameters. + +## Pure Pursuit Guidance Logic + +The desired yaw setpoints are generated using a pure pursuit algorithm: +The controller takes the intersection point between a circle around the vehicle and a line segment. +In mission mode this line is usually constructed by connecting the previous and current waypoint: + +![Pure Pursuit Algorithm](../../assets/airframes/rover/flight_modes/pure_pursuit_algorithm.png) + +The radius of the circle around the vehicle is used to tune the controller and is often referred to as look-ahead distance. + +The look ahead distance sets how aggressive the controller behaves and is defined as $l_d = v \cdot k$. +It depends on the velocity $v$ of the rover and a tuning parameter $k$ that can be set with the parameter [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN). + +:::info +A lower value of [PP_LOOKAHD_GAIN](#PP_LOOKAHD_GAIN) makes the controller more aggressive but can lead to oscillations! +::: + +The lookahead is constrained between [PP_LOOKAHD_MAX](#PP_LOOKAHD_MAX) and [PP_LOOKAHD_MIN](#PP_LOOKAHD_MIN). + +If the distance from the path to the rover is bigger than the lookahead distance, the rover will target the point on the path that is closest to the rover. + +To summarize, the following parameters can be used to tune the controller: + +| Parameter | Description | Unit | +| -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ---- | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius | m | + +## Parameter Overview + +List of all parameters of the differential rover module: + +| Parameter | Description | Unit | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | ------- | +| [RD_WHEEL_TRACK](../advanced_config/parameter_reference.md#RD_WHEEL_TRACK) | Wheel track | m | +| [RD_MAX_THR_YAW_R](../advanced_config/parameter_reference.md#RD_MAX_THR_YAW_R) | Yaw rate turning left/right wheels at max speed in opposite directions | m/s | +| [RD_MAX_YAW_RATE](../advanced_config/parameter_reference.md#RD_MAX_YAW_RATE) | Maximum allowed yaw rate for the rover | deg/s | +| [RD_YAW_RATE_P](../advanced_config/parameter_reference.md#RD_YAW_RATE_P) | Proportional gain for yaw rate controller | - | +| [RD_YAW_RATE_I](../advanced_config/parameter_reference.md#RD_YAW_RATE_I) | Integral gain for yaw rate controller | - | +| [RD_YAW_P](../advanced_config/parameter_reference.md#RD_YAW_P) | Proportional gain for yaw controller | - | +| [RD_YAW_I](../advanced_config/parameter_reference.md#RD_YAW_I) | Integral gain for yaw controller | - | +| [RD_MAX_SPEED](../advanced_config/parameter_reference.md#RD_MAX_SPEED) | Maximum allowed speed for the rover | m/s | +| [RD_MAX_THR_SPD](../advanced_config/parameter_reference.md#RD_MAX_THR_SPD) | Speed the rover drives at maximum throttle | m/s | +| [RD_SPEED_P](../advanced_config/parameter_reference.md#RD_SPEED_P) | Proportional gain for speed controller | - | +| [RD_SPEED_I](../advanced_config/parameter_reference.md#RD_SPEED_I) | Integral gain for speed controller | - | +| [PP_LOOKAHD_GAIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_GAIN) | Main tuning parameter for pure pursuit | - | +| [PP_LOOKAHD_MAX](../advanced_config/parameter_reference.md#PP_LOOKAHD_MAX) | Maximum value for the look ahead radius of the pure pursuit algorithm | m | +| [PP_LOOKAHD_MIN](../advanced_config/parameter_reference.md#PP_LOOKAHD_MIN) | Minimum value for the look ahead radius of the pure pursuit algorithm | m | +| [RD_MISS_SPD_DEF](../advanced_config/parameter_reference.md#RD_MISS_SPD_DEF) | Mission speed for the rover | $m/s$ | +| [RD_MAX_ACCEL](../advanced_config/parameter_reference.md#RD_MAX_ACCEL) | Maximum acceleration for the rover | $m/s^2$ | +| [RD_MAX_JERK](../advanced_config/parameter_reference.md#RD_MAX_JERK) | Maximum jerk for the rover | $m/s^3$ | +| [RD_TRANS_DRV_TRN](../advanced_config/parameter_reference.md#RD_TRANS_DRV_TRN) | Heading error threshold to switch from driving to spot turning | deg | +| [RD_TRANS_TRN_DRV](../advanced_config/parameter_reference.md#RD_TRANS_TRN_DRV) | Heading error threshold to switch from spot turning to driving | deg | + +## See Also + +- [Drive Modes (Differential Rover)](../flight_modes_rover/differential.md). diff --git a/zh/flight_modes_rover/ackermann.md b/zh/flight_modes_rover/ackermann.md index 1ab3e05416d3..26eaec14d60c 100644 --- a/zh/flight_modes_rover/ackermann.md +++ b/zh/flight_modes_rover/ackermann.md @@ -2,7 +2,7 @@ Flight modes (or more accurately "Drive modes" for ground vehicles) provide autopilot support to make it easier to manually drive the vehicle or to execute autonomous missions. -This section outlines all supported drive modes for Ackermann rovers. +This section outlines all supported drive modes for [Ackermann rovers](../frames_rover/ackermann.md). For information on mapping RC control switches to specific modes see: [Basic Configuration > Flight Modes](../config/flight_mode.md). @@ -14,30 +14,100 @@ Selecting any other mode than those listed below will either stop the rover or c Manual modes require stick inputs from the user to drive the vehicle. -![Manual Controls](../../assets/airframes/rover/flight_modes/rover_manual_controls.png) +![Manual Controls](../../assets/airframes/rover/flight_modes/manual_controls_ackermann_rover.png) -The manual modes listed below provide increasing levels of autopilot support: +The sticks provide the same "high level" control effects over direction and rate of movement in all manual modes: -| Mode | Features | -| ---------------------- | ------------------------------------------------------------------------------------ | -| [Manual](#manual-mode) | Directly map stick inputs to motor commands, no closed loop control. | +- `Left stick up/down`: Drive the rover forwards/backwards (controlling speed) +- `Right stick left/right`: Make a left/right turn (controlling steering angle ([Manual mode](#manual-mode)) or lateral acceleration ([Acro](#acro-mode) and [Position](#position-mode))). + +The manual modes provide progressively increasing levels of autopilot support for maintaining a course, speed, and rate of turn, compensating for external factors such as slopes or uneven terrain. + +| Mode | Features | +| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | No autopilot support. User is responsible for keeping the rover on the desired course and maintaining speed and rate of turn. | +| [Acro](#acro-mode) | + Maintains the lateral acceleration. This makes it feel more like driving a car than manual mode.
+ It also protects against roll over and is slightly better at holding a straight line in uneven terrain. | +| [Position](#position-mode) | + Best mode for holding a straight line.
+ Maintains speed against disturbances, e.g. when driving up a hill
+ Allows maximum speed to be limited. | + +:::details +Overview mode mapping to control effect + +| Mode | Forward speed | Steering angle/lateral acceleration | Required measurements | +| -------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| [Manual](#manual-mode) | Directly map stick input to motor command. | Directly map stick input to steering angle. | None. | +| [Acro](#acro-mode) | Directly map stick input to motor command. | Stick input creates a lateral acceleration setpoint for the control system to regulate. | Lateral acceleration. | +| [Position](#position-mode) | Stick input creates a speed setpoint for the control system to regulate. | Stick input creates a lateral acceleration setpoint for the control system to regulate. If this setpoint is zero (stick is centered) the control system will keep the rover driving in a straight line. | Lateral acceleration, yaw, speed and global position (GPS). | + +::: ### Manual Mode -The _Manual_ mode stops the rover when the RC control sticks are centred. -To manually move/drive the vehicle you move the sticks outside of the centre. +In this mode the stick inputs are directly mapped to motor commands. The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! +The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. + +| Stick | Effect | +| ---------------------- | ---------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Move the steering angle to the left/right. | -Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle. +For the configuration/tuning of this mode see [Manual mode](../config_rover/ackermann.md#manual-mode). + +### Acro Mode :::info -The rover does not attempt to maintain a specific orientation or compensate for external factors like slopes or uneven terrain! -The user is responsible for making the necessary adjustments to the stick inputs to keep the rover on the desired course. +This mode requires a lateral acceleration measurement. ::: +In this mode the vehicle regulates its lateral acceleration to a setpoint (but does not stabilize heading or regulate speed). + +Lateral acceleration can be directly mapped to a steering input based on the forward speed of the rover: + + + +$$\theta = \arctan(\frac{w_b \cdot a_{lat}}{ v^2})$$ + +with + +- $w_b:$ Wheel base, +- $\theta:$ Steering angle, +- $v:$ Forward speed. + +For driving this means that the same right hand stick input will cause a different steering angle based on how fast you are driving. +By limiting the maximum lateral acceleration, we can restrict the steering angle based on the speed, which can prevent the rover from rolling over. +This mode will feel more like "driving a car" than [Manual mode](#manual-mode). + +:::info +The lateral acceleration is only close loop controlled when driving forwards. When driving backwards the lateral acceleration setpoint is directly mapped to a steering angle using the equation above. +This is due to the fact that rear wheel steering (driving a car with front-wheel steering backwards) is non-minimum-phase w.r.t to the lateral acceleration which leads to instabilities when doing closed loop control. +::: + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Left stick up/down | Drive the rover forwards/backwards. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will attempt to maintain a zero lateral acceleration (minimal disturbance rejection) | + +For the configuration/tuning of this mode see [Acro mode](../config_rover/ackermann.md#acro-mode). + +### Position Mode + +:::info +This mode requires a lateral acceleration, yaw, speed and global position estimate. +::: + +This is the manual mode with the most autopilot support. The vehicle regulates its lateral acceleration and speed to a setpoint. If the lateral acceleration setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. + +| Stick | Effect | +| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Left stick up/down | Stick position sets a forward/back speed setpoint. The vehicle attempts to maintain this speed on slopes etc. | +| Right stick left/right | Create a lateral acceleration setpoint for the control system to regulate. If this input is zero the control system will maintain the course of the rover. | + +For the configuration/tuning of this mode see [Position mode](../config_rover/differential.md#position-mode). + ## Auto Modes In auto modes the autopilot takes over control of the vehicle to run missions, return to launch, or perform other autonomous navigation tasks. -For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#mission-parameters). +For the tuning process see the configuration for [Auto modes](../config_rover/ackermann.md#auto-modes). ### Mission Mode diff --git a/zh/flight_modes_rover/differential.md b/zh/flight_modes_rover/differential.md index 9499497bb018..0ae50c25aa54 100644 --- a/zh/flight_modes_rover/differential.md +++ b/zh/flight_modes_rover/differential.md @@ -80,7 +80,9 @@ For the configuration/tuning of this mode see [Stabilized mode](../config_rover/ This mode requires a yaw rate, yaw, speed and global position estimate. ::: -This is the mode with the most autopilot support. The vehicle regulates its yaw rate and speed to a setpoint. If the yaw rate setpoint is zero, the controller will remember the gps coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). +This is the manual mode with the most autopilot support. +The vehicle regulates its yaw rate and speed to a setpoint. +If the yaw rate setpoint is zero, the controller will remember the GNSS coordinates and yaw (heading) of the vehicle and use those to construct a line that the rover will then follow (course control). This offers the highest amount of disturbance rejection, which leads to the best straight line driving behavior. | Stick | Effect | diff --git a/zh/frames_rover/ackermann.md b/zh/frames_rover/ackermann.md new file mode 100644 index 000000000000..a426eae8775d --- /dev/null +++ b/zh/frames_rover/ackermann.md @@ -0,0 +1,14 @@ +# Ackermann Rovers + + + +An _Ackermann rover_ controls its direction by pointing the front wheels in the direction of travel — the [Ackermann steering geometry](https://en.wikipedia.org/wiki/Ackermann_steering_geometry) compensates for the fact that wheels on the inside and outside of the turn move at different rates. +This kind of steering is used on most commercial vehicles, including cars, trucks etc. + +:::info +PX4 does not require that the vehicle uses the Ackermann geometry and will work with any front-steering rover. +::: + +![Axial Trail Honcho](../../assets/airframes/rover/rover_ackermann/axial_trail_honcho.png) + +See [Configuration/Tuning](../config_rover/ackermann.md) to set up your rover and [Drive Modes](../flight_modes_rover/ackermann.md) for the supported flight (aka drive) modes. diff --git a/zh/frames_rover/differential.md b/zh/frames_rover/differential.md new file mode 100644 index 000000000000..35f3882bfabf --- /dev/null +++ b/zh/frames_rover/differential.md @@ -0,0 +1,11 @@ +# Differential Rovers + + + +A differential rover's motion is controlled using a differential drive mechanism, where the left and right wheel speeds are adjusted independently to achieve the desired forward speed and yaw rate. +Forward motion is achieved by driving both wheels at the same speed in the same direction. +Rotation is achieved by driving the wheels at different speeds in opposite directions, allowing the rover to turn on the spot. + +![Aion R1](../../assets/airframes/rover/aion_r1/r1_rover_no_bg.png) + +See [Configuration/Tuning](../config_rover/differential.md) to set up your rover and [Drive Modes](../flight_modes_rover/differential.md) for the supported flight (aka drive) modes. diff --git a/zh/frames_rover/index.md b/zh/frames_rover/index.md index a4c6285639e1..acc6fd938c1d 100644 --- a/zh/frames_rover/index.md +++ b/zh/frames_rover/index.md @@ -10,9 +10,11 @@ Support for rover is [experimental](../airframes/index.md#experimental-vehicles) PX4 supports the following rover types: -- [**Differential steering**](../frames_rover/differential.md): direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). This kind of steering is commonly used on bulldozers, tanks, and other tracked vehicles. -- [**Ackermann steering**](../frames_rover/ackermann.md): direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. -- [**Mecanum steering**](../frames_rover/mecanum.md): direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. +| Rover Type | Steering | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [**Ackermann**](../frames_rover/ackermann.md) | Direction is controlled by pointing wheels in the direction of travel. This kind of steering is used on most commercial vehicles, including cars, trucks etc. | +| [**Differential**](../frames_rover/differential.md) | Direction is controlled by moving the left- and right-side wheels at different speeds (also know as skid or tank steering). | +| [**Mecanum**](../frames_rover/mecanum.md) | Direction is controlled by moving each mecanum wheel individually at different speeds and in different directions. | The supported frames can be seen in [Airframes Reference > Rover](../airframes/airframe_reference.md#rover). @@ -31,8 +33,8 @@ Rovers use a custom build that must be flashed onto your flight controller inste ::: info You can also enable the modules in default builds by adding the respective line to your [board configuration](../hardware/porting_guide_config.md) (e.g. for fmu-v6x you might add one of these lines to [`main/boards/px4/fmu-v6x/default.px4board`](https://github.com/PX4/PX4-Autopilot/blob/main/boards/px4/fmu-v6x/default.px4board)): ```sh - CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_ACKERMANN=y + CONFIG_MODULES_ROVER_DIFFERENTIAL=y CONFIG_MODULES_ROVER_MECANUM=y ``` @@ -44,8 +46,7 @@ Rovers use a custom build that must be flashed onto your flight controller inste ## Simulation [Gazebo](../sim_gazebo_gz/index.md) provides simulations for both types of steering: - -- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) - [Ackermann rover](../sim_gazebo_gz/vehicles.md#ackermann-rover) +- [Differential rover](../sim_gazebo_gz/vehicles.md#differential-rover) -![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) \ No newline at end of file +![Rover gazebo simulation](../../assets/airframes/rover/rover_simulation.png) diff --git a/zh/releases/main.md b/zh/releases/main.md index 2a17e2b07754..cbdcea2bcc1f 100644 --- a/zh/releases/main.md +++ b/zh/releases/main.md @@ -84,19 +84,19 @@ Please continue reading for [upgrade instructions](#upgrade-guide). This release contains a major rework for the rover support in PX4: - Complete restructure of the [rover related documentation](../frames_rover/index.md). -- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build) ([PX4-Autopilot#22675](https://github.com/PX4/PX4-Autopilot/pull/22675)). -- New module dedicated to [differential rovers](../frames_rover/differential.md) ([PX4-Autopilot#22402](https://github.com/PX4/PX4-Autopilot/pull/22402), [PX4-Autopilot#23430](https://github.com/PX4/PX4-Autopilot/pull/23430) and [PX4-Autopilot#23629](https://github.com/PX4/PX4-Autopilot/pull/23629)) +- New firmware build specifically for [rovers](../frames_rover/index.md#flashing-the-rover-build). +- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md): + - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode), [acro mode](../flight_modes_rover/ackermann.md#acro-mode), [position mode](../flight_modes_rover/ackermann.md#position-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). +- New module dedicated to [differential rovers](../frames_rover/differential.md): - The module currently supports [manual mode](../flight_modes_rover/differential.md#manual-mode), [acro mode](../flight_modes_rover/differential.md#acro-mode), [stabilized mode](../flight_modes_rover/differential.md#stabilized-mode), [position mode](../flight_modes_rover/differential.md#position-mode) and [auto modes](../flight_modes_rover/differential.md#auto-modes). -- New module dedicated to [Ackermann rovers](../frames_rover/ackermann.md) ([PX4-Autopilot#23024](https://github.com/PX4/PX4-Autopilot/pull/23024), [PX4-Autopilot#23310](https://github.com/PX4/PX4-Autopilot/pull/23383), [PX4-Autopilot#23423](https://github.com/PX4/PX4-Autopilot/pull/23423) and [PX4-Autopilot#23572](https://github.com/PX4/PX4-Autopilot/pull/23572)). - - The module currently supports [manual mode](../flight_modes_rover/ackermann.md#manual-mode) and [auto modes](../flight_modes_rover/ackermann.md#auto-modes). -- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md) ([PX4-Autopilot#23708](https://github.com/PX4/PX4-Autopilot/pull/23708) and [PX4-Autopilot#23834](https://github.com/PX4/PX4-Autopilot/pull/23834)). +- New module dedicated to [mecanum rovers](../frames_rover/mecanum.md): - The module currently supports [manual mode](../flight_modes_rover/mecanum.md#manual-mode), [acro mode](../flight_modes_rover/mecanum.md#acro-mode), [stabilized mode](../flight_modes_rover/mecanum.md#stabilized-mode), [position mode](../flight_modes_rover/mecanum.md#position-mode) and [auto modes](../flight_modes_rover/mecanum.md#auto-modes). - Restructure of the [rover airframe](../airframes/airframe_reference.md#rover) numbering convention ([PX4-Autopilot#23506](https://github.com/PX4/PX4-Autopilot/pull/23506)). This also introduces several [new rover airframes](../airframes/airframe_reference.md#rover): - Generic Differential Rover `50000`. - Generic Ackermann Rover `51000`. - Axial SCX10 2 Trail Honcho `51001`. - Generic Mecanum Rover `52000`. -- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules ([PX4-Autopilot#23387](https://github.com/PX4/PX4-Autopilot/pull/23387) and [PX4-Autopilot#23438](https://github.com/PX4/PX4-Autopilot/pull/23438)). +- Library for the [pure pursuit guidance algorithm](../config_rover/differential.md#pure-pursuit-guidance-logic) that is shared by all the rover modules. - [Simulation](../frames_rover/index.md#simulation) for differential-steering and Ackermann rovers in gazebo (for release notes see `r1_rover` and `rover_ackermann` in [simulation](#simulation)). - Deprecation of the [rover position control](../frames_rover/rover_position_control.md) module: Note that the legacy rover module still exists but has been superseded by the new dedicated modules.