IPv4 DHCP

WendyOS assigns an IPv4 address to usb0 through DHCP. There are two modes depending on how the host is set up.

Modes

Mode 1 — DHCP Client (Default)

In the default build configuration (WENDYOS_USB_NET_MODE=dhcp), WendyOS acts as a DHCP client on usb0. The host is expected to run a DHCP server on its NCM adapter. The most common way to do this on Linux is to activate a NetworkManager "shared" connection on the host-side interface, which starts a dnsmasq instance automatically and assigns 10.42.0.1/24 to the host.

The NetworkManager connection profile on the device (/etc/NetworkManager/system-connections/usb-gadget.nmconnection) sets:

[ipv4]
method=@USB_NET_MODE@     # replaced at build time with "dhcp"
route-metric=700          # high metric, usb0 is the fallback route

The high route metric (700) means that Ethernet (100) and WiFi (300) are always preferred as the default route when available. usb0 only becomes the default route if no other interface is up.

DHCP timeout is set to 300 seconds (ipv4.dhcp-timeout=300) to handle hosts that activate sharing after the device has already booted.

Mode 2 — On-Device DHCP Server (Optional)

An alternative configuration ships an on-device dnsmasq instance that serves DHCP directly on usb0. This is provided by the gadget-network-config Yocto recipe.

Configuration file: /etc/dnsmasq.d/usb-gadget-dnsmasq.conf

interface=usb0
bind-interfaces

dhcp-range=10.42.0.2,10.42.0.5,12h

dhcp-option=3,10.42.0.1    # gateway = device itself
dhcp-option=6,8.8.8.8      # DNS

quiet-dhcp
quiet-dhcp6
quiet-ra

The systemd service gadget-dnsmasq.service starts after gadget-setup.service and runs dnsmasq with this config. It is type simple and restarts on failure.

In this mode the host receives an address from 10.42.0.2–10.42.0.5 and the device is the gateway at 10.42.0.1. This requires the device to be configured with a static 10.42.0.1/24 address on usb0, which is done by setting WENDYOS_USB_NET_MODE=shared at build time.

NetworkManager Configuration Files

Host-Side Setup

Mode 1 host setup — NetworkManager shared (recommended)

Run on the host once the NCM interface (enxXXXXXXXXXXXX) appears:

nmcli connection add type ethernet ifname <enxXXX> ipv4.method shared

This activates a built-in dnsmasq instance, assigns 10.42.0.1/24 to the host, and enables NAT so the device can reach the internet through the host.

Alternative — link-local addressing

The setup-host-usb-link-local.sh script in the wendyos repository configures the host for link-local addressing instead. This is useful when internet sharing is not needed. It supports both NetworkManager and systemd-networkd:

NetworkManager — installs /etc/NetworkManager/system-connections/wendyos-usb.nmconnection:

[connection]
type=ethernet
autoconnect-priority=100
match.driver=cdc_ncm;cdc_ether

[ipv4]
method=link-local

systemd-networkd — installs /etc/systemd/network/80-wendyos-usb.network:

[Match]
Driver=cdc_ncm cdc_ether

[Network]
LinkLocalAddressing=ipv4

Verifying DHCP

# On the device — check address assigned to usb0
ip addr show usb0

# On the device — check NetworkManager state
nmcli connection show usb-gadget | grep -E "ipv4|IP4"

# On the device — watch DHCP exchange in journal
journalctl -u NetworkManager | grep -i "usb0\|dhcp"

# On the host — capture DHCP packets
sudo tcpdump -i enxXXXXXXXXXXXX port 67 or port 68 -vn

A successful DHCP exchange looks like:

DISCOVER → (device to host, broadcast)
         ← OFFER    (host to device)
REQUEST  → (device to host)
         ← ACK      (host to device)