Visual Studio Code for Raspberry Pi 5: Remote-SSH C++ GPIO Setup

Using Visual Studio Code for Raspberry Pi development in 2026 means abandoning the native desktop IDE. The Pi 5 is a powerhouse, but running Electron-based apps directly on its desktop environment still consumes precious RAM and stutters during heavy C++ IntelliSense indexing. The definitive, professional approach is using the VS Code Remote-SSH extension to write, compile, and debug C++ hardware control code natively on the Pi's RP1 silicon, while keeping the heavy UI lifting on your host machine.

This guide provides the exact configuration, hardware BOM, and libgpiod C++ code to build a hardware-interrupt-driven button and LED circuit on the Raspberry Pi 5. We will also dissect the most common permission and IntelliSense errors that halt embedded developers on the new RP1 architecture.

The Verdict: Choosing Your VS Code Architecture

Before wiring a single pin, you must decide how Visual Studio Code will interact with the Pi. Here is the decision matrix that terminates in the only viable choice for hardware debugging.

The Concrete Pick: Use VS Code Remote-SSH targeting a headless Raspberry Pi 5 (8GB) running 64-bit Raspberry Pi OS (Bookworm). This gives you local-grade typing performance while compiling directly against the Pi's aarch64 toolchain.

Hardware BOM and Pin Mapping for the GPIO Test Rig

The Raspberry Pi 5 introduced the RP1 southbridge chip, which fundamentally changed how GPIO is addressed at the kernel level. The GPIO lines are no longer on gpiochip0; they are on gpiochip4. Your hardware and code must reflect this.

Pin Mapping Table

Configuring Visual Studio Code for Raspberry Pi C++

Follow these numbered steps to bridge your host machine to the Pi 5.

1. Prepare the Pi 5: Flash Raspberry Pi OS (64-bit, Bookworm) using Raspberry Pi Imager. In the Imager's OS Customisation settings, enable SSH (password or key), set your username (e.g., pi), and connect to WiFi.
2. Install Build Tools on Pi: SSH into the Pi and install the C++ compiler and the libgpiod development headers:

   sudo apt update
   sudo apt install build-essential cmake libgpiod-dev

3. Setup VS Code Host: Open VS Code on your Windows/Mac/Linux host. Install the Remote - SSH extension by Microsoft.
4. Configure SSH Config: Press F1, type Remote-SSH: Open SSH Configuration File, and add your Pi:

   Host pi5-embedded
       HostName 192.168.1.105
       User pi
       IdentityFile ~/.ssh/id_rsa

5. Connect and Workspace: Click the green Remote indicator in the bottom-left corner, select Connect to Host..., and pick pi5-embedded. Once connected, open a new folder (e.g., ~/projects/gpio-test).
6. Install Remote Extensions: VS Code will prompt you to install the C/C++ extension on the remote host. Click install. This ensures IntelliSense parses the Pi's actual /usr/include directories, not your host machine's headers.

The Code: libgpiod Button-Triggered LED in C++

This complete, compilable C++ block uses the libgpiod C API. It configures GPIO 17 as an output and GPIO 27 as an input with an internal pull-up resistor. It includes explicit error handling and a signal handler to ensure the GPIO lines are released cleanly if you press Ctrl+C.

Assumption: This code targets the libgpiod v1 API structure. If your Bookworm install defaults strictly to v2 without the v1 compatibility layer, see the debugging section below.

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

// Pin definitions for Raspberry Pi 5 (RP1 southbridge)
#define GPIO_CHIP "/dev/gpiochip4"
#define LED_PIN 17
#define BTN_PIN 27

volatile sig_atomic_t keep_running = 1;
void sig_handler(int _) { 
    keep_running = 0; 
}

