How to Use PuTTY for Raspberry Pi Serial UART and SSH Debugging

PuTTY connects to a Raspberry Pi via SSH (IP address, port 22) or Serial UART (COM port, 115200 baud). When your headless Pi drops off the network, corrupts its WPA supplicant config, or fails to boot entirely, SSH is useless. The hardware Serial UART connection via GPIO 14 (TXD) and GPIO 15 (RXD) is your ultimate fallback to regain shell access. This guide covers the exact wiring, PuTTY configuration, and a Python debugging script for the Raspberry Pi 4 Model B to get you back into the terminal.

Hardware Spec Sheet & UART Pin Mapping

Before opening PuTTY, you need a reliable physical layer. Do not use unmarked, cheap USB-to-serial adapters; many clone chips lack proper 3.3V logic level shifting and will fry your Pi's GPIO pins.

GPIO Pin Mapping (Pi 4 to FTDI Adapter)

The Raspberry Pi 4 uses 3.3V logic on its UART pins. Ensure your FTDI adapter is physically set to 3.3V or is a dedicated 3.3V cable.

Step-by-Step PuTTY Serial Configuration

By default, the Raspberry Pi routes its primary hardware UART (/dev/ttyAMA0) to the Bluetooth module. To use the GPIO pins for a serial console, you must reconfigure the Pi's boot overlays.

1. Enable UART in config.txt: If you have SD card access, mount the boot partition on your PC and open config.txt (located in /boot/firmware/ on Bookworm OS). Add these lines to the bottom:

   enable_uart=1
   dtoverlay=disable-bt

   This disables Bluetooth and maps the high-performance PL011 hardware UART to GPIO 14/15.
2. Wire the Adapter: Connect the FTDI cable to the Pi according to the pin mapping table above. Plug the USB end into your host PC.
3. Identify the COM Port: On Windows, open Device Manager > Ports (COM & LPT). Note the COM number assigned to the 'USB Serial Port' (e.g., COM3). On Linux, it will appear as /dev/ttyUSB0.
4. Configure PuTTY: Open PuTTY. Under 'Connection type', select the Serial radio button.
5. Set Parameters: Enter your COM port in the 'Serial line' box. Set 'Speed' (baud rate) to 115200. Data bits: 8, Stop bits: 1, Parity: None, Flow control: None.
6. Open Session: Click 'Open'. Press the Enter key twice. You should see the raspberrypi login: prompt.

Troubleshooting Exact PuTTY Error Strings

When embedded debugging goes wrong, PuTTY throws specific errors. Here is how to decode them and the first three things to check when your connection fails.

Error: 'Network error: Connection refused'

Context: This occurs when using PuTTY over SSH (IP address), not Serial.

• Cause 1: The SSH daemon (sshd) is not running or is disabled. Fix: Add an empty file named ssh (no extension) to the root of the Pi's boot partition and reboot.
• Cause 2: The Pi is on a different subnet or dropped its Wi-Fi connection. Fix: Switch to the Serial UART method outlined above to log in and run ip a to check the network stack.

Error: 'Unable to open connection to COM3: Access denied'

Context: Serial connection failure on Windows.

• Cause 1: Another program has locked the COM port. Fix: Close the Arduino IDE, Cura, or any other software that polls serial ports in the background.
• Cause 2: Windows 11 assigned a generic, incompatible driver to a PL2303 clone chip. Fix: Use a genuine FTDI FT232RL adapter, or roll back the driver in Device Manager to the 2014 PL2303 driver version.

Symptom: Blank Black Screen (No Error Popup)

Context: PuTTY opens, but the cursor just blinks on a black screen.

• Cause 1: The Pi is powered off or stuck in a boot loop. Fix: Check the power LED. If it flashes in a specific pattern, consult the Pi bootloader diagnostics.
• Cause 2: Flow control is enabled. Fix: In PuTTY settings (Connection > Serial), ensure 'Flow control' is set to None. Hardware flow control pins (RTS/CTS) are not wired, so the Pi waits indefinitely for a clear-to-send signal.

Python UART Bridge Script (Pi 4 Target)

Once you are logged into the Pi via PuTTY, you often need to debug external UART sensors (like a PM2.5 sensor or GPS module) wired to the Pi's secondary UART or a USB-serial dongle. Below is a complete, compilable Python script that reads from an external serial device and logs it safely.

