Updated generated API documentation.

evothings · Mar 10, 2016 · ad0ae33 · ad0ae33
1 parent 0a3ddbc
commit ad0ae33
Show file tree

Hide file tree

Showing 43 changed files with 4,227 additions and 199 deletions.
diff --git a/lib-doc/cordova-ble_ble.js.html b/lib-doc/cordova-ble_ble.js.html
diff --git a/lib-doc/arduinoble_arduinoble.js.html → ...s_evothings_arduinoble_arduinoble.js.html b/lib-doc/arduinoble_arduinoble.js.html → ...s_evothings_arduinoble_arduinoble.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: arduinoble/arduinoble.js</title>
+  <title>Source: evothings-libraries/libs/evothings/arduinoble/arduinoble.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: arduinoble/arduinoble.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/arduinoble/arduinoble.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: arduinoble.js
@@ -193,7 +193,7 @@ <h1>Source: arduinoble/arduinoble.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/lib-doc/arduinotcp_arduinotcp.js.html → ...s_evothings_arduinotcp_arduinotcp.js.html b/lib-doc/arduinotcp_arduinotcp.js.html → ...s_evothings_arduinotcp_arduinotcp.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: arduinotcp/arduinotcp.js</title>
+  <title>Source: evothings-libraries/libs/evothings/arduinotcp/arduinotcp.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: arduinotcp/arduinotcp.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/arduinotcp/arduinotcp.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: arduinotcp.js
@@ -462,7 +462,7 @@ <h1>Source: arduinotcp/arduinotcp.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/lib-doc/easyble_easyble.js.html → ...es_libs_evothings_easyble_easyble.js.html b/lib-doc/easyble_easyble.js.html → ...es_libs_evothings_easyble_easyble.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: easyble/easyble.js</title>
+  <title>Source: evothings-libraries/libs/evothings/easyble/easyble.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: easyble/easyble.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/easyble/easyble.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: easyble.js
@@ -443,13 +443,14 @@ <h1>Source: easyble/easyble.js</h1>
 		var advertisementData &#x3D; device.advertisementData;
 		if (advertisementData)
 		{
-			if (advertisementData.kCBAdvDataServiceUUIDs)
+			var serviceUUIDs &#x3D; advertisementData.kCBAdvDataServiceUUIDs;
+			if (serviceUUIDs)
 			{
-				for (var i in advertisementData)
+				for (var i in serviceUUIDs)
 				{
 					for (var j in serviceFilter)
 					{
-						if (advertisementData[i].toLowerCase() &#x3D;&#x3D;
+						if (serviceUUIDs[i].toLowerCase() &#x3D;&#x3D;
 							serviceFilter[j].toLowerCase())
 						{
 							return true;
@@ -469,16 +470,44 @@ <h1>Source: easyble/easyble.js</h1>
 	internal.addMethodsToDeviceObject &#x3D; function(deviceObject)
 	{
 		/**
-		 * This is the BLE DeviceInfo object obtained by calling
-		 * evothings.ble.startScan, with additional properties and
-		 * functions added. Internal properties are prefixed with two
-		 * underscores. Properties are also added to the Characteristic
-		 * and Descriptor objects.
 		 * @namespace
 		 * @alias evothings.easyble.EasyBLEDevice
+		 * @description This is the BLE DeviceInfo object obtained from the
+		 * underlying Cordova plugin.
+		 * @property {string} address - Uniquely identifies the device.
+		 * The form of the address depends on the host platform.
+		 * @property {number} rssi - A negative integer, the signal strength in decibels.
+		 * @property {string} name - The device&#x27;s name, or nil.
+		 * @property {string} scanRecord - Base64-encoded binary data. Its meaning is
+		 * device-specific. Not available on iOS.
+		 * @property {evothings.easyble.AdvertisementData} advertisementData -
+		 * Object containing some of the data from the scanRecord.
 		 */
 		var device &#x3D; deviceObject;
 
+		/**
+		 * @typedef {Object} evothings.easyble.AdvertisementData
+		 * @description Information extracted from a scanRecord. Some or all of the fields may be
+		 * undefined. This varies between BLE devices.
+		 * Depending on OS version and BLE device, additional fields, not documented
+		 * here, may be present.
+		 * @property {string} kCBAdvDataLocalName - The device&#x27;s name. Use this field
+		 * rather than device.name, since on iOS the device name is cached and changes
+		 * are not reflected in device.name.
+		 * @property {number} kCBAdvDataTxPowerLevel - Transmission power level as
+		 * advertised by the device.
+		 * @property {boolean} kCBAdvDataIsConnectable - True if the device accepts
+		 * connections. False if it doesn&#x27;t.
+		 * @property {array} kCBAdvDataServiceUUIDs - Array of strings, the UUIDs of
+		 * services advertised by the device. Formatted according to RFC 4122,
+		 * all lowercase.
+		 * @property {object} kCBAdvDataServiceData - Dictionary of strings to strings.
+		 * The keys are service UUIDs. The values are base-64-encoded binary data.
+		 * @property {string} kCBAdvDataManufacturerData - Base-64-encoded binary data.
+		 * This field is used by BLE devices to advertise custom data that don&#x27;t fit
+		 * into any of the other fields.
+		 */
+
 		/**
 		 * Match device name.
 		 * @param name The name to match.
@@ -1190,15 +1219,8 @@ <h1>Source: easyble/easyble.js</h1>
 		evothings.ble.readDescriptor(
 			device.deviceHandle,
 			descriptor.handle,
-			value,
-			function()
-			{
-				success();
-			},
-			function(errorCode)
-			{
-				fail(errorCode);
-			});
+			success,
+			fail);
 	};
 
 	/**
@@ -1457,7 +1479,7 @@ <h1>Source: easyble/easyble.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/lib-doc/eddystone_eddystone.js.html → ...ibs_evothings_eddystone_eddystone.js.html b/lib-doc/eddystone_eddystone.js.html → ...ibs_evothings_eddystone_eddystone.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: eddystone/eddystone.js</title>
+  <title>Source: evothings-libraries/libs/evothings/eddystone/eddystone.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: eddystone/eddystone.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/eddystone/eddystone.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: eddystone.js
@@ -62,9 +62,9 @@ <h1>Source: eddystone/eddystone.js</h1>
  * @description Starts scanning for Eddystone devices.
  * &amp;lt;p&gt;Found devices and errors will be reported to the supplied callbacks.&amp;lt;/p&gt;
  * &amp;lt;p&gt;Will keep scanning indefinitely until you call stopScan().&amp;lt;/p&gt;
- * To conserve energy, call stopScan() as soon as you&#x27;ve found the device
- * you&#x27;re looking  for.
- * &amp;lt;p&gt;Calling this function while scanning is in progress will fail.&amp;lt;/p&gt;
+ * &amp;lt;p&gt;To conserve energy, call stopScan() as soon as you&#x27;ve found the device
+ * you&#x27;re looking for.&amp;lt;/p&gt;
+ * &amp;lt;p&gt;Calling startScan() while scanning is in progress will produce an error.&amp;lt;/p&gt;
  *
  * @param {evothings.eddystone.scanCallback} - Success function called
  * when a beacon is found.
@@ -148,7 +148,6 @@ <h1>Source: eddystone/eddystone.js</h1>
  * Which properties are available depends on which packets types broadcasted
  * by the beacon. Properties may be undefined. Typically properties are populated
  * as scanning processes.
- * @alias evothings.eddystone.EddystoneDevice
  * @typedef {Object} evothings.eddystone.EddystoneDevice
  * @property {string} url - An Internet URL.
  * @property {number} txPower - A signed integer, the signal strength in decibels,
@@ -176,6 +175,56 @@ <h1>Source: eddystone/eddystone.js</h1>
 	isScanning &#x3D; false;
 }
 
+/**
+ * @description Calculate the accuracy (distance in meters) of the beacon.
+ * &amp;lt;p&gt;The beacon distance calculation uses txPower at 1 meters, but the
+ * Eddystone protocol reports the value at 0 meters. 41dBm is the signal
+ * loss that occurs over 1 meter, this value is subtracted by default
+ * from the reported txPower. You can tune the calculation by adding
+ * or subtracting to param txPower.&amp;lt;p&gt;
+ * &amp;lt;p&gt;Note that the returned distance value is not accurate, and that
+ * it fluctuates over time. Sampling/filtering over time is recommended
+ * to obtain a stable value.&amp;lt;p&gt;
+ * @public
+ * @param txPower The txPower of the beacon.
+ * @param rssi The RSSI of the beacon, subtract or add to this value to
+ * tune the dBm strength. 41dBm is subtracted from this value in the
+ * distance algorithm used by calculateAccuracy.
+ * @return Distance in meters, or null if unable to compute distance
+ * (occurs for example when txPower or rssi is undefined).
+ * @example
+ *   // Note that beacon.txPower and beacon.rssi many be undefined,
+ *   // in which case calculateAccuracy returns null. This happens
+ *   // before txPower and rssi have been reported by the beacon.
+ *   var distance &#x3D; evothings.eddystone.calculateAccuracy(
+ *       beacon.txPower, beacon.rssi);
+ */
+evothings.eddystone.calculateAccuracy &#x3D; function(txPower, rssi)
+{
+	if (!rssi || rssi &gt;&#x3D; 0 || !txPower)
+	{
+		return null
+	}
+
+	// Algorithm
+	// http://developer.radiusnetworks.com/2014/12/04/fundamentals-of-beacon-ranging.html
+	// http://stackoverflow.com/questions/21338031/radius-networks-ibeacon-ranging-fluctuation
+
+	// The beacon distance formula uses txPower at 1 meters, but the Eddystone
+	// protocol reports the value at 0 meters. 41dBm is the signal loss that
+	// occurs over 1 meter, so we subtract that from the reported txPower.
+	var ratio &#x3D; rssi * 1.0 / (txPower - 41)
+	if (ratio &amp;lt; 1.0)
+	{
+		return Math.pow(ratio, 10)
+	}
+	else
+	{
+		var accuracy &#x3D; (0.89976) * Math.pow(ratio, 7.7095) + 0.111
+		return accuracy
+	}
+}
+
 // Return true on frame type recognition, false otherwise.
 function parseFrameUID(device, data, win, fail)
 {
@@ -318,7 +367,7 @@ <h1>Source: eddystone/eddystone.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/lib-doc/evothings.js.html → ...ibraries_libs_evothings_evothings.js.html b/lib-doc/evothings.js.html → ...ibraries_libs_evothings_evothings.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: evothings.js</title>
+  <title>Source: evothings-libraries/libs/evothings/evothings.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: evothings.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/evothings.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: evothings.js
@@ -290,7 +290,7 @@ <h1>Source: evothings.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/...nordic-nRF51-ble_nordic-nRF51-ble.js.html → ...nordic-nRF51-ble_nordic-nRF51-ble.js.html b/...nordic-nRF51-ble_nordic-nRF51-ble.js.html → ...nordic-nRF51-ble_nordic-nRF51-ble.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: nordic-nRF51-ble/nordic-nRF51-ble.js</title>
+  <title>Source: evothings-libraries/libs/evothings/nordic-nRF51-ble/nordic-nRF51-ble.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: nordic-nRF51-ble/nordic-nRF51-ble.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/nordic-nRF51-ble/nordic-nRF51-ble.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: nordic-nRF51-ble.js
@@ -171,7 +171,7 @@ <h1>Source: nordic-nRF51-ble/nordic-nRF51-ble.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/...-nRF51822-ble_nordic-nRF51822-ble.js.html → ...-nRF51822-ble_nordic-nRF51822-ble.js.html b/...-nRF51822-ble_nordic-nRF51822-ble.js.html → ...-nRF51822-ble_nordic-nRF51822-ble.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: nordic-nRF51822-ble/nordic-nRF51822-ble.js</title>
+  <title>Source: evothings-libraries/libs/evothings/nordic-nRF51822-ble/nordic-nRF51822-ble.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: nordic-nRF51822-ble/nordic-nRF51822-ble.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/nordic-nRF51822-ble/nordic-nRF51822-ble.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: nordic-ble.js
@@ -219,7 +219,7 @@ <h1>Source: nordic-nRF51822-ble/nordic-nRF51822-ble.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>

diff --git a/lib-doc/rfduinoble_rfduinoble.js.html → ...s_evothings_rfduinoble_rfduinoble.js.html b/lib-doc/rfduinoble_rfduinoble.js.html → ...s_evothings_rfduinoble_rfduinoble.js.html
@@ -4,7 +4,7 @@
 <head>
   <meta name="generator" content="JSDoc 3.4.0">
   <meta charset="utf-8">
-  <title>Source: rfduinoble/rfduinoble.js</title>
+  <title>Source: evothings-libraries/libs/evothings/rfduinoble/rfduinoble.js</title>
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Karla:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Noto+Serif:400,400i,700,700i" type="text/css">
   <link rel="stylesheet" href="https://brick.a.ssl.fastly.net/Inconsolata:500" type="text/css">
@@ -26,7 +26,7 @@
         </div>
         <div id="jsdoc-main" role="main">
           <header class="page-header">
-            <h1>Source: rfduinoble/rfduinoble.js</h1>
+            <h1>Source: evothings-libraries/libs/evothings/rfduinoble/rfduinoble.js</h1>
           </header>
           <article>
             <pre class="prettyprint linenums"><code>// File: rfduinoble.js
@@ -174,7 +174,7 @@ <h1>Source: rfduinoble/rfduinoble.js</h1>
   <footer id="jsdoc-footer" class="jsdoc-footer">
     <div id="jsdoc-footer-container">
       <p>
-        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on February 10, 2016.
+        Generated by <a href="https://github.com/jsdoc3/jsdoc">JSDoc</a> 3.4.0 on March 10, 2016.
       </p>
     </div>
   </footer>