Chapter 1: Getting Started

Why Build a Smart Heater Controller?

I recently set out to create a smart heating controller for my Terma MOA Blue heaters using Python, Docker, and Bluetooth Low Energy (BLE).

The Problem

There’s currently no native way to communicate between Home Assistant (HA) and my heaters.

The Goal

I needed precise control over the heaters for my seasonal rental property to:

• Optimize energy consumption—Prevent guests from setting temperatures too high or leaving heaters on when they check out.
• Remotely manage settings—Avoid costly heating bills without physically visiting the property.
• Enable automation—Integrate with HA in the future for better scheduling and monitoring.

This post is the first chapter in a series where I’ll walk you through the process—from setting up the Raspberry Pi and Docker to writing Python scripts for direct Bluetooth control.

About the Terma MOA Blue Heaters

The Terma MOA Blue is a Bluetooth-enabled heating element designed for electric radiators and towel warmers.

Key features:

• Multiple Modes:
  • Manual (Room Temperature)
  • Manual (Heating Element Temperature)
  • Schedules and Timers
• Temperature Control:
  • Supports precision adjustments with 0.1°C steps.
• Bluetooth Low Energy (BLE):
  • Allows remote control via mobile apps or custom integrations.

While these heaters work seamlessly with the manufacturer’s mobile app, I wanted more flexibility by integrating them directly into a custom Python/Docker setup.

Special Thanks to the Home Assistant Community

I want to give a big shoutout to the Home Assistant Community for laying the groundwork and sharing insights about connecting to these heaters using BLE.

Their discussions helped clarify how the Bluetooth characteristics are structured and inspired many of the techniques implemented in this project.

Project Overview

We'll cover:

1. Setting up the Raspberry Pi with Docker.
2. Writing a Python script using BLE to connect to the heater.
3. Encoding and decoding temperature data and heater modes.
4. Packaging the app in Docker for easy deployment.
5. Planning for future features like multiple heater support and automation.

Setting Up the Raspberry Pi

I decided to use a Raspberry Pi as the central controller for this project. Here's how I set it up:

1. Flash Raspberry Pi OS: Download and install the latest Raspberry Pi OS image.
2. Enable SSH and Wi-Fi: Configure SSH access and Wi-Fi credentials during flashing to enable remote development.
3. Install Docker: Docker makes deployment and testing easier.

Commands:

sudo apt update
sudo apt install -y docker.io
sudo usermod -aG docker $USER

1. Test Docker Installation:

docker --version
docker run hello-world

This verifies Docker is installed and running properly.

Setting Up Git and Remote Access

To simplify updates to the code, I set up SSH keys and Git for remote access from my PC.

Key Steps:

1. Generate an SSH key pair:

ssh-keygen -t ed25519 -C "[email protected]"

1. Add the public key to GitHub.
2. Clone the repository:

git clone [email protected]:<username>/<repo>.git

Repository Link

You can check out the full source code in my GitHub repo:

👉 GitHub - ha-hudsonread-heater-control

Feel free to fork it, suggest improvements, or report any issues!

Controlling the Heater with Bluetooth

The Terma MOA Blue heater communicates over Bluetooth Low Energy (BLE), so I used the Bleak library in Python to handle the connection.

Key features implemented so far:

• Read and Write Temperatures: Using UUID-based characteristics.
• Mode Control: Switching between Off, Manual (Room Temp), and Manual (Heating Element Temp).
• Dynamic Updates: Control temperatures without affecting modes.

Current State and Next Steps

Right now, the controller can:

• Connect to the heater.
• Read the current temperature and target temperature.
• Switch modes and adjust temperatures independently.

Next Steps:

• Add support for multiple heaters.
• Enable automation via integration with Home Assistant or similar platforms.

Follow Along

Stay tuned for Chapter 2, where I’ll dive into the Python code, explain how BLE encoding and decoding works, and share insights from debugging Bluetooth connections.

We’ll also cover manual pairing and connection commands using bluetoothctl for anyone interested in a deeper look into BLE debugging.

Don’t forget to ⭐️ the GitHub repo and let me know in the comments what features you'd like to see added next!