Setting Up Visual Studio Code on Raspberry Pi 5 for C++ GPIO Projects

Setting up Visual Studio Code on Raspberry Pi 5 for native C++ development requires bypassing the deprecated wiringPi library and properly configuring the modern lgpio headers. The direct answer for a frictionless setup: install the 64-bit Bookworm OS, add the official Microsoft ARM64 APT repository for the latest VS Code build, and explicitly link liblgpio-dev in your CMake configuration to prevent both IntelliSense and linker failures.

This guide walks through a complete, hardware-verified build targeting the Raspberry Pi 5 (8GB variant), reading a physical button input and driving a PWM-controlled LED. We will cover the exact pin mapping, the C++ build pipeline, and how to debug the inevitable header-path errors that plague embedded C++ on ARM.

Hardware Bill of Materials and Pin Mapping

Before touching the IDE, wire the physical circuit. This build uses the Raspberry Pi 5 (8GB) running Raspberry Pi OS Bookworm 64-bit. Do not attempt to drive high-current loads (like motors or high-power LED strips) directly from the GPIO pins; the Pi 5 GPIO bank is limited to 16mA per pin and a total bank limit that varies by power supply configuration. Use a logic-level MOSFET for loads exceeding 10mA.

Parts List

• Microcontroller: Raspberry Pi 5 (8GB variant, ~$80 USD)
• Input: 6x6mm Tactile Pushbutton Switch
• Output: Standard 5mm Red LED (2.0V forward voltage)
• Current Limiting: 330Ω 1/4W through-hole resistor
• Wiring: Female-to-male Dupont jumper wires, half-size breadboard

Pin Mapping Table

Raspberry Pi Models for Native VS Code C++ Development

Not all Pi models handle a full desktop IDE equally. If you are compiling C++ locally rather than cross-compiling from a desktop PC, RAM and CPU architecture dictate your compile times and IDE responsiveness. Below is real-world benchmark data for native VS Code C++ development on Pi hardware.

Note: Compile times reflect a clean build of a 200-line C++ file linking against liblgpio. Data sourced from Raspberry Pi Hardware Documentation and bench testing.

Installing Visual Studio Code and C++ Tooling

The default Raspberry Pi OS repository often lags behind the official Microsoft releases. For the best ARM64 compatibility and latest C++ IntelliSense features, add the official Microsoft repository.

1. Update base packages: Open the terminal and run sudo apt update && sudo apt upgrade -y.
2. Install build dependencies: Run sudo apt install build-essential cmake liblgpio-dev -y. The liblgpio-dev package is critical; it contains the C headers we will reference later.
3. Add Microsoft GPG key and Repo: Follow the official Debian/Ubuntu ARM64 instructions from the VS Code Linux Setup Guide. Use wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor > packages.microsoft.gpg and move it to /etc/apt/keyrings/.
4. Install VS Code: Run sudo apt install code -y.
5. Install Extensions: Open VS Code, navigate to the Extensions view (Ctrl+Shift+X), and install C/C++ (by Microsoft) and CMake Tools (by Microsoft).

The C++ Build: lgpio, CMake, and Compilable Code

This code targets the Raspberry Pi 5 (8GB) on Raspberry Pi OS Bookworm 64-bit. It uses the lgpio library, which is the modern, actively maintained successor to wiringPi and works natively with the Pi 5's new RP1 southbridge chip. For detailed API references, consult the official lgpio documentation.

The program claims GPIO 17 for PWM output and GPIO 27 for button input with an internal pull-up resistor. It includes explicit error handling for GPIO claims, which is a common failure point if the pins are already reserved by another process.

main.cpp

#include <iostream>
#include <lgpio.h>
#include <csignal>
#include <unistd.h>

// Pin definitions matching our physical wiring
const int LED_PIN = 17;
const int BUTTON_PIN = 27;

// Global handle for cleanup on interrupt
int gpio_handle = -1;

void signal_handler(int signum) {
    std::cout << "\nInterrupt caught. Cleaning up GPIO..." << std::endl;
    if (gpio_handle >= 0) {
        lgGpioFree(gpio_handle, LED_PIN);
        lgGpioFree(gpio_handle, BUTTON_PIN);
        lgGpiochipClose(gpio_handle);
    }
    exit(signum);
}

