How to make Ethernet work on Android over OTG?

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:

• Is there a definite way to know if my phone supports USB-OTG or not?

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:

• Where kernel modules are installed?


• Add a driver to kernel without flashing a new kernel


• Load an unsigned Kernel Module to signature enforcing Kernel

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:s0


 disabled


 writepid /dev/cpuset/system-background/tasks



# set kernel hotplug helper or start uevent daemon on boot

on property:sys.boot_completed=1


 #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 200



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() {



 [ -e "/sys/$DEVPATH/$1" ] || return 1


 [ "$(cat "/sys/$DEVPATH/$1")" = "$2" ] || return 1


 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: https://www.usb.org/defined-class-codes#anchor_BaseClass08h


 if [ "$ACTION" = "add" ] && echo "$PRODUCT" | grep -q "$VID/$PID_UMS/" &&


  matches bInterfaceClass 08 && matches bInterfaceNumber 00


 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:s0


 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=usb0

  # 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.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

<<-'SCRIPT' cat >$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.