http://www.jeffgeerling.com/blog/2021/attaching-raspberry-pis-serial-console-uart-debugging

Skip to main content
Jeff Geerling

Main menu

  * Blog
  * Projects
  * About

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

October 1, 2021

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!

Further reading

  * The Raspberry Pi Compute Module 4 Review
  * Hardware RAID on the Raspberry Pi CM4
  * Setting up a Pi for remote Internet connection monitoring

raspberry pi
uart
debugging
serial
console
adafruit

  * Add new comment

Comments

abeck - 2 hours ago

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.

  * Reply

Jeff Geerling - 2 hours ago

In reply to You can use another Pi to... by abeck

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.

  * Reply

Search [                              ]
[Search]
Geerling Family Crest
All content copyright Jeff Geerling. Top of page.