USB Gadget Configuration and Linux Tools
Device-side USB Gadget implementation guide, Linux ConfigFS libcomposite setup, open-source gadgetconfig tooling, and pigadget_mcp remote automation for seamless interoperability with Windows 11 hosts.
Target host environments
- Windows 11 amd64
- Windows 11 arm64
- Windows 10 amd64 (Note: ARM64 is supported on Windows 11 only)
Descriptor and interface expectations
- Expose clear, stable interface descriptors for the selected networking protocol mode.
- For composite devices, keep interface numbering stable so host-side MI matching remains deterministic.
- Ensure descriptor changes are versioned and validated across firmware releases.
Protocol mode guidance
- Choose the protocol mode (RNDIS, ECM, EEM, NCM) intentionally per product line.
- Avoid unnecessary protocol switching across minor firmware updates.
- Document any protocol-specific limits in throughput, MTU handling, or framing behavior.
Operational behavior checklist
- Verify clean link bring-up after cable connect and host enumeration.
- Validate IP address assignment model (DHCP or static) for the expected deployment profile.
- Confirm stable reconnect behavior across repeated unplug/replug cycles.
- Validate sleep/resume recovery without stale link state.
Recommended interoperability tests
- Long-duration sustained transfer test (throughput and stability).
- Automated connect/disconnect cycling: Validate driver recovery and IP re-acquisition across continuous replug sequences. Belcarra provides the open-source usbtestnet Windows test harness to automate device enable/disable cycles via
devcon, verify network adapter readiness, and log ping/HTTP connectivity statistics. - Suspend/resume and reboot sequence validation.
- Multiple attached device scenario (if supported by product requirements).
USB Framework Architecture
The diagram below illustrates the complete device-side USB software and hardware framework—spanning the target operating system, composite interface functions (CDC-NCM, CDC-EEM, CDC-ECM, RNDIS, serial, storage, and HID), USB device core stack, and the peripheral controller driver (UDC) to the physical medium:
Linux gadget configuration tools (gadgetconfig)
For Linux-based devices (such as Raspberry Pi, BeagleBone, and custom embedded SoCs), Belcarra maintains the open-source gadgetconfig package to configure Linux kernel ConfigFS (libcomposite) gadgets via declarative JSON and systemd:
- Declarative JSON schema: Define device descriptors, interface functions (CDC-ECM, CDC-EEM, CDC-NCM, RNDIS, CDC-ACM, HID), and configurations in structured files.
- Vendor ID (idVendor) and Product ID (idProduct): ConfigFS device descriptors require 16-bit hexadecimal identifiers. OEM products can use their own official USB-IF Vendor ID, or licensees can have Belcarra allocate a dedicated Product ID under Belcarra's Vendor ID.
- Microsoft OS Descriptors: Native
os_descconfiguration for deterministic driver binding on Windows hosts. - Early-boot deployment: Convert JSON definitions to shell scripts using
gadgetconfig --sh-autofor minimal initramfs or early-init environments. - Headless First-Boot Setup (pi_zero_connected): For Raspberry Pi Zero systems, Belcarra provides the open-source pi_zero_connected utility to stage USB gadget networking directly on the FAT32
/bootpartition before first boot, bypassing Linuxextfilesystem editing on Windows or macOS. - Graphical Interface (gadgetapp): For interactive desktop workstations and Raspberry Pi systems running a display,
gadgetconfigincludes thegadgetappgraphical user interface for visual gadget design and testing. - Package installation: Available on PyPI (
pip3 install gadgetconfig) and GitHub at Belcarra/gadgetconfig.
Remote testbed automation via MCP (pigadget_mcp)
For automated driver qualification, CI/CD hardware pipelines, and remote agent-driven testbeds, Belcarra provides pigadget_mcp—a Model Context Protocol (MCP) service for controlling Raspberry Pi USB gadgets:
- Dynamic protocol switching: Automated scripts and AI agents can switch on-the-fly between CDC-ECM, CDC-NCM, CDC-EEM, and RNDIS protocol modes.
- Configurable hardware IDs: Specify custom USB Vendor and Product IDs (VID/PID) programmatically without modifying firmware files.
- Addressing control: Remotely assign static IPv4 addresses or toggle DHCP server allocation on the gadget side.
- Connection lifecycle testing: Programmatically initiate software disconnect and reconnect cycles, retrieve device status, and clean up test fixtures after qualification runs.
- Remote architecture: Operates as a headless background service directly accessible to local MCP clients or across secure networks via MCP broker proxies. Available on GitHub at Belcarra/pigadget_mcp.
Evidence to retain per release
- Descriptor snapshot and firmware build identifiers
- Protocol mode test logs and pass/fail summary
- Known issues and mitigation notes