# herrera-dev/hardware_boot_selection_switch architecture

> Architecture diagram of the GitHub repository herrera-dev/hardware_boot_selection_switch, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/herrera-dev/hardware_boot_selection_switch
- Repository: https://github.com/herrera-dev/hardware_boot_selection_switch

## Overview

##### Project Type & Purpose
- The project is an embedded firmware application running on the RP2040 microcontroller. Its main task is to manage boot selection by printing a mass storage (MSC) interface via USB.
- It integrates with PC boot loaders (as shown in the README’s GRUB script snippet) to decide which OS to boot.

##### File Structure
- Top-level files like CMakeLists.txt and main.c indicate a build system based on CMake with the main application source.
- The files msc_disk.c, tusb_config.h, and usb_descriptors.c point to the USB functionality using the TinyUSB stack.
- The C file structure is flat, implying that the project is rather simple but modular: separate source files for USB configuration, MSC (mass storage) features, and main control logic.

##### Key Components
a. Firmware / Main Application
- Core logic in main.c that initializes the application and coordinates the boot switch operation.
b. USB Stack and MSC Module
- A component for the TinyUSB configuration (tusb_config.h) and USB descriptors (usb_descriptors.c), which defines how the USB device appears to the host.
- MSC functionality implemented in msc_disk.c that emulates a mass storage device.
c. Build and Deployment Infrastructure
- Build system (CMakeLists.txt) as an external process that compiles the firmware.
d. Hardware Platform
e. Host Boot Script (GRUB Configuration)
- Although not part of the firmware code, include an external integration point that shows how the firmware is used on the host (Ubuntu) to select a boot option based on the hardware switch state.

##### Relationships & Interactions
- That the MSC module (msc_disk.c) is integrated with TinyUSB components (tusb_config.h and usb_descriptors.c) to create a USB mass storage device.
- That once the firmware is flashed onto the RP2040 ZERO, the board communicates via USB with a host PC.
- How the PC uses the boot selection information (e.g., through the inserted USB device and external configuration like GRUB) to select the appropriate OS image.
- Optionally, include a connection from the build system (CMake) to the firmware image creation, leading to the UF2 file that gets copied to the device.

##### Architectural Patterns & Design Principles
- Separation of concerns: firmware logic, USB stack integration, and MSC functionalities are handled in distinct modules/files.
- Modular build process that leverages CMake.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Host Integration Layer
    subgraph "Host Integration"
        HOST("Host Boot Config (GRUB Script)"):::host
        PC("Host PC (Ubuntu)"):::host
    end

    %% Build Environment
    subgraph "Build Environment"
        BS("Build System (CMake)"):::build
    end

    %% Firmware Layer
    subgraph "Firmware"
        MF("Main Firmware (main.c)"):::firmware
        MSC("USB MSC Module (msc_disk.c)"):::firmware
        TCFG("TinyUSB Config (tusb_config.h)"):::firmware
        UDES("USB Descriptors (usb_descriptors.c)"):::firmware
    end

    %% Hardware Layer
    subgraph "Hardware"
        HW("Waveshare RP2040 ZERO Hardware"):::hardware
    end

    %% Relationships from Build Environment to Firmware
    BS -->|"builds"| MF
    BS -->|"builds"| MSC
    BS -->|"builds"| TCFG
    BS -->|"builds"| UDES

    %% Firmware interactions
    MF -->|"initUSB"| TCFG
    MF -->|"initUSB"| UDES
    MF -->|"configMSC"| MSC
    MF -->|"flashed_on"| HW

    %% Hardware to Host Communication
    HW -->|"presentsMSC"| PC
    PC -->|"bootSelect"| HOST

    %% Click Events
    click MF "https://github.com/herrera-dev/hardware_boot_selection_switch/blob/master/main.c"
    click MSC "https://github.com/herrera-dev/hardware_boot_selection_switch/blob/master/msc_disk.c"
    click TCFG "https://github.com/herrera-dev/hardware_boot_selection_switch/blob/master/tusb_config.h"
    click UDES "https://github.com/herrera-dev/hardware_boot_selection_switch/blob/master/usb_descriptors.c"
    click BS "https://github.com/herrera-dev/hardware_boot_selection_switch/blob/master/CMakeLists.txt"
    click HOST "https://github.com/herrera-dev/hardware_boot_selection_switch/blob/master/Readme.md"

    %% Styles
    classDef build fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef firmware fill:#87CEEB,stroke:#000,stroke-width:2px;
    classDef hardware fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef host fill:#98FB98,stroke:#000,stroke-width:2px;
```
