From 16b609bc88626cb5fd6b25b1a56222404e5f9358 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Thu, 8 Apr 2021 17:03:49 +1000 Subject: [PATCH 1/2] Add goemetry file docs --- en/SUMMARY.md | 1 + en/concept/geometry_files.md | 80 ++++++++++++++++++++++++++++++++++++ 2 files changed, 81 insertions(+) create mode 100644 en/concept/geometry_files.md diff --git a/en/SUMMARY.md b/en/SUMMARY.md index b61dbf2bac51..e7279bdd6bb9 100644 --- a/en/SUMMARY.md +++ b/en/SUMMARY.md @@ -281,6 +281,7 @@ * [Flight Modes](concept/flight_modes.md) * [Flight Tasks](concept/flight_tasks.md) * [Mixing and Actuators](concept/mixing.md) + * [Geometry Files](concept/geometry_files.md) * [PWM limit state machine](concept/pwm_limit.md) * [System Startup](concept/system_startup.md) * [SD Card Layout](concept/sd_card_layout.md) diff --git a/en/concept/geometry_files.md b/en/concept/geometry_files.md new file mode 100644 index 000000000000..d08cefa13efa --- /dev/null +++ b/en/concept/geometry_files.md @@ -0,0 +1,80 @@ +# Geometry Files + +- Associated dev guide issue: https://github.com/PX4/PX4-Devguide/issues/349 +- Geometry files are found here: https://github.com/PX4/PX4-Autopilot/tree/master/src/lib/mixer/MultirotorMixer/geometries +- They are TOML files + +@[youtube](https://youtu.be/orvng_11ngQ?t=1080) - Control Allocation - 18 minute in. + +[Slide 14 has info](https://static.sched.com/hosted_files/px4developersummitvirtual2020/1b/PX4%20Developer%20Summit%202020%20-%20Overview%20of%20multicopter%20control%20from%20sensors%20to%20motors.pdf) + + + + +## How to add a new geometry + +1. Create new TOML geometry file in [/src/lib/mixer/MultirotorMixer/geometries](https://github.com/PX4/PX4-Autopilot/tree/master/src/lib/mixer/MultirotorMixer/geometries). + For example "foo.toml". + with a new key (e.g.: key = "4fo") and add to **CMakeLists.txt** + +2. In ROMFS/px4fmu_common/Create new mixer file **mixers/foo.main.mix** with a line containing the new key: + ``` + R 4fo 10000 10000 10000 0 + ``` + +3. Set the new mixer in **init.d/airframes/myconfig** + ``` + set MIXER foo + ``` + + +## Fragment from some files + +Looking at the toml files they all have this first. So I am assuming file description follwed by info. +- Is key random? +- Where is the description used? + +``` +# Generic Quadcopter in H configuration + +[info] +key = "4h" +description = "Generic Quadcopter in H configuration" +``` +Then we have rotor default which always has this structure +``` +[rotor_default] +axis = [0.0, 0.0, -1.0] +Ct = 1.0 +Cm = 0.05 + +direction = "CW" - except I Only see THIS line on Tri +``` +Then we have one of these for each rotor - so 3 for a tri +``` +[[rotors]] +name = "front_right_top" +position = [0.729, 0.684, 0.1] +direction = "CW" +``` + +- How do I work out what each of these fields mean? +- Are there geometries we can't capture? ie what if roto is on angle say? \ No newline at end of file From cf3e6ea28e951dc0a7e87189a7e8b2b4dd8f5a61 Mon Sep 17 00:00:00 2001 From: Hamish Willee Date: Wed, 21 Apr 2021 15:42:20 +1000 Subject: [PATCH 2/2] Update docs --- en/concept/geometry_files.md | 146 ++++++++++++++++++++--------------- 1 file changed, 83 insertions(+), 63 deletions(-) diff --git a/en/concept/geometry_files.md b/en/concept/geometry_files.md index d08cefa13efa..c5ebec2642c7 100644 --- a/en/concept/geometry_files.md +++ b/en/concept/geometry_files.md @@ -1,80 +1,100 @@ -# Geometry Files - -- Associated dev guide issue: https://github.com/PX4/PX4-Devguide/issues/349 -- Geometry files are found here: https://github.com/PX4/PX4-Autopilot/tree/master/src/lib/mixer/MultirotorMixer/geometries -- They are TOML files - -@[youtube](https://youtu.be/orvng_11ngQ?t=1080) - Control Allocation - 18 minute in. - -[Slide 14 has info](https://static.sched.com/hosted_files/px4developersummitvirtual2020/1b/PX4%20Developer%20Summit%202020%20-%20Overview%20of%20multicopter%20control%20from%20sensors%20to%20motors.pdf) - - - - -## How to add a new geometry - -1. Create new TOML geometry file in [/src/lib/mixer/MultirotorMixer/geometries](https://github.com/PX4/PX4-Autopilot/tree/master/src/lib/mixer/MultirotorMixer/geometries). - For example "foo.toml". - with a new key (e.g.: key = "4fo") and add to **CMakeLists.txt** - -2. In ROMFS/px4fmu_common/Create new mixer file **mixers/foo.main.mix** with a line containing the new key: +# Multicopter Geometry Files + +Geometry files are used by PX4 to generate mixer definitions that map the outputs of PX4 rate controllers to specific motors. +The files describe the positions, direction of thrust, rotation direction, thrust and drag coefficients of each of the rotors. + +## How to add a New Geometry + +1. Create new TOML geometry file (e.g. "foo.toml") in [/src/lib/mixer/MultirotorMixer/geometries](https://github.com/PX4/PX4-Autopilot/tree/master/src/lib/mixer/MultirotorMixer/geometries). + The file must include a new **key** (e.g.: `key = "4fo"`). + See [Geometry File Format](#geometry-file-format) for information on the required fields. +1. Add the geometry file to [/src/lib/mixer/MultirotorMixer/CMakeLists.txt](https://github.com/PX4/PX4-Autopilot/blob/master/src/lib/mixer/MultirotorMixer/CMakeLists.txt). +1. Create a new [mixer file](../concept/mixing.md) that uses the new geometry. For example you might create **ROMFS/px4fmu_common/mixers/foo.main.mix** with a line containing the new key (in this case `4fo`): ``` - R 4fo 10000 10000 10000 0 + R 4fo ``` - -3. Set the new mixer in **init.d/airframes/myconfig** +1. Set the new mixer in your [airframe configuration](../dev_airframes/adding_a_new_frame.md#add-new-airframe-to-qgroundcontrol) (e.g. **init.d/airframes/myconfig**) ``` set MIXER foo ``` - - -## Fragment from some files -Looking at the toml files they all have this first. So I am assuming file description follwed by info. -- Is key random? -- Where is the description used? +## Geometry File Format + +Geometry files are plain-text files that are divided into sections deliniated by the headers: `[info]`, `[rotor_default]`, and `[[rotor]]` (there is a `[[rotor]]` section for each rotor in the geometry). + +The fields allowed in each section are listed below (as defined in the [px_generate_mixers.py](https://github.com/PX4/PX4-Autopilot/blob/master/src/lib/mixer/MultirotorMixer/geometries/tools/px_generate_mixers.py) script). + + +### [info] section + +The `[info]` section identifies the files for readers and for PX4. + +It must define values for: +- **key:** An arbitrary identifier to allow the file to be distinguished from other geometry files. + By convention the key is usually the number of rotors followed by one or two letters (these letters _may_ hint at the configuration). + For example: "4hb" +- **description:** A human readable description of the configuration described by the geometry file. + For example: "Generic Quadcopter in H configuration" + + + +### [rotor_default] + +The `[rotor_default]` section specifies default values will be applied to a rotor if the corresponding key is not provided in the `[[rotor]]` definition. +For example, the rotation direction might be defined for every rotor, or a default might be specified in th + +The allowed keys are described in the `[[rotor]]` section below (noting that it doesn't make sense to define a default value for a key like *name* that is unique to each rotor). + +### [[rotor]] + +Each `[rotor]` section describes the geometry values for a rotor. +Default values may be supplied in `[rotor_default]` (the values in the rotor section take precedence). + +The allowed keys are: +- **name:** Human-readable name for the rotor. + For example: "front_right_top" +- **position:** A vector describing the location of the rotor relative to the vehicle centre of gravity in the body frame (Forward-Right-Down). + This can be any units (e.g. metres, fathoms, whatever) because the mixer is normalised (only only the ratio between the distances is really important). +- **axis:** A vector in the in the body frame (Forward-Right-Down) describing the direction of the thrust produced by the rotor. + For example `[1.0, 0.0, -1.0]` means that the rotor produces upward and forward thrust equally (i.e.: angle of 45 degrees). +- **direction:** specifies the direction of rotation of a rotor, `CW` (clockwise) or `CCW` (counter clockwise) +- **Ct:** Non-dimensional thrust coefficient. + For example, a rotor with a `Ct` of 2.0 produces 2 times the thrust of a rotor with a `Ct` of 1.0 +- **Cm:** Non-dimensional drag torque coefficient. + This relates to the axial torque produced by a spinning propeller. + This needs to be set relative to `Ct` if some torque can be produced by drag and thrust together. + If set to 0, the mixer will assume that the rotor does not produce any axial torque. + + +## Example File + +There are numerous exmaples in the source tree: [/src/lib/mixer/MultirotorMixer/geometries/](https://github.com/PX4/PX4-Autopilot/blob/master/src/lib/mixer/MultirotorMixer/geometries/). + +A tri-copter geometry ([tri_y.toml](https://github.com/PX4/PX4-Autopilot/blob/master/src/lib/mixer/MultirotorMixer/geometries/tri_y.toml)) is reproduced below. ``` -# Generic Quadcopter in H configuration +# Tri Y [info] -key = "4h" -description = "Generic Quadcopter in H configuration" -``` -Then we have rotor default which always has this structure -``` +key = "3y" +description = "Tri Y" + [rotor_default] axis = [0.0, 0.0, -1.0] Ct = 1.0 -Cm = 0.05 +Cm = 0.0 +direction = "CW" -direction = "CW" - except I Only see THIS line on Tri -``` -Then we have one of these for each rotor - so 3 for a tri -``` [[rotors]] -name = "front_right_top" -position = [0.729, 0.684, 0.1] -direction = "CW" +name = "front_right" +position = [0.5, 0.866025, 0.0] + +[[rotors]] +name = "front_left" +position = [0.5, -0.866025, 0.0] + +[[rotors]] +name = "rear" +position = [-1.0, 0.0, 0.0] ``` -- How do I work out what each of these fields mean? -- Are there geometries we can't capture? ie what if roto is on angle say? \ No newline at end of file