Add a sample mixer definition and documentation.

Add support for comments in mixer definitions.

3 files changed, 143 insertions, 1 deletions

diff --git a/ROMFS/Makefile b/ROMFS/Makefile
index cc5a3ccd3..3f7d4484f 100644
--- a/ROMFS/Makefile
+++ b/ROMFS/Makefile
@@ -20,7 +20,8 @@ ROMFS_FSSPEC	:= $(SRCROOT)/scripts/rcS~init.d/rcS \
 		   $(SRCROOT)/scripts/rc.logging~init.d/rc.logging \
 		   $(SRCROOT)/scripts/rc.standalone~init.d/rc.standalone \
 		   $(SRCROOT)/scripts/rc.PX4IO~init.d/rc.PX4IO \
-		   $(SRCROOT)/scripts/rc.PX4IOAR~init.d/rc.PX4IOAR
+		   $(SRCROOT)/scripts/rc.PX4IOAR~init.d/rc.PX4IOAR \
+		   $(SRCROOT)/mixers/FMU_delta.mix~mixers/FMU_delta.mix
 
 #
 # Add the PX4IO firmware to the spec if someone has dropped it into the
diff --git a/ROMFS/mixers/FMU_delta.mix b/ROMFS/mixers/FMU_delta.mix
new file mode 100644
index 000000000..75493c578
--- /dev/null
+++ b/ROMFS/mixers/FMU_delta.mix
@@ -0,0 +1,51 @@
+Delta-wing mixer for PX4FMU
+===========================
+
+Lines in this file that begin with a capital letter and a colon are interpreted
+as mixer commands.  All other lines are ignored.
+
+This delta-wing mixer assumes the elevon servos are connected to PX4FMU servo
+outputs 0 and 1 and the motor speed control to output 2. Output 3 is assumed to
+be unused.
+
+Inputs to the mixer come from channel group 0 (vehicle attitude), channels 0
+(roll), 1 (pitch) and 3 (thrust).
+
+See the README for more information on the scaler format.
+
+Elevon mixers
+-------------
+Three scalers total (output, roll, pitch).
+
+On the assumption that the two elevon servos are physically reversed, the pitch
+input is inverted between the two servos.
+
+The scaling factor for roll inputs is adjusted to implement differential travel
+for the elevons.
+
+M: 3
+S: 0 0  10000  10000      0 -10000  10000
+S: 0 0   3000   5000      0 -10000  10000
+S: 0 1   5000   5000      0 -10000  10000
+
+M: 3
+S: 0 0  10000  10000      0 -10000  10000
+S: 0 0   5000   3000      0 -10000  10000
+S: 0 1  -5000  -5000      0 -10000  10000
+
+
+Motor speed mixer
+-----------------
+Two scalers total (output, thrust).
+
+This mixer generates a full-range output (-1 to 1) from an input in the (0 - 1)
+range.  Inputs below zero are treated as zero.
+
+M: 2
+S: 0 0  10000  10000      0 -10000  10000
+S: 0 2      0  20000 -10000 -10000  10000
+
+
+We leave the fourth mixer empty.
+
+M: 0
diff --git a/ROMFS/mixers/README b/ROMFS/mixers/README
new file mode 100644
index 000000000..482478fa7
--- /dev/null
+++ b/ROMFS/mixers/README
@@ -0,0 +1,90 @@
+PX4 mixer definitions
+=====================
+
+Files in this directory implement example mixers that can be used as a basis
+for customisation, or for general testing purposes.
+
+Mixer basics
+------------
+
+Mixers combine control values from various sources (control tasks, user inputs,
+etc.) and produce output values suitable for controlling actuators; servos,
+motors, switches and so on.
+
+An actuator derives its value from the combination of one or more control
+values. Each of the control values is scaled according to the actuator's
+configuration and then combined to produce the actuator value, which may then be
+further scaled to suit the specific output type.
+
+Internally, all scaling is performed using floating point values. Inputs and
+outputs are clamped to the range -1.0 to 1.0.
+
+control    control   control
+   |          |         |
+   v          v         v
+ scale      scale     scale
+   |          |         |
+   |          v         |
+   +-------> mix <------+
+              |
+            scale
+              |
+              v
+             out
+
+Scaling
+-------
+
+Basic scalers provide linear scaling of the input to the output.
+
+Each scaler allows the input value to be scaled independently for inputs
+greater/less than zero. An offset can be applied to the output, and lower and
+upper boundary constraints can be applied. Negative scaling factors cause the
+output to be inverted (negative input produces positive output).
+
+Scaler pseudocode:
+
+if (input < 0)
+    output = (input * NEGATIVE_SCALE) + OFFSET
+else
+    output = (input * POSITIVE_SCALE) + OFFSET
+
+if (output < LOWER_LIMIT)
+    output = LOWER_LIMIT
+if (output > UPPER_LIMIT)
+    output = UPPER_LIMIT
+
+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.
+
+Each file may define more than one mixer; the allocation of mixers to actuators
+is specific to the device reading the mixer definition.
+
+A mixer begins with a line of the form
+
+	M: <scaler count>
+
+If the scaler count is zero, the mixer is a placeholder and the device will not
+allocate a mixer for this position. Otherwise, this line is followed by scaler
+definitions matching the given count.
+
+A scaler definition is a line of the form:
+
+	S: <group> <index> <-ve scale> <+ve scale> <offset> <lower limit> <upper limit>
+
+The first scaler definition following the M: line configures the output scaler.
+The <group> and <index> fields are ignored in this case.
+
+For the remaining scalers, the <group> value identifies the control group from
+which the scaler will read. Control group 0 is the vehicle attitude control
+group; other group numbers may be assigned for other purposes. The <index> value
+selects the  control within the group that will be scaled.
+
+The remaining fields on the line represent the scaler parameters as discussed
+above. Whilst the calculations are performed as floating-point operations, the
+values stored in the definition file are scaled by a factor of 10000; i.e. an
+offset of -0.5 is encoded as -5000.