Control GPIO with C++ on Raspberry Pi (Full Guide)

When working with Raspberry Pi, you will find that Python and Scratch are the most common languages used for many tasks, including GPIO programming. But did you know you could also use C++ for GPIO programming? And there are some good reasons to do that.

C++ can be used to program the Raspberry Pi GPIO pins with the help of libraries like WiringPi and PiGPIO. It offers better performance and control, making it ideal for hardware projects that require speed and precision.

The debate between Python Vs C++ for Raspberry Pi is pretty hot in the Raspberry Pi community. While Python is favored for its simplicity and vast ecosystem, C++ stands out when performance and precise hardware control matter. This feature makes C++ a solid choice for certain projects.

If you’re like me and sometimes mix up syntax between programming languages, I’ve got just the thing for you. I’ve put together a Python cheat sheet with all the essential syntax in one place, so you can keep it handy and avoid any confusion. Download it here for free!

Prerequisites

Below are some things you will need to get started with GPIO programming with C++.

• Raspberry Pi board: You can use any Raspberry Pi model that meets your project’s resource requirements. I’ll use a Raspberry Pi 4B with 2GB RAM for this tutorial.
  
• OS requirements: Any OS supported by Raspberry Pi will work. However, if you’re just starting, I recommend using Raspberry Pi OS first. You can always switch later once you have a good grasp of programming with C++ on the Raspberry Pi.
  
• C++ compiler (g++): This is the command-line compiler for C++, and it comes pre-installed on Raspberry Pi OS.
  
• Required libraries (WiringPi, PiGPIO): These C++ libraries are needed to interact with the Raspberry Pi’s GPIO pins.
  
• An LED: You’ll need at least one LED for this tutorial.

Understanding the Different GPIO Libraries for C/C++

Before diving into the different libraries available, let’s first understand why we need libraries when working with GPIO pins.

The main reason is simplicity. Libraries make it much easier to interact with GPIO pins without dealing with low-level hardware control, which can be complex and time-consuming.

For example, if I wanted to turn a GPIO pin ON/OFF, I could use this line of code:
digitalWrite(pin, HIGH); // Turn on an LED

But without a library, I’d have to work directly with memory registers, which is much more complicated.

WiringPi

WiringPi is one of the most popular libraries for interfacing with GPIO pins on the Raspberry Pi. I have used it for complex projects like building a line-following robot, and I didn’t face any issues.

However, before proceeding with WiringPi, you should know that its pin numbering system can be confusing.

WiringPi doesn’t follow the standard BCM (GPIO) numbering or the physical pin layout of the Raspberry Pi. When the first Raspberry Pi was released, it had only a few usable GPIO pins, which WiringPi numbered 0 to 7 in its way. As newer Raspberry Pi models introduced more GPIO pins, WiringPi kept its original numbering for backward compatibility.

This means that WiringPi pin numbers don’t always match the actual GPIO numbers or the physical pin positions on the board. But don’t worry! You can refer to the table below to see how each Raspberry Pi pin is mapped in WiringPi.

PiGPIO

pigpio is another library used to control GPIO pins on the Raspberry Pi with C++. I haven’t used it extensively as of writing this post, but from the few times I worked with it, I found it to be more powerful than WiringPi, and I would highly recommend it for advanced tasks only.

Unlike WiringPi, pigpio runs as a background service (daemon), making it ideal for precise GPIO control. If you’re working on a project that requires smooth and accurate motor or servo control, pigpio is worth considering.

However, this key feature is also its biggest downside. Since pigpio relies on its daemon, it may not work well on older Raspberry Pi models with limited resources (CPU & RAM), especially if you’re running heavy GPIO operations. Additionally, you can’t use it alongside other libraries like WiringPi, as they may conflict.

Note: For this post, I’ll be using WiringPi since I’m only writing a small program to light up an LED. WiringPi is beginner-friendly and one of the easiest ways to get started with GPIO on the Raspberry Pi.

Setting Up the Development Environment

You now have all the information needed to begin controlling GPIO pins with C++. Let’s now dive into the setup process.

Installing the Necessary Development Packages

If you’re using Raspberry Pi OS Full, it has many development packages pre-installed. However, if you’re using Raspberry Pi OS Lite (Minimal) or any other Debian-based distribution, you’ll need to install the C++ compiler and other dependencies manually.

You can do this by running the following commands:

sudo apt update
sudo apt install g++ build-essential

Installing and Setting Up WiringPI

You must install WiringPi to use it for your GPIO projects on the Raspberry Pi. First, update your system by running the command below:

sudo apt update

