/homeassistant-plum-ecomax

Plum ecoMAX boiler controller integration for Home Assistant.

Primary LanguagePythonMIT LicenseMIT

Plum ecoMAX boiler controller integration for Home Assistant.

ci Test Coverage Code style: black hacs_badge stability-release-candidate

Overview

This Home Assistant integration provides support for ecoMAX controllers manufactured by Plum Sp. z o.o.

It's based on PyPlumIO package and supports connection to ecoMAX controller via RS-485 to Ethernet/Wifi converters or via RS-485 to USB adapter.

ecoMAX controllers

Table of contents

Connect the ecoMAX

With this integration you have two ways of connecting to your ecoMAX controller. One is directly connecting the PC that runs Home Assistant via RS485 to USB adapter.

Other way is to use RS485 to WiFi converter. This has a benefit of being able to move PC that runs Home Assistant away from the boiler and connect to it wirelessly.

RS485 adapter and converters

Regardless of the chosen method, you'll need to find RS485 port on your ecoMAX controller. If you have ecoSTER thermostat, it's easy, as ecoSTERs also use RS485 port and you'll just have to connect your adapter/converter in parallel with it.

If you don't have ecoSTER, look for pins that are labeled as "D+" and "D-" then connect your device as follows:

Adapter ->  ecoMAX
[A]     ->  [D+]
[B]     ->  [D-]
[GND]   ->  [GND] (optional, less interference)

ecoNET 300

While this integration is built on top of PyPlumIO library, which from the start was intended as ecoNET 300 alternative, Patryk B is currently developing awesome HASS integration that communicates with ecoMAX controller via ecoNET 300 device.

If you have an ecoNET 300 device, be sure to check it out!

Installation

HACS

Click the following My button to install the integration via hacs:

Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.

HACS is recommended method to install and update the plum-ecomax integration.
If you still don't use it, give it a try, I'm sure you'll love it!

Manual

  1. Clone this repository with:
git clone https://github.com/denpamusic/homeassistant-plum-ecomax
  1. Move custom_components directory from homeassistant-plum-ecomax to your Home Assistant configuration directory. (next to configuration.yaml)
cp -r ./homeassistant-plum-ecomax/custom_components ~/.homeassistant
  1. Add empty plum_ecomax: section to your configuration.yaml file.
  2. Restart Home Assistant.

Configuration

Adding Plum ecoMAX integration to your Home Assistant instance can be done via user interface, by using this My button:

Add integration

Manual Configuration Steps

If the above My button doesn’t work, you can also perform the following steps manually:

  1. Browse to your Home Assistant instance.
  2. In the sidebar click on Settings.
  3. From the configuration menu select: Devices & Services.
  4. In the bottom right, click on the Add Integration button.
  5. From the list, search and select "Plum ecoMAX".

Search dialog

  1. Select you connection type. Choose serial port if your ecoMAX controller is connected directly to the PC that is running Home Assistant, choose network if ecoMAX is connected via RS-485 to WiFi converter

Menu

To connect via the network you'll need to fill in Host and Port:

TCP

To connect via serial port you'll need to fill in the Device path and Baudrate:

serial

⚠️ If you're running your Home Assistant in the docker container, don't forget to map your adapter/converter device, as described here.

  1. Your device should now be available in your Home Assistant installation.

Success

Entities

This integration provides the following entities, split between controller device and sub-devices.

Not all entities might be available for your controller model and entities that are deemed as unsupported during initial setup will be disabled.

ecoMAX pellet boiler controller model names has a "p" suffix (e. g. ecoMAX 850p), ecoMAX installation controller model names have an "i" suffix (e. g. ecoMAX 850i).

Controller (Hub)

Following section lists entities that are added to the ecoMAX device.

Sensors

Sensors can have numerical or text state. Temperature changes that are less than 0.1°C are ignored.

Name Unit ecoMAX pellet ecoMAX installation
Heating temperature °C
Water heater temperature °C
Outside temperature °C
Heating target temperature °C
Water heater target temperature °C
Heating mode n/a
Solar temperature °C
Fireplace temperature °C
Exhaust temperature °C
Feeder temperature °C
Return temperature °C
Heating load %
Fan power %
Fuel level %
Fuel consumption kg
Total fuel burned 1 kg
Heating power kW
Lower buffer temperature 2 °C
Upper buffer temperature 2 °C
Flame intensity 2 %
Oxygen level 3 %

1 Special meter entity. It counts burned fuel when HomeAssistant is running.
2 Controller support is required.
3 ecoLAMBDA module is required.

Binary sensors

Binary sensors have two states (on/off, running/not running, etc.).

