docs/Serial.md

   1 # Serial
   2
   3 Cleanflight has enhanced serial port flexibility but configuration is slightly more complex as a result.
   4
   5 Cleanflight has the concept of a function (MSP, GPS, Serial RX, etc) and a port (VCP, UARTx, SoftSerial x).
   6 Not all functions can be used on all ports due to hardware pin mapping, conflicting features, hardware, and software
   7 constraints.
   8
   9 ## Serial port types
  10
  11 * USB Virtual Com Port (VCP) - USB pins on a USB port connected directly to the processor without requiring
  12 a dedicated USB to UART adapter.  VCP does not 'use' a physical UART port.
  13 * UART - A pair of dedicated hardware transmit and receive pins with signal detection and generation done in hardware.
  14 * SoftSerial - A pair of hardware transmit and receive pins with signal detection and generation done in software.
  15
  16 UART is the most efficient in terms of CPU usage.
  17 SoftSerial is the least efficient and slowest, SoftSerial should only be used for low-bandwidth usages, such as telemetry transmission.
  18
  19 UART ports are sometimes exposed via on-board USB to UART converters, such as the CP2102 as found on the Naze and Flip32 boards.
  20 If the flight controller does not have an on-board USB to UART converter and doesn't support VCP then an external USB to UART board is required.
  21 These are sometimes referred to as FTDI boards.  FTDI is just a common manufacturer of a chip (the FT232RL) used on USB to UART boards.
  22
  23 When selecting a USB to UART converter choose one that has DTR exposed as well as a selector for 3.3v and 5v since they are more useful.
  24
  25 Examples:
  26
  27  * [FT232RL FTDI USB To TTL Serial Converter Adapter](http://www.banggood.com/FT232RL-FTDI-USB-To-TTL-Serial-Converter-Adapter-Module-For-Arduino-p-917226.html)
  28  * [USB To TTL / COM Converter Module buildin-in CP2102](http://www.banggood.com/Wholesale-USB-To-TTL-Or-COM-Converter-Module-Buildin-in-CP2102-New-p-27989.html)
  29
  30 Both SoftSerial and UART ports can be connected to your computer via USB to UART converter boards.
  31
  32 ## Serial Configuration
  33
  34 Serial port configuration is best done via the configurator.
  35
  36 Configure serial ports first, then enable/disable features that use the ports.  To configure SoftSerial ports the SOFTSERIAL feature must be also be enabled.
  37
  38 ### Constraints
  39
  40 If the configuration is invalid the serial port configuration will reset to its defaults and features may be disabled.
  41
  42 * There must always be a port available to use for MSP/CLI.
  43 * There is a maximum of 2 MSP ports.
  44 * To use a port for a function, the function's corresponding feature must be also be enabled.
  45 e.g. after configuring a port for GPS enable the GPS feature.
  46 * If SoftSerial is used, then all SoftSerial ports must use the same baudrate.
  47 * Softserial is limited to 19200 baud.
  48 * All telemetry systems except MSP will ignore any attempts to override the baudrate.
  49 * MSP/CLI can be shared with EITHER Blackbox OR telemetry.  In shared mode blackbox or telemetry will be output only when armed.
  50 * Smartport telemetry cannot be shared with MSP.
  51 * No other serial port sharing combinations are valid.
  52 * You can use as many different telemetry systems as you like at the same time.
  53 * You can only use each telemetry system once.  e.g.  FrSky telemetry cannot be used on two port, but MSP Telemetry + FrSky on different ports is fine.
  54
  55 ### Configuration via CLI
  56
  57 You can use the CLI for configuration but the commands are reserved for developers and advanced users.
  58
  59 The `serial` CLI command takes 6 arguments.
  60
  61 1. Identifier (see serialPortIdentifier_e in the source)
  62 1. Function bitmask (see serialPortFunction_e in the source)
  63 1. MSP baud rate
  64 1. GPS baud rate
  65 1. Telemetry baud rate (auto baud allowed)
  66 1. Blackbox baud rate
  67
  68
  69 ### Baud Rates
  70
  71 The allowable baud rates are as follows:
  72
  73 | Identifier | Baud rate |
  74 | ---------- | --------- |
  75 | 0          | Auto      |
  76 | 1          | 9600      |
  77 | 2          | 19200     |
  78 | 3          | 38400     |
  79 | 4          | 57600     |
  80 | 5          | 115200    |
  81 | 6          | 230400    |
  82 | 7          | 250000    |
  83
  84
  85
  86 ### Passthrough
  87
  88 Cleanflight can enter a special passthrough mode whereby it passes serial data through to a device connected to a UART/SoftSerial port. This is useful to change the configuration of a Cleanflight peripheral such as an OSD, bluetooth dongle, serial RX etc.
  89
  90 To initiate passthrough mode, use the CLI command `serialpassthrough` This command takes four arguments.
  91
  92     serialpassthrough <id> [baud] [mode] [DTR PINIO]
  93
  94 ID is the internal identifier of the serial port from Cleanflight source code (see serialPortIdentifier_e in the source). For instance UART1-UART4 are 0-3 and SoftSerial1/SoftSerial2 are 30/31 respectively. Baud is the desired baud rate, and mode is a combination of the keywords rx and tx (rxtx is full duplex). The baud and mode parameters can be used to override the configured values for the specified port. `DTR PINIO` identifies the PINIO resource which is optionally connected to a DTR line of the attached device.
  95
  96 For example. If you have your MWOSD connected to UART 2, you could enable communicaton to this device using the following command. This command does not specify the baud rate or mode, using the one configured for the port (see above).
  97
  98     serialpassthrough 1
  99
 100 If a baud rate is not specified, or is set to 0, then `serialpassthrough` supports changing of the baud rate over USB. This allows tools such as the MWOSD GUI to dynamically set the baud rate to, for example 57600 for reflashing the MWOSD firmware and then 115200 for adjusting settings without having to powercycle your flight control board between the two.
 101
 102 _To use a tool such as the MWOSD GUI, it is necessary to disconnect or exit Cleanflight configurator._
 103
 104 **To exit serial passthrough mode, power cycle your flight control board.**
 105
 106 In order to reflash an Arduino based device such as a MWOSD via `serialpassthrough` if is necessary to connect the DTR line in addition to the RX and TX serial lines. The DTR is used as a reset line to invoke the bootloader. The DTR line may be connected to any GPIO pin on the flight control board. This pin must then be associated with a PINIO resource, the instance of which is then passed to the serialpassthrough command. The DTR line associated with any given UART may be set using the CLI command `resource` specifying it as a PINIO resource.
 107
 108 For example, the following configuration for an OpenPilot Revolution shows the UART6 serial port to be configured with TX on pin C06, RX on pin C07 and a DTR connection using PINIO on pin C08.
 109
 110 ```
 111 resource SERIAL_TX 1 A09
 112 resource SERIAL_TX 3 B10
 113 resource SERIAL_TX 4 A00
 114 resource SERIAL_TX 6 C06
 115 resource SERIAL_RX 1 A10
 116 resource SERIAL_RX 3 B11
 117 resource SERIAL_RX 6 C07
 118
 119 resource PINIO 1 C08
 120 ```
 121
 122 To assign the DTR line to another pin use the following command.
 123
 124 ```
 125 resource PINIO 1 c05
 126 ```
 127
 128 To disassociate DTR from a pin use the following command.
 129
 130 ```
 131 resource PINIO 1 none
 132 ```
 133
 134 Having configured a PINIO resource assocaited with a DTR line as per the above example, connection to an MWOSD attached to an Openpilot Revolution could be achieved using the following command.
 135
 136 ```serialpassthrough 5 0 rxtx 1```
 137
 138 This will connect using UART 6, with the baud rate set over USB, full duplex, and with DTR driven on PINIO resource 1.
 139
 140 A (desirable) side effect of configuring the DTR line to be associated with a PINIO resource, is that when the FC is reset, the attached Arduino device will also be reset.
 141
 142 Note that if DTR is left configured on a port being used with a standard build of MWOSD firmware, the display will break-up when the flight controller is reset. This is because, by default, the MWOSD does not correctly handle resets from DTR. There are two solutions to this:
 143
 144 1. Assign the DTR pin using the resource command above prior to reflashing MWOSD, and then dissasociate DTR from the pin.
 145 2. Rebuild MWOSD with MAX_SOFTRESET defined. The MWOSD will then be reset correctly every time the flight controller is reset.
 146
 147
 148
 149