Creating new mixer geometry - documentation required

[mhkabir]

While working on bringing up a new airframe, I realized that there is absolutely no documentation on how to create a custom mix for a new geometry in the multi_tables.py script. https://github.com/PX4/Firmware/blob/master/src/modules/systemlib/mixer/multi_tables.py

I would be happy to document this, but I need someone who has worked on it to atleast give me a basic understanding of what each parameter is, how scaling works, how I can calculate the scaling factors given a model of the vehicle, etc. I would then be able to use my case as an example on the Devguide so that it's clear in the future.

Background

I am working on bringing up this asymmetric airframe, and defining a new geometry with exact measurements and angles from the frame would be nice :

Open questions

A mix for an airframe typically looks like this :

quad_deadcat = [
    [  60, CCW, 1.0],
    [-125, CCW, 0.92],
    [ -60, CW, 1.0],
    [ 125, CW, 0.92],
]

The 3 columns seem to be arm angles, rotation direction and scaling factor.

• Where are the arm angles measured from?
• The order of the array seems to follow the PX4 motor map order for the airframe, but it would be good to confirm this.
• How are the scaling factors calculated?
• How are the arm lengths, etc. incorporated into the scale factor calculation?

@SimonWilks @LorenzMeier @anton-matosov @kd0aij

[chrisbrent]

Here are two discussion topics that touch on this. The first one is the most useful
http://discuss.px4.io/t/multi-tables-py-generated-scale-tables/3103
http://discuss.px4.io/t/motor-mixer-for-px-odd-models-config/1537
The answer I know are:

• Angles are measured from the Cog relative to "forward"
• Array order matches the motor map order
  The ones I want to know are:
• How are the arm lengths scaled. See the first discussion post for details, but no real answers.
  Also note that https://github.com/PX4/Firmware/blob/master/src/modules/systemlib/mixer/multi_tables.py generates a table but
  https://github.com/PX4/Firmware/blob/master/src/modules/systemlib/mixer/mixer_multirotor.cpp#L133 is the code that picks up the table that was generated. The second field in the .mix file is used to map the model to the generated table:
  https://github.com/PX4/Firmware/blob/master/ROMFS/px4fmu_common/mixers/quad_x.main.mix#L1

[LorenzMeier]

@bresch Can you comment here and potentially put your tables extension (but not the mixer itself) into a PR?

[bresch]

In order to compute the mixer table for my asymmetric drone, I created a python script that solves the M, L, N body-axis moments equations (around roll, pitch and yaw) together in order to minimize coupling between the axes and create the required torque around the CG.
@jlecoeur created a general script to solve those moment equations and generate a mixer table and is interested to include it in PX4. He made a pretty cool python notebook here: https://github.com/jlecoeur/servo_mix_matrix/blob/master/servo_mix_matrix.ipynb

[jlecoeur]

The notebook handles 6dof control (3 axis torque + 3 axis thrust). That is interesting for holonomic platforms, and also for VTOL that can produce thrust in Z and X axis. FYI @dagar. I tested it on a real platform with the geometry "holonomic hexacopter" and it worked great, but that was not with PX4.
I meant to create another Mixer class for 6dof control and test it in parallel to the current 4dof multirotor mixer class.

Regarding the script, IMO the best would be something similar to uORB: a folder that contains one text file per platform. Each file provides the required information on the platform in human-friendly format: name, number of rotors, position and orientation of rotors, lift and moment coefficients, mass, intertia. Then during compilation the script generates a mix class per platform. That way it becomes super easy to add a new platform geometry.

edit: I also tested the notebook in PX4 with a drone with geometry "hexacopter in H shape". I hardcoded the weights generated by the notebook. It worked great and removed the yaw/roll coupling I had with the hexa_x mixer.

[dagar]

We should consider getting it into PX4 incrementally, with the more approachable folder structure.

[neom89]

@jlecoeur @dagar @LorenzMeier : Can you please enlist the steps required to add a new airframe in PX4?
As far as I understand, these could be the steps:

1. Use the notebook to generate mixer weights (not normalized).
2. Hardcode the weights in the multi_tables.py file for the new geometry.
3. Add the airframe in QGC.

Are there any additional steps which I may be missing?
Thanks!

[jlecoeur]

Hi @vmishra9 as far as I know (others can probably give you more info) the steps are:
1- add mixer
2- add a config that uses this mixer
3- add the config to QGC
This thread is about step 1.

Right now for step 1 you have to:
1a Modify multi_table.py, with new geom (like quad_deadcat above), then add it to the list towards the end of the file. Which numbers to put in multi_table is not documented unfortunately.
1b. Modify mixer_multicopter.cpp to handle your new mixer (around line 140)

What is in the notebook is not available yet. If #8063 is accepted, then step 1 will be just: Add geometry file in the folder src/lib/mixer/geom.

[neom89]

Hi @jlecoeur ! I can see that #8063 was accepted. So, step 1 is pretty straight forward now. Can you please tell me a bit more about step 2? i.e. How and where can I add a config that uses the new mixer?
Thanks!

[jlecoeur]

@vmishra9 Try to follow this documentation page and let me know if that answers your question:
https://dev.px4.io/en/airframes/adding_a_new_frame.html

For step 2, it says to add one config file in ROMFS/px4fmu_common/init.d/ and one mixer file in ROMFS/px4fmu_common/mixers/
Step 3 is done when uploading the compiled .px4 firmware file with QGC.

[neom89]

@jlecoeur The link was helpful. Thanks!
As you said for step 2, "add one mixer file in ROMFS/px4fmu_common/mixers/". Doesn't #8063 take care of this? or will I have to do it separately?

[jlecoeur]

Separately, #8063 covers only multicopters. It lets you add a multicopter geometry, which you use in the mixer file with the syntax R: <geometry> <roll scale> <pitch scale> <yaw scale> <deadband>
https://dev.px4.io/en/concept/mixing.html#syntax

[neom89]

@jlecoeur I am interested in the multicopter mixer. All the multicopter mixers I found in ROMFS/px4fmu_common/mixers/ have the same numbers except the geometry tab. ie R: 10000 10000 10000 0
which confuses me because I though it should be different if the multicopter is not symmetric in all the 3 axes.

I read the following the description in the link https://dev.px4.io/en/concept/mixing.html#syntax :
"Each of the roll, pitch and yaw scale values determine scaling of the roll, pitch and yaw controls relative to the thrust control."
Can you please tell me what scaling means here (physically) with respect to the motor/thrust output? What happens if the scale for roll, pitch and yaw are different from each other, i.e. how would a quadcopter behave?

[jlecoeur]

The multirotor mixer (R:) first applies these scaling factors on roll pitch yaw commands, then converts the scaled roll pitch yaw thrust commands to motor commands according to the geometry.
Most of the times it is ok to let the scales at 1000. Asymmetry is handled at the geometry level, for example 4dc is asymmetric.
But if you lower one scale -say roll scale- then the drone will have less authority on that axis.

[neom89]

@jlecoeur That helps. Thanks!