374 lines
8.4 KiB
Markdown
374 lines
8.4 KiB
Markdown
# USB Gadget Manager - UCI Configuration Guide
|
|
|
|
Universal USB Gadget Manager for OpenWrt using configfs interface.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# View current configuration
|
|
uci show usbgadget
|
|
|
|
# Enable/start the service
|
|
/etc/init.d/usb-gadget enable
|
|
/etc/init.d/usb-gadget start
|
|
|
|
# Check status
|
|
/etc/init.d/usb-gadget status
|
|
```
|
|
|
|
## Configuration File
|
|
|
|
Location: `/etc/config/usbgadget`
|
|
|
|
## Common Tasks
|
|
|
|
### Enable/Disable USB Gadget Mode
|
|
|
|
```bash
|
|
# Disable gadget (enable host mode - for USB storage, etc.)
|
|
uci set usbgadget.usb.enabled='0'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
|
|
# Enable gadget mode
|
|
uci set usbgadget.usb.enabled='1'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
### Network Functions
|
|
|
|
#### RNDIS (Windows Ethernet)
|
|
|
|
```bash
|
|
# Enable RNDIS
|
|
uci set usbgadget.rndis.enabled='1'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
**Compatible with:** Windows (all versions, plug-and-play)
|
|
|
|
#### ECM (macOS/Linux Ethernet)
|
|
|
|
```bash
|
|
# Enable ECM
|
|
uci set usbgadget.ecm.enabled='1'
|
|
uci set usbgadget.rndis.enabled='0' # Disable RNDIS
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
**Compatible with:** macOS ≤10.14, Linux (all)
|
|
|
|
#### NCM (Modern High-Performance Ethernet)
|
|
|
|
```bash
|
|
# Enable NCM (best performance)
|
|
uci set usbgadget.ncm.enabled='1'
|
|
uci set usbgadget.rndis.enabled='0' # Disable RNDIS
|
|
uci set usbgadget.ecm.enabled='0' # Disable ECM
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
**Compatible with:** Windows 11+, macOS ≥10.15, Linux (all)
|
|
|
|
**Note:** Network interfaces are automatically added to the LAN bridge.
|
|
|
|
### Serial Console (ACM)
|
|
|
|
#### Enable Serial Console with Login Shell
|
|
|
|
```bash
|
|
# Enable ACM with shell access
|
|
uci set usbgadget.acm.enabled='1'
|
|
uci set usbgadget.acm.shell='1'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
|
|
# Access from host:
|
|
# Linux/macOS: screen /dev/ttyACM0 115200
|
|
# Windows: Use PuTTY or similar on COMx port
|
|
```
|
|
|
|
#### Enable Raw TTY (No Shell)
|
|
|
|
```bash
|
|
# Enable ACM without shell (raw serial port)
|
|
uci set usbgadget.acm.enabled='1'
|
|
uci set usbgadget.acm.shell='0'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
### Mass Storage (UMS)
|
|
|
|
```bash
|
|
# Enable USB mass storage
|
|
uci set usbgadget.ums.enabled='1'
|
|
uci set usbgadget.ums.image_path='/var/lib/usb-gadget/storage.img'
|
|
uci set usbgadget.ums.image_size='1G'
|
|
uci set usbgadget.ums.readonly='0' # 0=read-write, 1=read-only
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
**Note:** Image file is created automatically on first use.
|
|
|
|
### Device Information
|
|
|
|
```bash
|
|
# Change USB vendor/product name
|
|
uci set usbgadget.usb.manufacturer='MyCompany'
|
|
uci set usbgadget.usb.product='My USB Device'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
|
|
# Change USB IDs (advanced)
|
|
uci set usbgadget.usb.vendor_id='0x1234'
|
|
uci set usbgadget.usb.product_id='0x5678'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
### Custom Gadget Name
|
|
|
|
```bash
|
|
# Change internal gadget name (optional)
|
|
uci set usbgadget.usb.gadget_name='my-device'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
## Common Scenarios
|
|
|
|
### Scenario 1: Quick Network Access (Windows PC)
|
|
|
|
```bash
|
|
uci set usbgadget.usb.enabled='1'
|
|
uci set usbgadget.rndis.enabled='1'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
Connect USB cable. Windows will detect "Remote NDIS Compatible Device" and get DHCP from OpenWrt.
|
|
|
|
### Scenario 2: Maximum Performance (Modern OS)
|
|
|
|
```bash
|
|
uci set usbgadget.usb.enabled='1'
|
|
uci set usbgadget.ncm.enabled='1'
|
|
uci set usbgadget.rndis.enabled='0'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
### Scenario 3: Serial Console + Network
|
|
|
|
```bash
|
|
uci set usbgadget.usb.enabled='1'
|
|
uci set usbgadget.rndis.enabled='1'
|
|
uci set usbgadget.acm.enabled='1'
|
|
uci set usbgadget.acm.shell='1'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
Provides both network access and serial console on the same USB connection.
|
|
|
|
### Scenario 4: USB Storage + Network
|
|
|
|
```bash
|
|
uci set usbgadget.usb.enabled='1'
|
|
uci set usbgadget.rndis.enabled='1'
|
|
uci set usbgadget.ums.enabled='1'
|
|
uci set usbgadget.ums.image_size='2G'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
### Scenario 5: Switch to USB Host Mode
|
|
|
|
```bash
|
|
# Disable gadget to use USB port for storage, etc.
|
|
uci set usbgadget.usb.enabled='0'
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
Now you can connect USB storage devices to the OpenWrt device.
|
|
|
|
## Service Management
|
|
|
|
```bash
|
|
# Start
|
|
/etc/init.d/usb-gadget start
|
|
|
|
# Stop
|
|
/etc/init.d/usb-gadget stop
|
|
|
|
# Restart (applies new configuration)
|
|
/etc/init.d/usb-gadget restart
|
|
|
|
# Status
|
|
/etc/init.d/usb-gadget status
|
|
|
|
# Enable on boot
|
|
/etc/init.d/usb-gadget enable
|
|
|
|
# Disable on boot
|
|
/etc/init.d/usb-gadget disable
|
|
```
|
|
|
|
## Viewing Configuration
|
|
|
|
```bash
|
|
# View all settings
|
|
uci show usbgadget
|
|
|
|
# View specific section
|
|
uci show usbgadget.usb
|
|
uci show usbgadget.rndis
|
|
uci show usbgadget.acm
|
|
|
|
# Export to file
|
|
uci export usbgadget > /tmp/usbgadget-backup.conf
|
|
|
|
# Import from file
|
|
uci import usbgadget < /tmp/usbgadget-backup.conf
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Check if gadget is active
|
|
|
|
```bash
|
|
/etc/init.d/usb-gadget status
|
|
```
|
|
|
|
### View logs
|
|
|
|
```bash
|
|
logread | grep usb-gadget
|
|
```
|
|
|
|
### Check USB controller
|
|
|
|
```bash
|
|
ls /sys/class/udc/
|
|
# Should show: ci_hdrc.0 (MSM8916), 20980000.usb (RPi), etc.
|
|
```
|
|
|
|
### Verify network interface
|
|
|
|
```bash
|
|
ip link show
|
|
# Look for: usb0, usb1, etc.
|
|
|
|
# Check if added to bridge
|
|
uci show network.@device[0].ports
|
|
```
|
|
|
|
### Reset to defaults
|
|
|
|
```bash
|
|
rm /etc/config/usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
This will recreate the config with default values.
|
|
|
|
### Common Issues
|
|
|
|
**"No UDC device found"**
|
|
- USB gadget kernel support not enabled
|
|
- Install:
|
|
- `opkg install kmod-usb-gadget kmod-usb-configfs`
|
|
- `apk add kmod-usb-gadget kmod-usb-configfs`
|
|
|
|
**"ttyGS0 not found"**
|
|
- ACM function takes ~10 seconds to initialize
|
|
- Check: `ls -l /dev/ttyGS0`
|
|
|
|
**Network not working**
|
|
- Verify function is enabled: `uci show usbgadget.rndis.enabled`
|
|
- Check if interface exists: `ip link show usb0`
|
|
- Verify bridge: `brctl show br-lan`
|
|
|
|
## Hardware Compatibility
|
|
|
|
**Auto-detects USB controller on:**
|
|
- Raspberry Pi (all models with USB OTG)
|
|
- Qualcomm MSM8916/MSM89xx devices
|
|
- Orange Pi, Banana Pi
|
|
- Any device with USB gadget kernel support
|
|
|
|
**No hardware-specific configuration needed!**
|
|
|
|
## Advanced: Manual UDC Selection
|
|
|
|
If auto-detection fails:
|
|
|
|
```bash
|
|
# Check available UDC
|
|
ls /sys/class/udc/
|
|
|
|
# Set manually
|
|
uci set usbgadget.usb.udc_device='ci_hdrc.0' # Example
|
|
uci commit usbgadget
|
|
/etc/init.d/usb-gadget restart
|
|
```
|
|
|
|
## Configuration Reference
|
|
|
|
### Device Section (`config device 'usb'`)
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `enabled` | `1` | Enable/disable gadget (0=host mode, 1=device mode) |
|
|
| `gadget_name` | `g1` | Internal gadget name (any string) |
|
|
| `vendor_id` | `0x1d6b` | USB Vendor ID (Linux Foundation) |
|
|
| `product_id` | `0x0104` | USB Product ID (Multifunction Composite) |
|
|
| `device_version` | `0x0100` | Device version (BCD format) |
|
|
| `manufacturer` | `OpenWrt` | Manufacturer string shown to host |
|
|
| `product` | `USB Gadget` | Product string shown to host |
|
|
| `udc_device` | _(empty)_ | UDC device name (auto-detect if empty) |
|
|
|
|
### Function Sections
|
|
|
|
Each function has:
|
|
- `enabled`: `0` or `1`
|
|
- `description`: Human-readable description (not used by system)
|
|
|
|
#### RNDIS Function (`config function 'rndis'`)
|
|
No additional options.
|
|
|
|
#### ECM Function (`config function 'ecm'`)
|
|
No additional options.
|
|
|
|
#### NCM Function (`config function 'ncm'`)
|
|
No additional options.
|
|
|
|
#### ACM Function (`config function 'acm'`)
|
|
- `shell`: `0` or `1` - Enable login shell on serial console
|
|
|
|
#### UMS Function (`config function 'ums'`)
|
|
- `image_path`: Path to image file
|
|
- `image_size`: Size when creating (e.g., `512M`, `1G`, `2G`)
|
|
- `readonly`: `0` (read-write) or `1` (read-only)
|
|
|
|
## Tips
|
|
|
|
- **Multiple functions:** You can enable multiple functions simultaneously (e.g., RNDIS + ACM)
|
|
- **Network priority:** Only one network function should be enabled at a time (RNDIS, ECM, or NCM)
|
|
- **Serial number:** Auto-generated from `/etc/machine-id` for uniqueness
|
|
- **MAC addresses:** Auto-generated deterministically (same device = same MACs)
|
|
- **Storage persistence:** UMS image persists across reboots (in `/var` which is `/tmp`)
|
|
|
|
## Learn More
|
|
|
|
- OpenWrt USB Gadget: https://openwrt.org/docs/guide-user/hardware/usb_gadget
|
|
- Linux USB Gadget API: https://www.kernel.org/doc/html/latest/usb/gadget_configfs.html
|
|
- UCI Documentation: https://openwrt.org/docs/guide-user/base-system/uci
|