Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Multicopter PID Tuning Cookbook reformulation #2113

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

junwoo091400
Copy link
Contributor

Need

There are quite a few cases where a big multicopter crashed because the operator simply didn't have a good guide on how to tune the PID values.

Multicopter experts like @MaEtUgR can of course tune them properly, but this isn't well documented in our current docs, and can often lead users into confusion as the structure isn't sound.

This PR aims to bring a major reformulation on the current Multicopter PID tuning guide.

Value Proposition

Existing guide suffers from the following problems:

  1. Topics are too scattered (User doesn't know where to start, as advanced / manual topics are listed without priority)
  2. Actual tuning guide isn't in a bad form, but it only covers rate tuning and completely disregards attitude/velocity/position tuning part
  3. The procedure is not in a cookbook form (i.e. User has to go back and forth in the document to know exactly what to do)

Therefore, this PR aims to bring in:

  1. Singular cookbook style guide that guides user from start to finish (from Hardware to Software), on how to properly do the PID tuning of a Multicopter
  2. Add all the necessary details user needs to know on each step, to make the guide complete

Other

For details, refer to the multicopter tuning guide reformulation document.

@hamishwillee
Copy link
Collaborator

I'll review this when you mark it as ready to review.

  • I agree that after the autotuning doc the tuning path is not clear.
  • Yes, we also don't cover the other kinds of tuning well (though they are far less important). It would be great to get more howto on those.
  • It is also not particularly clear when you need to think about auto tuning vs manual vs advanced.

A few thoughts:

  1. Renaming docs breaks external links. Is it worth it?
  2. I'm not a particular fan of the cookbook format. The assumption is so often that you need to do everything - and in this business you do not always need to do so. The result is often a monolithic document that no one can digest.
    That said, do it how you like - if the information is present but the format doesn't work we can chop it up again after.
  3. The actual entry point to tuning is https://docs.px4.io/main/en/config/autotune.html . It is important to position things because not all tuning is equal. A cookbook that goes end to end is great, but make it clear what is core and what is garnish.
  4. The advanced tuning is not so much "Advanced" as "provides a lot of description on how tuning works conceptually", whereas the current simple guide is more "follow these instructions". What is actually useful steps not captured in here is the airmode stuff.
    • Not sure how we keep the useful advanced guide in the context of your tuning cookbook
    • But I would put airmode stuff out of the "advanced". It is hidden there.

Thanks for taking this on. I would never have got to it.

@junwoo091400
Copy link
Contributor Author

Renaming docs breaks external links. Is it worth it?

This was done temporarily to make reviewing easier, as the diff is cleaner

I'm not a particular fan of the cookbook format. The assumption is so often that you need to do everything - and in this business you do not always need to do so. The result is often a monolithic document that no one can digest.

Having huge docs is of course bad! With this cookbook, I want to have a clear hyperlinks in the beginning and have the user be able to go to the section they are interested in & get all the relevant information.

Maybe splitting the doc into rate / attitude / velocity / position controller, etc would be nice as well. But since current doc is really not ideal for a person who really wants to tune a vehicle, this is just a starting point 👍

@junwoo091400 junwoo091400 force-pushed the pr_multicopter_pid_tuning_docs_improvement branch from 8393698 to 9c7ccdb Compare January 9, 2023 17:49
@junwoo091400
Copy link
Contributor Author

Rebased

part

Rename pid_multicopter to pid_multicopter_cookbook for easier Review

- Previous file was interfering the view in the diff of the PR, this
renames the file so that there's a clear *new-file indicator, instead of
a diff, since this is in principle, a new file
- As the PR gets merged, this file should be rename back to original, to
restore linked connections from other docs
@junwoo091400 junwoo091400 force-pushed the pr_multicopter_pid_tuning_docs_improvement branch from 9c7ccdb to ce9144c Compare January 9, 2023 17:50
@junwoo091400 junwoo091400 force-pushed the pr_multicopter_pid_tuning_docs_improvement branch from aea98ef to 7d03541 Compare January 9, 2023 18:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants