WendyOS Networking Overview

WendyOS provides a self-contained networking stack designed for USB-tethered connectivity between a device (Raspberry Pi, Jetson, or other supported hardware) and a host computer. When you plug a WendyOS device into a host via USB-C, the device presents a composite USB gadget that includes both a network interface and a serial console. No drivers, no pairing, no manual configuration — the device advertises itself over mDNS and the wendy-agent can discover and connect to it immediately.

Architecture

WendyOS device                          Host computer
───────────────────────────────         ───────────────────────────────
  usb0 (NCM gadget interface)  ←USB→    enxXXXXXXXXXXXX (CDC NCM)
  IPv4: DHCP client (or shared)         IPv4: 10.42.0.1/24 (NM shared)
  IPv6: link-local (auto)               IPv6: link-local (auto)
  mDNS: _wendyos._udp (Avahi)           mDNS discovery (avahi-browse/dns-sd)
  /dev/ttyGS0 (ACM serial)     ←USB→    /dev/ttyACM0 (serial console)

Components

Topics

• USB NCM Gadget — How the USB gadget is constructed and initialized
• MAC Address Generation — Deterministic MAC generation and IPv6 link-local formation
• IPv4 DHCP — DHCP client and server modes for usb0, and host-side setup
• IPv6 Router Advertisements — radvd configuration for IPv6 link-local on usb0
• mDNS / Avahi — Service broadcasting, hostname generation, and host-side discovery
• Troubleshooting — Diagnosing common networking problems

Key Addresses

Platform Notes

WendyOS runs on multiple hardware platforms. Networking behaviour is identical across them, but the underlying USB controller differs:

The QEMU virtual machine (qemuarm64-wendyos) does not use USB NCM gadget networking. It emulates a standard virtio network device instead.

Planned changes (not yet shipped)

The items below describe behaviour that is not implemented today. Current builds still rely exclusively on NetworkManager via its nmcli CLI for WiFi configuration, and have no built-in mTLS termination on the device side.

• Network Manager and IWD coexistence via auto-detect (WDY-1236) — planned, not yet implemented. Today the agent talks to NetworkManager (nmcli) only. The planned change adds IWD (Internet Wireless Daemon) as an alternative. The agent will detect which CLI is present on the running OS and select the matching backend, so devices on older OS builds that ship NetworkManager keep working unchanged. The OS-side change to ship iwd lands first; the agent-side switchover is gated on the OS PR.
• Unified TCP-based socket protocol for CLI and cloud (WDY-1246) — planned, not yet implemented. The same low-level TCP socket protocol — messages standardised by size, type, and payload — will back both cloud-to-device and CLI-to-device sessions, with the wendy CLI behaving as a local cloud instance. The existing flow (CLI emits a UDP broadcast, the device opens an HTTP connection back) becomes one of the supported transports under that unified surface.
• Mutual TLS for device communication (WDY-1245 covers the Wendy Light provisioning slice) — planned, not yet implemented. Sample mTLS socket plumbing exists in a development branch and will be merged once the unified protocol above is in place. The accompanying provisioning improvements (generating private keys and CSRs directly on-device, mDNS-based discovery) follow.