OpenWrt Setup on Raspberry Pi Zero 2W with USB-Ethernet

Raspberry Pi Zero 2W with OpenWrt requires manual installation of the RTL8152B driver through the kmod-usb-net-rtl8152 package, as this module is often missing from the base firmware. You also need to check the network interface configuration and, if necessary, perform initial setup via UART to activate the network.

Table of Contents

• Main Problems and Their Solutions
• Installing the RTL8152B Driver
• Network Interface Configuration
• Alternative Connection Methods
• Testing and Diagnostics
• Common Errors and Their Solutions

Main Problems and Their Solutions

The main issue is that the driver for the RTL8152B chip is not always included in the base OpenWrt firmware for the Raspberry Pi Zero 2W. According to OpenWrt forum research, many users have encountered the same situation where the USB-Ethernet adapter is not automatically recognized.

Problem causes:

• Missing kmod-usb-net-rtl8152 kernel module in the base build
• Version conflicts between kernel and driver
• USB port power issues on the Raspberry Pi Zero 2W
• Need for manual network interface activation

The solution involves manually installing the required driver and then configuring the network interface. As noted in one forum, “USB ports are recognized, but the Ethernet port doesn’t work” without installing the correct module.

Installing the RTL8152B Driver

Method 1: Via Command Line (opkg)

1. Connect to the Raspberry Pi Zero 2W via console (UART or USB-OTG)
2. Update the package list:
   bash

   opkg update
   

3. Install the required modules:
   bash

   opkg install kmod-usb-net-rtl8152
   opkg install kmod-mii
   opkg install kmod-crypto-sha256
   

Important: Additional dependencies may sometimes be required. As noted in the OpenWrt documentation, the kmod-usb-net and kmod-mii packages may be needed for RTL8152B to function.

Method 2: Through LuCI Web Interface

1. Access the LuCI interface at the address (if available)
2. Navigate: System → Packages
3. Click “Install package” and install:
   • kmod-usb-net-rtl8152.ipk
   • kmod-mii.ipk
4. Reboot the device after installation

Method 3: Manual Installation via USB Drive

If the network is unavailable, use this method:

1. Download the required packages on another computer from the official OpenWrt repository
2. Copy them to a USB drive
3. Connect the drive to the Raspberry Pi
4. Install the packages manually:
   bash

   opkg install /mnt/sda1/kmod-usb-net-rtl8152_*.ipk
   

Network Interface Configuration

After installing the driver, you need to configure the network interface:

1. Device Recognition Check

Run the command to check if the USB adapter is recognized:

lsusb

You should see output similar to:

Bus 001 Device 005: ID 0bda:8152 Realtek Semiconductor Corp. RTL8152 Fast Ethernet Adapter

2. Network Interface Check

Check which interfaces were created:

ifconfig -a

An interface such as eth1 or usb0 should appear.

3. Interface Configuration in UCI

Add configuration for the new interface:

uci set network.usb=interface
uci set network.usb.proto='dhcp'
uci set network.usb.type='bridge'
uci commit network

4. Network Restart

/etc/init.d/network restart

If the interface didn’t appear automatically, you can create it manually:

ifconfig eth1 up
udhcpc -i eth1

Alternative Connection Methods

Connection via UART (for initial setup)

If Ethernet isn’t working, set up access via UART:

1. Connect to the Raspberry Pi GPIO pins:
   • TX (GPIO 14) → Adapter RX
   • RX (GPIO 15) → Adapter TX
   • GND → GND
2. Use a terminal program (PuTTY, minicom, screen)
3. Baud rate: 115200, 8N1
4. Login: root, password: empty

Temporary Access via USB-OTG

The Raspberry Pi Zero 2W supports USB On-The-Go:

1. Connect the Pi Zero 2W to a computer via USB cable
2. A RNDIS network interface should appear on the computer
3. Use the IP address 192.168.7.1 to access the Pi

Testing and Diagnostics

Diagnostic Commands:

1. Module Loading Check:

   bash

   lsmod | grep rtl8152
   

2. Kernel Log Check:

   bash

   dmesg | grep -i rtl8152
   

3. Network Status Check:

   bash

   /etc/init.d/network status
   

4. Routing Table Check:

   bash

   route -n
   

Possible Diagnostic Results:

• Module not loaded: lsmod doesn’t show rtl8152
• Driver error: errors in dmesg
• Interface conflict: multiple interfaces of the same type

Common Errors and Their Solutions

Error 1: “Unknown package ‘kmod-usb-net-rtl8152’”

Solution: Ensure you’re using the correct package architecture for the Raspberry Pi Zero 2W (arm_arm1176jzf-s_vfp). Check kernel version compatibility.

Error 2: USB adapter is recognized but not working

Solution: Try disabling USB power saving:

echo 'max_suspend=-1' > /sys/bus/usb/devices/1-1/power/autosuspend_delay_ms

Error 3: No response when connecting Ethernet

Solution: Check USB port power. The Raspberry Pi Zero 2W may not provide sufficient current for some USB-Ethernet hubs. Try using external power.

Error 4: Interface not created after driver installation

Solution: Check driver version compatibility with the kernel. Sometimes you need to manually rebuild the module or use an older/newer version of OpenWrt.

Sources

1. Installing kmod-usb-net-8152 on a RPi Zero - OpenWrt Forum
2. Realtek RTL8152B drivers for Pi Zero W - Raspberry Pi Forums
3. USB-ethernet adapter not working on OpenWrt - OpenWrt Forum
4. Raspberry Pi + OpenWrt, via USB On-The-Go
5. Configuring a Raspberry Pi Zero with USB Ethernet and OpenWRT
6. Rpi 4 Ethernet Hat via GPIO - OpenWrt Forum
7. OpenWrt on Raspberry Pi 4 (and CM4) – WebIT Tech Blog

Conclusion

To successfully set up an RTL8152B USB-Ethernet hub on a Raspberry Pi Zero 2W with OpenWrt, you need to:

1. Install the kmod-usb-net-rtl8152 driver via opkg or the LuCI interface
2. Check device recognition with the lsusb command
3. Configure the network interface in the UCI configuration
4. Restart the network to apply changes
5. Use UART if necessary for initial setup

If standard methods don’t work, try alternative approaches: temporary connection via USB-OTG, checking USB port power, or using an external power source. Always check kernel and driver version compatibility, as this is a common cause of RTL8152B issues on OpenWrt.