Using USB Host Manager

Zebra USB Host Manager 1.0

Overview

Zebra USB Host Manager (UHM) can be installed on any Zebra device running Android, but is not required to apply rules on a device. Restrictions are applied when a rules file created by UHM is deployed to the device using Zebra StageNow or a company's own EMM system, if compatible. A common administrator workflow is shown below.

Requirements

  • Administrator PC configured with Zebra StageNow or EMM console
  • Zebra device running Android (to run USB Host Manager as admin)
  • Zebra device(s) running Android (for testing rules made with USB Host Manager)
  • Optional:
    • Zebra Workstation Cradle (with monitor, keyboard and mouse connected)
    • Zebra Workstation Connect software running on admin (Android) device

Zebra recommends using the Zebra Workstation Connect solution for maximum administrator productivity and convenience. Learn more. ZWC 1.6 (or later) is required.

Admin Workflow

  1. Connect USB peripherals desired for use
  2. Launch USB Host Manager, which scans and displays all connected peripherals
  3. Set rules to allow the desired connected peripherals (thereby disallowing all others)
  4. Export rules file and transfer to administrative PC
  5. Deploy rules file using Zebra StageNow or an EMM system to device(s) for testing
  6. After successful testing, deploy to enterprise as needed

Allowing USB Peripherals

Zebra USB Host Manager works through the creation of "Allow Rules," which enable an administrator to specify which peripherals are permitted to be used on a device, to the exclusion of all others. Once a set of Allow Rules is deployed to a device, all other peripherals are prohibited from use on that device, without exception. If an additional peripheral is required for use at a later time, a new set of Allow Rules that includes that peripheral must be created and deployed to the device, overwriting the previous rules file.

Peripheral Characteristics

USB peripherals can be identified by one or more categories.

  • Class - Class name of connected peripherals (see classes list, below)
  • Restricted Class - Displayed in a light gray font; they cannot be used to allow or disallow usage
  • Vendor ID - Unique alpha-numeric number assigned to each USB device manufacturer (see USB.org)
  • Product ID – Multi-digit value assigned to individual products by its manufacturer
  • Status - Status of peripherals is shown as "Enabled" (allowed) and "Disabled" (disallowed)

Home Screen Options:

  • Show All - Displays allowed (green) and disallowed (red) peripherals connected to the device
  • Show Enabled Only - Displays only peripherals that are connected and allowed

Create Rules

The following section provides details of the typical admin workflow for creating rules shown above.

To Create "Allow Rules"

  1. Connect USB peripherals to be allowed for use in the enterprise to a Zebra device running Android.

  2. Launch the USB Host Manager app on the device. The UHM home screen appears (screens vary by device): image The USB Host Manager home screen (above) showing enabled (green) and disabled (red) peripherals.
    Click image to enlarge; ESC to exit.
    image USB Host Manager (light and dark modes) running on handheld devices.
    Click image to enlarge; ESC to exit.

  3. Click or tap on a peripheral name to select it for an "Allow Rule." Depending on the platform, a screen appears that's similar to one of the images below.
    Click or tap on the desired rule button(s). Blue buttons are available for selection, and turn gray to indicate that a rule has been set.
    When finished, click or tap "Done" button to save selections and apply the rules on the current host device. image Click image to enlarge; ESC to exit.

    image Click image to enlarge; ESC to exit.

  4. Repeat Step 3 until rules are created to allow the desired peripherals.

  5. Click or tap the "Rules" button to review the rules before testing.
    image Click image to enlarge; ESC to exit.

  6. Click or tap the "Rules" button to display the rules in force on a device.
    To delete a rule, click or tap its icon. image Click image to enlarge; ESC to exit.

    image Click image to enlarge; ESC to exit.

  7. To export, click or tap the "Export" button.
      a. The rules file usb_device_config.xml is saved to the folder /enterprise/usr/usb on the device (as seen in image below).
      b. Copy the rules file to the administrator PC. image Click image to enlarge; ESC to exit.

Usage rules for USB peripherals can now be deployed using Zebra StageNow and USB Manager or an EMM system.

Supported Device Classes

The following device classes can be used for creating device rules:

  • AINPUT_SOURCE_DPAD
  • AINPUT_SOURCE_GAMEPAD
  • AINPUT_SOURCE_KEYBOARD
  • AINPUT_SOURCE_MOUSE
  • AINPUT_SOURCE_MOUSE_RELATIVE
  • AINPUT_SOURCE_JOYSTICK
  • AINPUT_SOURCE_ROTARY_ENCODER
  • AINPUT_SOURCE_STYLUS
  • AINPUT_SOURCE_TOUCH_NAVIGATION
  • AINPUT_SOURCE_TOUCHPAD
  • AINPUT_SOURCE_TOUCHSCREEN
  • AINPUT_SOURCE_TRACKBALL
  • USB_CLASS_AUDIO
  • USB_CLASS_CDC_DATA
  • USB_CLASS_COMM
  • USB_CLASS_CONTENT_SEC
  • USB_CLASS_CSCID
  • USB_CLASS_MASS_STORAGE
  • USB_CLASS_PHYSICA
  • USB_CLASS_PRINTER
  • USB_CLASS_STILL_IMAGE
  • USB_CLASS_VIDEO
  • USB_CLASS_WIRELESS_CONTROLLER

The following restricted classes CANNOT be used for creating device rules:

  • USB_CLASS_APP_SPEC
  • USB_CLASS_HID
  • USB_CLASS_HUB
  • USB_CLASS_MISC
  • USB_CLASS_PER_INTERFACE
  • USB_CLASS_VENDOR_SPEC

Learn more about creating custom rules.

Example "Allow Rules" File

                
                <?xml version="1.0" encoding="UTF-8"?>
                <usbconfig mode="whitelist">
                  <class>AINPUT_SOURCE_DPAD</class>
                  <class>AINPUT_SOURCE_JOYSTICK</class>
                  <class>USB_CLASS_AUDIO</class>
                    <vid vendorid="1504">
                    <pid>5889</pid>
                    </vid> 
                </usbconfig>

Zebra recommends deployment of machine-generated XML files only. Manual editing is NOT recommended.

All connected USB peripherals NOT explicitly allowed are rendered unusable by apps. Such peripherals continue to receive power (via USB) and in some cases could appear to be enabled, but are effectively prevented from communicating with apps.

Error Messages

Two potential errors could occur while using USB Host Manager.

  1. "Proxy Framework Timeout error"
    USB Host Manager scans for connected USB peripherals when initially launched and after clicking or tapping the "Refresh" button. If it does not receive data within three seconds, it displays this message, prompting to click or tap the "Refresh" button.

  2. "Intended only for Zebra devices"
    USB Host Manager is designed to run only on Zebra-branded devices. An error is displayed if attempting to run on non-Zebra devices. To clear the error, click or tap "OK" button.

Also See