Expand description
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,
/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
- Control signal status.
- Provides access to the Raspberry Pi’s UART peripherals and any USB to serial adapters.
Enums
- Errors that can occur when accessing the UART peripheral.
- Parity bit modes.
- Parity check modes.
- Queue types.
Type Definitions
- Result type returned from methods that can have
uart::Errors.