-
Notifications
You must be signed in to change notification settings - Fork 13.5k
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
FW Attitude controller Diagram #8316
Comments
We should standardize on a particular tool and gradually get these together for all controllers. It's a fairly common request. Options that immediately come to mind are https://www.draw.io/ for simplicity or using latex that lives in the repository. I think our best chance at keeping it up to date is to have the documentation in each module, but that won't be as easy to modify. @priseborough any suggestions? |
@dagar When you say "in each module" you mean storing the image in the github tree? Or were you talking out where you render it - ie here somewhere: https://dev.px4.io/en/middleware/modules_main.html ? Does this sort of thing modify regularly - if not, then having in source is not a necessity. Using a consistent tool makes a lot of sense. I like draw.io and other web based systems a lot, but I'm not sure how we'd manage access consistently in an "open source"/free world. The "best" solution is an open source diagrammer that allows you to store the source in github (for import by anyone). Dia was my goto for that, but it is a bit dated now. Anyone tried anything else - some options http://merabheja.com/best-free-tools-for-creating-flowcharts/ |
Yes in each module means in the git tree. For example the FW attitude controller diagram would live right here in the FW attitude controller module. https://github.com/PX4/Firmware/tree/master/src/modules/fw_att_control No it doesn't change that often, but I've seen quite a few bits of documentation spreadout across other directories in git (https://github.com/PX4/Firmware/tree/master/Documentation), various hosted services, old wiki, discuss posts, now the new wiki, etc. Ultimately I think it needs to live right in the source next to the thing it's describing. It can and should still be posted to the dev guide, but this would be the source. |
There is definitely a problem there, but the solution is arguable. I look at https://github.com/PX4/Firmware/tree/master/Documentation and see unmanaged documentation that no one is likely to discover until too late, which has no clear owner, which may be out of date, which has not context. IMO all of that should be moved into the devguide and the directory removed. In some cases it can be useful to keep the docs alongside source, but it still should go into our guides. via some form of import. If it isn't in the guides then we should work to remove it - that includes old wikis, but probably not old discussion boards. Lets review those docs and get them at least well linked from the Devguide - and ideally moved: PX4/PX4-Devguide#355 |
We should definitely have controller diagrams on the dev-guide. If they're kept high-level they don't change often. FYI @Stifael |
Is it possible to have the controller block diagram held with the source with links in the dev guide? Many of our controllers (eg TECS) are in libraries. I would not expect architecture diagrams to change often. |
@hamishwillee @dagar I agree with @priseborough that this diagrams does not change very often and in the future they will change even less. So why make it harder to maintain with a lot of tools etc. Placing a simple JPG with the diagram is fair enough. I could do the diagrams in a couple of days with the Corel and I could make them look pretty catchy. We need not more than 4-5 diagrams for the different aspects of the controller. BTW APM did it with the very basic black and white look but you get the concepts right away. |
@hamishwillee We could create a separate section called PX4 Controller Diagrams and place all the diagrams at one place. There are only certain people that need them and this way it will be much easier to find what you need with the rule of the "three clicks". Arranged this way google will make a good indexing as well and it will pop up in the search right away. |
If somebody can sketch the diagrams on paper, I will start making them digital. I could not find any diagram except this. BTW this diagram was dug deeper in a gitter chat and google search found it right away when I searched for the FF gain of PX4. |
Thanks all!
Generally a documentation set looks better if text and diagramming is consistent. As not everyone has Corel it is better to have images that aren't too funky :-) Upshot, keep it simple - use the basics. Add colour and funkyness where it adds to clarity.
I agree with this grouping, at least initially (if we had any documentation about individual controllers then splitting by controller would make sense) But where in the structure should this live - we don't actually have much real information about controllers? This isn't middleware. We could do (one of)
The whole devguide structure is going to get revisited, so open to ideas. |
I will do a quick sketch of the current position controller for @tubeme. However, it should be possible to modify the diagram at some later stage, because the position controller might change slightly. For instance, feedforward could become part of the position controller as well. If the devguide gets split into middleware and flightstack, then the controllers should live within flightstack |
note: There is also a line drawn right after v_d. This line is there because depending on the mode, the P-ctrl can be skipped where the velocity sepoints are generated either from stick inputs or through offboard let me know if it needs more clarification |
@tubeme Here is some work done a few month ago. It's quite accurate: http://discuss.px4.io/t/position-and-attitud-controllers-diagram/3186 |
@Stifael @bresch Thanks I will start making them in Corel. I will make them in one style, pretty simple one @hamishwillee without blink blink :). I will keep the CDR sources so we could change them with time. Probably we could create a space somewhere to keep the CDR files so they are available for future edit. @bresch I see this graph is from the MC ATT controller. How about the FW ATT controller. There is no D in the FW so there should be some difference. We noticed that the FF gain in the FW controller have connection to the whole PI chain. Ie. if we lower the FF too low, the ATT becomes sluggish and not adequate enough for good stabilization. Increasing the FF gain gives much better stabilization? Any ideas? |
Thanks all.
@tubeme Thanks!
Good idea. If they aren't huge we could reasonably put them in the gitbook assets alongside the generated image. |
@tubeme Indeed, for the FW controller, the attitude loop uses a proportional gain only (P-controller) and the rates loop uses a PI-controller with feedforward: |
@bresch It might be useful to capture some of that information (#8316 (comment)) alongside the image :-) |
@hamishwillee Here is the first diagram. If you like the style I will continue with the rest. @bresch Which diagram to use from the link you gave me ( http://discuss.px4.io/t/position-and-attitud-controllers-diagram/3186). There are couple of diagrams? Can you provide me with legend of the parameters? Do you have a diagram of your explanation about the FW controller and the FF gain, how does it differ from the MC implementation? Thanks @Stifael can you take a look to see if I got that correct? |
@tubeme Yes, I'll check and give you the corresponding parameters. About the diagram you just did:
|
@tubeme Awesome! Is there a way to allow to edit this in a cloud tool, like draw.io? |
@tubeme Yes looks great :-). It displays pretty well in gitbook too!
So what documentation should accompany this? The information above from bresch would seem useful. Other ":thoughts"
|
@tubeme looks good. I think you forgot the position estimate label which is subtracted from the desired position setpoint. I have some comments about documentation for math related implementation. NomenclatureThere are quite a lot of math symbols used in px4, and I am sure the amount of symbols will rather increase than decrease. Therefore I suggest to have a full list of Symbols within the documentation. This list would also include acronyms and abbreviations such as MPC, MC and so on. NotationIn the position control diagram I labeled vectors with an arrow. I only did that because that was the most obvious, easiest way to label a vector when drawing something by hand. However, for a documentation purpose it might be better to find a different kind of notation, such as having vectors boldface and scalars non-boldface. The really important part, however, is to be consistent with all symbols. I attached my own Nomenclature and Notation as example. |
@Stifael Could not agree more. Are you happy for us to steal your nomenclature and notation as a starting point for PX4?
What do you think would be the best thing to do in this case? |
Of course |
Thanks all let me think with all the info and I will post you with the idea about notations and nomenclature. |
@hamishwillee @Stifael @tubeme I started to write a glossary containing symbols and acronyms useful in the context of PX4. I've been highly inspired by several aeronautic, control and robotics books I read and try to avoid confusion in the notation as much as possible. |
@bresch @Stifael Probably best if those of you with more experience in using these symbols decide if you're happy with the set.
With respect to the acroymns, we can probably add them to the gitbook glossary. Care needs to be taken to limit that glossary size because Gitbook will actually cross link all the items, and as you can imagine the more you have the slower the process is. Eventually it will also fall over. |
@hamishwillee Thanks for your answer.
I merged the Latin and Greek together, it's true that it's not really useful to make two different sections for this.
Units are a good idea, I'll add them. About the gitbook glossary let me check, I never used it so far. |
I have. It is very limited, and massively slows builds. Only matters to those of use who work locally, but is a complete pain. It is just an option. We can have a glossary without using Gitbook functionality. |
@tubeme Any ETA on next iteration/Is this waiting on me/others for anything? The discussion of the maths is just as important as the diagram. I've also had a request to capture the information about how the controllers work in a webinar format. If you guys are interested in helping with that, please email me hamishwillee at gmail dot com, or catch me on slack (hamishwillee) |
Are we with these on draw.io yet? We need a workflow where control engineers can alter the diagram with minimal friction. |
@tubeme Would you like me to copy your diagram to draw.io for iteration - just to speed the process and make easier for anyone/everyone to edit? |
Appreciate you are busy. But if you don't respond I'll move what you have done across so we can continue progressing this. |
Questions:
@bresch Could you update those things you believe to be errors - and the multiplexer you referred to? If you have questions/undecided for me/us then can you raise again? Rationalising NomenclatureIMO we use SI and other "standard" symbols where possible. @Stifael as you are familiar with your nomenclature set, can you see any discrepencies from your set and @bresch set here - I picked you to review because his set is much smaller.
|
At the end it depends on the nomenclature that we define on. However, the nomenclature and style for the above diagram is most likely not the final solution. For instance, we definitely need to use subscripts. |
@Stifael Draw.io has a latex plugin, it is enabled, and that is what I am using in that image. To use it you just put the text in back ticks. There is a draw.io example here Subscripts work fine using _ , superscripts work with ^ .. sometimes you need to be tricky with ( ) to apply them properly. Could you please modify the image as you would prefer it to be based on what you and bresch believe is the right thing? |
@hamishwillee Thanks for the effort! I modified the diagram to match the glossary I made. Please @Stifael , tell me if there is anything you don't like or if you see a mistake. |
Thanks @bresch - looks good:
@Stifael Are you OK with this? If this is OK, then we're at a good point to decide what words should go with the diagram. Perhaps an explanation of anything that might not be clear from the diagram - where the inputs come from, where the outputs go to. As discussed above let's put them in "Controller Diagrams". Would these be better grouped under a parent of "Concepts", "Flight Stack" or "Architecture"? |
Yes.
It obviously needs to have a globally accepted px4 nomenclature and notation. @bresch, what is the standing of the nomenclature document that you have been working on?
Yes and no. It depends on what we define in the nomenclature. However, ^ is widely used in academia to indicate estimate.
I also lean towards Concepts. |
Corrected. I also added
As Dennis said, it is widely used in academia and in most estimation and control books
It might be worth mentioning that:
|
I made minor change to the index because the ( ) looked like a symbol - (). OK?
It would be good to provide good links to information, tutorials, videos about the standard loop. Anything you recommend?
Absolutely. I think that the comments @bresch has made are about the right level but that is something for you to resolve.
Whatever you guys propose will be the globally accepted "version 1". Lets get it in and iterate as needed. |
Sure, I can do that. What is the next step? I can add links, explanation and so on once I know where to put them. |
@Stifael I've created a branch on the devguide you should be able to contribute to - see the PR here: PX4/PX4-Devguide#400 This has placeholders for the notation and an "initial" spot for the diagrams. Don't feel the structure is fixed - I just wanted to kick off the discussion/iteration. After reviewing and adding to it, the next-next step is to mock up the other controller diagrams. Volunteers to either do direct in draw.io, or sketch for me to do first iteration? |
OK, Notation added from @bresch in PX4/PX4-Devguide#411. Controller diagram already in devguide here - everyone OK with this location and text? @Stifael What next? Can we have another sketch for FW position controller? What about attitude controllers? |
yep. I added comments for notation and if ok I will just do a PR for PX4/PX4-Devguide#411.
@bresch knows better.
I will do a PR for the attitude controller. |
@bresch Are you happy to create a sketch for the FW position controller - ideally direct on draw.io, but if you want to sketch it out on paper and I can do first iteration on draw.io that would be OK too. Are there any other controllers that need to be documented? I think it is just the attitude control for MC, FW and VTOL? |
Hello, is there something still incomplete, or this issue is fixed and could be closed? I am curious because the FW controller diagram seems to be published at DevGuide already. BTW, I got there through I looking for px4_fw_attitude_controller_diagram.png because I need to modify it for autogyro controller diagram. I had no success, therefore, I create the new diagram in Dia. But here I noticed you have to use the www.draw.io. Therefore I probably redraw my controller diagram to meet this standard. But I think it should be noted in a readme in the DevGuide assets directory because finding a source of the diagram is quite complicated. |
@kaklik This is now done, as you say, in https://dev.px4.io/en/flight_stack/controller_diagrams.html#fixed-wing-attitude-controller We still need VTOL diagrams and FW position controller, but that is not this issue. We have used draw.io because it generates slightly better output than dia, and doesn't require any extra tools. The theory is that the link is embedded in source near diagram. If you want to put a PR for a readme in the assets directory with links to resources I'll accept it, but I don't consider it personally high enough priority/best use of time. |
Hi guys,
We are are trying to get better understanding of the FF gains in the FW flight. I saw a old diagram from @Tumbili for the attitude controller but could not find it anywhere in the dev guide or other place. Any ideas? If there is no such diagram created with graphic tools I could create them for the dev guide and provide them to @hamishwillee
The text was updated successfully, but these errors were encountered: