Differential Drive Documentation

en/config_rover/configure_rover_differential.md

@@ -0,0 +1,83 @@
+# Differential Drive Rover Configuration & Tuning
+
+This is the configuration document for a [Differential Drive Rover](../airframes/airframe_reference.md#rover_rover_aion_robotics_r1_ugv), this rover type is very similar to also known as "Tank Drive & Skid Steer". This type of rover control type is essentially what you would find in a modern robot vacuum cleaner, also known as a "Roomba". 
+
+## Firmware & Basic Settings 
+
+1. Run _QGroundControl_
+2. Flash the firmware for your current release or master (PX4 `main` branch build).
+3. In the [Frame setup](../config/airframe.md) section select the appropriate Rover airframe.
+
+### Configuration Parameters
+
+Proper configuration of the rover's parameters is crucial for optimal control and stability. The parameters are divided into different categories based on their purpose.
+
+#### Geometric Parameters
+
+- `RDD_WHEEL_BASE`: This parameter defines the distance between the centers of the left and right wheels. It is a critical parameter for the inverse kinematics calculations used to translate the desired linear and angular velocities into individual wheel speeds.
+
+- `RDD_WHEEL_RADIUS`: This parameter specifies the radius of the rover's wheels. Along with the wheel base, it is used in the inverse kinematics calculations to determine the appropriate wheel speeds for a given desired motion.
+
+#### Motion Constraints
+
+- `RDD_MAX_JERK`: This parameter limits the rate of change of acceleration/deceleration, resulting in smoother motion profiles and reducing the risk of sudden jerks or oscillations.
+
+- `RDD_MAX_ACCEL`: This parameter sets the maximum acceleration (in meters per second squared) for the rover, limiting the rate at which the rover can increase or decrease its speed.
+
+Proper configuration of these parameters is essential for achieving the desired performance and stability of the Differential Drive Rover. The geometric parameters define the rover's physical characteristics, while the speed parameters control the maximum attainable velocities. The control gains dictate the responsiveness and accuracy of the control system, and the motion constraints ensure smooth and safe operation.
+
+### Control Structure
+
+![alt text](../../assets/config/rover/rover_control.png)
+
+In this control structure, the user can choose between three sources for the setpoints, all of which use the [DifferentialDriveSetpoint](../msg_docs/DifferentialDriveSetpoint.md) message:
+
+1. Manual setpoint
+2. Mission setpoint
+3. ROS2 setpoint
+
+The `DifferentialDriveSetpoint` message includes:
+
+- `speed` (float32): Collective roll-off speed in body x-axis [m/s]
+- `closed_loop_speed_control` (bool): True if speed is controlled using estimator feedback, false if direct feed-forward
+- `yaw_rate` (float32): Yaw rate [rad/s]
+- `closed_loop_yaw_rate_control` (bool): True if yaw rate is controlled using gyroscope feedback, false if direct feed-forward
+
+Regardless of the source (manual, mission, or ROS2), the setpoints (`v, ω, flags`) are sent through the `DifferentialDriveSetpoint` message to the PI controllers. The controlled setpoints (`v', ω'`) are then passed to the inverse kinematics module, which calculates the wheel angular velocities (`θl, θr`) for the left and right wheels, respectively. These wheel angular velocities are used to control the left and right motors.
+
+### Tuning Guide
+
+Once the basic configuration is complete, you may need to fine-tune the control gains and motion constraints to achieve the desired performance. The tuning process involves adjusting the parameters based on empirical testing and observing the rover's behavior in various scenarios.
+
+#### Manual Control Tuning
+
+The following parameters allow you to adjust the maximum speed and angular velocity of the rover during manual control:
+
+- `RDD_SPEED_SCALE`: Scales the maximum forward/reverse speed. A value of 1 represents the maximum configured speed, while lower values limit the top speed.
+
+- `RDD_ANG_SCALE`: Scales the maximum angular (rotational) velocity. A value of 1 represents the maximum configured angular velocity, while lower values limit the maximum rotation rate.
+
+- `RDD_WHEEL_SPEED`: Sets the maximum wheel speed in radians per second, which is used to calculate the rover's maximum linear and angular velocities based on the wheel radius and wheelbase.
+
+These parameters can be adjusted to suit your needs, such as reducing the maximum speed or angular velocity for increased control or safety.
+
+#### Controller Tuning
+
+The following parameters control the gains of the Proportional-Integral (PI) controllers responsible for maintaining the desired heading, speed, and angular velocity:
+
+- `RDD_P_HEADING`: Proportional gain for the heading controller, adjusting the rover's rotation rate to maintain the desired heading.
+
+- `RDD_P_SPEED`: Proportional gain for the speed controller, adjusting the rover's linear velocity to maintain the desired speed.
+
+- `RDD_I_SPEED`: Integral gain for the ground speed controller, helping to eliminate steady-state errors in the rover's linear velocity.
+
+- `RDD_P_ANG_VEL`: Proportional gain for the angular velocity controller, adjusting the rover's rotation rate to maintain the desired angular velocity.
+
+- `RDD_I_ANG_VEL`: Integral gain for the angular velocity controller, helping to eliminate steady-state errors in the rover's rotation rate.
+
+To tune the controller gains, it is recommended to measure the step responses and adjust the PI gains to achieve the desired performance. Higher proportional gains will increase the responsiveness but may lead to overshoot and oscillations, while higher integral gains can help eliminate steady-state errors but may cause instability if set too high.
+
+It's crucial to consider the characteristics of the terrain, payload, and environmental conditions when tuning the parameters for optimal performance. Extensive testing in different environments and scenarios is recommended to ensure the rover's behavior meets your requirements.
+
+
+

en/flight_modes_rover/manual_rover.md

@@ -0,0 +1,61 @@
+# Manual Mode (Rover)
+
+<img src="../../assets/site/difficulty_medium.png" title="Medium difficulty to fly" width="30px" />&nbsp;<img src="../../assets/site/remote_control.svg" title="Manual/Remote control required" width="30px" />&nbsp;
+
+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.
+
+:::note
+This rover mode is enabled if you set _Manual_ mode.
+::: 
+
+(**Differential Drive Rover**) When under manual control the throttle and roll sticks control the _speed_ and _yaw rate_ of the vehicle. 
+
+(**Ackermann Drive Rover**) When under manual control the throttle and roll sticks control the _thrust_ and _torque_ of the vehicle. 
+
+## Technical Description (Differential Drive)
+
+### Manual Mode
+
+In manual mode, the left and right joystick/stick inputs directly control (open-loop) the rover's forward speed and yaw rate (rotation rate), respectively. The rover does not attempt to maintain a specific position or heading but instead responds directly to the user's inputs, without any closed-loop feedback control.
+
+![Rover Manual Sticks](../../assets/flight_modes/manual_differential_rover_new.png)
+
+- Left Stick:
+ - Centered: Rover stops moving forward/backward.
+ - Pushed forward: Rover moves forward, with speed increasing as the stick is pushed further.
+ - Pulled backward: Rover moves in reverse, with speed increasing as the stick is pulled further back.
+
+- Right Stick:
+ - Centered: Rover maintains its current heading and does not rotate.
+ - Pushed left/right: Rover rotates counter-clockwise/clockwise, with the rotation rate increasing as the stick is pushed further in that direction.
+
+The 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.
+The left stick input directly maps to the forward component of the wheel speeds, while the right stick input maps to the differential component between the left and right wheel speeds for rotation.
+
+It's important to note that in this manual mode, 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.
+
+### Acro Mode
+
+Acro Mode is similar to Manual Mode, but with a closed-loop yaw rate control. In this mode, the left stick input remains open-loop for forward speed control, while the right stick input commands a desired yaw rate setpoint, which is then maintained by the rover's closed-loop control system.
+
+- Left Stick:
+Behavior remains the same as in Manual Mode, directly controlling the rover's forward speed in an open-loop manner.
+- Right Stick:
+ - Centered: Rover stops rotating and tries to maintains its current heading.
+ - Pushed left/right: Rover rotates counter-clockwise/clockwise at the rate commanded by the stick input, using a closed-loop controller (e.g., PID) to try to ensure the vehicle yaw rate matches the given setpoint.
+
+<a id="params"></a>
+
+## Parameters (Differential Drive)
+
+| Parameter | Description |
+| -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+
+| <a id="RRD_SPEED_SCALE"></a>[RRD_SPEED_SCALE](../advanced_config/parameter_reference.md#RRD_SPEED_SCALE) | Scales the speed output of the rover by multiplying it with this parameter to adjust for too high manual open-loop speeds. |
+
+| <a id="RRD_ANG_SCALE"></a>[RRD_ANG_SCALE](../advanced_config/parameter_reference.md#RRD_ANG_SCALE) | Scales the angular velocity output by multiplying it with this parameter, allowing for adjustments in the rover's manual open-loop turning speed. |
+
+