USB_ModeSwitch ≈ управление бистабильными USB устройствами под Linux

Оригинал: USB_ModeSwitch ≈ Handling Mode-Switching USB Devices on Linux
Автор: Josua Dietze
Дата последнего обновления: 10 июня 2013
Свободный перевод: Алексей Дмитриев
Дата перевода: июнь 2013

Предисловие

USB_ModeSwitch ≈ это программа переключающая режимы бистабильных USB устройств.

Все больше USB гаджетов (особенно из линейки высокоскоростных WAN устройств, созданных на основе сотовых чипсетов) имеют встроенные драйвера MS Windows; будучи подключенными к компьютеру в первый раз, они ведут себя как флеш-накопители и начинают установку своего программного обеспечения. По окончании установки (и при всех последующих подключениях) драйвер переключает режим гаджета, накопитель исчезает, и можно увидеть новое устройство (например USB модем). Производитель модемов "Option" называет такой механизм "ZeroCD (TM)" так как он позволяет обойтись без отдельного носителя с драйверами.

Поначалу никакой документации на этот счет не существовало и говорить о какой-либо поддержке Linux не приходилось.
Но, с другой стороны, большинство известных гаджетов нормально работают в обоих режимах с обычными Linux драйверами типа "usb-storage" и "option" (улучшенный драйвер последовательного порта, стандарт Linux для скоростных 3G модемов).
Остается только проблема переключения режима гаджета из накопителя в модем, или в какой-либо иной прибор.

К счастью, на свете есть здравый смысл, программы прослушивания шины USB и "libusb". Возможно отследить сообщения MS Windows драйвера, выделить команду или действие, переключающие режим, а потом воспроизвести подобный сценарий по правилам Linux или BSD.

USB_ModeSwitch позволяет легко управлять этим процессом, получая важные параметры из конфигурационного файла и проводя всю работу по связи и инициализации, все при мощной помощи "libusb".
Обычно все происходит автоматически ≈ через события udev и его правила ≈ и не требует вмешательства пользователя. Но можно применять его и как инструмент командной строки, обычно когда нужно запустить незнакомый прибор.

USB_ModeSwitch входит в состав основных дистрибутивов, поэтому нет нужды устанавливать его из исходников, за исключением случая, когда что-то не ладится и потребуется последняя версия программы.

 

Пожалуйста, прочтите эту статью внимательно, прежде чем начнете постить вопросы! Если у вас незнакомый гаджет, она поможет вам понять суть происходящего, каковое понимание, в свою очередь, поможет найти нужную переключающую команду и добавить ее в конфигурационный файл.

О том как проводить собственные исследования смотрите раздел Сотрудничество.

Загрузки

Последний на сегодняшний день релиз программы ≈ 1.2.6. tar архив содержит только исходник. Я применял libusb-0.1.12, но и "compat" версия библиотеки libusb-1.0 тоже будет работать.

Важно: кроме исходника вам понадобится также пакет данных data package!!
Изменения и обновления пакета данных data package происходят чаще чем выходят новые релизы программы, так как в этих файлах содержатся ценные сведения о новых гаджетах. Вот почему они поставляются отдельно.

• Загрузите usb-modeswitch-1.2.6.tar.bz2 датированный 2013-06-02; Debian пакет скоро появится в репозиториии Debian. Поддерживаются многие архитектуры (как amd64 или ia64).
  Имейте ввиду, что Deb-пакет не на 100% совместим с последними версиями Ubuntu.
• Загрузите usb-modeswitch-data (пакет датирован 2013-06-10). Он содержит базу данных устройств и файл с правилами, включая полные пути (path). Этот пакет может работать с релизами от 1.0.3 и выше, но самые "свежие" гаджеты и их характеристики могут потребовать и более новый релиз программы.
• Опционально device_reference.txt от 2013-06-10; это собрание сетапов большинства устройств и их производителей (contributors); используется как отправная точка при запуске нового гаджета.
• Не забудьте загрузить libusb если она у вас не установлена. В большинстве дистрибутивов есть пакет "libusb-dev" или "libusb-devel". Берите legacy-версию (0.1.12) или "compatible" пакет из libusb-1.0; когда я проверял в последний раз, его версия была 0.1.14.

