Device control object

The device control object allows applications to perform actions on USB hardware and manipulate the USB launcher configuration.

Applications can publish the following commands to the object:
Use this command: To:
HUB Set the power state of a USB hub, or toggle the power on or off.
LUA Modify the USB launcher configuration.
In response, the USB launcher service publishes the following command outcomes to the object:
Outcome Description
cmd_status The processing status of the last command issued by any client application. Available to all clients of this object.
last_cmd The last command that was successfully processed by a client. Available only to the client that issued the command.

Each instance of the USB launcher service, usblauncher_otg, creates a device control object. By default, the object's path is /pps/qnx/device/usb_ctrl, but you can change the path through command options to USB launcher.

You can run multiple instances of the USB stack, io-usb-otg, each identified by a unique number. The name of the device control object includes this stack number if you start the USB launcher service with the -S stackno option.

For instance, if you issue the command usblauncher_otg -S 1, the service creates a PPS object named /pps/qnx/device/usb_ctrl1. You must use this option to distinguish between control objects if you want to run multiple USB launcher instances and use the same PPS directory for all their device control objects. (You may want to run multiple launcher instances if, for example, you need to manage different controllers independently. In that case, the ports for each controller would be managed by a separate instance of the USB stack.)

HUB

The HUB command has two forms:

Attribute Description Type
busno Bus number of the hub Integer
devno Device number of the hub Integer
level Set the power off (0) or on (1). Boolean
portno

Port number.

If you issue a HUB::port_power command and omit portno, the specified level applies to all ports on the hub.

Likewise, if you issue a HUB::toggle_port_power command and omit portno, the command toggles the power of all ports on the hub. You must include portno if you specify a delay.

Integer
delay The delay, in milliseconds. Default is 500. Integer

You can specify the values for busno, devno, portno, and delay in decimal or hex. The values for busno and devno typically fall in the range of 0 to 64.

LUA

The LUA feature lets you manipulate the USB launcher configuration.

The command string begins with LUA:: (to tell USB launcher that you're accessing Lua functionality) and ends with a command name and a list of arguments:

LUA::lua_cmd,args

The command name and the individual arguments are separated by commas, and the arguments consist of key-value pairs with an equal sign (=) separating each key and value.

You can issue the following commands:
Command Description
setvar,table_name[variable]=value

Override a table variable to change the behavior of a Lua callout function.

For example, the following command sets the busy flag to prevent MirrorLink from starting automatically:

LUA::setvar,MirrorLink[busy]=true

setvar,variable=value Override a global variable to change the behavior of a Lua callout function.
getvar,table_name[variable] Get the value of a table variable.
getvar,variable Get the value of a global variable.
run,function Run a custom function defined in the main configuration file.

Table variables and global variables are stored in the main configuration file, rules.lua.

When you issue a setvar or getvar command, the command validates the existence of the variable and, if specified, the table. If one of these doesn't exist or if the value doesn't match the type of the variable, an error is returned.

Note: You can name only one variable per setvar or getvar command.

Currently, the LUA feature supports only the LUA_STRING, LUA_BOOLEAN, and LUA_NUMBER types.

Command outcomes

When the USB launcher service executes commands, it publishes the following attributes to the device control object:
Attribute Description Type Example
cmd_status

The processing status of the last command issued by any client. USB launcher broadcasts each update to this attribute to all clients of this object, not just to the one that issued the command.

When USB launcher receives a new command, it publishes the processing status to cmd_status and to slogger2. The attribute value and log message say whether the command was successfully processed or not (for instance, if an illegal operation was requested).

Note: Even for unrecognized commands, USB launcher writes an error message to this attribute and to slogger2.

An error string in the following format:

last_command,
 completion_status 
 =errno 
 (str_error(errno)) 

If the command is processed successfully, this field contains:

0 (No error)

If the client specifies an improper bus number or device number (or both), this field contains:

19 (No such device)
last_cmd

The last command that was successfully processed, its completion status, and, in some cases, its execution details. Only the client that issued the command receives notification; the update isn't broadcast.

USB launcher updates this attribute when it finishes processing a command, whether the underlying request succeeded or not.

In some cases, USB launcher reads USB stack descriptors and includes their information in the new attribute value.

A string in this format:

last_command,
 completion_status 
 =errno
 (str_error(errno)) 
 [, details::
 extra_details] 
If a LUA getvar command succeeds, this field contains a string like the following:
last_cmd::LUA,
completion_status=0 
   (No error), 
lua_type::1, 
lua_value::false
where lua_type indicates the type of variable and lua_value indicates the value that getvar read from the variable.