Module rppal::uart

Interface for the UART peripherals and any USB to serial adapters.

RPPAL controls the Raspberry Pi’s UART peripherals through the ttyAMA0 (PL011) and ttyS0 (mini UART) character devices. USB to serial adapters are controlled using the ttyUSBx and ttyACMx character devices.

UART peripherals

The Raspberry Pi’s BCM283x SoC features two UART peripherals. /dev/ttyAMA0 represents the PL011 UART, which offers a full set of features. /dev/ttyS0 represents an auxiliary peripheral that’s referred to as mini UART, with limited capabilities. More details on the differences between the PL011 and mini UART can be found in the official Raspberry Pi documentation.

On earlier Raspberry Pi models without Bluetooth, /dev/ttyAMA0 is configured as a Linux serial console. On more recent models with Bluetooth (3A+, 3B, 3B+, Zero W), /dev/ttyAMA0 is connected to the Bluetooth module, and /dev/ttyS0 is used as a serial console instead. Due to the limitations of /dev/ttyS0 and the requirement for a fixed core frequency, in most cases you’ll want to use /dev/ttyAMA0 for serial communication.

By default, TX (outgoing data) is tied to BCM GPIO 14 (physical pin 8) and RX (incoming data) is tied to BCM GPIO 15 (physical pin 10). You can move these lines to different GPIO pins using the uart0 and uart1 overlays, but the alternative pin options aren’t exposed through the GPIO header on any of the current Raspberry Pi models. They are only available on the Compute Module’s SO-DIMM pads.

Configure /dev/ttyAMA0 for serial communication (recommended)

Disable the Linux serial console by either deactivating it through sudo raspi-config, or manually removing the parameter console=serial0,115200 from /boot/cmdline.txt.

Remove any lines containing enable_uart=0 or enable_uart=1 from /boot/config.txt.

On Raspberry Pi models with a Bluetooth module, an extra step is required to either disable Bluetooth or move it to /dev/ttyS0, so /dev/ttyAMA0 becomes available for serial communication.

To disable Bluetooth, add dtoverlay=pi3-disable-bt to /boot/config.txt. You’ll also need to disable the service that initializes Bluetooth with sudo systemctl disable hciuart.

To move the Bluetooth module to /dev/ttyS0, instead of disabling it with the above-mentioned steps, add dtoverlay=pi3-miniuart-bt and core_freq=250 to /boot/config.txt.

Remember to reboot the Raspberry Pi after making any changes.

Configure /dev/ttyS0 for serial communication

If you prefer to leave the Bluetooth module connected to /dev/ttyAMA0, you can configure /dev/ttyS0 for serial communication instead.

Disable the Linux serial console by either deactivating it through sudo raspi-config, or manually removing the parameter console=serial0,115200 from /boot/cmdline.txt.

Add the line enable_uart=1 to /boot/config.txt to enable serial communication on /dev/ttyS0, which also sets a fixed core frequency.

Remember to reboot the Raspberry Pi after making any changes.

USB to serial adapters

In addition to controlling the hardware UART peripherals, Uart can also be used for USB to serial adapters. Depending on the type of device, these can be accessed either through /dev/ttyUSBx or /dev/ttyACMx, where x is an index starting at 0. The numbering is based on the order in which the devices are discovered by the kernel.

When you have multiple USB to serial adapters connected at the same time, you can uniquely identify a specific device by searching for the relevant symlink in the /dev/serial/by-id directory, or by adding your own udev rules.

Support for automatic software (XON/XOFF) and hardware (RTS/CTS) flow control for USB to serial adapters depends on the USB interface IC on the device, and the relevant Linux driver. Some ICs use an older, incompatible RTS/CTS implementation, sometimes referred to as legacy or simplex mode, where RTS is used to indicate data is about to be transmitted, rather than to request the external device to resume its transmission.

Hardware flow control

The RTS/CTS hardware flow control implementation supported by Uart and used by the Raspberry Pi’s UART peripherals requires RTS on one device to be connected to CTS on the other device. The RTS signal is used to request the other device to pause or resume its transmission.

Some devices use an older, incompatible RTS/CTS implementation, sometimes referred to as legacy or simplex mode, where RTS is connected to RTS, and CTS to CTS. The RTS signal is used to indicate data is about to be transmitted. Uart is not compatible with this implementation. Connecting the Raspberry Pi’s RTS and CTS pins incorrectly could damage the Pi or the external device.

When Uart is controlling a UART peripheral, enabling hardware flow control will also configure the RTS and CTS pins. On Raspberry Pi models with a 40-pin GPIO header, RTS is tied to BCM GPIO 17 (physical pin 11) and CTS is tied to BCM GPIO 16 (physical pin 36). RTS and CTS aren’t available on models with a 26-pin header, except for the Raspberry Pi B Rev 2, which exposes RTS and CTS through its unpopulated P5 header with RTS on BCM GPIO 31 (physical pin 6) and CTS on BCM GPIO 30 (physical pin 5).

The RTS and CTS pins are reset to their original state when Uart goes out of scope. Note that drop methods aren’t called when a process is abnormally terminated, for instance when a user presses Ctrl + C and the SIGINT signal isn’t caught, which prevents Uart from resetting the pins. You can catch those using crates such as simple_signal.

Troubleshooting

Permission denied

If new or with_path returns an io::ErrorKind::PermissionDenied error, make sure the file permissions for the specified device are correct, and the current user is a member of the group that owns the device, which is usually either dialout or tty.

Structs

Status	Control signal status.
Uart	Provides access to the Raspberry Pi’s UART peripherals and any USB to serial adapters.

Enums

Error	Errors that can occur when accessing the UART peripheral.
Parity	Parity bit modes.
ParityCheck	Parity check modes.
Queue	Queue types.

Type Definitions

Result

Result type returned from methods that can have uart::Errors.