DEV Community: Miguel Correa Calvo

Building a Smart Heater Controller with Python, Docker, and Bluetooth #5

Miguel Correa Calvo — Fri, 10 Jan 2025 12:40:54 +0000

Chapter 5: Exposing the Python Script Through an API to Control Heaters From Home Assistant

In this chapter, I’ll walk you through how I exposed my Python script via an API, allowing it to be controlled directly from Home Assistant (HA). We’ll detail the steps taken to build the API, integrate it with HA, and expand functionality with Zigbee USB devices in a Dockerized environment.

😺 Python git project
Feel free to fork and improve ! Git hub

🎥 HA Overview video

Section 1: Building the API for the Python Script

To enable control of the heaters, I implemented a RESTful API with the following:

Framework Selection: I used Flask to create the API due to its simplicity and compatibility with the existing Python script.
API Endpoint:
- POST /set-temp: This endpoint allows setting the temperature of a heater. The payload includes the room name and the target temperature, e.g., {"room": "kitchen", "temp": 22}.
Dockerizing the API:
- The Flask app was containerized using Docker.
- The Dockerfile was configured to expose port 5000 for the API.
- Used docker run to grant access to the network and expose the API locally:
```
    docker run -d --net=host --privileged -v /var/run/dbus:/var/run/dbus --name heater-controller
```
Testing the API:
- Used Postman and curl to test the /set-temp endpoint.

curl --location 'http://raspberrypi.local:5000/set-temp' \
--header 'Content-Type: application/json' \
--data '{
    "temperature": 60,
    "room":"living_room"
}'

Ensured proper error handling for invalid room names or temperatures outside acceptable ranges.

Section 2: Plugging Home Assistant Into the Local API

With the API running, I connected it to HA to enable heater control:

Configuration in HA:

Edited configuration.yaml to create REST commands for the API:

rest_command:
  set_heater_temp:
    url: "http://localhost:5000/set-temp"
    method: POST
    headers:
      Content-Type: application/json
    payload: '{"room": "{{ room }}", "temp": {{ temp | float }}}'

Common Errors and Fixes:
- Floats Sent as Strings: Adjusted templates in HA to ensure temperatures were sent as numbers.
- Timeout Issues: Increased the API timeout in HA to handle slower network responses.

Section 3: Controlling Heaters From Home Assistant

After integrating the API, I added controls in HA to manage heaters effectively:

Helpers:
- Set up input_number helpers for each room to adjust target temperatures.

Automation Scripts:

Created scripts to send temperature updates to the API when a helper value changes.

- id: update_heater_temp
  alias: Update Heater Temperature
  trigger:
    - platform: state
      entity_id: input_number.kitchen_temp
  action:
    - service: rest_command.set_heater_temp
      data:
        room: "kitchen"
        temp: "{{ states('input_number.kitchen_temp') | float }}"

UI Enhancements:
- Configured a Lovelace dashboard to show sliders for each room’s temperature control.
- Included feedback on current heater temperatures retrieved via sensors.

Section 4: Using Zigbee in a Dockerized HA Instance

I extended the system by adding Zigbee functionality for further automation:

USB Port Exposure:
- Updated Docker Compose to pass through the Zigbee USB coordinator:
```
devices:
  - "/dev/ttyUSB0:/dev/ttyUSB0"
```
Zigbee2MQTT Integration:
- Installed Zigbee2MQTT to manage Zigbee devices using a Conbee II USB coordinator.
- Added Zigbee sensors (e.g., window sensors) to HA.
Automation with Zigbee Sensors:
- Linked Zigbee sensors to heater control via automation scripts.
- Example: Turn off a room’s heater when its window sensor reports it is open.

Final Thoughts

By exposing the Python script as an API and integrating it with HA, I created a reliable system for controlling heaters. The addition of Zigbee functionality further enhanced the system, enabling seamless automation. This setup demonstrates the flexibility and scalability achievable with Docker, APIs, and smart home integrations.

Building a Smart Heater Controller with Python, Docker, and Bluetooth #4

Miguel Correa Calvo — Fri, 10 Jan 2025 12:23:44 +0000

Chapter 4: Exposing Home Assistant to the World

