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 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.

Table of Contents

• Description
  • Configuration
    • Reset configuration
  • Determine EQ-3 addresses
  • Supported commands
  • JSON-Format of status topic
  • Read current status
  • MQTT Topics
  • Web interface
• 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:

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

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

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

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

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

¹⁾ 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)

Notes

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.

Compiling

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.