esphome 2024.9.2__py3-none-any.whl → 2024.10.0__py3-none-any.whl

esphome/components/opentherm/hub.cpp

@@ -0,0 +1,277 @@
+#include "hub.h"
+#include "esphome/core/helpers.h"
+
+#include <string>
+
+namespace esphome {
+namespace opentherm {
+
+static const char *const TAG = "opentherm";
+
+OpenthermData OpenthermHub::build_request_(MessageId request_id) {
+  OpenthermData data;
+  data.type = 0;
+  data.id = 0;
+  data.valueHB = 0;
+  data.valueLB = 0;
+
+  // First, handle the status request. This requires special logic, because we
+  // wouldn't want to inadvertently disable domestic hot water, for example.
+  // It is also included in the macro-generated code below, but that will
+  // never be executed, because we short-circuit it here.
+  if (request_id == MessageId::STATUS) {
+    bool const ch_enabled = this->ch_enable;
+    bool dhw_enabled = this->dhw_enable;
+    bool cooling_enabled = this->cooling_enable;
+    bool otc_enabled = this->otc_active;
+    bool ch2_enabled = this->ch2_active;
+
+    data.type = MessageType::READ_DATA;
+    data.id = MessageId::STATUS;
+    data.valueHB = ch_enabled | (dhw_enabled << 1) | (cooling_enabled << 2) | (otc_enabled << 3) | (ch2_enabled << 4);
+
+// Disable incomplete switch statement warnings, because the cases in each
+// switch are generated based on the configured sensors and inputs.
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wswitch"
+
+    // TODO: This is a placeholder for an auto-generated switch statement which builds request structure based on
+    // which sensors are enabled in config.
+
+#pragma GCC diagnostic pop
+
+    return data;
+  }
+  return OpenthermData();
+}
+
+OpenthermHub::OpenthermHub() : Component() {}
+
+void OpenthermHub::process_response(OpenthermData &data) {
+  ESP_LOGD(TAG, "Received OpenTherm response with id %d (%s)", data.id,
+           this->opentherm_->message_id_to_str((MessageId) data.id));
+  ESP_LOGD(TAG, "%s", this->opentherm_->debug_data(data).c_str());
+}
+
+void OpenthermHub::setup() {
+  ESP_LOGD(TAG, "Setting up OpenTherm component");
+  this->opentherm_ = make_unique<OpenTherm>(this->in_pin_, this->out_pin_);
+  if (!this->opentherm_->initialize()) {
+    ESP_LOGE(TAG, "Failed to initialize OpenTherm protocol. See previous log messages for details.");
+    this->mark_failed();
+    return;
+  }
+
+  // Ensure that there is at least one request, as we are required to
+  // communicate at least once every second. Sending the status request is
+  // good practice anyway.
+  this->add_repeating_message(MessageId::STATUS);
+
+  this->current_message_iterator_ = this->initial_messages_.begin();
+}
+
+void OpenthermHub::on_shutdown() { this->opentherm_->stop(); }
+
+void OpenthermHub::loop() {
+  if (this->sync_mode_) {
+    this->sync_loop_();
+    return;
+  }
+
+  auto cur_time = millis();
+  auto const cur_mode = this->opentherm_->get_mode();
+  switch (cur_mode) {
+    case OperationMode::WRITE:
+    case OperationMode::READ:
+    case OperationMode::LISTEN:
+      if (!this->check_timings_(cur_time)) {
+        break;
+      }
+      this->last_mode_ = cur_mode;
+      break;
+    case OperationMode::ERROR_PROTOCOL:
+      if (this->last_mode_ == OperationMode::WRITE) {
+        this->handle_protocol_write_error_();
+      } else if (this->last_mode_ == OperationMode::READ) {
+        this->handle_protocol_read_error_();
+      }
+
+      this->stop_opentherm_();
+      break;
+    case OperationMode::ERROR_TIMEOUT:
+      this->handle_timeout_error_();
+      this->stop_opentherm_();
+      break;
+    case OperationMode::IDLE:
+      if (this->should_skip_loop_(cur_time)) {
+        break;
+      }
+      this->start_conversation_();
+      break;
+    case OperationMode::SENT:
+      // Message sent, now listen for the response.
+      this->opentherm_->listen();
+      break;
+    case OperationMode::RECEIVED:
+      this->read_response_();
+      break;
+  }
+}
+
+void OpenthermHub::sync_loop_() {
+  if (!this->opentherm_->is_idle()) {
+    ESP_LOGE(TAG, "OpenTherm is not idle at the start of the loop");
+    return;
+  }
+
+  auto cur_time = millis();
+
+  this->check_timings_(cur_time);
+
+  if (this->should_skip_loop_(cur_time)) {
+    return;
+  }
+
+  this->start_conversation_();
+
+  if (!this->spin_wait_(1150, [&] { return this->opentherm_->is_active(); })) {
+    ESP_LOGE(TAG, "Hub timeout triggered during send");
+    this->stop_opentherm_();
+    return;
+  }
+
+  if (this->opentherm_->is_error()) {
+    this->handle_protocol_write_error_();
+    this->stop_opentherm_();
+    return;
+  } else if (!this->opentherm_->is_sent()) {
+    ESP_LOGW(TAG, "Unexpected state after sending request: %s",
+             this->opentherm_->operation_mode_to_str(this->opentherm_->get_mode()));
+    this->stop_opentherm_();
+    return;
+  }
+
+  // Listen for the response
+  this->opentherm_->listen();
+  if (!this->spin_wait_(1150, [&] { return this->opentherm_->is_active(); })) {
+    ESP_LOGE(TAG, "Hub timeout triggered during receive");
+    this->stop_opentherm_();
+    return;
+  }
+
+  if (this->opentherm_->is_timeout()) {
+    this->handle_timeout_error_();
+    this->stop_opentherm_();
+    return;
+  } else if (this->opentherm_->is_protocol_error()) {
+    this->handle_protocol_read_error_();
+    this->stop_opentherm_();
+    return;
+  } else if (!this->opentherm_->has_message()) {
+    ESP_LOGW(TAG, "Unexpected state after receiving response: %s",
+             this->opentherm_->operation_mode_to_str(this->opentherm_->get_mode()));
+    this->stop_opentherm_();
+    return;
+  }
+
+  this->read_response_();
+}
+
+bool OpenthermHub::check_timings_(uint32_t cur_time) {
+  if (this->last_conversation_start_ > 0 && (cur_time - this->last_conversation_start_) > 1150) {
+    ESP_LOGW(TAG,
+             "%d ms elapsed since the start of the last convo, but 1150 ms are allowed at maximum. Look at other "
+             "components that might slow the loop down.",
+             (int) (cur_time - this->last_conversation_start_));
+    this->stop_opentherm_();
+    return false;
+  }
+
+  return true;
+}
+
+bool OpenthermHub::should_skip_loop_(uint32_t cur_time) const {
+  if (this->last_conversation_end_ > 0 && (cur_time - this->last_conversation_end_) < 100) {
+    ESP_LOGV(TAG, "Less than 100 ms elapsed since last convo, skipping this iteration");
+    return true;
+  }
+
+  return false;
+}
+
+void OpenthermHub::start_conversation_() {
+  if (this->sending_initial_ && this->current_message_iterator_ == this->initial_messages_.end()) {
+    this->sending_initial_ = false;
+    this->current_message_iterator_ = this->repeating_messages_.begin();
+  } else if (this->current_message_iterator_ == this->repeating_messages_.end()) {
+    this->current_message_iterator_ = this->repeating_messages_.begin();
+  }
+
+  auto request = this->build_request_(*this->current_message_iterator_);
+
+  ESP_LOGD(TAG, "Sending request with id %d (%s)", request.id,
+           this->opentherm_->message_id_to_str((MessageId) request.id));
+  ESP_LOGD(TAG, "%s", this->opentherm_->debug_data(request).c_str());
+  // Send the request
+  this->last_conversation_start_ = millis();
+  this->opentherm_->send(request);
+}
+
+void OpenthermHub::read_response_() {
+  OpenthermData response;
+  if (!this->opentherm_->get_message(response)) {
+    ESP_LOGW(TAG, "Couldn't get the response, but flags indicated success. This is a bug.");
+    this->stop_opentherm_();
+    return;
+  }
+
+  this->stop_opentherm_();
+
+  this->process_response(response);
+
+  this->current_message_iterator_++;
+}
+
+void OpenthermHub::stop_opentherm_() {
+  this->opentherm_->stop();
+  this->last_conversation_end_ = millis();
+}
+
+void OpenthermHub::handle_protocol_write_error_() {
+  ESP_LOGW(TAG, "Error while sending request: %s",
+           this->opentherm_->operation_mode_to_str(this->opentherm_->get_mode()));
+  ESP_LOGW(TAG, "%s", this->opentherm_->debug_data(this->last_request_).c_str());
+}
+
+void OpenthermHub::handle_protocol_read_error_() {
+  OpenThermError error;
+  this->opentherm_->get_protocol_error(error);
+  ESP_LOGW(TAG, "Protocol error occured while receiving response: %s", this->opentherm_->debug_error(error).c_str());
+}
+
+void OpenthermHub::handle_timeout_error_() {
+  ESP_LOGW(TAG, "Receive response timed out at a protocol level");
+  this->stop_opentherm_();
+}
+
+#define ID(x) x
+#define SHOW2(x) #x
+#define SHOW(x) SHOW2(x)
+
+void OpenthermHub::dump_config() {
+  ESP_LOGCONFIG(TAG, "OpenTherm:");
+  LOG_PIN("  In: ", this->in_pin_);
+  LOG_PIN("  Out: ", this->out_pin_);
+  ESP_LOGCONFIG(TAG, "  Sync mode: %d", this->sync_mode_);
+  ESP_LOGCONFIG(TAG, "  Initial requests:");
+  for (auto type : this->initial_messages_) {
+    ESP_LOGCONFIG(TAG, "  - %d", type);
+  }
+  ESP_LOGCONFIG(TAG, "  Repeating requests:");
+  for (auto type : this->repeating_messages_) {
+    ESP_LOGCONFIG(TAG, "  - %d", type);
+  }
+}
+
+}  // namespace opentherm
+}  // namespace esphome