Новость: Если у вас есть андроидный планшет с USB хост-портом и Андроид по крайней мере 2.2, то можете попробовать новый "PPP Widget" (тестовая версия 0.8). Он состоит из USB_ModeSwitch и PPPD и может установить выход в Интернет при помощи USB модема или телефона.

Сверх того, я предлагаю статический бинарник для ARM: usb_modeswitch-1.1.9-arm-static.bz2.
Скомпилировано при помощи gcc (arm-none-linux-gnueabi 3.4.4) без специальных настроек. Libusb 0.1.12 вкомпилирован.

Если вы мантейнер пакетов, то следующий XML файл поможет вам сверять новые релизы:
usb-modeswitch-versions.xml

Установка

Если у вас уже установлена более ранняя версия, рекомендуется деинсталляция ее ("make uninstall"). Начиная с версии 1.1.0 изменилось местоположение некоторых файлов, если у вас версия новее 1.1.0, то достаточно обновиться и переписать все файлы.

Распакуйте архив с исходником. В свежесозданной директории выполните от имени суперпользователя программу:

# make install

Команда установит небольшой shell-скрипт для udev, большой скрипт оболочки, конфигурационный файл, страницу мана и скомпилированный бинарник.
Важно: при установке программы данным способом, потребуется пакет "tcl" для работы большого управляющего скрипта. Есть другие способы установки, которые не требуют этого пакета. Для ознакомления с другими возможностями установки читайте файл README.

Такая же точно процедура с пакетом data package. Он установит конфигурационные файлы в директории "/usr/share/usb_modeswitch" и файл правил udev в директории "/lib/udev/rules.d". Прежняя директория "/etc/usb_modeswitch.d" зарезервирована для пользовательских конфигурационных файлов (новых или отредактированных).
Теперь все готово для работы; если ваш гаджет есть в базе данных, вы сможете использовать его сразу после подключения. Если он не работает как следует, то мы выясним отчего.

Для работы в ручном режиме просто нужно установить программу. Работать можно из командной строки, либо редактировать конфигурационный файл. В файле "device_reference" (см. "Загрузки") вы найдете отправные данные для создания собственной конфигурации. Этот файл обильно комментирован и подскажет вам что делать.
Ваш пользовательский конфигурационный файл может располагаться где угодно и называться как вам угодно; просто нужно указать его имя и местоположение в командной строке при помощи параметра -c.

Ручной режим предназначен для тестирования и исследования. Смотрите следующий раздел.

Использование

В большинстве случаев, вы сможете пользоваться гаджетом безо всяких дополнительных действий, не считая его подключения к компьютеру.

Если вы полагаете, что ваш прибор поддерживается, но почему-то не работает, первым делом подключите функцию ведения лога, как описано в разделе Диагностика.

Для тестирования, диагностики и приручения нового гаджета, можно использовать функционал программы в ручном режиме.
Это можно делать из командной строки, либо при помощи конфигурационного файла.

Чтобы получить список параметров команды запустите "usb-modeswitch -h".
Конфигурационный файл задается параметром -c.
Следует иметь ввиду, что если не подключены опции -W, -D, -I и -q, то конфигурационный файл, заданный параметром -c игнорируется, и все необходимые параметры нужно явно указывать в командной строке.

Для работы с конфигурационным файлом используйте один из файлов в директории "/usr/share/usb_modeswitch" или создайте его сами. Задайте имя и местоположения конфигурационного файла при помощи опции -c . В файле device_reference.txt смотрите подсказки по различным семействам модемов и объяснение параметров.

Важно: USB_ModeSwitch, как и все программы, использующие libusb, запускается в командной строке от имени суперпользователя (или через "sudo"). В противном случае появляются непонятные предупреждения, и работа не идет. Так как придется постоянно пробовать новые варианты команды, то имеет смысл работать с ней в оболочке root shell ("sudo bash" or "su -").

При работе в автоматическом режиме действуют следующие компоненты, перечисленные в порядке своей работы:

