Welcome Getting started API Reference Samples
Welcome Getting started API Reference Samples

chrome.usb

Warning
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

Properties

  • active
    boolean

    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.

  • 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

    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

    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

    The request type.

  • timeout
    number optional

    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

    The iManufacturer string read from the device, if available.

  • productId
    number

    The product ID.

  • productName
    string

    The iProduct string read from the device, if available.

  • serialNumber
    string

    The iSerialNumber string read from the device, if available.

  • vendorId
    number

    The device vendor ID.

  • version
    number

    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.

EndpointDescriptor

Properties

  • address
    number

    Endpoint address.

  • 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

    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

    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

    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.

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

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

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.

Direction

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

Enum

"in", or "out"

Recipient

Enum

"device", "interface", "endpoint", or "other"

RequestType

Enum

"standard", "class", "vendor", or "reserved"

SynchronizationType

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

Enum

"asynchronous", "adaptive", or "synchronous"

TransferType

Enum

"control", "interrupt", "isochronous", or "bulk"

UsageType

Enum

"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

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

  • An open connection to the device.

  • interfaceNumber
    number

    The interface to be claimed.

  • callback
    function

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

    () => {...}

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

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

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

getConfiguration

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

Gets the configuration descriptor for the currently selected configuration.

Parameters

getConfigurations

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

Returns the full set of device configuration descriptors.

Parameters

getDevices

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

Enumerates connected USB devices.

Parameters

  • The properties to search for on target devices.

  • callback
    function

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

    (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

  • Configuration of the device picker dialog box.

  • callback
    function

    Invoked with a list of chosen Devices.

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

    (devices: Device[]) => {...}

interruptTransfer

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

Performs an interrupt transfer on the specified device.

Parameters

isochronousTransfer

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

Performs an isochronous transfer on the specific device.

Parameters

listInterfaces

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

Lists all interfaces on a USB device.

Parameters

openDevice

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

Opens a USB device returned by getDevices.

Parameters

releaseInterface

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

Releases a claimed interface.

Parameters

  • An open connection to the device.

  • interfaceNumber
    number

    The interface to be released.

  • callback
    function

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

    () => {...}

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

    The Device to request access to.

  • interfaceId
    number

    The particular interface requested.

  • callback
    function

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

    (success: boolean) => {...}
    • 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

  • A connection handle to reset.

  • callback
    function

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

    (success: boolean) => {...}
    • 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

  • An open connection to the device.

  • configurationValue
    number
  • callback
    function

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

    () => {...}

setInterfaceAlternateSetting

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

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

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

    () => {...}

Events

onDeviceAdded

chrome.usb.onDeviceAdded.addListener(listener: 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.

Event

  • listener
    function

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

    (device: Device) => {...}

onDeviceRemoved

chrome.usb.onDeviceRemoved.addListener(listener: function)

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

Event

  • listener
    function

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

    (device: Device) => {...}
We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.