Update USB API docs

chrome/common/extensions/docs/templates/articles/app_hardware.html

 <h1>Accessing Hardware Devices</h1>
 
 <p>
-This doc shows you how packaged apps can connect to USB devices
-and read from and write to a user's serial ports.
-See also the reference docs for the
-<a href="usb.html">USB API</a>
-and the
-<a href="serial.html">Serial API</a>.
-The <a href="bluetooth.html">Bluetooth API</a> is also available;
-we've include a link to a Bluetooth sample below.
+  This doc shows you how packaged apps can connect to USB devices and read from
+  and write to a user's serial ports. See also the reference docs for the <a
+    href="usb.html">USB API</a> and the <a href="serial.html">Serial API</a>.
+  The <a href="bluetooth.html">Bluetooth API</a> is also available; we've
+  included a link to a Bluetooth sample below.
 </p>
 
 <p class="note">
-<b>API Samples: </b>
-Want to play with the code?
-Check out the
-<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/serial">serial</a>,
-<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/servo">servo</a>,
-<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/usb">usb</a>,
-and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/zephyr_hxm">zephyr_hxm Bluetooth</a> samples.
+  <b>API Samples: </b> Want to play with the code? Check out the <a
+    href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/serial">serial</a>,
+  <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/servo">servo</a>,
+  <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/usb">usb</a>,
+  and <a
+    href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/zephyr_hxm">zephyr_hxm
+  Bluetooth</a> samples.
 </p>
 
 <h2 id="usb">Accessing USB devices</h2>
 
 <p>
-You can use the USB API to send messages to connected devices using only JavaScript code. Some devices are not accessible through this API - see the <a href="#caveats">Caveats section</a> below for more details.
+  You can use the USB API to communicate with USB devices using only JavaScript

[Andy, 2013/09/05 22:51:36]

Replace the first sentence with:

"""
The <a href="usb.html">USB API</a> lets your app communicate with USB devices
using only JavaScript code.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  code. Some devices are not accessible through this API - see the <a

[Andy, 2013/09/05 22:51:36]

Replace the part after the dash with:

"""
See <a href="#caveats">Caveats</a> below for details.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+    href="#caveats">Caveats section</a> below for more details.
+</p>
+
+<p>

[Andy, 2013/09/05 22:51:36]

Delete this paragraph -- it does not fit into the introduction.  (We'll include
this information later.)

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  Each USB device is assigned with a vendor id/ product id (VID/PID) pair. You
+  can use $ref:chrome.usb.getDevices to
+  enumerate devices by its VID/PID pair. <br/>
+</p>
+
+<p>

[Andy, 2013/09/05 22:51:36]

The anchor text "here" is not helpful, especially for people who scan this
document quickly.  Replace this paragraph with:

"""
For background information about USB, see the official
<a href="http://www.usb.org/home">USB specifications</a>,
as well as this reasonable
<a href="http://www.beyondlogic.org/usbnutshell/usb1.shtml">crash course</a>.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  For official USB specifications can be found <a href="http://www.usb.org/home">
+  here</a>. <br/> <a href="http://www.beyondlogic.org/usbnutshell/usb1.shtml">Here</a>
+  is a reasonable crash course about it (you may be able to finish it within 24
+  hours).
 </p>
 
 <h3 id="manifest">Manifest requirement</h3>
 
-<p>
-The USB API requires a special permission "usb" in the manifest file:
-</p>
+<p>The USB API requires a special permission "usb" in the manifest file:</p>

[Andy, 2013/09/05 22:51:36]

'a special permission "usb"' -> 'the "usb" permission'

[Bei Zhang, 2013/09/06 07:37:15]

Done.

 
 <pre>
 "permissions": [
   "usb"
 ]
 </pre>
 
+<p>In order to prevent finger-printing, you must declare all the device type

[Andy, 2013/09/05 22:51:36]

1) What is fingerprinting?  It may be worth adding a parenthetical to explain
what this is.

2) You must declare all the specific devices you want to access, not just
"device types", right?

3) This sentence is incomplete. You can probably just delete ", other wi"

[Bei Zhang, 2013/09/06 07:37:15]

PID is the id of the device type.
Done.

+  you want to access in the manifest file, other wi. For each product id/vendor

[Andy, 2013/09/05 22:51:36]

Let's add the information about VID/PID before the sentence that starts with
"For".  I would write is as follows:

"""
Each USB device corresponds to a vendor id/product id (VID/PID) pair. You can
use $ref:chrome.usb.getDevices to enumerate devices by their VID/PID pair.
"""

Question: Is there a way to get the VID/PID pair for a device from a list
somewhere?  Otherwise there seems to be a chicken-or-egg problem here:  You have
to declare VID/PID pairs in the manifest before you can use chrome.usb, but you
need to use chrome.usb.getDevices to get the VID/PID pairs.

[Bei Zhang, 2013/09/06 07:37:15]

The VIDs are approved by http://www.usb.org/developers/vendor/. PID is rather
vendor specific. There is an official registry we are using to resolve the name
of the devices, but it is far from complete.
This pid/vid list is imported at src/third_party/usb_ids/usb.ids.

+  id pair of the device, you need to declare it in manifest file under

[Andy, 2013/09/05 22:51:36]

Replace the sentence that starts with "For" with:

"""
You must declare the VID/PID pair for each device you want to use under the
"usbDevices" permission in your app's manifest file,
as shown in the example below:
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  "usbDevices" permission:</p>
+
+<pre>
+"permissions": [
+  "usbDevices": [
+    {
+      "vendorId": 123,
+      "productId": 456
+    }
+  ]
+]
+</pre>
+
+<i>Note that only decimal numbers are allowed in JSON format. You cannot pass