esphome/components/opentherm/hub.h

@@ -0,0 +1,110 @@
+#pragma once
+
+#include "esphome/core/defines.h"
+#include "esphome/core/hal.h"
+#include "esphome/core/component.h"
+#include "esphome/core/log.h"
+
+#include "opentherm.h"
+
+#include <memory>
+#include <unordered_map>
+#include <unordered_set>
+#include <functional>
+
+namespace esphome {
+namespace opentherm {
+
+// OpenTherm component for ESPHome
+class OpenthermHub : public Component {
+ protected:
+  // Communication pins for the OpenTherm interface
+  InternalGPIOPin *in_pin_, *out_pin_;
+  // The OpenTherm interface
+  std::unique_ptr<OpenTherm> opentherm_;
+
+  // The set of initial messages to send on starting communication with the boiler
+  std::unordered_set<MessageId> initial_messages_;
+  // and the repeating messages which are sent repeatedly to update various sensors
+  // and boiler parameters (like the setpoint).
+  std::unordered_set<MessageId> repeating_messages_;
+  // Indicates if we are still working on the initial requests or not
+  bool sending_initial_ = true;
+  // Index for the current request in one of the _requests sets.
+  std::unordered_set<MessageId>::const_iterator current_message_iterator_;
+
+  uint32_t last_conversation_start_ = 0;
+  uint32_t last_conversation_end_ = 0;
+  OperationMode last_mode_ = IDLE;
+  OpenthermData last_request_;
+
+  // Synchronous communication mode prevents other components from disabling interrupts while
+  // we are talking to the boiler. Enable if you experience random intermittent invalid response errors.
+  // Very likely to happen while using Dallas temperature sensors.
+  bool sync_mode_ = false;
+
+  // Create OpenTherm messages based on the message id
+  OpenthermData build_request_(MessageId request_id);
+  void handle_protocol_write_error_();
+  void handle_protocol_read_error_();
+  void handle_timeout_error_();
+  void stop_opentherm_();
+  void start_conversation_();
+  void read_response_();
+  bool check_timings_(uint32_t cur_time);
+  bool should_skip_loop_(uint32_t cur_time) const;
+  void sync_loop_();
+
+  template<typename F> bool spin_wait_(uint32_t timeout, F func) {
+    auto start_time = millis();
+    while (func()) {
+      yield();
+      auto cur_time = millis();
+      if (cur_time - start_time >= timeout) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+ public:
+  // Constructor with references to the global interrupt handlers
+  OpenthermHub();
+
+  // Handle responses from the OpenTherm interface
+  void process_response(OpenthermData &data);
+
+  // Setters for the input and output OpenTherm interface pins
+  void set_in_pin(InternalGPIOPin *in_pin) { this->in_pin_ = in_pin; }
+  void set_out_pin(InternalGPIOPin *out_pin) { this->out_pin_ = out_pin; }
+
+  // Add a request to the set of initial requests
+  void add_initial_message(MessageId message_id) { this->initial_messages_.insert(message_id); }
+  // Add a request to the set of repeating requests. Note that a large number of repeating
+  // requests will slow down communication with the boiler. Each request may take up to 1 second,
+  // so with all sensors enabled, it may take about half a minute before a change in setpoint
+  // will be processed.
+  void add_repeating_message(MessageId message_id) { this->repeating_messages_.insert(message_id); }
+
+  // There are five status variables, which can either be set as a simple variable,
+  // or using a switch. ch_enable and dhw_enable default to true, the others to false.
+  bool ch_enable = true, dhw_enable = true, cooling_enable = false, otc_active = false, ch2_active = false;
+
+  // Setters for the status variables
+  void set_ch_enable(bool value) { this->ch_enable = value; }
+  void set_dhw_enable(bool value) { this->dhw_enable = value; }
+  void set_cooling_enable(bool value) { this->cooling_enable = value; }
+  void set_otc_active(bool value) { this->otc_active = value; }
+  void set_ch2_active(bool value) { this->ch2_active = value; }
+  void set_sync_mode(bool sync_mode) { this->sync_mode_ = sync_mode; }
+
+  float get_setup_priority() const override { return setup_priority::HARDWARE; }
+
+  void setup() override;
+  void on_shutdown() override;
+  void loop() override;
+  void dump_config() override;
+};
+
+}  // namespace opentherm
+}  // namespace esphome