Peter M. Groen / EasyOpenTherm

Commit 3b4bc58db3d1c4c44b8166bdf8589a82a7ec9a8a

Authored by Jeroen88
1 parent 0e34c6ab

Updated comments in the examples

Inline Side-by-side
Showing 3 changed files with 48 additions and 16 deletions
examples/Advanced_Thermostat/Advanced_Thermostat.ino
  View file @3b4bc58
... ... @@ -5,7 +5,7 @@
5 5 * This software needs an OpenTherm controller like
6 6 * https://www.tindie.com/products/Metriot/OpenTherm-adapter/ or
7 7 * https://www.tindie.com/products/Metriot/OpenTherm-adapter/ connected to a BOILER SUPPORTING
8   - * THE OPENTHERM PROTOCOL, an ESP32-S2 mini, ESP32-C3 mini or ESP-D1 mini flashed with this
  8 + * THE OPENTHERM PROTOCOL, an ESP32-S2 mini, ESP32-C3 mini or ESP8266 flashed with this
9 9 * software and Home Assistant or any other MQTT enabled home automation environment.
10 10 *
11 11 * MQTT_Advanced_Thermostat is a real working thermostat over MQTT. It offers a HIGH LEVEL API
... ... @@ -24,9 +24,10 @@
24 24 * - Change the WiFi credentials and MQTT credentials in this software
25 25 * - Flash this software to a ESP32-S2 mini, connect the ESP to the OpenTherm Adapter and connect the
26 26 * OpenTherm Adapter to the boiler with the two wires of your present thermostat (replace it)
  27 + * - See also both README.md's in the main and Examples directory
27 28 * THAT'ALL, all integrations should automatically appear in Home Assistant and be active!
28   -
29   - * Although it is designed to work with Home Assistant and it's MQTT integration, it can fucntion
  29 + *
  30 + * Although it is designed to work with Home Assistant and it's MQTT integration, it can function
30 31 * in any home automation system as long as it has an MQTT integration.
31 32 * This program is developed and tested for a boiler, but could be easily adapted to work with HVAC
32 33 * systems too.
... ... @@ -49,15 +50,15 @@
49 50 * any leading or trailing spaces, in capitals, e.g. HEAT.
50 51 *
51 52 * This thermostat publishes to a MQTT topic, Metriot/EasyOpenTherm/112233445566/climate/state
52   - * the local temperature measures by an onboard sensor. The value message is a JSON, e.g.:
53   - * {"local_temperature": 20.1}. The software already has support for a Dallas Sensor that can be
  53 + * the local temperature measures by an onboard sensor (if enabled). The value message is a JSON,
  54 + * e.g.: {"local_temperature": 20.1}. The software already has support for a Dallas Sensor that can be
54 55 * enabled by defining the one wire pin the sensor is connected to (const int oneWireBus). If you want
55   - * to use this temerature as room temperature, you have to write an automationm that subscribes to the
  56 + * to use this temperature as room temperature, you have to write an automation that subscribes to the
56 57 * above topic, extracts the temperature and publishes it in the right format to the room temperature
57   - * update topic.
  58 + * update topic (see above).
58 59 *
59 60 * Unlike other examples on the internet, MQTT_Advanced_Thermostat already is a fully functional
60   - * thermostat: just configure it once change, regularly publish teh room temperature and update the the
  61 + * thermostat: just configure it once change, regularly publish the room temperature and update the the
61 62 * room temperature setpoint any time your boiler to heat up the room to that setpoint.
62 63 *
63 64 * Use your home automation system, like Home Assistant or Domoticz, to create e.g. schedules
... ... @@ -90,12 +91,12 @@
90 91 * Connect the OpenTherm RXD pin to the microcontroller's pin defined by #define OT_TX_PIN.
91 92 *
92 93 * You can also use this shield <https://www.tindie.com/products/jeroen88/opentherm-controller/> and an
93   - * ESP32-S2 mini, an ESP32-C3 mini or an ESP D1 mini. With this shield all pins are already connected. The only thing you
94   - * have to connect are the two OpenTherm thermostat wires.
  94 + * ESP32-S2 mini, an ESP32-C3 mini or an ESP D1 mini (the latter not tested yet). With this shield all pins are already
  95 + * connected. The only thing you have to connect are the two OpenTherm thermostat wires.
95 96 *
96 97 * If needed, connect a Dallas Temperature Sensor to the right pin or, if you use the above shield, use the onboard sensor.
97 98 * Make sure though that the mesured temperature is not influenced too much by the heat produced by the processor. An
98   - * ESP32-S2 e.g. becomes too hot.
  99 + * ESP32-S2 e.g. becomes too hot and is too close to the sensor to produce valid readings.
