# Source: uart.adoc

*Note: This file could not be automatically converted from AsciiDoc.*

== Configure UARTs

There are two types of UART available on the Raspberry Pi -  http://infocenter.arm.com/help/index.jsp?topic=/com.arm.doc.ddi0183g/index.html[PL011] and mini UART. The PL011 is a capable, broadly 16550-compatible UART, while the mini UART has a reduced feature set.

All UARTs on the Raspberry Pi are 3.3V only - damage will occur if they are connected to 5V systems. An adapter can be used to connect to 5V systems. Alternatively, low-cost USB to 3.3V serial adapters are available from various third parties.

=== Raspberry Pi Zero, 1, 2 and 3

The Raspberry Pi Zero, 1, 2, and 3 each contain two UARTs as follows:

|===
| Name | Type

| UART0
| PL011

| UART1
| mini UART
|===

=== Raspberry Pi 4 and 400

The Raspberry Pi 4 Model B and 400 have an additional four PL011s, which are disabled by default:

|===
| Name | Type

| UART0
| PL011

| UART1
| mini UART

| UART2
| PL011

| UART3
| PL011

| UART4
| PL011

| UART5
| PL011
|===

=== Raspberry Pi 5

Raspberry Pi 5 has an additional four PL011s, which are disabled by default:

|===
| Name | Type

| UART0
| PL011

| UART1
| PL011

| UART2
| PL011

| UART3
| PL011

| UART4
| PL011

|===

Raspberry Pi 5 does not have mini UART.

=== CM1, CM3, CM3+ and CM4

The first generation Compute Module, together with Compute Module 3 and Compute Module 3+, has two UARTs, while Compute Module 4 has six UARTs as described above.

On all models of Compute Module, the UARTs are disabled by default and can be explicitly enabled using a Device Tree overlay. You may also specify which GPIO pins to use, for example:

[source,ini]
----
dtoverlay=uart1,txd1_pin=32,rxd1_pin=33
----

=== Primary UART

On the Raspberry Pi, one UART is selected to be present on GPIO 14 (transmit) and 15 (receive) - this is the primary UART. By default, this will also be the UART on which a Linux console may be present. Note that GPIO 14 is pin 8 on the GPIO header, while GPIO 15 is pin 10.

On Raspberry Pi 5, the primary UART appears on the Debug header.

=== Secondary UART

The secondary UART is not normally present on the GPIO connector. By default, the secondary UART is connected to the Bluetooth side of the combined wireless LAN/Bluetooth controller, on models which contain this controller.

=== Primary and Secondary UART

The following table summarises the assignment of UARTs on various Raspberry Pi devices:

|===
| Model | Primary/console | Secondary/Bluetooth

| Raspberry Pi Zero
| UART0
| UART1

| Raspberry Pi Zero W / Raspberry Pi Zero 2 W
| UART1
| UART0

| Raspberry Pi 1
| UART0
| UART1

| Raspberry Pi 2
| UART0
| UART1

| Raspberry Pi 3
| UART1
| UART0

| Compute Module 3 & 3+
| UART0
| UART1

| Raspberry Pi 4
| UART1
| UART0

| Raspberry Pi 5
| UART10
| <dedicated UART>
|===

Linux devices on Raspberry Pi OS:

|===
| Linux device | Description

| `/dev/ttyS0`
| mini UART

| `/dev/ttyAMA0`
| first PL011 (UART0)

| `/dev/serial0`
| primary UART

| `/dev/serial1`
| secondary UART

| `/dev/ttyAMA10`
| Raspberry Pi 5 Debug UART
|===

`/dev/serial0` and `/dev/serial1` are symbolic links which point to either `/dev/ttyS0` or `/dev/ttyAMA0`.

On the Raspberry Pi 5, `/dev/serial0` is a symbolic link that points to `/dev/ttyAMA10`.

Due to changes in _Bookworm_, `/dev/serial1` does not exist by default. You can re-enable `serial1` by setting the following values in `config.txt`:

[source,ini]
----
dtparam=krnbt=off
----

TIP: This option may not work on all models in the future. Only use this option if there is no other alternative for your use case.

=== Mini-UART and CPU Core Frequency

NOTE: The mini UART is disabled by default if it is the primary or when Bluetooth is disabled.

In order to use the mini UART, you need to configure the Raspberry Pi to use a fixed VPU core clock frequency. This is because the mini UART clock is linked to the VPU core clock, so that when the core clock frequency changes, the UART baud rate will also change. The `enable_uart` and `core_freq` settings can be added to `config.txt` to change the behaviour of the mini UART. The following table summarises the possible combinations:

|===
| Mini UART set to | core clock | Result

| primary UART
| variable
| mini UART disabled

