Connect to a UART console

Serial UART consoles permit communication between a computer and your board.

Hardware

On some boards (e.g. the HiFive Unmatched), the UART console is exposed via a USB socket, typically a micro-USB socket, and in these cases it is common that multiple UARTs are exposed by the one socket. However, most boards expose their UART console via simple header pins using RS-232 signaling.

UARTs consist of a minimum of three pins:

• ground (often abbreviated GND),

• receive (RX), and

• transmit (TX)

On some boards, the UART has its own dedicated header. On others, the UART is part of a larger GPIO header.

To connect your computer to the UART pins on your board, a USB adapter is commonly required. Some minor care in selecting adapters is needed: you want an adapter that signals at TTL levels (3.3 volts) rather than the traditional RS-232 levels (between 3 and 15 volts).

Adapters that use traditional RS-232 levels, which would cause permanent damage to most single board computers, typically have a DE-9 connector. Adapters that signal at TTL levels, by contrast, have three or four DuPont connector tails:

The receive and transmit lines cross between the computer and the board. In other words, the computer’s RX pin connects to the board’s TX pin, and the computer’s TX pin connects to the board’s RX pin. The GND pins are simply connected together.

If your adapter includes a red 5V output line, it should remain disconnected from the board.

Once connected to your computer, your USB UART adapter will appear as a tty device, commonly named /dev/ttyUSB0. However, depending on the hardware used, other device names are possible including /dev/ttyACM0 and /dev/ttyAMA0. If more than one serial adapter is present, the number at the end may be different too. If in doubt, check the output of dmesg(1). When attached you should see something like the following appear:

ubuntu@ubuntu:~$ sudo dmesg

...[605927.453848] usb 2-2: new full-speed USB device number 2 using xhci-hcd[605927.599633] usb 2-2: New USB device found, idVendor=067b, idProduct=2303, bcdDevice= 3.00[605927.599645] usb 2-2: New USB device strings: Mfr=1, Product=2, SerialNumber=0[605927.599649] usb 2-2: Product: USB-Serial Controller[605927.599652] usb 2-2: Manufacturer: Prolific Technology Inc.[605927.653506] usbcore: registered new interface driver usbserial_generic[605927.653537] usbserial: USB Serial support registered for generic[605927.656003] usbcore: registered new interface driver pl2303[605927.656045] usbserial: USB Serial support registered for pl2303[605927.656109] pl2303 2-2:1.0: pl2303 converter detected[605927.682845] usb 2-2: pl2303 converter now attached to ttyUSB0

Note that the last line displays the device name of the newly registered adapter.

Software

The Ubuntu archive contains several serial clients suitable for communicating with a UART console. The following is an example of installing the popular picocom(1) client, and accessing the UART device connected to /dev/ttyUSB0 at a baud rate of 115200bps:

sudo apt install picocom
picocom -b 115200 /dev/ttyUSB0

You should replace the baud rate 115200 with the one specified by your board. However, 115200bps is an extremely common default, and can generally be assumed if the specific rate is unknown. Replace the device /dev/ttyUSB0 with the one for your adapter (determined above).

To exit picocom, type Ctrl+A Ctrl+X.

Another common choice is GNU screen(1). Once again, substitute the device and baud-rate accordingly:

sudo apt install screen
screen /dev/ttyUSB0 115200

To exit screen, type Ctrl+A K then answer y to the prompt.

Troubleshooting

Always troubleshoot your hardware first. Ensure your connections are good, that the TX and RX pins are connected the right way round, and that the GND pin is connected properly. If your UART pins are part of a larger GPIO header, double-check you are looking at the correct set of pins for your board.

The following sections deal with specific problems common to UART usage.

Permission Denied

Typically, USB UART adapters will be accessible to any regular logged in user. However, some serial interfaces (particularly built-in ones) do not match the “uaccess” mechanism, and are only accessible to the root user and members of the dialout group. If you are seeing a permission denied error, check your access to the serial device:

test -r /dev/ttyUSB0 || echo "No read access"
test -w /dev/ttyUSB0 || echo "No write access"

If needed, the following command will add the current user to the dialout group, but you will need to logout and login again for this to take effect:

sudo adduser $USER dialout

Flow Control

Some UARTs have additional pins for flow control (sometimes labeled RTS and CTS). However, the vast majority of USB UART adapters only have the basic three pins. In such cases, the flow-control pins can simply be ignored.

The lack of hardware flow-control does mean that pasting large chunks of text can fill the UART’s buffer and result in lost characters. However, because lack of flow control is so common these days, workarounds are present in many serial clients (typically some form of enforced delay between transmitted key-presses).

screen

Use Ctrl+A : to enter command mode, then enter slowpaste 1 to set a 1ms delay on character transmission.

minicom

Under terminal settings (accessed with Ctrl+A T), change the “Character tx delay” to 1 for a 1ms delay between character transmissions.

picocom

Unfortunately this functionality is not supported yet.

Full Screen Applications

Some console applications take up the full screen, e.g. top(1) or vim(1). However, a serial terminal has no direct means of knowing how many columns or rows are available to the client. Typically, the terminal will assume it is only 80 columns by 24 rows large. If this does not match how many columns and rows are actually available, the application will either wind up compressed to the top left corner of the client, or will wrap its lines resulting in a “corrupted” display.

To work around this, open another terminal of the same size as the one running your serial client (if your terminal supports tabs, you may wish to open another tab beside the client one; this ensures both terminals are the same size). In the new terminal, run the following command:

echo stty cols $COLUMNS rows $LINES

For example:

ubuntu@ubuntu:~$ echo stty cols $COLUMNS rows $LINES

stty cols 105 rows 51

Paste the output of this command into your serial client, and set the TERM environment variable to screen-256color to indicate that the terminal can use modern color codes too:

stty cols 105 rows 51
export TERM=screen-256color

Once this is done, provided you do not resize the terminal containing your serial client, you should find you are able to run full screen applications like top and vim as normal (albeit full screen updates will be rather slow at 115200bps).