Fixing USB Portable Wi-Fi Detection Issues on ImmortalWrt

Background

While using ImmortalWrt on an ARM64 router, I encountered an issue where a USB portable Wi-Fi / cellular modem was not recognized correctly.
After plugging in the device, no network interface appeared, and common diagnostic tools such as lsusb were not available by default.

This post documents how I identified the problem, diagnosed the USB device manually, and finally made the device usable by installing missing USB libraries and drivers — even when custom package feeds were incomplete.

Problem Description

After connecting the USB Wi-Fi device:

No new network interface appeared (wwan, usb0, etc.)
lsusb was unavailable because usbutils was not installed
Attempting to install related tools failed:

opkg install usbutils
opkg install usb-modeswitch

Both commands resulted in:

Unknown package 'xxx'

This indicated that ImmortalWrt does not ship with certain USB utilities and drivers by default, and the configured opkg feeds did not include them either.

Step 1: Verifying USB Device Presence Without `lsusb`

Even without lsusb, Linux still exposes USB devices via sysfs.

I checked whether the kernel could see the USB device:

cat /sys/bus/usb/devices/1-1/idVendor
cat /sys/bus/usb/devices/1-1/idProduct

Output:

idVendor  = 19d2
idProduct = 0581

This confirmed that:

The USB device was detected at the kernel level
Vendor ID 19d2 corresponds to ZTE, a common manufacturer of USB cellular modems

So the problem was not hardware-related, but rather missing user-space support.

Step 2: Identifying the System Architecture

Since installing the wrong .ipk package can fail silently, I verified the router’s architecture:

opkg print-architecture

Output:

arch all 1
arch noarch 1
arch aarch64_generic 10
arch aarch64_cortex-a53 15

This confirmed that the router is ARM64 (aarch64), Cortex-A53.

Step 3: Manually Downloading `.ipk` Packages

Because the configured feeds did not contain the required packages, I manually downloaded the correct .ipk files for aarch64_cortex-a53, including:

usb-modeswitch
libusb-1.0
USB core support libraries

Example:

wget https://<mirror>/usb-modeswitch_2017-12-19-f40f84c2-1_aarch64_cortex-a53.ipk

However, installing usb-modeswitch initially failed with dependency errors:

cannot find dependency libusb-1.0

This revealed a key insight:

The real issue was missing USB dependency libraries, not usb-modeswitch itself.

Step 4: Installing USB Core Libraries First

The correct installation order mattered. I installed the USB libraries first:

opkg install libusb-1.0_*.ipk
opkg install usb-modeswitch_*.ipk

After resolving dependencies manually, the installation succeeded.

Step 5: Device Successfully Recognized

Once the USB stack was complete:

The device switched out of storage mode
A network interface appeared (e.g. wwan0)
The modem could now be configured normally in Network → Interfaces

At this point, ImmortalWrt finally recognized the USB portable Wi-Fi device correctly.

Key Takeaways

ImmortalWrt is minimal by design
Many USB utilities and drivers are not included by default.
lsusb is optional, sysfs is not
/sys/bus/usb/devices/ is a reliable way to inspect USB devices.
Custom feeds may lack critical dependencies
Even if a package exists, its required libraries may not.
Manual .ipk installation is sometimes unavoidable
Especially on embedded systems with restricted or customized feeds.
Correct architecture selection is critical
Installing mismatched .ipk files leads to confusing errors.

Conclusion

The USB Wi-Fi device was never “broken”.
The real issue was that ImmortalWrt lacked the necessary USB libraries and mode-switching support, and the custom package source did not provide them.

By manually identifying the architecture, installing missing USB dependencies, and then adding usb-modeswitch, the device was finally detected and usable.

If you’re running ImmortalWrt on ARM devices and your USB modem isn’t recognized — check your USB libraries first.