node-red-contrib-eq3-thermostat
Version:
Control Eqiva eQ-3 radiator thermostat
170 lines (166 loc) • 9.87 kB
HTML
<script type="text/javascript">
RED.nodes.registerType('Eqiva eQ-3', {
category: 'Heating',
color: '#e88000',
defaults: {
name: { value: "Eqiva eQ-3" },
mac: { value: "", validate: RED.validators.regex(/^(([0-9A-Fa-f]{2}[:]){5}([0-9A-Fa-f]{2}))$|^$/) },
interface: { value: "hci0", validate: RED.validators.regex(/^hci[0-9]+/) },
topic: { value: "" }
},
inputs: 1,
outputs: 1,
icon: "font-awesome/fa-thermometer-full",
label: function () {
return this.name || this.topic || "Eqiva eQ-3";
}
});
</script>
<script type="text/html" data-template-name="Eqiva eQ-3">
<div class="form-row">
<label for="node-input-name"><i class="fa fa-tag"></i>Name</label>
<input type="text" id="node-input-name" placeholder="Name">
</div>
<div class="form-row">
<label for="node-input-mac"><i class="fa fa-bluetooth"></i>MAC</label>
<input type="text" id="node-input-mac" placeholder="AA:BB:CC:DD:EE:FF">
</div>
<div class="form-row">
<label for="node-input-interface"><i class="fa fa-bluetooth"></i>Interface</label>
<input type="text" id="node-input-interface" placeholder="hci0">
</div>
<div class="form-row">
<label for="node-input-topic"><i class="fa fa-tag"></i>Topic</label>
<input type="text" id="node-input-topic" placeholder="If set overrides message topic">
</div>
</script>
<script type="text/html" data-help-name="Eqiva eQ-3">
<p>This node controls the Eqiva eQ-3 radiator Thermostat.</p>
<h3>Inputs</h3>
<dl class="message-properties">
<dt>payload
<span class="property-type">string</span>
</dt>
<dd> The command you want to send to thermostat. </dd>
<dt class="optional">mac <span class="property-type">string</span></dt>
<dd> The MAC of the EQ-3-Thermostat you want to control. If set it takes precedence of configured MAC in node properties. Format: AA:BB:CC:DD:EE:FF</dd>
<dt class="optional">interface<span class="property-type">string</span></dt>
<dd> The bluetooth interface you want to control the radiator thermostat with. If set it takes precedence of configured interface in node properties, example "hci1"</dd>
</dl>
<h3>Outputs</h3>
<ol class="node-ports">
<li>Return value of command
<dl class="message-properties">
<dt>payload <span class="property-type">JSON</span></dt>
<dd>The output of the command.</dd>
</dl>
</li></ol>
<h3>Details</h3>
<p><code>msg.payload</code> contains the commands you want to send to radiator thermostat.</p>
<p>Obtain the mac address of your thermostat(s) via an App like "nRF Connect" or use <code>sudo hcitool lescan</code>.</p>
<p>There seem to be 3 different firmware versions regarding Bluetooth connectivity</p>
<ol>
<li> Oldest version. Bluetooth is ready after thermostat is setup. You can directly use it with this script. This version does not provide additional information like offset temperature by a simple sync request.</li>
<li> After each battery insert you have to disable and re-enable bluetooth: Press left button (Mode Menu) for about 3 seconds. Turn control wheel until "bLE" is shown.
Press it shortly, then "OFF" will appear, press the wheel shortly again. This disables Bluetooth. Re-Do these steps, but now "ON" will appear. Press the wheel shortly again. This turns on Bluetooth.
<li> Latest version installed in January 2021 by update via App. With integrated bluetooth of Raspberry Pi 4 and Zero W you have to pair before you can control them. To do so go to commandline:
<pre>
sudo bluetoothctl
scan on
<wait until mac of new Eqiva EQ3 appears>
scan off
pair <MAC>
<Enter 6 digit number, getting by longpressing control wheel>
disconnect <MAC>
</pre>
Disconnecting is essential, otherwise bluetoothctl stays connected and you can't control the thermostat.
<p>With an external USB Bluetooth Receiver it was still possible to control the thermostat without pairing. So there is a false sense of security with new firmware.</p>
<p>With <code>paired-devices</code> in bluetoothctl you see all paired devices.</p>
<p>With <code>unpair <MAC></code> in bluetoothctl you can undo the pairing.</p>
</ol>
<p>This node uses the great eQ-3-radiator-thermostat API from Heckie75, see <a href="https://github.com/Heckie75/eQ-3-radiator-thermostat">
Github Heckie75/eQ-3-radiator-thermostat.</a></p>
<p>Node has a message buffer. That means all messages will be processed. So be careful and don't send too many messages. If you can't avoid this and commands may pile up, use a delay node before this node with a rate limit of 1 message every 30s (11s should be the minium). </p>
<p>Here are only the main commands listed, since Node-RED is intended for fully controlling your thermostats.
However you still can program all the settings via this node, like shedules, comfort and eco temperature and so on. Only aliases aren't officially supported, because for that you have to edit a file within Node-REDs directory structure. Because you can store some kind of aliases within msg.mac this feature wouldn't add much benefits when using inside Node-RED.
Please see API description from Github Heckie75/eQ-3-radiator-thermostat.</p>
<p>Send <code>sync</code> for getting current status and syncing time to thermostat <pre>
Target_temperature: 21
Valve: 12
Mode: array[2]
0: "manual"
1: "dst"
Vacation_mode: "off"
Comfort_temperature: 21
Eco_temperature: 17
Open_window_temperature: 16.5
Open_window_time: 0
Offset_temperature: 0
</pre>
</p>
<p>send <code>boost</code> for enabling boost function which means 5 minutes valve to 80 %.</p>
<p>send <code>boost off</code> for aborting boost function.</p>
<p>send <code>temp 21.5</code> for setting current temperature.</p>
<p>send <code>on</code> for turning thermostat permanently on (30 °C).</p>
<p>send <code>off</code> for turning it off (4.5 °C). Note: You can send <code>temp 1</code> for setting it even below those 4.5 °C.</p>
<p>send <code>manual</code> for manual control. This is the mode you probably want when controlling via Node-RED.</p>
<p>send <code>auto</code> for using the timers set in the radiator thermostat.</p>
<p>send <code>comfort</code> for setting target temperature to comfort temperature.</p>
<p>send <code>eco</code> for setting target temperature to eco temperature.</p>
<p>send <code>comforteco <comfort temperature> <eco temeperature></code> for setting comfort and eco temperature.</p>
<p>send <code>window 16.5 0:30</code> for setting window open mode. These values mean: Reduce target temperature to 16.5 °C for 30 minutes. <br/>Thermostat recognises
an open window by a fast drop of temperature. Maximum time of automatically reduced target temperature is 1 hour. If you set higher values time of reduced target temperature may be even shorter, watch the return value and output of <code>sync</code> command.
</p>
<p>send <code>offset <value from -3.5 to 3.5 in 0.5 °C steps></code> for setting an offset temperature. For example, you set your thermostat to 20 °C but your room thermometer displays only 18 °C.
Then send <code>offset -2</code>. If your thermometer displays 21 °C, send <code>offset 1</code>. Of course offset may vary depending on position of the radiator thermostat, outdoor temperature (especially in corners) and flow temperature.
The thermostat seems to have a correction algorithm for that. In my testroom temperature set on thermostat is quite accurate.
Now suppose we have 20 °C an offset 0. Now we set target temperature to 21 °C and valve opens to 44 %. So now setting target temperature of 20 °C but with an offset of -1 makes the thermostat think room has only 19 °C
and wants to heat up 1 °C more, so it should also heat to 21 °C. However in this testcase valve was closed completely. So use this feature carefully. Maybe on the longrun it works better.</p>
<p>send <code>lock</code> for locking thermostat.</p>
<p>send <code>unlock</code> for unlocking thermostat again.</p>
<p>Send <code>status</code> for getting the status including programmed timers, like
<pre>
object
mac: "AA:BB:CC:DD:EE:FF"
target_temperature: 21
valve: 12
mode: object
auto: false
manual: true
low battery: false
open window: false
vacation: false
locked: false
boost: false
unknown: false
dst: true
on: false
off: false
low_battery: false
open_window: false
vacation: null
comfort_temperature: 21
eco_temperature: 17
open_window_temperature: 16.5
open_window_time: "00:05"
offset_temperature: 0
timers: object
Sat: array[5]
Sun: array[5]
Mon: array[5]
Tue: array[5]
Wed: array[5]
Thu: array[5]
Fri: array[5]
Weekend: array[5]
Work: array[5]
</pre></p>
<p>In mode object you see "low battery" and "low_battery", same for open window. Original script uses space in key name.
However having the key without space makes it sometimes more easy to use this value.
So this is why these key/value pairs are included twice.</p>
<h3>References</h3>
<ul>
<li><a href="https://github.com/Heckie75/eQ-3-radiator-thermostat">Full API description</a></li>
<li><a href="https://github.com/JsBergbau/node-red-contrib-eq3-thermostat">GitHub</a> - the nodes github repository</li>
</ul>
</script>