heatmiser-neohub

Python client library and command-line interface for the IMI Heatmiser NeoHub API (WebSocket/WSS control interface on port 4243, plus UDP hubseek discovery on port 19790).

Stability (1.0)

The public API is the symbols exported from heatmiser_neohub (client, models, discovery helpers, errors) and the CLI commands discover, live-data, system, and cmd. This release does not promise typed wrappers for every NeoHub command, WebSocket auto-reconnect, or raising on hub application-error payloads (those remain returned response data).

See docs/reference/neohub-api-rev-3.02.md for the full protocol reference this library implements.

Related links

• PyPI
• neoHub smart control (product)
• IMI Heatmiser Developer Portal
• Official NeoHub API PDF

Documentation

Published docs (GitHub Pages): https://hypercat-net.github.io/heatmiser-neohub/

• CLI guide
• Python library guide
• NeoHub API protocol guide (reference)
• OpenAPI / Swagger (secondary command catalogue)

Source markdown lives under docs/guide/ (product docs) and docs/reference/neohub-api-rev-3.02.md (protocol).

Build the site locally:

pip install "markdown>=3.10" "PyYAML>=6.0.3"
python scripts/build_docs_site.py -o site
open site/index.html

GitHub Pages is published by .github/workflows/pages.yaml on pushes to main.

Installation

Install from PyPI:

pip install heatmiser-neohub

For local development, install in editable mode with the dev extras:

pip install -e ".[dev]"

Docker

A slim multi-arch image (linux/amd64, linux/arm64) is published to Docker Hub as hypercat42/heatmiser-neohub. The image is built from this repository’s source (not installed from PyPI) so each tag matches the git commit that produced it.

# Discovery uses UDP broadcast. Containers are isolated from the LAN by default,
# so on Linux use host networking for `discover` (and for auto-discover when
# NEOHUB_HOST is unset).
docker run --rm --network host hypercat42/heatmiser-neohub discover

docker run --rm -e NEOHUB_HOST -e NEOHUB_TOKEN hypercat42/heatmiser-neohub live-data
# or: docker run --rm --env-file .env hypercat42/heatmiser-neohub live-data

Configuration

Copy .env.example to .env and set your hub details:

cp .env.example .env

The neohub CLI loads .env automatically (real environment variables still win). You can also pass flags or export variables yourself.

# With .env in the working directory
neohub live-data

# Or export / Docker --env-file
export NEOHUB_HOST=192.168.0.19
export NEOHUB_TOKEN=your-api-token
docker run --rm --env-file .env hypercat42/heatmiser-neohub live-data

CLI usage

The package installs a neohub console script:

# Discover NeoHubs on the local network
neohub discover

# Fetch live zone/device data
neohub live-data

# Fetch hub system settings
neohub system

# Send an arbitrary JSON command
neohub cmd '{"GET_SYSTEM":0}'

# Version / logging
neohub --version
neohub -v live-data
neohub --debug cmd '{"FIRMWARE":0}'

Global options: --version/-V, --verbose/-v, --debug (also NEOHUB_VERBOSE / NEOHUB_DEBUG). Each command also accepts --host, --token, and --port, which override the corresponding environment variables.

Library example

import asyncio

from heatmiser_neohub import NeoHubClient


async def main() -> None:
    async with NeoHubClient(host="192.168.0.19", token="your-api-token") as client:
        live_data = await client.get_live_data()
        for device in live_data.devices:
            print(device.zone_name, device.actual_temp, device.set_temp)


asyncio.run(main())

Discovery

NeoHubs can be located on the local network without knowing their IP address:

from heatmiser_neohub.discover import discover_hubs

for hub in discover_hubs():
    print(hub.ip, hub.device_id)

Development

pip install -e ".[dev]"
pytest   # includes coverage; fail_under is configured in pyproject.toml

See CONTRIBUTING.md. This project is released under the MIT License.