px4-firmware/ROMFS/mixers

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.