node-red-contrib-huemagic 2.8.2 → 4.0.0

package/huemagic/locales/en-US/hue-temperature.html

@@ -1,50 +1,67 @@
-<script type="text/x-red" data-help-name="hue-temperature">
-    <p>Hue temperature node to receive current (room) temperature in Celsius and Fahrenheit.</p>
+<script type="text/markdown" data-help-name="hue-temperature">
+The "Hue Temperature" node can call up and report the current ambient temperature from a suitable sensor on the bridge.
 
-    <h3>Setup</h3>
-    <p>Select the preconfigured Hue Bridge and hit the search button to find all available temperature sensors. Type in the name of the sensor manually or keep the default device name. Note that events will only sent on deploy (once) and if the temperature changes. If necessary, all status updates of this node can be ignored by activating the "Skip events" option.</p>
+### Setup
 
-    <h3>Temperature Events</h3>
-    <p>The event message that the temperature sensor sends contains the following data in the <b>msg.payload</b> object:</p>
-    <dl class="message-properties">
-        <dt>celsius<span class="property-type">float</span></dt>
-        <dd>Temperature in Celsius</dd>
+Select the pre-configured Hue Bridge and click the search button to find all the available sensors. If you already know the ID of the sensor, you can also enter it here manually. You can either assign a new name for the sensor internally or choose the predefined name of the sensor. Optionally, you can also deactivate all automatic status messages for this node by clicking the setting "Skip events from node". The node will then no longer issue device updates. Alternatively, you can also choose whether the node's initialization message should not be suppressed when Node-RED is started. If you activate this setting, you will receive a status message for the currently selected sensor after each deployment.
 
-        <dt>fahrenheit<span class="property-type">float</span></dt>
-        <dd>Temperature in Fahrenheit</dd>
+If you do not select a sensor and use the node configuration in this way, the node works in the so-called "universal mode". In this mode, the node receives and outputs all status messages of the same type. You can also apply settings in universal mode to a specific sensor by transferring the corresponding sensor ID as a string in `msg.topic` together with your settings.
 
-        <dt>deviceValue<span class="property-type">int</span></dt>
-        <dd>Temperature value of the sensor (original value)</dd>
+### Get status
 
-        <dt>updated<span class="property-type">string</span></dt>
-        <dd>ISO 8601 date string of the last temperature change</dd>
-    </dl>
+Outputs the current status of the sensor as soon as a `msg.payload` object with the following content has been transferred to the node. Alternatively, you can also press the button in the Node-RED interface without having to pass a message to the node beforehand.
 
-    <h3>Additional Sensor Info</h3>
-    <p>Additional information about the sensor is going to be sent to the <b>msg.info</b> object:</p>
-    <dl class="message-properties">
-        <dt>id<span class="property-type">int</span></dt>
-        <dd>Numerical id of the sensor as registered on the bridge</dd>
+: status (boolean): Returns the current status of the sensor
 
-        <dt>uniqueId<span class="property-type">string</span></dt>
-        <dd>Unique Id of the sensor (typically hardware id)</dd>
+### Switch the sensor on / off
 
-        <dt>name<span class="property-type">string</span></dt>
-        <dd>Name for the sensor</dd>
+If necessary, the sensor can be switched on and off remotely. If the sensor has been switched off, it no longer registers any temperature changes and accordingly no longer outputs them. To do this, pass an object with the following content:
 
-        <dt>type<span class="property-type">string</span></dt>
-        <dd>Sensor type (e.g. Daylight, CLIPTemperature, ZGPSwitch)</dd>
+: payload (boolean): `true` switches the sensor on, `false` switches it off
 
-        <dt>softwareVersion<span class="property-type">float</span></dt>
-        <dd>Software version of the sensor</dd>
+### Status messages from the node
 
-        <dt>battery<span class="property-type">int</span></dt>
-        <dd>Current battery level of the temperature sensor in percent</dd>
+As soon as the sensor has registered a temperature change, the following status message is returned by the node:
 
-        <dt>model<span class="property-type">object</span></dt>
-        <dd>The model object of the sensor includes model specific information like the model.id, model.manufacturer, model.name and model.type</dd>
-    </dl>
+#### Status object under `msg.payload`
 
