diff --git a/README.md b/README.md index 550c9c1..5338050 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ can simultaneously simulate: Modbus addresses 1 and 2. The combined firmware publishes compatibility contract -`openquatt-modbus-opentherm-v2` and simulator version `v0.4.1`. HIL clients +`openquatt-modbus-opentherm-v2` and simulator version `v0.5.0`. HIL clients must verify the contract before changing controller or simulator state. The project has no runtime or source dependency on OpenQuatt. Its register, @@ -165,6 +165,24 @@ raw readbacks for `2099`, `2100`, `2101`, `2103`, `2105`, `2108`, `2133`, defrost register `2118`. +The installed `ODU Defrost Contract=manual-defrost-v1` marker identifies the +accelerated manual-cycle fixture. A `3999=4` write requires actual simulated +heating, nonzero compressor feedback, flow switch and at least 250 l/h, no fault +words, no injected defrost and no manual telemetry override. Duplicate commands +acknowledge the same cycle without resetting its timer or increasing `started`. +The default duration is 30 seconds (configurable 1..600 seconds), independent of +synthetic P279. During the cycle, `2099=4`, `2118=1`, and `2108` defrost, +four-way cooling and bottom-plate heater bits are asserted. Completion returns +to heating; ambient heater control can keep the heater on below 2 °C. + +`ODU 1 defrost diagnostics` and `ODU 2 defrost diagnostics` publish +`started=N completed=N aborted=N`. These counters survive the generic diagnostic +reset and reset only on boot or model/profile reconfiguration. Normal-mode writes, +`1999=0`, or loss of heating/flow/fault-free prerequisites abort the manual cycle; +compressor stop still follows the ordinary ramp/runtime model. Defrost method and +parameter blocks remain synthetic controller fixtures. This does not validate +real ODU automatic defrost thresholds or physical cycle timing. + Defrost can be injected per ODU. The defrost register and status bit are set, water-out temporarily falls, and `Hold physical level during defrost` controls whether a new requested F-level is deferred until defrost ends. diff --git a/components/quatt_odu_simulator/quatt_odu_simulator_model.h b/components/quatt_odu_simulator/quatt_odu_simulator_model.h index 2a701c5..c3d9357 100644 --- a/components/quatt_odu_simulator/quatt_odu_simulator_model.h +++ b/components/quatt_odu_simulator/quatt_odu_simulator_model.h @@ -58,7 +58,7 @@ struct ModelSettings { float power_factor{0.92f}; float demand_limiter{1.0f}; float maximum_frequency_hz{120.0f}; - float forced_defrost_duration_s{45.0f}; + float forced_defrost_duration_s{30.0f}; bool freeze_measured_frequency{false}; bool hold_level_during_defrost{true}; bool experimental_high_frequency_extrapolation{false}; @@ -120,6 +120,9 @@ struct OduState { bool defrost{false}; // defrost injected via the ODU defrost switch bool forced_defrost{false}; // defrost latched by a 3999=4 write (independent of the switch) float forced_defrost_remaining_s{0.0f}; + uint32_t defrost_started{0}; + uint32_t defrost_completed{0}; + uint32_t defrost_aborted{0}; // Bottom-plate heating (registers 3236..3238): mode, start temperature (raw // = degC + 30) and stop delta. Defaults follow the variant: V1 defaults to // mode 1, V1.5/V2 to mode 3. @@ -268,7 +271,8 @@ class QuattOduSimulatorModel { if (address == 2006U) return value <= 1U; if (address == 2010U) return value == 0U || value == 4096U; if (address == 2015U) return value <= 1000U; - if (address == 3999U) return value <= 2U || value == 4U; + if (address == 3999U) return value <= 2U || (value == 4U && + (this->state_.forced_defrost || this->manual_defrost_ready_())); if (address >= 3000U && address <= 3021U) return this->state_.table_write_enabled && value <= 120U; if (address >= 3050U && address <= 3069U) return this->state_.profile == Profile::V2_NEW && this->state_.table_write_enabled && value <= 120U; @@ -554,12 +558,14 @@ class QuattOduSimulatorModel { diagnostics.write_count++; switch (address) { case 1999: { + const bool forced_stop = value == 0U && this->state_.forced_defrost; + if (forced_stop) this->abort_forced_defrost_(); this->state_.requested_physical_level = value; this->state_.protocol.highest_requested_level = std::max( this->state_.protocol.highest_requested_level, static_cast(std::min(value, 255U))); const uint8_t accepted = static_cast(std::min(value, this->maximum_level())); if (value > this->maximum_level()) this->state_.protocol.level_capability_violations++; - if (this->state_.defrost_active() && this->settings_.hold_level_during_defrost) { + if (!forced_stop && this->state_.defrost_active() && this->settings_.hold_level_during_defrost) { this->state_.deferred_defrost_level = accepted; this->state_.deferred_defrost_level_pending = true; } else { @@ -583,14 +589,15 @@ class QuattOduSimulatorModel { case 3999: this->state_.protocol.last_3999_value = value; if (value == 4U) { - // A forced request latches an independent defrost cycle; the injection - // switch (set_defrost) must not clear it, and a normal-mode write is - // the only other way out. The cycle self-ends after the modelled duration. - this->state_.forced_defrost = true; - this->state_.forced_defrost_remaining_s = this->settings_.forced_defrost_duration_s; - this->state_.protocol.forced_defrost_count++; + // Duplicate commands acknowledge the existing cycle without extending it. + if (!this->state_.forced_defrost) { + this->state_.forced_defrost = true; + this->state_.forced_defrost_remaining_s = this->settings_.forced_defrost_duration_s; + this->state_.protocol.forced_defrost_count++; + this->state_.defrost_started++; + } } else { - this->state_.forced_defrost = false; + this->abort_forced_defrost_(); this->state_.requested_mode = static_cast(value); } diagnostics.accepted_raw = value; @@ -601,14 +608,36 @@ class QuattOduSimulatorModel { } } + bool manual_defrost_ready_() const { + return this->enabled() && !this->state_.manual_telemetry.enabled && !this->state_.defrost && + this->state_.requested_mode == WorkingMode::HEATING && this->state_.active_mode == WorkingMode::HEATING && + this->state_.accepted_physical_level > 0U && this->state_.measured_frequency_hz > 0.1f && + this->state_.flow_switch && this->state_.flow_lph >= 250.0f && + std::all_of(this->state_.fault_words.begin(), this->state_.fault_words.end(), [](uint16_t word) { return word == 0U; }) && + std::isfinite(this->settings_.forced_defrost_duration_s) && this->settings_.forced_defrost_duration_s >= 1.0f; + } + + void abort_forced_defrost_() { + if (!this->state_.forced_defrost) return; + this->state_.forced_defrost = false; + this->state_.forced_defrost_remaining_s = 0.0f; + this->state_.defrost_aborted++; + this->update_deferred_defrost_level_(); + } + // A forced defrost cycle runs for its modelled duration, then releases the // ODU back to its requested working mode. void update_forced_defrost_(float dt_s) { if (!this->state_.forced_defrost) return; + if (!this->manual_defrost_ready_()) { + this->abort_forced_defrost_(); + return; + } this->state_.forced_defrost_remaining_s -= dt_s; if (this->state_.forced_defrost_remaining_s > 0.0f) return; this->state_.forced_defrost = false; this->state_.forced_defrost_remaining_s = 0.0f; + this->state_.defrost_completed++; this->update_deferred_defrost_level_(); } @@ -840,7 +869,7 @@ class QuattOduSimulatorModel { uint16_t status_2108_() const { uint16_t status = 0U; if (this->state_.fan_speed_rpm > 0.0f && this->state_.fan_speed_rpm < 400.0f) status |= 0x0001U; - if (this->state_.outside_temperature_c < 2.0f) status |= 0x0004U; + if (this->state_.outside_temperature_c < 2.0f || this->state_.forced_defrost) status |= 0x0004U; if (this->state_.outside_temperature_c < 5.0f) status |= 0x0008U; if (this->state_.defrost_active()) status |= 0x0010U; if (this->state_.fan_speed_rpm > 700.0f) status |= 0x0020U; diff --git a/docs/hil-interface.md b/docs/hil-interface.md index 932ea87..756138a 100644 --- a/docs/hil-interface.md +++ b/docs/hil-interface.md @@ -50,3 +50,23 @@ Voor een nieuwe geautomatiseerde actie: leg eerst met browserinspectie of officiële documentatie vast welk protocol en welke authenticatie werkelijk nodig zijn. Voeg vervolgens alleen het minimaal noodzakelijke, expliciet geverifieerde commando aan de REST-referentie toe. + + +## Manual defrost capability (v0.5.0) + +The base contract stays `openquatt-modbus-opentherm-v2`. Check the running +`text_sensor/ODU Defrost Contract` equals `manual-defrost-v1` before claiming +manual-cycle coverage. `text_sensor/ODU 1 defrost diagnostics` and the ODU 2 +counterpart expose `started=N completed=N aborted=N` once per second. Counters +reset on boot/profile reconfiguration, not the generic diagnostics-reset button. + +Use the controller's normal defrost request, not a second Modbus master. Require +actual heating/compressor/flow feedback and no fault/manual override/injected +bit. `3999=4` starts one cycle; duplicates never restart it. Default duration is +30 seconds; the existing forced-duration controls permit 1..600 seconds. Check +`2099=4`, `2118=1`, `2108 & 0x0054 == 0x0054`, and started +1; then heating, +defrost bit clear, completed +1 and unchanged aborted. Normal stop commands or +lost prerequisites abort once. Independent injected-defrost switches remain bit +fixtures. Check final physical stop feedback after a stop, not only an ACK. + +This is an accelerated control-path fixture, not real ODU defrost validation. diff --git a/hcq_v1_system_simulator.yaml b/hcq_v1_system_simulator.yaml index 02dd7ca..3e31f09 100644 --- a/hcq_v1_system_simulator.yaml +++ b/hcq_v1_system_simulator.yaml @@ -2,7 +2,7 @@ substitutions: device_name: openquatt-simulator friendly_name: OpenQuatt Modbus and OpenTherm Simulator simulator_contract: openquatt-modbus-opentherm-v2 - simulator_version: v0.4.1 + simulator_version: v0.5.0 odu_1_address: "1" odu_2_address: "2" diff --git a/packages/quatt_odu_simulator.yaml b/packages/quatt_odu_simulator.yaml index e6475f9..ce12198 100644 --- a/packages/quatt_odu_simulator.yaml +++ b/packages/quatt_odu_simulator.yaml @@ -323,10 +323,10 @@ number: entity_category: config optimistic: true unit_of_measurement: "s" - min_value: 0 + min_value: 1 max_value: 600 step: 1 - initial_value: "45" + initial_value: "30" - platform: template id: odu_2_forced_defrost_duration_s @@ -334,10 +334,10 @@ number: entity_category: config optimistic: true unit_of_measurement: "s" - min_value: 0 + min_value: 1 max_value: 600 step: 1 - initial_value: "45" + initial_value: "30" - platform: template id: odu_1_pending_address @@ -1003,6 +1003,38 @@ sensor: lambda: return id(odu_simulator)->model(1).state().protocol.legacy_extension_read_violations; text_sensor: + - platform: template + name: "ODU Defrost Contract" + entity_category: diagnostic + update_interval: 1s + lambda: return {"manual-defrost-v1"}; + + - platform: template + name: "ODU 1 defrost diagnostics" + entity_category: diagnostic + update_interval: 1s + lambda: |- + const auto &s = id(odu_simulator)->model(0).state(); + char text[128]; + snprintf(text, sizeof(text), "started=%lu completed=%lu aborted=%lu", + static_cast(s.defrost_started), + static_cast(s.defrost_completed), + static_cast(s.defrost_aborted)); + return {text}; + + - platform: template + name: "ODU 2 defrost diagnostics" + entity_category: diagnostic + update_interval: 1s + lambda: |- + const auto &s = id(odu_simulator)->model(1).state(); + char text[128]; + snprintf(text, sizeof(text), "started=%lu completed=%lu aborted=%lu", + static_cast(s.defrost_started), + static_cast(s.defrost_completed), + static_cast(s.defrost_aborted)); + return {text}; + - platform: template name: "ODU 1 diagnostics" entity_category: diagnostic diff --git a/tests/quatt_odu_manual_defrost_test.cpp b/tests/quatt_odu_manual_defrost_test.cpp new file mode 100644 index 0000000..e3703c1 --- /dev/null +++ b/tests/quatt_odu_manual_defrost_test.cpp @@ -0,0 +1,89 @@ +#include +#include +#include "../components/quatt_odu_simulator/quatt_odu_simulator_model.h" +using namespace esphome::quatt_odu_simulator; + +static uint16_t read(QuattOduSimulatorModel &model, uint16_t address) { + uint16_t value = 0; + assert(model.read_register(address, value)); + return value; +} +static void heat(QuattOduSimulatorModel &model, Profile profile = Profile::V1_5) { + model.configure(profile); + model.mutable_settings().forced_defrost_duration_s = 30; + assert(model.write_register(1999, 5, 0)); + assert(model.write_register(3999, 2, 0)); + assert(model.write_register(2010, 4096, 0)); + assert(model.write_register(2015, 150, 0)); + for (int i = 0; i < 60; ++i) model.update(0.5f); + assert(read(model, 2099) == 2); +} +int main() { + QuattOduSimulatorModel model; + model.configure(Profile::V1_5); + assert(!model.write_register(3999, 4, 0)); // idle cannot fabricate a cycle + for (auto profile : {Profile::V1, Profile::V1_5, Profile::V2_OLD, Profile::V2_NEW}) { + heat(model, profile); + assert(model.write_register(3999, 4, 1)); + assert(read(model, 2099) == 4 && read(model, 2118) == 1); + assert((read(model, 2108) & 0x0054) == 0x0054); + model.set_defrost(false); // independent injection cannot cancel the cycle + for (int i = 0; i < 29; ++i) model.update(1); + const float remaining = model.state().forced_defrost_remaining_s; + assert(model.write_register(3999, 4, 2)); // lost-ACK retry cannot extend/restart + assert(model.state().forced_defrost_remaining_s == remaining); + assert(model.state().defrost_started == 1); + model.reset_diagnostics(); // generic diagnostics reset cannot erase cycle history + model.update(1); + assert(read(model, 2099) == 2 && read(model, 2118) == 0); + assert((read(model, 2108) & 0x0054) == 0); + assert(model.state().defrost_started == 1 && model.state().defrost_completed == 1); + assert(model.state().defrost_aborted == 0); + model.update(1); + assert(model.state().defrost_completed == 1); + } + heat(model); + model.mutable_state().flow_lph = 249; + assert(!model.write_register(3999, 4, 0)); + model.mutable_state().flow_lph = 250; + assert(model.write_register(3999, 4, 0)); + assert(model.write_register(1999, 0, 1)); + assert(model.state().defrost_aborted == 1 && model.state().accepted_physical_level == 0); + assert(read(model, 2118) == 0); + for (int i = 0; i < 30; ++i) model.update(1); + assert(read(model, 2099) == 0 && read(model, 2103) == 0); + assert(model.state().defrost_completed == 0); + for (uint16_t mode : {0, 1, 2}) { + heat(model); + assert(model.write_register(3999, 4, 0)); + assert(model.write_register(3999, mode, 1)); + assert(model.state().defrost_aborted == 1 && model.state().defrost_completed == 0); + assert(!model.state().forced_defrost && model.state().forced_defrost_remaining_s == 0); + } + for (int fault = 0; fault < 7; ++fault) { + heat(model); + auto invalidate = [&]() { + if (fault < 3) model.mutable_state().fault_words[fault] = 1; + if (fault == 3) model.set_manual_telemetry_enabled(true); + if (fault == 4) model.mutable_state().flow_switch = false; + if (fault == 5) model.mutable_settings().forced_defrost_duration_s = 0; + if (fault == 6) model.mutable_settings().forced_defrost_duration_s = std::numeric_limits::quiet_NaN(); + }; + invalidate(); + assert(!model.write_register(3999, 4, 0)); + assert(model.state().defrost_started == 0); + heat(model); + model.mutable_settings().forced_defrost_duration_s = 30; + assert(model.write_register(3999, 4, 0)); + invalidate(); + model.update(1); + assert(model.state().defrost_aborted == 1 && model.state().defrost_completed == 0); + } + heat(model); + assert(model.write_register(3999, 4, 0)); + model.mutable_state().outside_temperature_c = -3; + for (int i = 0; i < 30; ++i) model.update(1); + assert((read(model, 2108) & 0x0004) != 0); // ordinary ambient heater remains active + model.configure(Profile::V1_5); // reconfiguration starts a new history; never resume an active cycle + assert(model.state().defrost_started == 0 && !model.state().forced_defrost); +} diff --git a/tests/quatt_odu_simulator_model_test.cpp b/tests/quatt_odu_simulator_model_test.cpp index 3e9d281..1bf9883 100644 --- a/tests/quatt_odu_simulator_model_test.cpp +++ b/tests/quatt_odu_simulator_model_test.cpp @@ -152,6 +152,10 @@ int main() { assert(read(model, 3307U) == 5U); assert(read(model, 3336U) == 27U); assert(read(model, 3414U) == 18U); + assert(model.write_register(1999U, 10U, 62U)); + assert(model.write_register(3999U, 2U, 62U)); + assert(model.write_register(2010U, 4096U, 62U)); + for (int i = 0; i < 40; i++) model.update(0.25f); assert(model.write_register(3999U, 4U, 63U)); assert(read(model, 2099U) == 4U); assert(read(model, 2118U) == 1U); @@ -174,7 +178,8 @@ int main() { model.mutable_settings().minimum_runtime_s = 0.0f; assert(model.write_register(1999U, 20U, 100U)); assert(model.write_register(3999U, 2U, 101U)); // request heating - model.update(0.5f); + assert(model.write_register(2010U, 4096U, 102U)); + for (int i = 0; i < 40; i++) model.update(0.25f); const uint16_t settled_mode = read(model, 2099U); assert(settled_mode == 2U); assert(model.write_register(3999U, 4U, 110U)); // force defrost