USB Devices

This document describes how to use the USB API to communicate with USB devices. Some devices are not accessible through the USB API (see the Caveats section below for details). Chrome Apps can also connect to serial and Bluetooth devices.

For background information about USB, see the official USB specifications. USB in a NutShell is a reasonable crash course that you may find helpful.

Manifest requirement

The USB API requires the "usb" permission in the manifest file:

"permissions": [
  "usb"
]

In addition, in order to prevent finger-printing, you must declare all the device types you want to access in the manifest file. Each type of USB device corresponds to a vendor id/product id (VID/PID) pair. You can use usb.getDevices to enumerate devices by their VID/PID pair.

You must declare the VID/PID pairs for each type of device you want to use under the usbDevices permission in your app's manifest file, as shown in the example below:

"permissions": [
  {
    "usbDevices": [
      {
        "vendorId": 123,
        "productId": 456
      }
    ]
  }
]

Since Chrome 57, the requirement for declaring all the device types in the app manifest is relaxed for apps running as ChromeOS kiosk apps. For kiosk apps, you can use the interfaceClass permission property to request permission to access USB devices that:

• implement a USB interface of a specific interface class
• have a specific USB device class

For example, the following usbDevices permission would grant an app access to all USB devices that implement a printer interface (interface class code 7), and to USB hub devices (device class code 9):

"permissions": [
  {
    "usbDevices": [
      {"interfaceClass": 7},
      {"interfaceClass": 9}
    ]
  }
]

For the list of acceptable interfaceClass values, see USB Class Codes.

The interfaceClass property can be combined with the vendorId property to get access only to USB devices from a specific vendor, as demonstrated by the following example:

"permissions": [
  {
    "usbDevices": [
      {
        "vendorId": 123,
        "interfaceClass": 7
      }
    ]
  }
]

Finding a device

To determine whether one or more specific devices are connected to a user's system, use the usb.getDevices method:

chrome.usb.getDevices(enumerateDevicesOptions, callback);

Example:

function onDeviceFound(devices) {
  this.devices=devices;
  if (devices) {
    if (devices.length > 0) {
      console.log("Device(s) found: "+devices.length);
    } else {
      console.log("Device could not be found");
    }
  } else {
    console.log("Permission denied.");
  }
}

chrome.usb.getDevices({"vendorId": vendorId, "productId": productId}, onDeviceFound);

Opening a device

Once the Device objects are returned, you can open a device using usb.openDevice to obtain a connection handle. You can only communicate with USB devices using connection handles.

Example:

var usbConnection = null;
var onOpenCallback = function(connection) {
  if (connection) {
    usbConnection = connection;
    console.log("Device opened.");
  } else {
    console.log("Device failed to open.");
  }
};

chrome.usb.openDevice(device, onOpenCallback);

To simplify the opening process, you can use the usb.findDevices method, which enumerates, requests access, and opens devices in one call:

chrome.usb.findDevices({"vendorId": vendorId, "productId": productId, "interfaceId": interfaceId}, callback);

which is equivalent to:

chrome.usb.getDevices({"vendorId": vendorId, "productId": productId}, function (devices) {
  if (!devices) {
    console.log("Error enumerating devices.");
    callback();
    return;
  }
  var connections = [], pendingAccessRequests = devices.length;
  devices.forEach(function (device) {
    chrome.usb.requestAccess(interfaceId, function () {
      // No need to check for errors at this point.
      // Nothing can be done if an error occurs anyway. You should always try
      // to open the device.
      chrome.usb.openDevices(device, function (connection) {
        if (connection) connections.push(connection);
        pendingAccessRequests--;
        if (pendingAccessRequests == 0) {
          callback(connections);
        }
      });
    });
  })
});

USB transfers and receiving data from a device

The USB protocol defines four types of transfers: control, bulk, isochronous and interrupt. These transfers are described below.

