User Tools

Site Tools


docs:guide-user:network:wan:smartphone.usb.tethering

Smartphone USB tethering

Introduction

USB tethering is used to connect your OpenWrt Router to the Internet by using the your smartphone. It's more convenient and has better performance (lower latency) than turning your smartphone into an access point and using that. It also is less of a CPU load on your phone, charges your phone, and allows you the flexibility of doing things with your OpenWrt router that you cannot do with your phone like connecting multiple devices with ease, both wireless and wired, to each other and to the internet. In order to maximize performance, you should turn your tethered phone Wi-Fi and Bluetooth off.

  • :!: USB tethering is known to be problematic on iOS 14 devices.
  • :!: Connecting your whole network to the Internet using the Smartphone might consume your monthly traffic quota very fast.
  • Follow USB reverse tethering to share the internet from router to the smartphone over USB.

Instructions

1. Installation

For the easiest installation, have a wired upstream internet connection to boot-strap this process. You will need: the router, your tethering phone, necessary cables, a laptop and an upstream internet connection via Ethernet for initial setup. Instead of a wired upstream connection to plug into the router WAN port, is also possible to download necessary packages below, through your laptop while tethered to your phone, the same way you can get the OpenWrt distribution for your router.

Provide USB tethering support for Android 8/10 with RNDIS:

opkg update
opkg install kmod-usb-net-rndis

Extra steps depending on USB type and drivers for your router:

opkg update
opkg install kmod-nls-base kmod-usb-core kmod-usb-net kmod-usb-net-cdc-ether kmod-usb2

Additional steps for iOS devices:

opkg update
opkg install kmod-usb-net-ipheth usbmuxd libimobiledevice usbutils
 
# Call usbmuxd
usbmuxd -v
 
# Add usbmuxd to autostart
sed -i -e "\$i usbmuxd" /etc/rc.local

2. Smartphone

Connect the smartphone to the USB port of the router with the USB cable, and then enable USB Tethering from the Android settings. Turn on the phone's Developer Options [Find the Build information in the About Phone menu, and tap rapidly 7 x]. There is a Default USB Configuration: USB Tethering option. The phone will now immediately turn on USB Tethering mode when plugged into a configured router [or laptop], without further commands. However, it is necessary to remove the screen lock on the phone. A locked phone will not start USB Tethering by itself.

For IPhones, you may have to disable and re-enable the Personal Hotspot/Allow Others to Join setting on the IPhone to force the OpenWrt DHCP client to get an IP address from the eth1 IPhone interface. Disabling and re-enabling the Personal Hotspot/Allow Others to Join setting on the IPhone is also required if you disconnect the IPhone from the OpenWrt USB port and re-coonect it later, unless you cache Trust records (see watchdog section and/or LeJeko github link below).

3.a Command-line interface

On the router, enter:

# Enable tethering
uci set network.wan.ifname="usb0"
uci commit network
/etc/init.d/network restart

For IPhones, replace the interface name usb* with eth* depending on router.

It should be all working at this point. To activate wireless connections to the router, go to Network, Wireless and set then enable the interfaces.

3.b Web interface