In this chapter, I’ll walk you through how I exposed my Home Assistant (HA) instance to the internet using Cloudflare. This approach ensures secure, remote access to HA without needing to open ports on my router. It offers free access via Cloudflare tunnels. Alternatively, for a paid option with additional features, you can consider using Nabu Casa. If you’re running HA in Docker like I am, this guide is especially relevant since it involves running Cloudflared in a separate Docker container.

Why Cloudflared?

Cloudflare’s Cloudflared add-on provides a secure way to expose services running locally to the internet by creating a tunnel to Cloudflare’s network. It’s perfect for situations where you:

Don’t want to or cannot open ports on your router.
Want to avoid complex network configurations.
Require robust security with minimal setup.

Since I’m running HA in Docker and add-ons aren’t available for this setup, I needed to run Cloudflared in a separate Docker container.

Setting Up Cloudflared in Docker

Here’s how I set up Cloudflared to work with my Home Assistant instance:

Follow the Guide:
I followed the instructions detailed in this Home Assistant Community post. These steps outline how to configure Cloudflared in Docker for HA. Special thanks to brenner-tobias for creating the Cloudflared add-on and providing invaluable guidance.

A few key points :

Use the Correct Docker Image: Instead of the standard cloudflared/cloudflared image, I used milgradesec/cloudflared:latest. This image is tailored for arm64 which is required by Pi4.

   docker run -v ~/demo:/home/nonroot/.cloudflared      milgradesec/cloudflared:latest tunnel create test-tunnel