• /lib/udev/rules.d/40-usb_modeswitch.rules ≈ правила udev, запускающие оболочку при подключении прибора с указанным ID (vendor/product).
  Если прибор после переключения режима создает последовательные порты, второе правило снова запускает оболочку и создает символическую ссылку на правильный порт (см. ниже).
• /lib/udev/usb_modeswitch ≈ шелл-скрипт, инициируемый реальным скриптом оболочки. Начиная с версии 1.1.6 этот скрипт полностью совместим с шеллом "dash", применяемым в Ubuntu, так же как и с более старыми "bash" вариантами.
• /usr/sbin/usb_modeswitch_dispatcher ≈ проводит дополнительную проверку устройства и производит переключение режима, руководствуясь конфигурационным файлом для данного устройства.
  Если, после переключения режима, никакие драйвера не обеспечивают функционирование устройства, то диспетчер попытается загрузить и запустить драйвер "option" чтобы прибор мог работать.
• /etc/usb_modeswitch.conf ≈ общий конфигурационный файл для включения функции ведения логов при диагностике, или для запрета переключения режимов (обычно для того, чтобы получить доступ к виртуальному флеш-накопителю).
• /usr/share/usb_modeswitch ≈ директория, содержащая индивидуальные файлы для каждого прибора, именованными в соответствии с их ID (или другими идентификаторами в случае совпадения ID). Если имеется файл с именем ID вашего гаджета, все шансы за то, что ваш прибор поддерживается, даже если его модель и не совпадает.
  Напоминаю еще раз, что директория "/usr/share/usb_modeswitch" как и файл правил udev устанавливаются пакетом usb_modeswitch data package.
• usr/sbin/usb_modeswitch ≈ собственно бинарник, производящий переключение режимов.

После того, как режим переключен и драйвер последовательного порта запущен, наступает очередь операционной системы обнаружить новое устройство.

При работе с беспроводными устройствами, возможны проблемы с NetworkManager (или его компонентом ModemManager), который до сих пор часто ошибается при определении правильного порта.
Хорошо зарекомендовали себя программы wvdial, UMTSmon и несколько других, обеспечивающих графический интерфейс для запуска PPP, например kppp; правда, эти программы требуют некоторых знаний.

Также появилась новая ≈ необычная и интригующая ≈ концепция, которая сокращает утомительный путь настройки различных компонентов для подключения беспроводной связи. Sakis3G ≈ это самодостаточная программа (включающая в себя, среди прочего, и новейший USB_ModeSwitch бинарник). Программа уже поддерживает большое число провайдеров и стремительно развивается. В противоположность NetworkManager она действительно работает. Ищите ее на блоге ToDo Forever. Там же и инструкции по установке, в идеале она запускает ваш модем как только он подключен.

Главное препятствие полностью автоматического запуска вновь подключенного модема программой NetworkManager и иже с ним ≈ это определение правильного порта. Зачастую, после переключения режима, создается более одного порта (в некоторых случаях до 5 штук). Вообще-то не все они являются действительно последовательными портами (драйвер не может понять какие), хотя некоторые весьма похожи и даже отвечают на AT-команды, но только правильный порт является точкой передачи данных. К сожалению, NetworkManager руководствуется иными критериями проверки и иногда ошибается. Стоит заметить, что упомянутый выше Sakis3G находит истинный порт играючи.

Начиная с версии 1.1.2, usb_modeswitch добавляет символическую ссылку на правильный порт, обеспечивающий передачу данных, если устройство создает последовательные порты. Эта ссылка носит имя /dev/gsmmodem (с соответствующим номером, в случае подключения нескольких устройств).
Можно использовать эту ссылку при настройке программ дозвона типа wvdial. В большинстве случаев их конфигурация правится вручную.

Когда удалось вручную запустить переключение режима нового или плохо поддерживаемого гаджета, можно прописать соответствующее правило udev и конфигурационный файл. Но не поленитесь сообщить об этом, чтобы и другие могли последовать по вашему пути!
См. Сотрудничество

Поддерживаемые гаджеты

