Start usblauncher device enumerator and publisher
Synopsis:
usblauncher [-b] [-C] [-c config_file] [-e] [-h] [-l]
[-M mnt_rules] [-m pps_path] [-n stack_name] [-P]
[-p seconds] [-r] [-S stack_number] [-s dll_path] [-t] [-v]
Options:
- -b
- Run usblauncher in the foreground.
This option is handy for debugging because you can press CtrlC to terminate
the publisher.
- By default, usblauncher runs in the background.
- -C
- Always set the device configuration when attaching a device.
This option should be used alongside the io-usb -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 both usblauncher and io-usb
when supporting MirrorLink devices, which will make usblauncher set the configuration after sending
the NCM request.
- By default, usblauncher selects a configuration only for devices with multiple configurations,
based on the first driver that matches the device.
- -c config_file
- The configuration file. At startup, usblauncher reads this file to learn the USB device-matching rules
for different device types. These rules indicate which driver to launch for communicating with the device as well as which
command options to provide to the driver.
- If you don't specify a configuration file, usblauncher looks for the default file
(/etc/usblauncher/rules.lua). In this case, the default file must exist or
usblauncher won't run.
- The configuration file named with this command option can include other Lua files by using the dofile()
command. For example, if you use separate files to define various descriptors to use when running in USB device mode,
you can include these descriptor files in the main configuration file.
- -e
- Enable detection of extra events; specifically, bad device attachments and detachments as well as device resets.
- By default, usblauncher doesn't detect and publish information about these extra events.
- -h
-
Prevent the USB stack from starting in host mode, which is the default behaviour.
Use this option when you want to support OTG but your client application will decide which stack version to start and
then issue the start_stack command through PPS to tell usblauncher when to start a stack.
- -l
- Log messages to sloginfo instead of standard out.
- By default, usblauncher logs messages to standard out.
- -M mnt_rules
- The mountpoint file, which tells usblauncher 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
mcd mountpoint file (/etc/mcd.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 the -M option if you want to assign nondefault mountpoints to devices.
You can also name an empty file to prevent usblauncher from mounting USB devices (see
"Disabling usblauncher auto-mounter" for details).
- -m pps_path
- The 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 stack_name
- The server name of the USB stack. The default is /dev/io-usb/io-usb. Use this option only if
you don't support OTG and always run the USB host stack (io-usb), never the USB device stack
(io-usb-dcd), and if your USB host stack is stored at a nondefault location.
- If you want to support OTG and use nondefault USB stack paths, you must define these paths in the
Host_Stack and Device_Stack rules in the configuration file.
- -P
- Probe the media to get the partition count only if the device is ready.
- By default, usblauncher doesn't wait until the device is ready to try to obtain the partition count.
- -p seconds
- The polling interval (in seconds), which is how often usblauncher checks for changes to the
mountpoints associated with the active drivers.
- The default interval is three seconds.
- -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 terminate the USB device stack
after receiving a suspension event following a configuration event.
- -S stack_number
- The USB stack number. The usblauncher service stores this value in the information for each USB device
it monitors, to differentiate the device from others that have the same bus number and device number but are managed by
other io-usb servers.
- -s dll_path
- The plugin path. At startup, usblauncher looks in this path for plugins it can load and then use to
provide more detailed device information (see "Media Player Plugins").
- If this option isn't specified, no plugins are loaded.
- -t
- Terminate launched drivers when exiting.
- By default, usblauncher doesn't terminate driver processes
while deleting device and driver objects during shutdown.
- -v
- Increase output verbosity. The -v option is cumulative, so you can use several v's to
increase verbosity. 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.
- Output verbosity is handy when you're trying to understand the operation of usblauncher. However, when
lots of -v arguments are used, the logging becomes quite significant. The 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 with an explicit command only if the process terminates unexpectedly.
Before trying to start
usblauncher manually, always confirm that the process isn't already running by checking
the list of active processes with
pidin or
ps.
If you want to restart only the USB stack, send the
start_stack command to the
device control object.
The usblauncher command starts a multipurpose service that enumerates USB devices, launches drivers for
communicating with those devices, and publishes their information through PPS.
On the command line, you can override the default configuration file to provide usblauncher with a set of
custom rules for configuring different device types.
You can also name your own mountpoint file to mount filesystems to nondefault locations, set how often
usblauncher checks for mountpoint updates, and configure how it logs error and event information.
By default, usblauncher starts the USB stack in host mode, assuming you've defined the appropriate rules
in the configuration file. You can prevent the launching of this stack by using the -h option, if you plan to
use your system as the USB device.
The usblauncher service runs as a self-contained process that doesn't require any user input.
It has no client utility for performing device-publishing tasks on request or for adjusting any of its settings.
You can restart the USB stack in a different role by issuing the start_stack command through PPS, but to reconfigure
usblauncher in any other way, you must change the options in its command line and restart the service.
We recommend putting the usblauncher command line in a startup script (e.g., startup.sh)
to automatically launch the service during bootup.