Bluetooth: write documentation

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

+<h1>Bluetooth</h1>

[mkearney1, 2014/03/10 21:13:37]

Throughout this doc you say 'event does not begin discover of devices'. Wherever
you say this, add (see Discovering nearby devices) -- with proper a href.

[keybuk, 2014/03/11 17:03:39]

Done.

+
+<p>
+  This document describes how to use the <a href="bluetooth.html">Bluetooth
+  API</a> to communicate with Bluetooth and Bluetooth Low Energy devices.
+</p>
+
+<p>
+  For background information about Bluetooth, see the official
+  <a href="http://www.bluetooth.org">Bluetooth specifications</a>.
+</p>
+
+<h2 id="manifest">Manifest requirements</h2>
+
+<p>
+  For Chrome Apps that use Bluetooth, add the
+  <a href="manifest/bluetooth.html">bluetooth</a> entry to the manifest
+  and specify, if appropriate, the UUIDs of profiles you wish to implement.
+  For example:
+</p>
+
+<pre data-filename="manifest.json">
+"bluetooth": {
+  "profiles": [ "1105", "1106" ]
+}
+</pre>
+
+<p>
+  To only access adapter state, discover nearby devices and obtain basic

[mkearney1, 2014/03/10 21:13:37]

Small nit-- add comma after 'discover nearby devices'.

[keybuk, 2014/03/11 17:03:39]

Done.

[keybuk, 2014/03/11 17:03:39]

Done.

+  information about devices, omit the <code>profiles</code> list.
+</p>
+
+<h2 id="adapter_state">Obtaining adapter state</h2>
+
+<p>
+  To obtain the state of the Bluetooth adapter, use the
+  <code>chrome.bluetooth.getAdapterState</code> method:
+</p>
+
+<pre>
+chrome.bluetooth.getAdapterState(function(adapter) {
+  console.log("Adapter " + adapter.address + ": " + adapter.name);
+});
+</pre>
+
+<p>
+  The <code>chrome.bluetooth.onAdapterStateChanged</code> event is sent
+  whenever this state changes. This can be used, for example, to determine when
+  the adapter radio is powered on or off.
+</p>
+
+<pre>
+var powered = false;
+chrome.bluetooth.getAdapterState(function(adapter) {
+  powered = adapter.powered;
+});
+
+chrome.bluetooth.onAdapterStateChanged.addListener(
+  function(adapter) {
+    if (adapter.powered != powered) {
+      powered = adapter.powered;
+      if (powered) {
+        console.log("Adapter radio is on");
+      } else {
+        console.log("Adapter radio is off");
+      }
+    }
+  });
+</pre>
+
+<h2 id="listing_devices">Listing known devices</h2>
+
+<p>
+  To get a list of the devices known to the Bluetooth adapter, use the
+  <code>chrome.bluetooth.getDevices</code> method:
+</p>
+
+<pre>
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    console.log(devices[i].address);
+  }
+});
+</pre>
+
+<p>
+  All devices are returned, including paired devices and devices recently
+  discovered. It will not begin discovery of new devices.
+</p>
+
+<h2 id="device_notifications">Receiving device notifications</h2>
+
+<p>
+  Instead of repeatedly calling <code>chrome.bluetooth.getDevices</code>, you
+  can use the <code>chrome.bluetooth.onDeviceAdded</code>,
+  <code>chrome.bluetooth.onDeviceChanged</code> and
+  <code>chrome.bluetooth.onDeviceRemoved</code> events to receive notifications.
+</p>
+
+<p>
+  The <code>chrome.bluetooth.onDeviceAdded</code> event is sent whenever a
+  device is discovered by the adapter or makes a connection to the adapter:
+</p>
+
+<pre>
+chrome.bluetooth.onDeviceAdded.addListener(function(device) {
+  console.log(device.address);
+});
+</pre>
+
+<p>
+  Adding a listener for this event does not begin discovery of devices.  
+</p>
+
+<p>
+  Changes to devices, including previously discovered devices becoming paired,
+  are notified by the <code>chrome.bluetooth.onDeviceChanged</code> event:
+</p>
+
+<pre>
+chrome.bluetooth.onDeviceChanged.addListener(function(device) {
+  console.log(device.address);
+});
+</pre>
+
+<p>
+  Finally the <code>chrome.bluetooth.onDeviceRemoved</code> event is sent
+  whenever a paired device is removed from the system, or a discovered device
+  has not been seen recently:
+</p>
+
+<pre>
+chrome.bluetooth.onDeviceRemoved.addListener(function(device) {
+  console.log(device.address);
+});
+</pre>
+
+<h2 id="discovery">Discovering nearby devices</h2>
+
+<p>
+  To begin discovery of nearby devices use the

[mkearney1, 2014/03/10 21:13:37]

Small nit-- add comma between nearby devices and use 'nearby devices, use...'

[keybuk, 2014/03/11 17:03:39]

Done.

+  <code>chrome.bluetooth.startDiscovery</code> method, discovery can be
+  resource intensive so you should call

[mkearney1, 2014/03/10 21:13:37]

'discovery can be resource intensive...' should be its own sentence:

method. Discovery can be resource intensive...

[keybuk, 2014/03/11 17:03:39]

Done.

