ESP8266: Watchdog functions

The objective of this post is to analyse some of the watchdog functions available on the Arduino IDE libraries for the ESP8266.

Introduction

The objective of this post is to analyse some of the watchdog functions available on the Arduino IDE libraries for the ESP8266.

A watchdog is a timer that, when not reset before expiring, triggers the reset of the system [1] that is monitoring. In our case, the system will be the ESP8266 microcontroller.

So, the main program needs to periodically reset the watchdog timer, to prevent the reset of the CPU and keep working normally.

The watchdog should be configured with a time greater that the worst case scenario delay in the program [1], so it only triggers in error / unpredicted problems that may make the main program to be locked and not recover on its own [2]. In those locking cases, the watchdog is not reset and, when it expires, resets the system.

This concept is of extreme importance, specially in microcontrollers, which may be affected by environmental conditions such as electrical noise, which can cause hardware malfunction that locks the execution. Additionally, it is  useful for problem in the code that may put the execution in an undesired infinite loop.

The ESP8266 has 2 watchdogs, one implemented in hardware and another in software [3].

The tests were performed using a NodeMCU board, a very cheap and easy to use ESP8266 board. The board can also be bought at eBay here.

The software watchdog functions

In order to access the watchdog functions on the ESP8266, we have the EspClass, which can be analysed in more detail here. We can access the functionality of this class by using an extern variable called ESP, which is declared here in the libraries.

In order to disable the software watchdog, we just need to call the wdtDisable method on the ESP object, as indicated bellow.

ESP.wdtDisable();

Although this disables the software watchdog, the hardware watchdog will still remain active, causing a reset after some time. As indicated in the comments of the wdtDisable method, if we stop the software watchdog by more that 6 seconds, the hardware watchdog will trigger. This is approximately what I got when testing it.

We can re-enable the software watchdog by calling the wdtEnable method, as indicated bellow.

ESP.wdtEnable(1000);

It’s important to note that an integer value needs to be passed as input argument of this method, which would correspond to the number of milliseconds for the watchdog to trigger. Nevertheless, this value makes no effect and it is not used in the internal call of the SDK ESP8266 functions, as can be seen by the source code here.

Additionally, in the header file, it’s clearly stated that, at the time, setting the timeout is not implemented. Unfortunately, it’s not clear what is the default value of the watchdog timer when we call this function, and neither it is documented in the SDK of the ESP8266.

In order to explicitly restart the watchdog, we can call the wdtFeed method, specified here. Fortunately, the ESP libraries implicitly reset the watchdog in many of the functions, so most of the time we don’t need to worry about feeding the watchdog. Nevertheless, it’s important to know that it exists, in order to troubleshoot spontaneous reboots of our programs.

ESP.wdtFeed();

Triggering the hardware watchdog

To trigger the hardware watchdog, we just need to disable the software watchdog timer and do an infinite loop. We can do all of these actions in the setup function, as indicated bellow. Note that we will do an infinite loop with a while loop.

void setup() {

 ESP.wdtDisable();
 while (1){};

}

void loop(){}

After uploading the code, open the serial port to check the output. When the watchdog fires, a crash log is printed to the serial port, as indicated in the figure 1.

Figure 1 – Crash log of the hardware watchdog reset.

As indicated in the figure, there is a mention to the cause (wdt reset) and the reset cause has the number 4, which corresponds to the hardware watchdog reset [4]. You can check other reset code here. This result is consistent with the indicated in this document.

Triggering the software watchdog

In order to trigger the software watchdog reset, we just use the same code as before and remove the disabling of the software watchdog (enabled by default).

void setup() {

 while (1){};

}

void loop(){}

In this case, after uploading the code and opening the serial port, we will just get the result illustrated in figure 2, when the software watchdog triggers.

Figure 2 – Crash log of the software watchdog reset.

The result is also coherent with the one shown here.

Feeding the watchdog

Finally, we will use the code indicated bellow to test the function of restarting the watchdog. So, we will call the wtdFeed method inside our infinite loop, which will ensure the reset of the watchdog.

It works both for the software and hardware watchdog, so if we uncomment the call to the wdtDisable method, the program will still keep running without being reset by the hardware watchdog.

void setup() {

 //ESP.wdtDisable();
 while (1){ESP.wdtFeed();};

}

void loop(){}

Final notes

As can be seen through this post, the documentation about the watchdogs of the ESP8266 is still scarce and the functionality to control them is still a work in progress.

Additionally, an easy way to control the hardware watchdog is still lacking, which is an important feature to give us more control over the device.

References

[1] https://developer.mbed.org/cookbook/WatchDog-Timer

[2] http://searchmobilecomputing.techtarget.com/definition/watchdog-timer

[3] https://github.com/esp8266/Arduino/blob/4897e0006b5b0123a2fa31f67b14a3fff65ce561/doc/faq/a02-my-esp-crashes.md

[4] http://www.esp8266.com/viewtopic.php?p=2096#p2112

Technical details

• ESP8266 libraries: v2.3.0