[Andy, 2013/09/05 22:51:36]

1) Replace the <i> tag with <p class="note">. It's better to use fewer fonts.

2) Replace the second sentence with:

"""
You cannot use hexadecimal numbers in these fields.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+hexadecimal numbers to these fields.</i>
+
 <h3 id="finding_device">Finding a device</h3>
 
 <p>
-Every device in a USB bus is identified
-by its vendor and product IDs.
-To find a device,
-use the <code>findDevices()</code> method
-which has two parameters:
+  To find a device, use the $ref:chrome.usb.getDevices

[Andy, 2013/09/05 22:51:36]

"Find" implies that you can search for and discover devices, which I don't think
you can do.  I would replace "To find a device" with:

"""
To determine whether one or more specific devices are connected to a user's
system
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  method which has two parameters:

[Andy, 2013/09/05 22:51:36]

Delete "which has two parameters:".

[Bei Zhang, 2013/09/06 07:37:15]

Done.

 </p>
 
 <pre>
-chrome.usb.findDevices(FindDeviceOptions, callback)
+chrome.usb.getDevices(EnumerateDevicesOptions options, GetDevicesCallback callback);
 </pre>
 
-<br>
+<br/>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Parameter (type) </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Parameter (type)</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
-    <td>FindDeviceOptions (object)</td>
-    <td>An object specifying both a <code>vendorId</code> (long) and
-      <code>productId</code> (long) used to find the correct type of device on
-      the bus. Your manifest must declare the<code>usbDevices</code> permission
-      section listing all the <code>vendorId</code> and
-      <code>deviceId</code> pairs your app wants to access.
+    <td>EnumerateDevicesOptions (object)</td>
+    <td>An object specifying both a <code>vendorId</code> (long) and <code>productId</code>

[Andy, 2013/09/05 22:51:36]

Can you only specify one object (device) at a time?  The fact that you get an
array of objects in the callback would imply that you can specify multiple
devices as input for getDevices(), no?

[Bei Zhang, 2013/09/06 07:37:15]

As explained above, VID/PID refers to a type of devices, not a specific one.

+      (long) used to find the correct type of device on the bus. Your manifest
+      must declare the<code>usbDevices</code> permission section listing all the
+      <code>vendorId</code> and <code>deviceId</code> pairs your app wants to
+      access.
     </td>
   </tr>
   <tr>
     <td>callback (function)</td>
-    <td>Called when the device scan is finished.
-      The callback will be executed with one parameter, an array of device objects
-      with three properties: <code>handle</code>,
-      <code>vendorId</code>,
-      <code>productId</code>. If the optional permissions for this USB device
-      were not declared in the extension manifest or the user did not consent
-      to the permissions requested, the parameter will be <code>null</code>.
-      If no devices could be found, the array will be empty.</td>
+    <td>Called when the device scan is finished. The callback will be

[Andy, 2013/09/05 22:51:36]

I would replace "scan" with "search" or maybe "identification".  To me, scan
implies discovering devices, which I don't think you can do.

[Bei Zhang, 2013/09/06 07:37:15]

Done. I understand why it was called "scan". It's actually enumerate on each bus
and slot on the buses.

+      executed with one parameter, an array of <code>Device</code> objects with
+      three properties: <code>device</code>, <code>vendorId</code>, <code>productId</code>.

[Andy, 2013/09/05 22:51:36]

How is the "device" property used?

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+      If no devices could be found, the array will be empty.

[Andy, 2013/09/05 22:51:36]

"could be found" -> "are found"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+    </td>
   </tr>
 </table>
 
-<p>
-Example:
-</p>
+<p>Example:</p>
 
 <pre>