-    <h3>Last State Information</h3>
-    <p>This node also sends the entire last state data (before the update) in the <b>msg.lastState</b> object. It can either contain false (boolean) or the objects payload (msg.lastState.payload) and info (msg.lastState.info). The return value "false" is only sent if there was no last state, e.g. when the node was newly created or restarted.</p>
+: active (boolean): Indicates whether the sensor is switched on or off
+: reachable (boolean | string): `true` if the sensor is connected to the bridge, `unknown` if the connection status deviates
+: connectionStatus (string): The current connection status with the bridge in the form of a string. Can contain `connected`, `disconnected`, `connectivity_issue` or `unidirectional_incoming` as a value
+: celsius (float): Indicates the current ambient temperature in °C (degrees Celsius)
+: fahrenheit (float): Indicates the current ambient temperature in °F (degrees Fahrenheit)
+: temperatureIs (string): Describes the current temperature with the values ´very cold´, ´cold´, ´slightly cold´, ´comfortable´, ´slightly warm´, ´warm´, ´hot´ or ´very hot´
+: deviceValue (float): The original value of the temperature from the sensor
+: updated (string): Time of the last update of the resource by HueMagic (ISO 8601)
+
+#### Information about the sensor under `msg.info`
+
+: id (string): Indicates the new ID of the sensor
+: idV1 (string | boolean): Indicates the old ID of the sensor
+: uniqueId (string): The unique ID of the sensor
+: deviceId (string): The unique ID of the device
+: name (string): The currently set name of the sensor
+: type (string): The type of the sensor (always `temperature`)
+: softwareVersion (string): The current firmware of the sensor
+: battery (float): The current battery level of the sensor
+: batteryState (string): The current status of the battery level. Can contain `normal`, `low` or `critical` as a value
+: model (object): Contains the model information of the sensor under `id`, `manufacturer`, `name`, `type` and `certified`
+
+#### Status changes under `msg.updated`
+
+Lists individual parameters in the form of an object that have changed compared to the last state of the sensor. If no changes have been registered, this object is empty.
+
+#### Last status of the sensor under `msg.lastState`
+
+Contains the complete status object (see output values above) of the last status before the last registered change. If the last state of HueMagic has not yet been registered, it will output `false`.
+
+#### Last command under `msg.command` (optional)
+
+If the status of the node has changed via a certain command, the entire command that was executed is also output. Otherwise this object will not be output by the node.
+
+### Examples from HueMagic
+
+HueMagic provides some sample configurations for this node. To import a full featured example into your Node-RED interface, click on the Node-RED menu icon, then select "Import" and navigate to "Examples" in the sidebar of the popup. Then select the HueMagic folder and your desired node to import a sample flow.
+
+![examples](https://user-images.githubusercontent.com/5302050/148681840-2275c15a-7c0c-4a37-b817-199608e571d2.gif)
 </script>

package/huemagic/locales/en-US/hue-temperature.json

@@ -5,12 +5,14 @@
 		{
 			"name": "Name",
 			"sensor": "Sensor",
-			"skipevents": "Skip events",
 			"skipevents-node": "Skip events from node",
+			"sendinitevents-node": "Do not suppress initialization event",
 			"input-name": "Sensor name",
 			"searching": "searching temperature sensors…",
 			"none-found": "No temperature sensors found.",
-			"unknown-error": "Something went wrong. Please retry."
+			"unknown-error": "Something went wrong. Please retry.",
+			"universalevents": "Universal Events",
+			"universalevents-node": "Receives all messages from other nodes of the same type (only in universal mode)"
 		},
 		"node":
 		{
@@ -18,7 +20,12 @@
 			"not-configured": "not configured",
 			"init": "initializing…",
 			"not-reachable": "not reachable!",
-			"output": "temperature (changed)"
+			"input": "status query",
+			"output": "temperature (changed)",
+			"universal": "universal mode",
+			"command": "executing command…",
+			"deactivated": "deactivated",
+			"statusmsg": "Status queried successfully…"
 		}
 	}
 }

package/huemagic/utils/api.js

