How to make a thermostat controlled via a local WiFi web browser

This project will walk you through making a thermostat that can be controlled from a web browser over local WiFi.

Initially, I built this project because I needed such a device and I also wanted to learn about web technologies. I wanted to turn on the garage heater from home using my smartphone so I could warm it up before going in. I also wanted to see if I could build a nice looking mobile web app for the ESP32 web server that was simple enough and lightweight. This is my learning process using HTML5, Javascript, JSON, Bootstrap, Knockout, and other web technologies. I spent most of my time here, doing web research and trial and error. I will share my debugging setup.

The ESP32 Arduino code uses the ESP32 library, is not complex, and allows you to understand the specifics of the HTML protocol. While this is a complete working system (except for the shell) and a fully functional web application, it is also a good starting point for hacking other applications.

A few warnings about this project:

This project should only be used in low voltage (24v or less) low current (2A or less) two wire thermostat applications where a separate relay in the heating unit controls the supply current and the heating unit itself has its own safety system. It should not be used to directly control any heating element.

Since it is not designed to any safety standards, the builder can safely use it as a thermostat and monitor its operation. If it fails for some reason and remains on, and it freezes below freezing outside your room. If it fails and remains off, the heater may continue to run and produce high temperatures. One option is to connect it in series (or parallel) with the existing thermostat so that there is a backup in case the project is stuck in the off (or on) position. This helps avoid one failure mode, but not the other, so monitoring is required.

Prerequisites

Familiar with Arduino environment and board management

Prototyping Practice Using Jumper Wires and a Solderless Breadboard

Basic understanding of web technology concepts

step

1. Load the board definition of ESP32 into ArduinoIDE.

2. Edit the Arduino code to configure the WiFi access name, security code, and thermostat name.

3. Compile the code and load it into the ESP32 development board. (WiFi remote programming is available)

4. Connect the circuit according to the schematic diagram.

5. Find the IP address and open it in a web browser

6. Open the thermostat and change the set point.

How it works – Hardware

The ESP32 board supports WiFi connectivity and has IO capabilities that can be connected to the relay board, turn the relay on and off, and connect with the DHT22 temperature and humidity sensor. The relay contacts are connected to the 2-wire thermostat terminals of the heating system. When the relay is closed, it completes the 2-wire thermostat circuit and causes the heating system to heat up.

The relay board accepts two active low inputs to control each individual relay. Only one relay is used for this project. The other can be used for other purposes. The relay board uses a two-stage optoisolator and the relay itself to electrically isolate the sensitive MCU digital I/O pins from the heating system. For real-world MCU projects, ensuring isolation is very important for reliable and robust operation. Static electricity, AC noise, power supply noise/variability can cause the MCU to get false input signals, lock up, or worst of all, be permanently damaged. Debugging these types of problems is a headache, so isolation is important. The optoisolator converts the digital output from the MCU into light (via an LED), and then the photodetector picks up the light and converts it into a voltage on the isolated circuit.

This way, the MCU pin is electrically isolated from the potential of the driving relay. In this circuit, the power to drive the relay is still provided by the same power source as the ESP32 board power supply (USB power). It is also possible to use a separate power supply, which is why there is a jumper on the board. The relay itself acts as a mechanical switch and also provides a second stage of electrical isolation between the two-wire heating system thermostat terminals and the power supply for this project. In this circuit, the power to drive the relay is still provided by the same power source as the ESP32 board power supply (USB power). It is also possible to use a separate power supply, which is why there is a jumper on the board. The relay itself acts as a mechanical switch and also provides a second stage of electrical isolation between the two-wire heating system thermostat terminals and the power supply for this project. In this circuit, the power to drive the relay is still provided by the same power source as the ESP32 board power supply (USB power). It is also possible to use a separate power supply, which is why there is a jumper on the board. The relay itself acts as a mechanical switch and also provides a second stage of electrical isolation between the two-wire heating system thermostat terminals and the power supply for this project.

The DHT22 temperature and humidity sensor has the measurement range and accuracy required for our application:

It uses a serial single-wire communication interface to send 5 bytes of data representing temperature and humidity.

During normal operation (after initial programming), the ESP32 board is powered via a 5v USB charger. This 5v power is also distributed to the other boards. In this project, jumper wires are used to connect the components, but after the prototyping stage, soldering the connections will improve long-term reliability.

How it works - Software
The ESP32 implements a simple temperature controller and a web server.

A simple temperature controller performs the following functions:

1. Collect temperature and humidity data serially from DHT22 sensor through single wire interface.

2. Open and close the relay depending on whether the temperature is below or above the set point. The controller has some hysteresis so that when the temperature approaches the set point, the controller will not switch on and off repeatedly due to measurement errors.

3. Get time data from a server on the Internet in order to synchronize the internal ESP32 clock with the Internet server to get the official time.

