docs/VTX.md

   1 # VTX
   2
   3 Cleanflight supports control of VTX modules.
   4
   5 ## VTX Systems
   6
   7 Current support includes
   8 1. RTC6705 directly connected to the CPU (maybe via a PCB board interconnect, e.g. SPRACINGF3NEO)
   9 2. IRC Tramp
  10 3. TBS Smart Audio
  11
  12 ## VTX Button
  13
  14 If your FC has a button, excluding a BOOT buttons, then it can be used for VTX control.
  15
  16 Some boards like the SPRacingF3NEO have both a VTX module and a button.
  17 Other boards like the SPRacingF3MINI have multiple buttons.
  18
  19 ### VTX Button usage
  20
  21 While the VTX button is held the STATUS 2 LED will flash N times per second indicating the action that will be taken when
  22 the button is released. The flashing starts as soon as the button is held. e.g. You press the button, count flashes and
  23 then release as appropriate.
  24
  25 | Duration      | Function                  | Flashes   |
  26 |---------------|---------------------------|-----------|
  27 | 25ms to 1s    | Cycle Channel             | 4         |
  28 | 1s to 3s      | Cycle Band                | 3         |
  29 | 3s to 5s      | Cycle Power and RF Power  | 2         |
  30 | 5s or more    | Save FC settings          | 1         |
  31
  32 Example to cycle VTX power
  33
  34 ```
  35 | 0 seconds      | 1 second      | 2 seconds    | 3 seconds     | 4 seconds     | 5 seconds     | 6 seconds or more |
  36 |-HOLD BUTTON-----------------------------------|-RELEASE BUTTON-NOW------------|-RELEASED TOO LATE TO CHANGE POWER-|
  37 | 4 Flashes      | 3 flashes     | 3 flashes    | 2 flashes     | 2 flashes     | 1 flash       | 1 flash           |
  38 ```
  39
  40 The VTX button works with ALL VTX systems including onboard RTC6705, Tramp and SmartAudio.
  41
  42
  43 If the VTX can be turned off then POWER 0 will turn off the VTX and POWER 1 will set the VTX into it's lowest power output.
  44 If the VTX cannot be turned off then POWER 0 will set the VTX into it's lowest power output.
  45
  46 ## VTX Table
  47
  48 As of Betaflight 4.1.0, band/channel and power level information needed to control videotransmitters is no longer hardcoded,
  49 but stored in a new facility called vtxTable.
  50
  51 The contents of the vtxTable need to be setup manually. They need to match the hardware, local laws and regulations, as
  52 well as user preferences.
  53
  54 The contents of the table can be examined by typing the command `vtxtable` into the cli.
  55 Example:
  56 ```
  57 # vtxtable
  58 vtxtable bands 5
  59 vtxtable channels 8
  60 vtxtable band 1 BOSCAM_A A FACTORY    0 5845 5825 5805 5785 5765 5745    0
  61 vtxtable band 2 BOSCAM_B B FACTORY    0 5752 5771 5790 5809 5828 5847    0
  62 vtxtable band 3 BOSCAM_E E FACTORY    0    0    0    0    0    0    0    0
  63 vtxtable band 4 MYBAND   M CUSTOM  5745 5769    0 5806    0 5843    0    0
  64 vtxtable band 5 RACEBAND R FACTORY    0    0    0 5769 5806 5843    0    0
  65 vtxtable powerlevels 3
  66 vtxtable powervalues  14 20 26
  67 vtxtable powerlabels 25 100 400
  68 ```
  69
  70 ### Bands and channels
  71
  72 The example above contains 5 bands, **each with a name, a single-letter abbreviation, a factory flag and eight frequencies.**
  73
  74 The factory flag controls how Betaflight communicates with the vtx.
  75
  76 **When the flag is set to `FACTORY`, Betaflight sends the vtx a band and channel number.**
  77 The vtx will then use its built-in frequency table.
  78 In this mode, the actual contents of the vtxtable are **not** send the vtx. They are only used for display in the OSD and similar places.
  79 As such, bands with the flag set to `FACTORY` should be set to match the built-in frequency table of the vtx.
  80
  81 **When the flag is set to `CUSTOM`, Betaflight sends the vtx the frequency it should use.**
  82 This mode utilizes the contents of the table and allows the user to create custom bands with whatever frequencies they like.
  83 **Videotransmitters without a built-in table, such as IRC Tramp or rtc6705 only support `CUSTOM`.**
  84
  85 Entries of the vtxtable can be blocked by setting their frequency to 0. This is especially useful for bands set to `FACTORY`: The spots of
  86 unwanted entries of the videotransmitter's built-in table can be set to 0, effectively disabling them.
  87 In the example above this was used to only allow frequencies between 5725 and 5875 MHz, as a German pilot would want it to comply with
  88 German laws. Additionally, the Fatshark band was replaced with a new custom one.
  89
  90 As a starting point, the following table contains the commonly used frequencies:
  91
  92 ```
  93 # This table should not be used as-is, but trimmed down according to local laws and regulations.
  94 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
  95 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
  96 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
  97 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
  98 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
  99 ```
 100
 101
 102 ### Power levels
 103
 104 In addition the the frequency, videotransmitters also need to know how much power they should use for transmission.
 105 The example shown previously contains three power levels, **each with a value and a label.** The label is shown to the user in the OSD,
 106 while the value is sent to the vtx.
 107
 108 Power levels should be setup to match the hardware in use.
 109
 110 #### IRC Tramp devices should use:
 111 ```
 112 vtxtable powerlevels 5
 113 vtxtable powervalues 25 100 200 400 600
 114 vtxtable powerlabels 25 100 200 400 600
 115 ```
 116
 117 #### rtc6705 should use:
 118 ```
 119 vtxtable powerlevels 2
 120 vtxtable powervalues 1 2
 121 vtxtable powerlabels MIN MAX
 122 ```
 123
 124 Please note that turning off rtc6705 devices is not possible using powervalues. Use pitmode instead.
 125
 126 #### SmartAudio V1.0 devices should use:
 127 ```
 128 vtxtable powerlevels 4
 129 vtxtable powervalues 7 16 25 40
 130 vtxtable powerlabels 25 200 500 800
 131 ```
 132
 133 #### SmartAudio V2.0 devices should use:
 134 ```
 135 vtxtable powerlevels 4
 136 vtxtable powervalues 0 1 2 3
 137 vtxtable powerlabels 25 200 500 800
 138 ```
 139
 140 #### SmartAudio V2.1 devices vary depending on their model. Check the manufacturers website.
 141 For these devices the `powervalues` are the output power in dBm.
 142
 143 To query the available power levels from a SmartAudio 2.1 VTX enter the `vtx_info` command with no parameters. This will report the available power settings thus:
 144
 145 ```
 146 # vtx_info
 147 level 14 dBm, power 25 mW
 148 level 20 dBm, power 100 mW
 149 level 26 dBm, power 400 mW
 150 ```
 151
 152 For example the
 153
 154 [TBS Unify Pro32 Nano 5G8](https://www.team-blacksheep.com/products/prod:unifypro32_nano):
 155
 156 ```
 157 vtxtable powerlevels 3
 158 vtxtable powervalues 14 20 26
 159 vtxtable powerlabels 25 100 400
 160 ```
 161
 162 [TBS Unify Pro 5G8 HV - Race 2 (MMCX)](https://www.team-blacksheep.com/products/prod:unify_pro_hv_race2_m):
 163
 164 ```
 165 vtxtable powerlevels 3
 166 vtxtable powervalues 13 20 26
 167 vtxtable powerlabels 25 100 400
 168 ```
 169
 170 [TBS Unify Pro32 HV (MMCX)](https://www.team-blacksheep.com/products/prod:unifypro32_hv):
 171
 172 ```
 173 vtxtable powerlevels 4
 174 vtxtable powervalues 14 20 26 30
 175 vtxtable powerlabels 25 100 400 1W
 176 ```
 177
 178 [TBS Unify EVO](https://www.team-blacksheep.com/products/prod:tbs_unify_evo):
 179
 180 ```
 181 vtxtable powerlevels 4
 182 vtxtable powervalues 14 20 26 29
 183 vtxtable powerlabels 25 100 400 800
 184 ```
 185
 186 Power levels may be omitted. This is useful for compliance with local laws and regulations.
 187 Additionally, powerlabels (but not values!) can be set to anything three characters long.
 188 For example a TBS Unify EVO will also work the this config:
 189
 190 ```
 191 vtxtable powerlevels 2
 192 vtxtable powervalues 20 26
 193 vtxtable powerlabels .1W .4W
 194 ```
 195
 196 ### Complete Examples
 197
 198 #### IRC Tramp device
 199
 200 ```
 201 # This example enables a lot of power levels and channels.
 202 # Almost nobody will be able to legally use this without modification.
 203 # Check your local laws and regulations before use!
 204 vtxtable bands 5
 205 vtxtable channels 8
 206 vtxtable band 1 BOSCAM_A A CUSTOM 5865 5845 5825 5805 5785 5765 5745 5725
 207 vtxtable band 2 BOSCAM_B B CUSTOM 5733 5752 5771 5790 5809 5828 5847 5866
 208 vtxtable band 3 BOSCAM_E E CUSTOM 5705 5685 5665 5645 5885 5905 5925 5945
 209 vtxtable band 4 FATSHARK F CUSTOM 5740 5760 5780 5800 5820 5840 5860 5880
 210 vtxtable band 5 RACEBAND R CUSTOM 5658 5695 5732 5769 5806 5843 5880 5917
 211 vtxtable powerlevels 5
 212 vtxtable powervalues 25 100 200 400 600
 213 vtxtable powerlabels 25 100 200 400 600
 214 ```
 215
 216 #### SmartAudio 1.0 device
 217
 218 ```
 219 # This example enables a lot of power levels and channels.
 220 # Almost nobody will be able to legally use this without modification.
 221 # Check your local laws and regulations before use!
 222 vtxtable bands 5
 223 vtxtable channels 8
 224 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 225 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 226 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 227 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 228 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 229 vtxtable powerlevels 4
 230 vtxtable powervalues 7 16 25 40
 231 vtxtable powerlabels 25 200 500 800
 232 ```
 233
 234 #### SmartAudio 2.0 device
 235
 236 ```
 237 # This example enables a lot of power levels and channels.
 238 # Almost nobody will be able to legally use this without modification.
 239 # Check your local laws and regulations before use!
 240 vtxtable bands 5
 241 vtxtable channels 8
 242 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 243 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 244 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 245 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 246 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 247 vtxtable powerlevels 4
 248 vtxtable powervalues 0 1 2 3
 249 vtxtable powerlabels 25 200 500 800
 250 ```
 251
 252 #### SmartAudio 2.1 device
 253
 254 ```
 255 # This example enables a lot of power levels and channels.
 256 # Almost nobody will be able to legally use this without modification.
 257 # Check your local laws and regulations before use!
 258 vtxtable bands 5
 259 vtxtable channels 8
 260 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 261 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 262 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 263 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 264 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 265 vtxtable powerlevels 4
 266 vtxtable powervalues 14 20 26 30
 267 vtxtable powerlabels 25 100 400 1W
 268 ```
 269
 270 #### rtc6705
 271
 272 ```
 273 # This example enables a lot of power levels and channels.
 274 # Almost nobody will be able to legally use this without modification.
 275 # Check your local laws and regulations before use!
 276 vtxtable bands 5
 277 vtxtable channels 8
 278 vtxtable band 1 BOSCAM_A A CUSTOM 5865 5845 5825 5805 5785 5765 5745 5725
 279 vtxtable band 2 BOSCAM_B B CUSTOM 5733 5752 5771 5790 5809 5828 5847 5866
 280 vtxtable band 3 BOSCAM_E E CUSTOM 5705 5685 5665 5645 5885 5905 5925 5945
 281 vtxtable band 4 FATSHARK F CUSTOM 5740 5760 5780 5800 5820 5840 5860 5880
 282 vtxtable band 5 RACEBAND R CUSTOM 5658 5695 5732 5769 5806 5843 5880 5917
 283 vtxtable powerlevels 2
 284 vtxtable powervalues 1 2
 285 vtxtable powerlabels MIN MAX
 286 ```
 287
 288 ### Pitmode
 289 Pitmode is separate from vtxTable. No power level should be created for pitmode.
 290 Pitmode can be controlled in a variety of ways including OSD, AUX switches and lua scripts.
 291
 292 Some videotransmitters have restrictions on its usage. For example, SmartAudio V1.0 and V2.0 devices can only enter pitmode on power-up.
 293 Betaflight can make the these devices leave pitmode, but not enter it.
 294
 295 rtc6705 devices do not support a proper ultra-low power pitmode. Instead, if the board supports it, pitmode turns off rtc6705 devices completely.