C++ for Raspberry Pi 5: High-Speed Rotary Encoder Interrupts with libgpiod

Why C++ for Raspberry Pi Hardware Control?

If you are building a project that requires strict microsecond timing, high-frequency interrupt handling, or deterministic memory management, Python’s Global Interpreter Lock (GIL) and garbage collection pauses will eventually cause you to miss hardware events. When a mechanical rotary encoder spins at 3,000 RPM, it generates thousands of edge transitions per second. Python scripts frequently drop counts under this load, while C++ handles them effortlessly.

For modern Raspberry Pi hardware control in 2026, the deprecated wiringPi and legacy sysfs interfaces are dead. The official Linux kernel standard is libgpiod (specifically v2 on Debian Bookworm). Below is a real-world latency comparison when reading a GPIO edge interrupt on the Raspberry Pi 5.

As the data shows, C++ with libgpiod drops latency from milliseconds to microseconds. This guide walks through building a robust, interrupt-driven rotary encoder reader using C++ and the Linux character device API.

Project Specs and Parts List

• Microcomputer: Raspberry Pi 5 (8GB variant recommended for desktop multitasking, 4GB fine for headless)
• Sensor: KY-040 Rotary Encoder Module (Includes built-in 10kΩ pull-up resistors on the PCB)
• Wiring: 22 AWG solid core jumper wires (Female-to-Female)
• Power: Official Raspberry Pi 27W USB-C PD Power Supply (Crucial for Pi 5 stability under load)

Safety Note: The Raspberry Pi 5 GPIO pins are strictly 3.3V logic. The KY-040 module can operate on either 3.3V or 5V. You must power the module's VCC pin with 3.3V from the Pi. Feeding 5V into the Pi 5's GPIO pins will permanently destroy the RP1 southbridge.

Pin Mapping and Wiring

The KY-040 outputs two square waves (CLK and DT) offset by 90 degrees. By reading the state of DT when CLK transitions, we determine the direction of rotation. The table below maps the physical BCM GPIO pins to the Pi 5 header.

The C++ Implementation (libgpiod v2)

While libgpiod v2 includes C++ bindings (libgpiodcxx), the C++ template API frequently shifts between minor Debian kernel updates, leading to frustrating compilation breaks. The industry-standard workaround for embedded C++ is to use the stable C API (<gpiod.h>) wrapped in idiomatic C++ classes. This guarantees your code compiles cleanly on any Bookworm-based Pi OS.

Prerequisites: Install the development headers and tools:
sudo apt update && sudo apt install libgpiod-dev gpiod build-essential

Create a file named encoder.cpp and paste the following complete, compilable code:

#include <gpiod.h>
#include <iostream>
#include <stdexcept>
#include <thread>
#include <chrono>
#include <atomic>
#include <csignal>

// --- PIN DEFINITIONS ---
// Pi 5 uses the RP1 southbridge. The primary GPIO chip is gpiochip4.
const char* CHIP_PATH = "/dev/gpiochip4";
const unsigned int PIN_CLK = 17;
const unsigned int PIN_DT  = 22;

std::atomic<bool> keep_running(true);
std::atomic<int> encoder_position(0);

void signal_handler(int signum) {
    keep_running = false;
}

