EQ-3 radiator valves work really well for a home-automation heating system. They are fully configurable vie BLE as well as their front-panel. There are more features on the valves than the calorBT app makes available.
The main problem with centrally controlling EQ-3 valves is the limited range of BLE. This makes it impossible to use a single central-controller to talk to all TRVs in a typical house. Therefore multiple 'hubs' are required at distributed locations.
This application acts as a hub and uses BLE to communicate with EQ-3 TRVs and makes configuration possible via MQTT over WiFi.
When using calorBT some very basic security is employed. This security however lives in the calorBT application and not in the valve. The EQ-3 valves do not require any authentication from the BLE client to obey commands.
To quickly flash the application to a ESP32, download the latest release from https://github.com/softypit/esp32_mqtt_eq3/releases and flash it via esptool, using esptool.py --chip esp32 --port /dev/ttyUSB0 --baud 115200 --before default_reset --after hard_reset write_flash -z --flash_mode dio --flash_freq 40m --flash_size detect 0xd000 ota_data_initial.bin 0x1000 bootloader.bin 0x10000 eq3_trv_control.bin 0x8000 partitions.bin in a Linux terminal with esptool installed.
On first use the ESP32 will start in access-point mode appearing as 'HeatingController'. Connect to this AP (password is 'password' or unset) and browse to the device IP address (192.168.4.1). The device configuration parameters can be set here:
| Parameter | Description | Examples |
|---|---|---|
| ssid | the AP to connect to for normal operation | |
| password | the password for the AP | |
| mqtturl | url to access the mqtt broker allowed values: - IP-Address, Hostname or Domainname only ("mqtt://" is used in this case) - URL with scheme mqtt, ws, wss, tco, ssl (only mqtt is tested yet) |
192.168.0.2 mqtt://192.168.0.2 ws://192.168.0.2 |
| mqttuser | mqtt broker username | |
| mqttpass | mqtt broker password | |
| mqttid | the unique id for this device to use with the mqtt broker (max 20 characters) | livingroom |
| ntp enabled | enable network time protocol support | |
| ntp server1 | url for ntp server | pool.ntp.org |
| ntp server2 | url for ntp server | europe.pool.ntp.org |
| timezone | timezone in TZ format | GMT0BST,M3.5.0/2,M11.5.0/2 |
| ip | fixed IP for WiFi network (leave blank to DHCP) | |
| gw | gateway IP for WiFi network (leave blank for DHCP) | |
| netmask | netmask for WiFi network (leave blank for DHCP) | |
| DNS server1 | url for ntp server | 8.8.8.8 |
| DNS server2 | url for ntp server | 4.4.4.4 |
Once the ESP32 is running in client mode the configuration page can be accessed on the webserver at /config
The application can be forced into config mode by pressing and holding the BOOT key AFTER the EN key has been released.
Once connected in WiFi STA mode this application first scans for EQ-3 valves and publishes their addresses and rssi to the MQTT broker.
A scan can be initiated at any time by publishing to the /<mqttid>radin/scan topic.
Scan results are published to /<mqttid>radout/devlist in json format.
Control of valves is carried out by publishing to the /<mqttid>radin/trv topic with a payload consisting of:
ab:cd:ef:gh:ij:kl <command> [parm]
where the device is indicated by its bluetooth address (MAC)
| Parameter | Description | Parameters | Examples | Stable since |
|---|---|---|---|---|
| settime | sets the current time on the valve | settime has an optional parameter of the hexadecimal encoded current time. parm is 12 characters hexadecimal yymmddhhMMss (e.g. 13010c0c0a00 is 2019/Jan/12 12:00.00) if no parameter is submitted and ntp is enabled the ntp time (with timezone offset) will be used |
/<mqttid>radin/trv <eq-3-address> settemp 13010c0c0a00/livingroomradin/trv ab:cd:ef:gh:ij:kl settemp 13010c0c0a00 |
v1.20 |
| boost | sets the boost mode | -none - | /<mqttid>radin/trv <eq-3-address> boost/livingroomradin/trv ab:cd:ef:gh:ij:kl boost |
v1.20 |
| unboost | reset to unboost mode | -none - | /<mqttid>radin/trv <eq-3-address> unboost/livingroomradin/trv ab:cd:ef:gh:ij:kl unboost |
v1.20 |
| lock | locks the front-panel controls | -none - | /<mqttid>radin/trv <eq-3-address> lock/livingroomradin/trv ab:cd:ef:gh:ij:kl lock |
v1.20 |
| unlock | release the lock for the front-panel controls | -none - | /<mqttid>radin/trv <eq-3-address> unlock/livingroomradin/trv ab:cd:ef:gh:ij:kl unlock |
v1.20 |
| auto | enables the internal temperature/time program | -none - | /<mqttid>radin/trv <eq-3-address> auto/livingroomradin/trv ab:cd:ef:gh:ij:kl auto |
v1.20 |
| manual | disables the internal temperature/time program | -none - | /<mqttid>radin/trv <eq-3-address> manual/livingroomradin/trv ab:cd:ef:gh:ij:kl manual |
v1.20 |
| offset | sets the room-temperature offset | the temperature to set, this can be -3.5 - +3.5 in 0.5 degree increments | /<mqttid>radin/trv <eq-3-address> offset 3.5/livingroomradin/trv ab:cd:ef:gh:ij:kl offset 3.5 |
v1.20 |
| settemp | sets the required temperature for the valve to open/close at | the temperature to set, this can be 5.0 to 29.5 in 0.5 degree increments | /<mqttid>radin/trv <eq-3-address> settemp 20.0/livingroomradin/trv ab:cd:ef:gh:ij:kl settemp 20.0 |
v1.20 |
| on | opens the valve fully (lcd display 'on') | -none - | /<mqttid>radin/trv <eq3-address> on/livingroomradin/trv ab:cd:ef:gh:ij:kl on |
v1.49 |
| off | closes the valve fully (lcd display 'off') | -none - | /<mqttid>radin/trv <eq3-address> off/livingroomradin/trv ab:cd:ef:gh:ij:kl off |
v1.49 |
In response to every successful command a status message is published to /<mqttid>radout/status containing json-encoded details of address, temperature set point, valve open percentage, mode, boost state, lock state and battery state.
This can be used as an acknowledgement of a successful command to remote mqtt clients.
| Key | Description | Exampls | Since Version |
|---|---|---|---|
| trv | Bluetooth-Address of the corresponding thermostat | "trv":"ab:cd:ef:gh:ij:kl" |
1.20 |
| temp | the current target room-temperature is set | "temp":"20.0" |
1.20 |
| offsetTemp | the current offset temperature is set | "offsetTemp":"0.0" |
1.30 (upstream merge in dev) |
| mode | the current thermostate programm mode"auto" = internal temperature/time program is used"manual" = internal temperature/time program is disabled"holiday" = holiday mode is used |
"mode":"auto""mode":"manual""mode":"holiday" |
1.20 1) |
| boost | boost-mode is active / inactiv | "boost":"active""boost":"inactive" |
1.20 |
| state | front-panel controls are locked / unlocked | "state":"locked""state":"unlocked" |
1.20 |
| battery | battery state | "battery":"GOOD""battery":"LOW" |
1.20 |
| window | window-mode is active / inactive | "window":"open""window":"closed" |
There is no specific command to poll the status of the valve but using any of the commands to re-set the current value will achieve the required result.
Note: It has been observed that using unboost to poll a valve can result in the valve opening as if in boost mode but without reporting boost mode active on the display or status. It is probably not advisable to poll the valve with the unboost command.
| Key | Description | published | subscriped |
|---|---|---|---|
/<mqttid>radout/devlist |
list of available bluetooth devices | X | |
/<mqttid>radout/status |
show a status message each time a trv is contacted | X | |
/<mqttid>radin/trv <command> [param] |
sends a command to the trv | X | |
/<mqttid>radin/scan |
scan for available bluetooth devices | X |
When running in client mode the ESP32 presents a web interface that can be used to control TRVs and administer the EQ3-mqtt application. Software OTA feature can be used to apply new software binary files available in future without the need for usb/serial connection.
On first boot this application uses Kolbans bootwifi code to create the wifi AP.
Once configuration is complete and on subsequent boots the configured details are used for connection. If connection fails the application reverts to AP mode where the web interface is used to reconfigure.
web server is part of Mongoose - https://github.com/cesanta/mongoose
# Connect to a mosquitto broker:
mosquitto_sub -h 127.0.0.1 -p 1883 -t "<mqttid>radout/devlist" # Will display a list of discovered EQ-3 TRVs
mosquitto_sub -h 127.0.0.1 -p 1883 -t "<mqttid>radout/status" # will show a status message each time a trv is contacted
mosquitto_pub -h 127.0.0.1 -p 1883 -t "<mqttid>radin/trv" -m "ab:cd:ef:gh:ij:kl settemp 20.0" # Sets trv temp to 20 degrees
possible incomplete list because of rebranding eq-3 thermostats
| Name | Model Name | Factory | Factory Model Number | Remark | Verified |
|---|---|---|---|---|---|
| Eqiva eQ-3 Bluetooth Smart 2) | CC-RT-BLE-EQ | EQIVA | 141771E0 / 141771E0A | X | |
| Eqiva eQ-3 Bluetooth Smart (UK Version) 2) | CC-RT-M-BLE | EQIVA | 142461D0 | 1) | |
| Eqiva eQ-3 Bluetooth Smart 2) | EQIVA | 141771A1A | in the sale | 1) | |
| Eqiva eQ-3 Bluetooth Smart 2) | CC-RT-M-BLE | EQIVA | 142461A0 | discontinued sales | X |
| EHT CLASSIC MBLE (UK Version) | CC-RT-M-BLE | EQIVA | 142461D0 | 1) | |
| EHT CLASSIC MBLE (UK Version) | CC-RT-M-BLE | EQIVA | 142461A0 | discontinued sales | 1) |
| SmartBlue Bluetooth | 1) |
1) Used the same calor BT-App, so this should work out of the box
2) Many aliases for "Eqiva eQ-3 Bluetooth Smart" devices exists. Most of all are characterized by a combination of "Eqiva", "eQ-3", "Bluetooth", "Smart".
e.g. "eQ-3 AG Eqiva BLUETOOTH® Smart", "eqiva Bluetooth Smart Radiator Thermostat", "eQ-3 eqiva Heizkörperthermostat Typ N", "Eqiva Bluetooth Smart"
Don't buy Models without Bluetooth logo. They won't work with this "hub". e.g. "Eqiva Model N, 132231K0A"
- Paul (@softypit)
- @ul-gh
- Peter Becker (@floyddotnet)
version 1.6 has been ported to use ESP IDF 4.3.1 and Mongoose Embedded Networking Library 7.4. Various tweaks and bugfixes have been applied including addition of two DNS servers for use in fixed-IP mode and a second NTP server. A timeout has been added to BLE operations to attempt to prevent the 'freeze-up' experienced occasionally on previous versions.
menuconfig options allow setting of some parameters at compile time.
- The boot-mode GPIO pin (normally a button on GPIO 0 on many ESP32 platforms) used to force the device into AP mode at boot.
- Status LED GPIO which indicates if the device is in AP mode.
- Password for AP mode (enables WPA2PSK) to prevent unwanted access should the device go into AP mode when it is unable to connect to its configured Access Point.