How-To Set Up a Managed USB Hub on Linux

This guide takes you from a freshly connected Coolgear Managed USB Hub to switching ports from the terminal. It installs cusbi, Coolgear’s command-line utility, finds your hub, then covers every command the utility supports, with examples you can copy.

Before You Start

Managed USB HubConnected to the Linux computer by USB and powered on
The utility archivee.g. cusbi-r1.02.tar.gz, supplied with the hub
Root accessA sudo password; the utility needs root to reach the hub
A terminalAny distribution; the steps use Ubuntu as the example

Pick the right utility for your CPU

Run uname -m to see your processor type:

uname -m

cusbi Intel / AMD

Output is x86_64 or i686: most desktops, laptops, servers and mini PCs.

cusba ARM

Output starts with arm or aarch64: Raspberry Pi and other single-board computers.

Both tools take exactly the same commands. On an ARM system, type cusba wherever this guide says cusbi.

Install & First Run

  1. Copy the archive and extract it

    Copy the archive to your Desktop, then extract it from a terminal (or right-click it and choose Extract Here):

    cd ~/Desktop
    tar -xzf cusbi-r1.02.tar.gz
    ls

    Expect: cusbi in the listing. If it was extracted into a folder, cd into that folder and use its path in the steps below.

  2. Make it executable

    Some file managers drop the execute permission when extracting. Setting it again is harmless:

    chmod +x cusbi
  3. Check that Linux sees the hub

    The hub’s control interface appears as a USB serial device:

    ls /dev/ttyUSB*

    Expect: /dev/ttyUSB0 (or ttyUSB1, … with several USB serial devices). Nothing listed? Check the hub’s USB cable and power, and try a different USB port. Running dmesg | tail right after plugging the hub in shows whether Linux detected it.

  4. Switch to root

    The utility needs root privileges to access the hub. Start a root shell and enter your password:

    sudo -s

    Expect: the prompt changes from $ to #.

  5. Add the folder to your PATH

    This lets you type cusbi from anywhere instead of ./cusbi. Then confirm the folder was added:

    export PATH=$PATH:~/Desktop
    echo $PATH

    Expect: the output ends with :/root/Desktop or :/home/you/Desktop.

    Watch out: after sudo -s, ~ may point to /root rather than your own home folder. If cusbi then isn’t found, use the full path instead: export PATH=$PATH:/home/you/Desktop.

  6. Show the help message

    Either form prints the list of commands. If it appears, the utility is installed and runs.

    cusbi /?
    cusbi
  7. Find your hub

    cusbi /Q

    Write down what it reports. Every other command needs the control port:

    • Control port, e.g. ttyUSB0. Assigned by the system.
    • Number of ports, e.g. 10.
    • Current port states: which ports are on and off.
    • Firmware version, e.g. v01.
  8. Switch your first port

    Turn port 3 off, check the result, then turn it back on. Watch the port LEDs on the hub as you go.

    cusbi /G:ttyUSB0          # all ports on
    cusbi /S:ttyUSB0 0:3      # port 3 off
    cusbi /G:ttyUSB0          # port 3 now reads off
    cusbi /S:ttyUSB0 1:3      # port 3 back on

    Expect: port 3’s LED goes out, then comes back on. Setup is done.

Optional Setup

  1. Keep the PATH change Optional

    export only lasts until the terminal closes. To make it permanent, add the line to a shell startup file: /etc/bash.bashrc for every user, or ~/.bashrc for just you.

    echo 'export PATH=$PATH:/home/you/Desktop' >> ~/.bashrc
  2. Or install it system-wide Optional

    Copying the utility to /usr/local/bin, which is already on every user’s PATH, avoids editing PATH at all and keeps it safe from Desktop clean-ups:

    sudo cp ~/Desktop/cusbi /usr/local/bin/
    sudo chmod +x /usr/local/bin/cusbi
  3. Run without sudo Optional

    On Ubuntu and Debian, /dev/ttyUSB* devices belong to the dialout group. Adding your user to it usually lets cusbi reach the hub without root. Log out and back in afterwards. If the hub still isn’t found, keep using sudo.

    sudo usermod -aG dialout $USER
  4. Set a password Recommended

    Every hub ships with the password pass, and while it is unchanged any command works without one. On shared or networked machines, set your own (up to 8 characters):

    cusbi /P:ttyUSB0 myPass1

    From then on, put the password after the command in every command that changes the hub, e.g. cusbi /S:ttyUSB0 myPass1 0:3.

The Command Format

Every command has up to three parts after the tool name. Some commands need no password or argument.

cusbiTool
/S:ttyUSB0Command : port
passPassword (opt.)
0:3,4Argument

Command
A slash, one command letter, a colon and the hub’s control port: /S:ttyUSB0. Only /Q and /? work without a port.
Password
Up to 8 characters. Leave it out while the hub still uses the factory password pass.
Argument
What to set. For port commands it is state:ports, so 0:3,4 means “turn ports 3 and 4 off”.

Port arguments at a glance

Hover over (or tap) the underlined parts for details.

# state:ports turn ports 3 and 4 off
cusbi /S:ttyUSB0 0:3,4

# every port on
cusbi /S:ttyUSB0 1:ALL

# flip port 3 to the opposite state
cusbi /S:ttyUSB0 T:3

# set every port at once (ports 2 and 9 off)
cusbi /S:ttyUSB0 B:1011111101
cusbi /S:ttyUSB0 H:FDFEFFFF

