How To Make Ethernet Work On Android Over OTG

Desember 30, 2022Desember 22, 2022 falma.u99 android, ethernet

There is a long list of Ethernet related questions but none has a comprehensive answer covering all aspects. I’m generalizing your question in order to share my knowledge on this.

This is what you need to do in order to make Ethernet work on Android:

* Make sure OTG support is available
* Kernel must be built with Ethernet (and USB Ethernet) support
* Handle USB mode switch and kernel module loading (if applicable)
* Make Android framework do network configuration or do it manually

Note: Everything described below requires a rooted device, or at least the one with unlocked bootloader.
You should be familiar with commandline interface.

OTG SUPPORT
Your device must be able to operate in USB host mode.EthernetService is started only if device supports feature USB host (android.hardware.usb.host) or Ethernet (android.hardware.ethernet). You may also need to use a powered USB hub if Android’s USB power supply is not enough for connected device. Related question:

KERNEL CONFIGURATION
In order to use Ethernet over USB (adapters or modem-like devices) kernel must be built with CONFIG_USB_USBNET and other configurations like USB_NET_CDCETHER, USB_NET_HUAWEI_CDC_NCM, USB_NET_CDC_MBIM etc. depending on the type of connected device and the protocol it talks. Related questions:

USB MODE SWITCH AND LOADING KERNEL MODULE
Many USB network devices are multi-mode or flip flop devices. They appear as USB Mass Storage device (also called ZeroCD mode) when inserted and need to be switched to Ethernet/PPP mode. USB_ModeSwitch is a Linux tool commonly used for this purpose. See some details here how it works. You need to build this tool for your device, or may download this binary for aarch64. Get device database from here.

In order to automatically switch mode whenever the device is connected to Android, we need to listen to kernel USB uevents, either through hotplug helper or a userspace daemon (like udev on Linux and ueventd on Android). Additionally the kernel module can also be loaded/unloaded automatically. I’m defining an init service here to achieve this, you can do it manually too.

Note: There is an Android app PPP Widget (by the developer of USB_ModeSwitch, I have no affiliation) which handles mode switching automatically and needs “no kernel driver modules, the ‘driver’ implementation is based on the Android USB host API”. You might be interested in that too.

# /system/etc/init/custom.rc
# kernel hotplug or uevent daemon service
service cust.udevd /system/sbin/busybox uevent /system/sbin/udev.sh
seclabel u:r:magisk:s disabled
writepid /dev/cpuset/system-background/tasks
# set kernel hotplug helper or start uevent daemon on boot
on property:sys.boot_completed= #write /proc/sys/kernel/hotplug /system/sbin/udev.sh
start cust.udevd
* In case of hotplug you need to define custom SELinux policies to let kernel make changes (see this answer for details).

#!/system/bin/sh
# /system/sbin/udev.sh script is executed from kernel hotplug or uevent daemon
# set PATH where you placed binaries
export PATH=/system/bin
# save log
exec >>/dev/udev.log 2>&1
# don’t execute multiple instances
exec 200<>/dev/udev.lock
flock VID=”12d1″ # USB vendor ID of a Huawei devcie
PID_UMS=”1f01″ # product ID in ZeroCD mode
PID_ETH=”14db” # product ID in Ethernet mode
MODULE=”cdc_ether” # kernel module for USB Ethernet
IFACE=”usb0″ # Ethernet interface name
matches() return return 0

# check if a new USB device is added or removed
if [ “$SUBSYSTEM” = “usb” ]
then
# check if a USB device is added, then match VID and PID for mode switching
# also device must belong to UMS class: /defined-class-codes#anchor_BaseClass08h
if [ “$ACTION” = “add” ] && echo “$PRODUCT” | grep -q “$VID/$PID_UMS/” && matches bInterfaceClass 08 && matches bInterfaceNumber then echo “Switching USB mode…” # USB mode switching of flip flop devices (USB modems, routers etc.) # usb_modeswitch_dispatcher needs /system/sbin/usb_modeswitch binary and configuration files in /etc # so you need to modify the hard-coded paths in source code as per your requirement usb_modeswitch_dispatcher –switch-mode “$(basename “$DEVPATH”)”
fi # match VID and PID for module loading
# modprobe should be built with the hard-coded path to where you place modules e.g. /system/lib
if echo “$PRODUCT” | grep -q “$VID/$PID_ETH/”
then if [ “$ACTION” = “add” ] && ! grep -q “^$MODULE ” /proc/modules then echo “Loading $MODULE module…” modprobe “$MODULE” elif [ “$ACTION” = “remove” ] && grep -q “^$MODULE ” /proc/modules then echo “Removing $MODULE module…” modprobe -r “$MODULE” fi
fi
fi
# on network interface event
if [ “$SUBSYSTEM” = “net” ] && [ “$INTERFACE” = “$IFACE” ]
then
if [ “$ACTION” = “add” ]
then echo “Starting cust.eth_config service…” #start cust.eth_config # uncomment if you want to do manual network configuration
fi if [ “$ACTION” = “remove” ]
then echo “Stopping cust.eth_config service…” #stop cust.eth_config # uncomment if you want to do manual network configuration
fi
fi
NETWORK CONFIGURATION
Android framework has a hard-coded name for Ethernet interface (default is eth0, eth1, …). Whenever an Ethernet interface appears, its name is matched with the hard-coded value. Renaming interface afterwards doesn’t work because only kernel provided interface name is tracked.

