Attaching to a Raspberry Pi's Serial Console (UART) for debugging

Sometimes a Pi just won't boot. Or it'll boot, but it'll do weird things. Or you don't have an HDMI display, and you can't log into your Pi via SSH. Or maybe you're like me, and someone 'accidentally' cut your Raspberry Pi in half, and you want to see what it's doing since it won't boot anymore.

Raspberry Pi with UART Serial Console Debug cable connected

The Raspberry Pi can output information over a 'serial console', technically known as a UART (Universal Asynchronous Receiver/Transmitter). Many devices—including things like storage controller cards, which in a sense run their own internal operating system on an SoC—have a 'UART header', which is typically three or four pins that can connect over the RS-232 standard (though many do not operate at 12v like a traditional serial port! Use a USB-to-TTL adapter like the one I mention below).

Simply Embedded has a great overview of UART if you want to learn more.

If you want to access the Pi's serial console, here's what you need to do:

  1. Buy a USB to serial adapter. I bought the Adafruit 954 USB-to-TTL Serial Cable.
  2. Pop the Pi's microSD card into another computer, edit the config.txt file inside the boot volume, and add the following line at the bottom: enable_uart=1.
  3. Save that change, eject the microSD card, and stick the card back into the Pi.
  4. Plug the USB to serial adapter into the pins as pictured below on the Pi (Black to GND, White to GPIO 14/pin 8 (UART TX), and Green to GPIO 15/pin 10 (UART RX)):

    Raspberry Pi Serial Connection with Adafruit USB to TTL Adapter

  5. Open a terminal window on your Mac, and run ls /dev | grep usb

  6. Note the tty.usbserial- and cu.usbserial- numbers in there. That's the device you'll connect to on your Mac.

There are a number of ways to interact with the serial console on a Mac (and most are the same as on Linux, with sometimes minor usage differences), but the two I've used in the past are minicom and screen.

Use minicom

  1. Install minicom (brew install minicom) so you can emulate a terminal connected over serial.
  2. Run minicom -b 115200 -D /dev/tty.usbserial-0001
  3. Boot the Pi.
  4. Within a few seconds, you should see data in your session.

Note: In metacom, the Meta key is mapped to 'Esc' by default, at least on macOS. So press 'Esc-Z' to get help.

Use screen

  1. Run screen /dev/tty.usbserial-0001 115200
  2. Boot the Pi.
  3. Within a few seconds, you should see data in your session.

Note: To exit the screen session, press Ctrl-A, then Ctrl-K, and confirm you want to exit.

Debugging session in screen on macOS via Serial Console

See also: Adafruit's guide to using a serial console on the Pi.

I've done this process a few times in the past, but I've grown tired of looking back at old notes to remember specifically which pins to use on the GPIO, since I don't do it that often and the pins are unlabeled on most Pis. Hope this helped!

Update: I also forgot to mention—it's possible to get output from the Pi's own bootloader (at an even earlier stage) using the BOOT_UART option supplied to a custom EEPROM build; see cleverca22's post in the Pi Forums for details.

Comments

You can use another Pi to access the other by crossing rx/tx between the three wires. I find it pretty simple and reliable - enough that I dont remember where my usb-ftdi adapters are anymore.

True! I often don't have a spare monitor around though with all the Pis I'm running, so using USB to UART is easier since I almost always have my laptop on hand.

Right. But maybe you don't have a USB serial adapter handy, but do have a spare (second) Raspberry Pi. You can run the second Raspberry Pi headless, say, a Zero W. The goal is to ssh from laptop to this second Pi then use it's serial connection. The second Pi will need USB power, which for a Zero you should be able to get from your laptop. To allow a network connection from your laptop to the second Pi, you have a few choices:

1. Add USB network adapter to the second Pi and use an Ethernet cable
2. Configure the second Pi as a Wi-Fi access point you can connect to with your laptop
3. But for me the real winner is to set a Pi Zero up as a USB Gadget
3a. Set up the Pi Zero as an Ethernet Gadget (laptop will see Zero as USB Ethernet device when connected)
3b. Even simpler, set up the Pi Zero as a Serial Gadget (doesn't require a Zero W, a plain old Zero will work)

With an Ethernet connection, ssh to the second Pi and run minicom in the session. To connect to a Serial Gadget, instead run minicom on the laptop to connect to the second Pi, then run minicom to connect to the actual target (and be reminded of "Inception").

If you use a Zero W with no headers you can solder three wires to it with a triple header socket on the other end. (Don't forget to cross RX/TX as abeck mentions.) This is small enough to easily fit in a bag's pocket for easy traveling.

Cons (vs USB serial adapter):
* This is more complicated (but a great learning opportunity)

Pros (vs USB serial adapter):

* You may already have a Pi Zero laying around.
* A Pi Zero can be configured to do a lot more than just act as a serial bridge. (It's a great addition to your Go Bag.)

Will this also work with Windows, using a terminal program?

I am having a broken rpi4 where it also just has a study green light, but nothing seems to be in the TTY. Any ideas what I might be doing wrong?