int main() {
    signal(SIGINT, sig_handler);

    // 1. Open the GPIO chip
    struct gpiod_chip *chip = gpiod_chip_open(GPIO_CHIP);
    if (!chip) {
        std::cerr << "Failed to open " << GPIO_CHIP << ". Is the Pi 5 RP1 chip mapped correctly?" << std::endl;
        return 1;
    }

    // 2. Get the LED line and request output
    struct gpiod_line *led_line = gpiod_chip_get_line(chip, LED_PIN);
    if (!led_line || gpiod_line_request_output(led_line, "led_control", 0) < 0) {
        std::cerr << "Failed to request LED line " << LED_PIN << std::endl;
        gpiod_chip_close(chip);
        return 1;
    }

    // 3. Get the Button line and request input with pull-up
    struct gpiod_line *btn_line = gpiod_chip_get_line(chip, BTN_PIN);
    if (!btn_line || gpiod_line_request_input_flags(btn_line, "btn_read", GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP) < 0) {
        std::cerr << "Failed to request Button line " << BTN_PIN << std::endl;
        gpiod_line_release(led_line);
        gpiod_chip_close(chip);
        return 1;
    }

    std::cout << "Monitoring GPIO " << BTN_PIN << ". Press Ctrl+C to exit." << std::endl;

    // 4. Main polling loop
    while (keep_running) {
        int btn_state = gpiod_line_get_value(btn_line);
        if (btn_state < 0) {
            std::cerr << "Error reading button state" << std::endl;
            break;
        }
        
        // Button is active-low due to pull-up
        if (btn_state == 0) {
            gpiod_line_set_value(led_line, 1); // LED ON
        } else {
            gpiod_line_set_value(led_line, 0); // LED OFF
        }
        usleep(10000); // 10ms debounce delay
    }

    // 5. Clean up resources
    std::cout << "\nReleasing GPIO lines..." << std::endl;
    gpiod_line_release(led_line);
    gpiod_line_release(btn_line);
    gpiod_chip_close(chip);
    return 0;
}

Compile and run:
g++ -o gpio_test main.cpp -lgpiod
./gpio_test

Debugging: Fixing GPIO and IntelliSense Errors

When working with the RP1 chip and Remote-SSH, you will hit specific roadblocks. Here are the exact error strings and how to fix them.

Error 1: "gpiod_line_request_output: Permission denied"

This is the most common runtime failure on Pi 5. The kernel blocks your user from accessing the /dev/gpiochip4 character device.

Ranked Causes & Fixes:

1. Wrong Chip Number (Most Likely): You copied code from a Pi 4 tutorial targeting /dev/gpiochip0. Fix: Run gpiodetect in the terminal. On Pi 5, the RP1 chip is almost always gpiochip4. Update your #define GPIO_CHIP.
2. Missing User Permissions: Your user isn't in the hardware group. Fix: Run sudo usermod -aG gpio $USER, then log out and log back in.
3. Line Already Claimed: Another process (like a lingering Python script or pigpiod) holds the line. Fix: Run gpioinfo gpiochip4 | grep 17 to see if the line shows as "kernel" or "used". Kill the offending process.

Error 2: IntelliSense "cannot open source file 'gpiod.h'"

Your code compiles fine via SSH terminal, but VS Code shows red squiggly lines everywhere.

Ranked Causes & Fixes:

1. Host vs. Remote Extension Mismatch: You installed the C/C++ extension on your Windows host, but not on the remote Pi. Fix: Open the Extensions tab, filter by "Installed", and ensure C/C++ is explicitly installed in the "SSH: pi5-embedded" section.
2. Missing Include Path: Fix: Press F1, run C/C++: Edit Configurations (UI). In the "Include path" box, ensure /usr/include and /usr/include/gpiod are listed.

Extending the Build: Adding PWM and I2C Sensors

Once the basic digital I/O is stable, you will want to expand the project. Here is how to extend or simplify the build based on your end goal.

How to Extend: Hardware PWM and I2C

• PWM for LED Dimming: The libgpiod library does not handle PWM natively. To dim the LED, switch to the lgpio library (sudo apt install liblgpio-dev), which wraps the RP1 PWM hardware seamlessly. Alternatively, use the Pi's hardware PWM pins (GPIO 12 or 13) via the pigpio daemon, though lgpio is preferred for Pi 5.
• Adding an I2C Sensor (e.g., BME280): Wire SDA to GPIO 2 (Pin 3) and SCL to GPIO 3 (Pin 5). Enable I2C via sudo raspi-config. In VS Code, install the smbus2 Python package or use the C++ libi2c-dev headers to read temperature data alongside your GPIO button logic.

How to Simplify: Switching to Python

If C++ memory management and libgpiod API versioning are slowing down your prototyping, simplify the stack. Switch your VS Code workspace to Python using the gpiozero library. While Python is interpreted and lacks the microsecond latency of C++, gpiozero abstracts the RP1 chip complexities entirely. You lose the ability to catch low-level kernel permission errors directly in code, but you gain a 10x reduction in setup time for basic sensor polling.

For authoritative documentation on the RP1 chip architecture and Remote-SSH configurations, refer to the official Raspberry Pi 5 documentation and the libgpiod kernel repository.