Mixing: Syntax and virtual control group info. (#994)

* Mixing: Syntax and virtual control group info.

* tidy mixer definitions

en/concept/mixing.md

@@ -98,6 +98,9 @@ For a multicopter things are a bit different: control 0 (roll) is connected to a
 
 ## Virtual Control Groups
 
+> **Caution** *Virtual Control Group*s are only relevant to developers creating VTOL code.
+  They should not be used in mixers, and are provided only for "completeness".
+
 These groups are NOT mixer inputs, but serve as meta-channels to feed fixed wing and multicopter controller outputs into the VTOL governor module.
 
 ### Control Group #4 (Flight Control MC VIRTUAL)
@@ -199,35 +202,46 @@ See above for more information on [mixer loading](#loading_mixer).
 
 ### Syntax {#mixer_syntax}
 
-Mixer definitions are text files; lines beginning with a single capital letter followed by a colon are significant.
-All other lines are ignored, meaning that explanatory text can be freely mixed with the definitions.
+Mixer files are text files that define one or more mixer definitions: mappings between one or more inputs and one or more outputs. 
+
+There are four types of mixers definitions: [multirotor mixer](#multirotor_mixer), [helicopter mixer](#helicopter_mixer), [summing mixer](#summing_mixer), and [null mixer](#null_mixer).
+- [Multirotor mixer](#multirotor_mixer) - Defines outputs for 4, 6, or 8 rotor vehicles with + or X geometry.
+- [Helicopter mixer](#helicopter_mixer) - Defines outputs for helicopter swash-plate servos and main motor ESCs
+  (the tail-rotor is a separate [summing mixer](#summing_mixer).)
+- [Summing mixer](#summing_mixer) - Combines zero or more control inputs into a single actuator output.
+  Inputs are scaled, and the mixing function sums the result before applying an output scaler.
+- [Null mixer](#null_mixer) - Generates a single actuator output that has zero output (when not in failsafe mode).
 
-Each file may define more than one mixer; the allocation of mixers to actuators is specific to the device reading the mixer definition, and the number of actuator outputs generated by a mixer is specific to the mixer.
+> **Tip** Use *multirotor* and *helicopter mixers* for the respective types, the *summing mixer* for servos and actuator controls, and the *null mixer* for creating outputs that must be zero during normal use (e.g. a parachute has 0 normally, but might have a particular value during failsafe).
 
-For example: each simple or null mixer is assigned to outputs 1 to x in the order they appear in the mixer file.
+The number of outputs generated by each mixer depends on the mixer type and configuration.
+For example, the multirotor mixer generates 4, 6, or 8 outputs depending on the geometry, while a summing mixer or null mixer generate just one output.
 
-A mixer begins with a line of the form
+You can specify more than one mixer in each file.
+The output order (allocation of mixers to actuators) is specific to the device reading the mixer definition; for a PWM device the output order matches the order of declaration.
+For example, if you define a multi-rotor mixer for a quad geometry, followed by a null mixer, followed by two summing mixers then this would allocate the first 4 outputs to the quad, an "empty" output, and the next two outputs.
 
+Each mixer definition begin with a line of the form:
 ```
 <tag>: <mixer arguments>
 ```
 
-The tag selects the mixer type; 'M' for a simple summing mixer, 'R' for a 
-multirotor mixer, etc.
+The `tag` selects the mixer type (see links for detail on each type):
+- `R`: [Multirotor mixer](#multirotor_mixer)
+- `H`: [Helicopter mixer](#helicopter_mixer)
+- `M`: [Summing mixer](#summing_mixer)
+- `Z`: [Null mixer](#null_mixer)
 
-#### Null Mixer
+Some mixers definitions consist of a number of tags (e.g. `O` and `S`) that follow the mixer-type tag above.
 
-A null mixer consumes no controls and generates a single actuator output whose value is always zero.
-Typically a null mixer is used as a placeholder in a collection of mixers in order to achieve a specific pattern of actuator outputs.
+> **Note** Any line that does not begin with a single capital letter followed by a colon may be ignored (so explanatory text can be freely mixed with the definitions).
 
-The null mixer definition has the form:
-```
-Z:
-```
 
-#### Simple Mixer
+#### Summing Mixer {#summing_mixer}
+
+Summing mixers are used for actuator and servo control.
 
-A simple mixer combines zero or more control inputs into a single actuator output.
+A summing (simple) mixer combines zero or more control inputs into a single actuator output.
 Inputs are scaled, and the mixing function sums the result before applying an output scaler.
 
 A simple mixer definition begins with:
@@ -261,7 +275,21 @@ Whilst the calculations are performed as floating-point operations, the values s
 
 An example of a typical mixer file is explained [here](../airframes/adding_a_new_frame.md#mixer-file).
 
-#### Multirotor Mixer
+
+#### Null Mixer {#null_mixer}
+
+A null mixer consumes no controls and generates a single actuator output with a value that is always zero.
+
+Typically a null mixer is used as a placeholder in a collection of mixers in order to achieve a specific pattern of actuator outputs.
+It may also be used to control the value of an output used for a failsafe device (the output is 0 in normal use; during failsafe the mixer is ignored and a failsafe value is used instead).
+
+The null mixer definition has the form:
+```
+Z:
+```
+
+
+#### Multirotor Mixer {#multirotor_mixer}
 
 The multirotor mixer combines four control inputs (roll, pitch, yaw, thrust) into a set of actuator outputs intended to drive motor speed controllers.
 
@@ -290,9 +318,9 @@ Idlespeed is relative to the maximum speed of motors and it is the speed at whic
 
 In the case where an actuator saturates, all actuator values are rescaled so that the saturating actuator is limited to 1.0.
 
-#### Helicopter Mixer
+#### Helicopter Mixer {#helicopter_mixer}
 
-The helicopter mixer combines three control inputs (roll, pitch, thrust) into four outputs ( swash-plate servos and main motor ESC setting).
+The helicopter mixer combines three control inputs (roll, pitch, thrust) into four outputs (swash-plate servos and main motor ESC setting).
 The first output of the helicopter mixer is the throttle setting for the main motor.
 The subsequent outputs are the swash-plate servos.
 The tail-rotor can be controlled by adding a simple mixer.
@@ -332,7 +360,7 @@ The servo output is scaled by `<scale> / 10000`.
 After the scaling, the `<offset>` is applied, which should be between -10000 and +10000.
 The `<lower limit>` and `<upper limit>` should be -10000 and +10000 for full servo range.
 
-The tail rotor can be controller by adding a [simple mixer](#simple-mixer):
+The tail rotor can be controller by adding a [summing mixer](#summing_mixer):
 ```
 M: 1
 S: 0 2  10000  10000      0 -10000  10000
@@ -341,13 +369,26 @@ By doing so, the tail rotor setting is directly mapped to the yaw command.
 This works for both servo-controlled tail-rotors, as well as for tail rotors with a dedicated motor.
 
 The [blade 130 helicopter mixer](https://github.com/PX4/Firmware/blob/master/ROMFS/px4fmu_common/mixers/blade130.main.mix) can be viewed as an example.
-The throttle-curve starts with a slightly steeper slope to reach 6000 (0.6) at 50% thrust.
-It continues with a less steep slope to reach 10000 (1.0) at 100% thrust.
-The pitch-curve is linear, but does not use the entire range.
-At 0% throttle, the collective pitch setting is already at 500 (0.05).
-At maximum throttle, the collective pitch is only 4500 (0.45).
-Using higher values for this type of helicopter would stall the blades.
-The swash-plate servos for this helicopter are located at angles of 0, 140 and 220 degrees.
-The servo arm-lenghts are not equal.
-The second and third servo have a longer arm, by a ratio of 1.3054 compared to the first servo.
-The servos are limited at -8000 and 8000 because they are mechanically constrained.
+```
+H: 3
+T:      0   3000   6000   8000  10000
+P:    500   1500   2500   3500   4500
+# Swash plate servos:
+S:      0  10000  10000      0  -8000   8000
+S:    140  13054  10000      0  -8000   8000
+S:    220  13054  10000      0  -8000   8000
+
+# Tail servo:
+M: 1
+S: 0 2  10000  10000      0 -10000  10000
+```
+- The throttle-curve starts with a slightly steeper slope to reach 6000 (0.6) at 50% thrust.
+- It continues with a less steep slope to reach 10000 (1.0) at 100% thrust.
+- The pitch-curve is linear, but does not use the entire range.
+- At 0% throttle, the collective pitch setting is already at 500 (0.05).
+- At maximum throttle, the collective pitch is only 4500 (0.45).
+- Using higher values for this type of helicopter would stall the blades.
+- The swash-plate servos for this helicopter are located at angles of 0, 140 and 220 degrees.
+- The servo arm-lenghts are not equal.
+- The second and third servo have a longer arm, by a ratio of 1.3054 compared to the first servo.
+- The servos are limited at -8000 and 8000 because they are mechanically constrained.