		# node-red-contrib-sun-position

		#### 1.0.12: BugFix

		- general
		- BugFix: Allow 0 as value for any time input, mainly for time-compare or time-span node, but affects potentially all nodes.
		- BugFix: random offset #90 now working as expected
		- BugFix: node error output for time input if time can not be evaluated has missing original message.
		- prepared new Node interval-inject (not finished, not available) - is the same as standard node-red inject node for intervals with start and end of interval able to use sun-times.

		#### 1.0.11: enhancement
		@@ -4,0 +12,0 @@

202

clock_timer.md

		@@ -19,2 +19,3 @@ # clock-timer Controller
		- [overwrite settings](#overwrite-settings)
		- [special settings](#special-settings)
		- [Node Input](#node-input)
		@@ -24,2 +25,6 @@ - [Node Output](#node-output)
		- [rules](#rules)
		- [rules execution in detail](#rules-execution-in-detail)
		- [rules example](#rules-example)
		- [time rules additional constraints](#time-rules-additional-constraints)
		- [Samples](#samples)
		- [Other](#other)
		@@ -29,3 +34,3 @@

		The node was created out of the desire to be able to use the [blind-control node](blind_control.md) also for dimmers. So this node is a simplified [blind-control node](blind_control.md) without sun based control. In contrast, this node offers the possibility to have any payload.
		The node was created out of the desire to be able to use the [blind-control node](blind_control.md) also for dimmers or other use-cases. So this node is a simplified [blind-control node](blind_control.md) without sun based control. In contrast, this node offers the possibility to have any payload.

		@@ -46,2 +51,3 @@ ### Node settings
		- default payload The value which will be used if no other value given by rule, or override.
		- topic if defined, the default topic of any outgoing message will be set to this value, otherwise the topic of the ingoing message will be used

		@@ -70,10 +76,10 @@ ![clock-timer-settings-3](https://user-images.githubusercontent.com/12692680/70744707-84a94200-1d22-11ea-8fc4-f781e6202901.png)

		* output here is configurable if the node has one single (default) or two outputs. See [Node Output](#node-output) for further details.
		* auto trigger Typically the calculation will be triggered by an incoming message or by an expiring timeout from an override. Additionally the node can be configured to have an auto trigger time.
		* If such a time is configured the node will be trigger a new calculation automatically at the next possible time, taking the following times into account:
		* a time for a rule or the next rule occurs or expires
		* the configured time span in the node
		* To thus in the most cases it makes no sense to enter a short period (less than 15min) of auto trigger time in the configuration, because the node automatically shortens the time if necessary.
		* Please note that the node cannot react to changes in times that are configured via a context. If for example times or offsets configured by using a flow or global context, the auto trigger would not change the next trigger time.
		* start delay Sometimes on node-red start (or flow re deploy) the node should not send any output before the system has settled (contexts are set, incoming messages processed, ...). To thus it is possible to define a delay time. Setting a time will only block the node to send any output until the time has reached to the first output. All calculations still will be made.
		- output here is configurable if the node has one single (default) or two outputs. See [Node Output](#node-output) for further details.
		- auto trigger Typically the calculation will be triggered by an incoming message or by an expiring timeout from an override. Additionally the node can be configured to have an auto trigger time.
		- If such a time is configured the node will be trigger a new calculation automatically at the next possible time, taking the following times into account:
		- a time for a rule or the next rule occurs or expires
		- the configured time span in the node
		- To thus in the most cases it makes no sense to enter a short period (less than 15min) of auto trigger time in the configuration, because the node automatically shortens the time if necessary.
		- Please note that the node cannot react to changes in times that are configured via a context. If for example times or offsets configured by using a flow or global context, the auto trigger would not change the next trigger time.
		- start delay Sometimes on node-red start (or flow re deploy) the node should not send any output before the system has settled (contexts are set, incoming messages processed, ...). To thus it is possible to define a delay time. Setting a time will only block the node to send any output until the time has reached to the first output. All calculations still will be made.

		@@ -112,3 +118,3 @@ ### Node Input

		An output can be triggered by an incoming message or by an expiring timeout from an override. If the trigger is a incoming message, the incoming message will be forwarded to the first output if the rule has changed.
		An output can be triggered by an incoming message, by an expiring timeout from an override or by auto trigger. If the trigger is a incoming message, the incoming message will be forwarded to the first output if the rule or payload has changed.

		@@ -118,3 +124,3 @@ The incoming message is changed as following:
		- `msg.topic` if a topic is defined this topic will be used, otherwise no change of the topic from the incoming message
		- `msg.payload` the payload will be set to the new blind level (numeric value)
		- `msg.payload` the payload will be set to the new defiend payload

		@@ -128,48 +134,43 @@ If the output is set to single, an object property `msg.timeCtrl` will be attached to the message and forwarded to the first output.

		* `timeCtrl` a object will be added add as `msg.timeCtrl` property on single output mode or send as `msg.payload` on slit output mode with the following properties:
		* `timeCtrl.reason` - __object__ - for the reason of the current blind position
		* `timeCtrl.reason.code` - __number__ - representing the reason for the blind position. The possible codes are
		* NaN - start delay is setup and node is in this time
		* -1 - the rules was not evaluated, maybe override is active
		* 1 - defined default payload, because no other rule/condition/behavior
		* 2 - manual override
		* 3 - manual override - expiring
		* 4 - based blind position based by rule
		* `timeCtrl.reason.state` - __string__ - short text representing the reason for the blind position (same as node status text)
		* `timeCtrl.reason.description` - __string__ - describe the reason for the blind position
		* `timeCtrl.timeClock` - __object__ - containing all settings, only the most interesting ones are explained here
		* `timeCtrl.timeClock.payloadDefault` - __any__ - the defined default payload
		* `timeCtrl.timeClock.payloadDefaultType` - __string__ - the type of the default payload
		* `timeCtrl.timeClock.payloadDefault...` - other settings of the default payload
		* `timeCtrl.timeClock.topic` - __string__ - the defined default topic
		* `timeCtrl.timeCtrl.overwrite` - __object__
		* `timeCtrl.timeCtrl.overwrite.active` - __boolean__ - is `true` when overwrite is active, otherwise `false`
		* `timeCtrl.timeCtrl.overwrite.priority` - __number__ - the priority of the override
		* `timeCtrl.timeCtrl.overwrite.expires` - __boolean__ - is `true` when overwrite expires [exists only if overwrite active]
		* `timeCtrl.timeCtrl.overwrite.expireTs` - __number__ - a timestamp (UNIX) when overwrite expiring [exists only if overwrite expires]
		* `timeCtrl.timeCtrl.overwrite.expireDate` - __string__ - a timestamp (String) when overwrite expiring [exists only if overwrite expires]
		* `timeCtrl.rule` - __object__ - exists only if no override is active
		* `timeCtrl.rule.active` - __boolean__ - `true` if a rule applies
		* `timeCtrl.rule.id` - __number__ - id of the rule who applies (is `-1` if no rule has applied)
		* `timeCtrl.rule.level` - __number__ - the blind level defined by the rule if level type is __absolute__, otherwise the defined default blind position [exists only if a rule applies]
		* `timeCtrl.rule.conditional` - __boolean__ - `true` if the rule has a condition [exists only if a rule applies]
		* `timeCtrl.rule.timeLimited` - __boolean__ - `true` if the rule has a time [exists only if a rule applies]
		* `timeCtrl.rule.conditon` - __object__ with additional data about the condition [exists only if `timeCtrl.rule.conditional` is true] - good for debugging purpose
		* `timeCtrl.rule.time` - __object__ with additional data about the time [exists only if `timeCtrl.rule.timeLimited` is true] - good for debugging purpose
		* `timeCtrl.rule.hasMinimum` - __boolean__ - is __true__ if to the level of the rule an additional __minimum__ rule will be active, otherwise __false__
		* `timeCtrl.rule.levelMinimum` - __number__ - exists only if `timeCtrl.rule.hasMinimum` is __true__ and then contains then the blind level defined by the rule
		* `timeCtrl.rule.hasMaximum` - __boolean__ - is __true__ if to the level of the rule an additional __maximum__ rule will be active, otherwise __false__
		* `timeCtrl.rule.levelMinimum` - __number__ - exists only if `timeCtrl.rule.hasMaximum` is __true__ and then contains then the blind level defined by the rule
		* `timeCtrl.autoTrigger` - __object__ - with additional data about the autoTrigger [exists only if auto trigger is enabled in the settings]
		* `timeCtrl.autoTrigger.deaultTime` - __number__ - in milliseconds the auto trigger time of the settings
		* `timeCtrl.autoTrigger.time` - __number__ - in milliseconds the next auto trigger time (could be less than the dined time in the settings)
		* `timeCtrl.autoTrigger.type` - __number__ - the type of the next auto trigger
		* 0 - equal to defined `timeCtrl.autoTrigger.deaultTime`
		* 1 - by current rule end or `timeCtrl.autoTrigger.deaultTime`
		* 2 - by next rule or `timeCtrl.autoTrigger.deaultTime`
		* 3 - sun not on horizon (maybe it is night?)
		* 4 - sun not visible
		* 5 - sun before in window (auto trigger time will be at maximum every 10 minutes)
		* 6 - sun in window and smooth time is set (auto trigger time will be maximum the defined smooth time)
		* 7 - sun in window and no smooth time defined (auto trigger time will be at maximum every 5 minutes)
		- `timeCtrl` a object will be added add as `msg.timeCtrl` property on single output mode or send as `msg.payload` on slit output mode with the following properties:
		- `timeCtrl.reason` - __object__ - for the reason of the current blind position
		- `timeCtrl.reason.code` - __number__ - representing the reason for the blind position. The possible codes are
		- NaN - start delay is setup and node is in this time
		- -1 - the rules was not evaluated, maybe override is active
		- 1 - defined default payload, because no other rule/condition/behavior
		- 2 - manual override
		- 3 - manual override - expiring
		- 4 - based blind position based by rule
		- `timeCtrl.reason.state` - __string__ - short text representing the reason for the blind position (same as node status text)
		- `timeCtrl.reason.description` - __string__ - describe the reason for the blind position
		- `timeCtrl.timeClock` - __object__ - containing all settings, only the most interesting ones are explained here
		- `timeCtrl.timeClock.payloadDefault` - __any__ - the defined default payload
		- `timeCtrl.timeClock.payloadDefaultType` - __string__ - the type of the default payload
		- `timeCtrl.timeClock.payloadDefault...` - other settings of the default payload
		- `timeCtrl.timeClock.topic` - __string__ - the defined default topic
		- `timeCtrl.timeCtrl.overwrite` - __object__
		- `timeCtrl.timeCtrl.overwrite.active` - __boolean__ - is `true` when overwrite is active, otherwise `false`
		- `timeCtrl.timeCtrl.overwrite.priority` - __number__ - the priority of the override
		- `timeCtrl.timeCtrl.overwrite.expires` - __boolean__ - is `true` when overwrite expires [exists only if overwrite active]
		- `timeCtrl.timeCtrl.overwrite.expireTs` - __number__ - a timestamp (UNIX) when overwrite expiring [exists only if overwrite expires]
		- `timeCtrl.timeCtrl.overwrite.expireDate` - __string__ - a timestamp (String) when overwrite expiring [exists only if overwrite expires]
		- `timeCtrl.rule` - __object__ - exists only if no override is active
		- `timeCtrl.rule.active` - __boolean__ - `true` if a rule applies
		- `timeCtrl.rule.id` - __number__ - id of the rule who applies (is `-1` if no rule has applied)
		- `timeCtrl.rule.level` - __number__ - the blind level defined by the rule if level type is __absolute__, otherwise the defined default blind position [exists only if a rule applies]
		- `timeCtrl.rule.conditional` - __boolean__ - `true` if the rule has a condition [exists only if a rule applies]
		- `timeCtrl.rule.timeLimited` - __boolean__ - `true` if the rule has a time [exists only if a rule applies]
		- `timeCtrl.rule.conditon` - __object__ with additional data about the condition [exists only if `timeCtrl.rule.conditional` is true] - good for debugging purpose
		- `timeCtrl.rule.time` - __object__ with additional data about the time [exists only if `timeCtrl.rule.timeLimited` is true] - good for debugging purpose
		- `timeCtrl.rule.hasMinimum` - __boolean__ - is __true__ if to the level of the rule an additional __minimum__ rule will be active, otherwise __false__
		- `timeCtrl.rule.levelMinimum` - __number__ - exists only if `timeCtrl.rule.hasMinimum` is __true__ and then contains then the blind level defined by the rule
		- `timeCtrl.rule.hasMaximum` - __boolean__ - is __true__ if to the level of the rule an additional __maximum__ rule will be active, otherwise __false__
		- `timeCtrl.rule.levelMinimum` - __number__ - exists only if `timeCtrl.rule.hasMaximum` is __true__ and then contains then the blind level defined by the rule
		- `timeCtrl.autoTrigger` - __object__ - with additional data about the autoTrigger [exists only if auto trigger is enabled in the settings]
		- `timeCtrl.autoTrigger.deaultTime` - __number__ - in milliseconds the auto trigger time of the settings
		- `timeCtrl.autoTrigger.time` - __number__ - in milliseconds the next auto trigger time (could be less than the dined time in the settings)
		- `timeCtrl.autoTrigger.type` - __number__ - the type of the next auto trigger
		- 0 - equal to defined `timeCtrl.autoTrigger.deaultTime`
		- 1 - by current rule end or `timeCtrl.autoTrigger.deaultTime`
		- 2 - by next rule or `timeCtrl.autoTrigger.deaultTime`

		@@ -181,14 +182,87 @@ ### Node Status

		* red - any error or a start delay is set and node is currently in this time
		* blue - override active
		* grey - payload by rule
		* green - default value
		* yellow - any other
		- red - any error or a start delay is set and node is currently in this time
		- blue - override active
		- grey - payload by rule
		- green - default value
		- yellow - any other

		## rules

		------------------------------------------------------------
		The rules are not easy to understand.
		![rule-edit-0](https://user-images.githubusercontent.com/12692680/75869514-f4066d80-5e09-11ea-9130-a5ca4b804bf0.png)

		Documentation not finished, but you can used the documentation of the blind control. This node is very similar.
		There are basically 4 generic types of rules:

		- no time and no condition rule
		![rule-type-1](https://user-images.githubusercontent.com/12692680/75872780-12bb3300-5e0f-11ea-9c13-f086415dde46.png)
		- a rule with no time and no condition will be always active if checked.
		- such rules are evaluated in the order of time __until__ and time __from__ rules
		- a rule with a condition - conditional rule
		![rule-type-2](https://user-images.githubusercontent.com/12692680/75876361-db03b980-5e15-11ea-9f47-2d72ff4ab43d.png)
		- a rule with a condition will only be active if the condition matches, otherwise the rule will be ignored
		- rules with only a condition are evaluated in the order of time __until__ and time __from__ rules
		- a rule with a given time - time rule
		![rule-type-3](https://user-images.githubusercontent.com/12692680/75883648-a1d24600-5e23-11ea-9536-3bf03a83c2ac.png)
		- time rules differ again in 2 ways
		- __until__ time rules
		- rules will be active from Midnight __until__ the given time
		- the first matching __until__ rule with a time later than the current time will be selected
		- __from__ time rules
		- rules will be active __from__ given time to Midnight
		- the last matching __from__ rule with a time earlier than the current time will be considered
		- __from__ rules only considered if no __until__ rule was selected
		- a rule with a condition and a given time
		![rule-type-4](https://user-images.githubusercontent.com/12692680/75883859-02618300-5e24-11ea-8f73-720b8867fdea.png)
		- these type of rules are a combination. The rules will only be considered if the condition matches and then it act as a normal time rule. Otherwise it will be ignored.

		### rules execution in detail

		The exact logic is as follows:

		1. The system evaluates from the first rule starting to the last rule of type __until__ in ascending order (or if there is no __until__ rule, then to the last rule).
		- Rules whose condition does not apply will be skipped.
		- Rules of the time type __from__ are skipped.
		- The first rule of level type __absolute__, which has no time constraint or whose time is greater than the current time, is chosen.
		- Subsequent rules are no longer considered, even if they have no time constraint.
		2. If no rule was found under 1., the system evaluates the rules in descending order from the last rule.
		- Rules whose condition does not apply will be skipped.
		- Rules the time type __until__ to are skipped.
		- The first rule of the level type __absolute__, which has no time constraint or whose time is smaller than the current time, is chosen.
		- Further rules are not evaluated, even if they have no time constraint.
		3. If no rule was found with 1st and 2nd, the default payload value for the node is used.

		The rules in the range between the last to rule and the first rule are evaluated only if no other rule is active. This can be used to allow special control during this time.

		### rules example

		For examples, please see [blind control](blind_control.md). The clock-timer node is very similar to the blind-control node.

		### time rules additional constraints

		On a time rule additional constraints can be choose:
		![blind-control-rules-constraints](https://user-images.githubusercontent.com/12692680/75113198-f61f3e00-564b-11ea-835e-7550a9e765af.png)

		A rule is only executed if there are no restrictions.

		That means:

		- if the current day of the week is one of the selected days of the week
		- if the current month is one of the selected months
		- if only even is selected and the current day is an even day
		- if only odd is selected and the current day is an odd day
		- if the current day is in the time period as selected
		- For the time period settings the year is ignored.
		- Normal: the start day and month is less than the end day and month
		- the rule is only executed if the current month+day is greater than or equal the selected period start and less than the selected end month and day.
		- Example: This can be used To setup a period starting from 17th of March to 7th of May.
		- over the year: the start day and month is greater than the end day and month
		- the rule is only executed if the current month+day is greater than or equal the selected period start or less than the selected end month and day.
		- Example: This can be used To setup a period starting from 12th of November to 20th of February.

		All constraints are additive. Pleas careful to that, that means it is possible to setup a rule which never would be used.

		## Samples

		For examples, please see [blind control](blind_control.md). The clock-timer node is very similar to the blind-control node.

		## Other
		@@ -195,0 +269,0 @@

nodes/clock-timer.js

		@@ -79,4 +79,4 @@ /********************************************
		*/
		function setExpiringOverwrite(node, dNow, expire) {
		node.debug(`setExpiringOverwrite now=${dNow}, expire=${expire}`);
		function setExpiringOverwrite(node, dNow, expire, reason) {
		node.debug(`setExpiringOverwrite now=${dNow}, expire=${expire}, reason=${reason}`);
		if (node.timeOutObj) {
		@@ -94,3 +94,4 @@ clearTimeout(node.timeOutObj);
		if (!node.timeClockData.overwrite.expires) {
		node.debug(`expireNever expire=${expire} ${ typeof expire } - isNaN=${ isNaN(expire) } - finite=${ !isFinite(expire) } - min=${ expire < 100}`);
		node.log(`Overwrite is set which never expire (${reason})`);
		node.debug(`expireNever expire=${expire}ms ${ typeof expire } - isNaN=${ isNaN(expire) } - finite=${ !isFinite(expire) } - min=${ expire < 100}`);
		delete node.timeClockData.overwrite.expireTs;
		@@ -107,5 +108,5 @@ delete node.timeClockData.overwrite.expireDate;

		node.debug(`expires in ${expire}ms = ${node.timeClockData.overwrite.expireDate}`);
		node.log(`Overwrite is set which expires in ${expire}ms = ${node.blindData.overwrite.expireDateISO} (${reason})`);
		node.timeOutObj = setTimeout(() => {
		node.debug('timeout - overwrite expired');
		node.log(`Overwrite is expired (timeout)`);
		timePosOverwriteReset(node);
		@@ -126,2 +127,3 @@ node.emit('input', { payload: -1, topic: 'internal-triggerOnly-overwriteExpired', force: false });
		(node.timeClockData.overwrite.expireTs < dNow.getTime())) {
		node.log(`Overwrite is expired (trigger)`);
		timePosOverwriteReset(node);
		@@ -134,2 +136,5 @@ }
		if (val) {
		if (node.blindData.overwrite && node.blindData.overwrite.active) {
		node.log(`Overwrite reset by incoming message`);
		}
		timePosOverwriteReset(node);
		@@ -214,3 +219,3 @@ }
		// set to new expiring time
		setExpiringOverwrite(node, now, expire);
		setExpiringOverwrite(node, now, expire, 'set new expiring time by message');
		}
		@@ -234,7 +239,7 @@ if (prio > 0) {
		// will set expiring if prio is 0 or if expire is explizit defined
		setExpiringOverwrite(node, now, expire);
		setExpiringOverwrite(node, now, expire, 'set expiring time by message');
		} else if ((!prioMustEqual && (node.timeClockData.overwrite.priority < prio)) \|\| (!node.timeClockData.overwrite.expireTs)) {
		// priook
		// no expiring on prio change or no existing expiring
		setExpiringOverwrite(node, now, -1);
		setExpiringOverwrite(node, now, -1, 'no expire defined');
		}
		@@ -675,4 +680,4 @@ if (prio > 0) {
		node.payload = {
		current:undefined,
		topic:node.timeClockData.topic
		current: undefined,
		topic: node.timeClockData.topic
		};
		@@ -960,5 +965,5 @@
		rule.timeDateEnd = new Date(rule.timeDateEnd);
		rule.timeDateStart.setHours(23, 59, 59, 999);
		rule.timeDateEnd.setHours(23, 59, 59, 999);
		} else {
		rule.timeDateStart = new Date(2000,11,31, 23, 59, 59, 999);
		rule.timeDateEnd = new Date(2000,11,31, 23, 59, 59, 999);
		}
		@@ -965,0 +970,0 @@ }

nodes/locales/en-US/blind-control.json

		@@ -49,2 +49,3 @@ {
		"sunMinDelta": "min delta",
		"sunTopic": "Topic 🌞/⛄",
		"time": "time",
		@@ -61,2 +62,3 @@ "name": "name",
		"oversteer3BlindPos": "blind position",
		"oversteerTopic":"oversteer topic",
		"smoothTime": "smoothTime",
		@@ -86,3 +88,5 @@ "showEnhSettings": "Enhanced settings",
		"onlyEvenDays": "only even days",
		"onlyOddDays": "only odd days"
		"onlyOddDays": "only odd days",
		"editRule": "edit the rule",
		"duplicateRule": "duplicate the rule"
		},
		@@ -119,2 +123,5 @@ "placeholder": {
		"level": "level",
		"ruleTopic":"allows to define a seperate topic for outgoing message per rule, if not defined default topic will be used",
		"sunTopic": "allows to define a seperate topic for outgoing message if level is set by sun control, if not defined default topic will be used",
		"oversteerTopic":"allows to define a seperate topic for outgoing message if level is set by sun control oversteer, if not defined default topic of sun Control will be used",
		"ruleTimeDays": "select days wherefore it should be valid",
		@@ -121,0 +128,0 @@ "ruleTimeMonths": "select months wherefore it should be valid",

nodes/locales/en-US/clock-timer.json

		@@ -56,3 +56,5 @@ {
		"onlyEvenDays": "only even days",
		"onlyOddDays": "only odd days"
		"onlyOddDays": "only odd days",
		"editRule": "edit the rule",
		"duplicateRule": "duplicate the rule"
		},
		@@ -73,3 +75,3 @@ "placeholder": {
		"offset": "time offset",
		"level": "level",
		"ruleTopic": "allows to define a seperate topic for outgoing message per rule, if not defined default topic will be used",
		"ruleTimeDays": "select days wherefore it should be valid",
		@@ -76,0 +78,0 @@ "ruleTimeMonths": "select months wherefore it should be valid",

nodes/locales/en-US/time-inject.json

		@@ -7,3 +7,7 @@ {
		"time": "Time",
		"timeStart": "Time start",
		"timeEnd": "Time end",
		"timeOffset": "Offset",
		"timeStartOffset": "Start Offset",
		"timeEndOffset": "End Offset",
		"timeAlt": "Alternate time",
		@@ -43,3 +47,5 @@ "timeAltOffset": "Offset",
		"fewDays": "few days",
		"fewMonths": "few months"
		"fewMonths": "few months",
		"between":"between",
		"and":"and"
		},
		@@ -46,0 +52,0 @@ "placeholder": {

nodes/static/htmlglobal.js

		@@ -249,3 +249,3 @@ /************************************************************************/
		randomNumber: {
		value: 'random',
		value: 'randomNum',
		label: node._('node-red-contrib-sun-position/position-config:common.types.randomNumber','randomNumber'),
		@@ -252,0 +252,0 @@ icon: 'icons/node-red-contrib-sun-position/inputTypeRandomNumber.png',

package.json

		{
		"name": "node-red-contrib-sun-position",
		"version": "1.0.11",
		"version": "1.0.12",
		"description": "NodeRED nodes to get sun and moon position",
		@@ -5,0 +5,0 @@ "keywords": [

blind_control.md