Is this page helpful?

UART (Linux)

Introduction

Serial port (UART) access from userspace on Linux is provided through TTY devices under /dev. Since BSP 5, we provide standard Toradex names by family, such as /dev/apalis-uart1, /dev/colibri-uarta and verdin-uart1, to enhance pin compatibility on a software level.

This article is very useful if you plan to use UART for communication with other devices - often using RS-232 or RS-485 - but if you just want to access the Linux terminal on the default debug UART, make sure to follow the first lessons from our Quickstart Guide or alternatively read the article Configuring Serial Port Debug Console (Linux/U-Boot).

Toradex Standard Interfaces

Toradex SoMs are pin-compatible within a family, as long as you use the default pin muxing from the Toradex Embedded Linux BSP. In this section, you will learn what UART interfaces are available on all Toradex SoMs within a family.

Keep in mind that each SoM may have additional UART interfaces that you can use at the tradeoff of breaking pin compatibility. You will need to check how many UARTs are available on your specific SoM and modify the default pin muxing. Reading the SoM datasheet and the article Device Tree Customization are good starting points.

Apalis Family

The Apalis family has 4 pin-compatible UART interfaces. The BSP device name matches the signal name used in the SoM datasheet.

Toradex Name	Device Symlink	Note
UART1	/dev/apalis-uart1	debug (console) for the main OS (Cortex-A), with RTS/CTS, DTR/DSR and RI
UART2	/dev/apalis-uart2	general-purpose, with RTS/CTS
UART3	/dev/apalis-uart3	general-purpose
UART4	/dev/apalis-uart4	general-purpose

You can list the devices as follows:

# ls -l /dev/apalis-uart*

It will display the available Apalis pin-compatible UARTs and display the corresponding names used by the BSP. Those corresponding names are important because the Linux kernel logs will print the real device names (e.g. /dev/ttymxc0), not the Apalis symlinks (e.g. /dev/apalis-uart2).

Colibri Family

The Colibri family has 3 pin-compatible UART interfaces. The BSP device name matches the signal name used in the SoM datasheet.

Toradex Name	Legacy Toradex Name	Device Symlink	Note
UART_A	FF_UART	/dev/colibri-uarta	debug (console) for the main OS (Cortex-A), with RTS/CTS, DTR/DSR and RI
UART_B	BT_UART	/dev/colibri-uartb	general-purpose, with RTS/CTS
UART_C	STD_UART	/dev/colibri-uartc	general-purpose

You can list the devices as follows:

# ls -l /dev/colibri-uart*

It will display the available Colibri pin-compatible UARTs and display the corresponding names used by the BSP. Those corresponding names are important because the Linux kernel logs will print the real device names (e.g. /dev/ttymxc0), not the Colibri symlinks (e.g. /dev/colibri-uartc).

Verdin Family

The Verdin family has 4 pin-compatible UART interfaces. Three of them have RX and TX signals in Always Compatible pins, and the fourth has RX and TX signals on Reserved pins. The BSP device name matches the signal name used in the SoM datasheet.

Toradex Name	Device	Always Compatible Pins	Reserved Pins	Note
UART_1	/dev/verdin-uart1	RX and TX	RTS and CTS	general-purpose
UART_2	/dev/verdin-uart2	RX and TX	RTS and CTS	general-purpose
UART_3	/dev/verdin-uart3	RX and TX	-	debug (console) for the main OS (Cortex-A)
UART_4	/dev/verdin-uart4	-	RX and TX	debug for the real-time OS (Cortex-M) or general-purpose

You can list the devices as follows:

# ls -l /dev/verdin-uart*

It will display the available Verdin pin-compatible UARTs and display the corresponding names used by the BSP. Those corresponding names are important because the Linux kernel logs will print the real device names (e.g. /dev/ttymxc0), not the Verdin symlinks (e.g. /dev/verdin-uart2).

Configuration

This section has information about how to configure and use the serial, including a sub-section for RS-485.

Command-line

From userspace, one can use the command line utility stty to configure the serial speed. Then the port can be treated as as a regular file:

# stty -F /dev/verdin-uart1 115200
# echo Test > /dev/verdin-uart1

C

Using C, use the struct termios to set the initial baud rate:

#include <termios.h>
...
struct termios tty;
int fd;
int flags = O_RDWR | O_NOCTTY | O_NONBLOCK;