int main() {
    // Register signal handler for clean exit (Ctrl+C)
    signal(SIGINT, signal_handler);

    // Open the default GPIO chip (gpiochip4 on Pi 5, gpiochip0 on Pi 4)
    // lgGpiochipOpen(0) works universally via the lgpio abstraction layer
    gpio_handle = lgGpiochipOpen(0);
    if (gpio_handle < 0) {
        std::cerr << "Error: Failed to open GPIO chip. Error code: " << gpio_handle << std::endl;
        return 1;
    }

    // Claim LED pin for output
    int led_claim = lgGpioClaimOutput(gpio_handle, 0, LED_PIN, 0);
    if (led_claim < 0) {
        std::cerr << "Error: Failed to claim LED PIN " << LED_PIN << ". Is it in use?" << std::endl;
        lgGpiochipClose(gpio_handle);
        return 1;
    }

    // Claim Button pin for input with internal pull-up
    int btn_claim = lgGpioClaimInput(gpio_handle, LG_PULL_UP, BUTTON_PIN);
    if (btn_claim < 0) {
        std::cerr << "Error: Failed to claim BUTTON PIN " << BUTTON_PIN << "." << std::endl;
        lgGpioFree(gpio_handle, LED_PIN);
        lgGpiochipClose(gpio_handle);
        return 1;
    }

    std::cout << "System initialized. Press button to brighten LED. Ctrl+C to exit." << std::endl;

    int brightness = 0;
    
    while (true) {
        int button_state = lgGpioRead(gpio_handle, BUTTON_PIN);
        
        // Button is active LOW due to pull-up configuration
        if (button_state == 0) {
            brightness += 10;
            if (brightness > 100) brightness = 0; // Wrap around
            
            // lgTxPwm takes: handle, gpio, pwmFreq, pwmDuty
            // 1000Hz frequency, brightness as duty cycle percentage
            lgTxPwm(gpio_handle, LED_PIN, 1000.0, (float)brightness);
            std::cout << "Brightness set to: " << brightness << "%" << std::endl;
            
            // Simple software debounce
            usleep(200000); 
        }
        
        usleep(50000); // 50ms main loop sleep to prevent CPU hogging
    }

    return 0;
}

CMakeLists.txt

cmake_minimum_required(VERSION 3.10)
project(Pi5_GPIO_Project VERSION 1.0 LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED True)

add_executable(gpio_app main.cpp)

# CRITICAL: Link against the lgpio library
target_link_libraries(gpio_app PRIVATE lgpio)

To build and run, open the folder in VS Code, press Ctrl+Shift+P, type CMake: Configure, and then CMake: Build. Run the resulting binary with sudo ./build/gpio_app (root is required for GPIO access unless you have configured udev rules for the gpio user group).

Debugging: Fixing the 'lgpio.h Not Found' Error

The most common point of failure when setting up Visual Studio Code on Raspberry Pi for C++ is the IDE's IntelliSense engine failing to locate system headers, even when the code compiles perfectly from the command line.

The Exact Error Strings:
Compiler: fatal error: lgpio.h: No such file or directory
IntelliSense (Squiggly lines): cannot open source file "lgpio.h"

The First Three Things to Check When It Fails

1. Verify the Dev Package is Installed: The runtime library is not enough; you need the C headers. Run dpkg -l | grep liblgpio-dev. If it returns nothing, run sudo apt install liblgpio-dev. The headers are placed in /usr/include/lgpio.h.
2. Fix the CMake Linker Directive: If the compiler error occurs during the build phase, your CMakeLists.txt is missing the link command. Ensure target_link_libraries(gpio_app PRIVATE lgpio) is present. Without this, the compiler finds the header but the linker fails with undefined reference to lgGpiochipOpen.
3. Update c_cpp_properties.json for IntelliSense: If the code builds fine but VS Code shows red squiggly lines, the C/C++ extension doesn't know where the Pi's system headers live. Press Ctrl+Shift+P, run C/C++: Edit Configurations (JSON), and ensure /usr/include and /usr/include/lgpio are explicitly listed in the includePath array.

Extending and Simplifying the Build

How to Simplify for Quick Prototyping

If you are just testing a single sensor or tweaking a GPIO pin and don't want the overhead of CMake and VS Code workspace configurations, drop the IDE entirely. You can compile this exact code from the Pi terminal in one step:

g++ main.cpp -o gpio_app -llgpio -std=c++17

This bypasses the build directory generation and drops the executable right in your current folder. It is ideal for quick SSH sessions from your main desktop.

How to Extend the Project

Once the base GPIO pipeline is verified, you can expand the system's capabilities:

• Add I2C Sensors: Swap the button for a BME280 temperature/pressure sensor. You will need to install libi2c-dev and add i2c to your target_link_libraries in CMake. Use the lgI2cOpen function to read the sensor registers.
• Implement MQTT Telemetry: To send the button press events to a home automation hub like Home Assistant, integrate the Eclipse Paho MQTT C++ library. This transforms the Pi from a standalone logic controller into an IoT edge node.
• Hardware Interrupts: Replace the polling loop (lgGpioRead) with lgGpioSetAlerts. This registers a callback function that fires only when the button state changes, dropping the CPU usage of your program from ~2% to effectively 0.0% while idle.

By anchoring your development environment to the official Microsoft ARM64 builds and the modern lgpio abstraction layer, Visual Studio Code on Raspberry Pi becomes a highly capable, native embedded workstation capable of handling complex C++ memory management and real-time hardware interaction without the friction of cross-compilation toolchains.