Peter M. Groen / EasyOpenTherm

/*
 *    https://github.com/Jeroen88/EasyOpenTherm
 *    https://www.tindie.com/products/Metriot/OpenTherm-adapter/
 *
 *    This software needs an OpenTherm controller like 
 *    https://www.tindie.com/products/Metriot/OpenTherm-adapter/ or
 *    https://www.tindie.com/products/Metriot/OpenTherm-adapter/ connected to a BOILER  SUPPORTING
 *    THE OPENTHERM PROTOCOL, an ESP32-S2 mini, ESP32-C3 mini or ESP8266 flashed with this 
 *    software and Home Assistant or any other MQTT enabled home automation environment.
 *
 *    MQTT_Advanced_Thermostat is a real working thermostat over MQTT. It offers a HIGH LEVEL API
 *    (OFF / HEAT / COOL / AUTO and room temperature setpoint) to control your boiler from any other 
 *    system.
 *    
 *    It is SUPPOSED TO LOWER your energy bills, because  it modulates the boiler's maximum power. This 
 *    MAY lead to a LONGER PERIOD OF TIME before your room temperature setpoint is reached. If you are 
 *    not happy with it's present behaviour, please change any of the settings or program your OWN
 *    heating or cooling STRATEGY!
 *
 *    The easiest way to use this thermostat is from Home Assistant:
 *    - Set up a MQTT broker and integration in Home Assistant, if not already done
 *      (https://www.home-assistant.io/integrations/mqtt/). The MQTT broker should be reachable without
 *      using certificates (TLS).
 *    - Change the WiFi credentials and MQTT credentials in this software
 *    - Flash this software to a ESP32-S2 mini, connect the ESP to the OpenTherm Adapter and connect the
 *      OpenTherm Adapter to the boiler with the two wires of your present thermostat (replace it)
 *    - See also both README.md's in the main and Examples directory
 *    THAT'ALL, all integrations should automatically appear in Home Assistant and be active!
 *     
 *    Although it is designed to work with Home Assistant and it's MQTT integration, it can function
 *    in any home automation system as long as it has an MQTT integration.
 *    This program is developed and tested for a boiler, but could be easily adapted to work with HVAC
 *    systems too.
 *    Domestic Hot Water is supported if present (enabled by default and a sensor shows if the boiler
 *    is running for DHW). A secondary Heating cicuit (CH2) is not supported nor is Outside Temperature
 *    Compensation (OTC). If the boiler supports cooling too this is supported (though not tested).
 *    The Home Assistant MQTT Auto Discovery feature is used to automatically add a Climate (thermostat)
 *    entity to the user interface. Also several other sensors are added, like flame on / off, boiler
 *    flow and return water temperatures, WiFi RSSI, boiler water pressure, etc, depending on the 
 *    boiler's capabilities.
 *
 *    This thermostat subscribes to a MQTT topic, Metriot/EasyOpenTherm/112233445566/climate/state
 *    (with 112233445566 being replaced by an unique chip ID) to receive a (frequent) room temperature 
 *    update. THIS THERMOSTAT CAN NOT FUNCTION WITHOUT A REGULAR TEMPERATURE UPDATE. Temperature updates 
 *    should be send in the format {"temperature": 20,1}.
 *    
 *    This thermostat subscribes to a MQTT topic, Metriot/EasyOpenTherm/112233445566/mode/set
 *    to receive a mode (OFF, HEAT, COOL or AUTO). THIS THERMOSTAT CAN NOT FUNCTION WITHOUT A
 *    A MODE UPDATE, since it starts in 'OFF' state. Mode updates should be send as plain text without
 *    any leading or trailing spaces, in capitals, e.g. HEAT.
 *    
 *    This thermostat publishes to a MQTT topic, Metriot/EasyOpenTherm/112233445566/climate/state
 *    the local temperature measures by an onboard sensor (if enabled). The value message is a JSON, 
 *    e.g.: {"local_temperature": 20.1}. The software already has support for a Dallas Sensor that can be
 *    enabled by defining the one wire pin the sensor is connected to (const int oneWireBus). If you want
 *    to use this temperature as room temperature, you have to write an automation that subscribes to the
 *    above topic, extracts the temperature and publishes it in the right format to the room temperature
 *    update topic (see above).
 *    
 *    Unlike other examples on the internet, MQTT_Advanced_Thermostat already is a fully functional 
 *    thermostat: just configure it once change, regularly publish the room temperature and update the the 
 *    room temperature setpoint any time your boiler to heat up the room to that setpoint.
 *
 *    Use your home automation system, like Home Assistant or Domoticz, to create e.g. schedules
 *    and geo fencing, and have this program control your boiler by just setting the room 
 *    temperature setpoint.
 *
 *    Please note that after a reboot or a power cycle the thermostat starts in 'OFF' mode. This
 *    means that it will never activate the boiler after such an event. An 'ON' request is needed to 
 *    (re-)activate the boiler.
 *
 *    Copyright (C) 2022  Jeroen Döll <info@metriot.nl>
 *
 *    This program is free software: you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation, either version 3 of the License, or
 *    (at your option) any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 *    You need an OpenTherm controller that you can buy at my Tindie store, see <https://www.tindie.com/products/jeroen88/opentherm-controller/>
 *    Connect the two boiler wires to the OpenTherm controller pins marked OT. The order of the wires is not important.
 *    Connect the OpenTherm controller to your microcontroller's power (3v3) and ground (GND) pins.
 *    Connect the OpenTherm TXD pin to the microcontroller's pin defined by #define OT_RX_PIN.
 *    Connect the OpenTherm RXD pin to the microcontroller's pin defined by #define OT_TX_PIN.
 *
 *    You can also use this shield  <https://www.tindie.com/products/jeroen88/opentherm-controller/> and an
 *    ESP32-S2 mini, an ESP32-C3 mini or an ESP D1 mini (the latter not tested yet). With this shield all pins are already 
 *    connected. The only thing you have to connect are the two OpenTherm thermostat wires.
 *
 *    If needed, connect a Dallas Temperature Sensor to the right pin or, if you use the above shield, use the onboard sensor.
 *    Make sure though that the mesured temperature is not influenced too much by the heat produced by the processor. An 
 *    ESP32-S2 e.g. becomes too hot and is too close to the sensor to produce valid readings.
 *    Any other temperature sensor may be used, like a BME280, BME380, BMP380, BME680 if you adapt the program accordingly.
 *
 *    I hope you enjoy working with this library, please share ideas in the Github Discussions sessions of this library.
 */


