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 3
 120 vtxtable powervalues 0 1 2
 121 vtxtable powerlabels OFF MIN MAX
 122 ```
 123
 124 #### SmartAudio V1.0 devices should use:
 125 ```
 126 vtxtable powerlevels 4
 127 vtxtable powervalues 7 16 25 40
 128 vtxtable powerlabels 25 200 500 800
 129 ```
 130
 131 #### SmartAudio V2.0 devices should use:
 132 ```
 133 vtxtable powerlevels 4
 134 vtxtable powervalues 0 1 2 3
 135 vtxtable powerlabels 25 200 500 800
 136 ```
 137
 138 #### SmartAudio V2.1 devices vary depending on their model. Check the manufacturers website.
 139 For these devices the `powervalues` are the output power in dBm.
 140
 141 For example the
 142
 143 [TBS Unify Pro32 Nano 5G8](https://www.team-blacksheep.com/products/prod:unifypro32_nano):
 144
 145 ```
 146 vtxtable powerlevels 3
 147 vtxtable powervalues  14 20 26
 148 vtxtable powerlabels 25 100 400
 149 ```
 150
 151 [TBS Unify Pro 5G8 HV - Race 2 (MMCX)](https://www.team-blacksheep.com/products/prod:unify_pro_hv_race2_m):
 152
 153 ```
 154 vtxtable powerlevels 3
 155 vtxtable powervalues  13 20 26
 156 vtxtable powerlabels 25 100 400
 157 ```
 158
 159 [TBS Unify Pro32 HV (MMCX)](https://www.team-blacksheep.com/products/prod:unifypro32_hv):
 160
 161 ```
 162 vtxtable powerlevels 4
 163 vtxtable powervalues 14 20 26 30
 164 vtxtable powerlabels 25 100 400 1W
 165 ```
 166
 167 [TBS Unify EVO](https://www.team-blacksheep.com/products/prod:tbs_unify_evo):
 168
 169 ```
 170 vtxtable powerlevels 4
 171 vtxtable powervalues  14 20 26 29
 172 vtxtable powerlabels 25 100 400 800
 173 ```
 174
 175 Power levels may be omitted. This is useful for compliance with local laws and regulations.
 176 Additionally, powerlabels (but not values!) can be set to anything three characters long.
 177 For example a TBS Unify EVO will also work the this config:
 178
 179 ```
 180 vtxtable powerlevels 2
 181 vtxtable powervalues  20 26
 182 vtxtable powerlabels .1W .4W
 183 ```
 184
 185 ### Complete Examples
 186
 187 #### IRC Tramp device
 188
 189 ```
 190 # This example enables a lot of power levels and channels.
 191 # Almost nobody will be able to legally use this without modification.
 192 # Check your local laws and regulations before use!
 193 vtxtable bands 5
 194 vtxtable channels 8
 195 vtxtable band 1 BOSCAM_A A CUSTOM 5865 5845 5825 5805 5785 5765 5745 5725
 196 vtxtable band 2 BOSCAM_B B CUSTOM 5733 5752 5771 5790 5809 5828 5847 5866
 197 vtxtable band 3 BOSCAM_E E CUSTOM 5705 5685 5665 5645 5885 5905 5925 5945
 198 vtxtable band 4 FATSHARK F CUSTOM 5740 5760 5780 5800 5820 5840 5860 5880
 199 vtxtable band 5 RACEBAND R CUSTOM 5658 5695 5732 5769 5806 5843 5880 5917
 200 vtxtable powerlevels 5
 201 vtxtable powervalues 25 100 200 400 600
 202 vtxtable powerlabels 25 100 200 400 600
 203 ```
 204
 205 #### SmartAudio 1.0 device
 206
 207 ```
 208 # This example enables a lot of power levels and channels.
 209 # Almost nobody will be able to legally use this without modification.
 210 # Check your local laws and regulations before use!
 211 vtxtable bands 5
 212 vtxtable channels 8
 213 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 214 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 215 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 216 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 217 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 218 vtxtable powerlevels 4
 219 vtxtable powervalues 7 16 25 40
 220 vtxtable powerlabels 25 200 500 800
 221 ```
 222
 223 #### SmartAudio 2.0 device
 224
 225 ```
 226 # This example enables a lot of power levels and channels.
 227 # Almost nobody will be able to legally use this without modification.
 228 # Check your local laws and regulations before use!
 229 vtxtable bands 5
 230 vtxtable channels 8
 231 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 232 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 233 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 234 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 235 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 236 vtxtable powerlevels 4
 237 vtxtable powervalues 0 1 2 3
 238 vtxtable powerlabels 25 200 500 800
 239 ```
 240
 241 #### SmartAudio 2.1 device
 242
 243 ```
 244 # This example enables a lot of power levels and channels.
 245 # Almost nobody will be able to legally use this without modification.
 246 # Check your local laws and regulations before use!
 247 vtxtable bands 5
 248 vtxtable channels 8
 249 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 250 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 251 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 252 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 253 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 254 vtxtable powerlevels 4
 255 vtxtable powervalues 14 20 26 30
 256 vtxtable powerlabels 25 100 400 1W
 257 ```
 258
 259 #### rtc6705
 260
 261 ```
 262 # This example enables a lot of power levels and channels.
 263 # Almost nobody will be able to legally use this without modification.
 264 # Check your local laws and regulations before use!
 265 vtxtable bands 5
 266 vtxtable channels 8
 267 vtxtable band 1 BOSCAM_A A CUSTOM 5865 5845 5825 5805 5785 5765 5745 5725
 268 vtxtable band 2 BOSCAM_B B CUSTOM 5733 5752 5771 5790 5809 5828 5847 5866
 269 vtxtable band 3 BOSCAM_E E CUSTOM 5705 5685 5665 5645 5885 5905 5925 5945
 270 vtxtable band 4 FATSHARK F CUSTOM 5740 5760 5780 5800 5820 5840 5860 5880
 271 vtxtable band 5 RACEBAND R CUSTOM 5658 5695 5732 5769 5806 5843 5880 5917
 272 vtxtable powerlevels 3
 273 vtxtable powervalues 0 1 2
 274 vtxtable powerlabels OFF MIN MAX
 275 ```
 276
 277 ### Pitmode
 278 Pitmode is separate from vtxTable. No power level should be created for pitmode.
 279 Pitmode can be controlled in a variety of ways including OSD, AUX switches and lua scripts.
 280
 281 Some videotransmitters have restrictions on its usage. For example, SmartAudio V1.0 and V2.0 devices can only enter pitmode on power-up.
 282 Betaflight can make the these devices leave pitmode, but not enter it.