-var onDeviceFound = function(devices) {
-  _this.devices=devices;
+function onDeviceFound(devices) {
+  this.devices=devices;
   if (devices) {
-    if (devices.length &gt; 0) {
+    if (devices.length > 0) {
       console.log("Device(s) found: "+devices.length);
     } else {
       console.log("Device could not be found");
     }
   } else {
     console.log("Did not request correct permissions");
   }
 };
 
-chrome.usb.findDevices({"vendorId": vendorId, "productId": productId}, onDeviceFound);
+chrome.usb.getDevices({"vendorId": vendorId, "productId": productId}, onDeviceFound);
 </pre>
 
+<h3 id="usb_open">Opening the device</h3>

[Andy, 2013/09/05 22:51:36]

"the" -> "a"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+Once the <code>Device</code> objects are returned you can open the device using

[Andy, 2013/09/05 22:51:36]

1) Wrap your text in a <p> tag.

2) Add a comma after "returned".

3) "the device" -> "a device"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+$ref:chrome.usb.openDevice to obtain a connection handle. You can only
+communicate with the device using this handle.

[Andy, 2013/09/05 22:51:36]

"the device" -> "devices"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+
+Not every device can be opened successfully. Devices that are claimed by the OS cannot be opened in Chrome in general.

[Bei Zhang, 2013/09/03 21:25:55]

Zel@, This is the key part to explain interfaceId.

[Andy, 2013/09/05 22:51:36]

Start a new paragraph with "Not".  I would start this paragraph as follows:

"""
<p class="note">
Not every device can be opened successfully.
In general, devices that are claimed by the OS cannot be opened
in Chrome.
On Linux (other than Chrome OS), once one device interface
is claimed by the OS, the whole device is locked down,
even if other interfaces of the device can be used.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+On Linux other than Chrome OS, once an interface of a device is claimed by the OS, the whole device is locked down, even
+if the other interfaces of the device can be used. On Chrome OS, it is possible to request access to these devices using

[Andy, 2013/09/05 22:51:36]

It's not clear what "these devices" refers to.  Maybe use: "such devices".

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+$ref:chrome.usb.requestAccess method.
+
+To simplify the opending process, you can call $ref:chrome.usb.findDevices

[Andy, 2013/09/05 22:51:36]

1) I would start a new paragraph with "To simplify...".

2) "opending" -> "opening"

3) "call" -> "use the"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+method which enumerates, requests access and opens the devices in one call.

[Andy, 2013/09/05 22:51:36]

1) Add a comma after "method"

2) Add a comma after "access"

3) It would be helpful to provide a sample call for openDevice(), and a table
that describes the parameters, like for other methods in this article.

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+
 <h3 id="usb_transfers">USB transfers and receiving data from a device</h3>
 
 <p>
-USB protocol defines four types of transfers:
-<a href="#control_transfers">control</a>, <a href="#bulk_transfers">bulk</a>, <a href="#isochronous_transfers">isochronous</a> and <a href="#interrupt_transfers">interrupt</a>.
-Theoretically they can occur in both directions:<br>
-device-to-host (inbound) and host-to-device (outbound).
+  USB protocol defines four types of transfers: <a href="#control_transfers">control</a>,

[Andy, 2013/09/05 22:51:36]

"USB" -> "The USB"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  <a href="#bulk_transfers">bulk</a>, <a href="#isochronous_transfers">isochronous</a>
+  and <a href="#interrupt_transfers">interrupt</a>. Theoretically they can occur

[Andy, 2013/09/05 22:51:36]

Delete the sentence that starts with "Theorectically...", and add the following
sentence:

"""
These transfers are described below.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  in both directions:<br> device-to-host (inbound) and host-to-device
+  (outbound).
 </p>
 
 <p>
 However, due to the nature of the USB protocol, both inbound and outbound messages must be initiated by the host (your computer). For inbound (device-to-host) messages, the host, your JavaScript code, sends a message flagged as "inbound" to the device. The exact contents of the message depends on the device, but usually will have some identification of what you are requesting from it. The device then responds with the requested data. The device's response is handled by Chrome and delivered asynchronously to the callback you specified in the transfer method.

[Andy, 2013/09/05 22:51:36]

1) Start this paragraph with:

"""
Transfers can occur in both directions: device-to-host (inbound), and
host-to-device (outbound). Due to the nature...
"""

2) "your computer" -> "the user's computer"

3) Replace the following commas with parentheses: ", your JavaScript code," ->
"(your JavaScript Code)"

4) "exact contents" -> "exact content"

5) "you specified" -> "you specify"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

 An outbound (host-to-device) message is similar, but the response doesn't contain data returned from the device.</p>
 
 <p>For each message from the device,
 the specified callback will receive 
 an event object with the following properties:
 </p>
 
 <br>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Property </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Property</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
     <td>resultCode (integer)</td>