Очень важное замечание: Лично я физически не могу протестировать большинство приборов и вынужден полагаться на сообщения других людей. Поэтому возможно возникновение препятствий даже если ваш прибор есть в списке.
Но в последнее время аудитория пользователей данной программы значительно увеличилась, так что всякие ошибки обычно скоро вылезают наружу.

Существует три способа осуществить переключение режима:

1. Отключить накопительное устройство (в том числе SCSI) какой-либо редкой командой, например "eject" (немного непонятно написано; оказалось, что автор имеет ввиду управляющую команду (она же последовательность) 5553424312345678000000000000061b000000020000000000000000000000. Джошуа пишет на форуме: ≈ "Я всегда пытаюсь использовать Команду "извлечь" ("eject"), если ничего не помогает).
2. Послать на устройство одну из вендор-специфичных управляющих команд.
3. Насильно отключить от устройства драйвер накопителя (только для некоторых ранних гаджетов).

Еще раз скажу: даже если вы не нашли ваш гаджет в списке, он может все равно поддерживаться.
Важно чтобы ваш USB ID был в числе имен файлов в директории конфигурационных файлов /usr/share/usb_modeswitch. Загляните в новейший пакет usb-modeswitch-data (см. Загрузки).

Вот этот список поддерживаемых гаджетов вместе с их производителями:
device_reference.txt

Диагностика

Если, после знакомства со всем вышесказанным, вам все еще нужна поддержка, добро пожаловать на форум! Электронная почта предназначена для обсуждения вопросов сотрудничества.

Известные проблемы:

• Только ядра начиная с 2.6.27 и выше назначают 3G-оптимизированный драйвер последовательного порта. Если у вас более старое ядро и ваш модем после переключения режима не опознан ни одним драйвером, тогда используется универсальный драйвер "usbserial".
• Устройства с ID 19d2:2000 на ядрах с 2.6.26 по 2.6.28 испытывают затруднения при переключении режима. Это касается в основном ZTE устройств, "usb-storage" драйвер игнорирует данный ID, что приводит к невозможности переключить режим. Ничего не остается, как перекомпилировать ядро с небольшими изменениями. Подробности в разделе Проблемы связанные с ядром.

Для диагностики первым делом следует подключить функцию ведения логов. Как суперпользователь отредактируйте файл /etc/usb_modeswitch.conf в текстовом редакторе и замените строку

EnableLogging=0

на

EnableLogging=1

Программа начнет записывать отчет о своей деятельности в директории /var/log/usb_modeswitch_<device>.

Если вы выставили правильные параметры вашего устройства и проделали все фокусы из раздела Поддерживаемые гаджеты, USB_ModeSwitch что-то раз за разом делает, а толку нет, то скорее всего виноваты какие-то проблемы с системой.

Первое подозрение падает на системные правила для модемов, которые могут быть прописаны не вполне корректно.
Если ваш прибор до переключения режима имеет ID 05c6:1000, то в старых системах он может получать неверную переключающую команду. Существует четыре различных бистабильных прибора с этим ID, в больших дистрибутивах они все указываются как устройства от производителя "Option", что неверно в четырех случаях из пяти. Есть даже мобильные телефоны с этим ID, которые также неверно интерпретируются при подключении по USB.

Чтобы решить проблему, можно попытаться удалить файлы правил из директории "/lib/udev/rules.d", содержащие обращения к "modem-modeswitch". После удаления, USB_ModeSwitch произведет дополнительное расследование вне USB ID и обработает подозрительные устройства должным образом. Например, не будет рассматривать неизвестные устройства с ID 05c6:1000.

Другой печально известный "подозреваемый" ≈ снова 19d2:2000. Он может нормально подключаться по существующим правилам udev, но, если модель у вас новая и ее ID еще не прописан в модуле "option", драйвер к нему не загружается.
Нужно дать команду "eject" и тогда usb_modeswitch "подхватит" устройство с этим ID.

Проблемы связанные с ядром

Некоторые новейшие ядра обрабатывают определенные устройства таким образом, что переключения режимов не требуется. Для этих устройств больше не нужна USB_ModeSwitch; но, с другой стороны, уже не получится заглянуть в "CD-ROM" такого гаджета. Больше того, бывали случаи, когда подобного рада обработка не удавалась сама и препятствовала программе USB_ModeSwitch правильно сработать (случалось с гаджетами ZTE, error "-2").

Если у вас происходит подобное, загляните в "unusual_devs.h" в папке "drivers/usb/storage" исходника вашего ядра. Если там есть ваш ID (вендора и продукта в режиме накопителя) и USB_ModeSwitch генерирует ошибки, первым делом попробуйте занести "usb-storage" в черный список (blacklist).
Если это помогло, остается перекомпилировать ядро с дезактивированным пунктом "unusual_devs.h". После этого накопитель usb-storage будет работать в обычном режиме (а не в особом как до того). В Russian Gentoo wiki я нашел совет проделывать именно такие манипуляции с ZTE MF626.
Между прочим, разработчиками USB была достигнута договоренность не включать кода переключающего режимы в ядро, если возможно проделать это в пользовательском пространстве "user space".

Другим параметром, влияющим на поведение ядра является"delay_use" из "usb-storage", который устанавливает отрезок времени (в секундах после подсоединения) в течении которого устройство будет использоваться (и, возможно, автомонтироваться). По умолчанию задано 5 секунд; при определенных условиях это может влиять на результат переключения режимов.
Для изменения параметра добавьте в /etc/modprobe.conf:

options usb-storage delay_use=1 (или 10, или сколько хотите)

Старые системы (например CentOS 5 или Xandros 6)

Если вы пользуетесь не самой свежей системой (с ядром ниже 2.6.27), то можете натолкнуться на несовместимость между версиями "udev" (менеджера устройств). Если у вас не видно деятельности никаких компонентов usb_modeswitch (совсем нет его логов), то проделайте следующие шаги:

• Проверьте, нет ли в директории "/lib/udev/rules.d" других файлов кроме "40-usb_modeswitch.rules". Если нет, то переместите этот файл в директорию "/etc/udev/rules.d".
• Если не помогло, то проверьте другие файлы в директории "/etc/udev/rules.d" на предмет наличия строки"ATTRS". Если таковой нет, то отредактируйте файл "40-usb_modeswitch.rules", заменив все "ATTR" и "ATTRS" на "SYSFS". Сохраните изменения и проверьте как стало работать после переподключения.
• В особо сложных случаях "бездействия" может понадобиться анализ деятельности udev; это делается редактированием файла "/etc/udev/udev.conf" с заменой режима ведения логов на "debug" (udev_log="debug" /прим. переводчика/).

Сотрудничество

USB_ModeSwitch оставляет простор для экспериментов с неподдерживаемыми пока гаджетами.

Стоит попытаться использовать для новых гаджетов широко применяемые методы переключения режимов от уже известных устройств, как скажем, последовательность "eject" из файла "12d1:1446" устройства BandLuxe. Если же есть намеки, что ваш девайс сработан Huawei, то попробуйте последовательность из файла "12d1:1446". Не бойтесь повредить устройство, применение неправильной последовательности не может сломать девайс. Не забудьте только переподключать прибор после каждой попытки!

Коли ничто не помогает, попробуйте такой подход: Заметьте Vendor и Product ID прибора из /proc/bus/usb/devices (или из вывода команды "lsusb"); обычно соответствующий драйвер ≈ "usb-storage". Затем прошпионьте USB-коммуникации устройства с данным ID под M$ Windoze, после инсталляции им своих драйверов. Там ведь тоже произойдет переключение режима и вы можете поймать этот момент в логах. Рекомендую следующую программу: "SniffUSB"(http://www.pcausa.com/Utilities/UsbSnoop/default.htm).

Я кратко объяснил. Очень хороший пример Mark A. Ziesemer опубликовал в Alltel UM175AL USB EVDO under Ubuntu Hardy Heron

Все ваши наработки и открытия, информацию по новым гаджетам и отчеты об ошибках прошу постить на форуме ModeSwitchForum!
Если вам не нужна огласка, можете прислать мне старомодное и конфиденциальное (при желании) e-mail. Адрес найдете на сайте оригинала данной статьи в конце /прим. переводчика/.

 

---

---