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.
USB 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, SuperSpeed data, and Vbus lines simultaneously for a single port can be done by calling the following methods with channel in [0-7] being the port index:
stem.usb.setPortEnable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setPortDisable(channel) [cpp] [python] [NET] [LabVIEW]
Manipulating Hi-Speed data and SuperSpeed data lines while not affecting the Vbus lines simultaneously for a single port can be done by calling the following method with channel [0-7]:
stem.usb.setDataEnable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setDataDisable(channel) [cpp] [python] [NET] [LabVIEW]
Manipulating just the USB 2.0 Hi-Speed data lines for a single port can be done by calling the following method with channel [0-7]:
stem.usb.setHiSpeedDataEnable(channel [cpp] [python] [NET] [LabVIEW]
stem.usb.setHiSpeedDataDisable(channel) [cpp] [python] [NET] [LabVIEW]
Manipulating just the USB 3.1 SuperSpeed data lines for a single port can be done by calling the following method with channel [0-7]:
stem.usb.setSuperSpeedDataEnable(channel) [cpp] [python] [NET] [LabVIEW]
stem.usb.setSuperSpeedDataDisable(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-7]:
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.
USB 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-7], 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]
USB Downstream Current Limiting¶
Current-limit trip point settings can be accessed for each port by calling the following methods with channel [0-7], 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 USBHub3+ current limit behavior follows the USB BC1.2 defined “trip off” behavior. When a downstream device consumes more current than the set current limit, the Vbus voltage will immediately turn of and latch off until the port is re- enabled. An overcurrent error flag is set in getPortState() bitfield. The voltage-current behavior is detailed in Figure 6.
USB 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 |
2 |
SuperSpeed device enumerated |
USB 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 USBHub3+. 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.
USB Downstream Enumeration Delay¶
Once a USB device is detected by the USBHub3+ 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 7. 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]
USB Boost Mode¶
Boost mode increases the drive strength of the USB 2.0 Hi- Speed data signals (SuperSpeed data and 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 |
USB Hub Upstream Channels¶
The USBHub3+ 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 |
Definitions |
Hub Upstream Mode Descriptions |
|---|---|---|
0 |
usbUpstreamModePort0 |
Force upstream port 0 to be selected |
1 |
usbUpstreamModePort1 |
Force upstream port 1 to be selected |
2 |
usbUpstreamModeAuto |
Automatically detect upstream port |
255 |
usbUpstreamModeNone |
Disconnect both upstream ports |
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 USBHub3+ will be via a host connected to the BrainStem Control Port. See Figure 9 for more details.
USB Hub Upstream State¶
The USBHub3+ 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]
This command returns a 32-bit value which indicates:
Value |
Definitions |
Hub Upstream Mode Descriptions |
|---|---|---|
0 |
usbUpstreamModePort0 |
Force upstream port 0 to be selected |
1 |
usbUpstreamModePort1 |
Force upstream port 1 to be selected |
2 |
usbUpstreamModeAuto |
Automatically detect upstream port |
255 |
usbUpstreamModeNone |
Disconnect both upstream ports |
USB 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 USBHub3+ 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]
Bit |
Hub Operational Mode Word Definition |
|---|---|
0 |
USB Ch 0 USB Hi-Speed Data Enabled |
1 |
USB Ch 0 USB Vbus Enabled |
2 |
USB Ch 1 USB Hi-Speed Data Enabled |
3 |
USB Ch 1 USB Vbus Enabled |
4 |
USB Ch 2 USB Hi-Speed Data Enabled |
5 |
USB Ch 2 USB Vbus Enabled |
6 |
USB Ch 3 USB Hi-Speed Data Enabled |
7 |
USB Ch 3 USB Vbus Enabled |
8 |
USB Ch 4 USB Hi-Speed Data Enabled |
9 |
USB Ch 4 USB Vbus Enabled |
10 |
USB Ch 5 USB Hi-Speed Data Enabled |
11 |
USB Ch 5 USB Vbus Enabled |
12 |
USB Ch 6 USB Hi-Speed Data Enabled |
13 |
USB Ch 6 USB Vbus Enabled |
14 |
USB Ch 7 USB Hi-Speed Data Enabled |
15 |
USB Ch 7 USB Vbus Enabled |
16 |
USB Ch 0 USB SuperSpeed Data Enabled |
17 |
Reserved |
18 |
USB Ch 1 USB SuperSpeed Data Enabled |
19 |
Reserved |
20 |
USB Ch 2 USB SuperSpeed Data Enabled |
21 |
Reserved |
22 |
USB Ch 3 USB SuperSpeed Data Enabled |
23 |
Reserved |
24 |
USB Ch 4 USB SuperSpeed Data Enabled |
25 |
Reserved |
26 |
USB Ch 5 USB Super Speed Data Enabled |
27 |
Reserved |
28 |
USB Ch 6 USB SuperSpeed Data Enabled |
29 |
Reserved |
30 |
USB Ch 7 USB SuperSpeed Data Enabled |
31 |
Auto VBus Toggle Disable |
USB 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-7], 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 |
Reserved |
3 |
USB3 Data Enabled |
4:10 |
Reserved |
11 |
USB2 Device Attached |
12 |
USB3 Device Attached |
13:18 |
Reserved |
19 |
USB Error Flag |
20 |
USB2 Boost Enabled |
21:22 |
Reserved |
23 |
Device Attached |
24:31:00 |
Reserved |
USB 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-7].
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 (see Table 7) 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 (channel) Result Bitwise Description |
|---|---|
0 |
USB port current limit exceeded |
1 |
USB port back-drive condition detected |
2 |
Hub external power not present |
3 |
Hub overtemperature condition |
4 |
USB port short-circuit condition |
5:31 |
Reserved |