-    <td>0 is success; other values indicate failure. An error string can be read from
-      <code>chrome.extension.lastError</code> when a failure is indicated.</td>
+    <td>0 is success; other values indicate failure. An error string can be
+      read from <code>chrome.extension.lastError</code> when a failure is
+      indicated.
+    </td>
   </tr>
   <tr>
     <td>data (arraybuffer)</td>
-    <td>Contains the data sent by the device if transfer was inbound.
-    </td>
+    <td>Contains the data sent by the device if transfer was inbound.</td>

[Andy, 2013/09/05 22:51:36]

"transfer" -> "the transfer"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

   </tr>
 </table>
 
-<p>
-Example:
-</p>
+<p>Example:</p>
 
 <pre>
 var onTransferCallback = function(event) {
    if (event &amp;&amp; event.resultCode === 0 &amp;&amp; event.data) {
      console.log("got "+event.data.byteLength+" bytes");
    }
 };
 
 chrome.usb.bulkTransfer(device, transferInfo, onTransferCallback);

[Andy, 2013/09/05 22:51:36]

"device" -> "connectionHandle" ?

[Bei Zhang, 2013/09/06 07:37:15]

Done.

 </pre>
 
 <h3 id="control_transfers">CONTROL transfers</h3>
 
-<p>
-Control transfers are generally used to send or receive configuration
-or command parameters to a USB device.
-The method is simple and receives three parameters:
-</p>
+<p>Control transfers are generally used to send or receive configuration or
+  command parameters to a USB device. It always sends to endpoint 0 and no

[Andy, 2013/09/05 22:51:36]

1) It's not clear what "It" refers to. Maybe: "The controlTransfer method
always..."?

2) Add a comma after "0".

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  claimInterface is required. The method is simple and receives three
+  parameters:</p>
 
 <pre>
-chrome.usb.controlTransfer(deviceObj, transferInfo, transferCallback)
+chrome.usb.controlTransfer(connectionHandle, transferInfo, transferCallback)
 </pre>
 
 <br>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Parameter (types)</th>
-    <th scope="col"> Description </th>
+    <th scope="col">Parameter (types)</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
-    <td>deviceObj</td>
-    <td>Object sent in <code>findDevice()</code> callback.</td>
+    <td>connectionHandle</td>
+    <td>Object sent in $ref:chrome.usb.openDevice callback.

[Andy, 2013/09/05 22:51:36]

"sent" -> "received" ?

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+    </td>
   </tr>
   <tr>
     <td>transferInfo</td>
-    <td>Parameter object with values from the table below.
-      Check your USB device protocol specification for specifics.</td>
+    <td>Parameter object with values from the table below. Check your USB
+      device protocol specification for specifics.

[Andy, 2013/09/05 22:51:36]

"specifics" -> "details"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+    </td>
   </tr>
   <tr>
     <td>transferCallback()</td>
-    <td>Invoked when the transfer has completed.
+    <td>Invoked when the transfer has completed.</td>
+  </tr>
+</table>
+
+<p>
+  Values for
+  <code>transferInfo</code>
+  object:
+</p>
+
+<table class="simple">
+  <tr>
+    <th scope="col">Value</th>
+    <th scope="col">Description</th>
+  </tr>
+  <tr>
+    <td>requestType (string)</td>
+    <td>"vendor", "standard", "class" or "reserved".</td>
+  </tr>
+  <tr>
+    <td>recipient (string)</td>
+    <td>"device", "interface", "endpoint" or "other".</td>
+  </tr>
+  <tr>
+    <td>direction (string)</td>
+    <td>"in" or "out". "in" direction is used to notify the device that it

[Andy, 2013/09/05 22:51:36]

Start the second sentence with:

