Raspberry Pi Pico C SDK: BME280 I2C Logging & Debugging Guide

The Raspberry Pi Pico C/C++ SDK offers bare-metal performance and deterministic timing that MicroPython simply cannot match. However, trading the REPL for CMake and GCC means trading runtime tracebacks for compile-time linker errors and silent hardware faults. When your I2C bus hangs or your serial output vanishes, you need a systematic debugging framework, not guesswork.

This guide walks through building a robust environmental data logger using the native Pico C SDK, reading a BME280 sensor over hardware I2C, and outputting formatted data via USB CDC. More importantly, it dissects the exact build and runtime errors you will inevitably encounter and how to fix them.

Project Overview & Hardware Spec Sheet

We are targeting the original Raspberry Pi Pico (RP2040). While the Pico W and Pico 2 share the same core SDK structure, the original Pico avoids the complexities of the CYW43439 WiFi chip GPIO muxing, keeping our focus strictly on peripheral I2C and USB CDC stdio routing.

Bill of Materials

Pin Mapping Table

Complete Pico C Firmware: BME280 I2C & UART Logging

Before writing C code, your CMakeLists.txt must explicitly link the hardware abstraction libraries. The Pico SDK does not link hardware_i2c by default to save flash space.

CMakeLists.txt Configuration

cmake_minimum_required(VERSION 3.13)
include(pico_sdk_import.cmake)

project(pico_c_bme_logger C CXX ASM)
pico_sdk_init()

add_executable(bme_logger main.c)

# Explicitly link standard library, I2C, and PWM hardware drivers
target_link_libraries(bme_logger 
    pico_stdlib 
    hardware_i2c 
    hardware_pwm
)

# Route stdio (printf) over USB CDC, disable UART stdio
pico_enable_stdio_usb(bme_logger 1)
pico_enable_stdio_uart(bme_logger 0)

pico_add_extra_outputs(bme_logger)

main.c Firmware

This code initializes the I2C1 peripheral at 400kHz, verifies the BME280 silicon ID, and enters a polling loop. It includes explicit error handling for I2C timeouts.

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

// --- Pin Definitions ---
#define I2C_PORT i2c1
#define I2C_SDA_PIN 4
#define I2C_SCL_PIN 5
#define STATUS_LED_PIN 15

// --- Sensor Definitions ---
#define BME280_I2C_ADDR 0x76
#define BME280_REG_ID 0xD0
#define BME280_EXPECTED_ID 0x60

void setup_i2c() {
    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); // Internal pull-ups as backup
    gpio_pull_up(I2C_SCL_PIN);
}

void setup_pwm_led() {
    gpio_set_function(STATUS_LED_PIN, GPIO_FUNC_PWM);
    uint slice_num = pwm_gpio_to_slice_num(STATUS_LED_PIN);
    pwm_set_wrap(slice_num, 255);
    pwm_set_gpio_level(STATUS_LED_PIN, 128); // 50% duty cycle
    pwm_set_enabled(slice_num, true);
}

int main() {
    // Initialize stdio (USB CDC) before any printf calls
    stdio_init_all();
    
    // Brief delay to allow USB CDC enumeration on host PC
    sleep_ms(2000); 
    
    setup_i2c();
    setup_pwm_led();
    
    printf("System Boot: Pico C BME280 Logger Initialized.\n");

    // Verify Sensor Presence
    uint8_t rx_buf[1];
    uint8_t reg = BME280_REG_ID;
    
    int bytes_written = i2c_write_blocking(I2C_PORT, BME280_I2C_ADDR, ®, 1, true);
    if (bytes_written < 0) {
        printf("FATAL: I2C Write failed with code %d. Check wiring.\n", bytes_written);
        return 1;
    }

    int bytes_read = i2c_read_blocking(I2C_PORT, BME280_I2C_ADDR, rx_buf, 1, false);
    if (bytes_read < 0) {
        printf("FATAL: I2C Read failed with code %d. Check pull-ups.\n", bytes_read);
        return 1;
    }

    if (rx_buf[0] != BME280_EXPECTED_ID) {
        printf("ERROR: Unexpected Chip ID 0x%02X. Expected 0x%02X.\n", rx_buf[0], BME280_EXPECTED_ID);
    } else {
        printf("SUCCESS: BME280 detected on I2C bus.\n");
    }

    // Main Loop
    while (true) {
        // In a production build, you would trigger a forced measurement here 
        // and read the 0xF7-0xFC registers for temp/press/hum data.
        printf("Polling sensor... (Extend logic for full data read)\n");
        
        // Heartbeat toggle
        static bool led_state = false;
        pwm_set_gpio_level(STATUS_LED_PIN, led_state ? 200 : 50);
        led_state = !led_state;
        
        sleep_ms(1000);
    }
    return 0;
}

