Command line for USB launcher service (usblauncher_otg)

Synopsis

usblauncher_otg [-0] [-b] [-C] [-c config] [-d dll [opts]] [-E]
                [-l] [-M mnt_rules] [-m pub_path] [-n name] [-P]
                [-p seconds] [-r] [-S server_number] [-s dll_path] [-t]
                [-v[v]...]

Options

-0

(zero) Enable host events, including insertions and removals, on bus 0. Bus 0 refers to the first DLL listed in the io-usb-otg command line. This option allows you to use usblauncher_otg in systems where it manages a host-only port, such as when it is used in a virtual machine.

If you use the launcher service to role-switch (i.e., you're running USB device mode drivers through this service), you should always specify this option because you will likely have your host controller on bus 0.

-b

Run usblauncher_otg in the foreground instead of the background, which is the default behavior. Setting this option is handy for debugging because you can press Ctrl C to terminate the service.

-C

Always select a configuration when a device is attached. By default, usblauncher_otg selects a configuration only for devices with multiple configurations, based on the first driver that matches the device.

You should use this option alongside the io-usb-otg -C option, which tells the latter server utility never to set the device configuration at enumeration time.

-c config

Use the specified configuration file. At startup, usblauncher_otg reads this file to learn the USB matching rules, which specify how to process devices when they're attached.

If you don't specify a configuration file, the service looks for the default file, /etc/usblauncher/rules.lua. In this case, this file must exist or the service won't run.

The main configuration file named with this option can include other Lua files by using the dofile() command. For example, if you use separate files to define descriptors to expose when running in USB device mode, you can include these other files in the main file.

-d module

Load the specified module, either Android or Apple. The Android module lets a process request a device personality switch to support certain applications. The Apple module can check which protocol a device supports and role-swap the server, which entails changing the controller's role from USB host to USB device. Instructions on doing so are given in the Working with Apple Devices guide, which is part of the Apple Device Support package for the Multimedia for QNX SDP.

These modules allow smartphones to project their UIs onto the target system's display. Information on configuring the USB launcher service to support projection technologies is given in the Smartphone Connectivity Developer's Guide, which is part of the QNX SDK for Smartphone Connectivity package.

-E

Publish USB hub information. By default, usblauncher_otg doesn't report whether a device is connected directly to the target or whether it's connected through a hub. If the device doesn't have a hub, usblauncher_otg still publishes information about the parent via the topology stream or upstream section of the published device information.

You must set -E to publish device information objects for USB hubs as well as information about the upstream hub for other devices connected to a hub. You can use this information to decide whether to allow role-switching of the USB server, based on which type of hub and which hub port a device is connected to.

-l

Log messages to slog2info instead of to standard out (which is the default behavior). This option increases the verbosity level to -vvv, unless you use the -v option to set a different verbosity level.

-M mnt_rules

Specify the mount-rules file, which tells usblauncher_otg where to mount the filesystems of devices represented by particular /dev entries. Any file named with this option must be in the same format as the default mount rules found in /etc/usblauncher/rules.mnt.

In the mount rules file, you can name not only mountpoints but also the mount options provided to the filesystem library, such as codepage mapping or long-filename handling in fs-dos.

Use this option if you want to assign nondefault mountpoints to devices. You can also name an empty file or /dev/null to prevent the service from auto-mounting USB devices.

-m pub_path

Use the specified publisher directory path. The subdirectories for storing the device, device control, driver, and mount objects are located in this directory. The default is /usb/launcher/.

-n name

The server name of the USB server. The default is /dev/usb/io-usb-otg. Use this option only if the server is stored in a nondefault location.

-P

Probe the device to get its partition count only if it's ready. By default, usblauncher_otg doesn't wait until the device is ready to try to obtain the count.

-p seconds

The polling interval, in seconds, that determines how often usblauncher_otg checks for changes to the mountpoints associated with the active drivers. The default is 0. Note that polling can be CPU-intensive and cause a significant amount of logging.

-r

Treat a device suspension event as a cable removal event. Some devices don't generate removal events, so you can set this option to make usblauncher_otg force the server to change its role from device to host after receiving a configuration event followed by a suspension event.

-S server_number

Use the specified USB server (io-usb-otg) number. The usblauncher_otg service stores this value in the information for each USB device that it monitors, to differentiate the device from others that have the same bus number and device number but are managed by other instances of the io-usb-otg server.

-s dll_path

Use the specified plugin path. At startup, the service looks in this path for plugins that it can load and use to provide more device details (for more information, see Plugins).

If this option isn't specified, no plugins are loaded.

-t

Terminate launched drivers when exiting. By default, usblauncher_otg doesn't terminate driver processes while deleting device and driver objects during shutdown.

-v[v]...

Increase the level of output verbosity. You can specify additional -v arguments to increase the verbosity. This is handy when you're trying to understand the operation of usblauncher_otg. However, when lots of -v arguments are used, the logging becomes quite significant. A higher verbosity setting is good for systems under development but probably shouldn't be used in production systems or during performance testing.

Description

The usblauncher_otg command starts a multipurpose service that responds to USB device attachments and detachments, launches drivers for communicating with the devices, and publishes their information through RMPS. The service can also force a re-enumeration of a device, by resetting it or by requesting that it change its USB role.

On the command line, you can name a nondefault configuration file to make usblauncher_otg use a custom set of rules for configuring various device types. You can also name your own mount-rules file to mount filesystems to nondefault locations, and configure how errors and events are logged.

To reconfigure usblauncher_otg, you must restart it with new command-line options. For a production environment, we highly recommend putting the command line in a startup script to automatically launch the service during bootup.

Examples

usblauncher_otg -c /etc/enum.lua -s /lib/dll/pubs

usblauncher_otg -0 -E -n /dev/usb/io-usb-otg \z
 -c /option/etc/usblauncher/rules.lua -s /base/lib/dll/pubs/