EQ-3 Radiator valve control application for ESP-32

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 options available than the calorBT app makes available.

The main problem with centrally controlling them 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.

Description
Usage Summary
Developer notes
Testing
Supported Models
Credits

Description

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.

Configuration

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 server	url for ntp server	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)

Once the ESP32 is running in client mode the configuration page can be accessed on the webserver at /config

Reset configuration

The application can be forced into config mode by pressing and holding the BOOT key AFTER the EN key has been released.

Determine EQ-3 addresses

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)

Supported commands

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> offset 20.0` `/livingroomradin/trv ab:cd:ef:gh:ij:kl settemp 20.0`	v1.20

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.

JSON-Format of status topic

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 ¹⁾
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"`

Read current status

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.

MQTT Topics

Key	Description	published	subscriped
`/<mqttid>radout/devlist`	list of avalibile 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

Web interface

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.

Usage Summary

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.

Developer notes

web server is part of Mongoose - https://github.com/cesanta/mongoose
~~MQTT library is https://github.com/tuanpmt/espmqtt~~

Testing

# 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

Supported Models

possible incomplete list because of rebranding eq-3 thermostats

Name	Model Name	Factory	Factory Model Number	Remark	Verified
Eqiva eQ-3 Bluetooth Smart ²⁾	CC-RT-BLE-EQ	EQIVA	141771E0 / 141771E0A		X
Eqiva eQ-3 Bluetooth Smart (UK Version) ²⁾	CC-RT-M-BLE	EQIVA	142461D0		¹⁾
Eqiva eQ-3 Bluetooth Smart ²⁾		EQIVA	141771A1A	in the sale	¹⁾
Eqiva eQ-3 Bluetooth Smart ²⁾	CC-RT-M-BLE	EQIVA	142461A0	discontinued sales	X
EHT CLASSIC MBLE (UK Version)	CC-RT-M-BLE	EQIVA	142461D0		¹⁾
EHT CLASSIC MBLE (UK Version)	CC-RT-M-BLE	EQIVA	142461A0	discontinued sales	¹⁾
SmartBlue Bluetooth					¹⁾

¹⁾ Used the same calor BT-App, so this should work out of the box

²⁾ 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"

Credits

Based on the amazing work of the ESP-IDF project
and the reverse engineering of @Heckie75

Source and continuative reverse engineering by

Paul (@softypit)
@ul-gh
Peter Becker (@floyddotnet)

lhanneus/esp32_mqtt_eq3