"""
The "in" direction is used
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+      should send information to the host. All communication in a USB bus is

[Andy, 2013/09/05 22:51:36]

"in" -> "on"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+      host-initiated, so use an 'in' transfer to allow a device to send
+      information back.
+    </td>
+  </tr>
+  <tr>
+    <td>request (integer)</td>
+    <td>Defined by your device's protocol.</td>
+  </tr>
+  <tr>
+    <td>value (integer)</td>
+    <td>Defined by your device's protocol.</td>
+  </tr>
+  <tr>
+    <td>index (integer)</td>
+    <td>Defined by your device's protocol.</td>
+  </tr>
+  <tr>
+    <td>length (integer)</td>
+    <td>Only used when direction is "in". Notifies the device that this is
+      the amount of data the host is expecting in response.
+    </td>
+  </tr>
+  <tr>
+    <td>data (arraybuffer)</td>
+    <td>Defined by your device's protocol, required when direction is
+      "out".
     </td>
   </tr>
 </table>
 
-<p>
-Values for <code>transferInfo</code> object:
-</p>
-
-<table class="simple">
-  <tr>
-    <th scope="col"> Value </th>
-    <th scope="col"> Description </th>
-  </tr>
-  <tr>
-    <td>requestType&nbsp;(string)</td>
-    <td>"vendor", "standard", "class" or "reserved".</td>
-  </tr>
-  <tr>
-    <td>recipient&nbsp;(string)</td>
-    <td>"device", "interface", "endpoint" or "other".</td>
-  </tr>
-  <tr>
-    <td>direction&nbsp;(string)</td>
-    <td>"in" or "out".
-      "in" direction is used to notify the device
-      that it should send information to the host.
-      All communication in a USB bus is host-initiated,
-      so use an 'in' transfer to allow a device
-      to send information back.</td>
-  </tr>
-  <tr>
-    <td>request&nbsp;(integer)</td>
-    <td>Defined by your device's protocol.</td>
-  </tr>
-  <tr>
-    <td>value&nbsp;(integer)</td>
-    <td>Defined by your device's protocol.</td>
-  </tr>
-  <tr>
-    <td>index&nbsp;(integer)</td>
-    <td>Defined by your device's protocol.</td>
-  </tr>
-  <tr>
-    <td>length&nbsp;(integer)</td>
-    <td>Only used when direction is "in".
-      Notifies the device that this is the amount
-      of data the host is expecting in response.</td>
-  </tr>
-  <tr>
-    <td>data&nbsp;(arraybuffer)</td>
-    <td>Defined by your device's protocol,
-      required when direction is "out".</td>
-  </tr>
-</table>
-
-<p>
-Example:
-</p>
+<p>Example:</p>
 
 <pre>
 var transferInfo = {
-   "requestType": "vendor",
+  "requestType": "vendor",
    "recipient": "device",
-   "direction": "out",
-   "request":  0x31,
-   "value": 120,
-   "index": 0,
-   "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
- };
-chrome.usb.controlTransfer(deviceObj, transferInfo, optionalCallback);
+  "direction": "out",
+  "request":  0x31,
+  "value": 120,
+  "index": 0,
+  "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer  // Note that the ArrayBuffer, not the TypedArray it self is used.

[Andy, 2013/09/05 22:51:36]

1) "it self" -> "itself"

2) I don't understand this comment. Can you please clarify?

[Bei Zhang, 2013/09/06 07:37:15]

Means you cannot pass `new Uint8Array(...)` to it. Instead, you need to pass a
`new Uint8Array(...).buffer` to it.

+};
+chrome.usb.controlTransfer(connectionHandle, transferInfo, optionalCallback);
 </pre>
 
 <h3 id="isochronous_transfers">ISOCHRONOUS transfers</h3>
 
-<p>
-Isochronous transfers is the most complex type of USB transfers. They are commonly used for streams of data, like video and sound. To initiate an isochronous transfer (either inbound or outbound), you must use:
-</p>
+<p>Isochronous transfers is the most complex type of USB transfers. They are

[Andy, 2013/09/05 22:51:36]

"is" -> "are"

[Bei Zhang, 2013/09/06 07:37:15]

Done. Not sure about this though.

+  commonly used for streams of data, like video and sound. To initiate an
+  isochronous transfer (either inbound or outbound), you must use:</p>

[Andy, 2013/09/05 22:51:36]

"you must use" -> "you must use the isochronousTransfer() method:"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

 
 <pre>
-chrome.usb.isochronousTransfer(deviceObj, isochronousTransferInfo, transferCallback)
+chrome.usb.isochronousTransfer(connectionHandle, isochronousTransferInfo, transferCallback)
 </pre>
 
 <br>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Parameter </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Parameter</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
-    <td>deviceObj</td>
-    <td>Object sent on <code>findDevice()</code> callback.</td>
+    <td>connectionHandle</td>
+    <td>Object sent in $ref:chrome.usb.openDevice callback.

[Andy, 2013/09/05 22:51:36]

"sent" -> "received" ?

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+    </td>
   </tr>
   <tr>
     <td>isochronousTransferInfo</td>
     <td>Parameter object with the values in the table below.</td>
   </tr>
   <tr>
     <td>transferCallback()</td>
-    <td>Invoked when the transfer has completed.
-    </td>
+    <td>Invoked when the transfer has completed.</td>
   </tr>
 </table>
 
 <p>
-Values for <code>isochronousTransferInfo</code> object:
+  Values for
+  <code>isochronousTransferInfo</code>
+  object:
 </p>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Value </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Value</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
-    <td>transferInfo&nbsp;(object)</td>
-    <td>An object with the following attributes:<br>
-      <b>direction (string): </b>"in" or "out".<br>
-      <b>endpoint (integer): </b>defined by your device. Usually can be found by looking at an USB instrospection tool, like <code>lsusb -v</code><br>
-      <b>length (integer): </b>only used when direction is "in".
-      Notifies the device that this is the amount
-      of data the host is expecting in response. Should be AT LEAST <code>packets * packetLength</code><br>
-      <b>data (arraybuffer): </b>defined by your device's protocol;
-      only used when direction is "out".
+    <td>transferInfo (object)</td>
+    <td>An object with the following attributes:<br> <b>direction
+      (string): </b>"in" or "out".<br> <b>endpoint (integer): </b>defined by
+      your device. Usually can be found by looking at an USB instrospection
+      tool, like <code>lsusb -v</code><br> <b>length (integer): </b>only
+      used when direction is "in". Notifies the device that this is the amount
+      of data the host is expecting in response. Should be AT LEAST <code>packets
+        * packetLength</code><br> <b>data (arraybuffer): </b>defined by your
+      device's protocol; only used when direction is "out".
     </td>
   </tr>
   <tr>
-    <td>packets&nbsp;(integer)</td>
+    <td>packets (integer)</td>
     <td>Total number of packets expected in this transfer.</td>
   </tr>
   <tr>
-    <td>packetLength&nbsp;(integer)</td>
+    <td>packetLength (integer)</td>
     <td>Expected length of each packet in this transfer.</td>
   </tr>
 </table>
 
-<p>
-Example:
-</p>
+<p>Example:</p>
 
 <pre>
 var transferInfo = {
    "direction": "in",
    "endpoint": 1,
    "length": 2560
  };
 var isoTransferInfo = {
   "transferInfo": transferInfo,
   "packets": 20,
   "packetLength": 128
 };
-chrome.usb.isochronousTransfer(deviceObj, isoTransferInfo, optionalCallback);
+chrome.usb.isochronousTransfer(connectionHandle, isoTransferInfo, optionalCallback);
 </pre>
 
 <p>
-  <b>Notes:</b> One isochronous transfer will contain <code>isoTransferInfo.packets</code> packets of <code>isoTransferInfo.packetLength</code> bytes. If it is an inbound transfer (your code requested data from the device), the <code>data</code> field in the onUsbEvent will be an ArrayBuffer of size <code>transferInfo.length</code>. It is your duty to walk through this ArrayBuffer and extract the different packets, each starting at a multiple of <code>isoTransferInfo.packetLength</code> bytes. If you are expecting a stream of data from the device, remember that you will have to send one "inbound" transfer for each transfer you expect back. USB devices don't send transfers to the bus unless the host explicitly requests them through "inbound" transfers.
+  <b>Notes:</b> One isochronous transfer will contain
+  <code>isoTransferInfo.packets</code>
+  packets of
+  <code>isoTransferInfo.packetLength</code>
+  bytes. If it is an inbound transfer (your code requested data from the
+  device), the
+  <code>data</code>
+  field in the onUsbEvent will be an ArrayBuffer of size
+  <code>transferInfo.length</code>
+  . It is your duty to walk through this ArrayBuffer and extract the different
+  packets, each starting at a multiple of
+  <code>isoTransferInfo.packetLength</code>
+  bytes. If you are expecting a stream of data from the device, remember that
+  you will have to send one "inbound" transfer for each transfer you expect
+  back. USB devices don't send transfers to the bus unless the host explicitly

[Andy, 2013/09/05 22:51:36]

"the bus" -> "the USB bus"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  requests them through "inbound" transfers.
 </p>
 
 <h3 id="bulk_transfers">BULK transfers</h3>
 
-<p>
-Bulk transfer is an USB transfer type commonly used
-to transfer a large amount of data in a reliable way.
-The method has three parameters:
-</p>
+<p>Bulk transfer is an USB transfer type commonly used to transfer a large

[Andy, 2013/09/05 22:51:36]

Start this paragraph with:

"""
Bulk transfers are commonly used to...
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  amount of data in a reliable way. The method has three parameters:</p>

