[FEATURE]: Expose extra OpenTherm boiler data (counters, DHW flow, fault/diagnostic codes) #948

Describe the solution you are looking for

Hi @bouwew, @CoMPaTech,

My setup is an Adam with an OpenTherm boiler that reports more datapoints in /core/domain_objects than python-plugwise currently exposes. I'd like to add this data and then bring it to Home Assistant as sensors. Before I open a PR, I'd like to check whether you want this and how you'd like it structured.

What I'd add (only when the boiler/gateway actually reports it):

From point_log on the heater_central:

• dhw_flow: DHW flow rate (L/min)
• open_therm_oem_fault_code, open_therm_application_specific_fault_code, open_therm_oem_diagnostic_code: raw codes. What they mean depends on the boiler, so they're exposed as plain integers.

From cumulative_log on the heater_central (new for heater_central):

• burner_starts, failed_burner_starts, failed_burner_flame_ignitions
• burner_operation_time, dhw_burner_operation_time, dhw_burner_starts
• central_heater_pump_operation_time, central_heater_pump_starts
• dhw_pump_operation_time, dhw_pump_starts

On thermostats:

• maximum_modulation_level (%), which some OpenTherm thermostats connected to an Adam report

How I've implemented it so far (open to changing any of it):

• A new HEATER_CENTRAL_COUNTERS dict in constants.py, read by a small _appliance_counters() helper that runs only for the heater.
• New units: TIME_HOURS (h), UNIT_COUNT, and VOLUME_FLOW_LITERS_PER_MINUTE. Values in hours or counts are returned as int through an INTEGER_FORMAT check in format_measure().
• Keys use the existing dhw_ short form through DATA(...), the same way dhw_temperature does.
• I extended the test JSONs and the manual fixtures. Devices that don't report a value simply don't get the key, so existing setups don't change.

Questions:

1. Do you want this in python-plugwise at all, or only some of it? For example, are the raw fault codes useful enough to include?
2. Are the key names OK, or would you prefer other names or prefixes?
3. Do you have a preference for how to handle the new units and the int formatting?
4. Would you like this to go through plugwise-beta first before core?

For transparency: I wrote this with help from an AI coding assistant. I've reviewed and tested the changes and can explain all of it.

Thanks!

Is your feature request related to a problem? (optional)

An Adam with an OpenTherm boiler may already reports burner/pump counters, operation times, DHW flow and OpenTherm fault/diagnostic codes in /core/domain_objects (depending on boiler), but python-plugwise doesn’t expose them. Because of that they can’t be used in Home Assistant, for example to track burner starts (wear) or to see a fault code when the boiler locks out.

Describe alternatives you've considered

• Reading /core/domain_objects directly with a REST sensor in Home Assistant. This works, but it’s fragile and every user would have to set it up themselves.
• Adding only the counters and leaving out the raw fault/diagnostic codes, since what those codes mean depends on the boiler. I’m happy to narrow it down to that if you prefer.
• Starting in plugwise-beta instead of here. I’m happy to follow whatever route you prefer.

What type of installation are you running?

Home Assistant Container

How did you install python-plugwise (or plugwise) for short

Home Assistant Core

What kind of Plugwise device is having issues?

Smile: Adam (including Lisa, Tom, Floor)

What firmware version is your Plugwise product at?

3.12.6

Your setup

I have a bosch prolline next boiler

Additional context

Work-in-progress branch: https://github.com/bilhert/python-plugwise/tree/feature/extra-boiler-sensors