USB_MODESWITCH(1)

💅 usb_modeswitch(1) — the General Commands Manual, but make it cute 💅

okay bestie, welcome to section 1 of the General Commands Manual — this is the usb_modeswitch page and we're gonna get through every single line together, no cap. 💖

---

✨ NAME ✨

usb_modeswitch — control the mode of 'multi-state' USB devices. that's the whole vibe. iconic.

---

✨ SYNOPSIS ✨

usb_modeswitch [-heWQDIvpVPmM23rwKdHSOBGTNALnsRiuagft] [-c filename]

look at all those letters — she's literally the alphabet mafia 💀 but don't panic, we're breaking every single one down below.

---

✨ DESCRIPTION ✨

so here's the tea. several new USB devices have their proprietary Windows drivers onboard — most of them WWAN and WLAN dongles. when you plug one in for the first time, it acts like a flash storage and starts installing the Windows driver from there. if the driver is installed, it makes the storage device disappear and a new device shows up — mainly composite (e.g. with modem ports). queen behavior.

on Linux, in most cases the drivers are available as kernel modules, such as "usbserial" or "option". but the device initially binds to "usb-storage" by default. that's where usb_modeswitch comes in — it can send a provided bulk message (most likely a mass storage command) to the device. this message has to be determined by analyzing the actions of the Windows driver. detective work, honestly. 🔍

in some cases, USB control commands are used for switching. these cases are handled by custom functions, and no bulk message needs to be provided. slay.

usually, the program is distributed with a set of configurations for many known devices, which allows a fully automatic handling of a device upon insertion — made possible by combining usb_modeswitch with the wrapper script usb_modeswitch_dispatcher which is launched by the udev daemon. this requires a Linux-flavoured system though. 🐧

note that usb_modeswitch itself has no specific Linux dependencies.

---

✨ OPTIONS ✨

this program follows the usual GNU command line syntax, with long options starting with two dashes ('--'). a summary of options is included below. let's go, one by one, no skipping. 💅

