docs/Telemetry.md

   1 # Telemetry
   2
   3 Telemetry allows you to know what is happening on your aircraft while you are flying it.  Among other things you can receive battery voltages and GPS positions on your transmitter.
   4
   5 Telemetry can be either always on, or enabled when armed.  If a serial port for telemetry is shared with other functionality then telemetry will only be enabled when armed on that port.
   6
   7 Telemetry is enabled using the 'TELEMETRY` feature.
   8
   9 ```
  10 feature TELEMETRY
  11 ```
  12
  13 Multiple telemetry providers are currently supported, FrSky, Graupner
  14 HoTT V4, SmartPort (S.Port) and LightTelemetry (LTM)
  15
  16 All telemetry systems use serial ports, configure serial ports to use the telemetry system required.
  17
  18 ## FrSky telemetry
  19
  20 FrSky telemetry is transmit only and just requires a single connection from the TX pin of a serial port to the RX pin on an FrSky telemetry receiver.
  21
  22 FrSky telemetry signals are inverted.  To connect a cleanflight capable board to an FrSKy receiver you have some options.
  23
  24 1. A hardware inverter - Built in to some flight controllers.
  25 2. Use software serial and enable frsky_inversion.
  26 3. Use a flight controller that has software configurable hardware inversion (e.g. STM32F30x).
  27
  28 For 1, just connect your inverter to a usart or software serial port.
  29
  30 For 2 and 3 use the CLI command as follows:
  31
  32 ```
  33 set telemetry_inversion = ON
  34 ```
  35
  36
  37 ### Available sensors
  38
  39 The following sensors are transmitted :
  40
  41 Vspd : vertical speed, unit is cm/s.
  42
  43 Hdg : heading, North is 0°, South is 180°.
  44
  45 AccX,Y,Z : accelerometers values.
  46
  47 Tmp1 : baro temp if available, gyro otherwise.
  48
  49 RPM : if armed : throttle value, battery capacity otherwise. (Blade number needs to be set to 12 in Taranis).
  50
  51 Cels : average cell value, vbat divided by cell number.
  52
  53 VFAS : actual vbat value (see VFAS precision section bellow).
  54
  55 Curr : actual current comsuption, in amp.
  56
  57 Fuel : if capacity set :remaining battery percentage, mah drawn otherwise.
  58
  59 GPS : GPS coordinates.
  60
  61 Alt : barometer based altitude, init level is zero.
  62
  63 Date : time since powered.
  64
  65 GSpd : current speed, calculated by GPS.
  66
  67 GAlt : GPS altitude, sea level is zero.
  68
  69 Tmp2 : number of sats. Every second, a number > 100 is sent to represent GPS signal quality.
  70
  71 ### Precision setting for VFAS
  72
  73 Cleanflight can send VFAS (FrSky Ampere Sensor Voltage) in two ways:
  74
  75 ```
  76 set frsky_vfas_precision  = 0
  77 ```
  78 This is default setting which supports VFAS resolution of 0.2 volts and is supported on all FrSky hardware.
  79
  80 ```
  81 set frsky_vfas_precision  = 1
  82 ```
  83 This is new setting which supports VFAS resolution of 0.1 volts and is only supported by OpenTX radios (this method uses custom ID 0x39).
  84
  85
  86
  87 ## HoTT telemetry
  88
  89 Only Electric Air Modules and GPS Modules are emulated.
  90
  91 Use the latest Graupner firmware for your transmitter and receiver.
  92
  93 Older HoTT transmitters required the EAM and GPS modules to be enabled in the telemetry menu of the transmitter. (e.g. on MX-20)
  94
  95 Serial ports use two wires but HoTT uses a single wire so some electronics are required so that the signals don't get mixed up.  The TX and RX pins of
  96 a serial port should be connected using a diode and a single wire to the `T` port on a HoTT receiver.
  97
  98 Connect as follows:
  99
 100 * HoTT TX/RX `T` -> Serial RX (connect directly)
 101 * HoTT TX/RX `T` -> Diode `-(  |)-` > Serial TX (connect via diode)
 102
 103 The diode should be arranged to allow the data signals to flow the right way
 104
 105 ```
 106 -(  |)- == Diode, | indicates cathode marker.
 107 ```
 108
 109 1N4148 diodes have been tested and work with the GR-24.
 110
 111 As noticed by Skrebber the GR-12 (and probably GR-16/24, too) are based on a PIC 24FJ64GA-002, which has 5V tolerant digital pins.
 112
 113 Note: The SoftSerial ports may not be 5V tolerant on your board.  Verify if you require a 5v/3.3v level shifters.
 114
 115 ## LightTelemetry (LTM)
 116
 117 LTM is a lightweight streaming telemetry protocol supported by a
 118 number of OSDs, ground stations and antenna trackers.
 119
 120 The Cleanflight implementation of LTM implements the following frames:
 121
 122 * G-FRAME: GPS information (lat, long, ground speed, altitude, sat
 123   info)
 124 * A-FRAME: Attitude (pitch, roll, heading)
 125 * S-FRAME: Status (voltage, current+, RSSI, airspeed+, status). Item
 126   suffixed '+' not implemented in Cleanflight.
 127 * O-FRAME: Origin (home position, lat, long, altitude, fix)
 128
 129 In addition, in the inav (navigation-rewrite) fork:
 130 * N-FRAME: Navigation information (GPS mode, Nav mode, Nav action,
 131   Waypoint number, Nav Error, Nav Flags).
 132
 133 LTM is transmit only, and can work at any supported baud rate. It is
 134 designed to operate over 2400 baud (9600 in Cleanflight) and does not
 135 benefit from higher rates. It is thus usable on soft serial.
 136
 137 More information about the fields, encoding and enumerations may be
 138 found at
 139 https://github.com/stronnag/mwptools/blob/master/docs/ltm-definition.txt
 140
 141 ## SmartPort (S.Port)
 142
 143 Smartport is a telemetry system used by newer FrSky transmitters and receivers such as the Taranis/XJR and X8R, X6R and X4R(SB).
 144
 145 More information about the implementation can be found here: https://github.com/frank26080115/cleanflight/wiki/Using-Smart-Port
 146
 147 ### Available sensors
 148
 149 The following sensors are transmitted :
 150
 151 Alt : barometer based altitude, init level is zero.
 152
 153 Vspd : vertical speed, unit is cm/s.
 154
 155 Hdg : heading, North is 0°, South is 180°.
 156
 157 AccX,Y,Z : accelerometers values.
 158
 159 Tmp1 : actual flight mode, sent as 4 digits. Number is sent as (1)1234. Please ignore the leading 1, it is just there to ensure the number as always 5 digits (the 1 + 4 digits of actual data) the numbers are aditives (for example, if first digit after the leading 1 is 6, it means GPS Home and Headfree are both active) :
 160
 161 1. 1 is GPS Hold, 2 is GPS Home, 4 is Headfree
 162 2. 1 is mag enabled, 2 is baro enabled, 4 is sonar enabled
 163 3. 1 is angle, 2 is horizon, 4 is passthrough
 164 4. 1 is ok to arm, 2 is arming is prevented,  4 is armed
 165
 166 Tmp2 : GPS lock status, Number is sent as 1234, the numbers are aditives :
 167
 168 1. 1 is GPS Fix, 2 is GPS Home fix
 169 2. not used
 170 3. not used
 171 4. number of sats
 172
 173 VFAS : actual vbat value.
 174
 175 GAlt : GPS altitude, sea level is zero.
 176
 177 GSpd : current speed, calculated by GPS.
 178
 179 GPS : GPS coordinates.
 180
 181 ### Integrate Cleanflight telemetry with FrSky Smartport sensors
 182
 183 While Cleanflight telemetry brings a lot of valuable data to the radio, there are additional sensors, like Lipo cells sensor FLVSS, that can be a great addition for many aircrafts. Smartport sensors are designed to be daisy chained, and CF telemetry is no exception to that. To add an external sensor, just connect the "S" port of the FC and sensor(s) together, and ensure the sensor(s) are getting connected to GND and VCC either from the controler or the receiver
 184
 185 ![Smartport diagram](assets/images/integrate_smartport.png)
 186
 187 ### SmartPort on F3 targets with hardware UART
 188
 189 Smartport devices can be connected directly to STM32F3 boards such as the SPRacingF3 and Sparky, with a single straight through cable without the need for any hardware modifications on the FC or the receiver. Connect the TX PIN of the UART to the Smartport signal pin.
 190
 191 For Smartport on F3 based boards, enable the telemetry inversion setting.
 192
 193 ```
 194 set telemetry_inversion = ON
 195 ```
 196
 197 ### SmartPort on F1 and F3 targets with SoftSerial
 198
 199 Since F1 targets like Naze32 or Flip32 are not equipped with hardware inverters, SoftSerial might be simpler to use.
 200
 201 1. Enable SoftSerial ```feature SOFTSERIAL```
 202 2. In Configurator assign _Telemetry_ > _Smartport_ > _Auto_ to SoftSerial port of your choice
 203 3. Enable Telemetry ```feature TELEMETRY```
 204 4. Confirm telemetry invesion ```set telemetry_inversion = ON```
 205 5. You have to bridge TX and RX lines of SoftSerial and connect them together to S.Port signal line in receiver
 206
 207 Notes:
 208
 209 * This has been tested with Flip32 and SPracingF3 boards and FrSky X8R and X4R receivers
 210 * To discover all sensors board has to be armed, and when GPS is connected, it needs to have a proper 3D fix. When not armed, values like ***Vfas*** or GPS coordinates may not sent.