@@ -0,0 +1,290 @@
+const axios = require('axios');
+const dayjs = require('dayjs');
+const https = require('https');
+const EventSource = require('eventsource');
+
+function API()
+{
+	// STORAGE
+	this.bridge = null;
+	this.ipAddress = null;
+	this.accessKey = null;
+	this.events = null;
+
+	//
+	// INITIALIZE
+	this.init = function({ ip, key = 'default' })
+	{
+		const scope = this;
+
+		// FORCE RELOAD?
+		const forceReload = (this.ipAddress != ip.toString().trim());
+
+		// STORE ACCESS INFORMATION
+		this.ipAddress = ip.toString().trim();
+		this.accessKey = key.toString().trim();
+
+		// GET BRIDGE
+		return new Promise(function(resolve, reject)
+		{
+			if(scope.bridge !== null && forceReload === false)
+			{
+				resolve(scope.bridge);
+			}
+			else
+			{
+				// GET BRIDGE INFORMATION
+				axios({
+					"method": "GET",
+					"url": "https://" + ip + "/api/config",
+					"headers": { "Content-Type": "application/json; charset=utf-8" },
+					"httpsAgent": new https.Agent({ rejectUnauthorized: false }),
+				})
+				.then(function(response)
+				{
+					scope.bridge = response.data;
+					resolve(scope.bridge);
+				})
+				.catch(function(error)
+				{
+					reject(error);
+				});
+			}
+		});
+	}
+
+	//
+	// MAKE A REQUEST
+	this.request = function({ method = 'GET', ressource = null, data = null, version = 2 })
+	{
+		const scope = this;
+		return new Promise(function(resolve, reject)
+		{
+			// BUILD REQUEST OBJECT
+			var request = {
+				"method": method,
+				"url": "https://" + scope.ipAddress,
+				"headers": {
+					"Content-Type": "application/json; charset=utf-8",
+					"hue-application-key": scope.accessKey
+				},
+				"httpsAgent": new https.Agent({ rejectUnauthorized: false }), // Node is somehow not able to parse the official Philips Hue PEM
+			};
+
+			// HAS RESSOURCE? -> APPEND
+			if(ressource !== null)
+			{
+				if(version === 2)
+				{
+					ressource = (ressource !== "all") ? "/"+ressource : "";
+					request['url'] += "/clip/v2/resource" + ressource;
+				}
+				else if(version === 1)
+				{
+					request['url'] += "/api/" + scope.accessKey + ressource;
+				}
+			}
+
+			// HAS DATA? -> INSERT
+			if(data !== null) {
+				request['data'] = data;
+			}
+
+			// RUN REQUEST
+			axios(request)
+			.then(function(response)
+			{
+				if(version === 2)
+				{
+					if(response.data.errors.length > 0)
+					{
+						reject(response.data.errors);
+					}
+					else
+					{
+						resolve(response.data.data);
+					}
+				}
+				else if(version === 1)
+				{
+					resolve(response.data);
+				}
+			})
+			.catch(function(error)
+			{
+				reject(error);
+			});
+		});
+	}
+
+	//
+	// SUBSCRIBE TO BRIDGE EVENTS
+	this.subscribe = function(callback)
+	{
+		const scope = this;
+		return new Promise(function(resolve, reject)
+		{
+			if(scope.events === null)
+			{
+				var sseURL = "https://" + scope.ipAddress + "/eventstream/clip/v2";
+
+				// INITIALIZE EVENT SOURCE
+				scope.events = new EventSource(sseURL, {
+					headers: { 'hue-application-key': scope.accessKey },
+					https: { rejectUnauthorized: false },
+				});
+
+				// PIPE MESSAGE TO TARGET FUNCTION
+				scope.events.onmessage = function(event)
+				{
+					if(event && event.type === 'message' && event.data)
+					{
+						const messages = JSON.parse(event.data);
+						for (var i = messages.length - 1; i >= 0; i--)
+						{
+							const message = messages[i];
+							if(message.type === "update")
+							{
+								callback(message.data);
+							}
+						}
+					}
+				};
+
+				// CONNECTED?
+				scope.events.onopen = function()
+				{
+					resolve(true);
+				}
+
+				// ERROR? -> RETRY?
+				scope.events.onerror = function(error)
+				{
+					console.log("HueMagic:", "Connection to bridge lost. Trying to reconnect again in 30 seconds…", err);
+					setTimeout(function(){ scope.subscribe(callback); }, 30000);
+					resolve(true);
+				}
+			}
+			else
+			{
+				scope.unsubscribe();
+				scope.subscribe(callback);
+			}
+		});
+	}
+
+	//
+	// UNSUBSCRIBE
+	this.unsubscribe = function()
+	{
+		if(this.events !== null) { this.events.close(); }
+		this.events = null;
+	}
+
+	//
+	// GET FULL/ROOT RESSOURCE
+	this.fullRessource = function(ressource, allRessources = {})
+	{
+		const scope = this;
+		var fullRessource = Object.assign({}, ressource);
+
+		if(ressource["owner"])
+		{
+			fullRessource = scope.fullRessource(allRessources[fullRessource["owner"]["rid"]], allRessources);
+		}
+		else if(ressource["type"] === "device" || ressource["type"] === "room" || ressource["type"] === "zone" || ressource["type"] === "bridge_home")
+		{
+			// RESOLVE SERVICES
+			var allServices = {};
+
+			for (var i = ressource["services"].length - 1; i >= 0; i--)
+			{
+				const targetService = ressource["services"][i];
+				const targetType = targetService["rtype"];
+				const targetID = targetService["rid"];
+
+				if(!allServices[targetType]) { allServices[targetType] = {}; }
+				allServices[targetType][targetID] = Object.assign({}, allRessources[targetID]);
+			}
+
+			// REPLACE SERVICES
+			fullRessource["services"] = allServices;
+		}
+
+		return fullRessource;
+	}
+
+	//
+	// PROCESS RESSOURCES
+	this.processRessources = function(ressources)
+	{
+		const scope = this;
+
+		// SET CURRENT DATE/TIME
+		const currentDateTime = dayjs().format();
+
+		// ACTION!
+		return new Promise(function(resolve, reject)
+		{
+			let ressourceList = {};
+			let processedRessources = {
+				_groupsOf: {}
+			};
+
+			// CREATE ID BASED OBJECT OF ALL RESSOURCES
+			ressources.forEach(function(ressource, index)
+			{
+				// IS BUTTON? -> REMOVE PREVIOUS STATE
+				if(ressource.type === "button")
+				{
+					delete ressource["button"];
+				}
+
+				ressourceList[ressource.id] = ressource;
+			});
+
+			// GET FULL RESSOURCES OF EACH OBJECT
+			ressources.forEach(function(ressource, index)
+			{
+				// GET FULL RESSOURCE
+				let fullRessource = scope.fullRessource(ressource, ressourceList);
+
+				// ADD CURRENT DATE/TIME
+				fullRessource["updated"] = currentDateTime;
+
+				// ALL ALL TYPES BEHIND RESSOURCE
+				fullRessource["types"] = [ fullRessource["type"] ];
+
+				// RESSOURCE HAS SERVICES?
+				if(fullRessource["services"])
+				{
+					let additionalServiceTypes = Object.keys(fullRessource["services"]);
+
+					// SET ADDITIONAL TYPES BEHIND RECCOURCE
+					fullRessource["types"] = fullRessource["types"].concat(additionalServiceTypes);
+				}
+
+				// RESOURCE HAS GROUPED SERVICES?
+				if(fullRessource["grouped_services"])
+				{
+					for (var g = fullRessource["grouped_services"].length - 1; g >= 0; g--)
+					{
+						const groupedService = fullRessource["grouped_services"][g];
+						const groupedServiceID = groupedService["rid"];
+
+						if(!processedRessources["_groupsOf"][groupedServiceID]) { processedRessources["_groupsOf"][groupedServiceID] = []; }
+						processedRessources["_groupsOf"][groupedServiceID].push(fullRessource.id);
+					}
+				}
+
+				// GIVE FULL RESSOURCE BACK TO COLLECTION
+				processedRessources[fullRessource.id] = fullRessource;
+			});
+
+			resolve(processedRessources);
+		});
+	}
+}
+
+// EXPORT
+module.exports = new API;