static const char * TAG = __FILE__;

#if !defined(ESP32) && !defined(ESP_LOGE)
#define ESP_LOGE(...)
#define ESP_LOGI(...)
#define ESP_LOGV(...)
#endif

#include <Arduino.h>

#if defined(ESP8266)
#include <ESP8266WiFi.h>
#else
#include <WiFi.h>
#endif

#include <time.h>

#include <ArduinoJson.h>

#include <OneWire.h>
#include <DallasTemperature.h>

#include <PubSubClient.h>

#include <EasyOpenTherm.h>

#include "OpenThermHelpers.h"
#include "JSONs.h"
#include "MQTTHelpers.h"
#include "ThermoStateMachine.h"


// Update these with values suitable for your network.
const char * ssid = "YOUR WIFI NETWORK NAME";
const char * password = "YOUR WIFI PASSWORD";


// Update these with values suitable for your MQTT broker, in this example TLS or certificates are not used
const char * mqtt_server = "YOUR MQTT SERVER NAME OR IP ADDRESS";
const char * mqtt_user = "YOUR MQTT USER NAME";
const char * mqtt_password = "YOUR MQTT PASSWORD";
const char * MQTT_ID = "EasyOpenTherm";   // Should be unique for your broker, see e.g. https://stackoverflow.com/questions/40078252/mosquitto-prevent-duplicate-login


// Your time zone, used to display times correctly (and needed for WiFiClientSecure TLS certificate validation, if used)
#define TZ_Europe_Amsterdam	"CET-1CEST-2,M3.5.0,M10.5.0/3"
#define TIME_ZONE TZ_Europe_Amsterdam


// Define OT_RX_PIN, the GPIO pin used to read data from the boiler or HVAC (TxD). Must support interrupts
// Define OT_TX_PIN, the GPIO pin used to send data to the boiier or HVAC (RxD). Must not be a 'read only' GPIO
// Define DALLAS, the GPIO pin used for the Dallas sensor, if used

#if defined(ARDUINO_LOLIN_S2_MINI)
#define OT_RX_PIN (35)
#define OT_TX_PIN (33)
#define DALLAS (11)
#elif defined(ARDUINO_LOLIN_C3_MINI)
#define OT_RX_PIN (10)
#define OT_TX_PIN (8)
#define DALLAS (4)
#elif defined(ARDUINO_ESP8266_WEMOS_D1MINIPRO)
// I can't get my "D1 MINI PRO Based ESP8266EX" passed a WiFi connection
// D1 is GPIO5
#define OT_RX_PIN (5)
// D2 is GPIO4
#define OT_TX_PIN (4)
// D7 is GPIO13
#define DALLAS (13)
#elif defined(ESP32)
#define OT_RX_PIN (33)
#define OT_TX_PIN (16)
#define DALLAS (17)
#elif defined(ESP8266)
// GPIO5 is D1
#define OT_RX_PIN (5)
// GPIO4 is D2
#define OT_TX_PIN (4)
// D7 is GPIO13
#define DALLAS (13)
#else
#define OT_RX_PIN (35)
#define OT_TX_PIN (33)
#define DALLAS (-1)
#endif


// The maximum room temperature
#define ROOM_TEMPERATURE_MAX_SETPOINT (30.0f)
// The minimum room temperature
#define ROOM_TEMPERATURE_MIN_SETPOINT (10.0f)
// The maximum Central Heating boiler temperature. If your house is well isolated and/or you have low temperature radiators this could be as low as 40.0f
#define CH_MAX_SETPOINT (60.0f)
// The minimum Central Heating boiler temperature. If the boiler can cool set this to a realistic minimum temperature. If the boiler can only heat, this value
// is also used as an extra way to switch the boiler OFF
#define CH_MIN_SETPOINT (10.0f)

