pi_pico/color_switcher/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

Raspberry Pi Pico firmware that sends commands over UART to a host computer. Written entirely in C using the Pico SDK (RP2040 / Cortex-M0+).

Build System

All builds run inside Docker — no local toolchain required.

• docker compose build — build the container image (first time / after Dockerfile changes)
• docker compose run --rm pico-build bash build.sh — compile the firmware, output lands in build/
• docker compose run --rm pico-build bash — interactive shell for debugging
• ./flash.sh — flash the .uf2 to a Pico in BOOTSEL mode (host-side only, not Docker)
• docker compose run --rm pico-build bash build.sh && ./flash.sh — build + flash in one command

The build uses CMake with the Pico SDK's ARM cross-compilation toolchain. The final artifact is a .uf2 file in build/. Flashing must run on the host macOS because it copies to /Volumes/RPI-RP2 (the Pico's USB mass storage mount).

Repository layout

color_switcher/
├── cmake/                          # all build-system files
│   ├── CMakeLists.txt              # thin orchestrator, drives build phases in order
│   ├── pico_sdk_import.cmake       # Pico SDK bootstrap (copied from SDK)
│   └── cmake_config/
│       ├── project_config.cmake    # project-wide vars (name, version, languages)
│       ├── mcu_config.cmake        # MCU helpers: mcu_init / mcu_sdk_config / mcu_link_target
│       └── sources_config.cmake    # source glob + include dir list
├── src/
│   ├── STD_TYPES/inc/              # shared fixed-width types, status enums, macros
│   ├── MCU_UART/{inc,prg,cfg}/     # hardware UART peripheral abstraction
│   ├── MCU_USB/{inc,prg,cfg}/      # USB-CDC (virtual serial port) abstraction
│   ├── HAL_COM/{inc,prg,cfg}/      # transport-agnostic comm layer (dispatches to UART/USB)
│   ├── APP_CLSW/{inc,prg,cfg}/    # color switcher application logic
│   └── SYS_ECU/prg/                # top-level app orchestrator (main entry)
├── build.sh                        # out-of-source build wrapper
├── Dockerfile / docker-compose.yml # containerized build env

Component file convention

Each component uses three subfolders:

• inc/ — public API headers (safe for any other component to #include)
• prg/ — private header (*_priv.h) + implementation (*_prg.c)
• cfg/ — configuration header and definitions (*_cfg.h / *_cfg.c)

CMake build phases

The top-level cmake/CMakeLists.txt runs in a strict order dictated by the Pico SDK:

1. include(project_config) — defines variables
2. include(mcu_config) — defines helper macros (no side effects)
3. mcu_init() — includes pico_sdk_import.cmake (must be before project())
4. project(...)
5. mcu_sdk_config() — calls pico_sdk_init()
6. include(sources_config) — sets PROJECT_SOURCES and PROJECT_INCLUDE_DIRS
7. add_executable(...)
8. mcu_link_target(...) — target_link_libraries, stdio routing, UF2 output

PROJECT_ROOT_DIR is computed in the top-level CMakeLists.txt as the parent of cmake/ and used everywhere that refers to paths outside the build system (e.g. src/).

Conventions

• Always add descriptive comments to all code and config files
• Avoid magic numbers — use named constants in config.h