usb2

The usb2 command controls the USB 2.0 layer on devices with USB 2.0 routing support: pairing endpoints, setting extender chipset options, and resetting the extender.

Command Type	DisplayNet
Minimum Version	3.x.x

Usage

usb2 pair <source> <destination>
usb2 pairhub <source> <destination>[,<destination>...]
usb2 removepair <source> [<destination>]
usb2 setoption <device> <msa | multiuser> <on | off>
usb2 setrole <device> <local | remote>
usb2 reset <device>

Devices are addressed by hostname or MAC address. Any device that supports USB 2.0 routing can be used; when pairing, the source should be a TX device and the destination an RX device.

Subcommands

Subcommand	Description
pair	Pair two USB devices exclusively
pairhub	Pair multiple RX devices to a single TX, creating a virtual hub
removepair	Remove one pairing, or all of a device's pairings
setoption	Change USB extender chipset options on DN-3xx devices
setrole	Set a device's USB extender role (local or remote)
reset	Reset the USB extender chipset on a device

pair

Pairs two USB devices. Any existing pairings on either device are cleared first, so pair always results in a single one-to-one pairing. Use pairhub to pair multiple RX devices to one TX.

Pair a computer's USB to a seat
usb2 pair computer front_desk

pairhub

Pairs one or more RX devices to a single TX device, creating a virtual hub. Unlike pair, pairhub is additive: repeated commands add devices to the hub. Up to 7 RX devices are supported. Requires multiuser mode to be enabled on the devices (see setoption).

Add two seats to a source's virtual hub
usb2 pairhub bluray_player hd_monitor,monitor_two

removepair

Removes a pairing between source and destination. If destination is omitted, all of the source device's pairings are removed. Removing a pairing that does not exist is a no-op.

Remove all pairings from a source
usb2 removepair bluray_player

setoption

Changes a USB extender chipset option on DN-3xx devices. After changing an option, the extender chipset must be reset with the reset subcommand before the change takes effect.

Option	Values	Description
msa	on / off	Mass storage acceleration. Recommended off when using multiuser mode
multiuser	on / off	Simultaneous User (SUI) mode, which allows multiple RX devices to pair to one TX as a virtual hub (see pairhub)

Disable mass storage acceleration
usb2 setoption avp1 msa off

setrole

Sets the USB 2.0 extender role for an endpoint, determining whether it acts as the Local or Remote extender in the USB extension link. The role is independent of the device's TX/RX mode and can be set on either device.

Role	Meaning
local	Local extender (host side)
remote	Remote extender (device side)

Set extender roles on an endpoint pair
usb2 setrole endpoint_one local
usb2 setrole endpoint_two remote

reset

Resets the USB extender chipset on a device. Required after changing an option with setoption.

Reset a device's USB extender
usb2 reset avp1

Return value

usb2 pairhub bluray_player monitor_two
{
  "status": "SUCCESS",
  "request_id": null,
  "result": null,
  "error": null
}

Errors

Error	Cause
<device> is not a USB 2.0 extender	The device has no USB 2.0 extender support
Invalid Option specified	setoption with an option other than msa/multiuser
Invalid Option Value specified	setoption with a value other than on/off
Cannot remove USB pair on locked device	The device is locked in DisplayNet Manager

State and side effects

• The pairing is held by the USB extenders themselves, not by DisplayNet. It survives a server restart because the extender hardware remembers it, and clearing DisplayNet's records does not unpair anything.
• Both ends are changed together. Unpairing removes the pairing from the peer as well.
• A locked device at either end refuses the change, source or destination. See lock.

Notifications

Pairing changes produce a NOTIFICATION with event type SETTINGS_CHANGED when device options change.

setoption produces a DN_NOTIFICATION with the change reflected in the USB subobject of a streams_update result:

usb2 setoption avp1 multiuser off (excerpt)
{
  "status": "DN_NOTIFICATION",
  "request_id": null,
  "result": {
    "streams_update": [
      {
        "device_id": "6cdffb00387f",
        "USB": {
          "SUIEnabled": false,
          "MSAEnabled": false,
          "PendingReset": true,
          "HubConnection": "off"
        }
      }
    ]
  },
  "error": null
}

REST API

Endpoint type	DisplayNet API command
Address	POST /api/displaynet/<operation>, or name the operation in the body of a POST /api/displaynet. See Sending commands.
Role	User

Subcommand	Operation	Parameters
pair	usb2_pair	source destination
pairhub	usb2_pairhub	source destinations
removepair	usb2_removepair	source destination
reset	usb2_reset	source
setoption	usb2_setoption	device option value
setrole	usb2_setrole	device role

See also

• connect: connect USB performs a pair as part of general routing
• disconnect: disconnect usb removes pairings