4. A watchdog timer is maintained to detect system lockup or failure and automatically restart. This timer is constantly reset as long as the main program loop is running properly. If the main loop does not repeat due to some error or failure, the timer counts down and resets the MCU.

There are four different types of requests that a web server can respond to from a client browser:

1. HTTP - When it receives this request, the ESP32 sends the HTML file as a long string to the browser. The HTML file contains javascript that runs on the browser client and makes other types of requests to the web server.

2. GET - When it receives this request, the ESP32 sends the temperature, humidity, relay status (on/off), setpoint, time, and other information in the form of a JSON message. Generally speaking, JSON is a text message with key-value pairs in a hierarchical structure. In this application, we keep it simple and do not use any hierarchy.

{ Type: "TH&Relay", Name: "Cave", Temp: "69.44", RelH: "34.60", Tset: "40", Heater: "0", Control: "0", StartTime: "1552185144", CurrentTime: "1552185151", Wifi_ssi: "-42" }
The javascript on the browser client receives this and parses it to update the data objects held in the browser. These can then be displayed and manipulated on the client.

3. OPTIONS - This is a required request that is done before a POST operation to do a security check to ensure that the client can post information to the server.

4. POST - When the web server receives this request, it receives a JSON message from the client containing the set point temperature and whether temperature control should be activated.

{Control: "1", Tset: "72"}

The web server parses this data and sets internal variables for further processing.

Web Design and Debugging
This project used a number of web technologies and standards that allowed me to keep the HTML file content static and small, while still providing dynamic and responsive web pages. This was the focus of my learning on this project, and where I spent the most time researching the web and learning through trial and error.

Debug Setup
I think the best way to learn the web interface is to use the developer debugging features in your browser. I use Firefox. In the menu there is an option called "Web Developer" and then "Web Console". This allows you to see messages passed to the server, error messages, javascript exceptions, etc. Since the web server on the ESP32 only handles the 4 different requests mentioned above, it doesn't really care which web page is making those requests. It could be the web page that was loaded with request 1. But it could also be another web page - such as the "index.html" file you have open on your local computer. So this allows you to make small changes to this file in a text editor (I use Notepad++ because it knows html formatting), then refresh the browser and see what happens to the rendered page:

Web Design

The HTML file contains embedded CSS, HTML and Javascript in one file. It uses Bootstrap for designing responsive websites, which is a collection of CSS (Cascading Style Sheets), HTML and Javascript. It uses the javascript library KnockoutJS to dynamically update the browser view when data changes occur. In order to keep the HTML file small, these libraries are not kept in the HTML file itself. They are linked using so-called CDN (Content Delivery Network) providers. In addition, javascript uses the new native fetch() function to implement server calls 2-4. Finally it uses some glyphicon fonts in fontawesome for the reload button (circular arrow) and the flame icon - indicating that it is asking to turn on the heater.

Bootstrap simplifies the layout of web pages, and the layout can be properly adapted to mobile screens or larger screens. It has a series of widgets and styles to help make a clean-looking website.

KnockoutJS is a lightweight framework in javascript that seems to have fallen out of favor somewhat, but seemed perfect for my requirements. What I learned in my research is that people now use Angular and react, which seem to require their own development tools and seem to require a lot of learning. The KnockoutJS framework automatically updates the UI when the data changes. It is designed to isolate the UI from the underlying data that is kept in the browser DOM (Data Object Model). For me, this was the most challenging part of web design because it relies on a lot of object-oriented concepts of Javascript. The knockout website provides some tutorials and examples to learn from. Luckily, once I got it working, I didn't have to do any further improvements because it had nothing to do with UI changes, and that's the point.

fetch() is a new function native to javascript that handles client-server communication for http protocols like GET, OPTIONS and POST. Another approach is to use additional jQuery AJAX calls or other javascript libraries. Here is more information. https://davidwalsh.name/fetch

CDNs are used to serve CSS and javascript libraries and code to the browser so that the ESP32 web server does not have to serve these. A content delivery network is a collection of geographically dispersed servers that serve this content, usually for a fee for high volume or fast responses. For this project we used free services that worked well for the volume and response times we needed. If you look in the "index.html" file you will see the url links to these servers, for example boostrap 4.3.1 is merged using the link below.

fontawsome is used to add some nice glyph icons to the UI to reflect the heater status and refresh button. In HTML, this is:

Serving a Web Page from Arduino Code - The HTML file stores a string constant so that it can be processed in the web server. But for debugging purposes, I saved the file on my PC's local drive as "index.html" and opened that file in a browser. The browser doesn't really care how it receives this file (locally or from the ESP32 web server), so I can quickly change the HTML in this file, refresh the browser, and see the results. Once I was done, I used an online tool to convert the index.html to a string. I then pasted this string into the Arduino code.

Final Result:

I designed a case that can be 3D printed and fixed to the wall with two screws and hot glue between the plates.