Go to Network, Interfaces. Create a new interface called TetheringWAN, and bind to it the new *usb0* network device (or for some cases '*eth1*, check what the log is showing in your case), set the protocol to DHCP client mode, and under the Firewall Settings tab, place it into the WAN zone. Save changes.

See the following screenshots.

First page of the Create Interface wizard.

Firewall tab of the Create Interface Wizard. Very important to set it as WAN.

And the end result in the Interfaces page.

After committing the changes the new TetheringWAN should be activated. Otherwise, restart it with the buttons you find in the Interface page of LuCI web interface.

Troubleshooting

If all went well, you should be able to see something like the following in the kernel log

  • click on Status and then on Kernel Log to see this log from the LuCi web interface
  • or write “dmesg” in the console over SSH.
[  168.599245] usb 1-1: new high-speed USB device number 2 using orion-ehci
[  175.997290] usb 1-1: USB disconnect, device number 2
[  176.449246] usb 1-1: new high-speed USB device number 3 using orion-ehci
[  176.654650] rndis_host 1-1:1.0 usb0: register 'rndis_host' at usb-f1050000.ehci-1, RNDIS device, ee:da:c0:50:ff:44

Note how the last line tells us that this new “RNDIS device” was bound to interface usb0.

:!: The above messages will not be shown with IPhone tethering.

Extras

References

Restart tethering on connection failure

If your tethering connection fails every so often, and:

  • You see in your client devices that there is no internet connectivity, and
  • Your phone is still showing a good 4G/tower connection, and tethering enabled, and
  • Simply unplugging your tethering phone and plugging it back into the router fixes the problem

Then it might be fixed with the following solution:

# Install packages
opkg update
opkg install hub-ctrl
 
# Save connectivity checking script
cat << "EOF" > /root/wan-watchdog.sh
#!/bin/sh
 
# Fetch WAN gateway
. /lib/functions/network.sh
network_flush_cache
network_find_wan NET_IF
network_get_gateway NET_GW "${NET_IF}"
 
# Check WAN connectivity
TRIES="0"
while [ "${TRIES}" -lt 5 ]
do
    if ping -w 3 "${NET_GW}" &> /dev/null
    then exit 0
    else let TRIES++
    fi
done
 
# Restart network
/etc/init.d/network stop
hub-ctrl -h 0 -P 1 -p 0
sleep 1
hub-ctrl -h 0 -P 1 -p 1
/etc/init.d/network start
EOF
chmod +x /root/wan-watchdog.sh
 
# Add cron job
cat << "EOF" >> /etc/crontabs/root
* * * * * /root/wan-watchdog.sh
EOF

Every 1 minute, the script will be run, ping WAN gateway, and if there are 5 consecutive failures, it will stop the network, power off the USB hub (which will terminate tethering on the phone), power it back on, then restart the network. This solution is much faster than restarting the whole router.

iPhone automatic watchdog

Once you set up iPhone tethering as per above, you'll notice several issues:

  • usbmuxd needs to be started manually after every reboot
  • On iPhone, you need to set up trust again after every router reboot
  • If your cellular signal is weak, tethering will disconnect every now and then and you'll need to unplug and reconnect USB cable

Save following script to some location that survives reboot, e.g. /etc/lockdown, and execute it after every reboot. It should keep tethering up and running as long as iPhone is connected.

# Save watchdog script
mkdir -p /etc/lockdown
cat << "EOF" > /etc/lockdown/watchdog.sh
#!/bin/sh
# A small script to make life with iPhone tethering less cumbersome on OpenWrt
# Petr Vyskocil, Apr 2020
# Public domain
 
# After you successfully allow iPhone tethering, copy files with name like
# /var/lib/lockdown/12345678-9ABCDEF012345678.plist to /etc/lockdown/locks.
# That way, you won't have to set up trust again after router reboots.
if [ -e /etc/lockdown/locks ]
then
    mkdir -p /var/lib/lockdown
    cp -f /etc/lockdown/locks/* /var/lib/lockdown/
fi
 
# lockdown records restored, now we can launch usbmuxd. Don't launch it sooner!
usbmuxd
 
# We are up and running now. But unfortunately if your carrier signal is weak, iPhone will
# drop connection from time to time and you'd have to unplug and replug USB cable to start tethering
# again. Script below automates that activity.
 
# First wait a bit - we just brought the interface up by usbmuxd
sleep 20
 
# If we see iPhone ethernet interface, try to ping iPhone router's address (172.20.10.1).
# When the ping is unsuccessful, rebind iPhone ethernet USB driver and wait for things to settle down
while :
do
    for i in /sys/bus/usb/drivers/ipheth/*:*
    do
        test -e "${i}" || continue
        ping -w 3 172.20.10.1 &> /dev/null
        if [ "${?}" -ne 0 ]; then
            echo "${i##*/}" > "${i%/*}"/unbind
            echo "${i##*/}" > "${i%/*}"/bind
            sleep 20
        fi
    done
    sleep 1
done
EOF
chmod +x /etc/lockdown/watchdog.sh
 
# Add watchdog script to autostart
sed -i -e "\$i (/etc/lockdown/watchdog.sh) &" /etc/rc.local

Work around tethering-activation issue on rooted phones

If your Android phone does not seem to detect that there is something attached to the USB port and refuses to switch to USB tethering, you might want to install DriveDroid and try to enable various methods of using USB guest for its own functionality. This does solve that issue in my phone (which is running LineageOS nightly and sometimes after I update does show this issue). You will probably need root (administrator) access on your device though.

OpenWrt build issues

If you don't see something like the sample kernel log output in your device's log then your device might be lacking proper USB drivers (drivers to operate the USB controllers at all). Check Installing USB drivers and report the issue in a bug report or in the mailing list, as devices should have base USB drivers integrated and working already.

For other issues it might be worth it to check the article about using RNDIS dongles as Android tethering is using the same protocol.

This website uses cookies. By using the website, you agree with storing cookies on your computer. Also you acknowledge that you have read and understand our Privacy Policy. If you do not agree leave the website.More information about cookies
docs/guide-user/network/wan/smartphone.usb.tethering.txt · Last modified: 2020/09/26 17:07 by vgaetera