usb.core
Class Hub

java.lang.Object
  |
  +--usb.core.Descriptor
        |
        +--usb.core.Hub

All Implemented Interfaces:

java.io.Serializable

public final class Hub

extends Descriptor

Bundles access to a USB Hub descriptor and some hub operations. You will access underlying device directly, to examine and modify hub state, but for many purposes will use constants (notably feature IDs) and hub data as exposed through this class.

The hub class is defined in chapter 11 of the USB specification, and you'll need the later sections of that chapter to talk to a hub. You'll use setFeature and clearFeature to change feature flags, and getStatus or the hub descriptor (many methods on this class) for your indicators.

Because the kernel hub driver claims exclusive access to the hub interrupt endpoint (the hub "status change pipe"), user mode programs don't have direct access to that data. It's a stream of masks, often one byte each, with a bit set for each port with a status change (C_PORT_*) notification bit set. You can access much of the same information by hub and port status queries. If you see change notifications (C_*) managed by the kernel driver, do not clear or respond to these.

Note that for consistency with USB itself, port numbers start with one instead of zero.

See Also:

Serialized Form

Field Summary

static byte	C_HUB_LOCAL_POWER Hub change indicator, indicating local power
static byte	C_HUB_OVER_CURRENT Hub change indicator, indicating overcurrent status (for safety).
static byte	C_PORT_CONNECTION Port feature selector, indicating a device was attached or detached.
static byte	C_PORT_ENABLE Port feature selector, indicating a port disabled due to error.
static byte	C_PORT_OVER_CURRENT Port feature selector, reporting changed per-port overcurrent status.
static byte	C_PORT_RESET Port feature selector, indicating reset processing is complete.
static byte	C_PORT_SUSPEND Port feature selector, indicating port resume is complete.
static byte	PORT_CONNECTION Port feature selector, indicating whether a device is connected.
static byte	PORT_ENABLE Port feature selector, controlling whether the port is enabled.
static byte	PORT_HIGH_SPEED Port feature selector, indicates if an enabled port runs at low/full speed or at high speed.
static byte	PORT_INDICATOR Port feature selector, indicates if enabled port has an indicator.
static byte	PORT_LOW_SPEED Port feature selector, indicates if an enabled port is low speed USB.
static byte	PORT_OVER_CURRENT Port feature selector, indicating an overcurrent state for the port.
static byte	PORT_POWER Port feature selector, controlling power availability to this port (subject to gang power switching rules).
static byte	PORT_RESET Port feature selector, set to initiate a port reset.
static byte	PORT_SUSPEND Port feature selector, controlling "suspend" state for the port.
static byte	PORT_TEST Port feature selector, indicates if an enabled port is test mode.

Fields inherited from class usb.core.Descriptor

CLASS_APP_SPECIFIC, CLASS_AUDIO, CLASS_COMM, CLASS_DATA, CLASS_HID, CLASS_HUB, CLASS_MASS_STORAGE, CLASS_PRINTER, CLASS_VENDOR_SPECIFIC, TYPE_CONFIGURATION, TYPE_DEVICE, TYPE_DEVICE_QUALIFIER, TYPE_ENDPOINT, TYPE_HID, TYPE_HUB, TYPE_INTERFACE, TYPE_INTERFACE_POWER, TYPE_OTHER_SPEED, TYPE_PHYSICAL, TYPE_REPORT, TYPE_STRING

Constructor Summary

Hub(Device dev)
Constructs a hub object wrapping the specified USB hub device.

Method Summary

Device	getDevice() Returns the device with which this USB object is associated.
int	getHubCharacteristics() Returns the hub characteristics bitmap.
int	getHubCurrent() Returns the maximum current requirement of the hub electronics, in mA units.
int	getNumPorts() Returns the number of ports on this hub.
java.lang.String	getOverCurrentMode() Returns the overcurrent protection mode, "global", "per-port"; or only for USB 1.0 hubs, "none".
int	getPOTPGT() Returns the power-on to power-good time, in units of 2ms.
java.lang.String	getPowerSwitchingMode() Returns the power logical power switching mode, "ganged", "switched", or otherwise indicating an old USB 1.0 hub.
boolean	isCompound() Returns true if this hub is part of a compound device.
boolean	isIndicator() Returns true iff the hub supports status indicators.
boolean	isRemovable(int port) Returns true if the specified port (one-based) is removable.
boolean	isRootHub() Returns true if this is the root hub.
void	reset(int port) Resets the port (and the device connected to it).
void	resume(int port) Resumes the port.
void	suspend(int port) Suspends the port.

Methods inherited from class usb.core.Descriptor

