How to Connect PuTTY to Raspberry Pi 5: SSH and Serial UART Debugging

To connect PuTTY to a Raspberry Pi, you must choose between two protocols: SSH (over your local network) or Serial UART (via a physical USB-to-TTL adapter). For a Raspberry Pi 5 running Raspberry Pi OS Bookworm, SSH requires enabling the daemon via raspi-config or the boot partition, while Serial requires setting enable_uart=1 in /boot/firmware/config.txt and wiring a 3.3V logic adapter to GPIO 14 and 15. If your Pi is on Wi-Fi, use SSH on port 22; if it is bricked or unprovisioned, use Serial at 115200 baud.

The Verdict: SSH vs. Serial UART for PuTTY Connections

Choosing the right connection method prevents hours of blind troubleshooting. Use this decision tree to select your protocol before opening PuTTY.

Parts List & Pi 5 UART Pin Mapping

This guide assumes you are working with the current-generation Raspberry Pi 5 (4GB or 8GB variant) running Raspberry Pi OS Bookworm (64-bit). The Pi 5 introduced a dedicated 3-pin JST debug UART connector, but the standard 40-pin GPIO header remains the universal standard for hobbyist serial adapters.

Required Components

• Board: Raspberry Pi 5 (4GB/8GB)
• Adapter: USB-to-TTL Serial Cable (CP2102 or PL2303 chipset). Must be 3.3V logic.
• Power: Official Raspberry Pi 27W USB-C Power Supply
• Storage: 32GB+ microSD card (A2 speed class recommended)

Serial UART Pin Mapping (40-Pin Header)

Note: TX always connects to RX, and RX to TX. Do not connect the adapter's VCC/5V pin to the Pi unless you are intentionally back-powering the board (not recommended for Pi 5).

Step-by-Step: Configuring PuTTY for SSH and Serial

Bookworm changed the boot partition mount point from /boot/ to /boot/firmware/. Older tutorials will point you to the wrong directory. Follow these exact steps to enable both protocols.

1. Enabling SSH (Network)

1. Flash Raspberry Pi OS Bookworm using Raspberry Pi Imager. In the OS Customization menu, check 'Enable SSH' and select 'Use password authentication'.
2. Boot the Pi and find its IP address via your router's DHCP table (e.g., 192.168.1.45).
3. Open PuTTY. Set Connection type to 'SSH', enter the IP address, and ensure Port is 22.
4. Click Open. Accept the host key fingerprint and log in with your username (default pi if created, or your custom user).

2. Enabling Serial UART (Physical)

1. Access the Pi's boot partition via SSH or by plugging the SD card into your PC.
2. Open /boot/firmware/config.txt in a text editor (e.g., sudo nano /boot/firmware/config.txt).
3. Add the line enable_uart=1 at the very bottom of the file. Save and reboot.
4. Wire the CP2102 adapter to the Pi as per the pin mapping table above.
5. Plug the CP2102 USB into your Windows PC. Open Device Manager to find the COM port number (e.g., COM3).
6. Open PuTTY. Set Connection type to 'Serial', enter COM3 in the Serial line box, and set Speed to 115200.
7. Click Open. Press Enter a few times to trigger the login prompt.

Python Telemetry Code: Sending Data to PuTTY over UART

Once your serial connection is established, you can use PuTTY as a raw data terminal for embedded sensor telemetry. The following Python 3 script reads the Pi 5's CPU temperature and streams it over /dev/serial0. This code targets the Pi 5 on Bookworm and includes robust error handling for serial port locks.

Prerequisite: Install the pyserial library via sudo apt install python3-serial.

import serial
import time
import os
import sys

# Pin/Port Definition for Raspberry Pi 5 UART
# /dev/serial0 is the stable symlink to the primary UART (ttyS0 on Pi 5)
SERIAL_PORT = '/dev/serial0'
BAUD_RATE = 115200

def get_cpu_temp():
    """Fetches CPU temp using vcgencmd. Returns string or 'Error'."""
    try:
        temp = os.popen('vcgencmd measure_temp').readline()
        return temp.replace('temp=', '').replace("'C\n", '')
    except Exception:
        return 'Sensor_Error'