• -h, --help — show summary of options. the "help me help you" button.
• -e, --version — print version information and exit. short and sweet.
• -v, --default-vendor NUM — vendor ID to look for (mandatory), usually given as hex number (example: 0x12d1). each USB device is identified by a number officially assigned to the vendor by the USB association and a number for the respective model (product ID) chosen by the vendor.
• -p, --default-product NUM — product ID to look for (mandatory).
• -V, --target-vendor NUM — target vendor ID. when given will be searched for and detected initially for information purposes. if success checking (option -s) is active, providing target IDs (vendor/product) or target class is recommended.
• -j, --find-mbim — return configuration number with MBIM interface and exit.
• -P, --target-product NUM — target product ID.
• -b, --bus-num NUM — the original page literally lists this flag with zero description, so i'm not inventing one. it's just vibes and a number, bestie. 💀
• -g, --device-num NUM — if bus and device number are provided, the handling of a specific device on a specific USB port is guaranteed, in contrast to using only the USB ID. this is important if there are multiple similar devices on a system.
• -C, --target-class NUM — target Device Class according to the USB specification. some devices keep their original vendor/product ID after successful switching. to prevent them from being treated again, the device class can be checked. for unswitched devices it is always 8 (storage class), for switched modems it is often 0xff (vendor specific). in composite modes, the class of the first interface is watched.
• -m, --message-endpoint NUM — a specific endpoint to use for data transfers. only for testing purposes; usually endpoints are determined from the device attributes.
• -M, --message-content STRING — a bulk message to send as a switching command. provided as a hexadecimal string.
• -2, --message-content2 STRING — listed bare in the original, no separate description, she's mysterious like that. 🫶
• -3, --message-content3 STRING — additional bulk messages to send as switching commands. provided as hexadecimal strings. when used with mass storage commands, setting --need-response is strongly advised to comply with specifications and to avoid likely errors.
• -w, --release-delay <milliseconds> — after issuing all bulk messages, wait for the given time before releasing the interface. required for some modems on older systems (especially after an EJECT message).
• -n, --need-response — obsolete. CSW is always attempted to being read after mass storage transfers. no downside.
• -r, --response-endpoint NUM — try to read the response to a storage command from there. only for testing purposes; usually endpoints are determined from the device attributes.
• -K, --std-eject — apply the standard SCSI sequence of "Allow Medium Removal" and "Eject". implies -n. one 'Message' can be added with -M that will be transmitted after the eject sequence. used by many modems.
• -d, --detach-only — just detach the current driver. this is sufficient for some early devices to switch successfully. otherwise this feature can be used as a 'scalpel' for special cases, like separating the driver from individual interfaces.
• -H, --huawei-mode — send a special control message used by older Huawei devices.
• -J, --huawei-new-mode — send a specific bulk message used by all newer Huawei devices.
• -X, --huawei-alt-mode — send an alternative bulk message to Huawei devices.
• -S, --sierra-mode — send a special control message used by Sierra devices. (yes, -S shows up again below — the original lists it twice, and i'm not here to fix the manpage, i'm here to translate it. 💅)
• -G, --gct-mode — send a special control message used by GCT chipsets.
• -T, --kobil-mode — send a special control message used by Kobil devices.
• -N, --sequans-mode — send a special control message used by Sequans chipset.
• -A, --mobileaction-mode — send a special control message used by the MobileAction device.
• -B, --qisda-mode — send a special control message used by Qisda devices.
• -E, --quanta-mode — send a special control message used by Quanta devices.
• -F, --pantech-mode NUM — send a special control message used by Pantech devices. value NUM will be used in control message as 'wValue'.
• -Z, --blackberry-mode — send a special control message used by some newer Blackberry devices.
• -S, --option-mode — send a special control message used by all Option devices. (see? told you -S was doing double duty.)
• -O, --sony-mode — apply a special sequence used by Sony Ericsson devices. implies option --check-success.
• -L, --cisco-mode — send a sequence of bulk messages used by Cisco devices.
• -R, --reset-usb — send a USB reset command to the device. can be combined with any switching method or stand alone. it is always done as the last step of all device interactions. few devices need it to complete the switching; apart from that it may be useful during testing.
• -c, --config-file FILENAME — use a specific config file. if any ID or switching options are given as command line parameters, this option is ignored. in that case all mandatory parameters have to be provided on the command line.
• -f, --long-config STRING — provide device details in config file syntax as a multiline string on the command line.
• -t, --stdinput — read the device details in config file syntax from standard input, e.g. redirected from a command pipe (multiline text).
• -Q, --quiet — don't show progress or error messages. stealth mode activated.
• -W, --verbose — print all settings before running and show libusb debug messages. the yapper option, we love her.
• -D, --sysmode — changes the behaviour of the program slightly. a success message including the effective target device ID is put out and a syslog notice is issued. mainly for integration with a wrapper script.
• -s, --check-success <seconds> — after switching, keep checking for the result up to the given time. if target IDs or target class were provided, their appearance indicates certain success. otherwise the disconnection of the original device is rated as likely proof.
• -I, --inquire — obsolete. formerly obtained SCSI attributes, now ignored.
• -i, --interface NUM — select initial USB interface (default: 0). only for testing purposes.
• -u, --configuration NUM — select USB configuration (applied after any other possible switching actions).
• -a, --altsetting NUM — select alternative USB interface setting (applied after switching). mainly for testing.

---

✨ AUTHOR ✨

this manual page was originally written by Didier Raboud (didier@raboud.com) for the Debian system. additions made by Josua Dietze. permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License, Version 2 or any later version published by the Free Software Foundation.

the complete text of the current GNU General Public License can be found in http://www.gnu.org/licenses/gpl.txt

---

aaaand that's the whole page, bestie. for the sign-off: this manual is USB_MODESWITCH(1) from the General Commands Manual, and the footer just repeats USB_MODESWITCH(1) like a little echo — no extra date or version line in the source, so i'm not making one up. periodt. 💅✨💖