Tuesday, August 26, 2014

On 9:00 AM by Richard St-Pierre   8 comments

WatchDog Timer Overview

Computers running critical applications, often need a way to be reset if an unexpected event causes the system to become unresponsive. Getting a computer back up and running in a remote location can be costly and frustrating. The BeagleBone Black is being used in more applications, and (unattended) situations where an occasional reset may be required from time-to-time. Fortunately, there is an easy way to do this!

A watchdog timer is a circuit that requires a periodic 'wake up' signal or else it generates a reset pulse.
(Feed-me or I will bark!).

The BeagleBone Black has an embedded watchdog timer that can be very useful in providing a reset function.

A watchdog timer will:

  • Allow enough time for the system to boot before triggering a reset.  
  • Needs to receive periodic signals from the critical program (I'm alive and well).
  • Reset the system, if the program becomes unresponsive (fails to report on time). 

On the BeagleBone Black, the watchdog timer is activated by accessing the system device /dev/watchdog.

cat > /dev/watchdog

The watchdog function is initially activated by writing to /dev/watchdog.
This enables the watchdog, and it must now be periodically accessed. The initial period is about 60 seconds.

Your application program, should then access the watchdog timer to ensure that under normal operation the time interval is satisfied. Failing to write to the watchdog will cause a forced system reset. This is what we would like to happen if our program has become unresponsive.

Testing the Watchdog

To test the watchdog, simply write to the watchdog.

cat > /dev/watchdog

Wait about 60 seconds and your BeagleBone will reset and reboot.
On the other hand, if you issue the command again, before the timer has elapsed, the reset will be delayed further. These simple steps will help you test the watchdog timer.

NOTE: The watchdog is enabled once you FIRST write to /dev/watchdog, otherwise it is in-active.

Programming Hint

There are many approaches to implementing the watchdog 'keep alive' function. A simple method is to regularly issue a system command from the programming language chosen. Another method is to simply open the file '/dev/watchdog' for writing.

This tutorial shows an example of  issuing a system command using bonescript (exec child process).
BoneScript also has a simple method to automatically run a program. In Bonescript, simply drop the program into the AUTORUN folder.

Similar execution of system functions exist for Python and C/C++. The implementation will vary based on the application needs.

A simple python example:

#!/usr/bin/env python

import time
import os

time.sleep(60)                  # Wait before starting
wd = open("/dev/watchdog", "w+")
while 1:

Is it time for you to implement your own watchdog timer application?

Additional Information

Linux watchdog and
Wathcdog information


  1. Congratualtions! Very useful tutorial!
    In accord of my app i'd like to know:
    1- how to deactivate the WDT? (necessary on maintenances);
    2- how to implement in C language a timer to reset the WDT?
    Thanks a lot.
    Best regards,
    Jose Henrique

  2. Jose:

    You do not want to deactivate the WDT (because 'bad' code execution could deactivate).
    (simply don't activate it at the next reboot)
    For -C- language implementation . You can open the file '/dev/watchdog' for 'wb' and write to it at regular interval or issue a system command (system("cat > /dev/watchdog").

  3. Jose:

    Watchdog can be stopped without causing a reboot if the device
    /dev/watchdog is closed correctly, unless of course your kernel is com-
    piled with the CONFIG_WATCHDOG_NOWAYOUT option enabled.

    ref: http://swoolley.org/man.cgi/watchdog

    1. This is precisely what I'd like to avoid. Is there a way to keep the watchdog file open if, say the python program exits (sys.exit() or Ctrl+C or error)? Right now if it exits, the watchdog is disabled again. I'd like to keep with the standard Debian image that it ships with...

      Thanks for any solutions!

    2. I don't know your application...Why does the python code 'exit'? (better error-handling required?) The watchdog is there to react "when things don't go quite right".Ctrl-C implies 'someone' wants to change/interrupt program flow.Watchdog is typically for un-attended use. Maybe you c write it -C- ? Or have a 'primary program' with the watchdog code (only?) call other program(s) that can terminate (sys.exit) Ctrl-c etc. You want to plan your application, and determine which module is critical, --so that if it stopped-- would result in a system reset. - Hope this helps.

  4. Thank you very much,
    Can you please explain what actually happens when the watchdog times out .. what type of reset function is performed?
    If I am running ubuntu will the watchdog reset safely close open files and reboot the unbuntu O/S in a similar maller to a power on reset?

    Also how do I configure the watchdog for different reset times say 300 seconds?

    How does one correctly "close" the watchdog as per your previous post?

  5. The watchdog timer is an independent circuit that performs a hardware reset. 300 seconds is a very long time that would required a large capacitor difficult to integrate into an IC (60 seconds is already quite long). Close the '/dev/watchdog' file the same way as any other file. fclose()

    1. But how to change default timeout period?