So you need to make this naming convention consistent between kernel and AOSP by modifying one of the both (if needed). Kernel provided name can be seen using ip tool (as in your case it’s usb0). Use dumpsys or de-compile /system/framework/framework-res.apk using apktool to see the AOSP value.

~$ dumpsys ethernet
…
Ethernet interface name filter: eth\d
…
As soon as an Ethernet interface appears, Android configures it automatically, NetworkMonitor validates the connectivity and ConnectivityService turns off WiFi and Mobile Data (if it’s ON). Other services and components involved in configuration include UsbHostManager, EthernetTracker, EthernetNetworkFactory, IpClient.eth0, DhcpClient, DnsManager and Netd.

EthernetService was added in Android 5. Before that AOSP was patched to make Ethernet work (e.g. see this and this). Still stock Android provides no GUI settings for Ethernet, but some custom ROM developers and OEMs do (e.g. see this). EthernetManager class which is used to set and save manual IP configuration (to /data/misc/ethernet/ipconfig.txt) is hidden. Default is to use a hard-coded configuration (see using dumpsys ethernet under “IP Configurations:”) or DHCP provided configuration.

MANUAL CONFIGURATION

You might want to do manual network configuration e.g. if:

* Android framework doesn’t configure the Ethernet interface (on older devices or due to interface name inconsistency).
* You want to set static IP address or different DNS server.
* You want to use Ethernet along with WiFi or Mobile Data, or want to share internet among any of these.

But in this case Android’s Java network stack remains down, so some apps depending on Android APIs may not behave normally. For related details see Connecting to WiFi via ADB Shell.

# /system/etc/init/custom.rc
# Ethernet IP configuration service
service cust.eth_config /system/sbin/eth_config.sh
seclabel u:r:magisk:s disabled
writepid /dev/cpuset/system-background/tasks
# clear routing and DNS
on property:init.svc.cust.eth_config=stopped
exec u:r:magisk:s0 — /system/sbin/eth_config.sh stop
#!/system/bin/sh
# /system/sbin/eth_config.sh script is executed from eth_config init service
# set PATH where you placed binaries
export PATH=/system/bin
IFACE=usb # Ethernet interface name
DIR=/data/local/tmp/ethernet # temporary directory
mkdir -p $DIR
# save log
exec >$DIR/eth_config.log 2>&1
if [ “$1” = stop ]
then
echo “Clearing configuration…”
ip ru del lookup main
ip r f table main
ndc resolver setnetdns 0 ” 0.0.0. exit
fi
# destroy set network if any
ndc network default set 0
# turn WiFi and Mobile Data off
svc wifi disable
svc data disable
# set interfaces up
ip link set dev lo up
ip link set dev $IFACE up
# Android doesn’t use main table by default
ip rule add lookup main
# set IP, route and DNS manually here
# or add any other IP/routing configuration
# or run a minimal DHCP client as follows
# create ‘udhcpc’ script
<$DIR/udhcpc_default.script #!/system/bin/sh case $1 in bound|renew) echo "Setting IP address, gateway route and DNS for $interface..." ip address f dev $interface ip route f table main ip address add $ip/$mask dev $interface ip route add default via $router dev $interface ndc resolver setnetdns 0 '' $dns ;; *) echo "Ignoring $1" ;; esac SCRIPT # start DHCP client to obtain IP from server chmod 0755 $DIR/udhcpc_default.script exec busybox udhcpc -v -f -i $IFACE -s $DIR/udhcpc_default.script Do not forget to set proper permissions on .rc file and shell scripts. Once setup, Ethernet works as soon as you connect USB adapter.