# jpwright/fpganes architecture

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

- Interactive diagram: https://gitdiagram.com/jpwright/fpganes
- Repository: https://github.com/jpwright/fpganes

## Overview

##### Project Type and Purpose
- This is a hardware‐only, FPGA‐based image pipeline and AI “agent” for playing Super Mario Bros. on the Altera DE2 board (no soft CPU or operating system). It streams video in from a camera (ITU‐656), processes it through custom Verilog “AI” logic, stores frames in SDRAM, and outputs video to VGA plus audio via an I²C‐configured DAC. MATLAB and Excel scripts are used offline to generate parameterized buffers and sprite‐LUTs baked into the bitstream.

##### File‐Structure Analysis
- Top‐level:
- cam_to_vga/ – Quartus project + all Verilog modules
- matlab_generators/ – .m scripts to auto‐generate circular buffers and update Verilog parameters
- excel_generators/ – XLSX that outputs Verilog for sprites/kernels
- schematic/ – DE2 hardware schematic for reference
- Within cam_to_vga/:
- DE2_TV.* – Quartus design files, fit/map reports, pin assignments
- *.v – Verilog modules (AUDIO_DAC, I2C_AV_Config, ITU_656_Decoder, YUV422_to_444, YCbCr2RGB, line buffers, SDRAM controller, VGA controllers, detection modules, goomba.v, recolor.v, intensityCalc.v, etc.)
- Sdram_Control_4Port/ – multi‐port SDRAM controller IP and FIFO interfaces
- *.mif, *.txt – pre‐computed lookup tables (RGB, segment LUTs, etc.)
- script.m – top‐level MATLAB driver to regenerate buffers

##### README Insights
- The entry point is DE2_TV.v, which instantiates and wires together all submodules.
- MATLAB/Excel are purely offline code‐gen steps that produce MIF files and Verilog includes; they are not part of the FPGA bitstream’s run‐time.

a. Main Components
- Camera Sensor + I²C AV Configuration block
- ITU_656_Decoder → YUV422_to_444 → YCbCr2RGB converter
- Line_Buffer (stream pipeline)
- Sdram_Control_4Port (frame read/write memory)
- AI/Image‐processing modules: recolor.v, intensityCalc.v, detector.v, edgedetectH/V.v, goomba.v, pipe_corner.v, etc.
- VGA_Ctrl / VGA_Controller (fetch from SDRAM & generate timing)
- Audio path: VGA_Audio_PLL → AUDIO_DAC (I²S or parallel audio)
- Offline Code‐Generation: MATLAB scripts & Excel sprite generator feeding MIFs into compile-time

b. Relationships & Data Flows
[Camera] → [I²C_AV_Config] → [ITU_656_Decoder] → [YUV→RGB chain] →
→ Stream into [Line_Buffer] → either direct pixel ops or write to [SDRAM Controller]
→ Processing modules read/write SDRAM → final frames read by [VGA_Controller] → [VGA].
- Audio branch taps off PLL into AUDIO_DAC.
- Offline scripts produce lookup‐table files (MIFs) which are bundled into the bitstream but sit outside the run‐time path.

c. Architectural Patterns & Principles
- Streaming pipeline + multi-port shared memory (SDRAM) for frame buffering
- Modular design—each image function is a separate Verilog module with standard streaming FIFO interfaces
- Offline code generation to keep on-FPGA logic generic and parameterized

