doc/help/Drivers-UART.md
The UART driver handles plain serial communication: USB-to-serial adapters, RS-232 ports, RS-485 buses, and Bluetooth Classic devices that the OS exposes as virtual COM ports. It was the first driver Serial Studio shipped and is still the most widely used.
If you have never used a serial port before, read the next section first. If you only need the configuration reference, skip to How Serial Studio uses it.
UART stands for Universal Asynchronous Receiver-Transmitter. It is the small piece of hardware inside a microcontroller, a USB-to-serial chip, or a PC's chipset that converts parallel bytes into a sequential stream of bits and back. There is no clock line between the two ends; both sides agree in advance on how fast the bits will arrive, and the receiver synchronises itself to the start of each byte.
A UART is a peripheral, not a protocol. The protocol it implements is usually called asynchronous serial or just serial. When a datasheet says "speaks serial at 115200 8N1", it is describing UART parameters.
Every byte sent over a UART line is wrapped in a small fixed-shape frame: an idle high level, a single low start bit, the data bits (typically 8, least-significant first), an optional parity bit, and one or more high stop bits before the line returns to idle.
The trace above shows the byte 0x4B (0100 1011) sent as 8N1: 8 data bits, no parity, 1 stop bit. Bit times are equal; the receiver clocks at a multiple of the baud rate and samples each bit near the middle.
1 bits either always even or always odd. It catches single-bit errors.The most common configuration is 8N1: 8 data bits, No parity, 1 stop bit. With the start and stop bits, that is ten line bits per byte, a raw efficiency of 80%.
Baud rate is the number of symbols per second on the line. For UART that is identical to bits per second: at 9600 baud, each bit lasts 1 / 9600 ≈ 104.2 µs.
Common baud rates are 9600, 19200, 38400, 57600, 115200, 230400, 460800, and 921600. Modern USB-serial chips and microcontrollers usually support 1 Mbps and higher.
Both ends must agree. UARTs tolerate small clock mismatches between transmitter and receiver (roughly ±2% over a single frame), but if the configured baud rates differ (for example 115200 vs 9600) the result is garbage or no data at all.
A parity bit makes the total number of 1s in the frame either always even or always odd. It detects single-bit errors but cannot detect two-bit errors and cannot correct anything. Most modern designs leave parity off because USB and short cables rarely flip bits, and any error detection that matters is handled at a higher layer (a CRC in the application protocol).
Parity options exposed by Serial Studio:
1s is always even.1s is always odd.0. Rare.1. Used for inter-byte signalling on a few legacy buses.The stop bit holds the line high for one or two bit-times after the last data bit. Two stop bits were used at very low baud rates (300 baud and below) to give a slow receiver more time to process each byte. At 9600 baud and above, choose 1 stop bit unless the device explicitly requires something else.
Flow control lets the receiver tell the sender to pause when its buffer is full. UART supports two kinds:
0x11 = XON, 0x13 = XOFF) to signal go/stop. This reserves those byte values, so it cannot be used with arbitrary binary data.For typical Arduino, ESP32, and STM32 telemetry, choose None. Hardware flow control matters mainly with industrial equipment or sustained high-rate streams where the host cannot keep up at the application layer.
UART is the protocol; the physical layer is separate. Serial Studio works with any of them as long as the OS exposes a serial port, but the differences matter when you choose hardware:
A USB-to-serial adapter converts USB to TTL or RS-232 levels. To Serial Studio, all of them appear as a COM port on Windows or as /dev/ttyUSB0 / /dev/tty.usbserial-XXXX on Linux and macOS.
The UART driver wraps Qt's QSerialPort. Settings exposed in the Setup Panel map one-to-one onto UART parameters:
| Setting | Controls | Default |
|---|---|---|
| COM Port | Which OS-level serial device to open (COM3, /dev/ttyACM0, etc.) | none selected |
| Baud Rate | Bits per second; presets from 110 to 921600, and the field accepts any positive rate typed in | 9600 |
| Data Bits | 5 / 6 / 7 / 8 | 8 |
| Parity | None / Even / Odd / Space / Mark | None |
| Stop Bits | 1 / 1.5 / 2 | 1 |
| Flow Control | None / RTS/CTS / XON/XOFF | None |
| Send DTR Signal | Asserts the DTR line on connect (some boards reset on DTR toggle, e.g. Arduino) | on |
| Auto Reconnect | Rescans ports once per second and reconnects when the last-used device re-enumerates | off |
On Linux and macOS the COM Port field is editable: type a device path missing from the list (for example /dev/ttyAMA0) and press Enter to register it. On macOS each adapter is listed once, as its cu.* device; the tty.* duplicates are hidden.
QSerialPort uses Qt's event loop for non-blocking reads, so the UART driver runs entirely on the main thread; bytes arrive there and feed the FrameReader directly. See Threading and Timing Guarantees for the rationale.
The same settings are scriptable through the io.uart.* commands of the JSON-RPC API: setDevice (by path), setPortIndex, setBaudRate, setParity, setDataBits, setStopBits, setFlowControl, setDtrEnabled, and setAutoReconnect, plus the read-only listPorts, listBaudRates, and getConfig. setBaudRate takes the rate itself (baudRate, bits per second); the other line settings take a zero-based index into the option list in the same order as the Setup Panel (parityIndex 2 = Odd, stopBitsIndex 1 = 1.5, flowControlIndex 1 = RTS/CTS). When the in-app AI issues these commands, they sit behind the Allow device control toggle.
For step-by-step setup, see the Protocol Setup Guides, Serial/UART section.
udev may have renamed it; /dev/ttyUSB0 can become /dev/ttyUSB1 after a hot-unplug. A udev rule pinning the device by VID/PID to a stable symlink fixes it permanently.