Raspberry Pi · UART · offline recovery

Access a Raspberry Pi terminal through a Raspberry Pi Pico and UART

A Raspberry Pi can be controlled through a serial console over UART. Since a regular computer usually has no direct GPIO UART port, this guide uses a Raspberry Pi Pico as the USB-UART bridge between the computer and the Raspberry Pi.

Computer USB Raspberry Pi Pico with USB-UART bridge UART Raspberry Pi running Linux console
Main demo

Serial-port terminal in action

The video shows the real macOS flow: finding the Pico as a USB serial port, opening the 115200-baud connection, and getting a Raspberry Pi terminal through UART.

Animation of a macOS terminal opening minicom to the Raspberry Pi through the Pico serial port.
Do not connect 5 V or 3.3 V between the two boards for this setup. Each board must be powered through its normal power input. Only TX, RX, and GND should be connected. Both interfaces use 3.3 V logic levels; do not connect a 5 V UART device directly.

1. Parts needed for the UART link

  • A Raspberry Pi Pico or Pico H that will act as the USB-UART bridge.
  • The Raspberry Pi you already want to control through the serial console.
  • A data-capable USB cable to connect the Pico to the computer. Some USB cables are charge-only.
  • Three Dupont wires for TX, RX, and common GND.
  • A Windows, macOS, or Linux computer to open the serial terminal.

2. Turn the Pico into a USB-UART adapter

This guide uses a custom precompiled UF2 firmware. That firmware turns the Pico into a 115200-baud USB-UART bridge using GP0 as TX and GP1 as RX.

  1. Disconnect the Pico from the computer.
  2. Hold down the BOOTSEL button.
  3. Plug the Pico in over USB while keeping BOOTSEL pressed.
  4. Release the button when a USB drive, usually named RPI-RP2, appears.
  5. Download the UF2 from this page.
  6. Copy the .uf2 file to the RPI-RP2 drive.
  7. Wait until the drive unmounts and the Pico reboots automatically.
  8. Unplug and reconnect the Pico if needed.
The correct wiring is Pico GP0 TX to Raspberry Pi RXD/GPIO15, Pico GP1 RX to Raspberry Pi TXD/GPIO14, and common GND.

After installing it, the Pico should appear on the computer as a USB CDC serial port.

3. Wiring

With the UF2 from this guide, the Pico acts as a USB-UART adapter using GP0 and GP1. The important rule is simple: TX always connects to RX, and RX always connects to TX.

Real photo of a Raspberry Pi connected with UART wires to a Raspberry Pi Pico acting as a USB-UART adapter.
Real setup example: the Raspberry Pi keeps its normal power supply and the Pico connects to the computer over USB. Between both boards, only TX, RX, and common GND are connected.
Raspberry Pi Pico with USB-UART UF2 Function Standard Raspberry Pi
GP0, physical pin 1 Pico TX GPIO15 / RXD, physical pin 10
GP1, physical pin 2 Pico RX GPIO14 / TXD, physical pin 8
GND, for example physical pin 3 Common ground GND, for example physical pin 6
Never connect TX to TX or RX to RX. If the signals are not crossed, you will usually receive no data.

Connect GND first, then TX/RX, especially when both devices are powered from different supplies. The Pico is powered by the USB cable connected to the computer; the Raspberry Pi must use its own power supply.

4. Enable the serial console on the Raspberry Pi

The goal is to enable a Linux console with a login prompt, not to use UART for a sensor or custom application.

sudo raspi-config

Usual path:

Interface Options
└── Serial Port

Answer:

Would you like a login shell to be accessible over serial? Yes
Would you like the serial port hardware to be enabled? Yes
sudo reboot

For this use case, both things must be enabled: UART hardware and login shell over UART. In projects with sensors, GPS, or other peripherals, you normally enable the hardware but disable the console.

grep -o 'console=[^ ]*' /boot/firmware/cmdline.txt
systemctl status serial-getty@serial0.service
ls -l /dev/serial0
On older Raspberry Pi OS versions, boot files may be under /boot/. On recent versions, they are usually under /boot/firmware/. Do not edit cmdline.txt by adding line breaks: it must remain a single line. Make a backup before manually editing boot files.

5. Optional manual configuration

Only if raspi-config does not work. Usually you need:

# /boot/firmware/config.txt
enable_uart=1

# On the single line in /boot/firmware/cmdline.txt
console=serial0,115200

Do not overwrite cmdline.txt entirely. The exact content depends on the Raspberry Pi OS version and the Raspberry Pi model.