[Andy, 2013/09/05 22:51:36]

"The method" -> "The bulkTransfer() method"

When you say "the method", it has to be clear which method you're talking about.

[Bei Zhang, 2013/09/06 07:37:15]

Done.

 
 <pre>
-chrome.usb.bulkTransfer(deviceObj, transferInfo, transferCallback)
+chrome.usb.bulkTransfer(connectionHandle, transferInfo, transferCallback)
 </pre>
 
 <br>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Parameter </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Parameter</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
-    <td>deviceObj</td>
-    <td>Object sent on <code>findDevice()</code> callback.</td>
+    <td>connectionHandle</td>
+    <td>Object sent in $ref:chrome.usb.openDevice callback.

[Andy, 2013/09/05 22:51:36]

"sent" -> "received" ?

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+    </td>
   </tr>
   <tr>
     <td>transferInfo</td>
     <td>Parameter object with the values in the table below.</td>
   </tr>
   <tr>
     <td>transferCallback</td>
-    <td>Invoked when the transfer has completed.
-    </td>
+    <td>Invoked when the transfer has completed.</td>
   </tr>
 </table>
 
 <p>
-Values for <code>transferInfo</code> object:
+  Values for
+  <code>transferInfo</code>
+  object:
 </p>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Value </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Value</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
     <td>direction (string)</td>
     <td>"in" or "out".</td>
   </tr>
   <tr>
     <td>endpoint (integer)</td>
     <td>Defined by your device's protocol.</td>
   </tr>
   <tr>
     <td>length (integer)</td>