int main() {
    std::signal(SIGINT, signal_handler);
    
    // 1. Open the GPIO chip
    struct gpiod_chip* chip = gpiod_chip_open(CHIP_PATH);
    if (!chip) {
        std::cerr << "gpiod::exception: Failed to open GPIO chip: " << CHIP_PATH << "\n";
        return 1;
    }

    // 2. Configure line settings (Input, Both Edges, Internal Pull-Up)
    struct gpiod_line_settings* settings = gpiod_line_settings_new();
    gpiod_line_settings_set_direction(settings, GPIOD_LINE_DIRECTION_INPUT);
    gpiod_line_settings_set_edge_detection(settings, GPIOD_LINE_EDGE_BOTH);
    gpiod_line_settings_set_bias(settings, GPIOD_LINE_BIAS_PULL_UP);

    // 3. Map settings to specific lines
    struct gpiod_line_config* line_config = gpiod_line_config_new();
    unsigned int offsets[] = {PIN_CLK, PIN_DT};
    gpiod_line_config_add_line_settings(line_config, offsets, 2, settings);

    // 4. Request the lines from the kernel
    struct gpiod_line_request* request = gpiod_chip_request_lines(chip, NULL, line_config);
    if (!request) {
        std::cerr << "Failed to request GPIO lines. Check permissions.\n";
        gpiod_chip_close(chip);
        return 1;
    }

    std::cout << "Monitoring KY-040 Encoder on Pi 5. Press Ctrl+C to exit.\n";
    
    struct gpiod_edge_event_buffer* buffer = gpiod_edge_event_buffer_new(16);
    int last_clk_state = gpiod_line_request_get_value(request, PIN_CLK);

    // 5. Main Event Loop
    while (keep_running) {
        // Wait for an edge event with a 100ms timeout
        int ret = gpiod_line_request_wait_edge_events(request, 100000000); // nanoseconds
        
        if (ret < 0) continue; // Timeout or interrupt
        
        int events_read = gpiod_line_request_read_edge_events(request, buffer, 16);
        
        for (int i = 0; i < events_read; i++) {
            struct gpiod_edge_event* event = gpiod_edge_event_buffer_get_event(buffer, i);
            unsigned int offset = gpiod_edge_event_get_line_offset(event);
            
            if (offset == PIN_CLK) {
                int clk_state = gpiod_edge_event_get_line_value(event);
                // Only process on RISING edge to prevent double-counting mechanical bounce
                if (clk_state == 1) {
                    int dt_state = gpiod_line_request_get_value(request, PIN_DT);
                    if (dt_state != last_clk_state) {
                        encoder_position++;
                    } else {
                        encoder_position--;
                    }
                    std::cout << "Position: " << encoder_position << "\n";
                }
                last_clk_state = clk_state;
            }
        }
    }

    // 6. Cleanup (RAII style teardown)
    gpiod_edge_event_buffer_free(buffer);
    gpiod_line_request_release(request);
    gpiod_line_config_free(line_config);
    gpiod_line_settings_free(settings);
    gpiod_chip_close(chip);
    
    std::cout << "Final Position: " << encoder_position << "\n";
    return 0;
}

Compilation Command:
g++ -std=c++17 -O2 encoder.cpp -o encoder -lgpiod

Execution:
./encoder

Debugging: "Failed to open GPIO chip"

When migrating from older Pi models or outdated tutorials, the most common fatal error you will encounter is:

gpiod::exception: Failed to open GPIO chip: /dev/gpiochip0: No such file or directory
or
Failed to request GPIO lines. Check permissions.

Here are the ranked causes and the first three things to check when this fails:

1. Wrong Chip Path (The Pi 5 RP1 Shift): On the Pi 4, the BCM2711 SoC exposed GPIO at /dev/gpiochip0. The Pi 5 routes GPIO through the external RP1 chip, which maps to /dev/gpiochip4. Run ls /dev/gpiochip* in your terminal. If gpiochip4 is missing, your kernel device tree is corrupted. If you see gpiochip0 but it fails, you are running the wrong path for your board.
2. Missing User Permissions: The /dev/gpiochip* character devices are owned by the root user and gpio group. If you get a permission denied error, add your user to the group: sudo usermod -aG gpio $USER, then reboot or log out/in for the group change to take effect.
3. Pin Reservation Conflicts: If gpiod_line_request fails, another subsystem has claimed GPIO 17 or 22. Run gpioinfo /dev/gpiochip4 to inspect the pins. If they show as "kernel" or "spi" instead of "input", check your /boot/firmware/config.txt and disable conflicting overlays like dtoverlay=spi0-1cs.

Extending and Simplifying the Build

Depending on your application requirements, you may need to adjust the complexity of this build.

How to Simplify (Polling vs Interrupts)

If you are building a simple volume knob for a media center and don't care about microsecond latency, you can strip out the gpiod_edge_event_buffer entirely. Replace the interrupt wait loop with a simple std::this_thread::sleep_for(std::chrono::milliseconds(5)) and poll the pin states using gpiod_line_request_get_value(). This reduces the code footprint by 40% and lowers CPU context-switching overhead, at the cost of missing steps if the user spins the knob violently fast.

How to Extend (Adding I2C OLED Feedback)

To make this a standalone interface, wire an SSD1306 128x64 I2C OLED display to the Pi 5's I2C1 bus (Physical Pins 3 and 5). Because C++ excels at multithreading, you can spawn a std::thread dedicated to rendering the encoder_position atomic variable to the display at 30 FPS, while the main thread remains locked to the high-speed GPIO interrupt buffer. This separation of concerns—hardware timing on the main thread, UI rendering on a worker thread—is where C++ for Raspberry Pi truly outshines single-threaded Python scripts.

For deeper reading on the RP1 southbridge architecture and character device APIs, refer to the official Raspberry Pi hardware documentation and the kernel.org libgpiod repository.