chrome.usb

This API is part of the deprecated Chrome Apps platform. Learn more about migrating your app.

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.
Permissions
usb

Summary

Types
ConfigDescriptor
ConnectionHandle
ControlTransferInfo
Device
DeviceFilter
DevicePromptOptions
Direction
EndpointDescriptor
EnumerateDevicesAndRequestAccessOptions
EnumerateDevicesOptions
GenericTransferInfo
InterfaceDescriptor
IsochronousTransferInfo
Recipient
RequestType
SynchronizationType
TransferResultInfo
TransferType
UsageType
Methods
bulkTransfer
claimInterface
closeDevice
controlTransfer
findDevices
getConfiguration
getConfigurations
getDevices
getUserSelectedDevices
interruptTransfer
isochronousTransfer
listInterfaces
openDevice
releaseInterface
requestAccess
resetDevice
setConfiguration
setInterfaceAlternateSetting
Events
onDeviceAdded
onDeviceRemoved

Types

ConfigDescriptor

Properties

active
boolean
Chrome 47+
Is this the active configuration?
configurationValue
number
The configuration number.
description
string optional
Description of the configuration.
extra_data
ArrayBuffer
Extra descriptor data associated with this configuration.
interfaces
InterfaceDescriptor[]
Available interfaces.
maxPower
number
The maximum power needed by this device in milliamps (mA).
remoteWakeup
boolean
The device supports remote wakeup.
selfPowered
boolean
The device is self-powered.

ConnectionHandle

Properties

handle
number
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.
productId
number
The product ID.
vendorId
number
The device vendor ID.

ControlTransferInfo

Properties

data
ArrayBuffer optional
The data to transmit (required only by output transfers).
direction
Direction
The transfer direction ("in" or "out").
index
number
The wIndex field, see Ibid.
length
number optional
The maximum number of bytes to receive (required only by input transfers).
recipient
Recipient
The transfer target. The target given by index must be claimed if "interface" or "endpoint".
request
number
The bRequest field, see Universal Serial Bus Specification Revision 1.1 § 9.3.
requestType
RequestType
The request type.
timeout
number optional
Chrome 43+
Request timeout (in milliseconds). The default value 0 indicates no timeout.
value
number
The wValue field, see Ibid.

Device

Properties

device
number
An opaque ID for the USB device. It remains unchanged until the device is unplugged.
manufacturerName
string
Chrome 46+
The iManufacturer string read from the device, if available.
productId
number
The product ID.
productName
string
Chrome 46+
The iProduct string read from the device, if available.
serialNumber
string
Chrome 46+
The iSerialNumber string read from the device, if available.
vendorId
number
The device vendor ID.
version
number
Chrome 51+
The device version (bcdDevice field).

DeviceFilter

Properties

interfaceClass
number optional
USB interface class, matches any interface on the device.
interfaceProtocol
number optional
USB interface protocol, checked only if the interface sub-class matches.
interfaceSubclass
number optional
USB interface sub-class, checked only if the interface class matches.
productId
number optional
Device product ID, checked only if the vendor ID matches.
vendorId
number optional
Device vendor ID.

DevicePromptOptions

Properties

filters
DeviceFilter[] optional
Filter the list of devices presented to the user. If multiple filters are provided devices matching any filter will be displayed.
multiple
boolean optional
Allow the user to select multiple devices.

Direction

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

Type

"in"

, or

"out"

EndpointDescriptor

Properties

address
number
Endpoint address.
direction
Direction
Transfer direction.
extra_data
ArrayBuffer
Extra descriptor data associated with this endpoint.
maximumPacketSize
number
Maximum packet size.
pollingInterval
number optional
Polling interval (interrupt and isochronous only).
synchronization
SynchronizationType optional
Transfer synchronization mode (isochronous only).
type
TransferType
Transfer type.
usage
UsageType optional
Endpoint usage hint.

EnumerateDevicesAndRequestAccessOptions

Properties

interfaceId
number optional
The interface ID to request access to. Only available on Chrome OS. It has no effect on other platforms.
productId
number
The product ID.
vendorId
number
The device vendor ID.

EnumerateDevicesOptions

Properties

filters
DeviceFilter[] optional
A device matching any given filter will be returned. An empty filter list will return all devices the app has permission for.
productId
number optional
Deprecated
Equivalent to setting DeviceFilter.productId.
vendorId
number optional
Deprecated
Equivalent to setting DeviceFilter.vendorId.

GenericTransferInfo

Properties

data
ArrayBuffer optional
The data to transmit (required only by output transfers).
direction
Direction
The transfer direction ("in" or "out").
endpoint
number
The target endpoint address. The interface containing this endpoint must be claimed.
length
number optional
The maximum number of bytes to receive (required only by input transfers).
timeout
number optional
Chrome 43+
Request timeout (in milliseconds). The default value 0 indicates no timeout.

InterfaceDescriptor

Properties

