heatmiserv3

📖 View the Complete Protocol & Library Documentation Website

The documentation includes an interactive Visual Test Harness (Digital Twin) simulating backlit LCDs, relay contact states, underfloor overheat cutouts, environment sliders, and live RS485 bytecode packet inspection.

Overview

heatmiserv3 is a Python library to interact with Heatmiser Thermostats and Timing Switches communicating over the Heatmiser V3 RS485 serial-over-IP or serial bus protocol.

It provides high-level object models (HeatmiserThermostat, TM1Thermostat) as well as network connection multiplexing (HeatmiserUH1) to read Data Control Blocks (DCBs), inspect telemetry, adjust setpoints, and configure heating/timing schedules.

sequenceDiagram
    autonumber
    participant App as Home Assistant / Python App
    participant UH1 as HeatmiserUH1 Bridge
    participant RS485 as RS485 / Network Bus
    participant Stat as Heatmiser Slave (PRT / TM1)

    App->>UH1: Initialise connection (socket / serial)
    App->>UH1: Register thermostat (address 1, model "prt")
    App->>Stat: read_dcb() / get_target_temp()
    Stat->>UH1: Form READ frame + CRC16
    UH1->>RS485: Transmit binary bytecode
    RS485->>Stat: Bytecode delivered
    Stat-->>RS485: Respond with DCB frame (9-byte header + DCB payload + CRC)
    RS485-->>UH1: Raw bytes received
    UH1-->>Stat: Verify frame length & CRC16 checksum
    Stat-->>App: Parsed DCB attributes (temp, status, relays)

Supported Hardware

Category	Models	Protocol Features
Thermostats	`PRT`, `PRT-E`, `PRT-HW`, `DT`, `DT-E`	Full DCB read, setpoint modification, frost protection, floor temperature limit monitoring
Timing Switches	`TM1`, `TM1-N`	Relay switching, holiday hours, countdown timer, 5/2 & 7-day switching schedules
Wiring Centres	`UH1`	RS485 serial-over-IP multiplexing for up to 32 chained thermostats

Installation

Using pip:

pip install heatmiserv3

Using uv:

uv add heatmiserv3

Quick Start

Interfacing with a PRT Thermostat via UH1

from heatmiserv3 import connection, heatmiser

# 1. Connect to Heatmiser UH1 wiring centre over TCP/IP or local serial device:
uh1 = connection.HeatmiserUH1("192.168.1.57", 8068)
# Alternatively, connect via a direct local RS485 serial adapter:
# uh1 = connection.HeatmiserUH1(dev="/dev/ttyACM0")

# 2. Register a thermostat attached to the UH1 bus at RS485 address 1
thermo1 = heatmiser.HeatmiserThermostat(1, "prt", uh1)

# 3. Read telemetry
print(f"Room Temperature: {thermo1.get_floor_temp()}°{thermo1.get_temperature_format()}")
print(f"Target Temperature: {thermo1.get_target_temp()}°C")
print(f"Heating Active: {thermo1.get_heating() == 1}")

# 4. Modify setpoints (with built-in range validation)
success = thermo1.set_target_temp(21)
if success:
    print("Target temperature updated to 21°C")

Interfacing with a TM1 Timing Switch

from heatmiserv3 import connection, heatmiser

uh1 = connection.HeatmiserUH1("192.168.1.57", 8068)
timer = heatmiser.TM1Thermostat(2, uh1)

# Check timer status
print(f"On/Off: {timer.get_on_off()}")
print(f"Program Mode: {timer.get_program_mode()}")

# Override timer ON
timer.set_timer_state(1)

Architecture Decision Records (ADRs)

Key architectural decisions are documented under docs/adrs/:

Development & Testing

This project uses uv and hatchling.

# Clone the repository
git clone https://github.com/andylockran/heatmiserv3.git
cd heatmiserv3

# Install dependencies into virtualenv
uv sync

# Run tests and verify >90% coverage gate
uv run pytest --cov=heatmiserv3 --cov-report=term-missing

# Run code style and lint checks
uv run flake8

# Build source distribution and binary wheel
uv build

See CONTRIBUTING.md for contribution guidelines.

Origin & Credits

This library originated from reverse engineering and protocol implementation work carried out by Neil Trimboy in 2011 on Google Code. It has been maintained and modernized by Andy Loughran and community contributors.

Metadata

Release files for heatmiserv3 3.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for heatmiserv3 3.0.0
File	Size	Uploaded
heatmiserv3-3.0.0.tar.gz	16.8 kB	Oct 13, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for heatmiserv3 3.0.0
File	Interpreter	ABI	Platform	Reset
heatmiserv3-3.0.0-py3-none-any.whl 18.2 kB Oct 13, 2026	Python 3	none	any	Details

Total release size: 35.1 kB

Release files / heatmiserv3-3.0.0.tar.gz

Download URL	heatmiserv3-3.0.0.tar.gz
Size	16.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`0fb7e09c569f0dbf80ccc47ddfd912ad68b0e8b9ab1784846037291bda313d67`
BLAKE2b-256 checksum How to use checksums	`fbb388ac709b26d454adf25b67004f9ce991f529aa9ee0bb708784c24207566d`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/andylockran/heatmiserV3
Publishing commit: github.com/andylockran/heatmiserV3/tree/61d3c6edb360fcd135aaa99e2a301ee15e676b83

