usb_modeswitch

usb_modeswitch [options]

-v
    Specify the vendor ID of the USB device (in hexadecimal).

-p
    Specify the product ID of the USB device (in hexadecimal).

-V
    Specify the new vendor ID after switching (in hexadecimal).

-P
    Specify the new product ID after switching (in hexadecimal).

-t
    Specify the switching method type (e.g., option, huawei).

-s
    Specify the message to send for switching (in hexadecimal).

-n
    Do not detach the device after switching (useful for some devices).

-c
    Specify an alternative configuration file.

-W
    Wait for the device to reappear after switching. Implies -n.

-D
    Run in daemon mode (background process).

-u
    Explicitly specify the USB interface to use.

-S
    Scan device for supported modes.

-q
    Quiet mode; suppress most output.

-h
    Show help message and exit.

usb_modeswitch is a command-line tool that controls USB devices that implement a device mode switching scheme.

Many new USB devices, especially USB dongles used for mobile broadband, appear as USB mass storage devices (like a flash drive) when first plugged in. This is to allow easy driver installation on Windows systems, as the drivers are stored on the device itself. After the drivers are installed, the device switches to its functional mode (e.g., a modem or network adapter).

usb_modeswitch automates this switching process on Linux and other Unix-like systems. It sends specific control commands to the USB device to trigger the mode switch, enabling the intended functionality. It uses a configuration file containing information about different devices and their respective switching commands. The program supports a variety of devices from manufacturers like Huawei, ZTE, Option, Sierra Wireless, and others. It is essential for making these devices work correctly in Linux environments.

Incorrect configuration or inappropriate use can render a USB device unusable. Always research and understand the correct parameters for your specific device before using usb_modeswitch.

usb_modeswitch relies on configuration files located in /usr/share/usb_modeswitch/configPack.tar.gz (and older installations in /etc/usb_modeswitch.d/) to determine the correct switching commands for specific devices. These files contain vendor and product IDs, along with the switching messages.

Configuration files are constantly updated to include configuration for newly released devices.

usb_modeswitch is commonly integrated with udev rules to automatically switch devices when they are plugged in. This provides a seamless experience for the user, as the device is automatically configured without manual intervention. Udev rules can be found in the system's udev rules directory.

usb_modeswitch was initially developed to address the issue of USB modems appearing as mass storage devices. As more devices adopted this behavior, the tool evolved to support a wider range of devices and switching methods. It has become a standard utility in many Linux distributions, often integrated with udev rules for automatic device switching upon connection. Development continues to address new device types and switching strategies.

lsusb(1), udev(7)