# fadi-eid/vcp-display architecture

> Architecture diagram of the GitHub repository fadi-eid/vcp-display, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fadi-eid/vcp-display
- Repository: https://github.com/fadi-eid/vcp-display

## Overview

##### Project Type & Purpose
- A multi-component firmware and host-side toolchain.
- “Embedded” folder: Dual-core STM32H7 firmware split into CM4 and CM7 targets, with common dual-core boot code, CMSIS, HAL drivers, DSP and NN libraries, RTOS2 support, and Makefile or `.ioc` project for code generation.

##### File Structure Analysis
Top-level directories:
- Desktop/.devcontainer, .vscode – containerized dev environment for host code.
- Desktop/Comm – C++ CLI “Comm” tool (CMake).
- Desktop/Display – C++ “Display” app that consumes Comm data.
- Desktop/Test – host-side unit/integration tests plus PyListen scripts for automated verification.
- Embedded/.devcontainer, .vscode – containerized firmware build environment.
- Embedded/CM4 & Embedded/CM7 – core-specific startup and application code.
- Embedded/Common – dual-core boot and inter-core synchronization.
- Embedded/Drivers – CMSIS, CMSIS-DSP, CMSIS-NN, RTOS2, and STM32H7xx HAL drivers.
- Embedded/Makefile – scripts and linker scripts for flashing each core.
- Embedded/PyListen – Python utilities to parse UART logs from firmware.

##### Key README Insight
- No textual architecture; relies on image to show host apps ↔ MCU data exchange.

##### Main Components
A. Developer Workstation
– VS Code IDE
– Docker DevContainer(s) for Desktop and Embedded
– Build System: CMake (Desktop), Makefile / CubeMX (Embedded)
B. Host-Side Applications
– Comm App (C++, CMake)
– Display App (C++, CMake)
– Test Suite (C++, Python)
C. Communication Channel
– USB Virtual COM Port (UART over USB)
– Data protocol between host apps and firmware
D. Embedded Device (STM32H7 Board)
- Bootloader (Common dual-core startup)
- CM7 Core – high-level application tasks
- CM4 Core – real-time DSP/ML processing tasks
- HAL & Middleware – STM32H7xx HAL, CMSIS, CMSIS-DSP, CMSIS-NN, RTOS2
- Peripherals – USART (UART), DMA, GPIO, etc.

##### Relationships & Interactions
- Developer → DevContainer → Build → Host Apps / Firmware
- Host Apps ↔ USB‐VCP ↔ Firmware (UART)
- Firmware layers:
– Startup (CMSIS & HAL init)
– RTOS2 scheduler & tasks
– DSP/NN libraries invoked by CM4 tasks
– Inter-core messaging between CM7 ↔ CM4 via shared memory or hardware semaphores
- Test scripts invoke Comm or directly parse logs for CI.

##### Architectural Patterns & Principles
- Layered architecture: Hardware abstraction → Middleware → Application.
- Dual-core partitioning: CM7 for coordination & communication; CM4 for signal processing.
- Containerized, reproducible build environments (DevContainers).
- Separation of concerns: Host apps vs firmware vs test harness.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Machine"
        direction TB
        VSCode_Host["VS Code Settings\n(Host)"]:::host
        VSCode_Fw["VS Code Settings\n(Firmware)"]:::host
        Desktop_DevContainer["DevContainer\n(Desktop)"]:::host
        Embedded_DevContainer["DevContainer\n(Embedded)"]:::host
        Build_Host["Build System\nDesktop (CMake)"]:::host
        Build_Fw["Build System\nFirmware\n(Makefile/CubeMX)"]:::host
    end

    subgraph "Host Applications"
        direction TB
        CommApp["Comm App\n(C++, CMake)"]:::host
        DisplayApp["Display App\n(C++, CMake)"]:::host
        TestSuite["Test Suite\n(C++, Python)"]:::host
    end

    subgraph "Communication Layer"
        direction TB
        USB_VCP["USB Virtual COM Port\n(UART over USB)"]:::comm
        Protocol["Data Protocol"]:::comm
    end

    subgraph "Embedded Device"
        direction TB
        Bootloader["Dual-Core Bootloader\n(Common startup)"]:::embedded
        subgraph "Firmware Cores"
            direction TB
            CM7["CM7 Core\n(Coordination & UART)"]:::embedded
            CM4["CM4 Core\n(DSP/ML Processing)"]:::embedded
        end
        Middleware["HAL & Middleware\n(CMSIS, DSP, NN, RTOS2)"]:::embedded
        Peripherals["Peripherals\n(UART, DMA, GPIO)"]:::embedded
    end

    %% Build Flows
    VSCode_Host -->|develop in| Desktop_DevContainer
    VSCode_Fw -->|develop in| Embedded_DevContainer
    Desktop_DevContainer -->|uses CMake| Build_Host
    Embedded_DevContainer -->|uses Makefile/CubeMX| Build_Fw
    Build_Host -->|produces binaries| CommApp
    Build_Host -->|produces binaries| DisplayApp
    Build_Host -->|produces tests/scripts| TestSuite
    Build_Fw -->|produces firmware| Bootloader
    Build_Fw -->|produces firmware| CM7
    Build_Fw -->|produces firmware| CM4

    %% Data Flows
    CommApp -->|sends/receives| USB_VCP
    DisplayApp -->|reads data| USB_VCP
    TestSuite -->|invokes| CommApp
    USB_VCP -->|UART| CM7
    CM7 -->|inter-core msg| CM4
    CM7 -->|calls| Middleware
    CM4 -->|calls| Middleware
    Middleware -->|controls| Peripherals

    %% Click Events
    click Desktop_DevContainer "https://github.com/fadi-eid/vcp-display/blob/main/Desktop/.devcontainer"
    click Embedded_DevContainer "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/.devcontainer"
    click VSCode_Host "https://github.com/fadi-eid/vcp-display/blob/main/Desktop/.vscode"
    click VSCode_Fw "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/.vscode"
    click CommApp "https://github.com/fadi-eid/vcp-display/blob/main/Desktop/Comm/CMakeLists.txt"
    click DisplayApp "https://github.com/fadi-eid/vcp-display/blob/main/Desktop/Display/CMakeLists.txt"
    click TestSuite "https://github.com/fadi-eid/vcp-display/blob/main/Desktop/Test/CMakeLists.txt"
    click Build_Fw "https://github.com/fadi-eid/vcp-display/tree/main/Embedded/Makefile"
    click Build_Fw "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/STM32H755-UART-VCP.ioc"
    click Build_Fw "https://github.com/fadi-eid/vcp-display/tree/main/Embedded/Makefile/CM4/Makefile"
    click Build_Fw "https://github.com/fadi-eid/vcp-display/tree/main/Embedded/Makefile/CM7/Makefile"
    click Bootloader "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/Common/Src/system_stm32h7xx_dualcore_boot_cm4_cm7.c"
    click CM7 "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/CM7/Src/main.c"
    click CM4 "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/CM4/Src/main.c"
    click Middleware "https://github.com/fadi-eid/vcp-display/tree/main/Embedded/Drivers/CMSIS/Device"
    click Peripherals "https://github.com/fadi-eid/vcp-display/blob/main/Embedded/CM7/Src/usart.c"

    %% Styles
    classDef host fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef comm fill:#FFA500,stroke:#000,stroke-width:1px
    classDef embedded fill:#90EE90,stroke:#000,stroke-width:1px
```
