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, r
keybuk
2014/03/09 08:03:45
We only currently support 16-bit UUIDs - crbug.com
armansito
2014/03/09 18:38:10
Oh, that's right. If someone DOES go and put in a
|
+} |
+</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 startDiscove
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 woul
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> |
+ |