// Cheap sensor tend to be inaccurate. Accuracy can be increased by adding two temperatures as measured by the sensor and the 'real' temperature as measured with a calibrated thermometer
// If your sensor is accurate or if you do not want to use this feature, set measured and calibrated values to the same value
// Make sure that the lower temperatures and higher temperatures are a few degrees apart. Ideal would be to use temperatures around the minimum room temperature setpoint and the maximum room 
// temperature setpoint
// Make sure that the difference between both lower temperatures and both higher temperatures is about the same, otherwise your temperature sensor is really bad and you might get strange results 
// from recalculateTemperatures();
// Only used for (on board) temperature sensors, the room temperature coming in from MQTT is deemed to be correct
// https://www.letscontrolit.com/wiki/index.php?title=Basics:_Calibration_and_Accuracy
#define LOWER_MEASURED_TEMPERATURE (15.0)
#define LOWER_CALIBRATED_TEMPERATURE (15.0)
#define HIGHER_MEASURED_TEMPERATURE (20.0)
#define HIGHER_CALIBRATED_TEMPERATURE (20.0)


// Interval for publishing the thermostat state information (in seconds)
#define PUBLISH_STATE_UPDATE_INTERVAL (10)

// Minimum interval for running the PID controller (in seconds)
#define PID_INTERVAL_S (5)


// MQTT client message buffer sizes, must be big enough to store a full message
const size_t MSG_BUFFER_SEND_SIZE = 2 * 1024;
const size_t MSG_BUFFER_RECV_SIZE = 256;  // Too small a receive buffer will fail on receiving subscribed topics...

// Define a global WiFiClient instance for WiFi connection
WiFiClient  wiFiClient;

PubSubClient *mqtt = NULL;


// GPIO where the DS18B20 is connected to, set to '-1' if not used
//const int oneWireBus = DALLAS;
const int oneWireBus = -1;

// Define a pointer to oneWire instance to communicate with any OneWire devices
OneWire * oneWire = nullptr;

// Define a pointer to DallasTemperature instance to communicate with any OneWire devices
DallasTemperature * dallasSensors = nullptr;


// Create a global OpenTherm instance called 'thermostat' (i.e primary and boiler is secondary) with OT_RX_PIN to receive data from boiler and OT_TX_PIN to send data to boiler
// Only one OpenTherm object may be created!
OpenTherm thermostat(OT_RX_PIN, OT_TX_PIN);


// Use a PID controller to calculate the CH setpoint. See e.g. https://en.wikipedia.org/wiki/PID_controller
float pid(float                                 sp, 
          float                                 pv, 
          float                                 pv_last, 
          float &                               ierr, 
          float                                 dt) {
  float KP = 30;
  float KI = 0.02;

  float error = sp - pv;
  ierr = ierr + KI * error * dt;
  float dpv = (pv - pv_last) / dt;
  float P = KP * error;
  float I = ierr;  
  float op = P + I;
  // anti-reset windup
  if ((op < CH_MIN_SETPOINT) || (op > CH_MAX_SETPOINT)) {
    I = I - KI * error * dt;
    op = max(CH_MIN_SETPOINT, min(CH_MAX_SETPOINT, op));
  }
  ierr = I;

  op = roundf(op * 10.0f) / 10.0f;  // Round to one decimal
  
  return op;
}


// Lineair recalculation of the temperature measured by the sensor using two calibrated temperatures. Round to two decimals
float recalculateTemperature(float temperature) {
  // y = ax + b
  if(LOWER_MEASURED_TEMPERATURE == HIGHER_MEASURED_TEMPERATURE) return temperature;     // Lower and higher temperatures should be a few degrees apart, so this is wrong. Return the measured temperature
  float a = float(HIGHER_CALIBRATED_TEMPERATURE - LOWER_CALIBRATED_TEMPERATURE) / float(HIGHER_MEASURED_TEMPERATURE - LOWER_MEASURED_TEMPERATURE);
  float b = float(LOWER_CALIBRATED_TEMPERATURE) - a * float(LOWER_MEASURED_TEMPERATURE);
  return roundf(100.0f * a * (temperature + b)) / 100.0f;
}


// Global variables that are set by incoming MQTT messages and used by loop()
// Global variable to store the room temperature setpoint. 
float roomTemperatureSetpoint = ROOM_TEMPERATURE_MIN_SETPOINT;
// Global variable to store OFF/AUTO/HEAT/COOL requests to the boiler
ThermostatRequest thermostatRequest = ThermostatRequest::NONE;
// Global variable to keep track of the lastest room temperature update timestamp (in seconds)
uint32_t roomTemperatureTimestampS = 0;
// Global variable to store the room temperature
float roomTemperature;


