# casper-astro/tutorials_devel architecture

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

- Interactive diagram: https://gitdiagram.com/casper-astro/tutorials_devel
- Repository: https://github.com/casper-astro/tutorials_devel

## Overview

##### Project Type & Purpose
- This is a “multi-platform tutorial” repository for the CASPER FPGA Toolflow.
- It bundles:
–  Core libraries (`casperfpga`, `mlib_devel` submodules)
–  Sphinx documentation (`docs/`)
–  Platform directories (`snap/`, `roach2/`, `skarab/`, `red_pitaya/`, `alveo/`, `rfsoc/`) each containing:
·  `mlib_devel` (submodule of DSP library code)
·  Tutorial designs (`*.slx`, `*.py`, `*.fpg`, `*.dtbo`)
·  `startsg` scripts for launching the MATLAB front-end
·  Example Python drivers

##### Main Components & Their Relationships
a.  User Environment (Developer Workstation)
–  Virtual environment or bare Python/MATLAB install
–  Shell / CLI to run `activate_platform.sh` and `startsg`
b.  Core Libraries
–  `casperfpga` (Python API to communicate with boards)
–  `mlib_devel` (DSP library for CASPER toolflow)
c.  Platform Modules (one per board)
–  Each platform folder (e.g. `snap/`, `roach2/`, etc.)
–  Contains `mlib_devel` (checked-out submodule) + `startsg` scripts + tutorials
d.  Toolflow Front-End (MATLAB + Simulink)
–  Reads platform’s `startsg.local` for board specifics
–  Loads design files (`*.slx`) and DSP blocks from `mlib_devel`
–  Exports bitstream (`.fpg`) and optionally device tree overlay (`.dtbo`)
e.  Python Control Layer
–  Uses `casperfpga` to connect to the hardware over Ethernet/PCIe
–  Runs tutorial scripts (`*.py`) for data capture, plotting, etc.
f.  Hardware Boards
–  Actual FPGA hardware (SNAP, ROACH2, SKARAB, etc.)
–  Receives bitstream and streams ADC/DAC data, network packets, etc.
g.  Documentation Site
–  Sphinx sources in `docs/`
–  Builds HTML tutorials covering the above workflow

1.  User invokes `./activate_platform <platform>` → checks out platform’s `mlib_devel`.
2.  User runs `cd <platform>/` & `./startsg startsg.local` → launches MATLAB front-end.
3.  MATLAB toolflow (Simulink + `mlib_devel`) → synthesizes & generates `.fpg`/`.dtbo`.
4.  User runs Python tutorial (e.g. `snap/tut_spec/snap_tut_spec.py`) → uses `casperfpga`.
5.  Python API → communicates (Ethernet/PCIe) → FPGA board → streams data back.
6.  Results → plots & logs on user workstation.

##### Highlighted Architectural Patterns
- Plugin-style per-platform directories—each self-contained.
- Clear layering: Core libs → MATLAB/Simulink front-end → bitstream → Python API → hardware.
- Documentation decoupled from code; built via Sphinx.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Workstation"
        CLI["CLI: activate_platform.sh"]:::action
        MATLAB["MATLAB/Simulink Toolflow"]:::tool
        Python["Python Runtime"]:::code
    end

    subgraph "Core Libraries & Toolflow"
        FPGA["casperfpga (Python API)"]:::code
        MLIB["mlib_devel (DSP Library)"]:::code
    end

    subgraph "Platform Modules"
        SNAP["snap/"]:::module
        ROACH2["roach2/"]:::module
        SKARAB["skarab/"]:::module
        RED["red_pitaya/"]:::module
        ALVEO["alveo/"]:::module
        RFSOC["rfsoc/"]:::module
    end

    subgraph "FPGA Hardware"
        HW["FPGA Boards"]:::hardware
    end

    subgraph "Documentation Site"
        DOCS["Sphinx Docs (docs/)"]:::docs
    end

    %% Connections
    CLI -->|"select platform"| SNAP
    CLI --> SNAP
    CLI --> ROACH2
    CLI --> SKARAB
    CLI --> RED
    CLI --> ALVEO
    CLI --> RFSOC
    CLI --> Python

    SNAP --> MATLAB
    ROACH2 --> MATLAB
    SKARAB --> MATLAB
    RED --> MATLAB
    ALVEO --> MATLAB
    RFSOC --> MATLAB

    MLIB --> MATLAB
    MATLAB -->|"generates .fpg/.dtbo"| HW

    CLI -->|"run tutorial scripts"| Python
    FPGA --> Python
    Python -->|"Ethernet/PCIe"| HW

    CLI --> DOCS
    DOCS -->|"builds HTML site"| DOCS

    %% Click Events
    click CLI "https://github.com/casper-astro/tutorials_devel/blob/main/./activate_platform.sh"
    click FPGA "https://github.com/casper-astro/tutorials_devel/tree/main/./casperfpga/"
    click MLIB "https://github.com/casper-astro/tutorials_devel/blob/main/.gitmodules"
    click DOCS "https://github.com/casper-astro/tutorials_devel/tree/main/./docs/"
    click SNAP "https://github.com/casper-astro/tutorials_devel/tree/main/./snap/"
    click ROACH2 "https://github.com/casper-astro/tutorials_devel/tree/main/./roach2/"
    click SKARAB "https://github.com/casper-astro/tutorials_devel/tree/main/./skarab/"
    click RED "https://github.com/casper-astro/tutorials_devel/tree/main/./red_pitaya/"
    click ALVEO "https://github.com/casper-astro/tutorials_devel/tree/main/./alveo/"
    click RFSOC "https://github.com/casper-astro/tutorials_devel/tree/main/./rfsoc/"

    %% Styles
    classDef action fill:#f96,stroke:#333,stroke-width:1px
    classDef code fill:#bbf,stroke:#333,stroke-width:1px
    classDef module fill:#bbf,stroke:#333,stroke-width:1px
    classDef tool fill:#cff,stroke:#333,stroke-width:1px
    classDef hardware fill:#9f6,stroke:#333,stroke-width:1px
    classDef docs fill:#ccc,stroke:#333,stroke-width:1px
```