-    <td>Only used when direction is "in".
-      Notifies the device that this is the amount
-      of data the host is expecting in response.</td>
+    <td>Only used when direction is "in". Notifies the device that this is
+      the amount of data the host is expecting in response.
+    </td>
   </tr>
   <tr>
     <td>data (ArrayBuffer)</td>
-    <td>Defined by your device's protocol;
-      only used when direction is "out".</td>
+    <td>Defined by your device's protocol; only used when direction is
+      "out".
+    </td>
   </tr>
 </table>
 
-<p>
-Example:
-</p>
+<p>Example:</p>
 
 <pre>
 var transferInfo = {
-   "direction": "out",
-   "endpoint": 1,
-   "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
- };
+  "direction": "out",
+  "endpoint": 1,
+  "data": new Uint8Array([4, 8, 15, 16, 23, 42]).buffer
+};
 </pre>
 
 <h3 id="interrupt_transfers">INTERRUPT transfers</h3>
 
-<p>
-Interrupt transfers are used to send important notifications.
-Since all USB communication is initiated by the host,
-host code usually polls the device periodically,
-sending interrupt IN transfers that will make the device send data back
-if there is anything in the interrupt queue.
-The method has three parameters:
-</p>
+<p>Interrupt transfers are used to send important notifications. Since all

[Andy, 2013/09/05 22:51:36]

An example of an "important notification" would be helpful.

+  USB communication is initiated by the host, host code usually polls the device
+  periodically, sending interrupt IN transfers that will make the device send
+  data back if there is anything in the interrupt queue. The method has three

[Andy, 2013/09/05 22:51:36]

"The method" -> "The interruptTransfer() method"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  parameters:</p>
 
 <pre>
-chrome.usb.interruptTransfer(deviceObj, transferInfo, transferCallback)
+chrome.usb.interruptTransfer(connectionHandle, transferInfo, transferCallback)
 </pre>
 
 <br>
 
 <table class="simple">
   <tr>
-    <th scope="col"> Parameter </th>
-    <th scope="col"> Description </th>
+    <th scope="col">Parameter</th>
+    <th scope="col">Description</th>
   </tr>
   <tr>
-    <td>deviceObj</td>
-    <td>Object sent on <code>findDevice()</code> callback.</td>
+    <td>connectionHandle</td>
+    <td>Object sent in $ref:chrome.usb.openDevice callback.
+    </td>
   </tr>
   <tr>
     <td>transferInfo</td>
     <td>Parameter object with the values in the table below.</td>
   </tr>
   <tr>
     <td>transferCallback</td>
-    <td>Invoked when the transfer has completed.
-      Notice that this callback doesn't contain the device's response.
-      It's just to notify your code that the asynchronous transfer request
-      has been processed and you can go ahead.
-      The device's response, if any, will always be sent through
-      the <code>onEvent()</code> callback set on <code>findDevice()</code>.
+    <td>Invoked when the transfer has completed. Notice that this callback
+      doesn't contain the device's response. It's just to notify your code that

[Andy, 2013/09/05 22:51:36]

"It's just" -> "The purpose of the callback is simply"

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+      the asynchronous transfer request has been processed and you can go ahead.

[Andy, 2013/09/05 22:51:36]

Go ahead with what?  Maybe end the sentence after "processed".

[Bei Zhang, 2013/09/06 07:37:15]

Done.

     </td>
   </tr>
 </table>
 
 <p>
-Values for <code>transferInfo</code> object:
+  Values for
+  <code>transferInfo</code>
+  object:
 </p>
 
 <table class="simple">