// ============== Subscription callbacks ========================================
void PubSubClientCallback(char* topic, byte* payload, unsigned int length) {
  // handle message arrived
	char payloadReceived[length + 1];
	memcpy(payloadReceived, payload, length);
	payloadReceived[length] = '\0';

  Serial.printf("Received topic '%s' with payload '%s'\n", topic, payloadReceived);

  const char * subscriptionTopic = topicByReference("temperature_command_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
  if(subscriptionTopic == nullptr) return;
  if(strcmp(topic, subscriptionTopic) == 0) return processSetpointTemperatureMessage(payloadReceived);

  subscriptionTopic = topicByReference("mode_command_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
  if(subscriptionTopic == nullptr) return;
  if(strcmp(topic, subscriptionTopic) == 0) return processClimateMessage(payloadReceived);

  subscriptionTopic = topicByReference("current_temperature_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
  if(subscriptionTopic == nullptr) return;
  if(strcmp(topic, subscriptionTopic) == 0) return processRoomTemperatureMessage(payloadReceived);

  Serial.printf("Received unhandled topic '%s' with payload '%s'\n", topic, payloadReceived);
}


void processRoomTemperatureMessage(const char * payload) {
Serial.println("processRoomTemperatureMessage");

  StaticJsonDocument<32> roomTemperatureMsgDoc;
  DeserializationError error = deserializeJson(roomTemperatureMsgDoc, payload);
  if(error) {
    ESP_LOGE(TAG, "Parsing JSON payload failed (%s): '%s'", error.f_str(), payload);
Serial.printf("Parsing JSON payload failed (%s): '%s'\n", error.f_str(), payload);

    return;
  }
  
  if(!roomTemperatureMsgDoc.containsKey("temperature")) {
    ESP_LOGE(TAG, "\"temperature\" tag is missing in JSON payload: '%s'", payload);
Serial.printf("\"temperature\" tag is missing in JSON payload: '%s'\n", payload);

    return;
  }

// What if {"temperature":15.3} a non float value is send? Value will evaluate to zero, which is also a valid temperature...

  ESP_LOGI(TAG, "Received room temperature '%s'", payload);
  roomTemperatureTimestampS = time(nullptr);
  roomTemperature = roomTemperatureMsgDoc["temperature"];
Serial.printf("Received room temperature %.01f ºC\n", roomTemperature);
}


void processSetpointTemperatureMessage(const char * payload) {
  float setpoint;
  if(sscanf(payload, "%f", &setpoint) != 1) {
    ESP_LOGE(TAG, "Payload is not a float: '%s'", payload);

    return;
  }
  
  ESP_LOGI(TAG, "Received room temperature setpoint '%s'", payload);
Serial.printf("Received room temperature setpoint '%s'\n", payload);
  roomTemperatureSetpoint = setpoint;
}


void processClimateMessage(const char * payload) {
	ESP_LOGI(TAG,
		"Message arrived: qos %d, retained %d, dup %d, packetid %d, payload:[%s]",
		msg.qos, msg.retained, msg.dup, msg.id, payload
	);
Serial.printf("processClimateMessage PAYLOAD: '%s'\n", payload);
  ESP_LOGI(TAG, "processClimateMessage PAYLOAD: '%s'", payload);

  if(strcasecmp(payload, "off") == 0) {
    thermostatRequest = ThermostatRequest::OFF;
  } else if(strcasecmp(payload, "auto") == 0) {
    thermostatRequest = ThermostatRequest::AUTO;
  } else if(strcasecmp(payload, "heat") == 0) {
    thermostatRequest = ThermostatRequest::HEAT;
  } else if(strcasecmp(payload, "cool") == 0) {
    thermostatRequest = ThermostatRequest::COOL;
  }
}


void setup() {
  Serial.begin(115200);
  delay(5000);                                                     // For debug only: give the Serial Monitor some time to connect to the native USB of the MCU for output
  Serial.println("\n\nStarted");
  Serial.printf("Chip ID is %s\n", chipID());
  Serial.printf("Short ID is %s\n", shortID());

  Serial.printf("OpenTherm RX pin is %d, TX pin is %d\n", OT_RX_PIN, OT_TX_PIN);

//  pinMode(LED_BUILTIN, OUTPUT);

  // Connect WiFi
  WiFi.mode(WIFI_STA);
  WiFi.setAutoReconnect(true);
  WiFi.setAutoReconnect(false);
  WiFi.begin(ssid, password);

  uint32_t startMillis = millis();  
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
//    digitalWrite(LED_BUILTIN, digitalRead(LED_BUILTIN) == LOW ? HIGH : LOW);

    if(millis() - startMillis > 15000) ESP.restart();
  }

  Serial.printf("WiFi connected to %s\n", ssid);
  Serial.printf("IP address: %s\n", WiFi.localIP().toString().c_str());

// Set time and date, necessary for HTTPS certificate validation
  configTzTime(TIME_ZONE, "pool.ntp.org", "time.nist.gov");
  setenv("TZ", TIME_ZONE, 1); // Set environment variable with your time zone
  tzset();

  Serial.println("Waiting for NTP time sync: ");
  time_t now = time(nullptr);
  startMillis = millis();
  while (now < 8 * 3600 * 2) {
    delay(100);
    digitalWrite(LED_BUILTIN, digitalRead(LED_BUILTIN) == LOW ? HIGH : LOW);
    Serial.print(".");
    now = time(nullptr);

    if(millis() - startMillis > 15000) ESP.restart();
  }
#if defined(ESP8266)
  digitalWrite(LED_BUILTIN, HIGH);
#else
  digitalWrite(LED_BUILTIN, LOW);
#endif
  Serial.println();

  const struct tm  * timeinfo = localtime(&now);
  Serial.printf("%s %s", tzname[0], asctime(timeinfo));

  if(oneWireBus != -1) {
    oneWire = new OneWire(oneWireBus);
    dallasSensors = new DallasTemperature(oneWire);

    // Start the DS18B20 sensor
    dallasSensors->begin();
    dallasSensors->setWaitForConversion(false);
    dallasSensors->requestTemperatures(); 

  }

  // Do not let PubSubClient handle the TCP/IP socket connection, because of connection issues
  Serial.println("Connect to MQTT broker...");
  wiFiClient.connect(mqtt_server, 1883);
  if(!wiFiClient.connected()) {
    ESP_LOGE(TAG, "Can't establish the TCP connection");
    delay(5000);
    ESP.restart();
  }

	// Setup MQTT client
  mqtt = new PubSubClient(wiFiClient);
  mqtt->setBufferSize(1024);
  mqtt->setCallback(PubSubClientCallback);

  bool MQTTConnected = connectMQTT(*mqtt, MQTT_ID, mqtt_user, mqtt_password);
  if(MQTTConnected) {
    ESP_LOGI(TAG, "MQTT connected");
Serial.println("MQTT connected");
  } else {
    ESP_LOGI(TAG, "MQTT NOT connected");
Serial.println("MQTT NOT connected");
    delay(30000);

    return;
  }

  // Set all IDs for all discovery messages
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_SETPOINT_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLOW_TEMPERATURE_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_RETURN_TEMPERATURE_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_WATER_PRESSURE_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_RELATIVE_MODULATION_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_RSSI_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLAME_BINARY_SENSOR);
  discoveryMessageSetIDs(EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR);

  // Check all JSONs by parsing the JSONs
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_SETPOINT_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_SETPOINT_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLOW_TEMPERATURE_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLOW_TEMPERATURE_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_RETURN_TEMPERATURE_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RETURN_TEMPERATURE_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_WATER_PRESSURE_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_WATER_PRESSURE_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_RELATIVE_MODULATION_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RELATIVE_MODULATION_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_RSSI_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RSSI_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLAME_BINARY_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLAME_BINARY_SENSOR);
  if(!validJson(EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR)) Serial.printf("Invalid JSON '%s'\n", EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR);

  // Add all 'always present' entities (the other entities are added only if supported by the boiler)
  Serial.println("Add default entities to Home Assistant by publishing discovery messages to MQTT broker...");
  addEntity(*mqtt, "climate", "climate", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
  addEntity(*mqtt, "sensor", "boiler_setpoint", EASYOPENTHERM_MQTT_DISCOVERY_MSG_SETPOINT_SENSOR);
  addEntity(*mqtt, "sensor", "thermostat_rssi", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RSSI_SENSOR);
  addEntity(*mqtt, "binary_sensor", "boiler_flame", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLAME_BINARY_SENSOR);

  // Set all sensors, except those that are directly updated, to 'None', the binary sensor to 'Unknown'
  Serial.println("Set sensor values to 'none' by publishing to MQTT sensor state topics...");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_SETPOINT_SENSOR), "{\"ch_setpoint\":\"None\"}");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLOW_TEMPERATURE_SENSOR), "{\"flow_temperature\":\"None\"}");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RETURN_TEMPERATURE_SENSOR), "{\"return_temperature\":\"None\"}");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_WATER_PRESSURE_SENSOR), "{\"water_pressure\":\"None\"}");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RELATIVE_MODULATION_SENSOR), "{\"relative_modulation\":\"None\"}");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLAME_BINARY_SENSOR), "{\"flame\":\"None\"}");
  publish(*mqtt, topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR), "{\"dhw\":\"None\"}");

  Serial.println("Setup done, start loop...");
}


