Skip to content
HeatSync

Home Assistant integration

HeatSync surfaces in Home Assistant two ways — a custom HACS integration that polls the device’s local HTTP API, or MQTT auto-discovery using a broker you already have. Both ship the same core entities (climate, water heater, ~50 sensors). Pick one; running both gives you duplicate entities.

Which path?

Section titled “Which path?”
HACS integrationMQTT auto-discovery
Setup frictionOne HACS install + API tokenConfigure MQTT broker on both sides
Broker neededNoYes (e.g. HA’s Mosquitto add-on)
Latency~5 s (poll cadence)< 1 s (push)
Tariff / cost / carbon sensors✅ built-in (firmware-computed)✅ via the firmware’s published topics
HA quality-scale tierSilver, climbingUses HA core’s MQTT integration
Best forQuick start, no infrastructureAnyone already running MQTT

TL;DR: If you don’t have an MQTT broker, use the HACS integration. If you already run Mosquitto for other devices, MQTT is sub-second and HA-idiomatic.

Path A — HACS custom integration

Section titled “Path A — HACS custom integration”

Repo: github.com/dr-harper/heatsync-ha

Install

Section titled “Install”

Open HACS, add this integration

The button uses Home Assistant’s My Home Assistant deep-link service — it opens HACS on your instance with the repo URL pre-filled. After it adds, click HeatSync in the integrations list, hit Download, then restart Home Assistant. If the link doesn’t work (HACS not installed, or My Home Assistant disabled), fall back to the manual steps:

  1. HACS → Integrations → ⋯ → Custom repositories
  2. Add https://github.com/dr-harper/heatsync-ha as type Integration.
  3. Click HeatSync in the list → Download.
  4. Restart Home Assistant.

Setup

Section titled “Setup”
  1. On the HeatSync device, go to Settings → Home Assistant, scroll to the API token card, click Generate token. Copy the token (shown only once).
  2. In HA: Settings → Devices & Services → Add Integration → HeatSync. If your device is mDNS-discoverable (heatsync.local), HA auto-discovers it — otherwise enter the host (IP or .local) and paste the token.

What you get

Section titled “What you get”
EntityTypeNotes
Heat pumpclimateMode (heat / cool / auto / off), target, room temp
Hot waterwater_heaterPower + target + mode (eco / standard / power / force)
Water-law offsetnumber±5 °C heating-curve dial
Quiet mode, AwayswitchQuiet caps compressor RPM; Away applies a setback
Heating boost, DHW boostbuttonOne-shot +1 °C / +5 °C for 1 hour
Tank temp, Flow actual / target, Eva in / out, Water inlet, Flow rate, Humidity, Thermal powersensorIndoor-unit telemetry
Outdoor temp, Discharge / Suction temp, Power, Energy, Current, Voltage, Compressor freq, Fan RPM, Cycles/hour, Error codesensorOutdoor-unit + electrical
Water pump, Compressor, Fault, Backup heater, DHW booster heaterbinary_sensorRunning flags
Energy today, Cost today, Tariff rate, Tariff bucket, Carbon intensitysensorToday’s running totals — firmware-computed
Energy today (heating / hot water / defrost / standby)sensorPer-mode kWh split — opt-in
Energy yesterday, COP yesterday, Outdoor avg yesterdaysensorStable daily summary; COP-yesterday is the headline efficiency KPI
Cylinder volume, Cylinder loss, DHW last duration, Live COP, ΔT water, Capacity used, Building UAsensorDerived metrics — what HeatSync has learned about your system
Chip temperature, WiFi signal, Heap free, UptimesensorDevice diagnostics

All entities sit under a single HeatSync device card in HA’s UI.

Polling cadence

Section titled “Polling cadence”

The integration polls /api/live every 5 s plus a slower fetch of /api/cost/status + /api/carbon/status every 60 s, and /api/energy/daily hourly. Adding entities doesn’t add HTTP load — they all read from the shared coordinator state.

Path B — MQTT auto-discovery

Section titled “Path B — MQTT auto-discovery”

HeatSync’s firmware speaks the Home Assistant MQTT discovery spec natively — it’ll publish discovery payloads for ~50 entities the moment you point it at a broker.

Setup

Section titled “Setup”

