node-red-contrib-sun-position
Version:
NodeRED nodes to get sun and moon position
194 lines (168 loc) • 11.4 kB
HTML
<script type="text/html" data-help-name="blind-control">
<h3>About</h3>
<p>Used to control a blind with many possibilities. This can be time-dependent and it can calculate the blind position based on the current position of the sun to limit the sun light To limit the sunlight on the floor of a window.</p>
<p>Please see in <a href="https://github.com/rdmtc/node-red-contrib-sun-position/wiki/blind-control">the full Documentation of the Node</a> for more information.</p>
<h3>Inputs</h3>
The Input is for triggering the calculation and for setting overwrites of the blind position.
<dl class="message-properties">
<dt>payload
<span class="property-type">string | object</span>
</dt>
<dd> the payload of the message. Could be an object.</dd>
<dt class="optional">topic <span class="property-type">string</span></dt>
<dd> .</dd>
<dt class="optional">reset <span class="property-type">boolean</span></dt>
<dd> if <b>true</b> will reset any manual override (can be as <code>msg.reset</code> or <code>msg.payload.reset</code>) </dd>
<dt class="optional">position <span class="property-type">number</span></dt>
<dd> will override any of rule/sun/.. based level of the blind (can be as <code>msg.position</code> or <code>msg.payload.position</code>) </dd>
<dt class="optional">priority <span class="property-type">number</span></dt>
<dd> priority of the override, <em>default is 0</em> (can be as <code>msg.priority</code> or <code>msg.payload.priority</code>) </dd>
<dt class="optional">expire <span class="property-type">number</span></dt>
<dd> time in milliseconds when the override should be expire (can be as <code>msg.expire</code> or <code>msg.payload.expire</code>) </dd>
</dl>
<h3>Outputs</h3>
<p>It is configurable if the node will have one or two outputs.</p>
<ol class="node-ports">
<li>first output
<dl class="message-properties">
<dt>payload <span class="property-type">number</span></dt>
<dd>the new blind position</dd>
<dt>topic <span class="property-type">string</span></dt>
<dd>the defined topic</dd>
<dt>blindCtrl <span class="property-type">object</span></dt>
<dd>(optional) the object containing additional information about the blind position</dd>
</dl>
</li>
<li>second output - only available if configured
<dl class="message-properties">
<dt>payload <span class="property-type">object</span></dt>
<dd>the object containing additional information about the blind position</dd>
<dt>topic <span class="property-type">string</span></dt>
<dd>the defined topic</dd>
</dl>
</li>
</ol>
<h3>additional blind control object properties</h3>
<dl class="message-properties">
<dt>reason.code <span class="property-type">number</span></dt>
<dd> the reason for the blind position
<ol>
<li>defined default blind position, because no other rule/condition/behavior</li>
<li>manual override</li>
<li>manual override - expiring</li>
<li>based blind position based by rule</li>
<li>calculated blind position by sun control is below defined minimum blind position (minimum blind position used)</li>
<li>calculated blind position by sun control is above defined maximum blind position (maximum blind position used)</li>
<li>Sun below altitude threshold</li>
<li>Sun is not in window, default blind position is used</li>
<li>blind position calculated by sun position</li>
<li>defined oversteer condition applies</li>
<li>(enhanced settings) blind position calculated by sun position was not used caused by smooth settings</li>
<li>sun is in window (maximize mode), max blind position used</li>
<li>sun is not in window (maximize mode), min blind position used</li>
</ol>
<dt>reason.state <span class="property-type">string</span></dt>
<dd> a short text (same as node status text) representing the reason for the blind position</dd>
<dt>reason.description <span class="property-type">string</span></dt>
<dd> a text representing the reason for the blind position</dd>
<dt>reason.blind.level <span class="property-type">number</span></dt>
<dd> the new blind level (numeric value) - equal to <em>msg.payload</em> of the first output message</dd>
<dt>reason.blind.levelInverse<span class="property-type">number</span></dt>
<dd> if <em>blindCtrl.blind.overwrite.active</em> is true, the value of <em>blindCtrl.blind.levelInverse</em> will be equal to the value of <em>blindCtrl.blind.level</em>, otherwise it will be the inverse to <em>blindCtrl.blind.level</em>. This means if <em>blindCtrl.blind.level</em> indicates how much the blind is open, then <em>blindCtrl.blind.levelInverse</em> indicates how much the blind is closed. So if <em>blindCtrl.blind.level</em> is equal to <b>min position</b>, <em>blindCtrl.blind.levelInverse</em> will be <b>max position</b>.</dd>
<dt>reason.blind.overwrite.active <span class="property-type">boolean</span></dt>
<dd> is <code>true</code> when overwrite is active, otherwise <code>false</code></dd>
<dt>reason.blind.overwrite.priority <span class="property-type">number</span></dt>
<dd> the priority of the override</dd>
<dt>reason.blind.overwrite.expires <span class="property-type">number</span></dt>
<dd> (optional) is <code>true</code> when overwrite expires</dd>
<dt>reason.blind.overwrite.expireTs <span class="property-type">number</span></dt>
<dd> (optional) a timestamp (UNIX) when overwrite expiring</dd>
<dt>reason.blind.overwrite.expireDate <span class="property-type">Date | String</span></dt>
<dd> (optional) a timestamp (String) when overwrite expiring</dd>
<dt>reason.rule.active <span class="property-type">boolean</span></dt>
<dd> (optional) <code>true</code> if a rule applies</dd>
<dt>reason.rule.ruleId <span class="property-type">number</span></dt>
<dd> (optional) number of the rule who applies (is <code>-1</code> if no rule has applied - default blind position)</dd>
<dt>reason.rule.active <span class="property-type">boolean</span></dt>
<dd> (optional) <code>true</code> if a rule applies</dd>
<dt>reason.rule.conditional <span class="property-type">boolean</span></dt>
<dd> (optional) <code>true</code> if the rule has a condition</dd>
<dt>reason.rule.timeLimited <span class="property-type">boolean</span></dt>
<dd> (optional) <code>true</code> if the rule has a time</dd>
<dt>reason.sunPosition <span class="property-type">object</span></dt>
<dd> (optional) calculated sub-position data</dd>
<dt>reason.sunPosition.InWindow <span class="property-type">boolean</span></dt>
<dd> (optional) <code>true</code> if sun is in window</dd>
<dt>reason.sunPosition.oversteer <span class="property-type">object</span></dt>
<dd> (optional) object containing oversteer data</dd>
</dl>
<h3>Node-Status</h3>
<ul>
<li><span class="background-color:red;">red</span> - any error</li>
<li><span class="background-color:blue;">blue</span> - override active</li>
<li><span class="background-color:grey;">grey</span> - level by rule</li>
<li><span class="background-color:green;">green</span> - default value or sun not in window</li>
<li><span class="background-color:yellow;">yellow</span> - any other </li>
</ul>
<h3>rules</h3>
<p>The rules are not easy to understand.</p>
<p>There are basically 4 types of rules:</p>
<ol>
<li>absolute rule<ul>
<li>a rule with no time and no condition will be absolute. If such a rule is the first rule, no other rule will be active, no sun control will be done</li>
<li>such rules not really makes sense</li>
</ul>
</li>
<li>a rule with a condition - conditional rule<ul>
<li>a rule with a condition will only be active if the condition matches, otherwise the rule will be ignored</li>
</ul>
</li>
<li>a rule with a given time - time rule<ul>
<li>time rules differ again in 2 ways<ul>
<li><strong>until</strong> time rules<ul>
<li>rules will be active from Midnight <strong>until</strong> the given time</li>
<li>the first matching <strong>until</strong> rule will be
considered</li>
</ul>
</li>
<li><strong>from</strong> time rules
<ul>
<li>rules will be active <strong>from</strong> given
time to Midnight</li>
<li>the last matching <strong>from</strong> rule will be
considered</li>
</ul>
</ul>
</li>
</ul>
</li>
<li>a rule with a condition and a given time<ul>
<li>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.
</li>
</ul>
</li>
</ol>
<p>a typically ruleset could be setup in a way like:</p>
<ol>
<li><strong>until</strong> absolute time (e.g. early morning 6:00) blind will be closed</li>
<li><strong>until</strong> sun rise time (e.g. sunrise) blind will be closed<ul>
<li>The previous absolute until rule (rule 1) will consider that the blind is closed, even if the sun rise time (this rule 2) is earlier than the time of rule 1.</li>
</ul>
</li>
<li><strong>from</strong> sun set time (e.g. sunset) blind will be closed</li>
<li><strong>from</strong> absolute time (e.g. late night 22:00) blind will be closed<ul>
<li>This rule 4 will be consider that the blind is closed, even if the sun set time (rule 3) is later than this absolute time.</li>
</ul>
</li>
</ol>
<p>In the time between the rule 2 (last until) and the rule 3 (first from rule) the blind will set to the default position which is setup normally to open. Only in this time the blind position can be controlled by sun.
This simple example could be enhanced with additional conditional rules. More examples could be find in the <a href="https://github.com/rdmtc/node-red-contrib-sun-position/wiki/blind-control">Documentation</a> at github. There is also a kind of simulator for testing the rules.</p>
<h3>References</h3>
<ul>
<li><a href="https://github.com/rdmtc/node-red-contrib-sun-position/wiki">Documentation Wiki</a></li>
<li><a href="https://github.com/rdmtc/node-red-contrib-sun-position/wiki/Base-Functions">Generic Functions, Parameter and more</a></li>
<li><a href="https://github.com/rdmtc/node-red-contrib-sun-position/wiki/blind-control">Documentation of the Node</a></li>
<li><a href="https://www.suncalc.org/">Suncalc</a></li>
<li><a href="https://github.com/rdmtc/node-red-contrib-sun-position">GitHub</a> - the nodes github repository</li>
</ul>
</script>