Heatmiser V3 Protocol & Library Documentation

1. Overview & Architecture

The heatmiserv3 Python library provides a robust, low-level and high-level interface for controlling and reading telemetry from Heatmiser thermostats communicating via the Heatmiser Version 3 RS485 protocol.

In modern home automation setups, the UH1 or RS485 converter connects either via a direct local serial device (e.g. /dev/ttyACM0) or a TCP socket server (e.g. socket://192.168.1.57:102). The heatmiserv3 library establishes a connection to this interface via HeatmiserUH1 and coordinates session arbitration, frame formatting, CRC calculation, and response parsing.

2. Protocol Capability Audit: PDF v3.9 vs. heatmiserv3 Library

Below is a comprehensive audit assessing every chapter and feature described in the 45-page heatmiser_v3_protocol_3.9.pdf against the current library implementation:

3. Supported Thermostats & Model Identification

Every Heatmiser thermostat returns its Model ID at DCB Index 4 during a full DCB read:

4. How the Library Works

4.1 Master Command Frame Structure

Whenever a command is issued by the library, a 10-byte (read) or (10 + n)-byte (write) bytecode frame is assembled:

# heatmiserv3/heatmiser.py lines 26-96
class CRC16:
    """This is the CRC hashing mechanism used by the V3 protocol."""

    LookupHigh = [
        0x00, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70,
        0x81, 0x91, 0xA1, 0xB1, 0xC1, 0xD1, 0xE1, 0xF1,
    ]
    LookupLow = [
        0x00, 0x21, 0x42, 0x63, 0x84, 0xA5, 0xC6, 0xE7,
        0x08, 0x29, 0x4A, 0x6B, 0x8C, 0xAD, 0xCE, 0xEF,
    ]

    def __init__(self):
        self.high = 0xFF
        self.low = 0xFF

    def extract_bits(self, val):
        """Extracts 4 bits, XORs message data, and does table lookups."""
        thisval = (self.high >> 4) ^ val
        self.high = ((self.high << 4) | (self.low >> 4)) & 0xFF
        self.low = (self.low << 4) & 0xFF
        self.high = (self.high ^ self.LookupHigh[thisval]) & 0xFF
        self.low = (self.low ^ self.LookupLow[thisval]) & 0xFF

    def update(self, val):
        """Updates the CRC value using bitwise operations."""
        self.extract_bits(val >> 4)    # High nibble first
        self.extract_bits(val & 0x0F)  # Low nibble

    def run(self, message):
        """Calculates a CRC-16 checksum, returning [low, high]."""
        for value in message:
            self.update(value)
        return [self.low, self.high]

/* Heatmiser V3 Protocol Specification - Appendix A */
static const unsigned char CRC16_LookupHigh[16] = {
    0x00, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70,
    0x81, 0x91, 0xA1, 0xB1, 0xC1, 0xD1, 0xE1, 0xF1
};
static const unsigned char CRC16_LookupLow[16] = {
    0x00, 0x21, 0x42, 0x63, 0x84, 0xA5, 0xC6, 0xE7,
    0x08, 0x29, 0x4A, 0x6B, 0x8C, 0xAD, 0xCE, 0xEF
};

static unsigned char CRC16_High = 0xFF;
static unsigned char CRC16_Low  = 0xFF;

void CRC16_Init(void) {
    CRC16_High = 0xFF;
    CRC16_Low  = 0xFF;
}

void CRC16_Update4Bits(unsigned char val) {
    unsigned char t = (CRC16_High >> 4) ^ val;
    CRC16_High = (unsigned char)((CRC16_High << 4) | (CRC16_Low >> 4));
    CRC16_Low  = (unsigned char)(CRC16_Low << 4);
    CRC16_High ^= CRC16_LookupHigh[t];
    CRC16_Low  ^= CRC16_LookupLow[t];
}

void CRC16_Update(unsigned char val) {
    CRC16_Update4Bits(val >> 4);   /* High nibble first */
    CRC16_Update4Bits(val & 0x0F); /* Low nibble */
}

void CRC16_Calculate(const unsigned char *data, size_t len, unsigned char *out_low, unsigned char *out_high) {
    CRC16_Init();
    for (size_t i = 0; i < len; ++i) {
        CRC16_Update(data[i]);
    }
    *out_low  = CRC16_Low;
    *out_high = CRC16_High;
}

const CRC16_LOOKUP_HIGH = [
  0x00, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70,
  0x81, 0x91, 0xA1, 0xB1, 0xC1, 0xD1, 0xE1, 0xF1
];
const CRC16_LOOKUP_LOW = [
  0x00, 0x21, 0x42, 0x63, 0x84, 0xA5, 0xC6, 0xE7,
  0x08, 0x29, 0x4A, 0x6B, 0x8C, 0xAD, 0xCE, 0xEF
];

export function calculateCRC16(data: Uint8Array | number[]): [number, number] {
  let high = 0xFF;
  let low = 0xFF;

  function update4Bits(val: number) {
    const t = ((high >> 4) ^ val) & 0x0F;
    high = (((high << 4) | (low >> 4)) ^ CRC16_LOOKUP_HIGH[t]) & 0xFF;
    low = ((low << 4) ^ CRC16_LOOKUP_LOW[t]) & 0xFF;
  }

  for (let i = 0; i < data.length; i++) {
    const byte = data[i];
    update4Bits((byte >> 4) & 0x0F); // High nibble first
    update4Bits(byte & 0x0F);        // Low nibble
  }

  return [low, high]; // Returns [Low Byte, High Byte]
}

const CRC16_LOOKUP_HIGH: [u8; 16] = [
    0x00, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70,
    0x81, 0x91, 0xA1, 0xB1, 0xC1, 0xD1, 0xE1, 0xF1,
];
const CRC16_LOOKUP_LOW: [u8; 16] = [
    0x00, 0x21, 0x42, 0x63, 0x84, 0xA5, 0xC6, 0xE7,
    0x08, 0x29, 0x4A, 0x6B, 0x8C, 0xAD, 0xCE, 0xEF,
];

pub struct HeatmiserCrc16 {
    high: u8,
    low: u8,
}

impl HeatmiserCrc16 {
    pub fn new() -> Self {
        Self { high: 0xFF, low: 0xFF }
    }

    fn update_4bits(&mut self, val: u8) {
        let t = ((self.high >> 4) ^ val) as usize;
        self.high = (self.high << 4) | (self.low >> 4);
        self.low <<= 4;
        self.high ^= CRC16_LOOKUP_HIGH[t];
        self.low ^= CRC16_LOOKUP_LOW[t];
    }

    pub fn update(&mut self, val: u8) {
        self.update_4bits(val >> 4);
        self.update_4bits(val & 0x0F);
    }

    pub fn calculate(data: &[u8]) -> [u8; 2] {
        let mut crc = Self::new();
        for &b in data {
            crc.update(b);
        }
        [crc.low, crc.high] // [Low Byte, High Byte]
    }
}

package heatmiserv3

var (
    crcLookupHigh = [16]byte{
        0x00, 0x10, 0x20, 0x30, 0x40, 0x50, 0x60, 0x70,
        0x81, 0x91, 0xA1, 0xB1, 0xC1, 0xD1, 0xE1, 0xF1,
    }
    crcLookupLow = [16]byte{
        0x00, 0x21, 0x42, 0x63, 0x84, 0xA5, 0xC6, 0xE7,
        0x08, 0x29, 0x4A, 0x6B, 0x8C, 0xAD, 0xCE, 0xEF,
    }
)

// CalculateCRC16 computes the Heatmiser V3 CRC-16 checksum returning (low, high).
func CalculateCRC16(data []byte) (byte, byte) {
    high := byte(0xFF)
    low := byte(0xFF)

    update4Bits := func(val byte) {
        t := (high >> 4) ^ val
        high = (high << 4) | (low >> 4)
        low = low << 4
        high ^= crcLookupHigh[t]
        low ^= crcLookupLow[t]
    }

    for _, b := range data {
        update4Bits(b >> 4)    // High nibble first
        update4Bits(b & 0x0F)  // Low nibble
    }

    return low, high
}

5. Thermostat DCB Register Tables

The tables below replicate the exact register tables from the official Heatmiser V3.9 protocol specification, augmented with explicit Access Rights, Endianness Rules, and Value Scaling.

6. Visual Test Harness: Real-World DCB Dynamics

Writing register values to a Heatmiser thermostat over RS485 does not merely alter memory bytes in the Device Control Block (DCB)—it orchestrates physical relays, drives safety interlocks, updates LCD annunciators, and modulates HVAC heating loops in the real world.

6.1 Heating Relay Switching & Differential Hysteresis

The central heating relay (connected across Terminals 1 & 2) switches 230V mains or dry-contact signals to central heating motorized zone valves and boiler call-for-heat terminals:

• Call for Heat: When the ambient temperature drops below Target Setpoint - Switching Differential (DCB Addr 18 and Addr 27), the microcontroller fires Relay 1/2. The physical circuit closes, the boiler fires, and the 🔥 flame icon illuminates.
• Setpoint Reached: When the ambient temperature reaches or exceeds the target setpoint, Relay 1/2 opens. The boiler shuts down and the flame icon extinguishes.
• Hysteresis Protection: The 1°C, 2°C, or 3°C differential (DCB Addr 27) prevents rapid boiler short-cycling, extending compressor and burner life.

6.2 Underfloor Heating Overheat Thermal Safety Interlock

When configured for Mode 3 (Built-in Air + Floor Limit Sensor), the thermostat regulates room comfort using air temperature while continuously polling the NTC floor probe embedded in the floor screed:

• Safety Cutout Threshold: If the floor temperature reaches or exceeds Floor Max Limit (DCB Addr 29, typically 28°C–35°C), the firmware trips an Emergency Thermal Safety Cutout.
• Forced Relay Disengagement: The heating relay is forcibly opened immediately, even if the room is cold and demanding heat.
• Real-World Protection: This interlock protects engineered wood flooring from buckling, adhesive breakdown, and cement screed cracking. The LCD flashes FLR HI or a warning badge.

6.3 Domestic Hot Water Dual-Channel Control (PRT-HW)

The PRT-HW model features an independent secondary relay across Terminals 3 & 4 dedicated to domestic hot water (DHW) cylinder valves:

• Manual Hot Water Boost: Writing 01 to DCB Addr 41 (Unique Address 41) closes Terminals 3 & 4, energizing the cylinder valve and illuminating the 🚿 tap icon.
• Holiday Suppression: When Holiday Mode is engaged, hot water heating is suppressed for the holiday duration to conserve energy while the property is unoccupied.

6.4 TM1 Time Clock & Countdown Timer Operations

The TM1 operates in three distinct programming modes (DCB Addr 16: 5/2 day, 7 day, or Countdown Timer):

• Countdown Boost: Setting Countdown Minutes (DCB Addr 26–27, transmitted Little-Endian) energizes the relay and displays the remaining minutes alongside the ⏱️ timer icon. When the counter expires (0 minutes), the relay disengages automatically.
• Timer Override: DCB Addr 42 allows software overrides (0 = Auto Program, 1 = Constant ON, 2 = Constant OFF).

6.5 Commercial Anti-Tamper Keypad Lockout

In public buildings, rental properties, and commercial installations, keypad locking prevents unauthorized temperature manipulation:

• Lock Level 1: Full keypad lock (DCB Addr 22 = 1). All tactile front panel buttons are disabled, displaying a padlock 🔒 icon.
• Tamper Alarm: Attempting to press buttons on the physical faceplate causes the display to flash a red LOC tamper warning and prevents changes.
• Lock Level 2: Partial lock allowing setpoint adjustment within configured temperature limits.

6.6 Holiday Mode Setback vs. Sub-Zero Frost Protection

Energy conservation and freeze prevention are governed by two safety state machines:

• Holiday Mode: Setting holiday hours (DCB Addr 24–25) suspends normal scheduled comfort levels and locks the target to the Frost Protect Temperature (DCB Addr 17, default 12°C). The 🧳 suitcase icon is displayed.
• Standby Freeze Protection: Even when the user turns the thermostat completely OFF / Standby (DCB Addr 21 = 0), an emergency freeze-protection monitor remains active. If the room drops $\le 12^\circ\text{C}$, Relay 1/2 closes and the ❄️ snowflake icon illuminates to prevent burst water pipes.

6.7 One-Click Scenario Demonstration Presets

Click any scenario below to automatically configure the simulated environment, mutate the thermostat DCB registers, and observe real-world hardware actuation:

7. Interactive Bytecode Frame Inspector

Use the tool below to generate, inspect, and verify exact RS485 bytecode packets according to Section 3.1:

8. Protocol Gotchas & Clarifications

The official Heatmiser specification contains subtleties that frequently cause integration bugs. Here are critical clarifications:

9. Python API Specification & Developer Guide

The heatmiserv3 package provides an object-oriented Python interface adhering strictly to the Heatmiser V3 RS485 Protocol 3.9 specification. All convenience methods generate validated CCITT-16 checksummed frames, enforce hardware boundaries, and handle bi-directional telemetry conversion.

Python Automation Examples

from heatmiserv3 import heatmiser, connection

# Connect via serial bridge or direct RS485 adapter
uh1 = connection.HeatmiserUH1(ipaddress="192.168.1.57", port="102")

# Instantiate PRT programmable thermostat at address 1
prt = heatmiser.HeatmiserThermostat(address=1, model="prt", uh1=uh1)

# Configure device operating mode & regulation
prt.set_on_off(1)                       # Turn heating system ON
prt.set_temperature_format("C")         # Use Celsius
prt.set_differential(1)                 # 1°C switching differential
prt.set_target_temp(21)                 # Target comfort: 21°C
prt.set_floormax_temp(28)               # Floor safety cutout: 28°C

# Switch to Remote Air + Floor sensing mode (Mode 4)
prt.set_sensor_selection(4)

# Set 3-hour temporary comfort boost to 23°C
prt.set_temp_hold(minutes=180, temperature=23)

from heatmiserv3 import heatmiser, connection

uh1 = connection.HeatmiserUH1(dev="/dev/ttyUSB0")

# Instantiate PRT-HW thermostat at address 2
prt_hw = heatmiser.PRTHWThermostat(address=2, uh1=uh1)

# Read dual channel state
print("Heating Active:", prt_hw.get_heating_state())     # 1 or 0
print("Hot Water Active:", prt_hw.get_hot_water_state()) # 1 or 0

# Engage hot water boost
prt_hw.set_hot_water_boost(1)

# Reset boost back to scheduled auto mode
prt_hw.set_hot_water_boost(0)

from heatmiserv3 import heatmiser, connection

uh1 = connection.HeatmiserUH1(ipaddress="192.168.1.57", port="102")
tm1 = heatmiser.TM1Thermostat(address=3, uh1=uh1)

# 2-hour countdown timer
tm1.set_countdown_timer(120)

# Set 7-day vacation setback (168 hours)
tm1.set_holiday_hours(168)

# Configure 5/2 Weekday switching schedule (4 pairs: On H/M, Off H/M)
weekday_schedule = [
    6, 30,  8, 30,   # Time 1: 06:30 On, 08:30 Off
    17, 0, 22, 30,   # Time 2: 17:00 On, 22:30 Off
    24, 0, 24,  0,   # Time 3: Cancelled (Hour 24)
    24, 0, 24,  0,   # Time 4: Cancelled (Hour 24)
]
tm1.set_weekday_schedule(weekday_schedule)