Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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.
Expand Down
51 changes: 40 additions & 11 deletions components/quatt_odu_simulator/quatt_odu_simulator_model.h
Original file line number Diff line number Diff line change
Expand Up @@ -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};
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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<uint8_t>(
this->state_.protocol.highest_requested_level, static_cast<uint8_t>(std::min<uint16_t>(value, 255U)));
const uint8_t accepted = static_cast<uint8_t>(std::min<uint16_t>(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 {
Expand All @@ -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<WorkingMode>(value);
}
diagnostics.accepted_raw = value;
Expand All @@ -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_();
}

Expand Down Expand Up @@ -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;
Expand Down
20 changes: 20 additions & 0 deletions docs/hil-interface.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 1 addition & 1 deletion hcq_v1_system_simulator.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -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"

Expand Down
40 changes: 36 additions & 4 deletions packages/quatt_odu_simulator.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -323,21 +323,21 @@ 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
name: "ODU 2 forced defrost duration s"
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
Expand Down Expand Up @@ -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<unsigned long>(s.defrost_started),
static_cast<unsigned long>(s.defrost_completed),
static_cast<unsigned long>(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<unsigned long>(s.defrost_started),
static_cast<unsigned long>(s.defrost_completed),
static_cast<unsigned long>(s.defrost_aborted));
return {text};

- platform: template
name: "ODU 1 diagnostics"
entity_category: diagnostic
Expand Down
89 changes: 89 additions & 0 deletions tests/quatt_odu_manual_defrost_test.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
#include <cassert>
#include <limits>
#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<float>::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);
}
7 changes: 6 additions & 1 deletion tests/quatt_odu_simulator_model_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand All @@ -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
Expand Down
Loading