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:

port_power — Set the power state of a USB hub. You can use this command to repower a port if the upstream hub has disabled it (for instance, because of an overcurrent condition that may no longer apply). Here's the command syntax:
```
   HUB::port_power,busno=n,devno=n,level=boolean[,portno=n]
```
toggle_power_power — Turn a hub's power off, wait for a fixed delay, then turn the power back on. Here's the command syntax:
```
   HUB::toggle_port_power,busno=n,devno=n[,portno=n,delay=n]
```

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

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.

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.