def main():
    # 1. Initialize Serial Connection with Error Handling
    try:
        ser = serial.Serial(
            port=SERIAL_PORT,
            baudrate=BAUD_RATE,
            parity=serial.PARITY_NONE,
            stopbits=serial.STOPBITS_ONE,
            bytesize=serial.EIGHTBITS,
            timeout=1
        )
        print(f'Successfully opened {SERIAL_PORT} at {BAUD_RATE} baud.')
    except serial.SerialException as e:
        print(f'FATAL: Could not open serial port. {e}')
        print('Fix: Ensure enable_uart=1 is in config.txt and stop serial-getty.')
        sys.exit(1)

    # 2. Telemetry Loop
    try:
        while True:
            temp = get_cpu_temp()
            uptime = time.time()
            # Format payload with newline for PuTTY terminal readability
            payload = f'[Pi5 Telemetry] CPU: {temp}C | Uptime: {uptime:.0f}s\r\n'
            ser.write(payload.encode('utf-8'))
            time.sleep(2)
    except KeyboardInterrupt:
        print('\nTelemetry stopped by user.')
    finally:
        # 3. Clean up port lock
        if 'ser' in locals() and ser.is_open:
            ser.close()
            print('Serial port closed cleanly.')

if __name__ == '__main__':
    main()

Troubleshooting: Exact PuTTY Error Strings and Fixes

When a connection fails, PuTTY throws specific error strings. Do not guess; match your exact error to the ranked causes below.

Error 1: 'Network error: Connection refused'

Protocol: SSH
Ranked Causes:

1. SSH daemon is disabled: Bookworm disables SSH by default for security. Fix: Create an empty file named ssh (no extension) in the root of the boot partition, or run sudo systemctl enable --now ssh if you have local access.
2. Wrong IP Address: The Pi pulled a new DHCP lease. Fix: Ping raspberrypi.local or check your router's ARP table.
3. Firewall Block: ufw or iptables is dropping port 22. Fix: Run sudo ufw allow 22/tcp.

Error 2: 'PuTTY Fatal Error: Disconnected: No supported authentication methods available (server sent: publickey)'

Protocol: SSH
Ranked Causes:

1. Password auth disabled: If you generated keys via Raspberry Pi Imager, password auth might be off. Fix: Edit /etc/ssh/sshd_config, set PasswordAuthentication yes, and restart SSH.
2. Missing Private Key: PuTTY is trying to use Pageant but the key isn't loaded. Fix: In PuTTY Configuration > Connection > SSH > Auth > Credentials, browse and select your .ppk private key file.

Error 3: 'Unable to open serial port' or 'Access denied' (Windows COM port)

Protocol: Serial UART
Ranked Causes:

1. Port locked by Linux OS: The Raspberry Pi OS runs a background service that ties up the UART for console login, conflicting with your Python script. Fix: Run sudo systemctl stop serial-getty@ttyS0.service and sudo systemctl disable serial-getty@ttyS0.service.
2. Windows COM port hijacked: Another program (like Cura, Arduino IDE, or a previous PuTTY instance) holds the COM port. Fix: Close all other serial software and physically unplug/replug the CP2102 adapter.
3. TX/RX Crossed Wrong: You connected TX to TX. Fix: Swap the jumper wires on GPIO 14 and 15.

Extending the Build: Logging and Automated Headless Setups

Once you have mastered the baseline PuTTY connection, you can extend the workflow for professional embedded development.

First Three Things to Check When a New Build Fails

Before tearing apart your hardware, run this mental checklist:

1. Verify the Boot Partition Path: Are you editing /boot/config.txt (Bullseye and older) or /boot/firmware/config.txt (Bookworm)? Editing the wrong one will silently fail to enable UART.
2. Verify Logic Levels: Measure the voltage between the adapter's TX pin and GND with a multimeter. It should read ~3.3V. If it reads 5V, disconnect immediately.
3. Verify Baud Rate Match: Ensure both the Pi Python script and PuTTY are hardcoded to 115200. A mismatch results in garbled 'wingdings' text in the terminal.

How to Simplify and Extend

• Simplify (Headless Auto-Connect): Use PuTTY's saved sessions feature. Configure your SSH or Serial settings, type a name in the 'Saved Sessions' box, and click Save. Next time, double-click the session name to connect instantly without re-entering COM ports or IPs.
• Extend (Persistent Logging): PuTTY can log all serial output to a text file. Go to Session > Logging, select 'All session output', and choose a file path. This is invaluable for capturing kernel panic logs that scroll by too fast to read during boot.
• Extend (Multiplexing): Once inside an SSH session, install tmux (sudo apt install tmux). This allows you to detach from the session, disconnect PuTTY, and let your Python telemetry script keep running in the background without dropping the process.

For deeper configuration parameters regarding the BCM2712 SoC UART multiplexing, refer to the official Raspberry Pi Configuration Documentation. Always verify your specific adapter's chipset drivers (CP210x vs PL2303) are up to date in Windows Device Manager to avoid silent COM port dropouts during long telemetry captures.