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 | 0 seconds      | 1 second      | 2 seconds    | 3 seconds     | 4 seconds     | 5 seconds     | 6 seconds or more |
  35 |-HOLD BUTTON-----------------------------------|-RELEASE BUTTON-NOW------------|-RELEASED TOO LATE TO CHANGE POWER-|
  36 | 4 Flashes      | 3 flashes     | 3 flashes    | 2 flashes     | 2 flashes     | 1 flash       | 1 flash           |
  37 ```
  38
  39 The VTX button works with ALL VTX systems including onboard RTC6705, Tramp and SmartAudio.
  40
  41
  42 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.
  43 If the VTX cannot be turned off then POWER 0 will set the VTX into it's lowest power output.
  44
  45 ## VTX Table
  46
  47 As of Betaflight 4.1.0, band/channel and power level information needed to control videotransmitters is no longer hardcoded,
  48 but stored in a new facility called vtxTable.
  49
  50 The contents of the vtxTable need to be setup manually. They need to match the hardware, local laws and regulations, as
  51 well as user preferences.
  52
  53 The contents of the table can be examined by typing the command `vtxtable` into the cli.
  54 Example:
  55 ```
  56 # vtxtable
  57 vtxtable bands 5
  58 vtxtable channels 8
  59 vtxtable band 1 BOSCAM_A A FACTORY    0 5845 5825 5805 5785 5765 5745    0
  60 vtxtable band 2 BOSCAM_B B FACTORY    0 5752 5771 5790 5809 5828 5847    0
  61 vtxtable band 3 BOSCAM_E E FACTORY    0    0    0    0    0    0    0    0
  62 vtxtable band 4 MYBAND   M CUSTOM  5745 5769    0 5806    0 5843    0    0
  63 vtxtable band 5 RACEBAND R FACTORY    0    0    0 5769 5806 5843    0    0
  64 vtxtable powerlevels 3
  65 vtxtable powervalues  14 20 26
  66 vtxtable powerlabels 25 100 400
  67 ```
  68
  69 ### Bands and channels
  70
  71 The example above contains 5 bands, **each with a name, a single-letter abbreviation, a factory flag and eight frequencies.**
  72
  73 The factory flag controls how Betaflight communicates with the vtx.
  74
  75 **When the flag is set to `FACTORY`, Betaflight sends the vtx a band and channel number.**
  76 The vtx will then use its built-in frequency table.
  77 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.
  78 As such, bands with the flag set to `FACTORY` should be set to match the built-in frequency table of the vtx.
  79
  80 **When the flag is set to `CUSTOM`, Betaflight sends the vtx the frequency it should use.**
  81 This mode utilizes the contents of the table and allows the user to create custom bands with whatever frequencies they like.
  82 **Videotransmitters without a built-in table, such as IRC Tramp or rtc6705 only support `CUSTOM`.**
  83
  84 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
  85 unwanted entries of the videotransmitter's built-in table can be set to 0, effectively disabling them.
  86 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
  87 German laws. Additionally, the Fatshark band was replaced with a new custom one.
  88
  89 As a starting point, the following table contains the commonly used frequencies:
  90 ```
  91 # This table should not be used as-is, but trimmed down according to local laws and regulations.
  92 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
  93 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
  94 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
  95 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
  96 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
  97 ```
  98
  99
 100 ### Power levels
 101
 102 In addition the the frequency, videotransmitters also need to know how much power they should use for transmission.
 103 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,
 104 while the value is sent to the vtx.
 105
 106 Power levels should be setup to match the hardware in use.
 107
 108 #### IRC Tramp devices should use:
 109 ```
 110 vtxtable powerlevels 5
 111 vtxtable powervalues 25 100 200 400 600
 112 vtxtable powerlabels 25 100 200 400 600
 113 ```
 114
 115 #### rtc6705 should use:
 116 ```
 117 vtxtable powerlevels 3
 118 vtxtable powervalues 0 1 2
 119 vtxtable powerlabels OFF MIN MAX
 120 ```
 121
 122 #### SmartAudio V1.0 devices should use:
 123 ```
 124 vtxtable powerlevels 4
 125 vtxtable powervalues 7 16 25 40
 126 vtxtable powerlabels 25 200 500 800
 127 ```
 128
 129 #### SmartAudio V2.0 devices should use:
 130 ```
 131 vtxtable powerlevels 4
 132 vtxtable powervalues 0 1 2 3
 133 vtxtable powerlabels 25 200 500 800
 134 ```
 135
 136 #### SmartAudio V2.1 devices vary depending on their model. Check the manufacturers website.
 137 For example the
 138
 139 [TBS Unify Pro32 Nano 5G8](https://www.team-blacksheep.com/products/prod:unifypro32_nano):
 140 ```
 141 vtxtable powerlevels 3
 142 vtxtable powervalues  14 20 26
 143 vtxtable powerlabels 25 100 400
 144 ```
 145
 146 [TBS Unify Pro 5G8 HV - Race 2 (MMCX)](https://www.team-blacksheep.com/products/prod:unify_pro_hv_race2_m):
 147 ```
 148 vtxtable powerlevels 3
 149 vtxtable powervalues  13 20 26
 150 vtxtable powerlabels 25 100 400
 151 ```
 152
 153 [TBS Unify EVO](https://www.team-blacksheep.com/products/prod:tbs_unify_evo):
 154 ```
 155 vtxtable powerlevels 4
 156 vtxtable powervalues  14 20 26 29
 157 vtxtable powerlabels 25 100 400 800
 158 ```
 159
 160 Power levels may be omitted. This is useful for compliance with local laws and regulations.
 161 Additionally, powerlabels (but not values!) can be set to anything three characters long.
 162 For example a TBS Unify EVO will also work the this config:
 163 ```
 164 vtxtable powerlevels 2
 165 vtxtable powervalues  20 26
 166 vtxtable powerlabels .1W .4W
 167 ```
 168
 169 ### Complete Examples
 170
 171 #### IRC Tramp device
 172
 173 ```
 174 # This example enables a lot of power levels and channels.
 175 # Almost nobody will be able to legally use this without modification.
 176 # Check your local laws and regulations before use!
 177 vtxtable bands 5
 178 vtxtable channels 8
 179 vtxtable band 1 BOSCAM_A A CUSTOM 5865 5845 5825 5805 5785 5765 5745 5725
 180 vtxtable band 2 BOSCAM_B B CUSTOM 5733 5752 5771 5790 5809 5828 5847 5866
 181 vtxtable band 3 BOSCAM_E E CUSTOM 5705 5685 5665 5645 5885 5905 5925 5945
 182 vtxtable band 4 FATSHARK F CUSTOM 5740 5760 5780 5800 5820 5840 5860 5880
 183 vtxtable band 5 RACEBAND R CUSTOM 5658 5695 5732 5769 5806 5843 5880 5917
 184 vtxtable powerlevels 5
 185 vtxtable powervalues 25 100 200 400 600
 186 vtxtable powerlabels 25 100 200 400 600
 187 ```
 188
 189 #### SmartAudio 1.0 device
 190
 191 ```
 192 # This example enables a lot of power levels and channels.
 193 # Almost nobody will be able to legally use this without modification.
 194 # Check your local laws and regulations before use!
 195 vtxtable bands 5
 196 vtxtable channels 8
 197 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 198 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 199 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 200 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 201 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 202 vtxtable powerlevels 4
 203 vtxtable powervalues 7 16 25 40
 204 vtxtable powerlabels 25 200 500 800
 205 ```
 206
 207 #### SmartAudio 2.0 device
 208
 209 ```
 210 # This example enables a lot of power levels and channels.
 211 # Almost nobody will be able to legally use this without modification.
 212 # Check your local laws and regulations before use!
 213 vtxtable bands 5
 214 vtxtable channels 8
 215 vtxtable band 1 BOSCAM_A A FACTORY 5865 5845 5825 5805 5785 5765 5745 5725
 216 vtxtable band 2 BOSCAM_B B FACTORY 5733 5752 5771 5790 5809 5828 5847 5866
 217 vtxtable band 3 BOSCAM_E E FACTORY 5705 5685 5665 5645 5885 5905 5925 5945
 218 vtxtable band 4 FATSHARK F FACTORY 5740 5760 5780 5800 5820 5840 5860 5880
 219 vtxtable band 5 RACEBAND R FACTORY 5658 5695 5732 5769 5806 5843 5880 5917
 220 vtxtable powerlevels 4
 221 vtxtable powervalues 0 1 2 3
 222 vtxtable powerlabels 25 200 500 800
 223 ```
 224
 225 #### rtc6705
 226
 227 ```
 228 # This example enables a lot of power levels and channels.
 229 # Almost nobody will be able to legally use this without modification.
 230 # Check your local laws and regulations before use!
 231 vtxtable bands 5
 232 vtxtable channels 8
 233 vtxtable band 1 BOSCAM_A A CUSTOM 5865 5845 5825 5805 5785 5765 5745 5725
 234 vtxtable band 2 BOSCAM_B B CUSTOM 5733 5752 5771 5790 5809 5828 5847 5866
 235 vtxtable band 3 BOSCAM_E E CUSTOM 5705 5685 5665 5645 5885 5905 5925 5945
 236 vtxtable band 4 FATSHARK F CUSTOM 5740 5760 5780 5800 5820 5840 5860 5880
 237 vtxtable band 5 RACEBAND R CUSTOM 5658 5695 5732 5769 5806 5843 5880 5917
 238 vtxtable powerlevels 3
 239 vtxtable powervalues 0 1 2
 240 vtxtable powerlabels OFF MIN MAX
 241 ```
 242
 243 ### Pitmode
 244 Pitmode is separate from vtxTable. No power level should be created for pitmode.
 245 Pitmode can be controlled in a variety of ways including OSD, AUX switches and lua scripts.
 246
 247 Some videotransmitters have restrictions on its usage. For example, SmartAudio V1.0 and V2.0 devices can only enter pitmode on power-up.
 248 Betaflight can make the these devices leave pitmode, but not enter it.