Node-red module for energenie ENER314-RT board for raspberry pi
npm install node-red-contrib-energenie-ener314rtgpiod and libgpiod first (see Getting Started below).
gpiod and libgpiod dependencies (as of v0.7.x) :
sudo apt-get install gpiod libgpiod-dev
`
3) Install this module as you would any node-red module using the 'Manage palette' option in Node-Red GUI or by using npm.
4) If you have any 'Control' only devices, perform a one-time only setup to teach your devices to operate with your selected zone code(s) switch number(s) combinations:
* Drag a blue node onto the canvas
* Open the node by double clicking
* If required, add a board config (only done once for all devices), by clicking pencil next to board, and then clicking 'add'
* Set the parameters in the Control node that you wish to uniquely reference your device (following the zone rules below).
* You can test the zone/device combination by clicking the learn button to switch on the device, or continue these steps to 'teach' your device
* Hold the button on your device until it starts to flash.
* Click the teach (mortar board) icon in the control node properties.
* The device should learn the zone code being broadcast by the teach request, the light should stop flashing when successful.
* All subsequent calls using the same zone/switch number will cause your device to switch.
* Pressing the teach button again will cause the device to switch on, and pressing the 'power' button will cause the same device to switch off.
> TIP: Usually each energenie 'Control' only devices can be assigned 2 separate zone codes, so you could operate them across this and another system (e.g RF hand controller). There is one downside though, in that the on/off state will not be reflected on the other system for these devices.
5) If you have any 'Monitor' or 'Control & Monitor' devices perform one-time only setup to discover the devices
* Drag the appropriate pink or purple node onto the canvas (see Supported Devices table below, if you are unsure which one to use)
* Open the node by double clicking
* If required, add a board config (only done once for all devices), by clicking pencil next to board, and then clicking 'add'
* Click 'pencil' icon to add a new device
* The device config node will open and perform an auto-scan; after 10 seconds it returns a list of devices that it has found. If your device is not found you can force it to transmit a 'join' request by holding the button on the device for 5 seconds. You can click the search button as many times as you like if the device is not found. If you find that it is still not working, please raise a bug request.
* Select the device in the 'Devices' drop down
* The Product name, ID and type will populate
* (Optional) Change the 'Name' of the device if desired
* Click 'Add' to finish configuration of the device
* Click 'Done'
Hardware based SPI driver - NEW In Version 0.6
To increase reliability a new hardware SPI driver has been added. The hardware SPI driver version can be enabled using sudo raspi-config choosing Interface Options and SPI to enable the hardware SPI mode, do this whilst this software is not running. The module tries to use the hardware driver on start-up, if it has not been enabled it falls back to using the software SPI driver.
'Control Only' OOK Zone Rules
* Each Energenie 'Control' or OOK based device can be assigned to a specific zone (or house code) and a switch number.
* Each zone is encoded as a 20-bit address (1-1048575 decimal).
* Each zone can contain up to 6 switches (1-6) - NOTE: officially energenie state this is only 4 devices (1-4)
* All devices within the same zone can be switched at the same time using a switch number of '0'.
* A default zone '0' can be used to use Energenie's default zone (0x6C6C6).
* If you have a MiHome 4 gang Multi-plug, the same zone must be used for controlling all 4 switches, use switch #0 to control all, 1-4 for each socket
* If you have a MiHome 2 gang socket or light switch, the same zone must be used for controlling the 2 switches
Light Dimmer Support
Each Energenie Light Dimmer requires a dedicated OOK zone allocating to it, as internally it uses the switch numbers to set the brightness level of the dimmer. This node works slightly differently to the standard 'Control' node. The payload determines the light level required as follows:
|payload|Brightness Level|Action|
|:---:|:---:|---|
|0 OR false|OFF|Switch light off, remembering light level|
|1 OR true|last|Switch on at the previous light level set|
|2 or 20|20%|Switch light on at 20%|
|3 or 30|30%|Switch light on at 30%|
|4 or 40|40%|Switch light on at 40%|
|5 or 60|60%|Switch light on at 60%|
|6 or 80|80%|Switch light on at 80%|
|7 or 100|100%|Switch light on at 100%|
Processing Monitor Messages
The Pink and Purple nodes receive monitoring information from the devices and emit the received parameter values on their output. These messages conform to the OpenThings parameter standard.
All OpenThings parameters received from the device are decoded and returned in the `msg.payload`. Some of the values are used to set the node.status for the specific nodes, for example SWITCH_STATE is used to indicate if a device is 'ON' or 'OFF', and the TEMPERATURE value is used on the eTRV node to show the current temperature.
Some example `msg.payload`s are shown below. I have provided parameter name and type mapping for the known values for received messages. Connect up a debug node to see what your specific devices output.
A full parameter list can be found in C/src/achronite/openThings.c if required.
$3
Every 10 seconds:
`
deviceId:
mfrId: 4
productId: 2
timestamp:
REAL_POWER:
REACTIVE_POWER:
VOLTAGE:
FREQUENCY:
SWITCH_STATE: `
$3
`
deviceId:
mfrId: 4
productId: 5
timestamp:
APPARENT_POWER: 612
VOLTAGE: 4.566406
CURRENT: 2.179688
`
$3
`
deviceId:
mfrId: 4
productId: 12
timestamp:
MOTION_DETECTOR:
`
$3
`
deviceId:
mfrId: 4
productId: 13
timestamp:
DOOR_SENSOR:
`
$3
`
deviceId:
mfrId: 4
productId: 18
timestamp:
TEMPERATURE: 23.06
REL_HUMIDITY: 72
BATTERY_LEVEL: 3.08
MOTION_DETECTOR:
THERMOSTAT_MODE:
TARGET_TEMP:
SWITCH_STATE:
`
$3
`
deviceId:
mfrId: 4
productId: 19
timestamp:
VOLTAGE:
BUTTON: <1=Single press, 2=Double press, 255=long press>
`
MiHome Heating Device Support
The MiHome Thermostatic Radiator valve (eTRV) and MiHome Thermostat are battery powered devices that do not constantly listen for commands. This required specific code to be written to 'cache' commands for these devices. As a result there may be a delay from when a command is sent to it being processed by the device. See Command Caching below.
$3
Single commands are sent as a numeric value within a JSON request as shown in the tables below. For example to Request Diagnostics you can use a template node (Output as Parsed JSON) to send the following `msg.payload`:
`
{
"command": 226,
"data": 0
}
`
Example for setting temperature to 20C using command mode:
`
{
"command": 244,
"data": 20
}
`
#### eTRV Commands
The MiHome Thermostatic Radiator valve (eTRV) accepts commands to perform operations, provide diagnostics or perform self tests. The documented commands are provided in the table below, there may also be other undocumented commands.
| Command | # | Description | .data | Response Msg |
|---|:---:|---|---|:---:|
|CANCEL|0|Cancel existing cached command (set retries to 0)||Yes|
|EXERCISE_VALVE|163|Send exercise valve command, recommended once a week to calibrate eTRV||DIAGNOSTICS|
|SET_LOW_POWER_MODE|164|This is used to enhance battery life by limiting the hunting of the actuator, ie it limits small adjustments to degree of opening, when the room temperature is close to the TEMP_SET point. A consequence of the Low Power mode is that it may cause larger errors in controlling room temperature to the set temperature.|0=Off
1=On|No*|
|SET_VALVE_STATE|165|Set valve state|0=Open
1=Closed
2=Auto (default)|No|
|REQUEST_DIAGNOSTICS|166|Request diagnostic data from device, if all is OK it will return 0. Otherwise see additional monitored values for status messages||DIAGNOSTICS|
|IDENTIFY|191|Identify the device by making the green light flash on the selected eTRV for 60 seconds||No|
|SET_REPORTING_INTERVAL|210|Update reporting interval to requested value|300-3600 seconds|No|
|REQUEST_VOLTAGE|226|Report current voltage of the batteries||VOLTAGE|
|TARGET_TEMP|244|Send new target temperature for eTRV in 0.5 increments.
NOTE: The VALVE_STATE must be set to 'Auto' for this to work.|int|No|
> \ Although this will not auto-report, a subsequent call to REQUEST_DIAGNOSTICS will confirm the LOW_POWER_MODE* setting
#### Thermostat Commands
The MiHome Thermostat accepts the following commands to perform operations.
> WARNING: If you are using a MiHome gateway to control your thermostat command clash may occur by issuing command within node-red.
| Command | # | Description | .data | Tested |
|---|:---:|---|---|:---:|
|CANCEL|0|Cancel existing cached command (set retries to 0)||Yes|
|THERMOSTAT_MODE|170|Change mode of thermostat where
0 = OFF
1 = Temp Controlled
2 = ON|0-2|Yes|
|RELAY_POLARITY|171|Polarity of the boiler relay|0=Normally Open,1=Normally Closed|Yes|
|HUMID_OFFSET|186|Humidity Calibration|-20 to 20|Yes|
|TEMP_OFFSET|189|Temperature Calibration|-20.0 to 20.0|Yes||TARGET_TEMP|244|Send new target temperature for thermostat (0-30) in 0.5 increments.
NOTE: The THERMOSTAT_MODE must be set to '1' for this to work.|5-30|Yes|
|HYSTERESIS|254|The difference between the current temperature and target temperature before the thermostat triggers|0.5-10|Yes|
In order for the Thermostat to provide updates for it's telemetry data when used without a MiHome gateway, auto messaging has been enabled within this module. To start this auto-messaging you will need to send a command that returns the THERMOSTAT_MODE to the application (a THERMOSTAT_MODE command will do). The result of the most recent THERMOSTAT_MODE value will be stored and periodically replayed (until a restart) to prompt the thermostat into providing it's telemetry data.
$3
Battery powered energenie devices, such as the eTRV or Room Thermostat do not constantly listen for commands. For example, the eTRV reports its temperature at the SET_REPORTING_INTERVAL (default 5 minutes) after which the receiver is then activated to listen for commands. The receiver only remains active for 200ms or until a message is received.
To cater for these hardware limitations the 'eTRV' and 'Thermostat' nodes use command caching and dynamic polling. Any command sent using these nodes will be held until a TEMPERATURE (for eTRV) or WAKEUP (for Thermostat) message is received; at this point the most recent cached message (only 1 is supported) will be sent to the device. Messages will continue to be resent until they have been successful received or until the number of retries has reached 0.
Sometimes a specific command may be resent multiple times. This is particularly a problem for the eTRV devices, as they do not send an acknowledgement for every command type (indicated by a 'No' in the Response column in the above table). This includes the TEMP_SET command! So these commands are always resent for the full number of retries. NEW v0.6.x - When a device has acknowledged a command the 'command' and 'retries' topics are reset to 0.
Be careful when sending multiple commands to the same device, as the most recent command will overwrite any existing cached command for that device (check the retries is 0 first).
> NOTE: The performance of node-red may decrease when a command is cached due to dynamic polling. The frequency that the radio device is polled by the monitor thread automatically increases by a factor of 200 when a command is cached (it goes from checking every 0.5 seconds to every 25 milliseconds) this dramatically increases the chance of a message being correctly received by the device sooner.
$3
To support the MiHome Radiator Valve (MIHO013) aka 'eTRV' in v0.3 and above, additional code has been added to store the received and set information for these devices. An example of the values are shown below, only 'known' values are returned when the eTRV regularly reports the TEMPERATURE. See table for types and determining when field was last updated:
`
{
"deviceId":3989,
"mfrId":4,
"productId":3,
"timestamp":1567932119,
"TEMPERATURE":19.7,
"EXERCISE_VALVE":"success",
"VALVE_TS":1567927343,
"DIAGNOSTICS":512,
"DIAGNOSTICS_TS":1567927343,
"LOW_POWER_MODE":false,
"TARGET_TEMP": 10,
"VOLTAGE": 3.19,
"VOLTAGE_TS": 1568036414,
"ERRORS": true,
"ERROR_TEXT": ...
}
``