Skip to main content

USB Human Interface Device Support

This guide is intended for administrators wishing to integrate the use of USB Human Interface Device (HID) devices within their end user experience.

Frame now supports up to 10 USB HID input devices, such as 3D mice, game controllers, and joysticks, connected to the local endpoint, in addition to mouse and keyboard.

Considerations
  • Frame Terminal running in a supported web browser only supports USB HID on Linux and macOS Chrome browser.
  • Frame App fully supports USB HID on Linux, macOS, and Windows endpoints.

Requirements‚Äč

For end users to use USB HID, the administrator must verify that the Frame Virtual USB driver has been installed on the Sandbox and published. The Frame Virtual USB driver is included in the Frame Guest Agent Installer and can also be downloaded using the Frame Agent Setup Tool (FAST). Both the FGA and FAST installers are available for download from Nutanix Portal. You must have a My Nutanix user account in order to access the Nutanix Portal.

Frame Virtual USB Driver‚Äč

Verification‚Äč

Start by verifying you do have the Virtual USB driver installed in your Sandbox:

  1. Power on the Sandbox if it is not already running.
  2. Once you're in the Sandbox, verify that the Virtual USB driver has been installed by navigating to the Device Manager for your Sandbox. There will be a device named "Frame virtual devices". Selecting the Virtual USB Hub and examining the Driver Details will confirm that the Frame Virtual USB driver has been installed and operating correctly.

Device Manager

Device Manager - Frame virtual devices

Installation‚Äč

If the Frame virtual devices does not exist in the Device Manager, then:

  1. Download the Frame Agent Setup Tool from the Nutanix Portal inside the Sandbox and run the installer to install the Virtual USB driver.
  2. When installation is complete, reboot your Sandbox to ensure that the Frame Guest Agent detects the Virtual USB driver.
  3. You can follow the procedure above to verify that the Frame Virtual USB driver has been installed correctly.

Frame Account Configuration‚Äč

  1. Once you have verified that the Virtual USB driver has been installed, close the Sandbox session and navigate to the "Settings" page in the account's Dashboard.

  2. Under the "Session" tab, enable the USB Redirection toggle. Click "Save."

Session Settings - USB Redirection

Session Settings - USB Redirection
  1. You should now be able to test a USB Human Interface Device within your Sandbox.
  2. Once you are ready to make USB HID support available to your users, publish the Sandbox to ensure the Nutanix Frame Virtual USB driver is on your production workload VMs.
note

Since the USB Redirection setting is in Session Settings, Frame Administrators can enable the USB Redirection policy at the Sandbox or for a specific Launchpad, instead of enabling the USB HID feature at the Frame account level.

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 macOS or Linux‚Äč

For users on macOS or Linux endpoints, they must use Chrome on macOS or Linux-based operating systems in order to use USB Human Interface Devices. 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 URL
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.

Chrome Experimental Web Platform features

Chrome Experimental Web Platform features
  1. Click the "Relaunch" button at the lower right corner of the browser once the button appears at the bottom of the page to apply your changes.

Relaunch Chrome

Relaunch Chrome

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:
SUBSYSTEMS=="usb", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c626", MODE="0664", GROUP="plugdev"

Replace idVendor and idProduct values with the actual values for the USB HID device. 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‚Äč

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

  • 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.

  • Error message "Cannot open connection to device: Access denied": When you click on your USB device in the list to "plug in" to your remote session, Frame 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. While we have tested and validated many brands and types of USB HID devices, there may be USB devices that do not work yet with Frame. If you would like to submit feedback, please create a support case.