# Pico Projects

A collection of Raspberry Pi Pico (RP2040) firmware projects with shared reusable components. Each project is self-contained in its own subfolder; shared MCU drivers and HAL abstractions live in `common/` as git submodules.

## Cloning

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

The `--recursive` flag pulls all submodules in `common/`. If you already cloned without it:

```bash
git submodule update --init --recursive
```

## Projects

| Project | Description | Target Board |
|---|---|---|
| [color_switcher](color_switcher/) | Interactive color-switching firmware with USB-CDC serial commands and WS2812B LED control via PIO | Waveshare RP2040-Zero |

## Shared Components (git submodules)

| Component | Repo | Description |
|---|---|---|
| [STD_TYPES](common/STD_TYPES/) | [std_types](http://git.teqanylogix.com:3000/mohamed.salem/std_types) | Fixed-width types, status enums, utility macros |
| [MCU_UART](common/MCU_UART/) | [mcu_uart](http://git.teqanylogix.com:3000/mohamed.salem/mcu_uart) | Hardware UART driver with DMA/ISR TX and ring buffer RX |
| [MCU_USB](common/MCU_USB/) | [mcu_usb](http://git.teqanylogix.com:3000/mohamed.salem/mcu_usb) | USB-CDC virtual serial port driver with ring buffer RX |
| [MCU_PIO](common/MCU_PIO/) | [mcu_pio](http://git.teqanylogix.com:3000/mohamed.salem/mcu_pio) | Generic PIO state machine driver with WS2812 program |
| [HAL_COM](common/HAL_COM/) | [hal_com](http://git.teqanylogix.com:3000/mohamed.salem/hal_com) | Transport-agnostic communication (function-pointer dispatch) |
| [HAL_LED](common/HAL_LED/) | [hal_led](http://git.teqanylogix.com:3000/mohamed.salem/hal_led) | LED strip/pixel abstraction with intensity scaling |

Each submodule ships with a default config (`cfg/`). Projects can override configs by placing their own `cfg` files earlier in the CMake include path.

## Getting Started

Each project is independent. To work on one, `cd` into its folder:

```bash
cd color_switcher/
docker compose build                                          # first time only
docker compose run --rm pico-build bash /scripts/build.sh     # compile
cd .. && ./flash.sh color_switcher                            # flash (hold BOOTSEL + plug in)
```

See each project's own `README.md` for project-specific instructions.

## Prerequisites

- [Docker](https://docs.docker.com/get-docker/) and Docker Compose

No local ARM toolchain needed — everything builds inside Docker containers.

## Repository Structure

```
pico/
├── common/                      # shared reusable components (git submodules)
│   ├── STD_TYPES/               # fixed-width types and macros
│   ├── MCU_UART/                # hardware UART driver
│   ├── MCU_USB/                 # USB-CDC driver
│   ├── MCU_PIO/                 # generic PIO driver + ws2812.pio
│   ├── HAL_COM/                 # communication abstraction
│   └── HAL_LED/                 # LED strip abstraction
├── color_switcher/              # project: WS2812B color switcher
│   ├── cmake/                   # modular CMake build system
│   ├── src/                     # project-specific components (APP_CLSW, SYS_ECU)
│   ├── Dockerfile               # containerized ARM cross-compilation
│   ├── docker-compose.yml
│   └── docker-compose.yml
│   └── CLAUDE.md / README.md
├── build.sh                     # shared build script (runs inside Docker)
├── flash.sh                     # shared flash script (runs on host macOS)
├── .gitmodules
├── CLAUDE.md
└── README.md                    # this file
```