99 100 * Any other temperature sensor may be used, like a BME280, BME380, BMP380, BME680 if you adapt the program accordingly.
100 101 *
101 102 * I hope you enjoy working with this library, please share ideas in the Github Discussions sessions of this library.
... ...
examples/MQTT_Advanced_Thermostat/MQTT_Advanced_Thermostat.ino
  View file @3b4bc58
... ... @@ -41,6 +41,7 @@
41 41 */
42 42  
43 43 /* IMPORTANT NOTICES
  44 + * 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.
44 45 * You have to do a lot of configuration to get this running! It is not difficult, but you have to be diligent.
45 46 * This example uses a certificate to autenticate the MQTT server and to ecnrypt the connection using TLS (Transport Layer Security) with a WiFiClientSecure.
46 47 * 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 @@
55 56 *
56 57 * 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,
57 58 * #define I2C_SDA_PIN and I2C_SCL_PIN)
58   - * 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
  59 + * 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
  60 + * then you MUST adapt the program accordingly
59 61 *
60 62 * You MUST provide your WiFi credentials (const char * ssid and const char * password)
61 63 *
62   - * You MUST provide your MQTT server, MQTT user name and MQTT password (const char * mqtt_server, const char * mqtt_user and
63   - * const char * mqtt_password)
  64 + * 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)
64 65 * This thermostat publishes the corrected measured room temperature to the MQTT broker in topic 'temperature'
65 66 * It subscribes to topic 'room_temperature_setpoint' to receive the room temperature setpoint. This temperature is not persistant. If you restart the
66 67 * program, you have to resend it.
67 68 *
68   - * You MUST provide the CA certificate of your MQTT server (unless you use an insecure connection, see above, const char CACertificate[])
  69 + * You MUST provide the CA certificate of your MQTT server (unless you use an insecure connection, see above), const char CACertificate[]
69 70 *
70 71 * 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)
71 72 * with both the temperature sensor and a calibrated thermomter. Store the results into #define LOWER_MEASURED_TEMPERATURE, LOWER_CALIBRATED_TEMPERATURE,
... ... @@ -80,7 +81,8 @@
80 81 * 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
81 82 * in a badly insulated house. Check your boiler manual for the right maximum temperature.
82 83 *
83   - * I hope you enjoy working with this library, pPlease share ideas in the Github Discussions sessions of this library.
  84 + * I hope you enjoy working with this library, pPlease share ideas in the Github Discussions sessions of this library
  85 + * (https://github.com/Jeroen88/EasyOpenTherm/discussions)
84 86 */
85 87  
86 88 #include <Arduino.h>
... ...
examples/OpenTherm_Show_DATA-IDs/OpenTherm_Show_DATA-IDs.ino
  View file @3b4bc58
  1 +/*
  2 + * https://github.com/Jeroen88/EasyOpenTherm
  3 + * https://www.tindie.com/products/Metriot/OpenTherm-adapter/
  4 + *
  5 + * Test_Boiler_Communication is a program to test if your MCU can communicate with your OpenTherm compatible HVAC
  6 + * Copyright (C) 2022 Jeroen Döll <info@metriot.nl>
  7 + *
  8 + * This program is free software: you can redistribute it and/or modify
  9 + * it under the terms of the GNU General Public License as published by
  10 + * the Free Software Foundation, either version 3 of the License, or
  11 + * (at your option) any later version.
  12 + *
  13 + * This program is distributed in the hope that it will be useful,
  14 + * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16 + * GNU General Public License for more details.
  17 + *
  18 + * You should have received a copy of the GNU General Public License
  19 + * along with this program. If not, see <https://www.gnu.org/licenses/>.
  20 + *
  21 + * You need an OpenTherm controller that you can buy at my Tindie store, see <https://www.tindie.com/products/jeroen88/opentherm-controller/>
  22 + * Connect the two HVAC wires to the OpenTherm controller pins marked OT. The order is not important.
  23 + * Connect the OpenTherm controller to your microcontroller's power (3v3) and ground (GND) pins.
  24 + * Connect the OpenTherm TXD pin to the microcontroller's pin defined by #define OT_RX_PIN.
  25 + * Connect the OpenTherm RXD pin to the microcontroller's pin defined by #define OT_TX_PIN.
  26 +*/
  27 +
  28 +
  29 +
1 30 #include <EasyOpenTherm.h>
2 31  
3 32 #if defined(ARDUINO_LOLIN_S2_MINI)
... ...