Earlier, you could easily install WiringPi from the Raspberry Pi repositories using the apt command. However, since its support is discontinued, you need to clone it from the WiringPi GitHub repository:

git clone https://github.com/WiringPi/WiringPi.git
cd WiringPi
./build debian
cd debian-template
sudo apt install ./wiringpi_3.14_arm64.deb

The file name may vary; adjust the last command to fit the file generated on your device.

Once done, you can verify whether the installation was a success by running the command below:
gpio -v

Now that we have the software requirements ready, let’s move to the next step, where we are setting up the circuit.

Setting Up the Circuit

The next step is setting up the circuit. This one will require you to be more handy as you will be connecting the LED to the Raspberry Pi GPIO pins.

Understanding Raspberry Pi GPIO Layout

Before I proceed, you need to understand that you cannot connect the LED to just any pin on the Raspberry Pi. Each pin has a specific role, and you can use it only for that role. Some of them are input/output, power (3.3V or 5V), or ground.

If you haven’t done a project that involves working with GPIO pins, I would suggest you quickly look at our comprehensive post on Getting started with GPIO pins on the Raspberry Pi. It will help you greatly understand what we will be doing in this tutorial.

Connecting the LED to the Raspberry Pi

Now, for these steps, I will go barebones and connect my LED directly to the Raspberry Pi without a resistor. Yes, I know this isn’t the ideal method, but I’ve done it before without any issues. Plus, I know my LED is rated at 3V, which is on the safe end and won’t damage the Pi.

I’ll be using a breakout board since it’s much cleaner and easier, but you can also wire it directly to the pins on the Raspberry Pi if that’s more convenient for you. I’ll connect the LED to GPIO 26 and Ground (GND).

Writing the GPIO Program to Blink the LED

Once you have set up the circuit, we can write the code. There are many editors you can use to write programs on your Raspberry Pi. You can choose from command-line-based editors like Nano or GUI-based editors like Geany. For this tutorial, I will stick to the nano editor.

To get started, launch the terminal and use the commands below to navigate to the Documents directory and create a program file:

cd Documents
mkdir BlinkLEDProgram
touch blink_led.cpp

After creating the file, we can now proceed to open it with the nano editor:
nano blink_led.cpp

Writing the Code

This will open an empty text editor where you can start writing your code. I will divide this code into sections so you can gain a better understanding.

#include <wiringPi.h>
#include <iostream>
#include <chrono>
#include <thread>

• “include <wiringPi.h>”: This line includes the WiringPi library, which lets you control the Raspberry Pi’s GPIO pins. It’s essential to work with hardware like LEDs.
• “include <iostream>”: This is for input and output operations. In this case, we will use it to print text to the terminal.
• “include <chrono>”: This provides time utilities. In our program, we will use utilities like milliseconds to control delays.
• “include <thread>”: We will use this to pause the program for a specified amount of time. It is similar to the sleep() function in Python.

constexpr int LED_PIN = 25;

Here, we are defining a constant LED pin that we will interact with on the Raspberry Pi. You will notice that here I have set it to 25, yet during circuit setup, I stated clearly that I will connect the LED to GPIO 26.

Well, that comes down to the different GPIO numbering used by WiringPi. If you refer to the table above, you will notice that GPIO 26 on the Raspberry Pi is mapped as PIN 25 on the WiringPi library.

using namespace std;
using namespace std::chrono;
using namespace std::this_thread;

• using namespace std;: This means we can use standard C++ features (like cout, cerr, endl, etc.) without always needing to prefix them with std::.
• using namespace std::chrono; and using namespace std::this_thread;: These let us directly use time-related functions (like milliseconds and sleep_for) without writing out std::chrono::milliseconds or std::this_thread::sleep_for every time.

int main(int argc, char * argv[])

This is the entry point of our program where everything started running.

if (wiringPiSetup() == -1)
{
    cerr << "Failed to initialize wiringPi" << endl;
    return 1;
}

• wiringPiSetup(): This function initializes the WiringPi library. If it returns -1, something went wrong, and the library couldn’t be initialized.
• cerr << “Failed to initialize wiringPi” << endl;: If the WiringPi setup fails, this prints an error message to the terminal.
• return 1;: This ends the program if the setup fails. 1 indicates an error occurred.

pinMode(LED_PIN, OUTPUT);  // Set the LED pin as output

pinMode(LED_PIN, OUTPUT);: This tells the Raspberry Pi that GPIO pin 25 (where the LED is connected) will be used for output. This is important because pins can be set to either input (read data) or output (send data).

cout << "Blinking LED connected to GPIO pin " << LED_PIN << endl;

• cout: This prints a message to the terminal to let you know that the program is running and blinking the LED on GPIO pin 25. It’s like a quick status update for the user.