Target Board: Raspberry Pi 4 Model B.
Dependencies: sudo apt install python3-serial (or pip3 install pyserial).
Hardware Note: This script targets /dev/ttyUSB0 (a secondary USB-to-Serial adapter plugged into the Pi's USB port, reading an external 3.3V sensor). If you wired the sensor directly to the Pi's GPIO UART, change the port to /dev/ttyAMA0 (assuming Bluetooth is disabled as shown in step 1).

#!/usr/bin/env python3
"""
serial_logger.py
Target: Raspberry Pi 4 Model B
Reads NMEA/sensor data from an external UART device and logs to stdout.
"""
import serial
import time
import sys
import os

# Pin/Port Mapping:
# External Sensor TX -> USB-Serial Adapter RX -> Pi USB Port (/dev/ttyUSB0)
# External Sensor GND -> USB-Serial Adapter GND -> Pi GND
SERIAL_PORT = '/dev/ttyUSB0'
BAUD_RATE = 9600
TIMEOUT = 2  # seconds

def main():
    print(f'Attempting to open {SERIAL_PORT} at {BAUD_RATE} baud...')
    
    try:
        # Initialize serial connection with error handling
        ser = serial.Serial(
            port=SERIAL_PORT,
            baudrate=BAUD_RATE,
            bytesize=serial.EIGHTBITS,
            parity=serial.PARITY_NONE,
            stopbits=serial.STOPBITS_ONE,
            timeout=TIMEOUT
        )
        print(f'Successfully connected to {ser.name}. Press CTRL+C to exit.\n')
        
        # Clear the input buffer to avoid reading stale data
        ser.reset_input_buffer()
        
        while True:
            try:
                # Read a line, decode to UTF-8, and strip newline characters
                if ser.in_waiting > 0:
                    raw_data = ser.readline()
                    decoded_line = raw_data.decode('utf-8', errors='replace').strip()
                    
                    if decoded_line:
                        timestamp = time.strftime('%H:%M:%S')
                        print(f'[{timestamp}] SENSOR: {decoded_line}')
                        sys.stdout.flush() # Force print to PuTTY terminal immediately
                        
            except serial.SerialException as e:
                print(f'\n[ERROR] Serial port disconnected or failed: {e}')
                break
                
    except serial.SerialException as e:
        print(f'[FATAL] Could not open serial port {SERIAL_PORT}.')
        print(f'Details: {e}')
        print('Check if the device is plugged in and if user has dialout permissions.')
        print('Fix permissions with: sudo usermod -a -G dialout $USER')
        sys.exit(1)
        
    except KeyboardInterrupt:
        print('\n[INFO] Logging stopped by user (CTRL+C).')
    finally:
        if 'ser' in locals() and ser.is_open:
            ser.close()
            print('[INFO] Serial port closed cleanly.')

if __name__ == '__main__':
    main()

Execution: Run this script inside your PuTTY session using python3 serial_logger.py. The sys.stdout.flush() command is critical; without it, Python buffers the output, and PuTTY will appear to hang until the buffer fills.

Extending and Simplifying the Build

Depending on your project phase, you will want to scale this debugging setup up or down.

How to Simplify (Production Phase)

Once your embedded project is stable, drop the FTDI UART cable entirely. Rely solely on SSH over Wi-Fi/Ethernet. Remove dtoverlay=disable-bt from config.txt to re-enable Bluetooth if your project requires it, and use a headless logging service like systemd-journald instead of printing to stdout.

How to Extend (Advanced Debugging)

• Add SD Card Logging: Modify the Python script to append decoded_line to a CSV file on the Pi's SD card, ensuring you don't lose data if the PuTTY session drops.
• MQTT Telemetry: Instead of printing to stdout, use the paho-mqtt Python library to publish the UART sensor data to a local Mosquitto broker. You can then monitor the data via Node-RED on another machine without keeping a PuTTY SSH session open.
• Logic Analyzer: If the UART data is corrupted, bypass PuTTY temporarily. Connect a $10 24MHz logic analyzer (like a Saleae clone) to GPIO 14/15 and use PulseView to decode the raw UART frames and check for baud-rate drift.

FAQ: PuTTY for Raspberry Pi

Why is my PuTTY serial connection to Raspberry Pi showing garbage text?

Garbage text (e.g., ÿÿÿ or random symbols) almost always indicates a baud rate mismatch. The Raspberry Pi bootloader and Linux console default to 115200 baud. If your PuTTY session is set to 9600 or 38400, the timing of the bits will be misinterpreted. Double-check the 'Speed' field in PuTTY's Serial configuration. Less commonly, it can be caused by a ground loop; ensure the GND wire between the Pi and the FTDI adapter is secure and of adequate gauge (22 AWG or thicker).

How do I find the correct COM port for PuTTY on Windows 11?

Press Win + X and select Device Manager. Expand the Ports (COM & LPT) section. Plug in your USB-to-Serial adapter; a new entry like 'USB Serial Port (COM4)' will appear. If it appears under 'Other Devices' with a yellow warning triangle, Windows lacks the driver. For FTDI chips, Windows usually fetches the driver automatically. For Prolific PL2303 chips, you may need to download the specific driver from the Prolific website.

Can I use PuTTY for Raspberry Pi Pico over USB?

Yes, but the setup is different. The Raspberry Pi Pico (RP2040) does not run Linux; it runs bare-metal C/C++ or MicroPython. When you flash MicroPython onto a Pico and connect it via USB, it exposes a serial REPL (Read-Eval-Print Loop). You can use PuTTY to connect to the Pico's COM port at 115200 baud to interact with the MicroPython prompt directly. However, for Pico development, dedicated IDEs like Thonny or VS Code with the MicroPython extension are generally preferred over raw PuTTY.

What baud rate should I use for Raspberry Pi serial console?

The standard baud rate for the Raspberry Pi Linux serial console is 115200 (8 data bits, no parity, 1 stop bit). This is hardcoded in the Pi's cmdline.txt file (console=serial0,115200). While you can technically change this to 9600 by editing the boot parameters, there is no practical reason to do so, as 115200 is universally supported by modern FTDI adapters and provides a much faster terminal experience.