Domain Name Configuration:
I had already purchased a domain name through Cloudflare (https://www.cloudflare.com/en-ca/). Configuring the domain was straightforward:
- Added a CNAME record pointing my domain’s subdomain to the Cloudflare tunnel.
- Set up Zero Trust policies in the Cloudflare dashboard to control access.
Connect to Home Assistant:
I configured the Cloudflared tunnel to point to the internal IP of my HA instance running on Docker. This made my HA accessible through my custom domain securely.

HA configuration.yaml

# Loads default set of integrations. Do not remove.
default_config:

http:
  use_x_forwarded_for: true

  trusted_proxies:
  - 127.0.0.1

# Load frontend themes from the themes folder
frontend:
  themes: !include_dir_merge_named themes

automation: !include automations.yaml
script: !include scripts.yaml
scene: !include scenes.yaml

Cloudflare configuration

Benefits of Using Cloudflared

Security: Traffic is routed through Cloudflare’s network, ensuring that your HA instance is not directly exposed.
No Port Forwarding: There’s no need to open ports on your router, reducing the attack surface.
Custom Domain: Using my own domain makes accessing HA intuitive and professional.
Zero Trust Policies: Control who can access your HA instance using Cloudflare’s advanced security features.

Challenges and Solutions

Choosing the Right Docker Image:
Initially, I tried using cloudflared/cloudflared, but it didn’t work as expected. Switching to milgradesec/cloudflared:latest resolved the issue.
Configuring the Tunnel:
The community guide was invaluable in setting up the tunnel configuration correctly. Double-checking the YAML file and logs helped troubleshoot minor errors.
Domain Setup:
Configuring the domain name through Cloudflare’s dashboard was straightforward but required some trial and error with DNS records.

Final Thoughts

By setting up Cloudflared in a separate Docker container, I’ve ensured secure, remote access to my Home Assistant instance without compromising on security or flexibility. Whether you’re running HA in Docker or looking for a no-port-forwarding solution, this method works brilliantly.

In the next chapter, I’ll walk you through setting up the segue, given that HA is Dockerised. Stay tuned!

Building a Smart Heater Controller with Python, Docker, and Bluetooth #3

Miguel Correa Calvo — Sun, 29 Dec 2024 12:32:24 +0000

Chapter 3: Building the Pair Device Script and Setting Up Smart Heaters

In this chapter, I'll walk you through how I set up my Bluetooth-enabled heaters, from identifying each device to pairing them with a custom bash script and ensuring they’re ready for use with my Python code. If you've been following along, you already know the groundwork we’ve laid. Now let’s see how it all fits together.

Identifying Each Heater with LightBlue

The first step in managing multiple heaters was to identify their unique Bluetooth addresses. To do this, I used an Android app called LightBlue, which makes scanning and identifying Bluetooth devices straightforward. Here’s what I did:

Open LightBlue: I launched the app and started scanning for devices nearby.
Check Signal Strength: By moving closer to each heater, I could see the signal strength (RSSI) increase, helping me identify which device matched each physical heater.
Document Everything: I took note of each heater’s address and organized them by room (e.g., kitchen, living room) in a JSON file called rooms.json.

Here’s an example of how my rooms.json file looks, with each room containing an array of device addresses:

{
  "kitchen": ["CC:22:37:11:26:4F"],
  "living_room": ["CC:22:37:11:26:50"],
  "bedroom_1": ["CC:22:37:11:26:51"],
  "bedroom_2": ["CC:22:37:11:26:52"]
}

This step ensured I had a clear map of which devices belonged to which rooms, making it easier to target them with scripts.

Writing the Pair Device Bash Script

To make the process even more flexible, I used the Termux app on my Android phone. Termux is a command-line terminal that allowed me to move around freely while running the pairing script, making it easier to work near the heaters as I set them up.

To streamline the setup process, I wrote a bash script called pair_heaters.sh. Here’s what it does:

Reads from rooms.json:
The script reads device addresses and room assignments from the JSON file, ensuring every heater is accounted for.
Handles Pairing Automatically:
For each device, the script:
- Checks if it’s already paired.
- Attempts to connect if it’s paired.
- If not, prompts me to put the device in pairing mode and waits for my confirmation before proceeding.
- Logs the pairing and connectivity status of each heater.
Disconnects Devices Post-Pairing:
After pairing, the script disconnects each heater. This is necessary because the Python script needs the devices to be connectable but not actively connected.
Ensures Stability:
I included delays between Bluetooth commands to prevent issues caused by rapid interactions.
Provides Logs for Debugging:
Detailed logs make it easy to see what’s happening at each step, helping me fix any problems quickly.

To run the script, I simply use:

bash pair_heaters.sh

The script loops through all the devices in rooms.json, making the pairing process much faster and less error-prone.

Setting Up the Heaters for Use

After pairing and trusting the devices, they’re almost ready for use. Here’s what happens next:

Check the Connectable State:
The heaters must be in a connectable state—not connected to another device. This ensures the Python script can interact with them freely.
Control with Python:
Once ready, the Python script detects the heaters, reads their current mode and temperature, and lets me control them remotely. Pairing ensures they’re always ready for the script to connect.
Re-run the Script Only When Necessary:
The pairing script is only needed if a heater gets paired with another device (e.g., my phone). Otherwise, the heaters stay ready for action.

With this setup, my heaters are ready for automated control, bringing me closer to a fully smart system. If you want to see the script and configuration files, you can check out my GitHub repository.

In the next chapter, I’ll explain how to integrate the heaters into a home automation platform and make the Python script even more robust.

Ready to pair your devices?

Building a Smart Heater Controller with Python, Docker, and Bluetooth #2

Miguel Correa Calvo — Sat, 28 Dec 2024 11:55:10 +0000

Chapter 2: Cracking Bluetooth Control with Python

Introduction

In Chapter 1, we set up the foundation for controlling Terma MOA Blue heaters using a Raspberry Pi, Docker, and Python.

Now it’s time to dive deeper into:

How BLE works and how we used it to communicate with the heaters.
Debugging Bluetooth connections using bluetoothctl.
Encoding and decoding data for temperature and mode settings.
The Python script that brings it all together.

Bluetooth Low Energy (BLE) – Quick Overview

The Terma MOA Blue heaters use Bluetooth Low Energy (BLE) for communication. BLE devices expose GATT characteristics, which act like data points you can read from or write to.

Key Concepts:

UUIDs: Unique IDs identifying specific data points, like temperature or mode.
Characteristics: BLE properties holding the actual data.
Descriptors: Additional metadata about characteristics.
Write vs. Read Operations: Some characteristics only support reads (e.g., current temperature), while others allow writes (e.g., setting temperature).

Debugging Bluetooth Connections with bluetoothctl

Before automating the process with Python, we used bluetoothctl for manual testing and debugging.

Step 1: Scan for Devices

bluetoothctl
scan on

Look for devices named "Terma Wireless".

Ensure the Heater Is in Pairing Mode: Press and hold the temperature button for 5 seconds until the light blinks. This activates pairing mode.
Identify the Closest Device: The device with the lowest RSSI value (e.g., RSSI: -50) is likely the closest heater. Lower (more negative) RSSI values indicate weaker signals, so focus on the strongest signal.

Step 2: Pair with the Heater

pair <DEVICE_ADDRESS>

When prompted, enter the PIN code 123456.

Step 3: Trust and Connect

trust <DEVICE_ADDRESS>
connect <DEVICE_ADDRESS>

Step 4: Read Characteristics

Once connected, use:

info <DEVICE_ADDRESS>

This displays the available UUIDs for reading and writing data.

Important Notes:

Forget Other Devices First:
If the heater is already paired with another device (e.g., a phone app), you’ll need to unpair it from that device before proceeding.
Heaters can only maintain one active pairing at a time.
Reconnecting After Failures:
- If the heater was successfully connected but later fails to reconnect, use the following steps:
```
 remove <DEVICE_ADDRESS>
```

Then re-pair using the steps above.

Initial Connection Is Required for Python Script:
- The first connection must be established manually via bluetoothctl.
- Once paired, the Python script will be able to interact with the heater.
- However, if you later pair the heater with another device (breaking the connection), you’ll need to remove and reconnect manually from the Raspberry Pi before running the script again.

Cracking the Heater’s Data Format

Temperature Encoding

The heaters encode temperatures as two bytes (little-endian) with 0.1°C precision.

Example:

Hex: 012d → Decoded: 30.1°C

Python Decoding:

def decode_temperature(data):
    current_temp = ((data[1] << 8) | data[0]) / 10
    target_temp = ((data[3] << 8) | data[2]) / 10
    return round(current_temp, 1), round(target_temp, 1)

Python Encoding:

def encode_temperature(temp):
    temp_value = int(temp * 10)
    return temp_value.to_bytes(2, 'little')

Mode Encoding

Operating modes are stored as single bytes with specific values:

0: Off
5: Manual (Room Temp)
6: Manual (Heating Element Temp)
33: Verified Heating Element Mode (Hex: 0x21)

Python Decoding:

MODES = {
    0: "Off",
    5: "Manual (Room Temp)",
    6: "Manual (Heating Element Temp)",
    33: "Manual (Heating Element Temp - Verified)"
}

Python Encoding:

mode_value = {
    0: bytes.fromhex("00"),
    5: bytes.fromhex("05"),
    6: bytes.fromhex("06"),
    33: bytes.fromhex("21")
}

Key Lessons Learned

Bluetooth Pairing Challenges:
- Manual pairing often required enabling pairing mode and re-entering the PIN.
- Trusting the device was critical to avoid disconnects.
Encoding Mistakes:
- Initial attempts used 256 scaling instead of 255 for temperature encoding.
- Correcting to little-endian 0.1°C scaling solved decoding errors.
Mode Handling Issues:
- BLE modes weren’t well-documented, and we had to reverse-engineer the values.
- Testing confirmed 33 (0x21) worked for Manual Heating Element Temp mode.

What’s Next?

In the next chapter, I’ll:

Expand the script to support multiple heaters.
Introduce Docker integration for easier deployment.
Start exploring automation setups with Home Assistant.

Feedback and Suggestions?

Check out the GitHub repo:

👉 GitHub - ha-hudsonread-heater-control

Let me know your thoughts and suggestions in the comments below!

Building a Smart Heater Controller with Python, Docker, and Bluetooth #1

Miguel Correa Calvo — Sat, 28 Dec 2024 11:24:31 +0000

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:

Setting up the Raspberry Pi with Docker.
Writing a Python script using BLE to connect to the heater.
Encoding and decoding temperature data and heater modes.
Packaging the app in Docker for easy deployment.
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:

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

Commands:

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

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:

Generate an SSH key pair:

ssh-keygen -t ed25519 -C "your_email@example.com"

Add the public key to GitHub.
Clone the repository:

git clone git@github.com:<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!