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.

27 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

  10. Ricky says:

    Hello, what is the purpose of wdtFeed function? Thanks.

    Liked by 1 person

    • antepher says:

      Hi!

      The wtdFeed function allows to explicitly restart the watchdog, to avoid it resetting the ESP.

      But in a regular program you should not need to explicitly call it since many functions implicitly feed the watchdog.

      Hope this clarifies.

      Best regards,
      Nuno Santos

      Like

  11. LAMGHARI says:

    many thanks. this was very helpful

    Liked by 1 person

  12. Rita says:

    sorry,I really don‘t know the difference between Hardware watchDog and Software watchDog

    Liked by 1 person

  13. Rita says:

    Hi,I wonder if the program would restart when it timeout

    Like

    • antepher says:

      Hi,

      The function of the watchdog is precisely restarting your program without the need for human intervention, in case it is unable to feed the watchdog with the periodicity it needs.

      Note that the code shown here is designed to trigger the watchdogs, so it is not very useful.

      Nonetheless, a watchdog is of extreme importance for applications where it is impractical to have human intervention in case the program crashes (ex: space ships or satellites). So, if the program crashes and it is no longer able to feed the watchdog, then it is automatically restarted.

      Hope this clarifies. 🙂

      Best regards,
      Nuno Santos

      Like

  14. John Kneen says:

    Excellent article. I too have found documentation fairly light.

    I was having trouble with an ESP8266 set up program so to single step added code to flash an LED and then continuously loop using a while(1); statement – works with Arduino but in this case the LED continuously flashed indicating that the ESP8266 was continuously resetting.

    My internet readings then indicated that the watch dog timer would reset if ever the setup code or the loop code took greater than one second. (The one second may be too short but it indicates the idea.)

    Further reading indicated the function yield( ). This function allows ESP8266 background routines to perform actions – I suspect this would include resetting any watch dog timers.

    To flash the LED my code used the library function delay(mS); – normally delay( ) would block any user code (except for interrupts). Further investigation revealed delay() contained the function yield() – hence in my case using delay( ) as part of my routine to flash the LED would not cause the watch dog to time out.

    However while(1); did cause a problem. By including a yield( ) the issue was solved. That is while(1) { yield( ); } causes the program to loop as desired but still allows the watch dog to be reset in the background. In this case the yield( ) is equivalent to the library method ESP.wdtFeed(); used in your example.

    I hope this information is useful and not just added to the internet chatter.

    JK

    Liked by 1 person

    • antepher says:

      Hi!

      Thank you very much for your feedback, I’m very happy to know you found this article useful 🙂

      That was indeed one of the biggest gaps of the ESP8266 which is being worked on in the ESP32, since now there is much more documentation available. Still, I would really like to see much more documentation and examples available since some features are really hard to discover 🙂

      Thank you very much for sharing that information, it will definitely be very useful for others.

      What you mention makes perfect sense since there is plenty of stuff running under the hood and at some points the main code that is executing needs to give CPU time to those routines.

      I would really like to know more about what is done by all those routines, but unfortunately, at least at the time I was more actively working with the ESP8266, what happened under the hood was basically a black box and very few information was known.

      Again, thank you very much for the information and always feel free to share here new findings 🙂

      Best regards,
      Nuno Santos

      Like

      • John Kneen says:

        Following your reply I decided to do some more investigation. I am using a Mini ESP8266 Board from Duinotech – I suspect its the same as a WeMos D1 Mini Lite.

        The board contains a LED on pin D4 (GPIO2). I flash the LED once and once only at the beginning of the setup( ) routine:

        void setup() {
        pinMode(D4, OUTPUT);
        digitalWrite(D4,LOW); //LED active low
        digitalWrite(D4,HIGH);
        //delay(10000); //no problem
        // delayJK(10000); //a problem
        while(1) yield( );
        }
        Without the yield( ) the program continually exits the while(1) loop, resets itself and the flashes the LED. – While the flash is visible I used a logic analyser to measure the time between flashes as 3.2 seconds.

        Adding the yield( ) statement eliminates the flashing – ie the ESP8266 does not reset so I conclude the wdt does not time out.

        I added a 10 second delay which I have called delayJK( ).
        void delayJK(long wait){
        long start = millis();
        while (wait > (millis( ) – start))
        yield( ); //eliminates problem
        }

        Without the yield the LED flashes every 3 seconds as before. Adding a yield( ) and the processor does not reset. (LED does not flash – wdt does not time out)

        Testing with the library delay( ) routine did not cause the processor to reset. The library routine contains a yield( );

        These comments are just a little more detail on my previous but I have added the measurement of 3.2 seconds. I guess the conclusion is if your setup( ) or loop( ) routines are longer than 3 seconds be alert for unexpected resets due to the wdt timing out!

        JK

        Liked by 1 person

        • antepher says:

          Thank you very much for the additional information 🙂

          It’s very useful to know how much time to expect before the watchdog fires.

          Did you test it with both the Hardware and Software watchdogs enabled?

          Supposedly from the arduino core code comments, the hardware watchdog should trigger after around 6 seconds in case the software one is disabled:
          https://github.com/esp8266/Arduino/blob/4897e0006b5b0123a2fa31f67b14a3fff65ce561/cores/esp8266/Esp.cpp#L97

          At the time I’ve been testing this, I found that it was possible to disable the software watchdog, but did not find any way of disabling the hardware watchdog.

          It would also be nice if we could configure these timings for the hardware one. It is possible to configure it for the software watchdog, but I did not find any function for the hardware.

          I’ve been doing a lot of testing on the ESP32 but I haven’t yet dedicated any time to check how the watchdogs are working there.

          Hopefully they have improved and clarified how things operate, although I’ml curious how it works with the two cores of the ESP32.

          Need to find some time to look into it 🙂

          Thanks again for the info!

          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 )

Google+ photo

You are commenting using your Google+ 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 )

Connecting to %s