alternateSetting
number
The interface alternate setting number (defaults to 0
description
string optional
Description of the interface.
endpoints
EndpointDescriptor[]
Available endpoints.
extra_data
ArrayBuffer
Extra descriptor data associated with this interface.
interfaceClass
number
The USB interface class.
interfaceNumber
number
The interface number.
interfaceProtocol
number
The USB interface protocol.
interfaceSubclass
number
The USB interface sub-class.

IsochronousTransferInfo

Properties

packetLength
number
The length of each of the packets in this transfer.
packets
number
The total number of packets in this transfer.
transferInfo
GenericTransferInfo
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.

Recipient

Type

"device"

"interface"

"endpoint"

, or

"other"

RequestType

Type

"standard"

"class"

"vendor"

, or

"reserved"

SynchronizationType

For interrupt and isochronous modes, SynchronizationType and UsageType map to their namesakes within the USB specification.

Type

"asynchronous"

"adaptive"

, or

"synchronous"

TransferResultInfo

Properties

data
ArrayBuffer optional
The data returned by an input transfer. undefined for output transfers.
resultCode
number optional
A value of 0 indicates that the transfer was a success. Other values indicate failure.

TransferType

Type

"control"

"interrupt"

"isochronous"

, or

"bulk"

UsageType

Type

"data"

"feedback"

"explicitFeedback"

"periodic"

, or

"notification"

Methods

bulkTransfer

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

Performs a bulk transfer on the specified device.

Parameters

handle
ConnectionHandle
An open connection to the device.
transferInfo
GenericTransferInfo
The transfer parameters.
callback
function
The callback parameter looks like: (info: TransferResultInfo) => void
- info
  TransferResultInfo

claimInterface

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

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

handle
ConnectionHandle
An open connection to the device.
interfaceNumber
number
The interface to be claimed.
callback
function
The callback parameter looks like: () => void

closeDevice

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

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

handle
ConnectionHandle
The ConnectionHandle to close.
callback
function optional
The callback parameter looks like: () => void

controlTransfer

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

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

handle
ConnectionHandle
An open connection to the device.
transferInfo
ControlTransferInfo
callback
function
The callback parameter looks like: (info: TransferResultInfo) => void
- info
  TransferResultInfo

findDevices

chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback: function,
)

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

options
EnumerateDevicesAndRequestAccessOptions
The properties to search for on target devices.
callback
function
The callback parameter looks like: (handles: ConnectionHandle[]) => void
- handles
  ConnectionHandle[]

getConfiguration

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

Gets the configuration descriptor for the currently selected configuration.

Parameters

handle
ConnectionHandle
An open connection to the device.
callback
function
The callback parameter looks like: (config: ConfigDescriptor) => void
- config
  ConfigDescriptor

getConfigurations

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

Chrome 47+

Returns the full set of device configuration descriptors.

Parameters

device
Device
The Device to fetch descriptors from.
callback
function
The callback parameter looks like: (configs: ConfigDescriptor[]) => void
- configs
  ConfigDescriptor[]

getDevices

chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback: function,
)

Enumerates connected USB devices.

Parameters

options
EnumerateDevicesOptions
The properties to search for on target devices.
callback
function
The callback parameter looks like: (devices: Device[]) => void
- devices
  Device[]

getUserSelectedDevices

chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback: function,
)

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

options
DevicePromptOptions
Configuration of the device picker dialog box.
callback
function
The callback parameter looks like: (devices: Device[]) => void
- devices
  Device[]

interruptTransfer

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

Performs an interrupt transfer on the specified device.

Parameters

handle
ConnectionHandle
An open connection to the device.
transferInfo
GenericTransferInfo
The transfer parameters.
callback
function
The callback parameter looks like: (info: TransferResultInfo) => void
- info
  TransferResultInfo

isochronousTransfer

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

Performs an isochronous transfer on the specific device.

Parameters

handle
ConnectionHandle
An open connection to the device.
transferInfo
IsochronousTransferInfo
callback
function
The callback parameter looks like: (info: TransferResultInfo) => void
- info
  TransferResultInfo

listInterfaces

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

Lists all interfaces on a USB device.

Parameters

handle
ConnectionHandle
An open connection to the device.
callback
function
The callback parameter looks like: (descriptors: InterfaceDescriptor[]) => void
- descriptors
  InterfaceDescriptor[]

openDevice

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

Opens a USB device returned by getDevices.

Parameters

device
Device
The Device to open.
callback
function
The callback parameter looks like: (handle: ConnectionHandle) => void
- handle
  ConnectionHandle

releaseInterface

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

Releases a claimed interface.

Parameters

handle
ConnectionHandle
An open connection to the device.
interfaceNumber
number
The interface to be released.
callback
function
The callback parameter looks like: () => void

requestAccess

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

Deprecated

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.
interfaceId
number
The particular interface requested.
callback
function
The callback parameter looks like: (success: boolean) => void
- success
  boolean

resetDevice

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

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

handle
ConnectionHandle
A connection handle to reset.
callback
function
The callback parameter looks like: (success: boolean) => void
- success
  boolean

setConfiguration

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

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

handle
ConnectionHandle
An open connection to the device.
configurationValue
number
callback
function
The callback parameter looks like: () => void

setInterfaceAlternateSetting

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

Selects an alternate setting on a previously claimed interface.

Parameters

handle
ConnectionHandle
An open connection to the device where this interface has been claimed.
interfaceNumber
number
The interface to configure.
alternateSetting
number
The alternate setting to configure.
callback
function
The callback parameter looks like: () => void

Events

onDeviceAdded

chrome.usb.onDeviceAdded.addListener(
  callback: function,
)

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.

Parameters

callback
function
The callback parameter looks like: (device: Device) => void
- device
  Device

onDeviceRemoved

chrome.usb.onDeviceRemoved.addListener(
  callback: function,
)

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

Parameters

callback
function
The callback parameter looks like: (device: Device) => void
- device
  Device