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 |
|---|---|
|
Maps EcomaxServiceParameters by index. |
|
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 raw0..40to-20..20 °C.Negative offset with step:
partial(number, step=10.0, offset=-30, unit="rpm")maps raw0..255to300..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:
GitHub Issue: Attach the
<model_slug>.ziparchive exported by Command Line Interface to an issue on PyPlumIO.Pull Request: Open a PR containing all three required files:
pyplumio/parameters/custom/<model_slug>.py— exportsPARAMETERSwithmodelmatching<model_slug>, a non-bool integerid, and non-emptyservice_parametersorpatches.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.modelid (int) – Numeric product identifier matching
ProductInfo.idservice_parameters (Mapping[int, EcomaxParameterDescription] | None, optional) – Mapping of integer service parameter indices to
number()orswitch()descriptors, defaults toNonepatches (Mapping[str, EcomaxParameterDescription] | None, optional) – Mapping of standard parameter names to replacement
number()orswitch()descriptors, defaults toNone
- 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 - offsetwhen unpacking and divisor used when packing, defaults to1.0offset (int, optional) – Integer offset subtracted from the raw wire value before scaling, defaults to
0precision (int, optional) – Number of decimal places to round unpacked values to, defaults to
6optimistic (bool, optional) – Whether writes succeed immediately without waiting for controller confirmation, defaults to
Falseunit (UnitValue | UnitOfMeasurement | None, optional) – Physical unit of measurement as a
UnitOfMeasurementmember, supported unit string, orNone, defaults toNone
- Returns:
Number parameter description
- Return type:
EcomaxNumberDescription
- Raises:
ValueError – If
unitis 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 |
|
Meaning |
|---|---|---|
|
|
Degrees Celsius |
|
|
Kilowatts |
|
|
Grams |
|
|
Kilograms |
|
|
Kilowatt-hours per kilogram |
|
|
Kilograms per hour |
|
|
Seconds |
|
|
Minutes |
|
|
Days |
|
|
Pascals |
|
|
Revolutions per minute |
|
|
Percentage |