The documentation for mixers is bad

[tuloski]

Sorry for being rude, but I tried to read it over and over again, but the documentation suc*s. I tried to experiment with mixers, but I can't figure it out well how they work. It seems written by someone who knows very well how they works, but not written for people that doens't know how it works.

[hamishwillee]

@tuloski How DARE You!

Only joking, you're right, the docs are horrible. Periodically I have to make modifications to them or use them to answer questions. And it takes me close on a day to work out how it all works ... again. I'm now at the point that I feel that I somewhat understand them - but not enough to rework the docs.

Unfortunately I don't know how to fix this. Firstly the files and mixing topic is complicated. Secondly I have never actually created a real mixer ... so I don't know what I don't know. Last of all, there are so many things I can work on, and this is one that scares me.

Just on quick scan I'd suggest that the syntax section would be improved by an introduction that listed all the tags and types of mixers with a high level indication of what they are used for.

Then in each of the sections a summary of when you use it - e.g. the simple mixer states what it does, but now when/why you use it.

Suggestions on how to fix or at least improve welcome.

The specific docs are:

• https://dev.px4.io/master/en/concept/mixing.html
• https://dev.px4.io/master/en/airframes/adding_a_new_frame.html

[tuloski]

It's not an easy task. I really don't know where I'd start :).

For sure I'd add the example in "adding a new frame" into the main docs of mixers, because it's actually the only place where it explains the syntax of mixers (O line, S line, ...).

I can point out a few lines where it's really messy and I didn't understand at all the concept, but I feel like it's a useless work if it's going somehow to be revamped.

[hamishwillee]

@tuloski I don't know of any planned revamp of the mixers - (@bkueng is any planned?). So I think highlighting the bits you particularly don't understand makes sense.

[bkueng]

At some point yes, but I don't see that anytime soon, so I think it's worth improving the docs.

[tuloski]

I'll try to point a few parts where it's really confusing:

• Virtual control groups are not clear at all.
• Mixer file names: it talks about main and aux outputs, but for a beginner it is not clear what main and aux are. Maybe a reference or an example to an hardware is welcome.
• Syntax: it says that 'M' for a simple summing mixer, 'R' for a multirotor mixer, etc. But it is not described what summing mixer and multirotor mixer are and what are we supposed to pick.
• Simple mixer: a description of the various parameters (control count, -ve scale, offset, ...) is welcome.
• Simple mixer: what is an "S" line and "O" line? They are just thrown there without any description.
• It is in general not clear to me why there are mixers for multirotors, helicopters and so on. Can't it be gereralized? At the end it is only a mapping from inputs to outputs.

[fabrizioschiano]

I agree with what @tuloski said above. Is someone taking care of this? I would like to help but I would first need to understand better how the mixers work. I genuinely think that improving this part of the documentation would be really important.

I agree with all the points pointed out by @tuloski

[hamishwillee]

@fabrizioschiano IN theory me, but in practise I also need to have a better idea of how these work. I have been improving the docs as I go. But it is a long haul and the effort is costly.

I think I finally have a good grip on the identified issues. I'll follow up with the resident expert below and confirm.

[hamishwillee]

@bkueng Re virtual control groups, the docs say:

These groups are NOT mixer inputs, but serve as meta-channels to feed fixed wing and multicopter controller outputs into the VTOL governor module.

I can see from the airframe definition for generic standard vtol it takes a quad mixer on MAIN and a FW mixer on the AUX. I can't see any cases where the control groups are used in mixer files (as you would assume from the above docs).

My guess is that the vtol governer uses MC controller for MC mode, FW controller for FW mode, and probably the governor module gets both inputs and decides which to use at a particular time (and possibly now to "fuse" them during transition?).

I might further guess that the governor creates does magic with these virtual control groups to choose which real mixer outputs are live at a particular time.

However that's all a guess, and it isn't clear whether a normal user can do anything with these, and who needs to know about them. Can you clarify?

[hamishwillee]

Mixer file names: it talks about main and aux outputs, but for a beginner it is not clear what main and aux are. Maybe a reference or an example to an hardware is welcome.

Yes we can add something. Notes:

• Outputs are divided into MAIN and AUX. Generally MAIN is used for the core vehicle controls (e.g. motors, rudders). AUX may be used for core controls if needed, but if not is generally used for RC passthrough or less vital outputs (gimbal, whatever).
• The mapping of what outputs are is defined by the mixer files. For existing airframes you can see what these are in the airframe reference
• Historically the MAIN and AUX map to PWM outputs on a Pixhawk flight controller board.
• They may however instead map to UAVCAN or some other bus, depending on settings.

[hamishwillee]

@bkueng Can you please check my thinking for the points below:

Syntax: it says that 'M' for a simple summing mixer, 'R' for a multirotor mixer, etc. But it is not described what summing mixer and multirotor mixer are and what are we supposed to pick.

So firstly, how the different mixer types are used IS defined in the various sections, but it is correct that it isn't clear:

• When you pick each
• Whether you can combine them - e.g. can you have a quad mixer that has as simple mixer as well.
• Order - can a quad mixer go after a simple mixer

My understanding is that you use:

• multirotor mixer to define the outputs of a quad, hexa, octa rotor of different configs.
  • The relationship of all the rotors to each other based on roll, pitch, yaw is well defined based on the geometry, so you can define the mixing for all 4/6/8 outputs in a single line.
  • If you define a quad and still had some outputs left you could use a simple mixer for defining how these worked
  • The order of declaration doesn't matter. Usually you would have quad mixer first, but you could do simple first. The mc mixer would allocate the next consecutive outputs.
