Start usblauncher_otg device enumerator and publisher
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 CtrlC 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
Note: You should start usblauncher_otg with an explicit command only if the
process terminates unexpectedly. Before trying to start
usblauncher_otg manually, always confirm that the service
isn't already running by checking the list of active processes with
pidin or ps.
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