| primary UART
| fixed by setting `enable_uart=1`
| mini UART enabled, core clock fixed to 250 MHz, or if `force_turbo=1` is set, the VPU turbo frequency

| secondary UART
| variable
| mini UART disabled

| secondary UART
| fixed by setting `core_freq=250`
| mini UART enabled
|===

The default state of the `enable_uart` flag depends on which UART is the primary UART:

|===
| Primary UART | Default state of enable_uart flag

| mini UART
| 0

| first PL011 (UART0)
| 1
|===

=== Disabling the Linux Serial Console

By default, the primary UART is assigned to the Linux console. If you wish to use the primary UART for other purposes, you must reconfigure Raspberry Pi OS. This can be done by using xref:configuration.adoc#raspi-config[raspi-config]:

* Start raspi-config: `sudo raspi-config`
* Select option 3 - Interface Options
* Select option P6 - Serial Port
* At the prompt `Would you like a login shell to be accessible over serial?`, answer 'No'
* At the prompt `Would you like the serial port hardware to be enabled?`, answer 'Yes'
* Exit `raspi-config` and reboot the Raspberry Pi for changes to take effect

=== Enabling early console for Linux

Although the Linux kernel starts the UARTs relatively early in the boot process, it is still long after some critical bits of infrastructure have been set up. A failure in those early stages can be hard to diagnose without access to the kernel log messages from that time. To enable `earlycon` support for one of the UARTs, add one of the following options to `cmdline.txt`, depending on which UART is the primary:

For Raspberry Pi 5, `earlycon` output only appears on the 3-pin debug connector with the following configuration:

[source,ini]
----
earlycon=pl011,0x107d001000,115200n8
----

For Raspberry Pi 4, Compute Module 4, Compute Module 4S, and Pi 400:

[source,ini]
----
earlycon=uart8250,mmio32,0xfe215040
earlycon=pl011,mmio32,0xfe201000
----

For Raspberry Pi 2, 3, 3+, Zero 2 W, Compute Module 3, and Compute Module 3+:

[source,ini]
----
earlycon=uart8250,mmio32,0x3f215040
earlycon=pl011,mmio32,0x3f201000
----

For Raspberry Pi 1, Zero, Zero W, and Compute Module 1:

[source,ini]
----
earlycon=uart8250,mmio32,0x20215040
earlycon=pl011,mmio32,0x20201000
----

The baudrate defaults to 115200bps.

NOTE: Selecting the wrong early console can prevent the Raspberry Pi from booting.

=== UARTs and Device Tree

Various UART Device Tree overlay definitions can be found in the https://github.com/raspberrypi/linux[kernel GitHub]. The two most useful overlays are https://github.com/raspberrypi/linux/blob/rpi-6.1.y/arch/arm/boot/dts/overlays/disable-bt-overlay.dts[`disable-bt`] and https://github.com/raspberrypi/linux/blob/rpi-6.1.y/arch/arm/boot/dts/overlays/miniuart-bt-overlay.dts[`miniuart-bt`].

`disable-bt` disables the Bluetooth device and makes the first PL011 (UART0) the primary UART. You must also disable the system service that initialises the modem, so it does not connect to the UART, using `sudo systemctl disable hciuart`.

`miniuart-bt` switches the Bluetooth function to use the mini UART, and makes the first PL011 (UART0) the primary UART. Note that this may reduce the maximum usable baud rate (see mini UART limitations below). You must also set the VPU core clock to a fixed frequency using either `force_turbo=1` or `core_freq=250`.

The overlays `uart2`, `uart3`, `uart4`, and `uart5` are used to enable the four additional UARTs on the Raspberry Pi 4. There are other UART-specific overlays in the folder. Refer to `/boot/firmware/overlays/README` for details on Device Tree overlays, or run `dtoverlay -h overlay-name` for descriptions and usage information.

You add a line to the `config.txt` file to apply a xref:configuration.adoc#device-trees-overlays-and-parameters[Device Tree overlay]. Note that the `-overlay.dts` part of the filename is removed. For example:

[source,ini]
----
dtoverlay=disable-bt
----

=== PL011 and mini-UART

There are some differences between PL011 UARTs and mini-UART.

The mini-UART has smaller FIFOs. Combined with the lack of flow control, this makes it more prone to losing characters at higher baudrates. It is also generally less capable than a PL011, mainly due to its baud rate link to the VPU clock speed.

The particular deficiencies of the mini UART compared to a PL011 are:

* No break detection
* No framing errors detection
* No parity bit
* No receive timeout interrupt

Neither the mini UART nor the BCM2835 implementation of the PL011 has DCD, DSR, DTR or RI signals.

Further documentation on the mini UART can be found in the https://datasheets.raspberrypi.com/bcm2835/bcm2835-peripherals.pdf[SoC peripherals document].