Skip to content

Expose 26 documented readback values and add five MQTT setting commands - #1013

Open
kretzp wants to merge 5 commits into
heishamon:mainfrom
kretzp:codex/mqtt-settings-and-controls
Open

kretzp wants to merge 5 commits into
heishamon:mainfrom
kretzp:codex/mqtt-settings-and-controls

Conversation

@kretzp

@kretzp kretzp commented Oct 11, 2026

Copy link
Copy Markdown
Contributor

HeishaMon receives several documented heat pump settings and operating states without exposing them as individual MQTT topics. The protocol documentation also contains write examples for settings that currently have no named command.

This change adds 26 readback topics and five setting commands through the existing decoder and command tables. Existing topic names and IDs remain unchanged.

The new readback topics, TOP144–TOP169, cover:

  • Concrete drying state and current target temperature.
  • DHW capacity mode, internal heater capacity and DHW heater type.
  • Zone configuration and individual zone activity.
  • SG Ready and demand control enable settings, plus four SG Ready capacity settings.
  • DHW defrost configuration and pool temperature delta.
  • Maximum room operation time and DHW heat-up time.
  • Actual quiet/powerful mode states, heat/cool switch state, external switch state and bivalent boiler contact state.
  • Backup heater and cooling enable settings.
  • Heating water shift/direct target including the buffer delta.

Five new commands are available under <base_topic>/commands/:

Command Purpose Encoding
SetHeatToCoolTemp Outdoor temperature for automatic heat-to-cool switching Byte 95: °C + 128
SetCoolToHeatTemp Outdoor temperature for automatic cool-to-heat switching Byte 96: °C + 128
SetRoomOperationMaxTime Maximum room operation time when alternating with DHW Byte 97: minutes / 30 + 1
SetDHWHeatupMaxTime Maximum DHW heat-up time Byte 98: minutes + 1
SetQuietModeSchedule Enable or disable the existing quiet schedule Byte 7: 0x40 off / 0x80 on

For example, publishing 90 to <base_topic>/commands/SetRoomOperationMaxTime sends a command with byte 97 set to 0x04. Publishing 91 is rejected without sending a telegram because the setting uses 30-minute increments.

The commands validate the complete integer payload before modifying the command buffer. Empty, malformed, out-of-range and invalid-step inputs are rejected without transmission. Each accepted command sets only its intended field in the standard command template.

The shared tables also expose these additions through the existing HTTP and rules interfaces. SetQuietModeSchedule toggles the existing schedule; it does not configure schedule times or change the quiet level.

MQTT-Topics.md and ProtocolByteDecrypt.md document the topic names, payloads, byte mappings and readback relationships. Validation ranges represent nonzero protocol encodings; individual heat pump models may enforce narrower installer-menu limits.

Uncertain fields—including external heater timing, the possible bypass valve, the heat pump power field and the possible T-CAP indicator—remain unchanged. Zone sensor configuration and the conflicting second room thermostat byte mapping are also outside this change.

Validation completed successfully:

  • 78 setter/dispatch cases: documented example encodings, boundaries, preservation of unrelated fields and rejected inputs without transmission.
  • 26 decoder/MQTT cases: readback values, topic mappings, retained publication, change-triggered publication and unchanged-value suppression.
  • 24 existing rules regression scenarios.
  • ESP8266 firmware build, core 3.1.2.
  • ESP32-S3 firmware build, core 3.3.11.

The new write commands follow the repository’s documented telegram examples. Hardware acceptance and model-specific menu limits have not yet been verified.

…ation.

Prevent sending rejected commands and add documentation.
Hardware verified on Aquarea L.
Add 26 readback topics (TOP144-TOP169) for documented fields in the
normal heat pump data block, including SG Ready capacity settings,
concrete drying, heater configuration, actual operating states,
zone activity and room/DHW operation time limits.

Add five commands for automatic heat/cool switching temperatures,
room and DHW operation time limits, and quiet schedule activation.
Validate complete integer payloads before constructing a telegram;
reject malformed, out-of-range and invalid-step inputs without
sending a command.

Preserve existing topic IDs and reuse the shared decoder and command
tables so the additions are also available through HTTP and rules.

Document byte mappings, payload encodings, readback topics and the
distinction between protocol ranges and model-specific menu limits.
Leave uncertain protocol fields and zone sensor configuration unchanged.

Validation:
- 78 setter/dispatch cases passed
- 26 decoder/MQTT cases passed
- 24 rules regression scenarios passed
- ESP8266 build passed with core 3.1.2
- ESP32-S3 build passed with core 3.3.11

New writes follow documented telegram examples; hardware acceptance
and model-specific menu limits remain to be verified.
@IgorYbema IgorYbema added the enhancement New feature or request label Oct 11, 2026
@kretzp

kretzp commented Oct 13, 2026

Copy link
Copy Markdown
Contributor Author
image Works perfect on my Auqarea LT 5kW

@sigma415

Copy link
Copy Markdown

What about relay status ?

@kretzp

kretzp commented Oct 19, 2026

Copy link
Copy Markdown
Contributor Author

What about relay status ?

You mean the relay on the board? This PR is only about Aquarea Get and Set Parameters.
We could put it in another PR if it is useful.

@sigma415

Copy link
Copy Markdown

