chrome.usb

Description: Use the chrome.usb API to interact with connected USB devices. This API provides access to USB operations from within the context of an app. Using this API, apps can function as drivers for hardware devices. Errors generated by this API are reported by setting runtime.lastError and executing the function's regular callback. The callback's regular parameters will be undefined in this case.
Availability: Since Chrome 35.
Permissions: "usb"
Learn More: Accessing Hardware Devices

Summary

Types
Direction
Device
ConnectionHandle
EndpointDescriptor
InterfaceDescriptor
ConfigDescriptor
GenericTransferInfo
TransferResultInfo
DeviceFilter
Methods
getDevices − chrome.usb.getDevices(object options, function callback)
getUserSelectedDevices − chrome.usb.getUserSelectedDevices(object options, function callback)
getConfigurations − chrome.usb.getConfigurations( Device device, function callback)
requestAccess − chrome.usb.requestAccess( Device device, integer interfaceId, function callback)
openDevice − chrome.usb.openDevice( Device device, function callback)
findDevices − chrome.usb.findDevices(object options, function callback)
closeDevice − chrome.usb.closeDevice( ConnectionHandle handle, function callback)
setConfiguration − chrome.usb.setConfiguration( ConnectionHandle handle, integer configurationValue, function callback)
getConfiguration − chrome.usb.getConfiguration( ConnectionHandle handle, function callback)
listInterfaces − chrome.usb.listInterfaces( ConnectionHandle handle, function callback)
claimInterface − chrome.usb.claimInterface( ConnectionHandle handle, integer interfaceNumber, function callback)
releaseInterface − chrome.usb.releaseInterface( ConnectionHandle handle, integer interfaceNumber, function callback)
setInterfaceAlternateSetting − chrome.usb.setInterfaceAlternateSetting( ConnectionHandle handle, integer interfaceNumber, integer alternateSetting, function callback)
controlTransfer − chrome.usb.controlTransfer( ConnectionHandle handle, object transferInfo, function callback)
bulkTransfer − chrome.usb.bulkTransfer( ConnectionHandle handle, GenericTransferInfo transferInfo, function callback)
interruptTransfer − chrome.usb.interruptTransfer( ConnectionHandle handle, GenericTransferInfo transferInfo, function callback)
isochronousTransfer − chrome.usb.isochronousTransfer( ConnectionHandle handle, object transferInfo, function callback)
resetDevice − chrome.usb.resetDevice( ConnectionHandle handle, function callback)
Events
onDeviceAdded
onDeviceRemoved

Types

Direction

Direction, Recipient, RequestType, and TransferType all map to their namesakes within the USB specification.
Enum
"in", or "out"

Device

properties
integer device

An opaque ID for the USB device. It remains unchanged until the device is unplugged.

integer vendorId

The device vendor ID.

integer productId

The product ID.

integer version

Since Chrome 51.

The device version (bcdDevice field).

string productName

Since Chrome 46.

The iProduct string read from the device, if available.

string manufacturerName

Since Chrome 46.

The iManufacturer string read from the device, if available.

string serialNumber

Since Chrome 46.

The iSerialNumber string read from the device, if available.

ConnectionHandle

properties
integer handle

An opaque handle representing this connection to the USB device and all associated claimed interfaces and pending transfers. A new handle is created each time the device is opened. The connection handle is different from Device.device.

integer vendorId

The device vendor ID.

integer productId

The product ID.

EndpointDescriptor

properties
integer address

Endpoint address.

enum of "control", "interrupt", "isochronous", or "bulk" type

Transfer type.

Direction direction

Transfer direction.

integer maximumPacketSize

Maximum packet size.

enum of "asynchronous", "adaptive", or "synchronous" (optional) synchronization

Transfer synchronization mode (isochronous only).

enum of "data", "feedback", "explicitFeedback", "periodic", or "notification" (optional) usage

Endpoint usage hint.

integer (optional) pollingInterval

Polling interval (interrupt and isochronous only).

ArrayBuffer extra_data

