# CLAUDE.md

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

## Repository

Multi-project repository for Raspberry Pi Pico (RP2040) firmware. Shared reusable components live in `common/` as git submodules. Each project is a self-contained subfolder with its own Docker build, CMake config, and source tree.

## Projects

- `color_switcher/` — WS2812B LED control with USB-CDC serial commands. See `color_switcher/CLAUDE.md` for project-specific architecture, build commands, and conventions.

## Shared Components (`common/` — git submodules)

| Component | Layer | Description |
|---|---|---|
| `STD_TYPES` | Library | Fixed-width types (u8/u16/u32/s8/s16/s32), status enums, utility macros |
| `MCU_UART` | MCU | Hardware UART driver with DMA/ISR TX, ring buffer RX, config-driven multi-instance |
| `MCU_USB` | MCU | USB-CDC driver with ring buffer RX via lazy stdio drain |
| `MCU_PIO` | MCU | Generic PIO state machine driver + ws2812.pio program |
| `HAL_COM` | HAL | Transport-agnostic communication with function-pointer dispatch, multi-channel |
| `HAL_LED` | HAL | LED strip/pixel buffer with intensity scaling over PIO |

Each submodule has `inc/`, `prg/`, and `cfg/` (default config). Projects reference them via CMake include paths pointing at `common/`.

## Common Conventions

All components follow the same embedded C conventions:

- **Component structure:** `inc/` (public API), `prg/` (implementation + private header), `cfg/` (configuration)
- **Layered architecture:** STD_TYPES → MCU → HAL → APP → SYS
- **Coding style:** MISRA-C influenced — single return per function, fixed-width types from STD_TYPES (never native C types except void), Hungarian naming, no function calls in conditions
- **Build system:** Dockerized ARM cross-compilation with modular CMake. No local toolchain required.
- **Always add descriptive comments** to all code and config files
- **Avoid magic numbers** — use named constants in config headers

## Cloning

```bash
git clone --recursive http://git.teqanylogix.com:3000/mohamed.salem/pi_pico.git
```