You need an MQTT broker reachable from both Home Assistant and HeatSync. The simplest setup is the Mosquitto broker add-on inside Home Assistant itself.

  1. In HA, install the Mosquitto broker add-on (Settings → Add-ons → Add-on Store → Official Add-ons).
  2. Start it. Note the username/password — usually a regular HA user.
  3. On the HeatSync device, go to Settings → Home Assistant:
    • MQTT host: the Home Assistant IP
    • MQTT port: 1883
    • MQTT user / pass: as configured in step 2 (leave blank if your broker allows anonymous)
    • Topic prefix: samsung (default — fine to leave)
    • HA discovery prefix: homeassistant
    • HA discovery: enabled
  4. Save. HeatSync reconnects to MQTT and publishes discovery payloads.

Within 10 seconds the HeatSync device appears under Settings → Devices & Services → MQTT with the same entity set as Path A (minus four HA-side-only diagnostic sensors that come from the integration’s polling layer).

Energy dashboard

Section titled “Energy dashboard”

Both paths expose sensor.energy (lifetime kWh consumed) and sensor.energy_generated (lifetime kWh thermal delivered) with the correct device class + total_increasing state class for the Home Assistant Energy Dashboard:

  1. Settings → Dashboards → Energy.
  2. Under Individual devices, add HeatSync’s Energy sensor as consumption.
  3. Optionally add Energy generated as a heat-energy contribution to track delivered vs. consumed (visualises SCOP).

HACS integration users also get sensor.cost_today (GBP, monetary device-class) which slots into the dashboard’s running-cost tile, and sensor.carbon_intensity with the region as an attribute.

Template recipes

Section titled “Template recipes”

Useful formulas to drop into configuration.yaml. Recipes still work with both integration paths — but if you’re on the HACS path, many of these are already shipped as native entities (sensor.live_cop, sensor.cop_yesterday, sensor.dt_water, etc.) so you can skip maintaining your own.

Lifetime SCOP

Section titled “Lifetime SCOP”
template:
  - sensor:
      - name: "HeatSync lifetime SCOP"
        unit_of_measurement: ""
        icon: mdi:gauge
        state: >-
          {% set gen = states('sensor.heatsync_energy_generated') | float(0) %}
          {% set con = states('sensor.heatsync_energy') | float(0) %}
          {{ (gen / con) | round(2) if con > 0 else 'n/a' }}

Instantaneous COP

Section titled “Instantaneous COP”

Already shipped as sensor.live_cop on the HACS path. For MQTT-only setups:

template:
  - sensor:
      - name: "HeatSync instant COP"
        unit_of_measurement: ""
        availability: "{{ states('binary_sensor.heatsync_compressor') == 'on' }}"
        state: >-
          {% set p = states('sensor.heatsync_power') | float(0) %}
          {# Heat output ≈ flow_rate (L/min) × ΔT × 4.18 / 60 kW #}
          {% set flow = states('sensor.heatsync_flow_rate') | float(0) %}
          {% set tin  = states('sensor.heatsync_water_inlet') | float(0) %}
          {% set tout = states('sensor.heatsync_flow_actual') | float(0) %}
          {% set heat_kw = (flow * (tout - tin) * 4.18 / 60) %}
          {{ (heat_kw * 1000 / p) | round(2) if p > 100 else 'n/a' }}

Fault notification

Section titled “Fault notification”
automation:
  - alias: "Heat pump fault notification"
    trigger:
      - platform: state
        entity_id: binary_sensor.heatsync_fault
        to: "on"
    action:
      - service: notify.mobile_app_your_phone
        data:
          title: "Heat pump fault"
          message: "Check the HeatSync dashboard."

Troubleshooting

Section titled “Troubleshooting”

HACS path

Section titled “HACS path”

Integration won’t add — “cannot_connect”. Verify the device is reachable from HA: curl -H "Authorization: Bearer <token>" http://heatsync.local/api/status.

Token rejected — reauth flow appears. Generate a fresh token on the device (Settings → Home Assistant → API token → Generate, then Revoke the old one for hygiene).

Entities stuck “Unavailable”. Check the integration’s “Diagnostics” download — the coordinator’s last_exception field will name the cause (network, parse error, bad token).

MQTT path

Section titled “MQTT path”

Entities don’t appear after enabling discovery. Check the HeatSync events log (/api/events) — look for an [ha] line saying discovery was published. If not, MQTT isn’t connecting — check /api/status for mqtt.state.

Controls don’t work from HA. Bus writes must be enabled on Settings → Device → Bus & sensors. The climate entity drops back to read-only when writes are off (the command topic isn’t published).

Entity names not what you want. HA’s entity ID is derived from the discovery payload’s name field. You can rename entities or set custom friendly names in the HA UI without HeatSync caring.