From d07ea7500607db67c4266059657b8122b9395168 Mon Sep 17 00:00:00 2001 From: Emil Axfors <17743298+murre87@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:31:18 +0000 Subject: [PATCH] feat(heishamon): optional control: false read-only mode (0.8.2) Add an optional `control: false` to the driver config. The driver then stays read-only: the metrics still arrive, DRIVER.controls is empty and driver_command never publishes Z1_Heat_Request_Temp, so Home Assistant or the pump's own controller keeps the heat curve offset. Without the option nothing changes. `control` also accepts 0, "false", "no" and "off" for string configs. Registers and fields are unchanged. Covered by a harness test (default on, true, the false spellings, and no publish from command, default mode or cleanup); not yet checked on hardware. Reported downstream in murre87/energywizard#491. Co-Authored-By: Claude Sonnet 5.5 Signed-off-by: Emil Axfors <17743298+murre87@users.noreply.github.com> --- CHANGELOG.md | 10 ++++ SUPPORT_STATUS.md | 4 +- devices.yaml | 2 +- drivers/lua/heishamon.lua | 31 ++++++++++- .../test_heishamon_control_option.lua | 55 +++++++++++++++++++ .../tests/test_heishamon_control_option.py | 18 ++++++ index.yaml | 6 +- manifests/heishamon.yaml | 6 +- support-status.json | 2 +- 9 files changed, 121 insertions(+), 13 deletions(-) create mode 100644 drivers/tests/lua_harness/test_heishamon_control_option.lua create mode 100644 drivers/tests/test_heishamon_control_option.py diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f4d1e9..931cfcf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,16 @@ ## [Unreleased] +### heishamon 0.8.2 + +Add an optional `control: false` to the driver config. The driver then stays +read-only: the metrics still arrive, `DRIVER.controls` is empty, and +`driver_command` never publishes `Z1_Heat_Request_Temp`, so Home Assistant or +the pump's own controller keeps the heat curve offset. Without the option +nothing changes. `control` also accepts `0`, `"false"`, `"no"` and `"off"` for +configs that arrive as strings. Registers and fields are unchanged. Covered by +a harness test only; not yet checked on hardware. + ### heishamon 0.8.1 Default mode and cleanup reset `Z1_Heat_Request_Temp` to `safe_offset` only diff --git a/SUPPORT_STATUS.md b/SUPPORT_STATUS.md index 5c50b7c..1084853 100644 --- a/SUPPORT_STATUS.md +++ b/SUPPORT_STATUS.md @@ -76,8 +76,8 @@ Catalog source is not proof that a target can install or run a driver. | growatt | 2.1.3 | blixt-l1 | not_assessed | — | not_recorded | not_assessed | | hardybarth | 1.0.1 | ftw-core | not_assessed | — | not_recorded | not_assessed | | hardybarth | 1.0.1 | blixt-l1 | not_assessed | — | not_recorded | not_assessed | -| heishamon | 0.8.1 | ftw-core | not_assessed | — | not_recorded | not_assessed | -| heishamon | 0.8.1 | blixt-l1 | not_assessed | — | not_recorded | not_assessed | +| heishamon | 0.8.2 | ftw-core | not_assessed | — | not_recorded | not_assessed | +| heishamon | 0.8.2 | blixt-l1 | not_assessed | — | not_recorded | not_assessed | | hello | 1.1.2 | ftw-core | not_assessed | — | not_recorded | not_assessed | | hello | 1.1.2 | blixt-l1 | not_assessed | — | not_recorded | not_assessed | | home_assistant_vehicle | 0.1.0 | ftw-core | not_assessed | — | not_recorded | not_assessed | diff --git a/devices.yaml b/devices.yaml index f758c58..3cfa7e1 100644 --- a/devices.yaml +++ b/devices.yaml @@ -1021,7 +1021,7 @@ manufacturers: protocols: - protocol: mqtt driver: "heishamon" - version: "0.8.1" + version: "0.8.2" ders: [heatpump] control: true firmware_versions: "" diff --git a/drivers/lua/heishamon.lua b/drivers/lua/heishamon.lua index 8914be3..b38b66e 100644 --- a/drivers/lua/heishamon.lua +++ b/drivers/lua/heishamon.lua @@ -27,6 +27,11 @@ -- max_offset: 3 -- safe_offset: 0 -- power_topic: Heat_Power_Consumption +-- control: true +-- +-- control: false keeps the driver read-only. The metrics come in, DRIVER.controls is empty +-- and driver_command never writes Z1_Heat_Request_Temp, so Home Assistant or the pump's own +-- controller keeps the offset. -- -- power_topic names a main/ topic carrying electrical power in W. -- The default is Heat_Power_Consumption (TOP16), the heat-mode input. @@ -41,7 +46,7 @@ DRIVER = { id = "heishamon", name = "Panasonic Aquarea (Heishamon)", manufacturer = "Panasonic", - version = "0.8.1", + version = "0.8.2", protocols = { "mqtt" }, capabilities = { "heatpump" }, description = "Panasonic Aquarea H/J/K/L/M-series heat pump via Heishamon MQTT bridge. Controls Zone 1 heat curve offset (Z1_Heat_Request_Temp) in range -3..+3 °C.", @@ -51,7 +56,7 @@ DRIVER = { verification_status = "experimental", verified_by = { "Rolf (Runneval)" }, verified_at = "2026-06-21", - verification_notes = "Existing metrics and offset control tested on WH-SXC09H3E8 (H-series) with Heishamon Large v4.1.6 on ESP32 on 2026-06-21. The new hp_power_w reading is not hardware-verified; its default topic reports heat-mode input, not total input in cooling or DHW mode. 0.8.1 resets the offset only after FTW wrote one; that change is not yet checked on hardware.", + verification_notes = "Existing metrics and offset control tested on WH-SXC09H3E8 (H-series) with Heishamon Large v4.1.6 on ESP32 on 2026-06-21. The new hp_power_w reading is not hardware-verified; its default topic reports heat-mode input, not total input in cooling or DHW mode. 0.8.1 resets the offset only after FTW wrote one; that change is not yet checked on hardware. 0.8.2 adds the optional control: false read-only mode; it is covered by a harness test only and not yet checked on hardware.", -- What an operator may command, in terms a host UI can render without -- knowing this driver. The bounds are the defaults below; min_offset and -- max_offset can narrow them in config, and driver_command clamps to @@ -96,6 +101,17 @@ local min_offset = -3 local max_offset = 3 local safe_offset = 0 local power_topic = "Heat_Power_Consumption" +local control = true + +local function control_enabled(v) + if v == nil then return true end + if v == false or v == 0 then return false end + if type(v) == "string" then + local x = string.lower(v) + if x == "false" or x == "no" or x == "off" or x == "0" then return false end + end + return true +end ---------------------------------------------------------------------------- -- Lifecycle @@ -110,6 +126,10 @@ function driver_init(config) if config.max_offset then max_offset = tonumber(config.max_offset) or 3 end if config.safe_offset then safe_offset = tonumber(config.safe_offset) or 0 end if config.power_topic then power_topic = config.power_topic end + if config.control ~= nil then control = control_enabled(config.control) end + end + if not control then + DRIVER.controls = {} -- the host offers no offset command when the installation only wants the metrics end -- Subscribe broadly to all Heishamon topics @@ -123,7 +143,8 @@ function driver_init(config) host.log("info", "Heishamon: initialized, base_topic=" .. base_topic .. " offset_range=[" .. min_offset .. ".." .. max_offset .. "]" .. " safe_offset=" .. safe_offset - .. " power_topic=" .. power_topic) + .. " power_topic=" .. power_topic + .. " control=" .. tostring(control)) end function driver_poll() @@ -217,6 +238,10 @@ local function apply_offset(offset) end function driver_command(action, _power_w, cmd) + if not control then + host.log("debug", "Heishamon: control is off, not writing the offset") + return false + end if action == "set_heat_curve_offset" then local offset = tonumber(cmd and (cmd.offset or cmd.value)) if offset == nil then diff --git a/drivers/tests/lua_harness/test_heishamon_control_option.lua b/drivers/tests/lua_harness/test_heishamon_control_option.lua new file mode 100644 index 0000000..7015eba --- /dev/null +++ b/drivers/tests/lua_harness/test_heishamon_control_option.lua @@ -0,0 +1,55 @@ +-- control: false keeps heishamon read-only. The metrics still arrive, DRIVER.controls is empty and no +-- Z1_Heat_Request_Temp is ever published, so Home Assistant or the pump's own controller keeps the offset. +dofile("drivers/tests/lua_harness/host_mock.lua") + +host.mqtt_publish = function(topic, payload) + table.insert(host._calls, { func = "mqtt_publish", args = { topic, payload } }) + return nil +end + +local SET = "panasonic_heat_pump/set/Z1_Heat_Request_Temp" + +local function publishes() + local out = {} + for _, c in ipairs(host._calls) do + if c.func == "mqtt_publish" and c.args[1] == SET then + table.insert(out, c.args[2]) + end + end + return out +end + +local function fresh_driver(config) + host.reset() + dofile("drivers/lua/heishamon.lua") + driver_init(config) +end + +-- Default: control stays on, as before this option existed. +fresh_driver({}) +assert(#DRIVER.controls > 0, "controls must be offered by default") +assert(driver_command("set_heat_curve_offset", 0, { value = 2 }) == true, "default must still write") +assert(#publishes() == 1 and publishes()[1] == "2", "default write did not publish the offset") + +-- control: true behaves like the default. +fresh_driver({ control = true }) +assert(#DRIVER.controls > 0, "control: true must offer controls") + +-- control: false (and the spellings a YAML or string config produces): read-only. +for _, off in ipairs({ false, 0, "false", "False", "no", "off", "0" }) do + fresh_driver({ control = off }) + assert(#DRIVER.controls == 0, "control = " .. tostring(off) .. " must empty DRIVER.controls") + assert(driver_command("set_heat_curve_offset", 0, { value = 2 }) == false, + "control = " .. tostring(off) .. " must refuse the command") + driver_default_mode() + driver_cleanup() + assert(#publishes() == 0, "control = " .. tostring(off) .. " must never publish an offset") +end + +-- Anything else that is set keeps control on. +for _, on in ipairs({ true, 1, "true", "yes", "on" }) do + fresh_driver({ control = on }) + assert(#DRIVER.controls > 0, "control = " .. tostring(on) .. " must keep controls") +end + +print("heishamon control option ok") diff --git a/drivers/tests/test_heishamon_control_option.py b/drivers/tests/test_heishamon_control_option.py new file mode 100644 index 0000000..dee52ce --- /dev/null +++ b/drivers/tests/test_heishamon_control_option.py @@ -0,0 +1,18 @@ +"""heishamon: control: false keeps the driver read-only.""" + +from pathlib import Path +import subprocess + + +ROOT = Path(__file__).resolve().parents[2] + + +def test_heishamon_control_false_is_read_only(): + result = subprocess.run( + [str(ROOT / "lua55"), "drivers/tests/lua_harness/test_heishamon_control_option.lua"], + cwd=ROOT, + text=True, + capture_output=True, + check=False, + ) + assert result.returncode == 0, result.stdout + result.stderr diff --git a/index.yaml b/index.yaml index 0fe786c..7475c38 100644 --- a/index.yaml +++ b/index.yaml @@ -331,15 +331,15 @@ drivers: size_bytes: 2193 sha256: "517e086af899dc511c86b00460cd8ce052a8d4973edee8b018e5824d4b550d6e" - name: "heishamon" - version: "0.8.1" + version: "0.8.2" tier: core protocol: mqtt connectivity: local setup: [bridge] ders: [heatpump] control: true - size_bytes: 10923 - sha256: "1bae5c3d4caa0adc8b42cb5d470b7faff66b1e1c3b456182cdd66728a48b9800" + size_bytes: 12033 + sha256: "0e9dd2a1458953f5ac700daf59ec62bad6274620abef460a28eca42a03e20f98" - name: "hello" version: "1.1.2" tier: community diff --git a/manifests/heishamon.yaml b/manifests/heishamon.yaml index f26defc..1bc76ba 100644 --- a/manifests/heishamon.yaml +++ b/manifests/heishamon.yaml @@ -1,5 +1,5 @@ name: "heishamon" -version: "0.8.1" +version: "0.8.2" tier: core author: "Sourceful Labs AB" protocol: mqtt @@ -16,9 +16,9 @@ tested_devices: notes: "Panasonic Aquarea H/J/K/L/M-series heat pump via Heishamon MQTT bridge. Controls Zone 1 heat curve offset (Z1_Heat_Request_Temp) in range -3..+3 °C." min_driver_version: "0.4.0" min_host_version: "2.0.0" -size_bytes: 10923 +size_bytes: 12033 dkb_id: "heishamon" -sha256: "1bae5c3d4caa0adc8b42cb5d470b7faff66b1e1c3b456182cdd66728a48b9800" +sha256: "0e9dd2a1458953f5ac700daf59ec62bad6274620abef460a28eca42a03e20f98" signature: "" bytecode_sha256: "" diff --git a/support-status.json b/support-status.json index c6ee121..d8d56d5 100644 --- a/support-status.json +++ b/support-status.json @@ -758,7 +758,7 @@ }, { "catalog_source": true, - "catalog_version": "0.8.1", + "catalog_version": "0.8.2", "driver_id": "heishamon", "targets": { "blixt-l1": {