// updateClimateEntity()
// If the boikler can both heat and cool adds 'auto', 'off', 'cool' and 'heat' to the thermmostat modes
// If the boikler can only heat adds 'off' and 'heat' to the thermmostat modes
void updateClimateEntity(bool                           canCool) {
//  StaticJsonDocument<fullJsonDocSize> discoveryMsgDoc;
  DynamicJsonDocument discoveryMsgDoc(fullJsonDocSize);

  if(discoveryMsgToJsonDoc(discoveryMsgDoc, EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE)) {
    JsonArray modesArray = discoveryMsgDoc["modes"];
    if(canCool) {
      modesArray.add("auto");
      modesArray.add("off");
      modesArray.add("cool");
    } else {
      modesArray.add("off");        
    }
    modesArray.add("heat");

    addEntity(*mqtt, "climate", "climate", discoveryMsgDoc);

    const char * availabilityTopic = topicByReference("availability_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
    publish(*mqtt, availabilityTopic, "{\"climate_available\":\"ONLINE\"}");
  }
}


// Adds a DHW binary sensor entity, only if the boiler can run for Domestic Hot Water
void updateDHWEntity(bool                             enableDHW) {
  if(enableDHW) {
    addEntity(*mqtt, "binary_sensor", "boiler_dhw", EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR);

    const char * topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR);
    publish(*mqtt, topic, "{\"dhw\":\"OFF\"}");
  } else {
    addEntity(*mqtt, "binary_sensor", "boiler_dhw", "");
  }
}


// updateFlameSensor
// Update the value of the flame sensor in Home Assistant. Usually this sensor reacts within one second
// If the sensor is 'ON' the boiler is running for Central Heating or Domestic Hot Water (see updateDHWSensor to see which is active)
// If the sensor is 'OFF' the boiler is idle (no heat demand)
void updateFlameSensor(uint8_t                          statusFlags) {
  static bool flameSensorInitialised = false;
  static uint8_t previousStatusFlags = 0;

  if(!flameSensorInitialised || (statusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_FLAME_STATUS)) != (previousStatusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_FLAME_STATUS))) {
    const char * topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLAME_BINARY_SENSOR);
    if(statusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_FLAME_STATUS)) {
      publish(*mqtt, topic, "{\"flame\":\"ON\"}");
    } else {
      publish(*mqtt, topic, "{\"flame\":\"OFF\"}");
    }
    previousStatusFlags = statusFlags;
    flameSensorInitialised = true;
  }
}