# with a password once you have set one
cusbi /S:ttyUSB0 myPass1 0:3

Commands

Replace ttyUSB0 with the control port cusbi /Q reported for your hub. [password] can be left out while the password is still pass. Click a command to see its syntax, options and examples.

/? HelpShow the list of commands

Prints the usage for every command. Running cusbi with no arguments does the same.

cusbi /?

/Q Query hubsFind hubs and their control ports

Lists every connected Managed USB Hub with its control port, number of ports, current port states and firmware version. Run this first: the control port it reports is needed by every other command.

cusbi /Q[:ttyUSBn] [-F]
:ttyUSBn
optional: report on one hub only
-F
optional: short fixed-format output for scripts. 0002ttyUSB0,1 means 2 hubs, on ttyUSB0 and ttyUSB1. FBFFFFFF0Av01 means port states FBFFFFFF (hex bit-map), 0A = 10 ports, firmware v01.

Examples

cusbi /Q                  # all hubs, readable
cusbi /Q -F               # all hubs, e.g. 0002ttyUSB0,1
cusbi /Q:ttyUSB0 -F       # one hub,  e.g. FBFFFFFF0Av01

/G Get port statesRead the on/off state of every port

Reads the current on/off state of every port. The readable form is easiest for people; the two bit-map forms are easiest for scripts.

cusbi /G:ttyUSBn [-B | -H]
(none)
readable description
-B
binary string, one digit per port, rightmost is port 1: 1111111011
-H
8-digit hex bit-map, ports 1–8 first: FBFFFFFF

Examples

cusbi /G:ttyUSB0
cusbi /G:ttyUSB0 -B
cusbi /G:ttyUSB0 -H

/S Set ports  ·  /F Set & saveSwitch ports on, off or toggle; /F also saves them as the power-on state

Both switch ports with the same arguments. /S changes the ports until the hub is reset or loses power. /F also writes the new states to the hub’s flash memory, so they come back after a reset or power cut; it works like /S followed by /W.

cusbi /S:ttyUSBn [password] state:ports
state
0 off · 1 on · T toggle · B binary bit-map · H hex bit-map
ports
a comma list such as 1,2,5, or ALL. With B/H, the bit-map string.

Examples

To do this Run
Turn off port 3 (default password given) cusbi /S:ttyUSB0 pass 0:3
Turn off port 3 (password left out) cusbi /S:ttyUSB0 0:3
Turn on port 3 cusbi /S:ttyUSB0 1:3
Toggle port 3 cusbi /S:ttyUSB0 T:3
Turn off ports 1 and 2 cusbi /S:ttyUSB0 0:1,2
Turn on every port cusbi /S:ttyUSB0 1:ALL
Port 3 off only, 7-port hub (binary) cusbi /S:ttyUSB0 B:1111011
Port 3 off only, 4-port hub (binary) cusbi /S:ttyUSB0 B:1011
Ports 1, 2 and 4 off (hex) cusbi /S:ttyUSB0 H:F4FFFFFF
Turn off port 3 and keep it off after power loss cusbi /F:ttyUSB0 0:3

/S Set

Live states only. Good for quick tests and power-cycling a stuck device.

Changes ports nowYes
Survives power-off / resetNo

/F Set & save Schedules

Live states and flash. Use when the state must hold through outages.

Changes ports nowYes
Survives power-off / resetYes

/W Save

Saves whatever the ports are doing now. Nothing switches.

Changes ports nowNo
Survives power-off / resetYes

Check the bit order. In a binary string the rightmost digit is port 1. Some printed examples show B:1111110 for “port 3 off”, but that string turns off port 1. For port 3 on a 7-port hub, use B:1111011.

/W Save as power-on defaultSave the current states as the power-on state

Writes the current port states to the hub’s flash memory. From then on the hub starts with these states whenever it is powered up or reset. Handy after a series of /S commands.

cusbi /W:ttyUSBn [password]

Examples

cusbi /W:ttyUSB0
cusbi /W:ttyUSB0 pass

/P Change passwordSet or change the hub password

Sets or changes the hub’s password (8 characters maximum). The factory password is pass. After changing it, include the new password in every command that changes the hub.

cusbi /P:ttyUSBn [old_password] new_password

Examples

cusbi /P:ttyUSB0 new          # from factory "pass" to "new"
cusbi /P:ttyUSB0 new new2     # from "new" to "new2"

/R Hardware resetReset the hub without unplugging it

Resets the hub without unplugging it. Every downstream device disconnects and reconnects automatically, and the ports return to their saved states.

cusbi /R:ttyUSBn [password]

Examples

cusbi /R:ttyUSB0
cusbi /R:ttyUSB0 pass

/D Restore factory defaultsRestore the factory password and turn all ports on

Resets the password to pass and turns every port on. It needs the current password; if you’ve forgotten it, use the hub’s button instead: power the hub off, press and hold the button, then power it back on.

cusbi /D:ttyUSBn [password]

Examples

cusbi /D:ttyUSB0
cusbi /D:ttyUSB0 pass


Explore More. Automate More.

Discover more powerful automation scripts or explore Coolgear’s lineup of compatible Managed USB Hubs to expand your USB control capabilities.

View Compatible Managed USB Hubs Explore More Scripts

Looking for Assistance? Reach out to our tech team for help getting set up.