A standalone Home Assistant add-on repository for Heatmiser NeoHub heating systems.
NeoHub Control turns Heatmiser NeoHub into a proper Home Assistant citizen: cloud login, live zone telemetry, MQTT Discovery, thermostat control, socket control, diagnostic attributes, and a dashboard that looks like it belongs in a mission-control room rather than a boiler cupboard.
It uses the same NeoHub cloud method proven by the original Python project:
hm_user_loginfor login and device discoveryhm_cache_valuefor live heating statehm_set_tempfor temperature commandshm_set_modefor mode and socket-style commands
The result: your Heatmiser estate becomes discoverable climate.* and switch.* entities in Home Assistant, ready for dashboards, automations, voice assistants, energy workflows, and sane operational visibility.
Heating is infrastructure. It should be observable, scriptable, automatable, and beautiful.
NeoHub Control is for people who want more than a vendor app:
- Landlords and estate operators managing many heating zones
- Smart-home builders who want Home Assistant-native climate entities
- Engineers who want MQTT topics they can inspect, replay, automate, and trust
- Anyone who wants Heatmiser visibility without staring at a phone app
- Add this repository directly to the Home Assistant Add-on Store
- Runs inside Home Assistant OS / Supervised as an add-on
- Uses MQTT Discovery to create Home Assistant entities automatically
- Uses pre-built GHCR images and Home Assistant builder actions for supported
aarch64andamd64systems - Reads configuration from the standard add-on
/data/options.json - Uses the Mosquitto add-on by default at
core-mosquitto:1883
- Provides a valid
custom_components/neohub_controlintegration layout so HACS accepts the repository when users paste it there by mistake - Shows the correct Add-on Store installation route from inside Home Assistant
- Does not replace the add-on runtime, because HACS does not run add-on containers
- Thermostat-like zones become MQTT
climateentities - Socket-like zones become MQTT
switchentities - Stable object IDs based on hub and zone name
- Retained availability, state, and discovery topics
Commands from Home Assistant are routed back to the NeoHub API:
- Set target temperature from Home Assistant
- Change mode: heat, cool, fan-only/vent, off
- Toggle socket-like zones through the mode command path
The bridge publishes:
- Current temperature
- Target temperature
- HVAC mode
- Heating action
- Humidity
- Availability
- Window-open attribute
- Low-battery attribute
- Timer status
- Modulation level
This repository includes two dashboard templates:
-
dashboards/neohub-control-premium-dashboard.yaml- Premium Home Assistant dashboard using Mushroom, Auto Entities, and ApexCharts
- Auto-populates
climate.neohub_*andswitch.neohub_*entities - Includes a 24-hour temperature intelligence view
-
dashboards/neohub-control-basic-dashboard.yaml- Zero-dependency Lovelace dashboard using only built-in cards
- Good for clean installs or conservative systems
flowchart LR
HA[Home Assistant] -->|MQTT Discovery| MQTT[(MQTT Broker)]
MQTT -->|command topics| ADDON[NeoHub Control Add-on]
ADDON -->|hm_user_login| CLOUD[Heatmiser NeoHub Cloud]
ADDON -->|hm_cache_value| CLOUD
ADDON -->|hm_set_temp / hm_set_mode| CLOUD
CLOUD --> HUB[NeoHub]
HUB --> ZONES[Thermostats + Sockets]
ADDON -->|state topics| MQTT
MQTT -->|climate/switch entities| HA
The add-on is intentionally MQTT-native. MQTT Discovery is the cleanest way for an add-on to create Home Assistant climate and switch entities without writing and maintaining a separate Home Assistant custom integration.
.
├── hacs.json # HACS custom repository metadata
├── custom_components/
│ └── neohub_control/ # HACS companion helper integration
├── repository.yaml # Home Assistant add-on repository manifest
├── addons/
│ └── neohub_control/ # Home Assistant add-on
│ ├── config.yaml # Add-on manifest and options schema
│ ├── Dockerfile # Add-on container image
│ ├── DOCS.md # Add-on documentation
│ ├── README.md # Add-on store summary
│ ├── rootfs/ # s6 service runner
│ └── app/ # Code copied into the add-on image
├── assets/
│ └── neohub-control-hero.svg # Animated project header
├── dashboards/
│ ├── neohub-control-premium-dashboard.yaml
│ └── neohub-control-basic-dashboard.yaml
├── ha_addon/ # Testable add-on bridge source
├── neohub/ # NeoHub API wrapper
├── tests/ # MQTT bridge tests
└── requirements.txt # Local development requirements
NeoHub Control's working bridge runs as a Home Assistant add-on. HACS does not manage add-ons or add-on containers, so the functional installation path is the Home Assistant Add-on Store.
From 0.2.5, this repository also includes a small HACS companion integration under custom_components/neohub_control. That makes the repository valid when it is pasted into HACS as an integration, but the HACS-installed helper only explains the correct add-on installation path inside Home Assistant. It does not run the NeoHub MQTT bridge.
Use the Add-on Store path below for the working bridge:
In Home Assistant:
- Go to Settings → Add-ons → Add-on Store
- Open the three-dot menu
- Choose Repositories
- Add:
https://github.com/GitDakky/NeoHub-Control
- Refresh the add-on store
- Install
NeoHub Control
Install and start the official Mosquitto broker add-on, then make sure the MQTT integration is enabled in Home Assistant.
From 0.2.4, NeoHub Control explicitly declares minimal Supervisor API access and consumes Home Assistant Supervisor's mqtt:need service credentials automatically. Leave the MQTT username/password blank unless you intentionally use an external broker. This fixes the common failure where Mosquitto rejects anonymous add-on clients and no discovery entities appear.
username: your-neohub-email@example.com
password: your-neohub-password
url: https://neohub.co.uk/
poll_interval: 60
discovery_prefix: homeassistant
base_topic: neohub
property_name: Example House
# Assign each physical hub to a building/property zone.
hub_zones:
- hub_name: Gate House
zone: Gate House
- hub_name: 2nd Floor
zone: Upper Floor
# Assign thermostat points to rooms. `zone` can override the hub zone.
room_mappings:
- hub_name: Gate House
thermostat: Kitchen
room: Kitchen
zone: Gate House
- hub_name: 2nd Floor
thermostat: G Ensuite
room: Green Ensuite
zone: Upper Floor
mqtt:
host: ""
port: 1883
username: ""
password: ""
ssl: falseStart the add-on. Within one poll cycle, Home Assistant should discover entities like:
climate.neohub_main_hub_kitchen_ufh_hub_1
sensor.neohub_main_hub_kitchen_ufh_hub_1_floor_temperature
binary_sensor.neohub_main_hub_kitchen_ufh_hub_1_window_open
switch.neohub_main_hub_garden_socket_hub_1
Use this if you want the full visual experience:
dashboards/neohub-control-premium-dashboard.yaml
Recommended optional frontend cards, commonly installed through HACS:
- Mushroom Cards
- Auto Entities
- ApexCharts Card
- Optional: Card Mod for the glassmorphism hero card styling
The premium dashboard auto-discovers entities matching:
climate.neohub_*
switch.neohub_*
sensor.neohub_*
binary_sensor.neohub_*
Use this if you want no custom frontend dependencies:
dashboards/neohub-control-basic-dashboard.yaml
Edit the example entity IDs to match your actual discovered entities.
For a hub called Main Hub, hub ID hub-1, and a zone called Kitchen UFH, the bridge creates an object ID like:
neohub_main_hub_kitchen_ufh_hub_1
Discovery:
homeassistant/climate/neohub_main_hub_kitchen_ufh_hub_1/config
State:
neohub/neohub_main_hub_kitchen_ufh_hub_1/availability
neohub/neohub_main_hub_kitchen_ufh_hub_1/current_temperature
neohub/neohub_main_hub_kitchen_ufh_hub_1/target_temperature
neohub/neohub_main_hub_kitchen_ufh_hub_1/mode
neohub/neohub_main_hub_kitchen_ufh_hub_1/action
neohub/neohub_main_hub_kitchen_ufh_hub_1/humidity
neohub/neohub_main_hub_kitchen_ufh_hub_1/floor_temperature
neohub/neohub_main_hub_kitchen_ufh_hub_1/modulation_level
neohub/neohub_main_hub_kitchen_ufh_hub_1/attributes
Commands:
neohub/neohub_main_hub_kitchen_ufh_hub_1/set_temperature
neohub/neohub_main_hub_kitchen_ufh_hub_1/set_mode
Install local development dependencies:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txtRun tests:
PYTHONPATH=. pytest -qRun the add-on bridge tests against the packaged add-on copy:
PYTHONPATH=addons/neohub_control/app pytest tests/test_ha_mqtt.py -qRun lint:
ruff check .Build and publish flow:
- Pull requests run the Home Assistant builder workflow without publishing images.
- Pushes to
masterpublishghcr.io/gitdakky/neohub-control:<version>andlatestmulti-architecture images. addons/neohub_control/config.yamlpoints Home Assistant at the pre-built GHCR image, which avoids slow and fragile local builds on Home Assistant hosts.
Working and tested locally:
- MQTT discovery payload generation
- Climate state publishing
- Socket state publishing
- Command topic routing
- Temperature command validation
- Python compile checks
- Ruff lint checks
- YAML parsing checks
Needs real-world validation:
- Live NeoHub account/device test
- Home Assistant add-on store install flow
- Live Home Assistant install/update through the GHCR image published by CI
- Long-running MQTT reconnect behaviour under broker/cloud outages
This project is designed for NeoHub-backed devices. A reported Neostat WiFi case can read data but receives an HTML redirect when attempting control endpoints such as hm_set_temp. That likely needs a separate Neostat WiFi control strategy rather than the NeoHub control path.
- Credentials are read from Home Assistant add-on options.
- Credentials are not published to MQTT.
- MQTT discovery/state topics contain hub and zone names; choose zone names accordingly if topic visibility matters in your network.
- Use a trusted MQTT broker and avoid exposing it directly to the internet.
Pull requests are welcome.
Good first contributions:
- Confirm live device compatibility
- Add reconnect/backoff hardening
- Improve socket-specific control semantics
- Add optional sensors for diagnostics
- Add Home Assistant screenshots
- Package releases and SLSA provenance for real build artifacts
Please include tests for behavior changes where practical.
MIT. See LICENSE.
Built for the Home Assistant and Heatmiser communities, with respect for people who believe their heating system should be as observable and automatable as the rest of their infrastructure.