Command line for USB launcher service (usblauncher_otg)

Synopsis

usblauncher_otg [-0] [-b] [-C] [-c config] [-d dll [opts]] [-E] [-e]  
                [-L] [-l] [-M mnt_rules] [-m pps_path] [-n name] [-P]
                [-p seconds] [-r] [-S stackno] [-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 don't use the launcher service to support Apple CarPlay (and hence, don't run any 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 (not background). This option is handy for debugging because you can press Ctrl–C to terminate the publisher. By default, usblauncher_otg runs in the background.

-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 USB stack never to set the device configuration at enumeration time. Note that this stack option doesn't affect hubs—their configurations are always set by the stack.

We recommend using the -C option for usblauncher_otg and io-usb-otg when supporting MirrorLink devices, because it makes usblauncher_otg set the configuration after sending the NCM request.

-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, usblauncher_otg looks for the default file, /etc/usblauncher/rules.lua. In this case, this file must exist or usblauncher_otg 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 use when running in USB device mode, you can include these descriptor 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 QNX Multimedia Suite.

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. This option requires the -e option. By default, usblauncher_otg doesn't report whether a device is connected directly to the target system or through a USB hub.

You must set -E to publish device 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-swapping of the USB stack, based on which type of hub and which hub port a device is connected to.

-e

Enable detection of extra events; specifically, bad device attachments and detachments as well as device resets. By default, usblauncher_otg doesn't detect and publish information about these extra events.

-L

Run in local mode, even when the Qnet networking protocol is running.

The -L option can help simplify configuration for standalone systems. You should use it only when Qnet is running (e.g., for debugging). When usblauncher_otg runs in local mode, it:

• doesn't add the network prefix to paths it generates
• expects all paths it receives to already have the network prefix

-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

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 USB launcher mount rules found in /etc/usblauncher/rules.mnt. In this 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 usblauncher_otg from auto-mounting USB devices.

-m pps_path

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

-n name

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

-P

Probe the media to get the partition count only if the device is ready. By default, usblauncher_otg doesn't wait until the device is ready to try to obtain the partition 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. Default is 0. Note that polling can be CPU-intensive and result in 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 terminate the USB device stack after receiving a suspension event following a configuration event.

-S stackno

Use the specified USB stack 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 stack.

-s dll_path

Use the specified plugin path. At startup, usblauncher_otg 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]...

Override the output verbosity level. Setting one v logs USB device attachments and detachments. Setting two v's adds the logging of PPS object creation and deletion. Setting three or four v's logs more detailed events as well as errors that are less severe.

Increasing the output verbosity 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 PPS. The service can also force a re-enumeration of a device, by resetting it or by requesting that it change its personality.

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 usblauncher_otg command line in a startup script to automatically launch the service during bootup.

Examples

Use /etc/enum.lua as the configuration file and look for plugins in /lib/dll/pubs:

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

Store PPS objects in /ramdisk/pps, get the partition count only if the device is ready, and direct output to standard out:

usblauncher_otg -m /ramdisk/pps -P -vv