Rover: Update documentation #3377

chfriedrich98 · 2024-09-13T07:58:12Z

Update the rover docs to reflect the changes in the following PRs:

This PR the following improvements to the rover docs:

Restructure Drive Modes into Auto and Manual modes.
Major update to the documentation of differential rovers. The differential module received some big updates with the support for new manual modes (Stabilized and Position). Due to these new modes the tuning process for differential rovers can be streamlined which is now documented in detail as a step by step guide going through the parameters/setup for each mode. Each mode successively adds more autopilot support (Manual > Acro > Stabilized > Position > Auto) and with it more parameters to set. The user guide now also includes tips/suggestions on how to tune the individual parameters, making it easier to set up the vehicle.
Updated all graphics with a common color theme that works in both dark and light mode.

chfriedrich98 · 2024-09-13T08:24:21Z

Note: This PR is ready for review, but merging it will have to wait until PX4/PX4-Autopilot#23669 is merged.
This will also fix the missing anchor for RD_MAX_SPEED.
PR was merged.

hamishwillee · 2024-09-18T00:28:53Z

en/frames_rover/differential_rover.md


 ::: info
-The parameter [RD_MAN_YAW_SCALE](../advanced_config/parameter_reference.md#RD_MAN_YAW_SCALE) can be used to scale the manual input for the yaw rate.
+The parameter [RD_MAN_YAW_SCALE](#RD_MAN_YAW_SCALE) can be used to scale the manual input for the yaw rate.


IMO this should be moved to the first step of tuning, and have a bit more of an explanation.

github-actions · 2024-09-18T00:45:42Z

/en/frames_rover/ackermann_rover.md

LinkedFileMissingAnchor: #manual-mode not found in ../flight_modes_rover/index.md (/home/runner/work/PX4-user_guide/PX4-user_guide/en/flight_modes_rover/index.md)
LinkedFileMissingAnchor: #mission-mode not found in ../flight_modes_rover/index.md (/home/runner/work/PX4-user_guide/PX4-user_guide/en/flight_modes_rover/index.md)
LinkedFileMissingAnchor: #pure-pursuit-guidance-logic not found in ../flight_modes_rover/index.md (/home/runner/work/PX4-user_guide/PX4-user_guide/en/flight_modes_rover/index.md)

hamishwillee · 2024-09-18T01:07:33Z

en/flight_modes_rover/manual.md

+This mode requires a yaw rate estimate.
+:::
+
+Acro Mode is similar to [Manual mode](#manual-mode), but with closed-loop yaw rate control.


Start with the dummies version to give a "feel. Something like (I assume this is the point)

Suggested change

Acro Mode is similar to [Manual mode](#manual-mode), but with closed-loop yaw rate control.

Acro Mode is similar to [Manual mode](#manual-mode) except that closed-loop yaw rate control is used to maintain a yaw rate setpoint, which improves cornering behaviour, and makes it easier to maintain a straight line.

Same for the rest.

hamishwillee · 2024-09-18T01:11:25Z

en/flight_modes_rover/manual.md

+| Mode                           | Features                                                                                                   |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| [Manual](#manual-mode)         | Directly map stick inputs to motor commands, no closed loop control.                                       |
+| [Acro](#acro-mode)             | Closed loop yaw rate control.                                                                              |


Three column table showing what is supported for Differential, Ackermann, Features? (like your other table)

What are open loop and closed loop yaw rate control? (Hint, I do know, but the readers may not, and for most of this should not need to).

For this whole doc, the audience here is as far as possible a high school kid. Assume they know as little as possible about control theory as possible. Minimally it should start with this assumption, and only go to the detail when you absolutely have to. You can look at the FC and MC docs for inspiration.

You want to give a flavour to what this means for driving - i.e. how does closed loop yaw rate control make acro "better" than manual.

This is like the dummies version I mention below https://github.com/PX4/PX4-user_guide/pull/3377/files#r1764257980

"Yaw rate is controlled, providing better cornering ..."

Or do both

"Closed loop yaw rate control (holds line better when cornering)

Hope that makes sense (and is acheivable)

hamishwillee · 2024-09-18T01:19:51Z

en/flight_modes_rover/manual.md

+
+This is the most advanced manual mode. It uses _closed loop yaw rate control_, _closed loop speed control_ and a special logic for driving a straight line when there is no yaw rate input.
+
+In this mode, moving the left-stick up/down commands a desired speed setpoint, and moving the right-stick left and right commands a desired yaw rate setpoint which are both close-loop controlled by the autopilot.


What does setting a speed setpoint do for you in terms of changing the driving? Presumably if cornering the speed will adjust for the yaw setpoint?

Did you consider using an accel. setpoint? Matthias changed the MC position mode to this to make it "more like driving" - this seems less like driving.

hamishwillee · 2024-09-18T01:23:16Z

en/flight_modes_rover/manual.md

+This mode requires a yaw rate, yaw, speed and position estimate.
+:::
+
+This is the most advanced manual mode. It uses _closed loop yaw rate control_, _closed loop speed control_ and a special logic for driving a straight line when there is no yaw rate input.


"This is the most advanced manual mode. " - true but what do you mean by advanced? Or to put it another way, in MC we order from easiest/safest/most controlled to hardest/least controlled. The point being that for users we're assuming they want to start safe and work up to hard so we introduce the safest mode first.

This also affects the dummy version explanation. Who is this mode for?

hamishwillee · 2024-09-18T01:26:03Z

en/flight_modes_rover/manual.md

+
+- [**Differential Rover**](../frames_rover/differential_rover.md): Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _yaw rate_ of the vehicle.
+
+- [**Ackermann Rover**](../frames_rover/ackermann_rover.md): Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle.


This is true for all modes right? The difference is that in some modes you do closed loop control over the rate/angle?

hamishwillee · 2024-09-18T01:26:17Z

en/flight_modes_rover/manual.md

+| ------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| [Manual](#manual-mode)         | Directly map stick inputs to motor commands, no closed loop control.                                       |
+| [Acro](#acro-mode)             | Closed loop yaw rate control.                                                                              |
+| [Stabilized](#stabilized-mode) | Closed loop yaw rate and yaw control.                                                                      |


Ditto - the "both" might be

Suggested change

| [Stabilized](#stabilized-mode) | Closed loop yaw rate and yaw control. |

| [Stabilized](#stabilized-mode) | Closed loop yaw rate and yaw control (holds direction better when yaw is not applied). |

hamishwillee · 2024-09-18T01:27:18Z

en/flight_modes_rover/manual.md

+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.


Ah, the dummies version! This is what we want first! Does not have to be in an info box.

hamishwillee · 2024-09-18T01:29:44Z

en/frames_rover/differential_rover.md

+### Acro Mode
+
+To set up [Acro mode](../flight_modes_rover/manual.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters:


For all modes, at this point a reader doesn't know what acro mode is, so it wouldn't be obvious why/when you would do this. I would prefix each section with a one line summary about the mode. Something like:

Suggested change

### Acro Mode

To set up [Acro mode](../flight_modes_rover/manual.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters:

### Acro Mode

[Acro mode](../flight_modes_rover/manual.md#acro-mode) is a minimally stabilised mode where the vehicle attempts to hold its rate of turn (but does not stablise heading or speed).

To set up this mode navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters:

hamishwillee · 2024-09-18T01:35:32Z

en/flight_modes_rover/manual.md

+:::
+
+::: info
+This mode requires a yaw rate estimate.


For MC we needed up-front information about the modes, such as requires GPS, because a vehicle might not have GPS.
But why does a user need to know this up front? I would say it is detail you would only add if we have lots of things that are preconditions, and even so, that box would appear after the "for dummies" explanation of the mode.

hamishwillee · 2024-09-18T01:43:11Z

@chfriedrich98 Thanks for this

I've added a lot of notes, mostly about tailoring for audience. I think you need to present this as high level as possible first, so that anyone can determine the main point with very little understanding of control theory.
Really love the diagrams
New structure makes a lot of sense, at least for now. I do wish the tuning could go in flight mode docs, but I think this will always be hard since the tuning depends on the vehicle. We might in future create a stand-alone tuning doc for each rover type.
In terms of subediting, most of this is docs-consistency:
- I use sentence breaks for lines.
- I refer to mode as Position mode with that casing.
- The "note" type is not supported - we have to use info or tip for these.
- I added back an image you deleted. Ignore it for now - this is because it breaks the translation builds if this does not exist, and I can't fix that yet due to a problem in our translation tool. They are working on it.

PS YOu might not agree with all this, or it might not all be practical. But let's see what you think - compromise is possible :-)

hamishwillee · 2024-09-18T01:53:24Z

en/flight_modes_rover/manual.md

+
+## Acro Mode
+
+<Badge type="tip" text="Differential" />


FYI I added badging to show what is supported, and the warning below to note what is not supported.

chfriedrich98 added 2 commits September 13, 2024 09:44

rover: update documentation

575825b

fix links

b8819e8

chfriedrich98 self-assigned this Sep 13, 2024

chfriedrich98 requested a review from hamishwillee September 13, 2024 08:59

further improvements

2d17059

chfriedrich98 force-pushed the rover_docs_update branch from 1a9fd80 to 2d17059 Compare September 16, 2024 14:39

chfriedrich98 and others added 2 commits September 17, 2024 08:49

Merge branch 'main' into rover_docs_update

f74a15c

Restore manual_inputs.png temporarily

9883327

hamishwillee reviewed Sep 18, 2024

View reviewed changes

Subedit

183afc8

hamishwillee reviewed Sep 18, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rover: Update documentation #3377

Rover: Update documentation #3377

chfriedrich98 commented Sep 13, 2024 •

edited

Loading

chfriedrich98 commented Sep 13, 2024 •

edited

Loading

hamishwillee Sep 18, 2024 •

edited

Loading

github-actions bot commented Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024 •

edited

Loading

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee Sep 18, 2024

hamishwillee commented Sep 18, 2024 •

edited

Loading

hamishwillee Sep 18, 2024

	Acro Mode is similar to [Manual mode](#manual-mode), but with closed-loop yaw rate control.
	Acro Mode is similar to [Manual mode](#manual-mode) except that closed-loop yaw rate control is used to maintain a yaw rate setpoint, which improves cornering behaviour, and makes it easier to maintain a straight line.


		This is the most advanced manual mode. It uses _closed loop yaw rate control_, _closed loop speed control_ and a special logic for driving a straight line when there is no yaw rate input.

		In this mode, moving the left-stick up/down commands a desired speed setpoint, and moving the right-stick left and right commands a desired yaw rate setpoint which are both close-loop controlled by the autopilot.


		- [Differential Rover](../frames_rover/differential_rover.md): Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _yaw rate_ of the vehicle.

		- [Ackermann Rover](../frames_rover/ackermann_rover.md): Moving the left-stick up/down controls the _forward speed_ and moving the right-stick left/right controls the _steering angle_ of the vehicle.

	\| [Stabilized](#stabilized-mode) \| Closed loop yaw rate and yaw control. \|
	\| [Stabilized](#stabilized-mode) \| Closed loop yaw rate and yaw control (holds direction better when yaw is not applied). \|

		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

		To set up [Acro mode](../flight_modes_rover/manual.md#acro-mode) navigate to [Parameters](../advanced_config/parameters.md) in QGroundControl and set the following parameters:

Rover: Update documentation #3377

Are you sure you want to change the base?

Rover: Update documentation #3377

Conversation

chfriedrich98 commented Sep 13, 2024 • edited Loading

chfriedrich98 commented Sep 13, 2024 • edited Loading

hamishwillee Sep 18, 2024 • edited Loading

Choose a reason for hiding this comment

github-actions bot commented Sep 18, 2024

Choose a reason for hiding this comment

hamishwillee Sep 18, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hamishwillee commented Sep 18, 2024 • edited Loading

Choose a reason for hiding this comment

chfriedrich98 commented Sep 13, 2024 •

edited

Loading

chfriedrich98 commented Sep 13, 2024 •

edited

Loading

hamishwillee Sep 18, 2024 •

edited

Loading

hamishwillee Sep 18, 2024 •

edited

Loading

hamishwillee commented Sep 18, 2024 •

edited

Loading