ThermTerm: an open source heat pump controller and home automation terminal, built on ESP32
Control heat pumps manually or remotely via MQTT/Home Assistant.
I love my heat pumps. They're energy efficient and the fastest way to heat or cool any room.
But I've always hated the remote controls that come with heat pumps. They're clunky and hard to read, especially in low light. In theory, you can program schedules for your heat pumps, but in practice the remotes are too frustrating to use for that.
ThermTerm solves all the problems I've had with these physical controls, while integrating the heat pumps into Home Assistant via MQTT. Additional sensors pipe temperature, humidity and light data, for statistics and automation. Out of the box, ThermTerm supports Mitsubishi's infrared protocol, since that's the system I have. Thanks to integration with IRRemoteESP8266, you can make ThermTerm work with your own heat pumps by writing a few lines of adaptor code. No signal analysis or reverse-engineering required. See Customization for more details.
Note: you will need PlatformIO to get started.
Press the dial to toggle power.
Turn the dial to set temperature.
Change to heat mode with the bottom button, cool mode with the top. Set fan speed by pressing the center button, then turn the dial.
Through a TFT screen, readouts are visible any time of day. The chunky dial is easy to press without looking. Program automations using Home Assitant, not miserable rubber buttons like a VCR. Toggle your heat pumps from any room in the house, or even while you're away.
IRRemoteESP8266
, a library with bulletproof software-based PWM, a great API, and a shocking compendium of IR protocolsarduino-home-assistant
, an MQTT library with exhaustive implementations of Home Assistant-supported devicesThe sensors use I2C, so with a light rewrite, you can replace the above models with alternatives if needed, or skip them entirely if you don't care about recording data back to Home Assistant.
If you want to design your own enclosure and use a different display, I suspect any ESP32-based device will work fine.
There's not a huge upside to the battery in the current implementation but I designed the case to accommodate it for future enhancements. You can skip it unless you want to tinker with power outage-related home automation tasks.
Make a copy of _Credentials.h.example
, rename it to _Credentials.h
. This file will be ignored by git.
Fill in these values as appropriate to your network:
#define WIFI_SSID "" // your network SSID (name)
#define WIFI_PASSWORD "" // your network password
#define MQTT_LOGIN ""
#define MQTT_PASSWORD ""
#define MQTT_BROKER IPAddress(192, 168, 1, 100)
With correct MQTT credentials, ThermTerm should be discovered automatically in the Home Assistant MQTT configuration.
To troubleshoot, uncomment this line in platfomio.ini
:
build_flags = -D ARDUINOHA_DEBUG
This will log MQTT events and errors via serial.
The most urgent customization for most will be making this work with your own heat pump.
IRInterface
. You can use MistubishiInterface
as a starting point. The goal is to translate the system controller's state model into whatever features you care about for your own heat pump. Consult IRremoteESP8266 for the API that corresponds to your manufacturer.main.cpp
, replace the MitsubishiInterface
instance in the SystemController
constructor with your own interface: YourCustomInterface customInterface;
SystemController controller(customInterface);
That should get you moving.
To tweak other details about the device, explore _Constants.h
. To adapt this to alternative hardware, including other displays, you'll want to replace the implementations in src/hardware
.
If you want to go all-in and asemble one of these for yourself, 3D printing files have been provided. See ASSEMBLY.md for detailed instructions.
There's a lot more this platform could do, but this is the minimally-useful implementation that can get your whole heat pump system integrated in with an afternoon of work. Future features:
If you have anything useful you'd like to give back, feel free. Of particular interest:
SystemState
already has partial support for it.