d. Key Technologies & IP
- Verilog HDL targeting Altera/Intel Cyclone II (DE2 board)
- Altera SDRAM IP (Sdram_Control_4Port)
- I²C AV config core
- PLL blocks for clocking video/audio
- MATLAB & Excel for LUT/MIF generation
- Quartus compilation flow (db/, incremental_db/ folders)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Top-Level Integration"
        DE2["DE2_TV.v"]:::top
    end

    subgraph "Camera Interface"
        Camera["Camera Sensor"] 
        I2CConfig["I²C_AV_Config.v"]:::blue
        I2Cctrl["I²C_Controller.v"]:::blue
    end

    subgraph "Video Decode & Color Conversion"
        ITU["ITU_656_Decoder.v"]:::blue
        YUV422["YUV422_to_444.v"]:::blue
        YCbCr2RGB["YCbCr2RGB.v"]:::blue
    end

    subgraph "Streaming Buffer"
        LineBuf["Line_Buffer.v"]:::blue
    end

    subgraph "Frame Memory (SDRAM)" 
        SDRAM["SDRAM (Cylinder)"]:::orange
        subgraph "SDRAM Controller IP"
            SdramTop["Sdram_Control_4Port.v"]:::orange
            SdramRD["Sdram_RD_FIFO.v"]:::orange
            SdramWR["Sdram_WR_FIFO.v"]:::orange
            CtrlIface["control_interface.v"]:::orange
            DataPath["sdr_data_path.v"]:::orange
            Command["command.v"]:::orange
            PLLsdram["Sdram_PLL.v"]:::orange
        end
    end

    subgraph "AI / Image Processing"
        recolor["recolor.v"]:::green
        intensity["intensityCalc.v"]:::green
        detector["detector.v"]:::green
        edgeH["edgedetectH.v"]:::green
        edgeV["edgedetectV.v"]:::green
        goomba["goomba.v"]:::green
        pipe["pipe_corner.v"]:::green
        buffer3["buffer3.v"]:::green
        buffer11["buffer11.v"]:::green
        averager["averager.v"]:::green
    end

    subgraph "Output Controllers"
        VGA_ctrl["VGA_Controller.v"]:::purple
        VGA_CtrlAlt["VGA_Ctrl.v"]:::purple
        VGA_PLL["VGA_Audio_PLL.v"]:::purple
        AUDIO_DAC["AUDIO_DAC.v"]:::purple
        AUDIO_ADC["AUDIO_DAC_ADC.v"]:::purple
        VGA["VGA Output"]:::purple
        AudioOut["Audio Output"]:::purple
    end

    subgraph "Clock & Reset"
        PLL["PLL.v"]
        Reset["Reset_Delay.v"]
    end

    subgraph "Offline Code Generation"
        matlab["MATLAB Generators"]:::offline
        excel["Excel Generator"]:::offline
        script["script.m"]:::offline
    end

    subgraph "Compile-Time MIFs & LUTs"
        RGBmif["RGB1.mif"]:::offline
        SEG7["SEG7_LUT.v"]:::offline
        ROM["ROM.v"]:::offline
    end

    %% Data Flow
    DE2 --> Camera
    DE2 --> I2CConfig --> I2Cctrl --> ITU --> YUV422 --> YCbCr2RGB --> LineBuf
    LineBuf --> SDRAM
    SDRAM --> SdramTop --> SdramRD
    SdramTop --> SdramWR
    SdramTop --> CtrlIface --> DataPath --> Command --> PLLsdram
    SdramTop --> AIchain[/"AI Read/Write"/] 
    AIchain --> recolor --> intensity --> detector --> edgeH --> edgeV --> goomba --> pipe --> buffer3 --> buffer11 --> averager --> SDRAM
    SDRAM --> VGA_ctrl --> VGA
    VGA_ctrl --> VGA_CtrlAlt
    PLL --> ITU
    PLL --> VGA_PLL --> AUDIO_DAC --> AUDIO_ADC --> AudioOut
    Reset -.-> DE2

    %% Offline Data Flow
    matlab -.-> RGBmif
    matlab -.-> SEG7
    excel -.-> SEG7
    script -.-> RGBmif
    script -.-> ROM

    %% Click Events
    click DE2 "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/DE2_TV.v"
    click I2CConfig "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/I2C_AV_Config.v"
    click I2Cctrl "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/I2C_Controller.v"
    click ITU "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/ITU_656_Decoder.v"
    click YUV422 "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/YUV422_to_444.v"
    click YCbCr2RGB "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/YCbCr2RGB.v"
    click LineBuf "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Line_Buffer.v"
    click SdramTop "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/Sdram_Control_4Port.v"
    click SdramRD "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/Sdram_RD_FIFO.v"
    click SdramWR "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/Sdram_WR_FIFO.v"
    click CtrlIface "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/control_interface.v"
    click DataPath "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/sdr_data_path.v"
    click Command "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/command.v"
    click PLLsdram "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Sdram_Control_4Port/Sdram_PLL.v"
    click recolor "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/recolor.v"
    click intensity "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/intensityCalc.v"
    click detector "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/detector.v"
    click edgeH "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/edgedetectH.v"
    click edgeV "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/edgedetectV.v"
    click goomba "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/goomba.v"
    click pipe "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/pipe_corner.v"
    click buffer3 "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/buffer3.v"
    click buffer11 "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/buffer11.v"
    click averager "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/averager.v"
    click VGA_ctrl "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/VGA_Controller.v"
    click VGA_CtrlAlt "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/VGA_Ctrl.v"
    click VGA_PLL "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/VGA_Audio_PLL.v"
    click AUDIO_DAC "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/AUDIO_DAC.v"
    click AUDIO_ADC "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/AUDIO_DAC_ADC.v"
    click PLL "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/PLL.v"
    click Reset "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/Reset_Delay.v"
    click script "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/script.m"
    click matlab "https://github.com/jpwright/fpganes/blob/master/matlab_generators/*.m"
    click excel "https://github.com/jpwright/fpganes/blob/master/excel_generators/excel bitmapper.xlsx"
    click RGBmif "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/RGB1.mif"
    click SEG7 "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/SEG7_LUT.v"
    click ROM "https://github.com/jpwright/fpganes/blob/master/cam_to_vga/ROM.v"

    %% Styles
    classDef top fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef blue fill:#ADD8E6,stroke:#333,stroke-width:1px;
    classDef green fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef orange fill:#FFA500,stroke:#333,stroke-width:1px;
    classDef purple fill:#DDA0DD,stroke:#333,stroke-width:1px;
    classDef offline fill:#D3D3D3,stroke:#333,stroke-dasharray: 5 5;
    classDef memory fill:#FFA500,stroke:#333,stroke-width:1px,shape:cylinder;
    class SDRAM memoryconomie
```
