From 4ba2126205fa49e13882d77a45a5b7f4c67032a6 Mon Sep 17 00:00:00 2001
From: Peter Murray <pmurray@osirisoft.com>
Date: Fri, 9 Jan 2015 18:24:05 +0000
Subject: [PATCH] - Adding new function names to add clarity to the types of
 discovery offered and match them up to the Hue API documentation

---
 README.md | 23 ++++++++++++++---------
 index.js  | 27 ++++++++++++++++++++++++---
 2 files changed, 38 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 786f9f9..9d1b4df 100644
--- a/README.md
+++ b/README.md
@@ -52,13 +52,18 @@ $ npm install node-hue-api
 ## Examples
 
 ### Locating a Philips Hue Bridge
-There are two functions available to find the Phillips Hue Bridges on the network ``locateBridges()`` and ``searchForBridges()``.
+There are two functions available to find the Phillips Hue Bridges on the network ``nupnpSearch()`` and ``upnpSearch()``.
 Both of these methods are useful if you do not know the IP Address of the bridge already.
 
-### locateBridges()
+The offical Hue documentation recommends an approach to finding bridges by using both UPnP and N-UPnP in parallel
+to find your bridges on the network. This API library provided you with both options, but leaves it
+to the developer to decide on the approach to be used, i.e. fallback, parallel, or just one type.
+
+#### nupnpSearch() or locateBridges()
 This API function makes use of the official API endpoint that reveals the bridges on a network. It is a call through to
-``http://meethue.com/api/nupnp`` which may not work in all circumstances, in which case you can fall back to the old function
-``searchForBridges()``.
+``http://meethue.com/api/nupnp`` which may not work in all circumstances (your bridge must have signed into the methue portal),
+ in which case you can fall back to the slower
+``upnpSearch()`` function.
 
 This function is considerably faster to resolve the bridges < 500ms compared to 5 seconds to perform a full search on my
 own network.
@@ -72,11 +77,11 @@ var displayBridges = function(bridge) {
 
 // --------------------------
 // Using a promise
-hue.locateBridges().then(displayBridges).done();
+hue.nupnpSearch().then(displayBridges).done();
 
 // --------------------------
 // Using a callback
-hue.locateBridges(function(err, result) {
+hue.nupnpSearch(function(err, result) {
 	if (err) throw err;
 	displayBridges(result);
 });
@@ -84,11 +89,11 @@ hue.locateBridges(function(err, result) {
 
 The results from this call will be of the form;
 ```
-Hue Bridges Found: [{"id":"001788fffe096103","ipaddress":"192.168.2.129"}]
+Hue Bridges Found: [{"id":"001788fffe096103","ipaddress":"192.168.2.129","name":"Philips Hue","mac":"00:00:00:00:00"}]
 ```
 
 
-#### searchForBridges()
+#### upnpSearch or searchForBridges()
 This API function utilizes a network scan for the SSDP responses of devices on a network. It is the only method that does not
 support callbacks, and is only in the API as a fallback since Phillips provided a quicker discovery method once the API was
 officially released.
@@ -101,7 +106,7 @@ var displayBridges = function(bridge) {
 	console.log("Hue Bridges Found: " + JSON.stringify(bridge));
 };
 
-hue.searchForBridges(timeout).then(displayBridges).done();
+hue.upnpSearch(timeout).then(displayBridges).done();
 ```
 A timeout can be provided to the function to increase/decrease the amount of time that it waits for responses from the
 search request, by default this is set to 5 seconds (the above example sets this to 2 seconds).
diff --git a/index.js b/index.js
index 3b4a25b..e4c6829 100644
--- a/index.js
+++ b/index.js
@@ -1,14 +1,35 @@
 "use strict";
 
+var bridgeDiscovery = require("./hue-api/bridge-discovery");
+
 //
 // This wrapper is to provide some continuity in the modifications of the APIs over time
 //
 
 module.exports.HueApi = require("./hue-api/index.js");
 
-module.exports.locateBridges = require("./hue-api/bridge-discovery").locateBridges;
-module.exports.searchForBridges = require("./hue-api/bridge-discovery").networkSearch;
+module.exports.locateBridges = _deprecated(
+    bridgeDiscovery.locateBridges
+    , "'locateBridges' is deprecated, please use 'nupnpSearch' instead"
+);
+module.exports.nupnpSearch = bridgeDiscovery.locateBridges;
+
+module.exports.searchForBridges = _deprecated(
+    bridgeDiscovery.networkSearch
+    , "'searchForBridges' is deprecated, please use 'upnpSearch' instead"
+);
+module.exports.upnpSearch = bridgeDiscovery.networkSearch;
 
 module.exports.lightState = require("./hue-api/lightstate.js");
 module.exports.scheduledEvent = require("./hue-api/scheduledEvent.js");
-module.exports.ApiError = require("./hue-api/errors.js").ApiError;
\ No newline at end of file
+module.exports.ApiError = require("./hue-api/errors.js").ApiError;
+
+
+function _deprecated(fn, message) {
+
+    return function () {
+        var args = Array.prototype.slice.call(arguments);
+        console.error(message);
+        return fn.apply(this, args);
+    }
+}
\ No newline at end of file