fd = open("/dev/verdin-uart1", flags);

tcgetattr(fd, &tty);

tty.c_cflag = (tty.c_cflag & ~CSIZE) | CS8;
tty.c_cflag |= B115200;

if (tcsetattr (fd, TCSANOW, &tty) != 0)
{
    fprintf (stderr, "error %d from tcsetattr", errno);
    return -1;
}

Standard Baud Rates

A fixed list of baud rates are pre-defined:

Baud rate	Symbol
921600	B921600
460800	B460800
230400	B230400
115200	B115200
57600	B57600
38400	B38400
19200	B19200
9600	B9600
4800	B4800
2400	B2400
1200	B1200

RS-485

The Toradex Carrier Board implements RS-485 using a single transceiver in a half-duplex communication mode, which means that one medium is shared for transmitting and receiving data. The transceiver switches to transmit mode when the RTS signal is asserted (low active).

RS-485 defines the electrical characteristics of drivers and receivers for serial communication and supports bus topology. How RS-485 is exactly implemented depends on application and requirements. The RS-485 support has been tested using the configuration as found on Toradex Carrier Boards.

Our modules provide the following support:

i.MX 6, i.MX 6ULL and i.MX 7 Modules

The driver uses the RTS output to control a RS-485 transceiver (see below).

Tegra Modules

Due to hardware limitations, there is no RS-485 transceiver control support.

i.MX 8, i.MX 8X and i.MX 8M Mini Modules

The i.MX 8, i.MX 8X and i.MX 8M Mini UART block has built-in support for RS-485 auto RTS for controlling the direction of the RS-485 transceiver (see below).

Enabling RS-485 support

Enable the RS-485 feature by either using ioctl from userspace or using device tree properties.

Userspace

Enable the RS-485 using ioctl TIOCSRS485 from userspace is described in RS-485 Kernel Documentation.

On Toradex carrier boards the following flags should be used:

...
    /* Enable RS485 mode: */
    rs485conf.flags |= SER_RS485_ENABLED;

    /* or, set logical level for RTS pin equal to 0 when sending: */
    rs485conf.flags &= ~(SER_RS485_RTS_ON_SEND);

    /* Set logical level for RTS pin equal to 1 after sending: */
    rs485conf.flags |= SER_RS485_RTS_AFTER_SEND;

    /* Enable receiver during sending, required for i.MX devices */
    rs485conf.flags |= SER_RS485_RX_DURING_TX;
...

Note that i.MX6 based modules do not evaluate the delay and logic level parameters.

Device Tree

Enable it in the device tree by setting linux,rs485-enabled-at-boot-time, rs485-rts-active-low and rs485-rx-during-tx property.

&uart2 {
    status = "okay";
    linux,rs485-enabled-at-boot-time;
    rs485-rts-active-low;
    rs485-rx-during-tx;
};

info

Some kernel version do not support the device tree properties rs485-rts-active-low and rs485-rx-during-tx yet. However, having them specified is not harmful to older kernels. Due to different defaults, newer kernels require those properties for RS-485 operation on Toradex carrier boards.

info

On i.MX8 CPUs rs485-rts-delay is not working due to lack of hardware support.

Carrier Boards

This section provides details about UARTs on Toradex carrier boards. Remember that our carrier boards are open source and you can check their implementation anytime, just browse on the corresponding product page.

Apalis Evaluation Board

The Apalis Evaluation carrier board does have three regular 9-pin male D-Sub serial connectors for UART1 (RS-232 on bottom X28), UART2 (RS-232 on top X28) and optionally UART2 (RS-422/485 on X55). The UART3 is routed to the IrDA transceiver X30 by default. To route it to the UART1 port instead proceed as follows:

• Remove jumpers X3 rows 38 and 39 and X6 rows 33 to 40 to break the default UART1 to lower 9-pin male D-Sub and UART3 to IrDA connection.
• Connect X2-38 to X7-39 and X2-39 to X7-36 to re-route the UART3_TXD and UART3_RXD MXM3 pins to the UART1 lower 9-pin male D-Sub serial connector.

The UART4 is routed to the mezzanine connector X38 by default. To route it to the UART2 port instead proceed as follows:

