usb_modeswitch

usb_modeswitch [OPTIONS]
usb_modeswitch [-v ] [-p ] [-H] [-I] [-e] [-d ] [-s ] [-u ] [-n] [-c ] [-W] [-h]

-v , --vendor
    Specifies the 4-digit hexadecimal USB Vendor ID of the target device.

-p , --product
    Specifies the 4-digit hexadecimal USB Product ID of the target device.

-c , --config
    Specifies an alternative path to a device-specific configuration file.

-I, --ignore-config-file
    Ignores the global configuration files and relies solely on command-line parameters.

-H, --huawei-new-config
    Enables a special mode for handling newer Huawei devices that require a different switching method.

-e, --enable-control-sends
    Permits sending control messages (often used for specific device types).

-d , --device
    Specifies the USB device node (e.g., /dev/bus/usb/001/005) instead of inferring from IDs.

-s , --message-send
    Sends a specific message (e.g., SCSI command string) to the device. Used for devices requiring custom commands.

-u , --message-content
    Sends a specific bulk message to the device. Used for devices requiring custom bulk data transfers.

-n, --no-auto-send
    Prevents the automatic sending of messages read from the configuration file. Only uses messages specified by -s or -u.

-W, --verbose
    Enables verbose output, showing more details about the switching process for debugging.

-h, --help
    Displays the help message and exits.

usb_modeswitch is a crucial utility for Linux systems designed to handle 'flip-flop' USB devices. These devices, commonly 3G/4G mobile broadband modems or certain Wi-Fi adapters, initially present themselves to the operating system as a USB mass storage device (often containing drivers for other operating systems). Their true functionality (modem, network adapter) is hidden until a specific 'mode switch' command is sent.

The program intercepts the device's initial enumeration and sends the necessary command (typically a SCSI command or a special control message) to transition the device into its operational mode. Once the command is successfully sent, the device re-enumerates itself, allowing the Linux kernel to recognize it correctly and load the appropriate drivers (e.g., cdc_ether, qcserial, option).

usb_modeswitch relies on a database of device configurations, usually stored in /etc/usb_modeswitch.conf or individual files in /etc/usb_modeswitch.d/. These files contain the Vendor ID (VID), Product ID (PID), and the specific command sequence required for each known device. It is frequently employed in conjunction with udev rules to automate the switching process seamlessly when the device is plugged in, providing a plug-and-play experience for these otherwise challenging USB peripherals.

Requires root privileges to access and manipulate USB devices.

While generally safe due to its reliance on known device configurations, using incorrect or custom mode switch commands (e.g., with -s or -u options) could potentially cause unintended behavior or even temporary device malfunction, though permanent 'bricking' is rare.

The mode switch is typically a one-time operation per connection; the device remains in its switched mode until it is unplugged or its power is cycled. Re-enumeration by the kernel might sometimes require a slight delay or explicit udevadm trigger for the correct drivers to bind.

usb_modeswitch primarily operates using configuration files. The main configuration is typically located at /etc/usb_modeswitch.conf, which defines global settings. Device-specific configurations are usually found in individual files within the /etc/usb_modeswitch.d/ directory, named after the device's Vendor ID and Product ID (e.g., 12d1:1001). These files contain crucial information like the target Vendor/Product IDs after switching, and the specific message(s) required to trigger the mode change.

For automatic mode switching upon device connection, usb_modeswitch is almost always integrated with udev. A udev rule (e.g., in /etc/udev/rules.d/40-usb_modeswitch.rules) detects the initial connection of a known 'flip-flop' device based on its Vendor and Product IDs. This rule then triggers the execution of usb_modeswitch with the appropriate parameters, causing the device to switch modes automatically without user intervention. This ensures a true plug-and-play experience for compatible devices.

To use usb_modeswitch manually or to create custom configurations, it's essential to identify the Vendor ID (VID) and Product ID (PID) of your USB device. This can be easily done using the lsusb command. When the device is in its initial (storage/CD-ROM) mode, run lsusb and look for your device. The output will show something like 'ID xxxx:yyyy'. Here, xxxx is the Vendor ID and yyyy is the Product ID, both in hexadecimal format. These IDs are then used by usb_modeswitch to target the correct device.

The development of usb_modeswitch began around 2007-2008 as a pragmatic solution to a growing problem: the proliferation of 'flip-flop' USB modems, particularly 3G/4G dongles, that were designed primarily for Windows.

Initially, Linux users relied on various custom scripts and manual commands to get these devices working. However, as the number and variety of such devices increased, a more standardized and automated approach was needed. Josh Stewart initiated the project, and it quickly became a widely adopted utility, often bundled with Linux distributions.

Its evolution involved creating and maintaining a comprehensive database of device Vendor IDs, Product IDs, and their specific mode-switching commands, making it easier for new devices to be supported without requiring core code changes. This robust configuration system, combined with integration into the udev system, has made usb_modeswitch an essential component for seamless mobile broadband connectivity on Linux.

lsusb(8), udevadm(8), modprobe(8), nmcli(1), mmcli(1)