the Chromium logo

The Chromium Projects

USB API

Proposal Date

March 7th, 2012 Who is the primary contact for this API? gdk@chromium.org Who will be responsible for this API? (Team please, not an individual)

Apps Extension API Team

Overview The USB API aims to provide access to fundamental low-level USB operations from within the context of an extension. Use cases

Maybe. This API has the potential to be very controversial, and I believe there are people within the standards organization that would not back it.

Do you expect this API to be fairly stable? How might it be extended or changed in the future?

The API should remain fairly stable, as the fundamental mechanism for interacting with USB devices is standardized and does not change. This API will surface the underlying USB mechanisms for communication, and so itself should not need to change.

List every UI surface belonging to or potentially affected by your API:

How could this API be abused?

Imagine you’re Dr. Evil Extension Writer, list the three worst evil deeds you could commit with your API (if you’ve got good ones, feel free to add more):

  1. Use a USB-attached device to cause physical harm.
  2. Cause permanent harm to a USB device.
  3. TODO. Alright Doctor, one last challenge: Could a consumer of your API cause any permanent change to the user’s system using your API that would not be reversed when that consumer is removed from the system?

Yes. There are circumstances where a USB device could be put into a bad state (or frozen entirely!) that may be impossible to restore to a pristine state without physically reconnecting the device. The attached devices could also, for example, themselves leave a physical trace. A printer driver could print a page, a CD writer could write a disc, a robot karate arm could break a table, etc.

How would you implement your desired features if this API didn't exist?

By writing code that used libusb and then surfacing some form of WebSocket interface that would allow a client to communicate with my device-specific server.

Draft API spec

API reference: chrome.experimental.usb

Methods

bulkTransfer

chrome.experimental.usb.bulkTransfer(integer device, string direction,integer endpoint, string data, function callback)

Performs a USB bulk transfer to the specified device.

Parameters

device

( integer )

A device handle on which the transfer is to be made.

direction

( string )

The direction of the control transfer. "in" for an inbound transfer, "out" for an outbound transfer.

endpoint

( integer )

The endpoint to which this transfer is being made.

data

( string )

(TODO(gdk): ArrayBuffer) The bulk data payload for this transfer.

callback

( optional function )

A callback to be invoked with the results of this transfer.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(object result) {...};

result

( object )

data

( optional string )

(TODO(gdk): ArrayBuffer) If the transfer results in inbound data, it is returned here.

result

( integer )

On success, 0 is returned. On failure, -1.

closeDevice

chrome.experimental.usb.closeDevice(integer device, undefined callback)

Close a USB device handle.

Parameters

device

( integer )

The device handle to be closed.

callback

( optional function )

A callback function that is invoked after the device has been closed.

controlTransfer

chrome.experimental.usb.controlTransfer(integer device, string direction, string recipient, string type,integer request, integer value, integer index, string data, function callback)

Performs a USB control transfer to the specified device.

Parameters

device

( integer )

A device handle on which the transfer is to be made.

direction

( string )

The direction of the control transfer. "in" for an inbound transfer, "out" for an outbound transfer.

recipient

( string )

The intended recipient of this message. Must be one of "device", "interface", "endpoint" or "other".

type

( string )

The type of this request. Must be one of "standard", "class", "vendor" or "reserved".

request

( integer )

value

( integer )

index

( integer )

data

( string )

(TODO(gdk): ArrayBuffer) The data payload carried by this transfer.

callback

( optional function )

An optional callback that is invoked when this transfer completes.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(object result) {...};

result

( object )

data

( optional string )

(TODO(gdk): ArrayBuffer) If the transfer is inbound, then this field is populated with the data transferred from the device.

result

( integer )

On success, 0 is returned. On failure, -1.

createContext

chrome.experimental.usb.createContext(function callback)

Creates a USB context by which devices may be found.

Parameters

callback

( function )

Callback function

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

function(integer result) {...};

result

( integer )

The handle to the created context. On failure, -1.

destroyContext

chrome.experimental.usb.destroyContext(integer context)

Disposes of a context that is no longer needed. It is not necessary that this call be made at all, unless you want to explicitly free the resources associated with a context.

Parameters

context

( integer )

findDevice

chrome.experimental.usb.findDevice(integer context, integer vendorId, integer productId, function callback)

Locates an instance of the device specified by its vendor and product identifier.

Parameters

context

( integer )

A handle to a USB context.

vendorId

( integer )

The vendor ID of the device to search for.

productId

( integer )

The product ID of the device to search for.

callback

( function )

Callback function

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

function(integer result) {...};

result

( integer )

On success, the handle to the found USB device. On failure, -1.

interruptTransfer

chrome.experimental.usb.interruptTransfer(integer device, string direction, integer endpoint, string data,function callback)

Performs a USB interrupt transfer to the specified device.

Parameters

device

( integer )

A device handle on which the transfer is to be made.

direction

( string )

The direction of the control transfer. "in" for an inbound transfer, "out" for an outbound transfer.

endpoint

( integer )

The endpoint to which this transfer is being made.

data

( string )

(TODO(gdk): ArrayBuffer) The interrupt data payload for this transfer.

callback

( optional function )

A callback to be invoked with the results of this transfer.

Callback function

If you specify the callback parameter, it should specify a function that looks like this:

function(object result) {...};

result

( object )

data

( optional string )

(TODO(gdk): ArrayBuffer) If the transfer results in inbound data, it is returned here.

result

( integer )

On success, 0 is returned. On failure, -1.

Open questions Note any unanswered questions that require further discussion.