Workflow

Publishing configuration: github.com/andylockran/heatmiserV3/blob/61d3c6edb360fcd135aaa99e2a301ee15e676b83/.github/workflows/python-publish.yml
Publishing logs: github.com/andylockran/heatmiserV3/actions/runs/38472437167/attempts/1

Artifact

Subject: heatmiserv3-3.0.0.tar.gz
SHA-256 checksum: 0fb7e09c569f0dbf80ccc47ddfd912ad68b0e8b9ab1784846037291bda313d67 Verifying attestations

Release files / heatmiserv3-3.0.0-py3-none-any.whl

Download URL	heatmiserv3-3.0.0-py3-none-any.whl
Size	18.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`51bedbfca0ae8a3e196b69389fdf2d0fe6a5d2a0eb69db680ddace9c15cf3100`
BLAKE2b-256 checksum How to use checksums	`0f0bf30dc45b9e150849295e18cff299aad9f82859541d1addf372ac50393e7a`
Upload date	Oct 13, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/andylockran/heatmiserV3
Publishing commit: github.com/andylockran/heatmiserV3/tree/61d3c6edb360fcd135aaa99e2a301ee15e676b83

Workflow

Publishing configuration: github.com/andylockran/heatmiserV3/blob/61d3c6edb360fcd135aaa99e2a301ee15e676b83/.github/workflows/python-publish.yml
Publishing logs: github.com/andylockran/heatmiserV3/actions/runs/38472437167/attempts/1

Artifact

Subject: heatmiserv3-3.0.0-py3-none-any.whl
SHA-256 checksum: 51bedbfca0ae8a3e196b69389fdf2d0fe6a5d2a0eb69db680ddace9c15cf3100 Verifying attestations

Release history Release notifications | RSS feed

This release

3.0.0 This release

Oct 13, 2026 2 release files

2.0.6

Jan 7, 2026 2 release files

2.0.5

Dec 10, 2025 2 release files

2.0.4

Dec 8, 2025 2 release files

2.0.3

Jan 31, 2024 2 release files

2.0.2

Jan 28, 2024 2 release files

2.0.1

Jan 28, 2024 2 release files

2.0.0

Jan 28, 2024 2 release files

1.2.6

Jan 28, 2024 2 release files

1.2.3

Jan 28, 2024 2 release files

1.2.2

Jan 28, 2024 1 release file

1.2.1

Jan 15, 2023 2 release files

1.2.0

Jan 15, 2023 2 release files

1.1.18

Nov 30, 2019 2 release files

1.1.17

Nov 30, 2019 2 release files

1.1.16

Nov 30, 2019 2 release files

1.1.15

Nov 30, 2019 2 release files

1.1.14

Nov 30, 2019 2 release files

1.1.13

Nov 30, 2019 2 release files

1.1.12

Nov 30, 2019 2 release files

1.1.11

Nov 24, 2019 2 release files

1.1.10

Nov 24, 2019 2 release files

1.1.9

Jun 9, 2019 2 release files

1.1.8

Jan 20, 2019 2 release files

1.1.7

Jan 20, 2019 2 release files

1.1.6

Jan 20, 2019 2 release files

1.1.5

Jan 20, 2019 2 release files

1.1.3

Jan 20, 2019 2 release files

1.1.2

Jan 20, 2019 3 release files

1.1.1

Jan 16, 2019 2 release files

1.1.0

Jan 13, 2019 2 release files

1.0.0

May 26, 2017 2 release files

0.9.5

Feb 6, 2018 3 release files

0.9.4

Jan 31, 2018 1 release file

0.9.3

Dec 11, 2015 1 release file

0.9.2

Dec 11, 2015 1 release file

0.9.1

Dec 11, 2015 1 release file

0.9

Dec 9, 2015 1 release file

0.8

Dec 9, 2015 1 release file

0.7

Dec 9, 2015 1 release file

0.6

Dec 9, 2015 1 release file

0.5

Dec 9, 2015 1 release file

0.4

Dec 9, 2015 1 release file

0.3

Dec 9, 2015 1 release file

0.2

Dec 9, 2015 1 release file

heatmiserv3 3.0.0

heatmiserv3

Overview

Supported Hardware

Installation

Quick Start

Interfacing with a PRT Thermostat via UH1

Interfacing with a TM1 Timing Switch

Architecture Decision Records (ADRs)

Development & Testing

Origin & Credits

Project links

Key dates

2 maintainers

Credits

GitHub Statistics

License expression

Requires

Classifiers

Metadata

Project links

Key dates

2 maintainers

Credits

GitHub Statistics

License expression

Requires

Classifiers

Release files for heatmiserv3 3.0.0

Source distribution (sdist)

Built distribution (wheel)

Release files / heatmiserv3-3.0.0.tar.gz

Provenance

PyPI Publish Attestation

Identity

Workflow

Artifact

Release files / heatmiserv3-3.0.0-py3-none-any.whl

Provenance

PyPI Publish Attestation

Identity

Workflow

Artifact

Release history Release notifications | RSS feed