docs/Mixer.md

   1 # Mixer
   2
   3 Cleanflight supports a number of mixing configurations as well as custom mixing.  Mixer configurations determine how the servos and motors work together to control the aircraft.
   4
   5 ## Configuration
   6
   7 To use a built-in mixing configuration, you can use the Chrome configuration GUI.  It includes images of the various mixer types to assist in making the proper connections.  See the Configuration section of the documentation for more information on the GUI.
   8
   9 You can also use the Command Line Interface (CLI) to set the mixer type:
  10
  11 1. Use `mixer list` to see a list of supported mixes
  12 2. Select a mixer.  For example, to select TRI, use `mixer TRI`
  13 3. You must use `save` to preserve your changes
  14
  15 ## Supported Mixer Types
  16
  17 | Name             | Description               | Motors         | Servos           |
  18 | ---------------- | ------------------------- | -------------- | ---------------- |
  19 | TRI              | Tricopter                 | M1-M3          | S1               |
  20 | QUADP            | Quadcopter-Plus           | M1-M4          | None             |
  21 | QUADX            | Quadcopter-X              | M1-M4          | None             |
  22 | BI               | Bicopter (left/right)     | M1-M2          | S1, S2           |
  23 | GIMBAL           | Gimbal control            | N/A            | S1, S2           |
  24 | Y6               | Y6-copter                 | M1-M6          | None             |
  25 | HEX6             | Hexacopter-Plus           | M1-M6          | None             |
  26 | FLYING_WING      | Fixed wing; elevons       | M1             | S1, S2           |
  27 | Y4               | Y4-copter                 | M1-M4          | None             |
  28 | HEX6X            | Hexacopter-X              | M1-M6          | None             |
  29 | OCTOX8           | Octocopter-X (over/under) | M1-M8          | None             |
  30 | OCTOFLATP        | Octocopter-FlatPlus       | M1-M8          | None             |
  31 | OCTOFLATX        | Octocopter-FlatX          | M1-M8          | None             |
  32 | AIRPLANE         | Fixed wing; Ax2, R, E     | M1             | S1, S2, S3, S4   |
  33 | HELI_120_CCPM    |                           |                |                  |
  34 | HELI_90_DEG      |                           |                |                  |
  35 | VTAIL4           | Quadcopter with V-Tail    | M1-M4          | N/A              |
  36 | HEX6H            | Hexacopter-H              | M1-M6          | None             |
  37 | PPM_TO_SERVO     |                           |                |                  |
  38 | DUALCOPTER       | Dualcopter                | M1-M2          | S1, S2           |
  39 | SINGLECOPTER     | Conventional helicopter   | M1             | S1               |
  40 | ATAIL4           | Quadcopter with A-Tail    | M1-M4          | N/A              |
  41 | CUSTOM           | User-defined              |                |                  |
  42 | CUSTOM AIRPLANE  | User-defined airplane     | M1-M2          | S1-S8            |
  43 | CUSTOM TRICOPTER | User-defined tricopter    |                |                  |
  44
  45 ## Servo configuration
  46
  47 The cli `servo` command defines the settings for the servo outputs.
  48 The cli mixer `smix` command controls how the mixer maps internal FC data (RC input, PID stabilization output, channel forwarding, etc) to servo outputs.
  49
  50 ### cli `servo`
  51
  52 `servo <min> <max> <middle> <angleMin> <angleMax> <rate> <forwardFromChannel>`
  53
  54 - `<min>`, `<max>` - limit servo travel, in uS
  55
  56 - `<middle>` - mid value when not forwarding, value from servo mixer is added to this.
  57
  58 - `<angleMin>`,  `<angleMax>` - unused
  59
  60 - `<rate>` - scale for value from servo mixer or gimbal input, -100% .. 100%
  61
  62 - `<forwardFromChannel>` - use RC channel value as reference instead of `<middle>`. Servo will follow given RC channel, with possible correction from servo mixer. `<min>`, `<max>` are still honored.
  63
  64
  65 ## Servo filtering
  66
  67 A low-pass filter can be enabled for the servos.  It may be useful for avoiding structural modes in the airframe, for example.
  68
  69 ### Configuration
  70
  71 Currently it can only be configured via the CLI:
  72
  73 1. Use `set servo_lowpass_freq = nnn` to select the cutoff frequency.  Valid values range from 10Hz to 400Hz, second order filter is used.
  74 2. Use `set servo_lowpass_enable = ON` to enable filtering.
  75
  76 ### Tuning
  77
  78 One method for tuning the filter cutoff is as follows:
  79
  80 1. Ensure your vehicle can move at least somewhat freely in the troublesome axis.  For example, if you are having yaw oscillations on a tricopter, ensure that the copter is supported in a way that allows it to rotate left and right to at least some degree.  Suspension near the CG is ideal.  Alternatively, you can just fly the vehicle and trigger the problematic condition you are trying to eliminate, although tuning will be more tedious.
  81
  82 2. Tap the vehicle at its end in the axis under evaluation.  Directly commanding the servo in question to move may also be used.  In the tricopter example, tap the end of the tail boom from the side, or command a yaw using your transmitter.
  83
  84 3. If your vehicle oscillates for several seconds or even continues oscillating indefinitely, then the filter cutoff frequency should be reduced. Reduce the value of `servo_lowpass_freq` by half its current value and repeat the previous step.
  85
  86 4. If the oscillations are dampened within roughly a second or are no longer present, then you are done.  Be sure to run `save`.
  87
  88 ## Custom Motor Mixing
  89
  90 Custom motor mixing allows for completely customized motor configurations. Each motor must be defined with a custom mixing table for that motor. The mix must reflect how close each motor is with reference to the CG (Center of Gravity) of the flight controller. A motor closer to the CG of the flight controller will need to travel less distance than a motor further away.
  91
  92 Steps to configure custom mixer in the CLI:
  93
  94 1. Use `mixer custom` to enable the custom mixing.
  95 2. Use `mmix reset` to erase the any existing custom mixing.
  96 3. Optionally use `mmix load <name>` to start with one of available mixers.
  97 4. Issue a `mmix` statement for each motor.
  98
  99 The `mmix` statement has the following syntax: `mmix n THROTTLE ROLL PITCH YAW`
 100
 101 | Mixing table parameter | Definition |
 102 | ---------------------- | ---------- |
 103 | n                      | Motor ordering number |
 104 | THROTTLE               | Indicates how much throttle is mixed for this motor. All values used in current configurations are set to 1.0 (full throttle mixing), but other non-zero values may be used. Unused set to 0.0. |
 105 | ROLL                   | Indicates how much roll authority this motor imparts to the roll of the flight controller. Accepts values nominally from -1.0 to 1.0. |
 106 | PITCH                  | Indicates the pitch authority this motor has over the flight controller. Also accepts values nominally from -1.0 to 1.0. |
 107 | YAW                    | Indicates the direction of the motor rotation in relationship with the flight controller. 1.0 = CCW -1.0 = CW. |
 108
 109 Note: the `mmix` command may show a motor mix that is not active, custom motor mixes are only active for models that use custom mixers.
 110
 111 Note: You have to configure every motor number starting at 0. Your command will be ignored if there was no `mmix` command for the previous motor number (mixer stops on first THROTTLE value that is zero). See example 5.
 112
 113
 114 ## Custom Servo Mixing
 115
 116 Custom servo mixing rules can be applied to each servo.  Rules are applied in the order they are defined.
 117
 118 ##### `smix`
 119
 120 Prints current servo mixer
 121
 122 Note: the `smix` command may show a servo mix that is not active, custom servo mixes are only active for models that use custom mixers.
 123
 124 ##### `smix reset`
 125
 126 Erase custom mixer. Servo reversal in current profile ONLY is erased too.
 127
 128 ##### `smix load <name>`
 129
 130 Load servo part of given configuration (`<name>` is from `mixer list`)
 131
 132 ##### `smix <rule> <servo> <source> <rate> <speed> <min> <max> <box>`
 133
 134 - `<rule>` is index of rule, used mainly for bookkeeping. Rules are applied in this order, but ordering has no influence on result in current code.
 135
 136 - `<servo>`
 137
 138 | id |  Servo slot |
 139 |----|--------------|
 140 | 0  | GIMBAL PITCH |
 141 | 1  | GIMBAL ROLL |
 142 | 2  | ELEVATOR / SINGLECOPTER_4 |
 143 | 3  | FLAPPERON 1 (LEFT) / SINGLECOPTER_1 |
 144 | 4  | FLAPPERON 2 (RIGHT) / BICOPTER_LEFT / DUALCOPTER_LEFT / SINGLECOPTER_2 |
 145 | 5  | RUDDER / BICOPTER_RIGHT / DUALCOPTER_RIGHT / SINGLECOPTER_3 |
 146 | 6  | THROTTLE (Based ONLY on the first motor output) |
 147 | 7  | FLAPS |
 148
 149 Only some `<servo>` channels are connected to output, based on mode. For custom modes:
 150   - RUDDER for CUSTOM_TRI
 151   - ELEVATOR ... FLAPS for CUSTOM_AIRPLANE
 152   - no servos for CUSTOM
 153
 154 GIMBAL handling is hard-coded, mmix rule is ignored.
 155
 156 - `<source>`
 157
 158 | id |  Input sources |
 159 |----|-----------------|
 160 | 0  | Stabilized ROLL |
 161 | 1  | Stabilized PITCH |
 162 | 2  | Stabilized YAW |
 163 | 3  | Stabilized THROTTLE (ONLY the first motor output) |
 164 | 4  | RC ROLL |
 165 | 5  | RC PITCH |
 166 | 6  | RC YAW |
 167 | 7  | RC THROTTLE |
 168 | 8  | RC AUX 1 |
 169 | 9  | RC AUX 2 |
 170 | 10 | RC AUX 3 |
 171 | 11 | RC AUX 4 |
 172 | 12 | GIMBAL PITCH |
 173 | 13 | GIMBAL ROLL |
 174
 175 Stabilized ROLL/PITCH/YAW is taken directly from RC command when in PASSTHRU mode.
 176
 177 - `<rate>` is used to scale `<source>`, -100% - 100% is allowed. Note that servo reversal may be applied, see below. Zero `<rate>` will terminate smix table.
 178
 179 - `<speed>` will limit <source> speed when non-zero. This speed is taken per-rule, so you may limit only some sources. Value is maximal change of value per loop (1ms with default configuration)
 180
 181 - `<min>` `<max>` - Value in percentage of full servo range. For symmetrical servo limits (equal distance between mid and min/max), 0% is servo min, 50% is servo center, 100% is max servo position. When mid position is asymmetrical, 0% and 100% limits will be shifted.
 182
 183 - `<box>` rule will be applied only when `<box>` is zero or corresponding SERVOx mode is enabled.
 184
 185 ##### `smix reverse`
 186
 187 Print current servo reversal configuration
 188
 189 ##### `smix reverse <servo> <source> r|n`
 190
 191 Each `<source>` may be `r`eversed or `n`ormal for given `<servo>`. It is almost equivalent to using negative <rate> in given rule, but `<min>, `<max>` limits are applied to value before reversing.
 192 `smix reverse` works for non-custom mixers too.
 193
 194 e.g. when using the TRI mixer to reverse the tail servo on a tricopter use this:
 195
 196 `smix reverse 5 2 r`
 197
 198 i.e. when mixing rudder servo slot (`5`) using Stabilized YAW input source (`2`) reverse the direction (`r`)
 199
 200 `smix reverse` is a per-profile setting.  So ensure you configure it for your profiles as required.
 201
 202
 203 ### Example 1: A KK2.0 wired motor setup
 204 Here's an example of a X configuration quad, but the motors are still wired using the KK board motor numbering scheme.
 205
 206 ```
 207 KK2.0 Motor Layout
 208
 209   1CW      2CCW
 210      \    /
 211        KK
 212      /    \
 213   4CCW     3CW
 214 ```
 215
 216 1. Use `mixer custom`
 217 2. Use `mmix reset`
 218 3. Use `mmix 0 1.0,  1.0, -1.0, -1.0` for the Front Left motor. It tells the flight controller the #1 motor is used, provides positive roll, provides negative pitch and is turning CW.
 219 4. Use `mmix 1 1.0, -1.0, -1.0,  1.0` for the Front Right motor. It still provides a negative pitch authority, but unlike the front left, it provides negative roll authority and turns CCW.
 220 5. Use `mmix 2 1.0, -1.0,  1.0, -1.0` for the Rear Right motor. It has negative roll, provides positive pitch when the speed is increased and turns CW.
 221 6. Use `mmix 3 1.0,  1.0,  1.0,  1.0` for the Rear Left motor. Increasing motor speed imparts positive roll, positive pitch and turns CCW.
 222
 223 ### Example 2: A HEX-U Copter
 224
 225 Here is an example of a U-shaped hex; probably good for herding giraffes in the Sahara. Because the 1 and 6 motors are closer to the roll axis, they impart much less force than the motors mounted twice as far from the FC CG. The effect they have on pitch is the same as the forward motors because they are the same distance from the FC CG. The 2 and 5 motors do not contribute anything to pitch because speeding them up and slowing them down has no effect on the forward/back pitch of the FC.
 226
 227 ```
 228 HEX6-U
 229
 230 .4........3.
 231 ............
 232 .5...FC...2.
 233 ............
 234 ...6....1...
 235 ```
 236
 237 |Command| Roll | Pitch | Yaw |
 238 | ----- | ---- | ----- | --- |
 239 | Use `mmix 0 1.0, -0.5,  1.0, -1.0` | half negative | full positive | CW |
 240 | Use `mmix 1 1.0, -1.0,  0.0,  1.0` | full negative | none | CCW |
 241 | Use `mmix 2 1.0, -1.0, -1.0, -1.0` | full negative | full negative | CW |
 242 | Use `mmix 3 1.0,  1.0, -1.0,  1.0` | full positive | full negative | CCW  |
 243 | Use `mmix 4 1.0,  1.0,  0.0, -1.0` | full positive | none | CW |
 244 | Use `mmix 5 1.0,  0.5,  1.0,  1.0` | half positive | full positive | CCW |
 245
 246 ### Example 3: Custom tricopter
 247
 248 ```
 249 mixer CUSTOMTRI
 250 mmix reset
 251 mmix 0 1.000 0.000 1.333 0.000
 252 mmix 1 1.000 -1.000 -0.667 0.000
 253 mmix 2 1.000 1.000 -0.667 0.000
 254 smix reset
 255 smix 0 5 2 100 0 0 100 0
 256 profile 0
 257 smix reverse 5 2 r
 258 profile 1
 259 smix reverse 5 2 r
 260 profile 2
 261 smix reverse 5 2 r
 262
 263 ```
 264
 265 ### Example 4: Custom Airplane with Differential Thrust
 266 Here is an example of a custom twin engine plane with [Differential Thrust](http://rcvehicles.about.com/od/rcairplanes/ss/RCAirplaneBasic.htm#step8)
 267 Motors take the first 2 pins, the servos take pins as indicated in the [Servo slot] chart above.
 268 Settings bellow have motor yaw influence at "0.3", you can change this number to have more or less differential thrust over the two motors.
 269 Note: You can look at the Motors tab in [Cleanflight Cofigurator](https://chrome.google.com/webstore/detail/cleanflight-configurator/enacoimjcgeinfnnnpajinjgmkahmfgb?hl=en) to see motor and servo outputs.
 270
 271 | Pins | Outputs          |
 272 |------|------------------|
 273 | 1    | Left Engine      |
 274 | 2    | Right Engine     |
 275 | 3    | Pitch / Elevator |
 276 | 4    | Roll / Aileron   |
 277 | 5    | Roll / Aileron   |
 278 | 6    | Yaw / Rudder     |
 279 | 7    | [EMPTY]          |
 280 | 8    | [EMPTY]          |
 281
 282 ```
 283 mixer CUSTOMAIRPLANE
 284 mmix reset
 285 mmix 0 1.0 0.0 0.0 0.3   # Left Engine
 286 mmix 1 1.0 0.0 0.0 -0.3  # Right Engine
 287
 288 smix reset
 289 # Rule  Servo   Source  Rate    Speed   Min     Max     Box
 290 smix 0 3 0 100 0 0 100 0  # Roll / Aileron
 291 smix 1 4 0 100 0 0 100 0  # Roll / Aileron
 292 smix 2 5 2 100 0 0 100 0  # Yaw / Rudder
 293 smix 3 2 1 100 0 0 100 0  # Pitch / Elevator
 294
 295 ```
 296
 297 ### Example 5: Use motor output 0,1,2,4 because your output 3 is broken
 298 For this to work you have to make a dummy mmix for motor 3. We do this by just saying it has 0 impact on yaw, roll and pitch.
 299 ```
 300 mixer custom
 301 mmix reset
 302 mmix 0 1.0, -1.0, 1.0, -1.0
 303 mmix 1 1.0, -1.0, -1.0,  1.0
 304 mmix 2 1.0, 1.0, 1.0, 1.0
 305 mmix 3 1.0, 0.0, 0.0, 0.0
 306 mmix 4 1.0, 1.0, -1.0, -1.0
 307 save
 308 ```