Handling GPIO-connected switches robustly in C on the Raspberry Pi

Educational applications for the Raspberry Pi often involve connecting switches or pushbuttons to the GPIO pins, and using the switch state to trigger some action -- perhaps controlling some other electrical device, or just performing some operation in software.

The 'sysfs' interface in the Linux kernal -- despite its deprecated status -- makes this kind of thing very easy, at least in principle. It's just a matter of reading the GPIO pin status from a pseudo-file in the /sys/class/gpio/ directory. This will either return "1" for a high logic level, or "0" for a low one.

In an educational setting, having a program loop endlessly, checking the state of the GPIO, and then doing something when it changes, might well be satisfactory. In a practical application, this won't work very well, for various reasons.

First, unless the program checks the status very frequently -- which involves a lot of CPU activity -- it won't be very responsive to button presses. Second, it doesn't cope very well with the scourge of switch contact bounce. Again, this might not matter in all applications -- it might not hurt to switch something on that is already on, for example. But if you're using push-buttons to operate a menu selection, for example, it's very unhelpful if every press of the button moves the menu selection by three of four steps. For counting applications, this lack of determinacy could be a critical failure.

What we need is a strategy that (a) uses little or no CPU for the routine processes of checking the GPIO pin status, (b) responds instantly (well, within milliseconds), and (c) makes some effort to avoid the effects of contact bounce.

This article describes an approach for handling these issues in a C application, working around some odd quirks in the way that the Raspberry Pi kernel handles GPIO interrupts. I don't suppose that this is the only way to solve the problem, and I can't be certain that future Raspberry Pi models, or even newer kernels, would behave in exactly the same way.

Polling for interrupts

The least CPU-intensive way to determine when a GPIO pin has changed status is to use the poll() operation to check for 'priority' events. The way this should work for the sysfs interface is described in the kernel documentation.

We need to open the value pseudo-file for each pin, and the call poll() on the array of file descriptors. In outline, the code looks something like this:

struct pollfd fdset [MAX_PINS];
int gpio_fd_1 = open ("/sys/class/gpio/gpio22/value", O_RDONLY|O_NONBLOCK);
fdset[0].fd = gpio_fd_1;
fdset[0].events = POLLPRI;
int gpio_fd_2 = open ("/sys/class/gpio/gpio27/value", O_RDONLY|O_NONBLOCK);
fdset[1].fd = gpio_fd_2;
fdset[1].events = POLLPRI;
...

poll (fdset, MAX_PINS, -1);

The code creates an array of pollfd objects, and then sets each one to be triggered by a priority POLLPRI event. The poll() call returns whenever such an event is detected.

A priority event could be a low-to-high level change, or a high-to-low level change, or both, according to the value written to the edge pseudo-file for the relevant GPIO pin. In practice, though, a switch contact will generate both high-low and low-high transitions, whether it opens or closes, so we can't assume that contact bounce won't generate multiple events, even if the specific edge value is set.

Note that the poll operation can monitor any number of pins in the same call, and it does not seem to make any difference to the CPU usage -- it's effectively zero whilst waiting for a transition, however many pins are monitored.

Of course, if you monitor multiple pins, you need a way to work out which pin triggered poll() to exit.

for (i = 0; i < MAX_PINS; i++)
  {
  if (fdset[i].revents & POLLPRI)
    {
    // Pin definition i was triggered
    }
  }

If we are looking for level changes in both directions (switch on and switch off), the polling code does not give any indication of which direction the level changed. To figure this out we need to read the file descriptor for the value pseudo-file again. Unfortunately, this file won't contain valid data at this point. According to the kernel documentation:

"After poll(2) returns, either lseek(2) to the beginning of the sysfs file and read the new value or close the file and re-open it to read the value."

In fact, neither of these approaches seems to work very well on the Pi, if there are very rapid level transitions -- which there will be if the switch contacts bounce.

What I've found to work reasonably well is the following:

1. Read the file descriptor to exhaustion (probably only two bytes) to clear the interrupt status
2. Wait a short time (see below)
3. Open the value file again, and get a new file descriptor
4. Read two bytes -- the first byte will be the desired "1" or "0"
5. Close the new file descriptor

The length of a 'short time' needs a little explanation. We aren't waiting for any change in the contact status here -- we're just waiting for the value stored by the kernel to settle. In my tests, a delay of a millisecond or so is sufficient. I have to admit that I've arrived at this procedure by trial-and-error, because the documented method does not seem to work reliably. I can't be certain that it will work in all Pi versions and set-ups, although I've been using it myself for about five years, and it's held up so far.

Characterstics of contact bounce

So we have a way to detect pin level changes without putting any strain on the CPU. But that, in itself, doesn't provide a way to handle contact bounce.

It isn't obvious to most designers, but switch contacts rarely make or break cleanly. The GPIO input level detection trips at a particular voltage but, if the voltage is changing slowly -- and 'slowly' here means over the course of a few milliseconds -- mutliple level changes can be registered over a short period. In addition, switch contacts frequently do literally bounce; that is, the contact surfaces bounce off one another before they settle into position. Typically a plot of pin state over time looks something like this:

In this plot, the 'bounce time' is the time over which we have to assume that level changes are not genuine, and must be ignored. The chaotic nature of switch contact behaviour, combined with the behaviour of the GPIO input circuit, means that we can't really predict how long the bounce time is -- all we can do is to set a value and hope, or insist, that the switch is not operated more frequently than that limit allows.

Handling contact bounce

So far as I know, the only robust way to handle contact bounce in a C application (or any other language routinely used on the Raspberry Pi) is to lock out transition detection for the bounce time, after the first level transition is detected. That's easy enough if we're only monitoring one pin -- we can just have the program sleep for a couple hundred milliseconds, or whatever turns out to be appropriate, then flush any outstanding interrupt events. However, if we are monitoring multiple pins, although we might want to lock out the same pin from triggering rapidly, we probably want other pins to trigger within the bounce times of their neighbours.

One way to handle this is to maintain an array of time values for each pin, recording when the first transition was detected for each pin. Subsequent transition for the same pin are ignored until the current time exceeds the stored time by the selected bounce time.

The complication here is that most programming languages and libraries do not provide a way to determine the time elapsed since a fixed point in time (e.g., the program start). This is actually surprisingly difficult to do, unless you have specialist hardware. We can use the general system clock to determine the elapsed time by calling, for gettimeofday() but this is problematic.

Why should this be? The problem is that that Linux system clock is prone to be disturbed. In a system like the Pi, which has no built-in real-time clock, it's particularly problematic. That's because we usually have to synchronize the clock from a time server using, e.g., NTP -- or just accept that the date is sometime around January 1970 all the time.

What typically happens when a Pi boots is that the system clock starts in January 1970 and then, when an Internet connection is established, suddenly jumps forward forty or so years. Looking for timing differences in switch contact changes of the order of milliseconds, when your timing baseline can suddenly shift by forty years, is a little tricky.

If you can't delay your program start-up until the system time has settled -- and in embedded applications you probably can't -- then one approach to a solution is just to reset the program's timing baseline when two events seem to be further apart in time than it reasonably plausible -- a year, perhaps. This does seem to work for me, but it's a method that might have to be adapted to suit the needs of the application.

Example

Complete sample code that demonstrates the techniques described in this article can be found in my pi-button-pipe application on GitHub.

Conclusion

It's surprisingly difficult to handle GPIO-connected switches in a robust, production-ready way on the Raspberry Pi. Partly that's because it's a genuinely difficult problem, and partly because the Pi kernel is a little quirky in this area. If practicable, hardware switch debouncing, or a combination of hardware and software, might be more appropriate for critical applications.