USB Human Interface Device (HID) Support

Early Access Feature

USB HID support is an Early Access Feature

Frame now supports up to 10 USB HID devices (3D mice, gamepads, and joysticks) connected to the local endpoint, in addition to mouse and keyboard. This guide is intended to walk administrators through the setup and configuration of USB HID.

Note

Frame App fully supports USB HID on Windows, MacOS and Linux endpoints while Frame Terminal (HTML5 Browser) only supports USB HID on MacOS and Linux Chrome browser at this time.

Requirements

  • Administrators must have access to the account’s Sandbox.

  • The administrator will need to install the virtual USB 1.0 driver on the Sandbox. To obtain this driver, please create a support case.

Setup

  1. Start by navigating to the Sandbox of the account you would like to configure with USB HID support. Power on the Sandbox if it is not already running.

../_images/hid_1.png
  1. Once you’re in the Sandbox, download the Virtual USB 1.0 driver from the Nutanix Portal and run the installer.

  2. When installation is complete, reboot your Sandbox to ensure that the Frame Guest Agent detects the Virtual USB driver.

  3. You can verify that the Virtual USB driver has been installed by navigating to the Device Manager for your Sandbox. You should see “XiFrame virtual devices” at the bottom of the list.

../_images/hid_dev_mgmt.png
  1. Once you have verified that the Virtual USB 1.0 driver has been installed, close the Sandbox session and navigate to the “Settings” page in the account’s Dashboard.

  2. Under the “Session” tab, scroll down to the “Advanced options” section. Enter usb under the “Advanced Terminal Arguments” field as shown below. Click “Save.”

../_images/hid_arg.png

End User Configuration

Depending on the combination of ways to access Frame, additional configuration may be required. The sections below detail additional setup instructions for your end users.

Chrome on Mac OS or Linux

Some additional configuration may be needed by the end user, depending on how they are accessing their Frame session. If your users are accessing Frame via a web browser, they must use Chrome on MacOS or Linux-based operating systems. End users should follow the steps below to complete configuration of USB HID support. Chrome users must enable the “Experimental Web Platform features” within the Chrome browser, as Google still considers USB HID and WebUSB support to be an experimental feature.

  1. In a new Chrome browser tab, enter the following in the address bar:

chrome://flags/#enable-experimental-web-platform-features
  1. At the top of the page you will see the “Experimental Web Platform features” option. Use the drop-down menu to enable this feature.

../_images/hid_eu11.png
  1. Click the “Relaunch” button once it appears at the bottom of the page to apply your changes.

../_images/hid_eu21.png

Frame App on Mac OS

If you are planning on using USB features in Frame App on MacOS 10.15 or higher, you will need to adjust local security settings. Simply navigate to System Preferences > Security & Privacy > Input Monitoring. From there, add Frame App to the list.

../_images/usb_mac1.png

Frame App on Linux

For the devices that the user would like access to, a udev rule must be created.

  1. Create a file 50-usbdevices.rules in /etc/udev/rules.d

  2. For each device, add a line as follows:

    UBSYSTEM=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c626", MODE="0664", GROUP="plugdev"
    

    Replace idVendor value and idProduct values with the actual values. In the example above, the rule is written for device with idVendor=046d and idProduct=c626 (the values are hexadecimal).

Note

The user running Frame application must be part of “plugdev” group.

Troubleshooting

If the USB icon in the bottom right corner of the Frame status bar is red, hover over it to see what error is displayed. Here are some examples of different scenarios and their meanings.

  • Tooltip message “Not supported”: Server does not support USB functionality. Either the Frame Guest Agent needs to be updated or the virtual USB driver needs to be installed. Note that driver may be installed, but Frame Guest Agent may need to be upgraded to the newer version of driver in order for the USB functionality to work properly.

  • Tooltip message “Cannot obtain devices from host”: The application is having trouble accessing USB devices on the host machine (the machine where the application is installed and running).

  • Error message “Cannot plug in device”: You may see this message after clicking on a device in the USB device list. This means that the Frame platform was unable to communicate with the USB device. We recommend creating a support case for further evaluation.

  • Your device is not listed: If you find that your USB device is not showing up as an option in the device list, the Frame platform is not recognizing your device. We recommend creating a support case for further evaluation.

  • Error message “Cannot open connection to device: Access denied”: When you click on your USB device to “plug in” to your remote session, the platform could not open a connection to the device because the operating system is blocking the connection.

    • If Frame App is running on Linux, verify that the udev rules are applied to the local Linux endpoint. If udev rules are valid for Linux or the application is running on Windows or macOS, the operating system on your local endpoint is blocking the connection and will require further investigation.

Testing your USB Device

You can open up a browser within your Frame session and visit an online resource such as https://gamepad-tester.com/ to test your USB HID devices. USB HID support is an Early Access Feature. While we have tested and validated many types and brands of USB HID devices, we are always open to feedback on our early access features. If you would like to submit feedback, please create a support case.