getBCD, getClassName, getDescriptorType, getDescriptorTypeName, getLength, getU16, getU32, getU8, nextDescriptor

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

C_HUB_LOCAL_POWER

public static final byte C_HUB_LOCAL_POWER

Hub change indicator, indicating local power

C_HUB_OVER_CURRENT

public static final byte C_HUB_OVER_CURRENT

Hub change indicator, indicating overcurrent status (for safety).

PORT_CONNECTION

public static final byte PORT_CONNECTION

Port feature selector, indicating whether a device is connected.

PORT_ENABLE

public static final byte PORT_ENABLE

Port feature selector, controlling whether the port is enabled.

PORT_SUSPEND

public static final byte PORT_SUSPEND

Port feature selector, controlling "suspend" state for the port.

PORT_OVER_CURRENT

public static final byte PORT_OVER_CURRENT

Port feature selector, indicating an overcurrent state for the port.

PORT_RESET

public static final byte PORT_RESET

Port feature selector, set to initiate a port reset.

PORT_POWER

public static final byte PORT_POWER

Port feature selector, controlling power availability to this port (subject to gang power switching rules).

PORT_LOW_SPEED

public static final byte PORT_LOW_SPEED

Port feature selector, indicates if an enabled port is low speed USB.

PORT_HIGH_SPEED

public static final byte PORT_HIGH_SPEED

Port feature selector, indicates if an enabled port runs at low/full speed or at high speed.

PORT_TEST

public static final byte PORT_TEST

Port feature selector, indicates if an enabled port is test mode.

PORT_INDICATOR

public static final byte PORT_INDICATOR

Port feature selector, indicates if enabled port has an indicator.

C_PORT_CONNECTION

public static final byte C_PORT_CONNECTION

Port feature selector, indicating a device was attached or detached.

C_PORT_ENABLE

public static final byte C_PORT_ENABLE

Port feature selector, indicating a port disabled due to error.

C_PORT_SUSPEND

public static final byte C_PORT_SUSPEND

Port feature selector, indicating port resume is complete.

C_PORT_OVER_CURRENT

public static final byte C_PORT_OVER_CURRENT

Port feature selector, reporting changed per-port overcurrent status.

C_PORT_RESET

public static final byte C_PORT_RESET

Port feature selector, indicating reset processing is complete.

Constructor Detail

Hub

public Hub(Device dev)
    throws java.io.IOException

Constructs a hub object wrapping the specified USB hub device.

Method Detail

getDevice

public Device getDevice()

Description copied from class: Descriptor

Returns the device with which this USB object is associated.

Overrides:

getDevice in class Descriptor

isRootHub

public boolean isRootHub()
                  throws java.io.IOException

Returns true if this is the root hub.

getNumPorts

public int getNumPorts()

Returns the number of ports on this hub. USB ports are numbered beginning at one.

getHubCharacteristics

public int getHubCharacteristics()

Returns the hub characteristics bitmap.

See Also:

getPowerSwitchingMode(), isCompound(), getOverCurrentMode()

getPowerSwitchingMode

public java.lang.String getPowerSwitchingMode()

Returns the power logical power switching mode, "ganged", "switched", or otherwise indicating an old USB 1.0 hub.

isCompound

public boolean isCompound()

Returns true if this hub is part of a compound device.

getOverCurrentMode

public java.lang.String getOverCurrentMode()

Returns the overcurrent protection mode, "global", "per-port"; or only for USB 1.0 hubs, "none".

isIndicator

public boolean isIndicator()

Returns true iff the hub supports status indicators. These are LEDs that can display as either green or amber. Normally they are used in an automatic mode where the indicator is off if no device is attached, and shows a solid green to indicate normal functioning. A solid amber indicates some kind of error. Under software control, the indicator can also blink.

getPOTPGT

public int getPOTPGT()

Returns the power-on to power-good time, in units of 2ms.

getHubCurrent

public int getHubCurrent()

Returns the maximum current requirement of the hub electronics, in mA units.

isRemovable

public boolean isRemovable(int port)

Returns true if the specified port (one-based) is removable. Non-removable ports may be built in to compound devices, such as keyboards with built-in hubs.

suspend

public void suspend(int port)
             throws java.io.IOException

Suspends the port. Port must be operational. It will resume automatically if necessarary, or by explicit resume().

Use with caution; parent/child relationships are tricky, you may not affect the device you intend.

resume

public void resume(int port)
            throws java.io.IOException

Resumes the port. Ignored if port isn't suspended.

Use with caution; parent/child relationships are tricky, you may not affect the device you intend.

reset

public void reset(int port)
           throws java.io.IOException

Resets the port (and the device connected to it).

Use with caution; parent/child relationships are tricky, you may not affect the device you intend.