Building a Router with Raspberry Pi 5: The 2026 Dual-NIC Guide

Building a router with Raspberry Pi used to mean juggling USB-to-Ethernet dongles, fighting CPU-bound NAT bottlenecks, and accepting 400 Mbps as your hard ceiling. That era is over. The Raspberry Pi 5’s exposed PCIe 2.0 x1 lane allows us to bypass the USB 3.0 bus entirely, attaching dedicated MAC/PHY chips directly to the silicon. In 2026, a Pi-based router isn't just a travel toy; with the right hardware stack, it’s a legitimate, SQM-capable edge router for a home lab or small office.

This guide cuts through the forum noise. We are targeting the Raspberry Pi 5 (8GB variant) running OpenWrt, paired with a PCIe 2.5G Ethernet HAT. Below is the exact hardware stack, the UCI configuration script, and the debugging playbook for when the PCIe bus inevitably throws a tantrum.

The Decision Path: Which Hardware Stack Wins?

Before buying parts, let's terminate the "which board should I use" debate. Here is the decision matrix for Pi-based routing in 2026.

Parts List & Hardware Interface Mapping

This build relies on the Pi 5’s onboard Gigabit port acting as the WAN interface, while the PCIe HAT provides a 2.5G LAN interface. This avoids the need for a PCIe switch chip, keeping latency low and driver compatibility high.

Bill of Materials (BOM)

• Compute: Raspberry Pi 5 (8GB RAM)
• Networking: Waveshare 2.5G Ethernet HAT for Pi 5 (RTL8125BG chipset)
• Thermal: Raspberry Pi Active Cooler (Do not use passive heatsinks; NAT routing sustains high CPU die temps)
• Power: Official Raspberry Pi 27W USB-C PD Power Supply (Crucial: 15W supplies will brownout the PCIe lane under load)
• Storage: 32GB High-Endurance MicroSD (e.g., SanDisk High Endurance) or a 128GB NVMe via a separate M.2 HAT if you prefer booting from PCIe.

Hardware Interface & Pin Mapping

Unlike GPIO-based sensors, the HAT connects via the 16-pin FFC (Flexible Flat Cable) PCIe connector and the standard 40-pin header for power and I2C EEPROM enumeration. Here is what is actually electrically active for this build:

Step-by-Step: Flashing and Configuring OpenWrt

We are targeting the Raspberry Pi 5 8GB board variant. Download the latest stable OpenWrt release (24.x or newer) specifically built for the rpi-5 target from the OpenWrt Table of Hardware. Flash the .img.gz to your SD card using Raspberry Pi Imager or balenaEtcher.

1. Enable PCIe Gen 2 and Boot

Out of the box, the Pi 5 limits PCIe to Gen 2. The RTL8125BG is a Gen 2 device, so this is fine, but we must ensure the bus is enabled. Edit the config.txt file on the boot partition and add:

dtparam=pciex1
# Optional: Force Gen 3 if using a Gen 3 capable HAT, but Gen 2 is stable for RTL8125BG
# dtparam=pciex1_gen=3

2. Apply the UCI Network Configuration

Once booted and connected via SSH (ssh root@192.168.1.1), run this complete bash script. It uses OpenWrt’s Unified Configuration Interface (UCI) to map the onboard port to WAN, the PCIe HAT to LAN, and enables SQM to eliminate bufferbloat.

#!/bin/sh
# OpenWrt UCI Configuration for Raspberry Pi 5 Router
# Target: Raspberry Pi 5 (8GB) + Waveshare 2.5G PCIe HAT
set -e

# Error handling wrapper
run_uci() {
    if ! uci "$@"; then
        echo "ERROR: UCI command failed: $*" >&2
        exit 1
    fi
}

echo "Mapping interfaces..."
# 1. Define WAN (Onboard 1G Ethernet)
run_uci delete network.wan 2>/dev/null || true
run_uci set network.wan=device
run_uci set network.wan.name='eth0' 
run_uci set network.wan.proto='dhcp'

# 2. Define LAN (PCIe 2.5G HAT)
run_uci delete network.lan 2>/dev/null || true
run_uci set network.lan=device
run_uci set network.lan.name='eth1' 
run_uci set network.lan.proto='static'
run_uci set network.lan.ipaddr='192.168.1.1'
run_uci set network.lan.netmask='255.255.255.0'

