docs/Mixer.md

   1 # Mixer
   2
   3 INAV 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     |                |                  |
  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 controllers how the mixer maps internal FC data (RC input, PID stabilisation output, channel forwarding, etc) to servo outputs.
  49
  50 ## Servo filtering
  51
  52 A low-pass filter can be enabled for the servos.  It may be useful for avoiding structural modes in the airframe, for example.
  53
  54 ### Configuration
  55
  56 Currently it can only be configured via the CLI:
  57
  58 1. Use `set servo_lowpass_freq = nnn` to select the cutoff frequency.  Valid values range from 10 to 400.  This is a fraction of the loop frequency in 1/1000ths. For example, `40` means `0.040`.
  59 2. Use `set servo_lowpass_enable = 1` to enable filtering.
  60
  61 The cutoff frequency can be determined by the following formula:
  62 `Frequency = 1000 * servo_lowpass_freq / looptime`
  63
  64 For example, if `servo_lowpass_freq` is set to 40, and looptime is set to the default of 3500 us, the cutoff frequency will be 11.43 Hz.
  65
  66 ### Tuning
  67
  68 One method for tuning the filter cutoff is as follows:
  69
  70 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.
  71
  72 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.
  73
  74 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.
  75
  76 4. If the oscillations are dampened within roughly a second or are no longer present, then you are done.  Be sure to run `save`.
  77
  78 ## Custom Motor Mixing
  79
  80 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.
  81
  82 Steps to configure custom mixer in the CLI:
  83
  84 1. Use `mixer custom` to enable the custom mixing.
  85 2. Use `mmix reset` to erase the any existing custom mixing.
  86 3. Issue a `mmix` statement for each motor.
  87
  88 The mmix statement has the following syntax: `mmix n THROTTLE ROLL PITCH YAW`
  89
  90 | Mixing table parameter | Definition |
  91 | ---------------------- | ---------- |
  92 | n     | Motor ordering number |
  93 | THROTTLE      | All motors that are used in this configuration are set to 1.0. Unused set to 0.0. |
  94 | 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. |
  95 | PITCH | Indicates the pitch authority this motor has over the flight controller. Also accepts values nominally from 1.0 to -1.0. |
  96 | YAW   | Indicates the direction of the motor rotation in relationship with the flight controller. 1.0 = CCW -1.0 = CW. |
  97
  98 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.
  99
 100 ## Custom Servo Mixing
 101
 102 Custom servo mixing rules can be applied to each servo.  Rules are applied in the order they are defined.
 103
 104 | id | Servo slot |
 105 |----|--------------|
 106 | 0  | GIMBAL PITCH |
 107 | 1  | GIMBAL ROLL |
 108 | 2  | ELEVATOR / SINGLECOPTER_4 |
 109 | 3  | FLAPPERON 1 (LEFT) / SINGLECOPTER_1 |
 110 | 4  | FLAPPERON 2 (RIGHT) / BICOPTER_LEFT / DUALCOPTER_LEFT / SINGLECOPTER_2 |
 111 | 5  | RUDDER / BICOPTER_RIGHT / DUALCOPTER_RIGHT / SINGLECOPTER_3 |
 112 | 6  | THROTTLE (Based ONLY on the first motor output) |
 113 | 7  | FLAPS |
 114
 115
 116 | id | Input sources |
 117 |----|-----------------|
 118 | 0  | Stabilised ROLL |
 119 | 1  | Stabilised PITCH |
 120 | 2  | Stabilised YAW |
 121 | 3  | Stabilised THROTTLE |
 122 | 4  | RC ROLL |
 123 | 5  | RC PITCH |
 124 | 6  | RC YAW |
 125 | 7  | RC THROTTLE |
 126 | 8  | RC AUX 1 |
 127 | 9  | RC AUX 2 |
 128 | 10 | RC AUX 3 |
 129 | 11 | RC AUX 4 |
 130 | 12 | GIMBAL PITCH |
 131 | 13 | GIMBAL ROLL |
 132
 133 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.
 134
 135 ## Servo Reversing
 136
 137 Servos are reversed using the `smix reverse` command.
 138
 139 e.g. when using the TRI mixer to reverse the tail servo on a tricopter use this:
 140
 141 `smix reverse 5 2 r`
 142
 143 i.e. when mixing rudder servo slot (`5`) using Stabilised YAW input source (`2`) reverse the direction (`r`)
 144
 145 `smix reverse` is a per-profile setting.  So ensure you configure it for your profiles as required.
 146
 147 ### Example 1: A KK2.0 wired motor setup
 148 Here's an example of a X configuration quad, but the motors are still wired using the KK board motor numbering scheme.
 149
 150 ```
 151 KK2.0 Motor Layout
 152
 153   1CW      2CCW
 154      \    /
 155        KK
 156      /    \
 157   4CCW     3CW
 158 ```
 159
 160 1. Use `mixer custom`
 161 2. Use `mmix reset`
 162 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.
 163 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.
 164 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.
 165 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.
 166
 167 ### Example 2: A HEX-U Copter
 168
 169 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.
 170
 171 ```
 172 HEX6-U
 173
 174 .4........3.
 175 ............
 176 .5...FC...2.
 177 ............
 178 ...6....1...
 179 ```
 180
 181 |Command| Roll | Pitch | Yaw |
 182 | ----- | ---- | ----- | --- |
 183 | Use `mmix 0 1.0, -0.5,  1.0, -1.0` | half negative | full positive | CW |
 184 | Use `mmix 1 1.0, -1.0,  0.0,  1.0` | full negative | none | CCW |
 185 | Use `mmix 2 1.0, -1.0, -1.0, -1.0` | full negative | full negative | CW |
 186 | Use `mmix 3 1.0,  1.0, -1.0,  1.0` | full positive | full negative | CCW  |
 187 | Use `mmix 4 1.0,  1.0,  0.0, -1.0` | full positive | none | CW |
 188 | Use `mmix 5 1.0,  0.5,  1.0,  1.0` | half positive | full positive | CCW |
 189
 190 ### Example 3: Custom tricopter
 191
 192 ```
 193 mixer CUSTOMTRI
 194 mmix reset
 195 mmix 0 1.000 0.000 1.333 0.000
 196 mmix 1 1.000 -1.000 -0.667 0.000
 197 mmix 2 1.000 1.000 -0.667 0.000
 198 smix reset
 199 smix 0 5 2 100 0 0 100 0
 200 profile 0
 201 smix reverse 5 2 r
 202 profile 1
 203 smix reverse 5 2 r
 204 profile 2
 205 smix reverse 5 2 r
 206
 207 ```
 208
 209 ### Example 4: Custom Airplane with Differential Thrust
 210 Here is an example of a custom twin engine plane with [Differential Thrust](http://rcvehicles.about.com/od/rcairplanes/ss/RCAirplaneBasic.htm#step8)
 211 Motors take the first 2 pins, the servos take pins as indicated in the [Servo slot] chart above.
 212 Settings bellow have motor yaw influence at "0.3", you can change this nuber to have more or less differential thrust over the two motors.
 213 Note: You can look at the Motors tab in [INAV Cofigurator](https://chrome.google.com/webstore/detail/cleanflight-configurator/enacoimjcgeinfnnnpajinjgmkahmfgb?hl=en) to see motor and servo outputs.
 214
 215 | Pins | Outputs          |
 216 |------|------------------|
 217 | 1    | Left Engine      |
 218 | 2    | Right Engine     |
 219 | 3    | [EMPTY]          |
 220 | 4    | Roll / Aileron   |
 221 | 5    | Roll / Aileron   |
 222 | 6    | Yaw / Rudder     |
 223 | 7    | Pitch / Elevator |
 224 | 8    | [EMPTY]          |
 225
 226 ```
 227 mixer CUSTOMAIRPLANE
 228 mmix reset
 229 mmix 0 1.0 0.0 0.0 0.3  # Left Engine
 230 mmix 1 1.0 0.0 0.0 -0.3  # Right Engine
 231
 232 smix reset
 233 # Rule  Servo   Source  Rate    Speed   Min     Max     Box
 234 smix 0 3 0 100 0 0 100 0  # Roll / Aileron
 235 smix 1 4 0 100 0 0 100 0  # Roll / Aileron
 236 smix 3 5 2 100 0 0 100 0  # Yaw / Rudder
 237 smix 2 2 1 100 0 0 100 0  # Pitch / Elevator
 238
 239 ```