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

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:

1. Forget Other Devices First:
2. 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.

3. Heaters can only maintain one active pairing at a time.

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

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

1. Bluetooth Pairing Challenges:

   • Manual pairing often required enabling pairing mode and re-entering the PIN.
   • Trusting the device was critical to avoid disconnects.

2. Encoding Mistakes:

   • Initial attempts used 256 scaling instead of 255 for temperature encoding.
   • Correcting to little-endian 0.1°C scaling solved decoding errors.

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