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 settingruntime.lastError
and executing the function's regular callback. The callback's regular parameters will be undefined in this case. - Permissions
usb
Summary
- Types
- Methods
usb.bulkTransfer(handle: ConnectionHandle, transferInfo: GenericTransferInfo, callback: function)
usb.claimInterface(handle: ConnectionHandle, interfaceNumber: number, callback: function)
usb.closeDevice(handle: ConnectionHandle, callback: function)
usb.controlTransfer(handle: ConnectionHandle, transferInfo: ControlTransferInfo, callback: function)
usb.findDevices(options: EnumerateDevicesAndRequestAccessOptions, callback: function)
usb.getConfiguration(handle: ConnectionHandle, callback: function)
usb.getConfigurations(device: Device, callback: function)
usb.getDevices(options: EnumerateDevicesOptions, callback: function)
usb.getUserSelectedDevices(options: DevicePromptOptions, callback: function)
usb.interruptTransfer(handle: ConnectionHandle, transferInfo: GenericTransferInfo, callback: function)
usb.isochronousTransfer(handle: ConnectionHandle, transferInfo: IsochronousTransferInfo, callback: function)
usb.listInterfaces(handle: ConnectionHandle, callback: function)
usb.openDevice(device: Device, callback: function)
usb.releaseInterface(handle: ConnectionHandle, interfaceNumber: number, callback: function)
usb.requestAccess(device: Device, interfaceId: number, callback: function)
usb.resetDevice(handle: ConnectionHandle, callback: function)
usb.setConfiguration(handle: ConnectionHandle, configurationValue: number, callback: function)
usb.setInterfaceAlternateSetting(handle: ConnectionHandle, interfaceNumber: number, alternateSetting: number, callback: function)
- Events
Types
ConfigDescriptor
Properties
- activeboolean
Since Chrome 47.
Is this the active configuration?
- configurationValuenumber
The configuration number.
- descriptionstring optional
Description of the configuration.
- extra_dataArrayBuffer
Extra descriptor data associated with this configuration.
- interfaces
Available interfaces.
- maxPowernumber
The maximum power needed by this device in milliamps (mA).
- remoteWakeupboolean
The device supports remote wakeup.
- selfPoweredboolean
The device is self-powered.
ConnectionHandle
Properties
- handlenumber
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
. - productIdnumber
The product ID.
- vendorIdnumber
The device vendor ID.
ControlTransferInfo
Properties
- dataArrayBuffer optional
The data to transmit (required only by output transfers).
- direction
The transfer direction (
"in"
or"out"
). - indexnumber
The
wIndex
field, see Ibid. - lengthnumber 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"
. - requestnumber
The
bRequest
field, see Universal Serial Bus Specification Revision 1.1 § 9.3. - requestType
The request type.
- timeoutnumber optional
Since Chrome 43.
Request timeout (in milliseconds). The default value
0
indicates no timeout. - valuenumber
The
wValue
field, see Ibid.
Device
Properties
- devicenumber
An opaque ID for the USB device. It remains unchanged until the device is unplugged.
- manufacturerNamestring
Since Chrome 46.
The iManufacturer string read from the device, if available.
- productIdnumber
The product ID.
- productNamestring
Since Chrome 46.
The iProduct string read from the device, if available.
- serialNumberstring
Since Chrome 46.
The iSerialNumber string read from the device, if available.
- vendorIdnumber
The device vendor ID.
- versionnumber
Since Chrome 51.
The device version (bcdDevice field).
DeviceFilter
Properties
- interfaceClassnumber optional
USB interface class, matches any interface on the device.
- interfaceProtocolnumber optional
USB interface protocol, checked only if the interface sub-class matches.
- interfaceSubclassnumber optional
USB interface sub-class, checked only if the interface class matches.
- productIdnumber optional
Device product ID, checked only if the vendor ID matches.
- vendorIdnumber optional
Device vendor ID.
DevicePromptOptions
Since Chrome 40.
Properties
- filtersDeviceFilter[] optional
Filter the list of devices presented to the user. If multiple filters are provided devices matching any filter will be displayed.
- multipleboolean optional
Allow the user to select multiple devices.
EndpointDescriptor
Properties
- addressnumber
Endpoint address.
- direction
Transfer direction.
- extra_dataArrayBuffer
Extra descriptor data associated with this endpoint.
- maximumPacketSizenumber
Maximum packet size.
- pollingIntervalnumber optional
Polling interval (interrupt and isochronous only).
- synchronizationSynchronizationType optional
Transfer synchronization mode (isochronous only).
- type
Transfer type.
- usageUsageType optional
Endpoint usage hint.
EnumerateDevicesAndRequestAccessOptions
Properties
- interfaceIdnumber optional
The interface ID to request access to. Only available on Chrome OS. It has no effect on other platforms.
- productIdnumber
The product ID.
- vendorIdnumber
The device vendor ID.
EnumerateDevicesOptions
Properties
- filtersDeviceFilter[] optional
A device matching any given filter will be returned. An empty filter list will return all devices the app has permission for.
- productIdnumber optional
Deprecated. Equivalent to setting
DeviceFilter.productId
. - vendorIdnumber optional
Deprecated. Equivalent to setting
DeviceFilter.vendorId
.
GenericTransferInfo
Properties
- dataArrayBuffer optional
The data to transmit (required only by output transfers).
- direction
The transfer direction (
"in"
or"out"
). - endpointnumber
The target endpoint address. The interface containing this endpoint must be claimed.
- lengthnumber optional
The maximum number of bytes to receive (required only by input transfers).
- timeoutnumber optional
Since Chrome 43.
Request timeout (in milliseconds). The default value
0
indicates no timeout.
InterfaceDescriptor
Properties
- alternateSettingnumber
The interface alternate setting number (defaults to
0</code).
- descriptionstring optional
Description of the interface.
- endpoints
Available endpoints.
- extra_dataArrayBuffer
Extra descriptor data associated with this interface.
- interfaceClassnumber
The USB interface class.
- interfaceNumbernumber
The interface number.
- interfaceProtocolnumber
The USB interface protocol.
- interfaceSubclassnumber
The USB interface sub-class.
IsochronousTransferInfo
Properties
- packetLengthnumber
The length of each of the packets in this transfer.
- packetsnumber
The total number of packets in this transfer.
- 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.
TransferResultInfo
Properties
- dataArrayBuffer optional
The data returned by an input transfer.
undefined
for output transfers. - resultCodenumber 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
usb.bulkTransfer(handle: ConnectionHandle, transferInfo: GenericTransferInfo, callback: function)
Performs a bulk transfer on the specified device.
Parameters
- handle
An open connection to the device.
- transferInfo
The transfer parameters.
- callbackfunction
The callback parameter should be a function that looks like this:
(info: TransferResultInfo) => {...}
claimInterface
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
An open connection to the device.
- interfaceNumbernumber
The interface to be claimed.
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
closeDevice
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
The
ConnectionHandle
to close. - callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
controlTransfer
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
An open connection to the device.
- transferInfo
- callbackfunction
The callback parameter should be a function that looks like this:
(info: TransferResultInfo) => {...}
findDevices
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
The properties to search for on target devices.
- callbackfunction
The callback parameter should be a function that looks like this:
(handles: ConnectionHandle[]) => {...}
- handles
getConfiguration
usb.getConfiguration(handle: ConnectionHandle, callback: function)
Gets the configuration descriptor for the currently selected configuration.
Parameters
- handle
An open connection to the device.
- callbackfunction
The callback parameter should be a function that looks like this:
(config: ConfigDescriptor) => {...}
- config
getConfigurations
usb.getConfigurations(device: Device, callback: function)
Since Chrome 47.
Returns the full set of device configuration descriptors.
Parameters
- device
The
Device
to fetch descriptors from. - callbackfunction
The callback parameter should be a function that looks like this:
(configs: ConfigDescriptor[]) => {...}
- configs
getDevices
usb.getDevices(options: EnumerateDevicesOptions, callback: function)
Enumerates connected USB devices.
Parameters
- options
The properties to search for on target devices.
- callbackfunction
getUserSelectedDevices
usb.getUserSelectedDevices(options: DevicePromptOptions, callback: function)
Since Chrome 40.
Presents a device picker to the user and returns the Device
s 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
Configuration of the device picker dialog box.
- callbackfunction
interruptTransfer
usb.interruptTransfer(handle: ConnectionHandle, transferInfo: GenericTransferInfo, callback: function)
Performs an interrupt transfer on the specified device.
Parameters
- handle
An open connection to the device.
- transferInfo
The transfer parameters.
- callbackfunction
The callback parameter should be a function that looks like this:
(info: TransferResultInfo) => {...}
isochronousTransfer
usb.isochronousTransfer(handle: ConnectionHandle, transferInfo: IsochronousTransferInfo, callback: function)
Performs an isochronous transfer on the specific device.
Parameters
- handle
An open connection to the device.
- transferInfo
- callbackfunction
The callback parameter should be a function that looks like this:
(info: TransferResultInfo) => {...}
listInterfaces
usb.listInterfaces(handle: ConnectionHandle, callback: function)
Lists all interfaces on a USB device.
Parameters
- handle
An open connection to the device.
- callbackfunction
The callback parameter should be a function that looks like this:
(descriptors: InterfaceDescriptor[]) => {...}
- descriptors
openDevice
usb.openDevice(device: Device, callback: function)
Opens a USB device returned by getDevices
.
Parameters
- device
The
Device
to open. - callbackfunction
The callback parameter should be a function that looks like this:
(handle: ConnectionHandle) => {...}
- handle
releaseInterface
usb.releaseInterface(handle: ConnectionHandle, interfaceNumber: number, callback: function)
Releases a claimed interface.
Parameters
- handle
An open connection to the device.
- interfaceNumbernumber
The interface to be released.
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
requestAccess
usb.requestAccess(device: Device, interfaceId: number, callback: function)
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.
resetDevice
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
A connection handle to reset.
- callbackfunction
The callback parameter should be a function that looks like this:
(success: boolean) => {...}
- successboolean
setConfiguration
usb.setConfiguration(handle: ConnectionHandle, configurationValue: number, callback: function)
Since Chrome 41.
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
An open connection to the device.
- configurationValuenumber
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
setInterfaceAlternateSetting
usb.setInterfaceAlternateSetting(handle: ConnectionHandle, interfaceNumber: number, alternateSetting: number, callback: function)
Selects an alternate setting on a previously claimed interface.
Parameters
- handle
An open connection to the device where this interface has been claimed.
- interfaceNumbernumber
The interface to configure.
- alternateSettingnumber
The alternate setting to configure.
- callbackfunction
The callback parameter should be a function that looks like this:
() => {...}
Events
onDeviceAdded
usb.onDeviceAdded.addListener(listener: function)
Since Chrome 41.
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
.
onDeviceRemoved
usb.onDeviceRemoved.addListener(listener: function)
Since Chrome 41.
Event generated when a device is removed from the system. See onDeviceAdded
for which events are delivered.