Debugging Common Pico C SDK Build & Runtime Errors

When migrating from Arduino or MicroPython to the native Pico C SDK, the compiler and hardware abstraction layer (HAL) will punish missing configurations. Here are the exact error strings you will see and how to resolve them.

Error 1: The Missing Header Linker Fault

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

Ranked Causes:

1. CMake Omission (95%): You forgot to add hardware_i2c to target_link_libraries in your CMakeLists.txt. The SDK requires explicit opt-in for hardware peripherals.
2. SDK Path Corruption (5%): Your PICO_SDK_PATH environment variable is pointing to an incomplete or aborted Git clone of the SDK.

Error 2: The Silent I2C Timeout

Exact Error String: FATAL: I2C Read failed with code -2. Check pull-ups. (Code -2 is PICO_ERROR_TIMEOUT)

Ranked Causes:

1. Missing Pull-up Resistors: I2C is an open-drain bus. Without pull-ups to 3.3V, the SDA line floats low, and the RP2040 I2C state machine times out waiting for the bus to clear.
2. Wrong I2C Address: The BME280 defaults to 0x77 on many bare modules, but 0x76 on Adafruit breakouts. Check your specific silkscreen.
3. Multiplexed Pin Conflict: You assigned GP4/GP5 but initialized i2c0 instead of i2c1. GP4/GP5 belong to the i2c1 hardware block.

Error 3: The Vanishing Serial Output

Symptom: Code compiles and flashes successfully, the Pico reboots, but your serial monitor (PuTTY, screen, or Thonny) shows absolute silence.

Ranked Causes:

1. Missing USB CDC Flag: You omitted pico_enable_stdio_usb(bme_logger 1) in CMake, defaulting stdio to UART pins (GP0/GP1) instead of the USB port.
2. Missing Initialization: You forgot to call stdio_init_all(); at the very top of main().
3. USB Enumeration Race Condition: The Pico boots and prints to USB CDC before the host PC's OS has finished enumerating the virtual COM port. Always add a sleep_ms(2000); after stdio_init_all().

Extending and Simplifying Your Pico C Build

Once the basic I2C handshake and USB logging are stable, you will want to read actual temperature and humidity data. The BME280 requires reading calibration registers and applying complex compensation algorithms.

How to Extend: Offloading to Core 1

The RP2040 is a dual-core microcontroller. USB CDC polling and I2C blocking reads can cause micro-stutters in time-critical loops. Use the pico_multicore library to offload sensor polling to Core 1, passing data to Core 0 via the hardware FIFO.

#include "pico/multicore.h"

void core1_entry() {
    while (true) {
        // Perform blocking I2C reads here
        int32_t temp_data = read_bme280_temp();
        multicore_fifo_push_blocking(temp_data);
        sleep_ms(1000);
    }
}

// In main() on Core 0:
multicore_launch_core1(core1_entry);
while(true) {
    int32_t temp = multicore_fifo_pop_blocking();
    printf("Temp: %ld\n", temp);
}

How to Simplify: Using Bosch's Official API

Do not write the BME280 compensation math from scratch. Clone the official Bosch BME280 C driver from GitHub. Add bme280.c to your add_executable list in CMake, and implement the required user_i2c_read and user_delay_ms wrapper functions to bridge the Bosch API with the Pico HAL.

Frequently Asked Questions

How do I switch my Pico C code from the standard Pico to the Pico W?

The Pico W routes the onboard LED through the CYW43439 WiFi/BT chip, not a standard RP2040 GPIO. To control the LED on a Pico W, you must include pico/cyw43_arch.h, link pico_cyw43_arch_none in your CMake file, and use cyw43_arch_gpio_put(CYW43_WL_GPIO_LED_PIN, 1) instead of standard GPIO/PWM functions. Your I2C and USB CDC code will remain completely unchanged.

Why is my Pico C printf not showing up in the serial monitor?

By default, the Pico SDK routes printf output to UART0 (GP0/TX, GP1/RX). If you are plugging the Pico directly into your PC via USB and expecting to see text in a terminal, you must explicitly enable USB stdio in your CMakeLists.txt using pico_enable_stdio_usb(your_target_name 1) and ensure stdio_init_all() is called before your first print statement.

Can I use Arduino libraries in my Raspberry Pi Pico C SDK project?

No, not natively. The official Pico C SDK uses its own Hardware Abstraction Layer (HAL) and CMake build system, which is fundamentally incompatible with the Arduino core API (Wire.h, pinMode()). If you want to use Arduino libraries, you should abandon the native SDK and instead install the arduino-pico core by Earle Philhower via the Arduino IDE Boards Manager. However, you will sacrifice the deterministic timing, dual-core FIFO control, and PIO (Programmable I/O) access that make the native C SDK superior for embedded engineering.