-  <tr>
-    <th scope="col"> Value </th>
-    <th scope="col"> Description </th>
-  </tr>
-  <tr>
-    <td>direction (string)</td>
-    <td>"in" or "out".</td>
-  </tr>
-  <tr>
-    <td>endpoint (integer)</td>
-    <td>Defined by your device's protocol.</td>
-  </tr>
-  <tr>
-    <td>length (integer)</td>
-    <td>Only used when direction is "in".
-      Notifies the device that this is the amount
-      of data the host is expecting in response.</td>
-  </tr>
-  <tr>
-    <td>data (ArrayBuffer)</td>
-    <td>Defined by your device's protocol;
-      only used when direction is "out".</td>
-  </tr>
+<tr>
+  <th scope="col">Value</th>
+  <th scope="col">Description</th>
+</tr>
+<tr>
+  <td>direction (string)</td>
+  <td>"in" or "out".</td>
+</tr>
+<tr>
+  <td>endpoint (integer)</td>
+  <td>Defined by your device's protocol.</td>
+</tr>
+<tr>
+  <td>length (integer)</td>
+  <td>Only used when direction is "in". Notifies the device that this is
+    the amount of data the host is expecting in response.
+  </td>
+</tr>
+<tr>
+  <td>data (ArrayBuffer)</td>
+  <td>Defined by your device's protocol; only used when direction is
+    "out".
+  </td>
+</tr>
+</table>
 
-<p>
-Example:
-</p>
+<p>Example:</p>
 
 <pre>
 var transferInfo = {
-   "direction": "in", 
-   "endpoint": 1,
-   "length": 2
- };
-chrome.usb.interruptTransfer(deviceObj, transferInfo, optionalCallback);
+  "direction": "in",
+  "endpoint": 1,
+  "length": 2
+};
+chrome.usb.interruptTransfer(connectionHandle, transferInfo, optionalCallback);
 </pre>
 
 <h3 id="caveats">Caveats</h3>
 
 <p>
-On most Linux systems, USB devices are mapped with read-only permissions by default. To access it through this API, your user will need to have write access too. A simple solution is to set a udev rule. Create a file <code>/etc/udev/rules.d/50-yourdevicename.rules</code>
-with the following content:
+  On most Linux systems, USB devices are mapped with read-only permissions by
+  default. To access it through this API, your user will need to have write

[Andy, 2013/09/05 22:51:36]

What does "it" refer to?  Try: "To access devices through this API..."

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  access too. A simple solution is to set a udev rule. Create a file

[Andy, 2013/09/05 22:51:36]

Do users need to set this rule?  Or can an app do that?  If users need to set
the rule, we should tell developers that they may want to provide instructions
in their app telling end-users what they need to do.

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  <code>/etc/udev/rules.d/50-yourdevicename.rules</code>
+  with the following content:
 </p>
 
 <pre>
 SUBSYSTEM=="usb", ATTR{idVendor}=="[yourdevicevendor]", MODE="0664", GROUP="plugdev"
 </pre>
 
 <p>
-  Then, just restart the udev daemon: <code>service udev restart</code>. You can check if the permissions are correctly set by:
-  <ul>
-    <li>Find the bus and device numbers in <code>lsusb</code></li>
-    <li><code>ls -al /dev/bus/usb/[bus]/[device]</code>. This file should be owned by group "plugdev" and have group write permissions.</li>
-  </ul>
+  Then, just restart the udev daemon: <code>service udev restart</code>. You can

[Andy, 2013/09/05 22:51:36]

Replace the last sentence with:

"""
You can check if device permissions are set correctly by following these steps:
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  check if the permissions are correctly set by:
 </p>
 
-<p>
-  Not all devices can be accessed through this API. In general, devices are not accessible either because the Operating System's kernel or a native driver holds them off from user space code. Some examples are devices with HID profiles on OSX systems and USB pen drives.
-</p>
+<ul>
+  <li>Find the bus and device numbers in <code>lsusb</code></li>

[Andy, 2013/09/05 22:51:36]

Replace the first step with:

"""
Run <code>lsusb</code> to find the bus and device numbers.
"""

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  <li><code>ls -al /dev/bus/usb/[bus]/[device]</code>. This file should be owned

[Andy, 2013/09/05 22:51:36]

Start the second step with:

"""
Run <code>ls...
"""

When you have a list of items, it's much easier to read/process the list if the
items all use a parallel structure.

[Bei Zhang, 2013/09/06 07:37:15]

Done.

+  by group "plugdev" and have group write permissions.
+  </li>
+</ul>
+
+<p>On Chrome OS, simply call $ref:chrome.usb.requestAccess.</p>
+
+<p>Not all devices can be accessed through this API. In general, devices
+  are not accessible either because the Operating System's kernel or a native
+  driver holds them off from user space code. Some examples are devices with
+  HID profiles on OSX systems and USB pen drives.</p>
 
 <h2 id="serial">Accessing serial devices</h2>
 
 <p>
 You can use the serial API to read
 and write from a serial device.
 </p>
 
 <h3 id="requirement">Manifest requirement</h3>
 
@@ skipping 143 matching lines @@
 
 <p>
 You can flush your serial port buffer by issuing the flush command:
 </p>
 
 <pre>
   chrome.serial.flush(connectionId, onFlush);
 </pre>
 
 <p class="backtotop"><a href="#top">Back to top</a></p>