Update repo-level README and CLAUDE.md for submodule structure

CLAUDE.md

@@ -4,19 +4,38 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository
 
-Multi-project repository for Raspberry Pi Pico (RP2040) firmware. Each project is a self-contained subfolder with its own Docker build, CMake config, and source tree.
+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 projects in this repo follow the same embedded C conventions:
+All components follow the same embedded C conventions:
 
-- **Component structure:** each component has `inc/` (public API), `prg/` (implementation + private header), `cfg/` (configuration)
+- **Component structure:** `inc/` (public API), `prg/` (implementation + private header), `cfg/` (configuration)
-- **Layered architecture:** STD_TYPES (library) → MCU (hardware drivers) → HAL (abstractions) → APP (application logic) → SYS (orchestrator)
+- **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
+```

README.md

@@ -1,6 +1,18 @@
 # Pico Projects
 
-A collection of Raspberry Pi Pico (RP2040) firmware projects. Each project is self-contained in its own subfolder with its own Dockerized build system, CMake configuration, and source code.
+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
 
@@ -8,15 +20,28 @@ A collection of Raspberry Pi Pico (RP2040) firmware projects. Each project is se
 |---|---|---|
 | [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 build                                  # first time only
-docker compose run --rm pico-build bash build.sh   # compile
+docker compose run --rm pico-build bash build.sh      # compile
-./flash.sh                        # flash to Pico (hold BOOTSEL + plug in)
+./flash.sh                                            # flash (hold BOOTSEL + plug in)
 ```
 
 See each project's own `README.md` for project-specific instructions.
@@ -31,12 +56,21 @@ No local ARM toolchain needed — everything builds inside Docker containers.
 
 ```
 pico/
-├── color_switcher/          # WS2812B color switcher with USB/UART comm
+├── common/                      # shared reusable components (git submodules)
-│   ├── cmake/               # modular CMake build system
+│   ├── STD_TYPES/               # fixed-width types and macros
-│   ├── src/                 # layered C firmware (MCU → HAL → APP → SYS)
+│   ├── MCU_UART/                # hardware UART driver
-│   ├── Dockerfile           # containerized ARM cross-compilation
+│   ├── 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
 │   ├── build.sh / flash.sh
 │   └── CLAUDE.md / README.md
-└── README.md                # this file
+├── .gitmodules
+├── CLAUDE.md
+└── README.md                    # this file
 ```