Setting up a watchdog timer on a Raspberry Pi

Introduction

Running long-term projects on Raspberry Pi? Having it freeze is the worst thing it can happen to your Pi, especially if you have an IoT remote project not easily accessible by any means.

Freezes can happen for a variety of reasons: program bugs, insufficient RAM, too many spawned processes/threads… Watchdog can prevent that from happening.

The watchdog timer is a hardware-implemented timer used to reset microcontrollers or processors in case a malfunction is detected. It works by pinging the μCU/CPU at set intervals. If the μCU/CPU responds, the watchdog timer is reset and nothing happens. If it doesn’t respond or responds in an unusual way, the timer isn’t reset and it sends the signal to the μCU/CPU to reboot it.

This article introduces the concept of a watchdog timer in the context of the Raspberry Pi, a hardware-implemented device for restoring frozen systems. The following guide will help you set up the watchdog timer correctly on your system.

Setting up the watchdog timer

Prerequisites

• A working Raspberry Pi with an installed OS.
• Internet connection: only necessary during the installation process.
• Basic knowledge of Linux: you should be familiar with CLI text editors like nano or vi/vim and other Linux commands for managing the system.

Steps

1. As in almost every Raspberry Pi installation process, it’s best to make sure the system is up-to-date before you begin the installation.

sudo apt update
sudo apt full-upgrade

2. Enable the watchdog timer in the config.txt file, which is disabled by default in the Raspberry OS. You can use any editor, but I’ve opted to use nano for simplicity. Pre-Debian Bookworm release of Raspberry OS, config.txt was located in /boot/config.txt. In the Debian Bookworm release, it has been moved to /boot/firmware/config.txt. You’ll find the dtoverlay= line in the file. It may or may not contain any other parameters. If it doesn’t contain anything, add:

dtoverlay=watchdog

If it contains any parameters, just add the comma and watchdog after it. In my case, this line before edit was:

dtoverlay=vc4-kms-v3d,composite

And after I’ve added the watchdog parameter:

dtoverlay=vc4-kms-v3d,composite,watchdog

3. Install the watchdog daemon which controls the watchdog timer:

sudo apt install watchdog

4. Configure the watchdog daemon. The configuration file is located in /etc/watchdog.conf which needs to be edited. Find these two lines and uncomment them:

watchdog-device = /dev/watchdog
max-load-1 = 24

The first line is the interface which the daemon will use to communicate with the watchdog timer. The second line is the load average which will trigger the system reset. You can tune the second line based on your needs, but a normal functioning Raspberry Pi shouldn’t have a load average above 24.

5. Enable and start the watchdog timer using systemctl:

sudo systemctl enable watchdog
sudo systemctl start watchdog

6. (optional) If you wish, you can test the watchdog timer by using a so-called fork bomb. It spawns as many processes as possible freezing the system and triggering the system reset. There are two ways you can do that. The first way:

sudo bash -c ':(){ :|:& };:'

The second way:

sudo fork bomb

Conclusion

Setting up a watchdog timer is a great way to improve system reliability. It’s the perfect solution for IoT projects, especially in remote and off-grid applications. Having a watchdog timer pinging the CPU at set intervals restores system freezes and system crashes which insufficient RAM, process/thread spawning and program bugs can cause. In essence, the watchdog timer should reduce system downtime to a minimum.