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.
Availability:	Stable since Chrome 26.
Permissions:	"usb"
Learn More:	Accessing Hardware Devices

Summary

Types
Direction
Device
ConnectionHandle
GenericTransferInfo
TransferResultInfo
Methods
getDevices − `chrome.usb.getDevices(object options, 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)`
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)`

Types

Direction

Direction, Recipient, RequestType, and TransferType all map to their namesakes within the USB specification.

Enum
`"in"`, or `"out"`

Device

properties
integer	device	The id of the USB device. It remains unchanged until the device is unplugged.
integer	vendorId
integer	productId

ConnectionHandle

properties
integer	handle	The id of the USB connection handle.
integer	vendorId
integer	productId

GenericTransferInfo

properties
Direction	direction	The direction of this transfer.
integer	endpoint
integer	(optional) length	If this is an input transfer then this field indicates the size of the input buffer. If this is an output transfer then this field is ignored.
ArrayBuffer	(optional) data	If this is an output transfer then this field must be populated. Otherwise, it will be ignored.

TransferResultInfo

properties
integer	(optional) resultCode	A value of 0 indicates that the transfer was a success. Other values indicate failure.
ArrayBuffer	(optional) data	If the transfer was an input transfer then this field will contain all of the input data requested.

Methods

getDevices


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

Lists USB devices specified by vendorId/productId/interfaceId tuple.

Parameters

object

options

The properties to search for on target devices.

integer	vendorId
integer	productId

function

callback

Invoked with a list of |Device|s on complete.

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

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

array of Device

devices

requestAccess


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

This method is ChromeOS specific. Calling this method on other platforms will fail. Requests access from the permission broker to an OS claimed device if the given interface on the device is not claimed.

Parameters

Device device The device to request access to.

integer interfaceId

function

callback

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

function(boolean sucess) {...};

boolean

sucess

openDevice


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

Opens a USB device returned by |getDevices|.

Parameters

Device device The device to open.

function

callback

Invoked with the created ConnectionHandle on complete.

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 vendorId/productId/interfaceId tuple and, if permissions allow, opens them for use.

On Chrome OS, you can specify the interfaceId. In that case the method will request access from permission broker in the same way as in |requestUsbAcess|.

If the access request is rejected, or the device is failed to be opened, its connection handle will not be created or returned.

Calling this method is equivalent to calling |getDevices| followed by a series of |requestAccess| (if it is on ChromeOs) and |openDevice| calls, and returning all the successfully opened connection handles.

Parameters

object

options

The properties to search for on target devices.

integer	vendorId
integer	productId
integer	(optional) interfaceId	The interface id to request access against. Only available on ChromeOS. It has no effect on other platforms.

function

callback

Invoked with the opened ConnectionHandle on complete.

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 device after it has been closed is a safe operation, but causes no action to be taken.

Parameters
ConnectionHandle	handle	The connection handle to close.
function	(optional) callback	The callback to invoke once the device is closed. If you specify the callback parameter, it should be a function that looks like this: `function() {...};`

listInterfaces


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

Lists all the interfaces on the USB device.

Parameters

ConnectionHandle handle The device from which the interfaces should be listed.

function

callback

The callback to invoke when the interfaces are enumerated.

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

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

array of object

descriptors

Properties of each object

integer interfaceNumber

integer alternateSetting

integer interfaceClass

integer interfaceSubclass

integer interfaceProtocol

string (optional) description

array of object

endpoints

Properties of each object

integer	address
enum of `"control"`, `"interrupt"`, `"isochronous"`, or `"bulk"`	type
Direction	direction
integer	maximumPacketSize
enum of `"asynchronous"`, `"adaptive"`, or `"synchronous"`	(optional) synchronization	Used for isochronous mode.
enum of `"data"`, `"feedback"`, or `"explicitFeedback"`	(optional) usage
integer	(optional) pollingInterval	If this is an interrupt endpoint, this will be 1-255.

claimInterface


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

Claims an interface on the specified USB device. Before you can transfer data with endpoints, you must claim their parent interfaces. Only one connection handle on the same host can claim each interface. If the interface is already claimed, this call will fail.

You shall call releaseInterface when the interface is not needed anymore.

Parameters
ConnectionHandle	handle	The device on which the interface is to be claimed.
integer	interfaceNumber
function	callback	The callback to invoke once the interface is claimed. The callback parameter should be a function that looks like this: `function() {...};`

releaseInterface


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

Releases a claim to an interface on the provided device.

Parameters
ConnectionHandle	handle	The device on which the interface is to be released.
integer	interfaceNumber
function	callback	The callback to invoke once the interface is released. 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 on a device.

Parameters
ConnectionHandle	handle	The device on which the interface settings are to be set.
integer	interfaceNumber
integer	alternateSetting	The alternate setting to set.
function	callback	The callback to invoke once the interface setting is set. 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. See the ControlTransferInfo structure for the parameters required to make a transfer.

Conceptually control transfer talks to the device itself. You do not need to claim interface 0 to perform a control transfer.

Parameters

ConnectionHandle handle A connection handle to make the transfer on.

object

transferInfo

The parameters to the transfer. See ControlTransferInfo.

Direction	direction	The direction of this transfer.
enum of `"device"`, `"interface"`, `"endpoint"`, or `"other"`	recipient	The intended recipient for this transfer.
enum of `"standard"`, `"class"`, `"vendor"`, or `"reserved"`	requestType	The type of this request.
integer	request
integer	value
integer	index
integer	(optional) length	If this transfer is an input transfer, then this field must be set to indicate the expected data length. If this is an output transfer, then this field is ignored.
ArrayBuffer	(optional) data	The data payload carried by this transfer. If this is an output transfer then this field must be set.

function

callback

Invoked once the transfer has completed.

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 A connection handle to make the transfer on.

GenericTransferInfo transferInfo The parameters to the transfer. See GenericTransferInfo.

function

callback

Invoked once the transfer has completed.

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 A connection handle to make the transfer on.

GenericTransferInfo transferInfo The parameters to the transfer. See GenericTransferInfo.

function

callback

Invoked once the transfer has completed.

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 A connection handle to make the transfer on.

object

transferInfo

The parameters to the transfer. See IsochronousTransferInfo.

GenericTransferInfo	transferInfo	All of the normal transfer parameters are encapsulated in the transferInfo parameters. Note that the data 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

Invoked once the transfer has been completed.

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 and restores it to the previous status. If the reset fails, the given connection handle will be closed and the USB device will appear to be disconnected then reconnected. In that case you must call |getDevices| or |findDevices| again to acquire the device.

Parameters

ConnectionHandle handle A connection handle to reset.

function

callback

Invoked once the device is reset with a boolean indicating whether the reset is completed successfully.

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

function(boolean result) {...};

boolean

result