Custom Parameters

Overview

ecoMAX firmware varies across controller models: newer models store settings in the service parameter table (EcomaxServiceParameters), and some models shift or repurpose entries in the standard parameter table (EcomaxParameters). Custom parameter modules map those entries to named parameters so they work seamlessly with Reading and Writing (ecomax.get(...) and ecomax.set(...)).

A custom module defines one or both of the following tables:

Table

Purpose

service_parameters

Maps EcomaxServiceParameters by index.

patches

Overrides EcomaxParameters by name.

To match a module to a controller, PyPlumIO converts ProductInfo model (from the UID response) into <model_slug> by replacing "-" and " " with "_" and lowercasing (for example, "ecoMAX 350P2-ZF" becomes ecomax_350p2_zf). Both the exact model string and numeric id (visible in the CLI header or via await ecomax.get("product")) must match the connected controller.

How-To Guides

Generating a Starter Module with the CLI

Use the interactive utility in Command Line Interface to connect to your controller, inspect raw EcomaxServiceParameters entries, and export a starter service_parameters module, test file, and captured frame JSON (optionally bundled as <model_slug>.zip). Saving in the CLI regenerates plain number() and switch() entries for service_parameters, so add manual patches or functools.partial helpers afterward.

Writing or Patching a Module by Hand

Create pyplumio/parameters/custom/<model_slug>.py with a module docstring, from __future__ import annotations, and a module-level PARAMETERS = custom_parameters(...) constant. See ecomax_350p2_zf.py (pyplumio/parameters/custom/ecomax_350p2_zf.py) for a complete reference.

For service_parameters, map each raw index to number() or switch(), use # comments to document enum-style numeric options, and factor repeated descriptors with functools.partial. When raw wire values are scaled or shifted, PyPlumIO unpacks them as unpacked = round((raw - offset) * step, precision):

  • Positive offset: number("heating_curve_shift", offset=20, unit="°C") maps raw 0..40 to -20..20 °C.

  • Negative offset with step: partial(number, step=10.0, offset=-30, unit="rpm") maps raw 0..255 to 300..2850 rpm.

"""Contains custom parameters for ecoMAX 860P4-NM TOUCH."""

from __future__ import annotations

from functools import partial

from pyplumio.parameters.custom import custom_parameters, number, switch

_fan_speed = partial(number, step=10.0, offset=-30, unit="rpm")

PARAMETERS = custom_parameters(
    model="ecoMAX 860P4-NM TOUCH",
    id=41,
    service_parameters={
        0: number("max_boiler_output", unit="kW"),
        11: _fan_speed("fan_speed_30"),
        # 0 - off, 1 - priority, 2 - no priority.
        90: number("water_heater_pump_mode"),
        100: switch("heat_exchanger"),
        220: number("fuel_correction", offset=20, unit="%"),
    },
)

For patches, keys are the original standard parameter names from EcomaxParameters, mapped to replacement number() or switch() descriptors (adapted from pyplumio/parameters/custom/ecomax_860d3_hb.py):

PARAMETERS = custom_parameters(
    model="ecoMAX 860D3-HB",
    id=48,
    patches={
        "disable_pump_on_thermostat": number("water_heater_target_temp", unit="°C"),
        "pump_hysteresis": switch("water_heater_disinfection"),
    },
)

Testing and Contributing

You can contribute mapped parameters in two ways:

  1. GitHub Issue: Attach the <model_slug>.zip archive exported by Command Line Interface to an issue on PyPlumIO.

  2. Pull Request: Open a PR containing all three required files:

    • pyplumio/parameters/custom/<model_slug>.py — exports PARAMETERS with model matching <model_slug>, a non-bool integer id, and non-empty service_parameters or patches.

    • tests/testdata/parameters/<model_slug>.json — real frame data captured from the controller.

    • tests/parameters/custom/test_<model_slug>.py — parametrized tests verifying each parameter’s class, value, bounds, and unit; use test_ecomax_350p2_zf.py (service_parameters) or test_ecomax_860d3_hb.py (patches) as a template.

Before opening a PR, verify the test suite and linters pass locally:

$ uv run pytest
$ prek run --all-files

DSL Reference

pyplumio.parameters.custom.custom_parameters(*, model: str, id: int, service_parameters: Mapping[int, EcomaxParameterDescription] | None = None, patches: Mapping[str, EcomaxParameterDescription] | None = None) → CustomParameters

Return custom parameters for a device model.

Parameters:
  • model (str) – Exact controller model string matching ProductInfo.model

  • id (int) – Numeric product identifier matching ProductInfo.id

  • service_parameters (Mapping[int, EcomaxParameterDescription] | None, optional) – Mapping of integer service parameter indices to number() or switch() descriptors, defaults to None

  • patches (Mapping[str, EcomaxParameterDescription] | None, optional) – Mapping of standard parameter names to replacement number() or switch() descriptors, defaults to None

Returns:

Custom parameter definition for the controller model

Return type:

CustomParameters

pyplumio.parameters.custom.number(name: str, *, step: float = 1.0, offset: int = 0, precision: int = 6, optimistic: bool = False, unit: UnitValue | UnitOfMeasurement | None = None) → EcomaxNumberDescription

Return an ecoMAX number parameter description.

Parameters:
  • name (str) – Snake-case parameter name used on the device

  • step (float, optional) – Multiplier applied to raw - offset when unpacking and divisor used when packing, defaults to 1.0

  • offset (int, optional) – Integer offset subtracted from the raw wire value before scaling, defaults to 0

  • precision (int, optional) – Number of decimal places to round unpacked values to, defaults to 6

  • optimistic (bool, optional) – Whether writes succeed immediately without waiting for controller confirmation, defaults to False

  • unit (UnitValue | UnitOfMeasurement | None, optional) – Physical unit of measurement as a UnitOfMeasurement member, supported unit string, or None, defaults to None

Returns:

Number parameter description

Return type:

EcomaxNumberDescription

Raises:

ValueError – If unit is not a recognized unit string or enum member

pyplumio.parameters.custom.switch(name: str, *, optimistic: bool = False) → EcomaxSwitchDescription

Return an ecoMAX switch parameter description.

Parameters:
  • name (str) – Snake-case parameter name used on the device

  • optimistic (bool, optional) – Whether writes succeed immediately without waiting for controller confirmation, defaults to False

Returns:

Switch parameter description

Return type:

EcomaxSwitchDescription

Supported Units

number(..., unit=...) accepts UnitOfMeasurement enum members, PERCENTAGE, None, or any string literal listed below. Passing an unrecognized string raises ValueError.

Literal

UnitOfMeasurement / Constant

Meaning

"°C"

CELSIUS

Degrees Celsius

"kW"

KILO_WATT

Kilowatts

"g"

GRAMS

Grams

"kg"

KILOGRAMS

Kilograms

"kWh/kg"

KILO_WATT_HOUR_PER_KILOGRAM

Kilowatt-hours per kilogram

"kg/h"

KILOGRAMS_PER_HOUR

Kilograms per hour

"s"

SECONDS

Seconds

"min"

MINUTES

Minutes

"days"

DAYS

Days

"Pa"

PASCAL

Pascals

"rpm"

REVOLUTIONS_PER_MINUTE

Revolutions per minute

"%"

PERCENTAGE

Percentage