Yes, the two relays on the large heishamon board.
Actually they are write-only via MQTT, no status feedback, no MQTT publishing of their status.
This would be great if you could put in another PR :)
Thank you.

@geduxas

geduxas commented Oct 20, 2026

Copy link
Copy Markdown
Contributor

@sigma415 just use retaining flag on mqtt topic and use it as indication.

@sigma415

Copy link
Copy Markdown

Thanks, I know the retain flag.
But first, respectRetain is not recommended to activate in my broker environment (MQTT2)
and second retain flag does not report the real HW status, it's only a "should be"

@geduxas

geduxas commented Oct 20, 2026

Copy link
Copy Markdown
Contributor

Thanks, I know the retain flag. But first, respectRetain is not recommended to activate in my broker environment (MQTT2) and second retain flag does not report the real HW status, it's only a "should be"

Same are on hardware..

First heishamon don't store it's status, so retain flag will triger last state after heishamon crash/reboot/offline.
Second if we are talking on hardware level.. heishamon also dont realy know if relays are on or not.. it just sends signal.. same as mqtt do...

Publish both onboard relay states under gpio/relay/{one,two}/state
using retained 0/1 payloads.

Report states after MQTT relay commands, on MQTT reconnect, and at
the configured full-data resend interval. Detect changes made by
rules at the end of each main loop and retry failed publications.

Document the status topics and clarify that they report GPIO output
levels rather than mechanical relay contact feedback.
@kretzp

kretzp commented Oct 20, 2026

Copy link
Copy Markdown
Contributor Author

Thanks, I know the retain flag. But first, respectRetain is not recommended to activate in my broker environment (MQTT2) and second retain flag does not report the real HW status, it's only a "should be"

Same are on hardware..

First heishamon don't store it's status, so retain flag will triger last state after heishamon crash/reboot/offline. Second if we are talking on hardware level.. heishamon also dont realy know if relays are on or not.. it just sends signal.. same as mqtt do...

Put it knows the level of the gpio that triggering the relay. And this complies to the state of the relay. That ist the way I implemented it.

Add TOP170 and TOP171 to the main page for Relay 1 and Relay 2.
Read their states directly from GPIO21 and GPIO47 and display
On/Off alongside the configured MQTT state topics.

Refresh relay states every five seconds independently of MQTT
connectivity and document the new topic IDs and JSON output.
@kretzp

kretzp commented Oct 20, 2026

Copy link
Copy Markdown
Contributor Author
image So it shows the state in the UI, updated every 5 seconds and sends a MQTT message, when it changes or when the interval (e.g., 300 sec) arrives.

@sigma415

Copy link
Copy Markdown

Same are on hardware..

First heishamon don't store it's status, so retain flag will triger last state after heishamon crash/reboot/offline. Second if we are talking on hardware level.. heishamon also dont realy know if relays are on or not.. it just sends signal.. same as mqtt do...

Heishmon writes to ESP GPIO, but can not read it ?

@sigma415

Copy link
Copy Markdown

image So it shows the state in the UI, updated every 5 seconds and sends a MQTT message, when it changes or when the interval (e.g., 300 sec) arrives.

@kretzp: Thank you. That's exactly what we need. Would this be implemented in future Heishamon firmware ?

@shabbab

shabbab commented Oct 21, 2026 •

Copy link
Copy Markdown

Put it knows the level of the gpio that triggering the relay. And this complies to the state of the relay. That ist the way I implemented it.

Thank you! Finally the old issue #889 is being fixed. MQTT retain would not work with systems that use rules for local processing and MQTT for remote monitoring.

Will that also make the REST Api for relay control function? It has been part of the translated readme files, for example:
https://github.com/heishamon/HeishaMon/blob/main/README_DE.md#benutzerkonfigurierbare-extra-gpios

And another point, entirely different but since you are currently working on MQTT:
I am missing a read-only topic for rule engine status. Currently I have to manually check status in a browser to find issues. MQTT would make that much easier.

@sigma415

sigma415 commented Oct 22, 2026 •

Copy link
Copy Markdown

@kretzp : I own a actual K-series, R32 split 7kW. If you could provide me your preliminary large-board.bin and md5, I could and would test your code also with K-series.

@kretzp

kretzp commented Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

@kretzp : I own a actual K-series, R32 split 7kW. If you could provide me your preliminary large-board.bin and md5, I could and would test your code also with K-series.

This pull request has a build. You can download it here:
https://github.com/heishamon/HeishaMon/actions/runs/39493274212/artifacts/12296478327

@kretzp

kretzp commented Oct 23, 2026

Copy link
Copy Markdown
Contributor Author

Put it knows the level of the gpio that triggering the relay. And this complies to the state of the relay. That ist the way I implemented it.

Thank you! Finally the old issue #889 is being fixed. MQTT retain would not work with systems that use rules for local processing and MQTT for remote monitoring.

Will that also make the REST Api for relay control function? It has been part of the translated readme files, for example: https://github.com/heishamon/HeishaMon/blob/main/README_DE.md#benutzerkonfigurierbare-extra-gpios

And another point, entirely different but since you are currently working on MQTT: I am missing a read-only topic for rule engine status. Currently I have to manually check status in a browser to find issues. MQTT would make that much easier.

I will check it

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants