Writing Bare-Metal Raspberry Pi C Code for RP2040 Sensor Projects

To write deterministic, low-level Raspberry Pi C code for hardware control in 2026, you target the RP2040 microcontroller (Pico or Pico W) using the official Pico C/C++ SDK. Unlike Linux user-space GPIO libraries on the Pi 4 or Pi 5, bare-metal C on the RP2040 bypasses OS scheduling overhead, giving you microsecond-precise timing, direct register access, and predictable interrupt latency. This guide walks through a complete I2C sensor and PWM actuator build, the exact CMake toolchain setup, and how to debug the most common linker and compiler errors.

Project Spec Sheet & Hardware Bill of Materials

RP2040 GPIO Pin Mapping & Electrical Constraints

Before writing a single line of Raspberry Pi C code, you must map your physical pins to the RP2040's internal peripheral slices. The RP2040 does not hardwire I2C or PWM to specific pins; instead, it uses a multiplexer. However, electrical limits are strictly enforced by the silicon.

Source: RP2040 Datasheet (Section 2.19 - GPIO)

The Raspberry Pi C Code: I2C Sensor & PWM Fading

This block is fully compilable using the Pico SDK. It initializes I2C0 at 400kHz (Fast Mode), reads the BME280 chip ID to verify communication, and sets up a PWM slice on GPIO 15 to fade an LED using hardware interrupts rather than blocking sleep_ms() delays.

#include <stdio.h>
#include "pico/stdlib.h"
#include "hardware/i2c.h"
#include "hardware/pwm.h"
#include "hardware/gpio.h"

// --- PIN DEFINITIONS ---
#define I2C_PORT i2c0
#define I2C_SDA_PIN 2
#define I2C_SCL_PIN 3
#define BME280_ADDR 0x76
#define BME280_CHIP_ID_REG 0xD0
#define PWM_LED_PIN 15

// --- PWM INTERRUPT HANDLER ---
// In a real production build, you would use a DMA chain or PIO for zero-CPU PWM.
// For this example, we use the PWM wrap interrupt to step the duty cycle.
static volatile uint16_t pwm_level = 0;
static volatile bool fade_direction = true;

void on_pwm_wrap() {
    pwm_clear_irq(pwm_gpio_to_slice_num(PWM_LED_PIN));
    if (fade_direction) {
        pwm_level += 16;
        if (pwm_level >= 4096) fade_direction = false;
    } else {
        pwm_level -= 16;
        if (pwm_level == 0) fade_direction = true;
    }
    pwm_set_gpio_level(PWM_LED_PIN, pwm_level);
}

int main() {
    stdio_init_all();
    printf("Booting Raspberry Pi C Code Environment...\n");

    // 1. Initialize I2C Peripheral
    i2c_init(I2C_PORT, 400 * 1000); // 400kHz Fast Mode
    gpio_set_function(I2C_SDA_PIN, GPIO_FUNC_I2C);
    gpio_set_function(I2C_SCL_PIN, GPIO_FUNC_I2C);
    gpio_pull_up(I2C_SDA_PIN); // Explicitly enable internal pull-ups
    gpio_pull_up(I2C_SCL_PIN);

    // 2. Verify BME280 Sensor Presence (Error Handling)
    uint8_t chip_id = 0;
    uint8_t reg = BME280_CHIP_ID_REG;
    int bytes_read = i2c_write_blocking(I2C_PORT, BME280_ADDR, ®, 1, true);
    if (bytes_read < 0) {
        panic("I2C NACK: BME280 not found at 0x%02X. Check wiring.", BME280_ADDR);
    }
    i2c_read_blocking(I2C_PORT, BME280_ADDR, &chip_id, 1, false);
    
    if (chip_id != 0x60) {
        printf("Warning: Unexpected Chip ID 0x%02X (Expected 0x60)\n", chip_id);
    } else {
        printf("BME280 Verified. Chip ID: 0x%02X\n", chip_id);
    }

    // 3. Initialize PWM for LED Fading
    gpio_set_function(PWM_LED_PIN, GPIO_FUNC_PWM);
    uint slice_num = pwm_gpio_to_slice_num(PWM_LED_PIN);
    
    pwm_clear_irq(slice_num);
    pwm_set_irq_enabled(slice_num, true);
    irq_set_exclusive_handler(PWM_IRQ_WRAP, on_pwm_wrap);
    irq_set_enabled(PWM_IRQ_WRAP, true);

    pwm_config config = pwm_get_default_config();
    pwm_config_set_clkdiv(&config, 4.0f); // Slow down clock for visible fading
    pwm_config_set_wrap(&config, 4095);   // 12-bit resolution
    pwm_init(slice_num, &config, true);

    printf("System Online. LED Fading via Hardware PWM Interrupts.\n");
    
    // Main loop is free for Wi-Fi/RTOS tasks since PWM is interrupt-driven
    while (true) {
        tight_loop_contents(); 
    }
    return 0;
}

Build System & Flashing Steps

The Pico SDK relies on CMake. A missing library declaration here is the #1 cause of build failures for beginners writing Raspberry Pi C code.

1. Install the SDK: Clone the official SDK into a directory named pico-sdk and set your environment variable: export PICO_SDK_PATH=/path/to/pico-sdk.
2. Create CMakeLists.txt: In your project folder, create the build script. You must explicitly link the hardware libraries.

cmake_minimum_required(VERSION 3.13)
include(pico_sdk_import.cmake)
project(pico_sensor_project C CXX ASM)
pico_sdk_init()

add_executable(main main.c)

# CRITICAL: Link the specific hardware blocks used in the C code
target_link_libraries(main 
    pico_stdlib 
    hardware_i2c 
    hardware_pwm
)

pico_enable_stdio_usb(main 1)
pico_enable_stdio_uart(main 0)
pico_add_extra_outputs(main)

3. Compile: Run mkdir build && cd build && cmake .. && make.
4. Flash: Hold the BOOTSEL button on the Pico W, plug it into your PC via USB, and drag the generated main.uf2 file into the mounted RPI-RP2 drive.

Debugging: Ranked Causes for Common CMake & Linker Errors

When your build fails, do not guess. Check these exact error strings against the ranked solutions below.

The First Three Things to Check When It Fails

1. Library Linkage: Did you include hardware_i2c and hardware_pwm in target_link_libraries? The SDK does not auto-link hardware blocks.
2. SDK Path Variable: Is PICO_SDK_PATH exported in your current terminal session? (It does not persist across reboots unless added to .bashrc).
3. Physical Pull-ups: If the code compiles but panics at runtime with an I2C NACK, verify your breakout board has physical pull-up resistors. The RP2040 internal pull-ups (~60kΩ) are often too weak for 400kHz I2C bus capacitance.

Error String 1: undefined reference to 'i2c_init'

Cause: This is a linker error, not a compiler error. Your C code is syntactically correct, and the header was found, but the compiled binary for the I2C peripheral was not linked into the final .elf file.

Fix: Open CMakeLists.txt and ensure hardware_i2c is inside the target_link_libraries() parentheses. Clean your build directory (rm -rf build/*) and re-run CMake.

Error String 2: CMake Error: PICO_SDK_PATH is not defined

Cause: CMake cannot locate the pico_sdk_import.cmake file because the environment variable pointing to the SDK root is missing or misspelled.

Fix: Run echo $PICO_SDK_PATH. If it returns blank, export it: export PICO_SDK_PATH=~/pico/pico-sdk. Alternatively, hardcode it in your CMakeLists.txt above the include() line using set(PICO_SDK_PATH "/absolute/path/to/pico-sdk").

Error String 3: fatal error: hardware/i2c.h: No such file or directory

Cause: The compiler cannot find the header files. This usually happens if you are using a generic ARM GCC toolchain instead of the Pico-specific toolchain, or if pico_sdk_init() was omitted from the CMake script.

Fix: Ensure pico_sdk_init() is called after project() but before add_executable() in your CMake file. Verify you are using the arm-none-eabi-gcc compiler.

Extending and Simplifying the Build

Depending on your project phase, you may need to strip this build down or scale it up.

How to Simplify (Bench Testing Phase)

If you are just validating the toolchain and don't have the BME280 sensor on hand, strip out all hardware_i2c references. Remove the I2C initialization and sensor read blocks from the C code, and remove hardware_i2c from the CMake linker list. This leaves you with a pure PWM interrupt test that requires only an LED and a 330Ω resistor, eliminating bus-capacitance variables while you verify your compiler environment.

How to Extend (Production / IoT Phase)

Because this code targets the Pico W variant, the natural extension is adding the pico_cyw43_arch library to connect to Wi-Fi.

• Add FreeRTOS: Integrate the FreeRTOS SMP port for the RP2040. Move the I2C polling to a dedicated low-priority task, and handle MQTT telemetry on the second core.
• Use PIO for I2C: If you need to read multiple BME280 sensors on different pins without using up the RP2040's two hardware I2C blocks, rewrite the I2C read sequence using the Programmable I/O (PIO) state machines. This frees up the main CPU cores entirely.
• Add Watchdog: For remote deployments, include hardware/watchdog.h and call watchdog_update() in your main loop. If the Wi-Fi stack hangs (a known edge case with the CYW43439 driver under heavy SPI DMA load), the watchdog will hard-reset the silicon in 8 seconds.

Writing Raspberry Pi C code for the RP2040 bridges the gap between high-level Linux Python scripts and raw silicon manipulation. By respecting the hardware multiplexer, explicitly linking your CMake dependencies, and leveraging hardware interrupts over blocking delays, you build embedded systems that are both power-efficient and deterministic.