Since Chrome 39.

Extra descriptor data associated with this endpoint.

InterfaceDescriptor

properties
integer interfaceNumber

The interface number.

integer alternateSetting

The interface alternate setting number (defaults to 0
integer interfaceClass

The USB interface class.

integer interfaceSubclass

The USB interface sub-class.

integer interfaceProtocol

The USB interface protocol.

string (optional) description

Description of the interface.

array of EndpointDescriptor endpoints

Available endpoints.

ArrayBuffer extra_data

Since Chrome 39.

Extra descriptor data associated with this interface.

ConfigDescriptor

Since Chrome 39.

properties
boolean active

Since Chrome 47.

Is this the active configuration?

integer configurationValue

The configuration number.

string (optional) description

Description of the configuration.

boolean selfPowered

The device is self-powered.

boolean remoteWakeup

The device supports remote wakeup.

integer maxPower

The maximum power needed by this device in milliamps (mA).

array of InterfaceDescriptor interfaces

Available interfaces.

ArrayBuffer extra_data

Extra descriptor data associated with this configuration.

GenericTransferInfo

properties
Direction direction

The transfer direction ("in" or "out").

integer endpoint

The target endpoint address. The interface containing this endpoint must be claimed.

integer (optional) length

The maximum number of bytes to receive (required only by input transfers).

ArrayBuffer (optional) data

The data to transmit (required only by output transfers).

integer (optional) timeout

Since Chrome 43.

Request timeout (in milliseconds). The default value 0 indicates no timeout.

TransferResultInfo

properties
integer (optional) resultCode

A value of 0 indicates that the transfer was a success. Other values indicate failure.

ArrayBuffer (optional) data

The data returned by an input transfer. undefined for output transfers.

DeviceFilter

Since Chrome 39.

properties
integer (optional) vendorId

Device vendor ID.

integer (optional) productId

Device product ID, checked only if the vendor ID matches.

integer (optional) interfaceClass

USB interface class, matches any interface on the device.

integer (optional) interfaceSubclass

USB interface sub-class, checked only if the interface class matches.

integer (optional) interfaceProtocol

USB interface protocol, checked only if the interface sub-class matches.

Methods

getDevices

chrome.usb.getDevices(object options, function callback)

Enumerates connected USB devices.

Parameters
object options

The properties to search for on target devices.

integer (optional) vendorId

Deprecated since Chrome 39. Equivalent to setting DeviceFilter.vendorId.

integer (optional) productId

Deprecated since Chrome 39. Equivalent to setting DeviceFilter.productId.

array of DeviceFilter (optional) filters

Since Chrome 39.

A device matching any given filter will be returned. An empty filter list will return all devices the app has permission for.

function callback

The callback parameter should be a function that looks like this:

function(array of Device devices) {...};
array of Device devices

getUserSelectedDevices

chrome.usb.getUserSelectedDevices(object options, function callback)

Since Chrome 40.

Presents a device picker to the user and returns the Devices selected. If the user cancels the picker devices will be empty. A user gesture is required for the dialog to display. Without a user gesture, the callback will run as though the user cancelled.

Parameters
object options

Configuration of the device picker dialog box.

boolean (optional) multiple

Allow the user to select multiple devices.

array of DeviceFilter (optional) filters

Filter the list of devices presented to the user. If multiple filters are provided devices matching any filter will be displayed.

function callback

Invoked with a list of chosen Devices.

The callback parameter should be a function that looks like this:

function(array of Device devices) {...};
array of Device devices

getConfigurations

chrome.usb.getConfigurations( Device device, function callback)

Since Chrome 47.

Returns the full set of device configuration descriptors.

Parameters
Device device

The Device to fetch descriptors from.

function callback

The callback parameter should be a function that looks like this:

function(array of ConfigDescriptor configs) {...};
array of ConfigDescriptor configs

requestAccess

chrome.usb.requestAccess( Device device, integer interfaceId, function callback)

Deprecated since Chrome 40. This function was Chrome OS specific and calling it on other platforms would fail. This operation is now implicitly performed as part of openDevice and this function will return true on all platforms.

Requests access from the permission broker to a device claimed by Chrome OS if the given interface on the device is not claimed.

Parameters
Device device

The Device to request access to.

integer interfaceId

The particular interface requested.

function callback

The callback parameter should be a function that looks like this:

function(boolean success) {...};
boolean success

openDevice

chrome.usb.openDevice( Device device, function callback)

Opens a USB device returned by getDevices.

Parameters
Device device

The Device to open.

function callback

The callback parameter should be a function that looks like this:

function( ConnectionHandle handle) {...};
ConnectionHandle handle

findDevices

chrome.usb.findDevices(object options, function callback)

Finds USB devices specified by the vendor, product and (optionally) interface IDs and if permissions allow opens them for use.

If the access request is rejected or the device fails to be opened a connection handle will not be created or returned.

Calling this method is equivalent to calling getDevices followed by openDevice for each device.

Parameters
object options

The properties to search for on target devices.

integer vendorId

The device vendor ID.

integer productId

The product ID.

integer (optional) interfaceId

The interface ID to request access to. Only available on Chrome OS. It has no effect on other platforms.

function callback

The callback parameter should be a function that looks like this:

function(array of ConnectionHandle handles) {...};
array of ConnectionHandle handles

closeDevice

chrome.usb.closeDevice( ConnectionHandle handle, function callback)

Closes a connection handle. Invoking operations on a handle after it has been closed is a safe operation but causes no action to be taken.

Parameters
ConnectionHandle handle

The ConnectionHandle to close.

function (optional) callback

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

setConfiguration

chrome.usb.setConfiguration( ConnectionHandle handle, integer configurationValue, function callback)

Since Chrome 42.

Select a device configuration.

This function effectively resets the device by selecting one of the device's available configurations. Only configuration values greater than 0 are valid however some buggy devices have a working configuration 0 and so this value is allowed.

Parameters
ConnectionHandle handle

Since Chrome 41.

An open connection to the device.

integer configurationValue

Since Chrome 41.

function callback

The callback parameter should be a function that looks like this:

function() {...};

getConfiguration

chrome.usb.getConfiguration( ConnectionHandle handle, function callback)

Since Chrome 39.

Gets the configuration descriptor for the currently selected configuration.

Parameters
ConnectionHandle handle

An open connection to the device.

function callback

The callback parameter should be a function that looks like this:

function( ConfigDescriptor config) {...};
ConfigDescriptor config

listInterfaces

chrome.usb.listInterfaces( ConnectionHandle handle, function callback)

Lists all interfaces on a USB device.

Parameters
ConnectionHandle handle

An open connection to the device.

function callback

The callback parameter should be a function that looks like this:

function(array of InterfaceDescriptor descriptors) {...};
array of InterfaceDescriptor descriptors

claimInterface

chrome.usb.claimInterface( ConnectionHandle handle, integer interfaceNumber, function callback)

Claims an interface on a USB device. Before data can be transfered to an interface or associated endpoints the interface must be claimed. Only one connection handle can claim an interface at any given time. If the interface is already claimed, this call will fail.

releaseInterface should be called when the interface is no longer needed.

Parameters
ConnectionHandle handle

An open connection to the device.

integer interfaceNumber

The interface to be claimed.

function callback

The callback parameter should be a function that looks like this:

function() {...};

releaseInterface

chrome.usb.releaseInterface( ConnectionHandle handle, integer interfaceNumber, function callback)

Releases a claimed interface.

Parameters
ConnectionHandle handle

An open connection to the device.

integer interfaceNumber

The interface to be released.

function callback

The callback parameter should be a function that looks like this:

function() {...};

setInterfaceAlternateSetting

chrome.usb.setInterfaceAlternateSetting( ConnectionHandle handle, integer interfaceNumber, integer alternateSetting, function callback)

Selects an alternate setting on a previously claimed interface.

Parameters
ConnectionHandle handle

An open connection to the device where this interface has been claimed.

integer interfaceNumber

The interface to configure.

integer alternateSetting

The alternate setting to configure.

function callback

The callback parameter should be a function that looks like this:

function() {...};

controlTransfer

chrome.usb.controlTransfer( ConnectionHandle handle, object transferInfo, function callback)

Performs a control transfer on the specified device.

Control transfers refer to either the device, an interface or an endpoint. Transfers to an interface or endpoint require the interface to be claimed.

Parameters
ConnectionHandle handle

An open connection to the device.

object transferInfo
Direction direction

The transfer direction ("in" or "out").

enum of "device", "interface", "endpoint", or "other" recipient

The transfer target. The target given by index must be claimed if "interface" or "endpoint".

enum of "standard", "class", "vendor", or "reserved" requestType

The request type.

integer request

The bRequest field, see Universal Serial Bus Specification Revision 1.1 § 9.3.

integer value

The wValue field, see Ibid.

integer index

The wIndex field, see Ibid.

integer (optional) length

The maximum number of bytes to receive (required only by input transfers).

ArrayBuffer (optional) data

The data to transmit (required only by output transfers).

integer (optional) timeout

Since Chrome 43.

Request timeout (in milliseconds). The default value 0 indicates no timeout.

function callback

The callback parameter should be a function that looks like this:

function( TransferResultInfo info) {...};
TransferResultInfo info

bulkTransfer

chrome.usb.bulkTransfer( ConnectionHandle handle, GenericTransferInfo transferInfo, function callback)

Performs a bulk transfer on the specified device.

Parameters
ConnectionHandle handle

An open connection to the device.

GenericTransferInfo transferInfo

The transfer parameters.

function callback

The callback parameter should be a function that looks like this:

function( TransferResultInfo info) {...};
TransferResultInfo info

interruptTransfer

chrome.usb.interruptTransfer( ConnectionHandle handle, GenericTransferInfo transferInfo, function callback)

Performs an interrupt transfer on the specified device.

Parameters
ConnectionHandle handle

An open connection to the device.

GenericTransferInfo transferInfo

The transfer parameters.

function callback

The callback parameter should be a function that looks like this:

function( TransferResultInfo info) {...};
TransferResultInfo info

isochronousTransfer

chrome.usb.isochronousTransfer( ConnectionHandle handle, object transferInfo, function callback)

Performs an isochronous transfer on the specific device.

Parameters
ConnectionHandle handle

An open connection to the device.

object transferInfo
GenericTransferInfo transferInfo

Transfer parameters. The transfer length or data buffer specified in this parameter block is split along packetLength boundaries to form the individual packets of the transfer.

integer packets

The total number of packets in this transfer.

integer packetLength

The length of each of the packets in this transfer.

function callback

The callback parameter should be a function that looks like this:

function( TransferResultInfo info) {...};
TransferResultInfo info

resetDevice

chrome.usb.resetDevice( ConnectionHandle handle, function callback)

Tries to reset the USB device. If the reset fails, the given connection handle will be closed and the USB device will appear to be disconnected then reconnected. In this case getDevices or findDevices must be called again to acquire the device.

Parameters
ConnectionHandle handle

A connection handle to reset.

function callback

The callback parameter should be a function that looks like this:

function(boolean success) {...};
boolean success

Events

onDeviceAdded

Since Chrome 42.

Event generated when a device is added to the system. Events are only broadcast to apps and extensions that have permission to access the device. Permission may have been granted at install time, when the user accepted an optional permission (see permissions.request), or through getUserSelectedDevices.

addListener

chrome.usb.onDeviceAdded.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( Device device) {...};
Device device

Since Chrome 41.

onDeviceRemoved

Since Chrome 42.

Event generated when a device is removed from the system. See onDeviceAdded for which events are delivered.

addListener

chrome.usb.onDeviceRemoved.addListener(function callback)
Parameters
function callback

The callback parameter should be a function that looks like this:

function( Device device) {...};
Device device

Since Chrome 41.