FW Attitude controller Diagram

[tubeme]

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

[hamishwillee]

@bkueng Thoughts on this?
@tubeme Where would you put this in the guide?

[dagar]

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?

[hamishwillee]

@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/

[dagar]

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.

[hamishwillee]

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

[bkueng]

We should definitely have controller diagrams on the dev-guide. If they're kept high-level they don't change often.

FYI @Stifael

[priseborough]

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.

[tubeme]

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

[tubeme]

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

[tubeme]

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.

https://gitter.im/PX4/VTOL/archives/2015/05/22

[hamishwillee]

Thanks all!

1. Yes it is possible and easy to keep the images in source, but I would prefer not to do this. It is better to maintain all the docs in one place, if only so that people know what will be affected by moving, deleting or whatever the image.

   • In the general case I am pragmatic - if an image had to belong in source we would live with it.

2. @tubeme Thanks for offering to do the images.

   • @dagar @Stifael @bkueng Can you sketch them out for Vasil, or point me to best people to ask for help?

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.

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.

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

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)

• Concepts > Controllers > Controller Diagrams
• Flight Stack > Controllers > Controller Diagrams

The whole devguide structure is going to get revisited, so open to ideas.

[Stifael]

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

[Stifael]

note:
P-ctrl = proportional controller (not position controller)
PID-ctrl = proportional, integral, derivative controller

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

[bresch]

@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

[tubeme]

@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?

[hamishwillee]

Thanks all.

1. Presumably the different gains etc map to parameters.(?). I assume it would be useful to map these to the diagrams? If so:
   • propose do this in the document outside of the diagram
   • Can I have the mapping :-)
2. Can I have the list of controllers that we aim to create? ... so we can make sure they all get done.

@tubeme Thanks!

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.

Good idea. If they aren't huge we could reasonably put them in the gitbook assets alongside the generated image.

[bresch]

@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:
https://github.com/PX4/ecl/blob/b0300b97235d4c5907bd1ad8878550540403c933/attitude_fw/ecl_roll_controller.cpp#L130-L132
The feedforward isn't directly affecting the PI loop but improves a lot the tracking. Let's take for example a roll maneuver: moving the ailerons produces a torque around the longitudinal axis that accelerate the body. As the rollrate increases, the roll damping contribution will limit the maximum rollrate with the current deflection. (Ultra-simplified, the roll moment is: L = C_ld*aileron - C_lp*rollrate)
The I term of the controller might be able to handle this, but using integral for normal operation is never a good solution. The better approach is then to use a feedforward that will directly deflect the ailerons with roughly the correct amplitude and the PI-controller will just need to compensate for errors.
Furthermore, on an aircraft, the roll damping derivative term is usually so high that even without a PI-controller (Attitude loop directly controlling the ailerons) you might not see a big difference. That's also why piloting manually an aircraft feels more like piloting in rates than in acceleration.

[hamishwillee]

@bresch It might be useful to capture some of that information (#8316 (comment)) alongside the image :-)

[tubeme]

@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?

[bresch]

@tubeme Yes, I'll check and give you the corresponding parameters.

About the diagram you just did:

• I would suggest to use a different letter styles for the letter P in order to avoid confusion between position and P gain (e.g. use for the position vector)
• I don't think "- Ctrl" is needed in the controller rectangles, it would be lighter and clear enough to put P in a triangle (to indicate a gain) and PID in a rectangle.
• The "Psi" greek letter used to define yaw should be in lowercase () as the uppercase is usually used to represent the attitude vector.
• The P hat is missing
• The V hat signal has the arrow in the wrong direction (it should be like for the position one, with a minus sign too)
• Could you use subscripts for the "desired setpoints" ?
• For the line after V_d, it might be useful to add a "mux" element triggered by a "Mode" variable described in the legend of the image of in some explaining text. (https://goo.gl/images/EuFJLa)

[LorenzMeier]

@tubeme Awesome! Is there a way to allow to edit this in a cloud tool, like draw.io?

[hamishwillee]

@tubeme Yes looks great :-). It displays pretty well in gitbook too!

1. We need to have an easy way to change if needed. Normally we suggest draw.io.
2. @bresch suggestions seem reasonable.
3. I like the legend. Will be good to see the parameter mapping too.
4. As this will be embedded in the docs, we may not need the heading and logo.
5. Presumably this is just MC - not FW?

So what documentation should accompany this? The information above from bresch would seem useful. Other ":thoughts"

• What are the effects of tuning different values
• Where to go in the code to play with things
• What can/should be modified/not modified
• How the controller maps to the quadcopter model - ie why the maths works..

[Stifael]

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

Nomenclature

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

Notation

In 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.
nomenclature.pdf
notation.pdf

[hamishwillee]

@Stifael Could not agree more. Are you happy for us to steal your nomenclature and notation as a starting point for PX4?

@tubeme

for a documentation purpose it might be better to find a different kind of notation, such as having vectors boldface and scalars non-boldface.

What do you think would be the best thing to do in this case?

[Stifael]

Are you happy for us to steal your nomenclature and notation as a starting point for PX4?

Of course

[tubeme]

Thanks all let me think with all the info and I will post you with the idea about notations and nomenclature.

[bresch]

@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.
Here is my fist version of the glossary: https://github.com/bresch/Glossary/blob/master/main.pdf
It needs to be ordered and sorted correctly and there is still a lot missing. Please comment here or in the repository so we can quickly have a good basis to start to write schematics.

[hamishwillee]

@bresch @Stifael Probably best if those of you with more experience in using these symbols decide if you're happy with the set.
My two bits:

• Is there any benefit in sorting by Latin, Greek, whatever? I would have thought perhaps by "Domain".
• I like that @Stifael version has units.
• How do we turn the two sets into one?

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.

[bresch]

@hamishwillee Thanks for your answer.

• Is there any benefit in sorting by Latin, Greek, whatever? I would have thought perhaps by "Domain".

I merged the Latin and Greek together, it's true that it's not really useful to make two different sections for this.

• I like that @Stifael version has units.

Units are a good idea, I'll add them.

About the gitbook glossary let me check, I never used it so far.

[hamishwillee]

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.

[hamishwillee]

@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)