• Remove jumpers X3 rows 36 and 37 and X6 rows 29 to 32 to break the default UART2 to upper 9-pin male D-Sub and UART4 to mezzanine connection.
• Connect X2-36 to X7-32 and X2-37 to X7-29 to re-route the UART4_TXD and UART4_RXD MXM3 pins to the UART2 upper 9-pin male D-Sub serial connector.

UART1 can optionally be connected to an integrated FTDI USB-to-serial chip to conveniently access the debug console. Make sure J10 and J12 Pin 2 and 3 are each jumpered (USB) to route TXD/RXD to the FTDI chip. Then, a simple USB A-B cable is sufficient to get a serial console directly from a computer (through /dev/ttyUSB0 on Linux hosts).

Colibri Evaluation Board

The Colibri Evaluation carrier board does have two regular 9-pin male D-Sub serial connectors for UART_A (lower) and UART_B (upper). The UART_C is routed to the IR by default. To route it to the UART_A port instead proceed as follows:

• Remove jumpers X11 rows 2, 3, 10 and 11 to break the default UART_A to lower 9-pin male D-Sub and UART_C to IR connection.
• Connect X10-2 to X12-10 and X10-3 to X12-11 to re-route the UART_C_RXD and UART_C_TXD SODIMM pins to the UART_A lower 9-pin male D-Sub serial connector.

UART_A can optionally be connected to an integrated FTDI USB-to-serial chip to conveniently access the debug console. Make sure J17 and J19 Pin 2 and 3 are each jumpered (USB) to route TXD/RXD to the FTDI chip. Then, a simple USB A-B cable is sufficient to get a serial console directly from a computer (through /dev/ttyUSB0 on Linux hosts).

Dahlia Carrier Board

• UART_3 and UART_4 are available on the USB Type Micro-B port (X18), via the USB to serial converter FT4232HL. You can use a regular USB Type Micro-B to Type-A.
  • It is possible to route those interfaces to the Primary Extension Header with Dahlia's assembly options. Consult the datasheet for more details.
  • In addition, FTDI and GPIO functions of the FT4232HL are connected to the Verdin SoM via R293-R296, JP6 and JP7. Consult the datasheet for more details.
• UART_1 is available on the Primary Extension Header (X20), as +1.8V TTL signals.
• UART_2 is available on the Secondary Extension Header (X19), as +1.8V TTL signals.

Iris Carrier Board

• To use UART_A (FF_UART) on the Iris carrier board a regular 10 pin female IDC to 9-pin male D-Sub RS-232 serial cable adapter (e.g. as used for most former PC motherboards) on X13 is required.
• To use the UART_B (BT_UART) on the Iris carrier board one can use the same regular RS-232 serial adapter from X13 on X14 as the RXD/TXD and RTS/CTS pins share the same connector layout.
• To use UART_C (STD_UART) on the Iris carrier board one can use X14 pin 1 as UART_C_RXD and pin 7 as UART_C_TXD.

For more information, see also Iris Carrier Board Peripherals.

Ixora Carrier Board

• To use UART1 on the Ixora carrier board a regular 10 pin female IDC to 9-pin male D-Sub RS-232 serial cable adapter (e.g. as used for most former PC motherboards) on X22 is required.
• To use the UART2 on the Ixora carrier board one can use the same regular RS-232 serial adapter from X22 on X21 as the RXD/TXD and RTS/CTS pins share the same connector layout.
• To use UART3 on the Ixora carrier board one can use X21 pin 1 as UART3_RXD and pin 7 as UART3_TXD.
• UART4 is only available as TTL level on the extension connector X27.

Verdin Development Board

The Verdin Development Board exposes the four UART interfaces.

• UART_3 and UART_4 are available on the USB Type Micro-B port (X66), via the USB to serial converter FT4232HL. You can use a regular USB Type Micro-B to Type-A.
  • In addition, FTDI and GPIO functions of the FT4232HL are connected to the Verdin SoM via the X67 jumper area.
• UART_1 is available on a regular 9-pin male D-Sub serial connector (X50), through a RS-485 transceiver. Read the datasheet for available hardware configuration via jumpers JP6, JP9 and JP10.
• UART_2 is available on a regular 9-pin male D-Sub serial connector (X51), through a RS-232 transceiver. Read the datasheet for available hardware configuration via jumpers JP12. The V1.1D has a data rate limit of 250 Kbps. Otherwise, earlier versions are limited to 1000 Kbps.