Device object

USB device objects have names in the form: usb-bus_number.device_number. You can run multiple instances of the USB stack, each identified by a unique number. If you invoke the USB launcher service (usblauncher_otg) with the -S stackno option, the name of the device object includes the stack number in front of the bus number. For instance, for a USB device with a stack number of 0, a bus number of 1, and a device number of 3, the device control object would be named usb-0.1.3.

Each device object that the USB launcher service writes to PPS can contain the following fields:
Name Description Type Example
bus Bus type String USB
busno Bus number Integer 0x00
configuration Selected configuration Integer 1
configurations Number of configurations Integer 1
device_class Device class ID Integer 0xff
device_protocol Device protocol (present only if device_class is nonzero) Integer 0xff
device_subclass Device subclass ID (present only if device_class is nonzero) Integer 0x00
devno Device number Integer 0x04
drivers_matched Number of drivers matching the device based on the configuration file rules. A value of 0 means the device is unsupported. Integer 1
drivers_running Number of drivers launched for the device. This value can be less than drivers_matched if some drivers haven't been started yet or if some have terminated (possibly in error). Integer 0
manufacturer Manufacturer name, as given in device descriptors received from USB stack String Kingston
max_packet_size Maximum packet size Integer 64
num_ports For USB hubs, the number of downstream ports (present only in device objects for hubs) Integer 4
portno Port number of the downstream port on a USB hub with an overcurrent condition (present only in overcurrent device objects) Integer 3

Filename of the PPS device object that represents the upstream USB hub (this field is present only if the -E option was issued). An empty string means the device is attached to a root port and not a hub.

This field is useful for validating your setup when hubs are connected; for example, if your application has to monitor the number of cascaded hubs and generate an error if a certain limit is reached.

String /pps/qnx/device/usb-1.2
product Product name String DataTraveler G3
product_id OEM product ID Integer 0x1624
serial_number Product serial number String with a vendor-defined length and format 07D22494

USB stack number specified with -S command-line option for the USB launcher service.

This field differentiates devices that have the same bus number (busno) and device number (devno) but are managed by different instances of the io-usb-otg stack.

Integer 0
status Device status. Normally, this field is present only when the device is being reset; the field is deleted when the reset completes. Integer followed by string: status (message) When the device is being reset, this field contains: -1 (Device reset)
topology Duplicates upstream device and port numbers (devno, upstream_port) and provides upstream information for hub chain. String containing integers in ordered pairs

This value indicates that a USB device is attached to hub 2, port 1, and the hub is connected to the root device, port 2.

upstream_device_address USB address where the device is connected. When the device is connected to the root port of a host controller, this field is 0. When the device is connected to a USB hub, this field contains the hub's address. Integer 1

Host controller number. If you have multiple USB controllers, this field contains the number of the controller that detected the device. If you have a single controller, the field is 0.

The field value is the position of the controller's DLL, as named in the USB stack command. For example, if the stack command line names 3 controllers, the value could be 0, 1, or 2 (where 0 is the controller whose DLL is listed leftmost in the command string).

Integer 0
upstream_port Port number. When the device is connected to a hub, this field contains the port number on the hub. When the device is connected to the root port of a host controller, this field is 0. Integer 4
upstream_port_speed Port speed String, set to one of High, Low, or Full High

ID of the vendor of the active device feature. This field may refer to a different vendor than the device manufacturer; for instance, a device using the AOA protocol has a vendor ID of 0x18D1, which refers to Google, because they make the AOA feature.

You can find the full list of possible vendors in the Using Hardware Devices page in the Android docs.

Integer 0x018D1

USB hub objects

When the user device is attached to a USB hub instead directly to a host controller on the target, the USB launcher service publishes an additional device object that represents the device's upstream USB hub (assuming the service was started with the launcher's -E option). This object contains the same fields as objects for non-hub devices but also specifies the number of downstream ports, in the num_ports entry.

A partial device object for a hub looks like this:

The device class is 0x09 and the device subclass is 0x00. The following protocols are supported:
  • 0x00 — Full-speed hub
  • 0x01 — Hi-speed hub with a single transaction translator
  • 0x02 — Hi-speed hub with multiple transaction translators

Overcurrent condition

When the USB stack notifies the USB launcher service of an overcurrent condition, the service publishes a special device object representing the USB hub that is reporting the condition. The object doesn't provide information on the device causing the condition; in fact, the device is taken off the USB bus and its device, driver, and mount PPS objects are deleted.

The filename of the object is in this format: usb-overcurrent-stackno.busno.devno.portno. The stack number (stackno) is present only if you ran usblauncher_otg with the -S option.

Here's an example of the complete object :

status::-1 (Overcurrent)

When the overcurrent condition is cleared, the overcurrent object is deleted.

Bad devices

When enumeration fails, the USB stack sends a notification to listeners, including the USB launcher service, indicating that it detected a bad device on a given port. In response, the USB launcher service publishes a device object with fewer attributes than normal to describe the “bad” device. Also, the object's filename is in a different format: usb-stackno.upstream_device_address.upstream_host_controller.upstream_port. The filename contains the stack number (stackno) only if you started USB launcher with the -S option.

Here's an example of what the complete object looks like:

status::48 (Not supported)