• helicopter mixer - use for helicopters. YOu can also have a simple mixer too.
• Simple mixer: Use for mapping one or more inputs to one or more outputs. This is used for Fixed wing control mapping, and for servos etc.
  • The relationship between the outputs isn't predictable, so there is no FW mixer.
• Null mixer. This indicates an output that is unused. It would be used in a simple mixer for example, if you wanted to avoid defining an output between two others.

There are only these three main types, which start a group with R, H, M, Z respectively. The other lines like S

Simple mixer: a description of the various parameters (control count, -ve scale, offset, ...) is welcome. Simple mixer: what is an "S" line and "O" line? They are just thrown there without any description.

They are both in the simple mixer. We need to link down to that. Possibly pull in some of the example info from the add an airframe doc.

It is in general not clear to me why there are mixers for multirotors, helicopters and so on. Can't it be gereralized? At the end it is only a mapping from inputs to outputs.

As above, it is generalised for the cases like mc where the relationships of different outputs are related. It isn't where they can't be.

Beat, if you can confirm, I can probably make this significantly better with some small changes.

[bkueng]

My guess is that the vtol governer uses MC controller for MC mode, FW controller for FW mode, and probably the governor module gets both inputs and decides which to use at a particular time (and possibly now to "fuse" them during transition?).

Yes, you nailed it. Anyone working with mixers does not need to know anything about those - only people working on VTOL code.

Whether you can combine them - e.g. can you have a quad mixer that has as simple mixer as well. Order - can a quad mixer go after a simple mixer

Anything of the above is possible - except you need to be careful about VTOL, which makes certain assumptions in the code (but we want to remove those - for now, it's best to just follow an existing VTOL config to avoid running into issues).

Null mixer. This indicates an output that is unused. It would be used in a simple mixer for example, if you wanted to avoid defining an output between two others.

Correct, and I think this is also used for the parachute.

The rest is also correct.

[tuloski]

Hi @fabrizioschiano how are you?

BTW back to the topic I'd like to have a more "scientific" approach to "mixers". Basiacally a mixer is an allocation matrix. We have some inputs (forces and torques) that must be mapped into real input of the systems (motors, flaps, ...). So it's basically a R^n-->R^u transformation, where n is the number of inputs (usually 4 for multicopters and vtol but it can be generalized to 6 for a full wrench) and u is the number of real input of the system. This transformation can be a complex one for complex allocation strategies, especially when u>n but usually it's a linear transformation, i.e. a MATRIX!

Why not making the mixer a simple matrix?! Clean, easy to understand, mathematically correct, generalized for every vehicle....

[fabrizioschiano]

Hey @tuloski , thanks for the answer. What you wrote for me it is clear, a lot of concepts I understand them already but I think that, for the sake of being clear with non-experts, it would be nice to improve their explanation in the documentation. This is what I meant

[hamishwillee]

I have fixed the specific issues outlined in https://github.com/PX4/Devguide/issues/868#issuecomment-534035053 in https://github.com/PX4/Devguide/pull/994

That is not to say that it is perfect, but I think a bit more accessible. Thanks very much for the report.

If you want to discuss the whole architecture of the mixers that's not a devguide discussion> That's probably an RFC or separate issue with breakdown of the proposal - that then gets take to the dev call.

[ghost]

I'll second the sentiment of the OP.

In addition, some questions that need to be answered:

where is the syntax/acceptable settings for the multirotor "R:" mixer defined? For instance, the "vtol_tailsitter_duo.main.mix" has "R: 2-", and i dont see that in the list. Is "R: 1" an acceptable option?

what is required in a mixer file? Do multirotor have to have "R:" mixers or can you use only simple mixers?

[hamishwillee]

@davidcgregory You're not alone. Perhaps not much consolation, but the docs are much more complete and "understandable" in this area than they used to be. There is also a missing part of the story in the docs - "geometry files" which I believe "compensate" for different rotor geometries.

@bkueng Can you confirm

1. R=2 is an undocumented acceptable option.
2. R=1 is not an acceptable option. That is a helicopter, so you'd use the Helicopter mixer
3. (This is a complete guess - for you to confirm) A multirotor should use a multirotor mixer (R). Thing like geometry files and other code assumes that a multirotor is defined using a multirotor mixer.

[bkueng]

The R: requires a corresponding toml file, e.g. https://github.com/PX4/Firmware/blob/master/src/lib/mixer/MultirotorMixer/geometries/twin_engine.toml#L4. So R: 2 does not exist, but R: 2- does.

[ghost]

Thanks @hamishwillee and @bkueng

WRT to R: 1, there are configurations which are not "helicopters" which might have a single rotor (i happen to be building one). Imagine something like the VTOL tail-sitter dual rotor but with only one rotor.

This is important to answer I think: "(This is a complete guess - for you to confirm) A multirotor should use a multirotor mixer (R). Thing like geometry files and other code assumes that a multirotor is defined using a multirotor mixer.

[hamishwillee]

@bkueng Thank you. So is my guess "3" correct? i.e. that you could in theory create a mixer for a multicopter using simple mixers, but there is lots of code that assumes a multicopter uses the multicopter mixer?

[bkueng]

@bkueng Thank you. So is my guess "3" correct? i.e. that you could in theory create a mixer for a multicopter using simple mixers, but there is lots of code that assumes a multicopter uses the multicopter mixer?

Yes in theory. There's no code assuming that, but the MC mixer has unsaturation logic that cannot be achieved with simple mixers.

"(This is a complete guess - for you to confirm) A multirotor should use a multirotor mixer (R).

Correct. You could also use a geometry file for a single motor though but it would currently not add any benefit.