Bluetooth: write documentation

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

Index: chrome/common/extensions/docs/templates/articles/app_bluetooth.html
diff --git a/chrome/common/extensions/docs/templates/articles/app_bluetooth.html b/chrome/common/extensions/docs/templates/articles/app_bluetooth.html
new file mode 100644
index 0000000000000000000000000000000000000000..37b6d5bd2346ee5a1d98f80f229dbaf2082ace43
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/articles/app_bluetooth.html
@@ -0,0 +1,257 @@
+<h1>Bluetooth</h1>
+
+<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" ]

[armansito, 2014/03/09 05:51:33]

We do allow specifying 128-bit UUIDs in the API, right? If so, I would change
one of the example UUIDs to 128-bit format, to show that various types of UUIDs
can be specified. This would be especially good for those who are new to
Bluetooth in general.

[keybuk, 2014/03/09 08:03:45]

We only currently support 16-bit UUIDs - crbug.com/237582

The documentation can be changed later when that's fixed

[armansito, 2014/03/09 18:38:10]

Oh, that's right. If someone DOES go and put in a 128-bit UUID in the manifest
file, I wonder if Chrome complains with an error when the extension gets
installed. If it doesn't, we should probably make it do so later. Either way,
should we add a note here for now that only 16-bit UUIDs can be specified?

+}
+</pre>
+
+<p>
+  To only access adapter state, discover nearby devices and obtain basic
+  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
+  <code>chrome.bluetooth.startDiscovery</code> method, discovery can be
+  resource intensive so you should call
+  <code>chrome.bluetooth.stopDiscovery</code> when done.

[armansito, 2014/03/09 05:51:33]

I would mention here that the call to startDiscovery shouldn't be conditional on
the adapter state and that the apps should always call this method if they
require discovery, as other apps might cause discovery to stop.

Unless, discovery state changes to false even though the app called
startDiscovery successfully before, in which case they should call it again, if
needed.

[keybuk, 2014/03/09 16:24:39]

Done.

+</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
+  <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];
+}
+
+chrome.bluetooth.onDeviceAdded.addListener(updateDeviceName);
+chrome.bluetooth.onDeviceChanged.addListener(updateDeviceName);
+chrome.bluetooth.onDeviceRemoved.addListener(removeDeviceName);
+
+chrome.bluetooth.getDevices(function(devices) {

[armansito, 2014/03/09 05:51:33]

The code is pretty self-explanatory, though I would add a comment line above
this call, something like "// Get devices that were already discovered."

[keybuk, 2014/03/09 16:24:39]

Done.

+  for (var i = 0; i < devices.length; i++) {
+    updateDeviceName(devices[i]);
+  }
+});
+
+chrome.bluetooth.startDiscovery(function() {
+  // Stop discovery after 30 seconds.
+  setTimeout(function() {
+    chrome.bluetooth.stopDiscovery(function() {});
+  }, 30000);
+});
+</pre>
+
+<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
+  you must intead rely on information about the class or type of the device,

[armansito, 2014/03/09 05:51:33]

s/intead/instead/

[keybuk, 2014/03/09 16:24:39]

Done.

+  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>
+