Raspberry Pi 5 may differ because it includes a dedicated UART debug connector. Before assuming serial0 is on GPIO14 and GPIO15, check the system mapping and the documentation for the model you are using.
ls -l /dev/serial*
pinctrl get 14
pinctrl get 15
grep -E 'enable_uart|dtoverlay' /boot/firmware/config.txt

6. Connect from macOS

  1. Install and configure the Raspberry Pi Pico correctly if this has not been done yet (follow these steps).
Animation of the macOS flow: finding the Pico USB serial port and opening minicom at 115200 baud to access the Raspberry Pi through UART.
Real macOS example: first identify the /dev/cu.usbmodem* port, then open minicom at 115200 baud and the Raspberry Pi terminal appears over UART.
ls /dev/cu.usbmodem*
ls /dev/cu.*

To compare before and after connecting the Pico:

ls /dev/cu.* > /tmp/ports-before.txt
# Connect the Pico
ls /dev/cu.* > /tmp/ports-after.txt
diff /tmp/ports-before.txt /tmp/ports-after.txt

The port usually looks similar to /dev/cu.usbmodemXXXX, but the exact name changes between computers and connections.

screen /dev/cu.usbmodemXXXX 115200

The configuration is 115200 8N1: 115200 baud, 8 data bits, no parity, 1 stop bit, and no flow control.

To exit screen: press Ctrl+A, then \ and confirm with y.

brew install minicom
minicom -D /dev/cu.usbmodemXXXX -b 115200

If Homebrew is not installed, check its official site: brew.sh.

lsof | grep usbmodem
screen -ls
screen -r
screen -D -r

7. Connect from Linux

ls /dev/ttyACM*
dmesg --follow
sudo dmesg --follow
sudo apt update
sudo apt install minicom
minicom -D /dev/ttyACM0 -b 115200
screen /dev/ttyACM0 115200

Do not always assume /dev/ttyACM0: it may appear as /dev/ttyACM1, /dev/ttyUSB0, or another device.

ls -l /dev/ttyACM0
sudo usermod -aG dialout "$USER"

After adding the user to the relevant group, log out and log back in. Do not use chmod 777 on the device.

8. Connect from Windows with PuTTY

Install PuTTY from Microsoft Store after verifying the official package, from the official installer at chiark.greenend.org.uk/~sgtatham/putty/latest.html, or with winget after checking the exact package identifier:

winget search PuTTY

Connect the Pico, open Device Manager, expand “Ports (COM & LPT)”, look for a USB serial or CMSIS-DAP device, and note the port, for example COM5.

Get-CimInstance Win32_SerialPort |
    Select-Object DeviceID, Name, Description

In PuTTY:

  • Connection type: Serial
  • Serial line: COM5
  • Speed: 115200
  • Connection -> Serial: 8 data bits, 1 stop bit, parity None, flow control None

If the window appears blank, press Enter once or twice. To close cleanly, run exit before closing the window.

9. Log in

Raspberry Pi OS raspberrypi login: daniel Password: daniel@raspberrypi:~ $ hostname

Use an existing user on the Raspberry Pi. The password shows no characters, dots, or asterisks while you type; this is normal on Linux. After authentication, you get a real Raspberry Pi shell, independent of Wi-Fi, Ethernet, or SSH.

hostname
ip address
uname -a
systemctl --failed
journalctl -b -p warning

10. Troubleshooting

Symptom Possible cause Fix
No serial port appears Charge-only cable, wrong UF2, USB problem, or Pico still in BOOTSEL mode. Try another data cable, reinstall the UF2, check Device Manager, /dev/cu.* or /dev/ttyACM*, and reconnect the Pico.
The port exists, but no text appears TX/RX not crossed, missing common GND, serial console disabled, wrong speed, wrong port, or Raspberry Pi powered off. Verify wiring, press Enter, reboot with the terminal already open, and confirm console=serial0,115200 and serial-getty.
Unreadable characters appear Wrong baud rate, configuration other than 8N1, flow control enabled, or UART incorrectly mapped. Use 115200 baud, 8 bits, no parity, 1 stop bit, and no flow control.
Messages appear, but no login prompt UART hardware enabled, but login console disabled, or getty not running. Check serial0 and run systemctl status serial-getty@serial0.service. If appropriate: sudo systemctl enable --now serial-getty@serial0.service.
You can read, but not type The Pico TX -> Pi RX line works, but the Pi TX -> Pico RX line does not; GP0/GP1 swapped; bad cable; flow control enabled. Check the return line, replace the suspect wire, and disable flow control.
screen shows “Resource busy” Another program or session is keeping the port open. Run lsof | grep -E 'usbmodem|ttyACM|ttyUSB' and close the process or recover/close the screen session.
The console works, but SSH does not UART and SSH are independent mechanisms. Use UART to repair networking, firewall, IP address, SSH keys, services, or boot errors.