while (true)
{
    digitalWrite(LED_PIN, HIGH);
    sleep_for(milliseconds(500));

    digitalWrite(LED_PIN, LOW);  // Corrected from 'Low' to 'LOW'
    sleep_for(milliseconds(500));
}

• while (true): This starts an infinite loop. The code inside the loop will run forever until you stop the program manually. This is used to blink the LED continuously.
• digitalWrite(LED_PIN, HIGH);: This turns the LED on by sending a high signal to GPIO pin 25. HIGH is a constant that means “on.”
• sleep_for(milliseconds(500));: This pauses the program for 500 milliseconds (0.5 seconds), so the LED stays on for half a second.
• digitalWrite(LED_PIN, LOW);: This turns the LED off by sending a low signal to GPIO pin 25. LOW means “off.”
• sleep_for(milliseconds(500));: This pauses the program for another 500 milliseconds, so the LED stays off for half a second.

This loop makes the LED blink on and off every half-second.

return 0;

This line marks the end of the program and returns 0 to indicate that everything ran successfully. However, since we have an infinite while (true) loop, this line will never be reached unless the program is manually stopped by hitting Ctrl + C on the keyboard.

The resulting code looks similar to the image below.

Once done, use Ctrl + S to save the code and exit (Ctrl + X).

Running and Compiling the Code

To compile this program, execute the command below:

g++ -std=c++17 -o blink_led blink_led.cpp -lwiringPi

• g++: This is the GNU C++ compiler.
• -std=c++17: Specifies that the code should be compiled using the C++17 standard.
• -o blink_led: This tells the compiler to create an output file named blink_led (the executable).
• blink_led.cpp: This is the source file where we wrote the code.
• -lwiringPi: Links the WiringPi library, which is needed to control the Raspberry Pi’s GPIO pins.

After successful execution, you can run the program using the line below:
./blink_led

The video below shows the output I got on my end. Everything went smoothly, and my LED was blinking as expected.

Troubleshooting Any Errors

Most of the errors in the code will be captured during the compiling process and displayed on the screen. However, other issues might cause the program not to run or the LED not to blink

If you try to run the program and come across an error like:
wiringPiSetup: command not found

That means WiringPi is not installed properly. You can reinstall it by following the instructions in the “Installing and Setting up WiringPI” section above.

Another advanced method you can use to troubleshoot any arising issues is the gpio readall command:
gpio readall

It displays a table showing the current pin states, modes, and numbers for all GPIO pins. You can use this information to solve several issues with your LED not blinking.

• Checking Pin Numbering: Since different libraries (BCM, WiringPi, and Physical) use different numbering schemes, gpio readall helps you confirm which numbering system your program should use.
• Verifying Pin Modes: You check if the pin is set to INPUT, OUTPUT, or ALT mode.
• Checking Pin States: The command shows whether a pin is currently HIGH (1) or LOW (0). Therefore, if your LED is supposed to be ON but the pin is still LOW (0), you might have a wiring or software issue.
• Detecting Conflicts: You can also use this information to check if a PIN is being used by another process or library.

That’s it! You should now understand how to control GPIO pins using C++ on the Raspberry Pi. In this tutorial, I have only used a small example of blinking an LED using the WiringPi library. You can take this further by working on more complex projects and using more components.

FAQ

Can You Program GPIO Without Any Libraries?

Yes, but it’s much harder. You would need to interact directly with memory registers or system files like /sys/class/gpio/. Libraries like WiringPi and PiGPIO make it much easier.

Do You Need Root Privileges to Control GPIO in C++?

That depends on the library you’re using. WiringPi requires root (sudo) to access GPIO pins because it interacts directly with the hardware. PiGPIO runs as a background service (daemon), so it doesn’t always require sudo, but it depends on how the daemon is set up.

Whenever you’re ready, here are other ways I can help you:

Test Your Raspberry Pi Level (Free): Not sure why everything takes so long on your Raspberry Pi? Take this free 3-minute assessment and see what’s causing the problems.

The RaspberryTips Community: Need help or want to discuss your Raspberry Pi projects with others who actually get it? Join the RaspberryTips Community and get access to private forums, exclusive lessons, and direct help.

Master your Raspberry Pi in 30 days: If you are looking for the best tips to become an expert on Raspberry Pi, this book is for you. Learn useful Linux skills and practice multiple projects with step-by-step guides.

Master Python on Raspberry Pi: Create, understand, and improve any Python script for your Raspberry Pi. Learn the essentials step-by-step without losing time understanding useless concepts.

You can also find all my recommendations for tools and hardware on this page.