A visual watchdog for the PI

Sometimes visualisations go wrong and get stuck for various reasons. It is useful to be able to detect and react to that.

How it works

It's a small C program for the Raspberry Pi that takes snapshot of the current content of the screen at a specified interval. Each time a snapshot is taken the tool calculates a checksum and compares the checksum with the checksum of the previous snapshot. If the checksums don't change it most likely means that the content of the screen didn't change.

If the screen doesn't change for a specified number of times the tool exits, so you can run (for example) a script that restarts your visualisation.

Installation

The visual-watchdog tool is part of a small collection of tools written for info-beamer pi but they are perfectly usable without using info-beamer itself. Source code is available on github.

First, fetch the source code and compile the tool on the PI:

pi@raspberrypi ~ $ git clone https://github.com/info-beamer/tools.git
Cloning into 'tools'...
remote: Counting objects: 56, done.
remote: Total 56 (delta 0), reused 0 (delta 0)
Unpacking objects: 100% (56/56), done.
pi@raspberrypi ~ $ cd tools/visual-watchdog/
pi@raspberrypi ~/tools/visual-watchdog $ make
[...]
pi@raspberrypi ~/tools/visual-watchdog $ 

A test run

Have a look at the README or just give the tool a try:

pi@raspberrypi ~/tools/visual-watchdog $ WATCHDOG_INTERVAL=1 WATCHDOG_COUNT=3 ./visual-watchdog 
starting watchdog for screen 1280x1024. 1 second interval, 3 trigger
chksum: 96558876
chksum: 103429708
chksum: 99403227
chksum: 100188574
chksum: 103353807
^C      <- I'm interrupting the tool by pressing Ctrl-C here
That's all. Have a nice day
pi@raspberrypi ~/tools/visual-watchdog $ 

The tool will output the checksum every WATCHDOG_INTERVAL seconds. Let's see what happens when the output on the screen doesn't change for WATCHDOG_COUNT intervals. To do that, you have to start the tool after over an ssh connection, otherwise the output in the terminal on your Pi will change the output on the screen :-)

pi@raspberrypi ~/tools/visual-watchdog $ export WATCHDOG_INTERVAL=1
pi@raspberrypi ~/tools/visual-watchdog $ export WATCHDOG_COUNT=3
pi@raspberrypi ~/tools/visual-watchdog $ ./visual-watchdog && echo "oh snap. It's unchanged"
starting watchdog for screen 1280x1024. 1 second interval, 3 trigger
chksum: 88232511
chksum: 88232511
chksum: 88232511
chksum: 88232511
stuck detected!
That's all. Have a nice day
oh snap. It's stuck

Notice the last line. The tool only exits with exit status 0 if it detects that the screen didn't change. So you can use && in the shell to start another program or script only in that case.

A real setup

If you use the tool in a real setup you can probably increase the WATCHDOG_INTERVAL setting to (for example) 30 seconds.

A complete setup might look like the following shell script:

#!/bin/bash
export WATCHDOG_INTERVAL=10
export WATCHDOG_COUNT=3
while true; do
    ./visual-watchdog && /etc/init.d/your-visualisation restart
    sleep 10 # give it time to restart
done

You can use daemontools to automatically start this script after the PI boot process finished. Have a look at the blog post about this.

Hope the tool is helpful to you.