Bluetooth: write documentation

Write an app_bluetooth page documenting the APIs for adapter state,
device information and discovery. Update links accordingly.

BUG=256728
R=armansito@chromium.org, mkearney@chromium.org

Review URL: https://codereview.chromium.org/189263004

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@256260 0039d316-1c4b-4281-b951-d872f2087c98

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

@@ -0,0 +1,284 @@
+<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" ]
+}
+</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 (see
+  <a href="#discovery">Discovering nearby devices</a>).
+</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
+  (see <a href="#discovery">Discovering nearby devices</a>).
+</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.
+</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
+  <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
+  <code>chrome.bluetooth.onAdapterStateChanged</code> event. If the
+  <code>discovering</code> property changes to <code>false</code>, then your app
+  will need to call <code>chrome.bluetooth.startDiscovery</code> again to
+  resume. Be cautious of the resource intensive nature of 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,
+  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>
+

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

@@ -6,7 +6,7 @@ <h1>Serial Devices</h1>
 <p>
 This document describes how to use the <a href="serial.html">serial API</a> to read
 and write from serial devices. Chrome Apps can also connect to
-<a href="app_usb.html">USB</a> and <a href="bluetooth.html">Bluetooth</a> devices.
+<a href="app_usb.html">USB</a> and <a href="app_bluetooth.html">Bluetooth</a> devices.
 </p>
 
 <p class="note">
@@ -88,7 +88,7 @@ <h2 id="opening">Connecting to a serial device</h2>
 <h2 id="disconnect">Disconnect from a serial port</h2>
 
 <p>
-When an app terminates, connections to serial ports that are not persistent 
+When an app terminates, connections to serial ports that are not persistent
 are automatically closed by the platform. However, if you want to disconnect
 while your app is still running, you can use the $ref:serial.disconnect method:
 </p>
@@ -109,9 +109,9 @@ <h2 id="reading">Reading from a serial port</h2>
 <p>
 The serial API reads from the serial port and delivers the read bytes as an ArrayBuffer to event listeners.
 
-Every port that your application is connected to will generate read events to all listeners added through 
+Every port that your application is connected to will generate read events to all listeners added through
 <code>chrome.serial.onReceive.addListener(onReceiveCallback)</code>. If you are connected to more than one port at the
-same time, you may find the corresponding <code>connectionId</code> of an incoming read event in the callback parameter 
+same time, you may find the corresponding <code>connectionId</code> of an incoming read event in the callback parameter
 of $ref:serial.onReceive.
 </p>
 <p>

chrome/common/extensions/docs/templates/articles/manifest/bluetooth.html

@@ -0,0 +1,28 @@
+<h1>Manifest - Bluetooth</h1>
+
+<p>
+The <code>bluetooth</code> manifest property declares which permissions are
+available for the $ref:bluetooth API.
+</p>
+
+<h2 id="manifest">Sample manifest.json</h2>
+<pre data-filename="manifest.json">
+{
+  "name": "My Bluetooth {{platform}}",
+  "bluetooth": {
+    // Permission for chrome.bluetooth.addProfile:
+    // The application is allowed to make and receive connections
+    // implementing the profiles identified by the UUIDs
+    // 0x1105 and 0x1106.
+    "profiles": [ "1105", "1106" ]
+  },
+  ...
+}
+</pre>
+
+<section>
+<h2 id="reference">Reference</h2>
+<p class="api_reference">
+{{+partials.type type:apis.manifestTypes.byName.bluetooth/}}
+</p>
+</section>

chrome/common/extensions/docs/templates/json/apps_sidenav.json

@@ -184,6 +184,10 @@
               {
                 "title": "Network Communications",
                 "href": "/apps/app_network.html"
+              },
+              {
+                "title": "Bluetooth",
+                "href": "/apps/app_bluetooth.html"
               }
             ]
           },

chrome/common/extensions/docs/templates/json/chrome_sidenav.json

@@ -408,6 +408,10 @@
               {
                 "title": "Network Communications",
                 "href": "/apps/app_network"
+              },
+              {
+                "title": "Bluetooth",
+                "href": "/apps/app_bluetooth"
               }
             ]
           },

chrome/common/extensions/docs/templates/json/intro_tables.json

@@ -38,8 +38,8 @@
   "bluetooth": {
     "Learn More": [
       {
-        "link": "app_usb.html",
-        "text": "Accessing Hardware Devices"
+        "link": "app_bluetooth.html",
+        "text": "Bluetooth"
       }
     ]
   },

chrome/common/extensions/docs/templates/json/manifest.json

@@ -16,7 +16,13 @@
     "example": false,
     "level": "recommended"
   },
-  "browser_action": {
+  "bluetooth": {
+    "documentation": "manifest/bluetooth.html",
+    "example": {
+      "profiles": [ "1105", "1006" ]
+    }
+  },
+   "browser_action": {
     "documentation": "browserAction.html",
     "example": {},
     "level": "only_one"

chrome/common/extensions/docs/templates/public/apps/app_bluetooth.html

@@ -0,0 +1 @@
+{{+partials.standard_apps_article article:intros.app_bluetooth/}}

chrome/common/extensions/docs/templates/public/apps/manifest/bluetooth.html

@@ -0,0 +1 @@
+{{+partials.standard_apps_article article:intros.manifest/bluetooth/}}