Transfers can occur in both directions: device-to-host (inbound), and host-to-device (outbound). Due to the nature of the USB protocol, both inbound and outbound messages must be initiated by the host (the computer that runs the Chrome app). For inbound (device-to-host) messages, the host (initiated by your JavaScript code) sends a message flagged as "inbound" to the device. The details of the message depend on the device, but usually will have some identification of what you are requesting from it. The device then responds with the requested data. The device's response is handled by Chrome and delivered asynchronously to the callback you specify in the transfer method. An outbound (host-to-device) message is similar, but the response doesn't contain data returned from the device.

For each message from the device, the specified callback will receive an event object with the following properties:

Example:

var onTransferCallback = function(event) {
   if (event && event.resultCode === 0 && event.data) {
     console.log("got " + event.data.byteLength + " bytes");
   }
};

chrome.usb.bulkTransfer(connectionHandle, transferInfo, onTransferCallback);

CONTROL transfers

Control transfers are generally used to send or receive configuration or command parameters to a USB device. The controlTransfer method always sends to/reads from endpoint 0, and no claimInterface is required. The method is simple and receives three parameters:

chrome.usb.controlTransfer(connectionHandle, transferInfo, transferCallback)

Values for transferInfo object:

Example:

var transferInfo = {
  "requestType": "vendor",
   "recipient": "device",
  "direction": "out",
  "request":  0x31,
  "value": 120,
  "index": 0,
  // Note that the ArrayBuffer, not the TypedArray itself is used.
  "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
};
chrome.usb.controlTransfer(connectionHandle, transferInfo, optionalCallback);

ISOCHRONOUS transfers

Isochronous transfers are the most complex type of USB transfer. They are commonly used for streams of data, like video and sound. To initiate an isochronous transfer (either inbound or outbound), you must use the usb.isochronousTransfer method:

chrome.usb.isochronousTransfer(connectionHandle, isochronousTransferInfo, transferCallback)

Values for isochronousTransferInfo object:

Example:

var transferInfo = {
  "direction": "in",
  "endpoint": 1,
  "length": 2560
};

var isoTransferInfo = {
  "transferInfo": transferInfo,
  "packets": 20,
  "packetLength": 128
};

chrome.usb.isochronousTransfer(connectionHandle, isoTransferInfo, optionalCallback);

BULK transfers

Bulk transfers are commonly used to transfer a large amount of non-time-sensitive data in a reliable way. usb.bulkTransfer has three parameters:

chrome.usb.bulkTransfer(connectionHandle, transferInfo, transferCallback);

Values for transferInfo object:

Example:

var transferInfo = {
  "direction": "out",
  "endpoint": 1,
  "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
};

INTERRUPT transfers

Interrupt transfers are used to small amount of time sensitive data. Since all USB communication is initiated by the host, host code usually polls the device periodically, sending interrupt IN transfers that will make the device send data back if there is anything in the interrupt queue (maintained by the device). usb.interruptTransfer has three parameters:

chrome.usb.interruptTransfer(connectionHandle, transferInfo, transferCallback);

Values for transferInfo object:

Example:

var transferInfo = {
  "direction": "in",
  "endpoint": 1,
  "length": 2
};
chrome.usb.interruptTransfer(connectionHandle, transferInfo, optionalCallback);

Caveats

Not all devices can be accessed through the USB API. In general, devices are not accessible because either the Operating System's kernel or a native driver holds them off from user space code. Some examples are devices with HID profiles on OSX systems, and USB pen drives.

On most Linux systems, USB devices are mapped with read-only permissions by default. To open a device through this API, your user will need to have write access to it too. A simple solution is to set a udev rule. Create a file /etc/udev/rules.d/50-yourdevicename.rules with the following content:

SUBSYSTEM=="usb", ATTR{idVendor}=="[yourdevicevendor]", MODE="0664", GROUP="plugdev"

Then, just restart the udev daemon: service udev restart. You can check if device permissions are set correctly by following these steps:

• Run lsusb to find the bus and device numbers.
• Run ls -al /dev/bus/usb/[bus]/[device]. This file should be owned by group "plugdev" and have group write permissions.

Your app cannot do this automatically since this this procedure requires root access. We recommend that you provide instructions to end-users and link to the Caveats section on this page for an explanation.

On ChromeOS, simply call usb.requestAccess. The permission broker does this for you.