Device information object

Updated: April 19, 2023

USB device information objects have names in this general form: usb-bus_number.device_number. You can run multiple instances of the USB server, each with a unique number. If you run usblauncher_otg with the -S server_number option, the name of the device information object includes the server number at the front, as follows: usb-server_number.bus_number.device_number.

Each device information object can contain the following fields:
Name Description Type Example
aoa

Version of Android Open Accessory (AOA) protocol supported by device, either 1 or 2

Number 2
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_release Device release String 1.0
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 rules (0 means it's 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
iap

Whether iPod Accessory Procotol version 2 (iAP2) is supported by the device. This applies only to Apple devices.

Number 2 if iAP2 is supported; -1 if device runs iAP1 or iAP2 probe failed
manufacturer Manufacturer name, as given in device descriptors received from USB server String Kingston
max_packet_size Maximum packet size Integer 64
num_ports For USB hubs, the number of downstream ports (present only in hub device information objects) Integer 4
portno Port number of the downstream port on a USB hub with an overcurrent condition (present only in overcurrent device information objects) Integer 3
PPS_HUB_ID

Filename of the device information object for 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 program must monitor the number of cascaded hubs and report 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
role_swap Status of last role-swap request made of device (this field is present only if such a request was made). If the request succeeded, the field contains a string indicating the reason for role-swapping; if it failed, the field contains an error code and a string describing the failure. String on success, integer followed by string on failure AppleDevice
serial_number Product serial number String with vendor-specific content 07D22494
stackno

USB server number specified with -S option for usblauncher_otg.

This field distinguishes devices with the same bus number (busno) and device number (devno) that are managed by different server instances.

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 (2,1),(0,2)

Here, a USB device is attached to hub 2, port 1, and the hub 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 it's connected to a USB hub, this field contains the hub's address. Integer 1
upstream_host_controller

Host controller number. If you have a single USB controller, this field is 0. If you have multiple USB controllers, this field indicates the controller that detected the device, by storing the position of the controller's DLL as named in the USB server startup command.

Suppose three controllers are named in the startup command. The field value could be 0, 1, or 2, where 0 is the controller whose DLL is listed first.

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, one of High, Low, or Full High
USB_version USB version String 3.0
vendor_id

ID of the vendor of the active device feature. This field may refer to a vendor other 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 feature.

For the full list of vendors, see the Android developer documentation.

Integer 0x018D1

USB hub objects

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

A partial device information object for a hub looks like this:
bus::USB
busno::0x00
devno::0x01
device_class::0x09
device_subclass::0x00
device_protocol::0x02
num_ports::4
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 server notifies the USB launcher service of an overcurrent condition, the service publishes a special device information object representing the USB hub that is reporting the condition. This 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 server number (which is represented by the stackno attribute) is present only if you ran usblauncher_otg with the -S option.

Here's an example of the complete object:
status::-1 (Overcurrent)
bus::USB
stackno::0
busno::0x00
devno::0x01
portno::3

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

Bad devices

When enumeration fails, the USB server notifies its listeners, including the USB launcher service, indicating that it detected a bad device on a given port. In response, the service publishes a device information object with fewer attributes than normal to describe the “bad” device.

The object's filename is in a different format: usb-stackno.upstream_device_address.upstream_host_controller.upstream_port. The filename contains the server number (which is represented by the stackno attribute) only if you ran usblauncher_otg with the -S option.

Here's an example of what the complete object looks like:
status::48 (Not supported)
bus::USB
stackno::0
upstream_device_address::3
upstream_host_controller::0
upstream_port::7
upstream_port_speed::High