// updateDHWSensor
// Update the value of the DHW sensor in Home Assistant. Usually this sensor reacts within one second
// If the sensor is 'ON' the boiler is running for Domestic Hot Water
// If the sensor is 'OFF' the boiler is either idle or running for Central Heating (this can be checked woth the flame sensor)
void updateDHWSensor(uint8_t                            statusFlags) {
  static uint8_t previousStatusFlags = 0;

  bool changedDHW = (statusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_DHW_MODE)) != (previousStatusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_DHW_MODE)) |
                    (statusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_CH_MODE)) != (previousStatusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_CH_MODE));
  if(changedDHW) {
    const char * topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_DHW_BINARY_SENSOR);
    if(statusFlags & uint8_t(OpenTherm::STATUS_FLAGS::SECONDARY_DHW_MODE)) {
      publish(*mqtt, topic, "{\"dhw\":\"ON\"}");
    } else {
      publish(*mqtt, topic, "{\"dhw\":\"OFF\"}");
    }
    previousStatusFlags = statusFlags;
  }
}


// updateSensors
// Update the values of all 'interval' sensors in Home Assistant by sending the value in the right format to the topic looked up in the discovery JSON. OpenTherm sensor can be read and do not have 
// an entity yet in Home Assistant are created by sending the discovery JSON to the right '/config' topic.
void updateSensors(PubSubClient &                       client,
                    bool                                isConnectedOT,
                    float                               CHSetpoint,
                    uint32_t &                          previousOTCommunicationMs) {
  if(client.connected()) {
    char payload[64];
    const char * topic;

    // Publish RSSI
    snprintf(payload, sizeof payload, "{\"RSSI\":%d}", WiFi.RSSI());
    topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RSSI_SENSOR);
    publish(client, topic, payload);

    // Publish the Dallas sensor value if such a sensor is present. This value can be used as room temperatur value using an automation in Home Assistant publishing it back to the same topic
    // but with the JSON key 'temperature' instead
    if(dallasSensors) {
      snprintf(payload, sizeof payload, "{\"local_temperature\":%.01f}", recalculateTemperature(dallasSensors->getTempCByIndex(0)));
      topic = topicByReference("current_temperature_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
      publish(client, topic, payload);
    }

    if(isConnectedOT) {
      // Publish the Central Heating setpoint temperature
      snprintf(payload, sizeof payload, "{\"ch_setpoint\":%.01f}", CHSetpoint);
      topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_SETPOINT_SENSOR);
      publish(client, topic, payload);

      float value;
      // Test if Relative Modulation Level can be read from the boiler
      if(readSensor(thermostat, OpenTherm::READ_DATA_ID::RELATIVE_MODULATION_LEVEL, value, previousOTCommunicationMs)) {
        Serial.printf("Relative Modulation level is %.01f %\n", value);
        // Use a static variable to keep track of the entity already being created
        static bool relativeModulationLevelDiscoveryPublished = false;
        if(!relativeModulationLevelDiscoveryPublished) {
          // Create the entity
          addEntity(client, "sensor", "relative_modulation", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RELATIVE_MODULATION_SENSOR);
          relativeModulationLevelDiscoveryPublished = true;
        }
        // Publish the Relative Modulation Level
        snprintf(payload, sizeof payload, "{\"relative_modulation\":%.01f}", value);
        topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RELATIVE_MODULATION_SENSOR);
        publish(client, topic, payload);
      }

      // Test if Relative Central Heating Water Pressure can be read from the boiler
      if(readSensor(thermostat, OpenTherm::READ_DATA_ID::CH_WATER_PRESSURE, value, previousOTCommunicationMs)) {
        Serial.printf("Central Heating water pressure is %.01f bar\n", value);
        // Use a static variable to keep track of the entity already being created
        static bool waterPressureEntityAdded = false;
          // Create the entity
        if(!waterPressureEntityAdded) {
          addEntity(client, "sensor", "water_pressure", EASYOPENTHERM_MQTT_DISCOVERY_MSG_WATER_PRESSURE_SENSOR);
          waterPressureEntityAdded = true;
        }
        // Publish the Central Heating Water Pressure
        snprintf(payload, sizeof payload, "{\"water_pressure\":%.01f}", value);
        topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_WATER_PRESSURE_SENSOR);
        publish(client, topic, payload);
      }

      // Test if Flow Temperature can be read from the boiler
      if(readSensor(thermostat, OpenTherm::READ_DATA_ID::BOILER_WATER_TEMP, value, previousOTCommunicationMs)) {
        Serial.printf("Flow water temperature from boiler is %.01f %\n", value);
        // Use a static variable to keep track of the entity already being created
        static bool flowTemperatureEntityAdded = false;
          // Create the entity
        if(!flowTemperatureEntityAdded) {
          addEntity(client, "sensor", "flow_temperature", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLOW_TEMPERATURE_SENSOR);
          flowTemperatureEntityAdded = true;
        }
        // Publish the Flow Temperature
        snprintf(payload, sizeof payload, "{\"flow_temperature\":%.01f}", value);
        topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_FLOW_TEMPERATURE_SENSOR);
        publish(client, topic, payload);
      }

      // Test if Return Temperature can be read from the boiler
      if(readSensor(thermostat, OpenTherm::READ_DATA_ID::RETURN_WATER_TEMPERATURE, value, previousOTCommunicationMs)) {
        Serial.printf("Return water temperature to boiler is %.01f %\n", value);
        // Use a static variable to keep track of the entity already being created
        static bool returnTemperatureEntityAdded = false;
          // Create the entity
        if(!returnTemperatureEntityAdded) {
          addEntity(client, "sensor", "return_temperature", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RETURN_TEMPERATURE_SENSOR);
          returnTemperatureEntityAdded = true;
        }
        // Publish the Return Temperature
        snprintf(payload, sizeof payload, "{\"return_temperature\":%.01f}", value);
        topic = topicByReference("state_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_RETURN_TEMPERATURE_SENSOR);
        publish(client, topic, payload);
      }

      // Any other OpenTherm sensor that returns a float (f8.8) can be added in the same way as above by using the correct OpenTherm::READ_DATA_ID::, adding a dicovery JSON in JSONs.h, calling
      // addEntity with the according parameters and publishing the value to the right topic in the right format
    }
  }
}


