Naturela pellet boiler — Home Assistant integration

Share your Projects! Custom Integrations
1

Naturela Smarthome — Home Assistant integration is live

Two and a half years after my own message above (“an HA integration would be welcome”), I finally sat down and built it. It’s now running stable on my own Naturela BurnerTouch boiler and it’s published on GitHub:

Repo: GitHub - cjjagtenberg/naturela_smarthome: Home Assistant custom integration for Naturela BurnerTouch pellet stoves (iot.naturela-bg.com) · GitHub
Latest release: v1.2.0
License: MIT
HACS: custom repository (works with the standard HACS workflow)

For anyone with a Naturela pellet stove or boiler that uses the BurnerTouch controller (NPBC_V6T_2, firmware ≥ 65, the same hardware behind the **iot.naturela-bg.com**web portal and the Naturela Smart mobile app), this should drop straight in. No firmware mods, no local hardware, no MQTT bridge — it talks to the existing cloud API that the official app already uses.

What you get

Climate entity

  • On / off
  • Setpoint 30–85 °C
  • Current boiler temperature
  • HVAC mode reflects real stove status (Standby / Heating / Cooling / Cleaning / Error)

Sensors

Entity Unit Notes
Boiler temperature °C Current boiler water
Target temperature °C Setpoint
Flue temperature °C Chimney / exhaust
DHW temperature °C Hot water tank
Burner stage 1–5 Combustion stage
Thermal power kW Calculated output
Flame level 0–5 Combustion intensity
Pellet consumption kg Total since install
Output level % Power percentage
Status text Standby / Firing / Working / Cleaning / Cooling / Error
Status code int Raw numeric code (0,1,2,3,5,6,7,8,10)

Binary sensors

  • CH pump
  • DHW pump
  • Ignition active
  • Cleaning active
  • Thermostat input
  • External stop input

Installation

Option 1 — HACS (recommended)

  1. In Home Assistant: HACS → Integrations
  2. Top-right ⋮ menu → Custom repositories
  3. Add https://github.com/cjjagtenberg/naturela_smarthome as type Integration
  4. Search for Naturela Smarthome and click Download
  5. Restart Home Assistant
  6. Settings → Devices & services → Add integration→ search for Naturela Smarthome

Option 2 — Manual

  1. Copy the folder custom_components/naturela_smarthome/ from the repo into your HA config directory:
<config>/custom_components/naturela_smarthome/
  1. Restart HA
  2. Settings → Devices & services → Add integration→ search for Naturela Smarthome

Configuration

The config flow asks for four things:

Field Example How to find it
Email [email protected] Same login you use for iot.naturela-bg.com / the Naturela Smart app
Password •••••••• Same password
Device ID #### Log in to iot.naturela-bg.com in a browser, open your stove — the URL contains /#/device/burnertouch/####
Poll interval 30 Seconds between cloud polls (default 30, minimum 10)

That’s it — the integration logs in (CSRF-token handled automatically), creates one device with all entities listed above, and starts polling.

Optional: Lovelace dashboard card

A custom card called naturela-pellet-card.js ships in the repo. It shows boiler status, flue temperature, thermal power, pump activity and a coloured header that follows the burner state.

  1. Copy naturela-pellet-card.js to <config>/www/
  2. Settings → Dashboards → Resources → Add resource
  • URL: /local/naturela-pellet-card.js
  • Type: JavaScript module
  1. Add to your dashboard:
type: custom:naturela-pellet-card
climate_entity: climate.pellet_stove
boiler_sensor: sensor.pellet_stove_boiler_temperature
flue_sensor: sensor.pellet_stove_flue_gas_temperature
power_sensor: sensor.pellet_stove_thermal_output
status_sensor: sensor.pellet_stove_status
alarm_sensor: sensor.pellet_stove_alarm

(Replace <your_stove> with whatever name HA gives the device — mine is schuurkachel.)

Known limitations

  • Cloud-only — needs an active internet connection (no local API on the BurnerTouch as far as I could find)
  • The Naturela “Timer mode” (State = 2) cannot be set from HA yet
  • Status-code mapping is partly reverse-engineered; if your stove reports a code I haven’t covered, please open an issue with a screenshot and I’ll add it
  • Tested on firmware 65; older firmwares may behave differently

Help wanted

If you have a different BurnerTouch model or firmware, I’d love to hear what works and what doesn’t. Issues and PRs welcome on the repo. The Dutch UI strings are easy to translate — happy to merge an en.json if anyone wants to take a swing at it.

Hope this saves the next person the weekend I spent on it.

— Cor (cjjagtenberg)