+  <code>chrome.bluetooth.stopDiscovery</code> when done.
+</p>
+
+<p>
+  You should call <code>chrome.bletooth.startDiscovery</code> whenever your
+  app needs to discover nearby devices. Do not check the
+  <code>discovering</code> property of <code>AdapterState</code>. The call
+  to start discovery will succeed even if another app is discovering nearby
+  devices, and will ensure the adapter continues to perform discovery after
+  that other app has stopped.
+</p>
+
+<p>
+  Information about each newly discovered device is received using the
+  <code>chrome.bluetooth.onDeviceAdded</code> event. For devices that have
+  already been discovered recently, or have been previously paired with or
+  connected to, the event will not be sent, instead you should call

[mkearney1, 2014/03/10 21:13:37]

'instead you should call...' should be its own sentence: sent. Instead you
should call...'

[keybuk, 2014/03/11 17:03:39]

Done.

+  <code>chrome.bluetooth.getDevices</code> to obtain the current information,
+  and use the <code>chrome.bluetooth.onDeviceChanged</code> event to be notified of changes to that information as a result of discovery.
+</p>
+
+<p>
+  Example:
+</p>
+
+<pre>
+var device_names = {};
+var updateDeviceName = function(device) {
+  device_names[device.address] = device.name;
+};
+var removeDeviceName = function(device) {
+  delete device_names[device.address];
+}
+
+// Add listeners to receive newly found devices and updates
+// to the previously known devices.
+chrome.bluetooth.onDeviceAdded.addListener(updateDeviceName);
+chrome.bluetooth.onDeviceChanged.addListener(updateDeviceName);
+chrome.bluetooth.onDeviceRemoved.addListener(removeDeviceName);
+
+// With the listeners in place, get the list of devices found in
+// previous discovery sessions, or any currently active ones,
+// along with paired devices.
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    updateDeviceName(devices[i]);
+  }
+});
+
+// Now begin the discovery process.
+chrome.bluetooth.startDiscovery(function() {
+  // Stop discovery after 30 seconds.
+  setTimeout(function() {
+    chrome.bluetooth.stopDiscovery(function() {});
+  }, 30000);
+});
+</pre>
+
+<p>
+  If the user turns off the Bluetooth radio, all discovery sessions will be
+  ended and not resumed automatically when the radio is switched on. If this
+  matters to your app you should watch the

[mkearney1, 2014/03/10 21:13:37]

Add comma between 'app' and 'you': 'matters to your app, you should...'

[keybuk, 2014/03/11 17:03:39]

Done.

+  <code>chrome.bluetooth.onAdapterStateChanged</code> event. If the
+  <code>discovering</code> property changes to <code>false</code> then your app

[mkearney1, 2014/03/10 21:13:37]

Add comma between 'false' and 'then': '<code>false</code>, then your app...'

[keybuk, 2014/03/11 17:03:39]

Done.

+  will need to call <code>chrome.bluetooth.startDiscovery</code> again to
+  resume. Be cautious of the resource intensive nature of discovery.

[mkearney1, 2014/03/10 21:13:37]

Is this caution important enough to put in a warning paragraph?

[keybuk, 2014/03/11 17:03:39]

No, it's more just a continual reminder to enforce good practice of always
planning to stop the discovery

+</p>
+
+<h2 id="identifying_devices">Identifying devices</h2>
+
+<p>
+  A number of different options are provided for identifying devices returned
+  by <code>chrome.bluetooth.getDevices</code> and the related events.
+</p>
+
+<p>
+  If the device supports the Bluetooth
+  <a href="https://developer.bluetooth.org/TechnologyOverview/Pages/DI.aspx">Device ID specification</a>,
+  several properties are added to the Device object containing the fields
+  defined by that specification. Example:
+</p>
+
+<pre>
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    if (devices[0].vendorIdSource != undefined) {
+      console.log(devices[0].address + ' = ' +
+                  devices[0].vendorIdSource + ':' +
+                  devices[0].vendorId.toString(16) + ':' +
+                  devices[0].productId.toString(16) + ':' +
+                  devices[0].deviceId.toString(16));
+    }
+  }
+});
+</pre>
+
+<p>
+  The Device ID specification is usually sufficient to identify a particular
+  model, and even revision, of a device from a vendor. Where it is not present

[mkearney1, 2014/03/10 21:13:37]

Add comma after 'present': 'Where it is not present, you...'

[keybuk, 2014/03/11 17:03:39]

Done.

+  you must instead rely on information about the class or type of the device,
+  optionally combined with the manufacturer prefix in the <code>address</code>.
+</p>
+
+<p>
+  Most Bluetooth devices provide Class of Device information as a bit-field
+  interpreted according to the
+  <a href="https://www.bluetooth.org/en-us/specification/assigned-numbers/baseband">Baseband Assigned Numbers</a>
+  document. This bit-field is available in the <code>deviceClass</code>
+  property.
+</p>
+
+<pre>
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    if (devices[0].vendorIdSource != undefined) {
+      console.log(devices[0].address + ' = ' +
+                  devices[0].deviceClass.toString(16));
+    }
+  }
+});
+</pre>
+
+<p>
+  Parsing the field can be complex so for the most common device types Chrome
+  handles this for you and sets the <code>type</code> field. Where this is
+  not available, or insufficient for your needs, you'll need to parse the
+  <code>deviceClass</code> yourself.
+</p>
+
+<pre>
+chrome.bluetooth.getDevices(function(devices) {
+  for (var i = 0; i < devices.length; i++) {
+    if (devices[0].vendorIdSource != undefined) {
+      console.log(devices[0].address + ' = ' + devices[0].type);
+    }
+  }
+});
+</pre>
+