# 3. Configure Firewall Zones
run_uci set firewall.@zone[0].name='lan'
run_uci set firewall.@zone[0].network='lan'
run_uci set firewall.@zone[1].name='wan'
run_uci set firewall.@zone[1].network='wan'

# 4. Enable SQM (Cake) for bufferbloat mitigation
# Note: Install sqm-scripts first via: opkg update && opkg install sqm-scripts
run_uci set sqm.eth0=sqm
run_uci set sqm.eth0.enabled='1'
run_uci set sqm.eth0.interface='wan'
run_uci set sqm.eth0.download='900000' # Set to 90% of your ISP download speed (Kbps)
run_uci set sqm.eth0.upload='900000'   # Set to 90% of your ISP upload speed (Kbps)
run_uci set sqm.eth0.qdisc='cake'
run_uci set sqm.eth0.script='piece_of_cake.qos'

# 5. Commit and restart services
run_uci commit network
run_uci commit firewall
run_uci commit sqm

/etc/init.d/network restart
/etc/init.d/firewall restart
/etc/init.d/sqm restart

echo "Configuration applied. Router with Raspberry Pi 5 is live."

Debugging: PCIe Link Failures & Interface Drops

The Pi 5’s PCIe implementation is notoriously sensitive to power delivery and Active State Power Management (ASPM). If your router drops packets under load or the WAN interface fails to pull an IP, you are likely hitting a bus-level hardware fault, not a software bug.

The Exact Error String

If you run dmesg -w while pushing a 900 Mbps iperf3 test and see this exact string, your PCIe bus is collapsing:

pcieport 0000:00:00.0: PCIe Bus Error: severity=Corrected, type=Data Link Layer, id=0000
Followed by: netifd: Interface 'wan' has link connectivity loss

The First Three Things to Check

1. Verify the Power Supply (The 27W Rule): The RTL8125BG chip draws significant current during burst traffic. If you are using a third-party 15W USB-C charger, the Pi 5 will silently throttle the PCIe lane voltage to protect the SoC, causing Data Link Layer errors. Fix: Use only the official 27W Raspberry Pi PD supply.
2. Disable ASPM in config.txt: The Pi 5 firmware attempts to put the PCIe bus to sleep during micro-idle states, which the RTL8125BG driver often fails to wake from fast enough. Fix: Add dtparam=pciex1_aspm=off to your config.txt and reboot.
3. Check FFC Cable Seating and Bend Radius: The 16-pin FFC cable is fragile. If it is bent at a sharp 90-degree angle to clear the Active Cooler fan, the impedance of the TX/RX differential pairs changes, causing CRC errors at 2.5G speeds. Fix: Ensure a smooth, looping bend radius of at least 15mm.

Extending or Simplifying the Build

Once you have a stable baseline, you can scale this project up or down depending on your deployment environment.

How to Extend (The Home Lab Upgrade)

• Add NVMe Boot: MicroSD cards will corrupt under heavy syslog and DHCP lease logging. Swap the SD card for a Pineberry Pi HatDrive Bottom and a 128GB NVMe drive. You will need to use a longer FFC cable to daisy-chain the 2.5G HAT on top.
• Implement VLAN Trunking: The RTL8125BG supports 802.1Q. You can use a managed switch to trunk multiple VLANs (IoT, Guest, Lab) into the single 2.5G eth1 port, turning the Pi into a "router on a stick" and freeing up physical ports.
• Add AdGuard Home: With 8GB of RAM, you have plenty of headroom to run Docker (via luci-app-dockerman) and deploy AdGuard Home for network-wide DNS sinkholing without impacting NAT throughput.

How to Simplify (The Travel Router Downgrade)

If you are building a portable router for hotel WiFi or van life, the Pi 5 is overkill and draws too much power from a 12V LiFePO4 battery bank.

• Downgrade to Pi Zero 2 W: Flash OpenWrt onto a Pi Zero 2 W.
• Use USB Tethering as WAN: Plug an Android phone into the USB port and use the usbmodem interface for WAN.
• Use Onboard WiFi as LAN: Configure the Pi Zero's onboard 2.4GHz radio as an AP. This drops your throughput to ~70 Mbps, but reduces power draw to under 2W, making it ideal for solar/battery setups.

For deeper dives into ARM-based networking, consult the official Raspberry Pi PCIe documentation to stay updated on firmware-level bus tuning. Building a router with Raspberry Pi 5 is no longer a compromise; with the right PCIe HAT and strict power delivery, it is a highly capable edge device that punches well above its $80 price tag.