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.

Permissions

usb

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.

Enum

"in"

"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).

  • 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

Enum

"device"

"interface"

"endpoint"

"other"

RequestType

Enum

"standard"

"class"

"vendor"

"reserved"

SynchronizationType

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

Enum

"asynchronous"

"adaptive"

"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

Enum

"control"

"interrupt"

"isochronous"

"bulk"

UsageType

Enum

"data"

"feedback"

"explicitFeedback"

"periodic"

"notification"

Methods

bulkTransfer()

Promise 
chrome.usb.bulkTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

Performs a bulk transfer on the specified device.

Parameters

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

claimInterface()

Promise 
chrome.usb.claimInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
): Promise<void>

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

  • An open connection to the device.

  • interfaceNumber

    number

    The interface to be claimed.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

closeDevice()

Promise 
chrome.usb.closeDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<void>

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

Returns

  • Promise<void>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

controlTransfer()

Promise 
chrome.usb.controlTransfer(
  handle: ConnectionHandle,
  transferInfo: ControlTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

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

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

findDevices()

Promise 
chrome.usb.findDevices(
  options: EnumerateDevicesAndRequestAccessOptions,
  callback?: function,
): Promise<ConnectionHandle[]>

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

Returns

  • Promise<ConnectionHandle[]>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getConfiguration()

Promise 
chrome.usb.getConfiguration(
  handle: ConnectionHandle,
  callback?: function,
): Promise<ConfigDescriptor>

Gets the configuration descriptor for the currently selected configuration.

Parameters

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getConfigurations()

Promise Chrome 47+ 
chrome.usb.getConfigurations(
  device: Device,
  callback?: function,
): Promise<ConfigDescriptor[]>

Returns the full set of device configuration descriptors.

Parameters

Returns

  • Promise<ConfigDescriptor[]>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getDevices()

Promise 
chrome.usb.getDevices(
  options: EnumerateDevicesOptions,
  callback?: function,
): Promise<Device[]>

Enumerates connected USB devices.

Parameters

  • The properties to search for on target devices.

  • callback

    function optional

    The callback parameter looks like: 

    (devices: Device[]) => void

Returns

  • Promise<Device[]>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

getUserSelectedDevices()

Promise 
chrome.usb.getUserSelectedDevices(
  options: DevicePromptOptions,
  callback?: function,
): Promise<Device[]>

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

  • Configuration of the device picker dialog box.

  • callback

    function optional

    The callback parameter looks like: 

    (devices: Device[]) => void

Returns

  • Promise<Device[]>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

interruptTransfer()

Promise 
chrome.usb.interruptTransfer(
  handle: ConnectionHandle,
  transferInfo: GenericTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

Performs an interrupt transfer on the specified device.

Parameters

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

isochronousTransfer()

Promise 
chrome.usb.isochronousTransfer(
  handle: ConnectionHandle,
  transferInfo: IsochronousTransferInfo,
  callback?: function,
): Promise<TransferResultInfo>

Performs an isochronous transfer on the specific device.

Parameters

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

listInterfaces()

Promise 
chrome.usb.listInterfaces(
  handle: ConnectionHandle,
  callback?: function,
): Promise<InterfaceDescriptor[]>

Lists all interfaces on a USB device.

Parameters

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

openDevice()

Promise 
chrome.usb.openDevice(
  device: Device,
  callback?: function,
): Promise<ConnectionHandle>

Opens a USB device returned by getDevices.

Parameters

Returns

  • Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

releaseInterface()

Promise 
chrome.usb.releaseInterface(
  handle: ConnectionHandle,
  interfaceNumber: number,
  callback?: function,
): Promise<void>

Releases a claimed interface.

Parameters

  • An open connection to the device.

  • interfaceNumber

    number

    The interface to be released.

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

requestAccess()

Promise Deprecated
chrome.usb.requestAccess(
  device: Device,
  interfaceId: number,
  callback?: function,
): Promise<boolean>

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 optional

    The callback parameter looks like: 

    (success: boolean) => void

    • success

      boolean

Returns

  • Promise<boolean>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

resetDevice()

Promise 
chrome.usb.resetDevice(
  handle: ConnectionHandle,
  callback?: function,
): Promise<boolean>

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

  • A connection handle to reset.

  • callback

    function optional

    The callback parameter looks like: 

    (success: boolean) => void

    • success

      boolean

Returns

  • Promise<boolean>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setConfiguration()

Promise 
chrome.usb.setConfiguration(
  handle: ConnectionHandle,
  configurationValue: number,
  callback?: function,
): Promise<void>

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

  • An open connection to the device.

  • configurationValue

    number

  • callback

    function optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

setInterfaceAlternateSetting()

Promise 
chrome.usb.setInterfaceAlternateSetting(
  handle: ConnectionHandle,
  interfaceNumber: number,
  alternateSetting: number,
  callback?: function,
): Promise<void>

Selects an alternate setting on a previously claimed interface.

Parameters

  • 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 optional

    The callback parameter looks like: 

    () => void

Returns

  • Promise<void>

    Chrome 116+

    Promises are only supported for Manifest V3 and later, other platforms need to use callbacks.

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

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