Name ecoMAX pellet ecoMAX installation
Heating pump state
Water heater pump state
Circulation pump state
Fireplace pump state
Solar pump state
Fan state
Lighter state
Exhaust fan state

Selects

Select entites can have multiple options to choose from.

Name Options ecoMAX pellet ecoMAX installation
Summer mode Off, Auto, On

Switches

Switches have two states (on/off) that can be switched between.

Name ecoMAX pellet ecoMAX installation
Controller power switch
Water heater disinfection switch
Water heater pump switch
Weather control switch
Fuzzy logic switch
Heating schedule switch
Water heater schedule switch

Numbers

Numbers are represented as changeable sliders or input boxes.

Name Unit Style ecoMAX pellet ecoMAX installation
Heating temperature °C slider
Minimum heating power % slider
Maximum heating power % slider
Minimum heating temperature °C slider
Maximum heating temperature °C slider
Grate mode temperature °C slider
Fuel calorific value kWh/kg box

Diagnostics

Diagnostics are random entities that provide you with service and debug information.

Name Type ecoMAX pellet ecoMAX installation
Alert Binary sensor
Connection status Binary sensor
Service password Text sensor
UID Text sensor
Software version Text sensor
Detect sub-devices Button

Water heater

The integration provides full control for the connected indirect water heater using Home Assistant's internal water heater platform.

This includes ability to set target temperature, switch into priority, non-priority mode or turn off.

Please note, that due to the way base water heater entity is implemented, custom modes are not allowed. Please use the following reference table to convert between water heater operation modes displayed in Home Assistant and ecoMAX.

HomeAssistant ecoMAX
Off On
Performance Priority mode
Eco Non-priority mode

Thermostats

This integration provides Home Assistant's climate platform entity for each ecoSTER thermostat connected to the ecoMAX controller.

This allows to check current room temperature, set target room temperature and change between ecoSTER operation modes.

Climate card

Mixers/Circuits (Sub-devices)

Following section lists entities that are added to each sub-device.

Please note, that for ecoMAX installation ("i") controllers mixers are renamed to circuits.

Mixers/Circuits are added as sub-devices for the ecoMAX controller.
Sub-devices detected only once, when integration is added to HomeAssistant.
If you connected them after setting up the integration, you can use Detect sub-devices button in Diagnostics section to force detection of new sub-devices.

Sensors

Name Unit ecoMAX pellet ecoMAX installation
Mixer temperature °C
Target mixer temperature °C

Binary sensors

Name ecoMAX pellet ecoMAX installation
Mixer pump

Selects

Name Options ecoMAX pellet ecoMAX installation
Work mode Off, Heating, Floor, Pump only

Switches

Name ecoMAX pellet ecoMAX installation
Enable in summer mode
Enable mixer
Weather control
Disable pump on thermostat

Numbers

Name Unit Style ecoMAX pellet ecoMAX installation
Mixer temperature °C slider
Minimum mixer temperature °C slider
Maximum mixer temperature °C slider
Day target mixer temperature 1 °C slider
Night target mixer temperature 1 °C slider

1 Only available on second circuit.

Device-specific entities

These entities are only available for specific devices.

Sensors

Name Unit Model Product ID Data key
Ash pan full % ecoMAX 860P3-O 51 227

Events

This integration fires following events:

plum_ecomax_alert

This event is fired when ecoMAX controller issues an alert.

Event data

Name Description
name Config entry name. By default is set to the device model.
code Alert code. List of known codes is available here.
from Datetime object representing the alert start time.
to 1 Datetime object representing the alert end time.

1 Only present if the alert has already ended.

Services

This integration provides following services:

Set parameter

Provides ability to set device/sub-device parameter by name. Any parameter that is supported by the device/sub-device can be used with this service. To get parameter names, please download and open diagnostics data.

Fields

Field Type Description
name string Name of the parameter.
value number, "on", "off" Value of the parameter.

Targets

Device 1 Description
ecoMAX Set parameter on the ecoMAX controller.
Mixer Set parameter on the mixer sub-device.

1 Device can be targeted via any selector: area, device or entity.

Calibrate meter

Allows to set meter entity to a specific value.
Currently this can be used to set a value of a Total fuel burned sensor which is only available on pellet burner controllers.

Fields

Field Type Description
value integer Set target sensor to this value.

Targets

Entity Description
total_fuel_burned Counts total burned fuel in kilograms.

Reset meter

Allows to reset the meter entity value.
Currently this can be used to reset a value of the Total fuel burned sensor which is only available on pellet burner controllers.

Targets

Entity Description
total_fuel_burned Counts total burned fuel in kilograms.

License

This product is distributed under MIT license.