Control a Duepi pellet stove from Home Assistant, either through the dpremoteiot.com cloud API or through the Duepi relay server used by the MyDPRemote app.
- Two transports — dpremoteiot.com account, or the Duepi relay (no account needed, reads the stove's real running power, fumes temperature, phase and error code)
- Native Climate entity — full HVAC control with temperature and power level, using the stove's built-in temperature sensor
- Auto-login — authenticates with email/password, auto-renews the session when it expires (no more manual cookie extraction!)
- Automatic stove discovery — sign in and select a stove without hunting for its device ID
- Config flow UI — set up entirely from the Home Assistant UI (Settings → Add Integration)
- Eco and Comfort presets — switch temperature and power together from the climate entity
- Rich diagnostics — alarms, problem state, last-seen time, operating hours, and estimated pellet use
- HACS compatible — install easily via HACS custom repository
- Reauth flow — automatically prompts for new credentials if authentication fails
- Diagnostics — built-in diagnostic dump for troubleshooting
- A Duepi Remote Wifi module connected to your stove. Examples: poelediscount.com, lafrancaisedupoele.fr
- For the cloud transport: an account on dpremoteiot.com with your stove added.
- For the Duepi relay transport: the module's device code (printed on the module label) and the relay server and port shown in the MyDPRemote app settings (for example
duepiwebserver4.com, port3000; each module may use a different server). - Home Assistant 2024.6.0 or later.
HACS (Home Assistant Community Store) is the easiest way to install custom integrations.
Don't have HACS yet? Follow the official HACS installation guide first.
- In Home Assistant, go to HACS → Integrations.
- Click the ⋮ (3-dot menu) in the top-right corner → Custom repositories.
- In the dialog that opens:
- Repository:
https://github.com/FlorianCasse/DuepiRemoteHA - Category: select Integration
- Click Add.
- Repository:
- Close the dialog. Search for Duepi Pellet Stove in the HACS integration list.
- Click Download and confirm.
- Restart Home Assistant (Settings → System → Restart).
Use this method if you don't want to use HACS.
- Download or clone this repository.
- Copy the entire
custom_components/duepi/folder into your Home Assistant configuration directory:<your HA config>/ └── custom_components/ └── duepi/ ├── __init__.py ├── manifest.json ├── api.py ├── climate.py ├── ...Tip: The HA config directory is
/homeassistant/on Home Assistant OS 17+,/config/on older HA OS/Supervised, or~/.homeassistant/for Core installations. - Restart Home Assistant (Settings → System → Restart).
Once the integration is installed and HA has restarted:
- Go to Settings → Devices & Services.
- Click + Add Integration (bottom-right).
- Search for Duepi Pellet Stove and select it.
- Choose how Home Assistant reaches the stove: dpremoteiot.com account or Duepi relay.
dpremoteiot.com account
- Enter your dpremoteiot.com email and password.
- Select the stove discovered on your account. Selection is shown even when the account contains only one stove.
- Click Submit. A new Duepi Pellet Stove device appears with all its entities.
If the dashboard format prevents automatic discovery, the flow falls back to a manual Device ID field. Existing installations keep their current device ID and do not need to be reconfigured.
Authentication failed? Double-check your email and password. Make sure you can log in to dpremoteiot.com with the same credentials in a browser.
Duepi relay
- Enter the relay server and port from the MyDPRemote app settings, and the device code from the module label (4 to 32 letters or digits).
- Click Submit. Home Assistant reads the stove once to check the code, then creates the device.
The device code stays in the Home Assistant configuration; it is never logged and is redacted from diagnostics. "The stove did not answer with this device code" most often means the code is wrong (a corrupted reply gives the same message); "Cannot reach the Duepi relay" most often means the server or port is wrong (a timeout, a dropped connection or an unreadable reply gives the same message, so retry once before changing the settings).
- Go to Settings → Devices & Services → Duepi Pellet Stove.
- Click Configure.
| Option | Default | Description |
|---|---|---|
| Update interval | 30s | How often to poll the stove state (min: 30s) |
| Comfort/default power | 1 | Power level used for Comfort and normal turn-on (1-5) |
| Comfort/default temperature | 25°C | Temperature used for Comfort and normal turn-on (5-40°C) |
| Eco power | 1 | Power level used by the Eco preset (1-5) |
| Eco temperature | 18°C | Temperature used by the Eco preset (5-40°C) |
| Pellet rate at power 1 | 0.6 kg/h | Estimated minimum consumption rate (0-10 kg/h) |
| Pellet rate at power 5 | 1.8 kg/h | Estimated maximum consumption rate (0-10 kg/h) |
The minimum pellet rate must not exceed the maximum. Changing any option reloads the integration automatically.
All entities are grouped under a single Duepi Pellet Stove device:
| Entity | Type | Description |
|---|---|---|
| Duepi Pellet Stove | Climate | Main control — HVAC mode, target temperature, power 1-5, and Eco/Comfort presets |
| Room temperature | Sensor | Current room temperature from the stove's built-in sensor (°C) |
| Power level | Sensor | Current working power level (1-5) |
| Status | Sensor | Status text (Heating, Idle, Standby, Off...) |
| Set temperature | Sensor | Current target temperature (°C) |
| Online | Binary sensor | Whether the stove is reachable through its transport (dpremoteiot.com or the Duepi relay) |
| Problem | Binary sensor | Active when an alarm field or alarm/error status is reported |
| Alarm | Sensor | Cloud alarm text/code, or E<code> from the relay error code; disabled by default because fields vary by stove |
| Last seen | Sensor | Last UTC time the cloud explicitly reported the stove online, or the relay last read it |
| Operating hours | Sensor | Restored cumulative time while the stove is on |
| Pellet consumption (estimated) | Sensor | Restored consumption estimate based on runtime and power, disabled by default |
| Power level | Number | Slider to adjust power level (1-5) |
| Real power | Sensor | Relay only. Power level the stove actually runs at, as shown on the stove display (0 when off); it modulates below the setting |
| Power setting | Sensor | Relay only. Power level set on the stove (panel, MyDPRemote or Home Assistant) |
| Fumes temperature | Sensor | Relay only. Flue gas temperature (°C) |
| Phase code | Sensor | Relay only, diagnostic. Raw operating phase reported by the stove |
| Error code | Sensor | Relay only, diagnostic. Raw stove error code (0 = none) |
With the relay transport, the Power level slider, sensor and presets follow the stove's own power setting, including changes made on the panel; Real power shows the level it runs at. Right after each brazier cleaning (about every 30 minutes) the stove restarts at power 1 for a few seconds before returning to its setting.
The stove does not report its target temperature to the relay, so the thermostat shows the last target set from Home Assistant (initially the Comfort/default temperature option). This value is kept in memory only: after a Home Assistant restart, an integration reload or an option change, it returns to the Comfort/default temperature and a target waiting to be sent is dropped. A target changed on the stove panel is not visible in Home Assistant.
The cloud can briefly report a healthy stove offline during its periodic heartbeat. The integration waits 120 seconds before publishing a disconnect, while restoring connectivity immediately on the next online report.
If you were using the previous stoveOnOff.py + command_line setup, an interactive migration script is provided to guide you through the process.
The script can run locally on your HA instance or remotely from your computer via SSH.
If you have direct access to the HA terminal (SSH add-on, console, etc.), first copy migrate.py from the root of this repository to /config/scripts/ (neither installation method above installs it), then run:
python3 /config/scripts/migrate.pyRun the script from your computer — it connects to HA via SSH and performs all operations remotely:
# Basic usage (default SSH port 22):
python3 migrate.py --ssh root@homeassistant
# With a custom SSH port (e.g. Home Assistant OS uses port 22222):
python3 migrate.py --ssh root@192.168.1.100 --port 22222
# With a specific SSH key:
python3 migrate.py --ssh root@homeassistant --key ~/.ssh/ha_key
# Non-interactive mode (auto-confirm backup/removal, useful for scripting):
python3 migrate.py --ssh root@homeassistant --no-interactive
# Custom HA config directory (default is /config):
python3 migrate.py --ssh root@homeassistant --config /home/homeassistant/.homeassistant
# Rollback — restore old files and remove the custom integration:
python3 migrate.py --rollback
python3 migrate.py --rollback --ssh root@homeassistant| Option | Default | Description |
|---|---|---|
--ssh USER@HOST |
(local) | SSH destination for remote execution |
--port PORT |
22 |
SSH port (HA OS typically uses 22222) |
--key PATH |
(none) | Path to SSH private key file |
--config PATH |
/config |
HA config directory on the target machine |
--rollback |
(off) | Restore old files from backup and remove the custom integration |
--no-interactive |
(off) | Skip confirmation prompts (auto-yes) |
- Detects the old installation (
stoveOnOff.pyand.envin/config/scripts/) - Reads your old
.envto extract the Device ID and default settings - Scans
configuration.yamlforcommand_lineandgeneric_thermostatentries to remove - Checks if the new
custom_components/duepiintegration is already installed - Backs up old files to
/config/duepi_migration_backup/then removes them - Prints step-by-step instructions to finish the migration in the HA UI
============================================================
Duepi Pellet Stove — Migration Script
============================================================
Mode: SSH remote → root@192.168.1.100
HA config: /config
[Step 1] Detecting old installation
✓ Found old script: /config/scripts/stoveOnOff.py
✓ Found old .env: /config/scripts/.env
[Step 2] Reading old credentials
✓ Device ID: a1b2c3d4e5f6...
✓ Session cookie found (will NOT be migrated — new integration uses email/password)
✓ Default power: 5
✓ Default temperature: 25°C
[Step 3] Scanning configuration.yaml for old entries
⚠ Found command_line references to stoveOnOff.py:
command_on: "python3 /config/scripts/stoveOnOff.py on"
command_off: "python3 /config/scripts/stoveOnOff.py off"
command_state: "python3 /config/scripts/stoveOnOff.py status"
✓ No generic_thermostat stove entries found
[Step 4] Checking new custom integration
✓ New integration already installed at custom_components/duepi/
[Step 5] Backup and cleanup
✓ Backed up: /config/scripts/stoveOnOff.py → /config/duepi_migration_backup/
✓ Backed up: /config/scripts/.env → /config/duepi_migration_backup/
✓ Removed: /config/scripts/stoveOnOff.py
✓ Removed: /config/scripts/.env
[Step 6] Next steps
...
If the new integration doesn't work as expected, you can rollback to the old script-based setup:
# Locally:
python3 migrate.py --rollback
# Or via SSH:
python3 migrate.py --rollback --ssh root@homeassistantThe rollback will:
- Restore
stoveOnOff.pyand.envfrom the backup to/config/scripts/ - Remove the
custom_components/duepi/integration - Clean up the backup directory
- Print instructions to re-add old YAML configuration and restart HA
Note: The rollback only restores the script files. You will need to manually re-add the
command_lineandgeneric_thermostatentries to yourconfiguration.yaml(see thelegacy/folder for reference configs).
If you prefer to migrate manually without the script:
- Install the custom integration (see Installation).
- Remove from your
configuration.yaml:- The
command_lineswitch and sensor entries referencingstoveOnOff.py - The
generic_thermostatclimate entry (if used)
- The
- Restart Home Assistant.
- Add the integration via the UI, choose dpremoteiot.com account, and enter your dpremoteiot.com email and password.
- Delete
/config/scripts/stoveOnOff.pyand/config/scripts/.env. - Update any automations using the entity mapping below.
| Old entity | New entity |
|---|---|
switch.pellet_stove |
climate.duepi_pellet_stove |
sensor.pellet_stove_info (room_temperature) |
sensor.duepi_pellet_stove_room_temperature |
sensor.pellet_stove_info (working_power) |
sensor.duepi_pellet_stove_power_level |
sensor.pellet_stove_info (status_text) |
sensor.duepi_pellet_stove_status |
sensor.pellet_stove_info (online) |
binary_sensor.duepi_pellet_stove_online |
The old script files are preserved in the legacy/ folder of this repository for reference.
On the Duepi module, a power command sent to a stopped stove starts the ignition. The relay transport therefore:
- starts the stove only from an explicit turn on (climate on / HVAC mode heat), and only when the stove reads as off, with no error code and no running power; a second start is refused for one minute, even if the first one's answer was lost ("The stove cannot be started now…"); presets and power changes never ignite it;
- after a turn off from Home Assistant, refuses power changes until the stove is seen off or shutting down (10 minutes at most), so a late command cannot cancel the shutdown;
- for one minute after the integration is loaded or reloaded, refuses starts and power changes (the safety state above is kept in memory only);
- before changing the power, reads the phase and the real power in the same connection and refuses the command unless the stove is in stable heating ("The stove is not heating…"); a target temperature set while the stove is not in stable heating is held back and sent once it is;
- never sends the target temperature to a stopped stove: on turn on it sends only the power command, then sends the target once the stove reaches stable heating, if it does so within an hour of that start. A target set while the stove is off is never sent to a stove started from its panel or MyDPRemote, which keeps its own target; a start from Home Assistant sends the default (Comfort) or preset target instead. A target changed while a stove started from Home Assistant is still igniting (within an hour of that start) is sent once it reaches stable heating. The stove does not acknowledge a target temperature in a verifiable way, so Home Assistant cannot confirm it was applied;
- only sends a fixed list of commands (power 1-5, off, target temperature).
One risk remains: if someone stops the stove from its panel or from MyDPRemote in the fraction of a second between that check and the command, the command can restart it. Home Assistant cannot rule this out; avoid changing the power from two places at the same moment.
The Duepi protocol sends the device code unencrypted to the relay at each connection, and the encryption key is derived from that code. Anyone who sees the code (on the module label, on the network path, or the relay operator) can control the stove, including starting it, and the safety checks above trust what the relay reports. Treat the device code like a password.
To enable debug logs, add the following to your configuration.yaml:
logger:
default: warning
logs:
custom_components.duepi: debugRestart Home Assistant and view the logs:
- From the HA OS terminal:
docker logs homeassistant 2>&1 | grep -i duepi - From Studio Code Server / File Editor: open the
home-assistant.logfile
Note: The Settings → System → Logs page only shows warnings and errors. Debug/info logs are only visible in the full log file or via
docker logs.
With the Duepi relay transport:
- The stove became unavailable after its device code or relay server changed — a relay entry cannot be edited yet. Delete the entry in Settings → Devices & Services → Duepi Pellet Stove, then add it again with the new code, server and port.
- "The Duepi relay is busy; try again" — another poll or command was still talking to the relay. Wait a few seconds and try again.
- Power level may be ignored on startup — some stove models always start at a fixed power level regardless of the
settedPowervalue. When the stove is turned on from Home Assistant, the integration re-sends the desired power once, when the stove first reports nominal heating, so the configured level applies after ignition. Stoves started from their panel or the vendor app are left alone. This only applies to the cloud transport: the relay reads the real power, so it does not need the re-send. - Cloud dependency — both transports require internet connectivity: dpremoteiot.com for the cloud transport, the Duepi relay server for the relay transport. Neither talks to the stove over the local network.
- Relay phases — phase codes were mapped on one stove: off, ignition, stable heating, brazier cleaning and shutdown (shown as off while it cools down). Any other code shows as "Phase N" and is treated as not heating, so power and target changes are refused while it is shown. Please report the phase codes your stove goes through, especially on Hydro models.
- Relay and MyDPRemote — Home Assistant opens a short connection to the relay at each poll (about 1 s every 30 s). Whether MyDPRemote keeps working at the same time has not been confirmed yet; please report it.
- No relay reconfigure step — the server, port and device code of a relay entry cannot be changed in place; delete and re-add the entry.
- HTML scraping fallback — state detection primarily uses JSON data embedded in the dashboard HTML, with regex parsing as a fallback. If dpremoteiot.com changes their layout, the integration may need updating.
- Estimated pellet use — consumption is calculated from configured rates and observed power, not measured by the stove. Gaps are capped to avoid counting through long outages or restarts.