Updated comments in the examples

Jeroen88
1 parent 0e34c6ab
Showing 3 changed files with 48 additions and 16 deletions
examples/Advanced_Thermostat/Advanced_Thermostat.ino
examples/MQTT_Advanced_Thermostat/MQTT_Advanced_Thermostat.ino
examples/OpenTherm_Show_DATA-IDs/OpenTherm_Show_DATA-IDs.ino
@@ -5,7 +5,7 @@
  *    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 ESP-D1 mini flashed with this 
+ *    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
@@ -24,9 +24,10 @@
  *    - 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 fucntion
+ *     
+ *    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.
@@ -49,15 +50,15 @@
  *    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. The value message is a JSON, e.g.:
- *    {"local_temperature": 20.1}. The software already has support for a Dallas Sensor that can be
+ *    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 temerature as room temperature, you have to write an automationm that subscribes to the
+ *    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.
+ *    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 teh room temperature and update the the 
+ *    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
@@ -90,12 +91,12 @@
  *    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. With this shield all pins are already connected. The only thing you 
- *    have to connect are the two OpenTherm thermostat wires.
+ *    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.
+ *    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.
@@ -41,6 +41,7 @@
  */
 /* IMPORTANT NOTICES
+ * The other example, 'Advanced_Thermostat.ino' is more recent, and more up-to-date. You should better take that example, even if you do not use Home Assistant. 
  * You have to do a lot of configuration to get this running! It is not difficult, but you have to be diligent.
  * This example uses a certificate to autenticate the MQTT server and to ecnrypt the connection using TLS (Transport Layer Security) with a WiFiClientSecure.
  * If you do not want to use this feature, because e.g. your MQTT broker does not support it, you have to adapt this program:
@@ -55,17 +56,17 @@
  *
  * You MUST use a BME280 temperature sensor board and provide the I2C address of your sensor and the GPIO pins it is connected to (#define BME_ADDRESS,
  * #define I2C_SDA_PIN and I2C_SCL_PIN)
- * You MAY use a completely different sensor, e.g a BME680 or even a Dallas temperature sensor) but then you MUST  adapt the program accordingly
+ * You MAY use a completely different sensor, e.g a BME680 or even a Dallas temperature sensor (or even use a temperature received from 'somewhere else') but 
+ * then you MUST adapt the program accordingly
  * 
  * You MUST provide your WiFi credentials (const char * ssid and const char * password)
  *
- * You MUST provide your MQTT server, MQTT user name and MQTT password (const char * mqtt_server, const char * mqtt_user and 
- * const char * mqtt_password)
+ * You MUST provide your MQTT server, MQTT user name and MQTT password (const char * mqtt_server, const char * mqtt_user and const char * mqtt_password)
  *    This thermostat publishes the corrected measured room temperature to the MQTT broker in topic 'temperature'
  *    It subscribes to topic 'room_temperature_setpoint' to receive the room temperature setpoint. This temperature is not persistant. If you restart the
  *    program, you have to resend it.
  *
- * You MUST provide the CA certificate of your MQTT server (unless you use an insecure connection, see above, const char CACertificate[]) 
+ * You MUST provide the CA certificate of your MQTT server (unless you use an insecure connection, see above), const char CACertificate[]
  *
  * You SHOULD calibrate your sensor by measuring a low temperature (e.g. 15 *C, not very critical) and a high temperature (e.g. 20 *C, again not critical) 
  * with both the temperature sensor and a calibrated thermomter. Store the results into #define LOWER_MEASURED_TEMPERATURE, LOWER_CALIBRATED_TEMPERATURE, 
@@ -80,7 +81,8 @@
  *    using low temperature radiators e.g to 40.0 *C. If it takes too long to warm your house on a very cold winter day, increase to 60.0 *C or even higher
  *    in a badly insulated house. Check your boiler manual for the right maximum temperature.
  *
- * I hope you enjoy working with this library, pPlease share ideas in the Github Discussions sessions of this library.
+ * I hope you enjoy working with this library, pPlease share ideas in the Github Discussions sessions of this library 
+ * (https://github.com/Jeroen88/EasyOpenTherm/discussions)
  */ 
 #include <Arduino.h>
+/*
+ *    https://github.com/Jeroen88/EasyOpenTherm
+ *    https://www.tindie.com/products/Metriot/OpenTherm-adapter/
+ *
+ *    Test_Boiler_Communication is a program to test if your MCU can communicate with your OpenTherm compatible HVAC
+ *    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 HVAC wires to the OpenTherm controller pins marked OT. The order 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.
+*/
+
+
+
 #include <EasyOpenTherm.h>
 #if defined(ARDUINO_LOLIN_S2_MINI)