// updateRoomTemperatureStale()
// If the room temperature becomes stale, after it has not been updated within the ROOM_TEMPERATURE_STALE_INTERVAL_S that defaults to 15 minutes,
// signal this to Home Assistant by setting the room temperature to None/
void updateRoomTemperatureStale(bool                    stale) {
  static bool previousStale = false;

  if(stale && !previousStale) {
    const char * topic = topicByReference("current_temperature_topic", EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE);
    publish(*mqtt, topic, "{\"temperature\":\"None\"}");
  }

  previousStale = stale;
}


// subscribeAll()
// Subsbribe to all needed topics: one for the room temperature setpoint, one for the mode (OFF / HEAT / COOL / AUTO) and one for 
// the actual room temperature
bool subscribeAll(PubSubClient &                        client) {
  if(client.connected()) {
    subscribe(client, EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE, "temperature_command_topic");
    subscribe(client, EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE, "mode_command_topic");
    subscribe(client, EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE, "current_temperature_topic");
//    subscribe(client, processClimateMessage, EASYOPENTHERM_MQTT_DISCOVERY_MSG_CLIMATE, "preset_mode_command_topic");  // Not implemented yet
  }

  return client.connected();
}


// The main loop, repeat over and over again:
// - Try to connect to the boiler if not connected yet
// - If connected, every second:
//    - Inform the boiler of room temperature setpoint and actual room tenperature
//    - Update the state (from OFF to IDLE to HEATING or COOLING to ANTI_HUNTING
//    - Update the primary flags according to the state. The primary flags control if the boiler will statrt heating (or cooling) or not
//    - Compute the new Central Heating Setpoint using the PID controller, if enough time (PID_INTERVAL_S) has lapsed 
//    - Inform the boiler of the Central Heating water temperature setpoint
//    - read the boiler status (this also updates the primary falgs) and update all sensors
void loop() {
  static ThermoStateMachine thermoStateMachine;

  // Static variable to (re-)subscribe to topics
  static bool subscribed = false;
  // static variables used by the PID controller
  static uint32_t previousPIDTimestampS;                                                      // Save timestamp that the PID was previously run
  static float previousPIDRoomTemperature;                                                    // Save previous room temperature
  static float ierr;                                                                          // Save PID integral error

  // static variable to store the CH setpoint
  static float CHSetpoint = CH_MIN_SETPOINT;
  // static variable used to comply to the OpenTherm specification to have a primary to secondary communication at least once every second
  static uint32_t previousOTCommunicationMs = millis() - 1000;      // Initialise to force the first communication
  // static variables used to decide if the thermostat state should be published
  static uint32_t publishedThermostatStateTimestamp = time(nullptr);                        // Initialise previous thermostat state publishing timestamp


  // Check if we are still connected to the MQTT broker. If not, reconnect and resubscribe to the topics we are interested in
  if(!mqtt->connected()) {
    Serial.println("MQTT disconnected");
    // handle the TCP/IP socket connection outside of PubSubClient because of connection issues
    if(!wiFiClient.connected()) {
      Serial.printf("WiFi client disconnected, WiFi status = %d\n", WiFi.status());
//      wiFiClient.stop();
      wiFiClient.connect(mqtt_server, 1883);
      if(wiFiClient.connected()) {
        Serial.println("WiFi client reconnected");
      }
    }
    if(wiFiClient.connected()) {
      Serial.printf("WiFi client is connected, WiFi status = %d\n", WiFi.status());
      bool MQTTConnected = connectMQTT(*mqtt, MQTT_ID, mqtt_user, mqtt_password);
      Serial.printf("MQTT reconnected is %s\n", MQTTConnected ? "true" : "false");
      subscribed = false;
    } else {
        Serial.println("WiFi client did not reconnected");
    }
  }

// Subscribe to all relevant topics after a new connection
  if(!subscribed) {
    Serial.println("Subscribe to all relevant MQTT topics...");
    if(subscribeAll(*mqtt)) {
      subscribed = true;
    }
  }

  uint32_t thermostatStateTimestampAligned = (time(nullptr) / PUBLISH_STATE_UPDATE_INTERVAL) * PUBLISH_STATE_UPDATE_INTERVAL;    // Align to exact intervals
  uint32_t thermostatStateTimestampMs = millis();
  if(millis() - previousOTCommunicationMs >= 1000) {      // OpenTherm specifies that primary to secondary communication should take place at least every second
    // connected() becomes 'true' after communication has taken place between thermostat and boiler and the boiler's configuration flags are read

    if(!thermoStateMachine.connected()) {
      // Try to contact the boiler and construct the thermostat's primary flags from the boiler's capabilities
      OpenTherm::CONFIGURATION_FLAGS configurationFlags;
      if(readSecondaryConfiguration(thermostat, configurationFlags, previousOTCommunicationMs)) {
        Serial.println("OpenTherm secondary connected");
        thermoStateMachine.initPrimaryFlags(configurationFlags);

        updateClimateEntity(((uint8_t) configurationFlags & (uint8_t) OpenTherm::CONFIGURATION_FLAGS::SECONDARY_COOLING) != 0); 
        updateDHWEntity(((uint8_t) configurationFlags & (uint8_t) OpenTherm::CONFIGURATION_FLAGS::SECONDARY_DHW_PRESENT) != 0); 
      }
    }

    if(thermoStateMachine.connected()) {
      // Inform the boiler of the room temperature setpoint; is automatically ignored if setpoint did not change or if not supported by the boiler
      roomTemperatureSetpointToBoiler(thermostat, roomTemperatureSetpoint, previousOTCommunicationMs);
      // Check if roomTemperatureTimestampS is zero (No room temperature received yet)
      if(roomTemperatureTimestampS != 0) {
        // Inform the boiler of the room temperature; is automatically ignored if room temperature did not change or if not supported by the boiler
        roomTemperatureToBoiler(thermostat, roomTemperature, previousOTCommunicationMs);

        uint32_t stateTimestampS = time(nullptr);
        // State changes from IDLE -> HEATING or COOLING -> ANTI_HUNTING > IDLE, depending on the current state and changes in temperature setpoint and / or room temperature
        // updateState returns true if the state has changed
        if(thermoStateMachine.update(roomTemperature, roomTemperatureTimestampS, roomTemperatureSetpoint, thermostatRequest)) {
          // state has changed, update the primary flags to the new state
          thermoStateMachine.updatePrimaryFlags();
          Serial.printf("State changed to '%s'\n", thermoStateMachine.c_str());
          // Initialise the PID variables
          ierr = 0;
          previousPIDTimestampS = stateTimestampS;
          previousPIDRoomTemperature = roomTemperature;            
        } else {
          Serial.printf("State still is '%s'\n", thermoStateMachine.c_str());
          // state did not change, update the CH setpoint using the PID if state is HEATING or COOLING
          switch(thermoStateMachine.getState()) {
            case ThermostatState::HEATING:
            case ThermostatState::COOLING:
              // If at least PID_INTERVAL_S seconds have elapsed, compute the new CH temperature setpoint using the PID
              if(stateTimestampS - previousPIDTimestampS >= PID_INTERVAL_S) {
                // Time between measurements in seconds
                float dt = stateTimestampS - previousPIDTimestampS;
                CHSetpoint = pid(roomTemperatureSetpoint, roomTemperature, previousPIDRoomTemperature, ierr, dt);
                previousPIDTimestampS = stateTimestampS;
                previousPIDRoomTemperature = roomTemperature;
                Serial.printf("Computed CH setpoint using PID is %.01f\n", CHSetpoint);
              }

            break;
            default:
              CHSetpoint = CH_MIN_SETPOINT; // Just to be sure, the boiler should alreay been disabled by the primary flags
            break;
          }
        }
      }

      // If room temperature gone stale, signal this to Home Assistant by setting the room temperature to None
      updateRoomTemperatureStale(thermoStateMachine.getRoomTemperatureStale());

      // Inform the boiler of the boiler water setpoint; is automatically ignored if CH setpoint temperature did not change
      CHSetpointToBoiler(thermostat, CHSetpoint, previousOTCommunicationMs);

      uint8_t primaryFlags = uint8_t(thermoStateMachine.getPrimaryFlags());
      uint8_t statusFlags;
      // Read status in every loop, to meet the 'communication each second' requirement
      if(readStatus(thermostat, primaryFlags, statusFlags, previousOTCommunicationMs)) {
        // Inform Home Assitant directly about the status; is automatically ignored if the flame status or CH / DHW status did not change
        updateFlameSensor(statusFlags); 
        updateDHWSensor(statusFlags);
      }
    }
  }

  // Publish the 'interval' sensors' at exact 'PUBLISH_STATE_UPDATE_INTERVAL' intervals
  if(thermostatStateTimestampAligned - publishedThermostatStateTimestamp >= PUBLISH_STATE_UPDATE_INTERVAL) {
    Serial.println("Update sensors by publishing sensor values to MQTT broker...");
    updateSensors(*mqtt, thermoStateMachine.connected(), CHSetpoint, previousOTCommunicationMs);
    publishedThermostatStateTimestamp = thermostatStateTimestampAligned;
  }

  mqtt->loop();
}