Configure the Pico correctly and flash the UART bridge UF2

After using Thonny for MicroPython or to check that the Mac detects the board, the UART bridge is not flashed again with Thonny. For this setup, use the Pico BOOTSEL mode and copy an already compiled .uf2 file directly to the RPI-RP2 drive.

This custom firmware turns the Pico into a USB-UART bridge using Serial over USB and Serial1 over UART0. This UF2 uses GP0 as TX and GP1 as RX.

Downloadable files for the Pico

Download the precompiled UF2 to flash it directly onto the Pico. The Arduino sketch is included in case you want to review the code or rebuild it yourself.

SHA-256: e81d2f46e79dbd3f2e4d864bf0d03309dcfa2fd98e372a13236c1359cc6459a8
This UF2 is for the custom firmware with GP0 as TX and GP1 as RX: GP0 -> Raspberry Pi RXD/GPIO15, GP1 <- Raspberry Pi TXD/GPIO14 and common GND.

Exact steps from macOS

  1. Put the Pico in BOOTSEL mode: unplug USB, hold BOOTSEL, plug USB back in, wait 2-3 seconds, then release BOOTSEL.
  1. Check that macOS sees it as a mounted volume.
ls /Volumes

You should see:

RPI-RP2
  1. Download the already compiled UF2 firmware from this page.
pico_usb_uart_bridge.ino.uf2
  1. Copy that file to the Pico mounted as RPI-RP2.
cp ~/Downloads/pico_usb_uart_bridge.ino.uf2 /Volumes/RPI-RP2/
  1. When the copy finishes, the Pico reboots by itself and comes back as a serial port. The exact name can change; in this setup it appeared as:
/dev/cu.usbmodem21201
  1. Open the Pico as a 115200-baud serial port, replacing the port if macOS assigned a different name.
minicom -D /dev/cu.usbmodem21201 -b 115200
  1. To exit minicom, press Ctrl-A, then X.
  2. Connect Pico GP0 TX to Raspberry Pi GPIO15/RXD, Pico GP1 RX to Raspberry Pi GPIO14/TXD, and GND to GND.
Where that UF2 comes from

The pico_usb_uart_bridge.ino.uf2 file is produced by compiling the downloadable Arduino/C++ sketch from this page with binary export enabled. If you want to rebuild it with arduino-cli, create a sketch folder named pico_usb_uart_bridge and save pico_usb_uart_bridge.ino inside it:

arduino-cli compile --export-binaries -b rp2040:rp2040:rpipico pico_usb_uart_bridge
Notes
  • If RPI-RP2 does not appear, the Pico is not in BOOTSEL mode.
  • If /dev/cu.usbmodem* does not appear, macOS is not detecting the Pico.
  • If minicom shows Resource busy, another program is using the port. Close Thonny, screen, Arduino IDE, or any other serial terminal.
  • The pico_usb_uart_bridge firmware turns the Pico into a 115200-baud USB-UART bridge.

Firmware source code

// Raspberry Pi Pico USB <-> UART bridge for Raspberry Pi serial console.
static constexpr uint32_t UART_BAUD = 115200;
static constexpr int UART_TX_PIN = 0;  // GP0 -> Pi RXD GPIO15, pin 10
static constexpr int UART_RX_PIN = 1;  // GP1 <- Pi TXD GPIO14, pin 8

void setup() {
  Serial.begin(115200);
  Serial1.setTX(UART_TX_PIN);
  Serial1.setRX(UART_RX_PIN);
  Serial1.begin(UART_BAUD);
  Serial.ignoreFlowControl(true);

  unsigned long start = millis();
  while (!Serial && (millis() - start < 1500)) {
    delay(10);
  }

  delay(200);
  while (Serial.available()) {
    Serial.read();
  }

  Serial.println("Pico USB-UART bridge ready (GP0 TX, GP1 RX, 115200)");
}

void loop() {
  while (Serial.available()) {
    Serial1.write(Serial.read());
  }

  while (Serial1.available()) {
    Serial.write(Serial1.read());
  }
}