[LorenzMeier]

Are we with these on draw.io yet? We need a workflow where control engineers can alter the diagram with minimal friction.

[hamishwillee]

@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?

[hamishwillee]

@tubeme Any ETA on next iteration/Is this waiting on me/others for anything?

Appreciate you are busy. But if you don't respond I'll move what you have done across so we can continue progressing this.

[hamishwillee]

OK, I have created a near duplicate of @tubeme controller diagram on draw.io here. Any of you can edit it. Just pausing in case one of you wants to proceed from here?

Image looks like this:

[hamishwillee]

Updated version above has following changes:

• PID - Ctrl in box TO PID
• p (position) - changed from P
• v (velocity) - changed from V
• Ψ (attitude vector) (psi upper case) - changed from q
• ψ (yaw angle) (psi lower case) - changed from Ψ

Questions:

• F is "thrust" . Is that a reasonable synonym for force? @Stifael "F" is (I believe) more common than "f" as a symbol for force. What should we use here, and is 'thrust' OK for the label?

@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 Nomenclature

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

• In his version he defines things like yaw angle as euler yaw angle. Is this helpful definition over "yaw angle"? If so lets merge.
• If there are discrepancies, are you happy to use his set, or can you propose an alternative?
• Last of all, could you make a copy and experiment with your thoughts on vectors?

[Stifael]

F is "thrust" . Is that a reasonable synonym for force? @Stifael "F" is (I believe) more common than "f" as a symbol for force. What should we use here, and is 'thrust' OK for the label?

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.
@bresch has shown to me a good draft for nomenclature. I suggest that we start with this diagram and also add the draft for nomenclature, which both have to be adjusted simultaneously ( instead of waiting for the perfect, final solution).
One issue that I currently see is that the nomenclature definitions (upper-, lower-, right- and left subscripts) and mathematical symbols might not be very well supported by draw.io. Maybe there is a latex plugin, which would help a lot.
One thing that I personally don't like about the above diagram: arrows as vector indication. I prefer to have vectors and matrices bold-face. It looks just clunky with arrows... :)

[hamishwillee]

@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?

[bresch]

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

[hamishwillee]

Thanks @bresch - looks good:

• Should the F in the index be bold (appears to match on your diagram but not on draw.io version s ?
  
• Is the hat (^) standard for estimate? If not, then r subscript e (like r subscript d) might be more readable.

@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.
@bresch What words would you like to see appearing with the diagram?

As discussed above let's put them in "Controller Diagrams". Would these be better grouped under a parent of "Concepts", "Flight Stack" or "Architecture"?
[I lean towards Concepts for now, while we are working out a better structure for the guide]

[Stifael]

Are you OK with this?

Yes.

Perhaps an explanation of anything that might not be clear from the diagram

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?
I also think that it is important that we do not try to explain everything our-self. Certain things are very standard (such as PID), and you can waste a lot of time trying to explain everything compared to just adding a reference link.

Is the hat (^) standard for estimate

Yes and no. It depends on what we define in the nomenclature. However, ^ is widely used in academia to indicate estimate.

Would these be better grouped under a parent of "Concepts"

I also lean towards Concepts.

[bresch]

Should the F in the index be bold (appears to match on your diagram but not on draw.io version s ?

Corrected. I also added Z in the legend and corrected the projection operator

Is the hat (^) standard for estimate? If not, then r subscript e (like r subscript d) might be more readable.

As Dennis said, it is widely used in academia and in most estimation and control books

What words would you like to see appearing with the diagram?

It might be worth mentioning that:

• the estimates come from EKF2
• this is a standard cascaded position-velocity loop
• depending on the mode, the outer (position) loop is bypassed. The position loop is only used when holding position or when the requested velocity in an axis is null (is this correct @Stifael ?).
• the integrator in the inner loop (velocity) controller includes an anti-reset windup (ARW) using a clamping method
• @Stifael Some details about what's happening in the Conversion block?

[hamishwillee]

I made minor change to the index because the ( ) looked like a symbol - (). OK?

this is a standard cascaded position-velocity loop

It would be good to provide good links to information, tutorials, videos about the standard loop. Anything you recommend?

I also think that it is important that we do not try to explain everything our-self. Certain things are very standard (such as PID), and you can waste a lot of time trying to explain everything compared to just adding a reference link.

Absolutely. I think that the comments @bresch has made are about the right level but that is something for you to resolve.

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?

Whatever you guys propose will be the globally accepted "version 1". Lets get it in and iterate as needed.

[Stifael]

Some details about what's happening in the Conversion block?

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.

[hamishwillee]

@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?

[hamishwillee]

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?

[Stifael]

@hamishwillee

OK with this location and text?

yep. I added comments for notation and if ok I will just do a PR for PX4/PX4-Devguide#411.

Can we have another sketch for FW position controller?

@bresch knows better.

What about attitude controllers?

I will do a PR for the attitude controller.

[hamishwillee]

@bresch knows better.

@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?

[kaklik]

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.

[hamishwillee]

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