USB¶
API Documentation: [cpp] [python] [.NET] [LabVIEW]
The USB Entity provides the software control interface for USB related features. This entity is supported by BrainStem products which have programmatically controlled USB features.
Downstream Channel Control¶
Downstream USB channels can be manipulated through the usb entity command to enable and disable USB data and Vbus lines, measure current, measure Vbus voltage, boost data line signals, and measure temperature.
Manipulating Hi-Speed data and Vbus lines simultaneously for a single port can be done by calling the following methods with channel in [0-3] being the port index:
stem.usb.setPortEnable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setPortDisable(channel) [cpp] [python] [NET] [LabVIEW]
Manipulating Hi-Speed data while not affecting the Vbus lines simultaneously for a single port can be done by calling the following methods with channel [0-3]. The folloing methods provide equivalent functionality; the two methods are offered for compatability with other products.
stem.usb.setDataEnable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setDataDisable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setHiSpeedDataEnable(channel [cpp] [python] [NET] [LabVIEW]
stem.usb.setHiSpeedDataDisable(channel) [cpp] [python] [NET] [LabVIEW]
Manipulating just the USB Vbus line for a single port can be done by calling the following method with channel [0-3]:
stem.usb.setPowerEnable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setPowerDisable(channel) [cpp] [python] [NET] [LabVIEW]
To affect multiple ports and lines simultaneously, see usb.setHubMode() later in this section.
Note that transitions between power and data enables states where power is enabled and only data is changing, require the USBHub2x4 to toggle Vbus power. This apprears as a port cycle event and the USBHub2x4 hardware will cycle Vbus even if the Vbus/Power setting is enabled.
Downstream Measurements¶
The USB Vbus voltage, as well as the current consumed on Vbus, can be read for each channel by calling the following methods with channel [0-3], where the second variable passed into the method is the location for the measurement result:
stem.usb.getPortVoltage(channel, μV) [cpp] [python] [NET] [LabVIEW]
stem.usb.getPortCurrent(channel, μA) [cpp] [python] [NET] [LabVIEW]
Downstream Current Limiting¶
Current-limit trip point settings can be accessed for each port by calling the following methods with channel [0-3], where the second variable passed into the method is either the set value or the write location of the result:
stem.usb.getPortCurrentLimit(channel, μA) [cpp] [python] [NET] [LabVIEW]
stem.usb.setPortCurrentLimit(channel, μA) [cpp] [python] [NET] [LabVIEW]
The current-limiting behavior follows the USB BC1.2 specification which allows for many different behaviors. The USBHub2x4 has two stages of current-limiting. When a downstream device consumes current higher than the programmed current limit, the hub will enter a “constant current” mode and is indicated in the getPortState() bitfield with the constant current bit. In the constant current mode, the Vbus voltage will be reduced to attempt maintain a constant current at the set current limit. The time and amount of voltage reduction and maximum allowed current draw depends on the current limit set point.
As the Vbus voltage is reduced, if the device continues to increase its current draw (reduce it’s effective resistance), the USBHub2x4 will “trip off” by disabling the Vbus and high-speed data lines. This state is indicated with the error bit in the getPortState() bitfield. The Channel X Power error LED will also illuminate when this error occurs. See the LED Indicators.
Downstream Enumeration Speed¶
The enumeration state and speed of each downstream port can be read with
stem.usb.getDownstreamDataSpeed [cpp] [python] [NET] [LabVIEW]
Value |
Hub Downstream Speed Descriptions |
|---|---|
0 |
No device enumerated |
1 |
Hi-Speed device enumerated |
Downstream Operational Mode¶
The USB port operational mode controls the behavior of each downstream port’s charging behavior. Each port can be setup to support different modes in the USB Battery Charge Specification 1.2 (BC1.2). Standard Downstream Port (SDP) mode will cause BC1.2 compliant or older USB devices to consume 500mA or less. Configuring a port as a Charging Downstream Port (CDP) will cause the hub signal to downstream devices that devices may consume up to 5A, the maximum allowed by BC1.2. If there is no upstream USB host connected to the hub, downstream ports set to CDP will behave as Dedicated Charging Ports (DCP).
The actual current consumed by the device is controlled by the downstream device and not the USBHub2x4. Devices which are not compliant with BC1.2 or the previous USB power specifications may draw more current than specified above.
The operational mode is set or read by calling the methods:
stem.usb.getPortMode(mode) [cpp] [python] [NET] [LabVIEW]
stem.usb.setPortMode(mode) [cpp] [python] [NET] [LabVIEW]
Value |
Hub Port Mode Descriptions |
|---|---|
0 |
Standard downstream port (SDP) |
1 |
Charging downstream port (CDP) |
Note
A system.save() and system.reset() is required before the new setting will take affect.
Downstream Enumeration Delay¶
Once a USB device is detected by the USBHub2x4 it is possible to delay its connection to an upstream host computer and subsequent enumeration on the USB bus. The enumeration delay can mitigate or eliminate host kernel instabilities by forcing devices to enumerate in slow succession, allowing a focus on validation of drivers and software. The enumeration delay is configured in milliseconds, representing the time delay between enabling each successive downstream port from 0 to 3. Enumeration delay is applied when the hub powers on or when a new upstream connection is made.
stem.usb.setEnumerationDelay(delay) [cpp] [python] [NET] [LabVIEW]
stem.usb.getEnumberationDelay(delay) [cpp] [python] [NET] [LabVIEW]
Hub Operational Mode¶
In addition to targeting individual downstream USB ports, a bit-mapped hub mode interface is also available. This interface allows the reading or setting of all USB downstream ports in one functional call.
Auto Vbus Toggle
By default the USBHub2x4 will toggle its downstream ports anytime the host connection is lost, changed or disconnected. Disabling (setting the bit) will cause the hub to not cycle downstream power on upstream changes. This behavior can be helpful for certain host controllers and devices. Enumeration delay will override this setting.
stem.usb.getHubMode(mode) [cpp] [python] [NET] [LabVIEW]
stem.usb.setHubMode(mode) [cpp] [python] [NET] [LabVIEW]
This command returns a 32-bit value which indicates:
Bit |
Hub Operational Mode Bitwise Description |
|---|---|
0 |
USB Channel 0 USB Hi-Speed Data Enabled |
1 |
USB Channel 0 USB Vbus Enabled |
2 |
USB Channel 1 USB Hi-Speed Data Enabled |
3 |
USB Channel 1 USB Vbus Enabled |
4 |
USB Channel 2 USB Hi-Speed Data Enabled |
5 |
USB Channel 2 USB Vbus Enabled |
6 |
USB Channel 3 USB Hi-Speed Data Enabled |
7 |
USB Channel 3 USB Vbus Enabled |
8:31 |
Reserved |
Hub Upstream Channels¶
The USBHub2x4 is perfect for environments where multiple devices need to be shared or switched between two host computers using two host (upstream) connections via USB standard-B connectors. The upstream connection can be automatically detected or specifically selected using the following methods:
stem.usb.getUpstreamMode(mode) [cpp] [python] [NET] [LabVIEW]
stem.usb.setUpstreamMode(mode) [cpp] [python] [NET] [LabVIEW]
The mode parameter can be defined as the following:
Value |
Hub Upstream Mode Descriptions |
|---|---|
0 |
Force upstream port 0 to be selected |
1 |
Force upstream port 1 to be selected |
2 |
Automatically detect upstream port |
Predefined C++ macros for these can be found in aProtocoldef.h, and Python’s built-in help interface.
The default operational mode is to auto detect which upstream USB port is selected. Automatic detection uses the presence of Vbus on the USB type-B upstream connector to determine presence of a host. If only one upstream port is connected to a host, it will be used for upstream USB. If both upstream ports are connected, the hub will use upstream port 0.
If the Hub Upstream Mode is set to disconnect both upstream ports (or the only active upstream port), the only path available to establish a BrainStem link to the USBHub2x4 will be via a host connected to the BrainStem Control Port.
Hub Upstream State¶
The USBHub2x4 can provide status information on which upstream port is actively selected as data path to the downstream ports:
stem.usb.getUpstreamState(mode) [cpp] [python] [NET] [LabVIEW]
Value |
Hub Upstream State Descriptions |
|---|---|
0 |
Upstream port 0 is actively selected |
1 |
Upstream port 1 is actively selected |
2 |
No upstream port is selected |
Port State¶
Each downstream port reports information regarding its operating state represented in bit-packed results from:
stem.usb.getPortState(state) [cpp] [python] [NET] [LabVIEW]
where channel can be [0-3], and the value status is 32-bit word, defined as the following:
Bit |
Port State: Result Bitwise Description |
|---|---|
0 |
USB Vbus Enabled |
1 |
USB2 Data Enabled |
2:18 |
Reserved |
19 |
USB Error Flag |
20 |
USB2 Boost Enabled |
21:22 |
Reserved |
23 |
Device Attached |
24 |
Constant Current Mode |
25:31 |
Reserved |
Port Error Status Mapping¶
Error states for all downstream ports are bit-packed in 32-bit words available from:
stem.usb.getPortError(channel) [cpp] [python] [NET] [LabVIEW]
where channel is [0-3].
Errors can be cleared on each individual channel by calling the following method:
stem.usb.clearPortErrorStatus(channel) [cpp] [python] [NET] [LabVIEW]
Calling this command clears the port-related error bit flags in the port error state. Global bits for hub errors cannot be cleared by this command.
Details about the port error status 32-bit word are as follows:
Bit |
Port Error Status Bitwise Description |
|---|---|
0 |
USB port current limit exceeded |
1 |
USB port back-drive condition detected |
2 |
Reserved |
3 |
Hub over temperature condition |
4 |
VBus Discharge error |
5:31 |
Reserved |
Boost Mode¶
Boost mode increases the drive strength of the USB 2.0 Hi- Speed data signals (power signals are not changed). Boosting the data signal drive strength may help to overcome connectivity issues when using long cables or connecting through relays, “pogo” pins or other adverse conditions. This setting is applied after a system.save() call and reset or power cycle of the hub. The system setting is persistent until changed or the hub is hard reset. After a hard reset, the default value of 0% boost is restored. A hard reset is done by pressing the “Reset” button on the back of the hub while the hub is powered.
Boost mode can be applied to both the upstream and downstream USB ports with the follow methods:
stem.usb.getDownstreamBoostMode(setting) [cpp] [python] [NET] [LabVIEW]
stem.usb.setDownstreamBoostMode(setting) [cpp] [python] [NET] [LabVIEW]
stem.usb.getUpstreamBoostMode(setting) [cpp] [python] [NET] [LabVIEW]
stem.usb.setUpstreamBoostMode(setting) [cpp] [python] [NET] [LabVIEW]
The setting parameter is an integer that correlates to the following:
Value |
Hub Boost Mode Descriptions |
|---|---|
0 |
Normal drive strength |
1 |
4% increase in drive strength |
2 |
8% increase in drive strength |
3 |
12% increase in drive strength |