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.

esp8266-hardware-watchdog-reset

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.

esp8266-software-watchdog-reset

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
Advertisements
This entry was posted in ESP8266 and tagged , , , . Bookmark the permalink.

15 Responses to ESP8266: Watchdog functions

  1. mamacker says:

    Awesome. Thank you for the write up!

    Liked by 2 people

  2. Tiep says:

    See how CPU speed works, RAM and power consumption

    Liked by 1 person

  3. occar says:

    Thank you!
    It is exactly what i needed to restart my project, on commands.

    Liked by 1 person

  4. ctreber says:

    Thanks!

    Liked by 1 person

  5. Pingback: Elster A1100 Meter Remote Reader – Elster A1100

  6. lopezjm2001 says:

    Nice work. Should the software watchdog timer time out, is it possible to automatically restart the main void through programming?

    Liked by 1 person

    • antepher says:

      Hi! Thank you very much 🙂 At the time I’ve investigated the watchdog, the documentation was very scarce, but if I’m not mistaken the ESP8266 is automatically reset and runs from the beginning of the program again.

      But the easiest way to confirm is by putting a serial.println at the beginning of the setup function and check if it prints the message again upon resetting.

      That should be the behavior of a watchdog, although at that time the ESP8266 watchog was kind of a mess 🙂

      Let us know if you have the chance to test.

      Best regards,
      Nuno Santos

      Like

  7. lopezjm2001 says:

    Thanks.
    I found that the default time out was about 8 seconds. I changed it to 20 seconds i.e. ESP.wdtEnable(20000);. So far so good. My ESP8266 is inside my electrical switchboard so I cannot verify the serial print if restarted.

    Like

  8. This was really helpful. The ESP8622 (NodeMCU) WDT was hindering with a certain part of my code and baffled me for an hour. Disabling the SW WDT solved my problem. It’s sad that documentation on such low level hardware features is scarce and hard to find 😦 Thanks 🙂

    Liked by 1 person

    • antepher says:

      Hi! thank you very much for the feedback, I’m glad it helped solving your problem 🙂

      That’s true, I would also like to have more documentation on the WTD. Hopefully some more is released in the future.

      Best regards,
      Nuno Santos

      Like

  9. dalee says:

    I don’t understand clearly, that the ESP8266 starts Its operation (e.g. after reset) what the whachdog state is. Is it operate or it is disabled. Can I disable the WDT? If I disable the sw WDT the hw WDT will start. If I enable sw WDT the sw WDT will start. How can I disable the operation of it?

    Liked by 1 person

    • antepher says:

      Hi!

      When I investigated the watchdogs of the ESP8266, the information was very scarce.

      I don’t know if the situation has changed yet since I’ve not been working with the ESP8266 for a while, but you can ask at the ESP8266 forum.

      If I’m not mistaken, both watchdogs (the software and the hardware) start enabled on the ESP8266.

      So, what happens is that if you don’t feed the watchdog for more than a certain period of time, then it will trigger and reset your program.

      In most of the programs we develop, we don’t need to worry about calling the watchdog feed function since it is called under the hood for us in many of the ESP functions we use.

      Nonetheless it may be a source of “unexpected” resets in some situations where we lock the execution and don’t feed the watchdog.

      At the time of writing, it was possible to disable the software watchdog (as explained on the post) but not the hardware watchdog.

      Hope this helps.

      Best regards,
      Nuno Santos

      Like

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s