Master USBHub3+ host switching: auto or manual, HubTool or Python

Simplify device sharing and streamline control with USBHub3+

Automatic switching

By default, the USBHub3+ will automatically switch to upstream host 0 if available.  This enables simple peripheral device sharing, where a dedicated PC could be connected to the host "Up 1" port, and an occasional user could connect a laptop to "Up 0" and gain access to the peripherals.  When they're done and disconnect, control of the devices would revert to the PC.  One common application would be for conference room AV systems with dedicated room PCs, where users may want to directly connect a laptop to the AV equipment and bypass the room computer. Automatic host switching is also useful in scenarios where groups of USB devices need to be temporarily transferred from one host to another, for example, in a music studio with multiple audio and MIDI interfaces, or manufacturing and robotics where multiple machine controls need to work together.

On-command host switching

The USBHub3+ can receive commands from the connected host PC, but when switching hosts, it is recommended to use the dedicated control port (mini USB) to control the hub since after switching to the second host, the first host will have lost its connection to the hub and won't be able to send commands. You'll need a USB-A to Mini-B cable.  If you accidentally set the upstream hosts to none and don't have the mini USB cable, don't panic:  when the hub is power cycled, it reverts to auto-selecting the upstream host.

The control port will always take precedence over the other ports if it is connected. The control PC could be separate from the host PCs, or a host PC could also control the hub:

Selecting an upstream host manually with HubTool

If you haven't already, install HubTool, which is part of the Brainstem Dev Kit. Power on the hub and connect your computer via a USB-A to Mini-B cable to the hub's control port. Launch HubTool (located in "bin")

You should see a mostly blank window with the serial number of the connected hub(s) in the lower right.  Click on the hub's serial to connect.
There will be an overview of the hub connections.  In the upper right under "upstream" is the port selector.  Choose Auto Mode, Port 0, Port 1, or None.

Selecting an upstream host with Python

We'll be using an interactive python console to be able to work line-by-line, but these same commands could be used in a script.
If you haven’t already, install the Brainstem package (See the Quickstart Guide for more detail)

>>> import brainstem

Create an instance of the USBHub3p called "hub"

>>> hub = brainstem.stem.USBHub3p()

Discover and connect to the hub

>>> hub.discoverAndConnect(brainstem.link.Spec.USB) 0

A return value of 0 means no error.  

Read the upstream port mode:

>>> hub.usb.getUpstreamMode().value
2

Table of upstream port modes

Set the upstream port mode to force selection of upstream port 0: 

>>> hub.usb.setUpstreamMode(0)

Set it back to auto mode

>>> hub.usb.setUpstreamMode(2)

Example script

Python scripts can be triggered on a schedule using Automator (Mac), Windows Task Scheduler, or Cron (Linux). Here is an example script that toggles between Up 0 and Up 1 host ports:

# host_switch.py
import sys

from brainstem.stem import USBHub3p
from brainstem.link import Spec
from brainstem.result import Result

def main():

    print('\nConnecting to USBHub3+...')
    hub = USBHub3p()

    # To Locate and connect to the first USBHub3+ you find on USB
    result = hub.discoverAndConnect(Spec.USB)
    # To Locate and connect to a specific module, add a second parameter with your serial number (hex).
    # result = stem.discoverAndConnect(Spec.USB, 0x66F4859B)

    if result == (Result.NO_ERROR):
        result = hub.system.getSerialNumber()
        print("Connected to USBHub3+ with serial number: 0x%08X" % result.value)
        print("Switching host control...")
        result = hub.usb.getUpstreamState()
        if result.error == Result.NO_ERROR:
            if result.value == 0:
                print("  to port 1")
                result = hub.usb.setUpstreamMode(1)
            else:
                print("  to port 0") 
                result = hub.usb.setUpstreamMode(0)
        else:
            print("Error determining new host port.")

        if result in [Result.NO_ERROR, Result.TIMEOUT]:
            print("Done.")
        else:
            print("Error setting port.")
    else:
        print('Could not find a module.\n')

    hub.disconnect()

if __name__ == "__main__":
    sys.exit(main())

What else could you do with USBHub3+?

1. Independently control VBus and data for each port
   • Turn on and off VBus
   • Enable and disable data connections:
2. Power Measurements
   • Measure current and voltage on each port
   • Monitor input power and system power
3. Switch ports between Charging Downstream Port (CDP) and Standard Downstream Port (SDP) (up to 500 mA)
4. View the enumeration speed of a connected device
5. Switch upstream hosts
   • Automatically 
   • Programatically
6. Add more ports by daisy chaining hubs
7. Other USBHub3+ uses

In conclusion, mastering USBHub3+ host switching offers versatile control for various applications. Whether it's automatic or manual switching with HubTool or Python, the flexibility and convenience it provides can enhance device management and connectivity in diverse scenarios. With the ability to select upstream hosts and manage multiple devices efficiently, USBHub3+ opens up possibilities for optimizing USB connectivity in your projects.