# naelf/binarycop architecture

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

- Interactive diagram: https://gitdiagram.com/naelf/binarycop
- Repository: https://github.com/naelf/binarycop

## Overview

##### Project type and purpose
- BinaryCoP is a hardware-software co-design for on-edge binary neural network inference.
- It combines a Jupyter-based prototype (notebook), Python driver layers (FINN core & utils), FPGA bitstream hardware (PYNQ overlay), and auxiliary scripts (Grad-CAM interpretability, DSP bit-packing).
- Purpose: classify mask-wear & positioning on low-power PYNQ boards, with all processing on the device to preserve privacy.

##### File structure
- Top level: README, docs/, notebook/, utils/.
- notebook/ contains:
– BinaryCoP_Demo.ipynb (UI entry point)
– driver.py & driver_base.py (runtime drivers)
– finn/core & finn/util (FINN framework submodules for onnx_exec, remote_exec, rtlsim_exec, data layout & packing, Vivado integration)
– resizer.bit/.hwh (FPGA overlay files)
- utils/ contains two independent tools:
– bnn_interpretability (Grad-CAM script)
– mvtu_dsp_bitpacking (VHDL module + Python script for DSP-based bit-packing)
- docs/ holds design report & slides; notebook/input.npy is a sample input dataset.

##### Extract architecture hints from the README
- Execution flow: Notebook → FINN driver → (a) software ONNX execution or (b) remote FPGA execution via PYNQ overlay → classification result.
- Dependencies: PYNQ-Z1 board, Vivado for bitstream synthesis.
- Goal: end-to-end edge inference pipeline, with optional external utilities for model interpretability and hardware optimizations.

1. User Interface (Jupyter Notebook)
2. Python Runtime Layer
- driver_base.py & driver.py
- FINN Core (onnx_exec, remote_exec, rtlsim_exec)
- FINN Util (data_packing, vivado, config)
3. FPGA Accelerator (PYNQ Overlay)
- resizer.bit/.hwh
- DMA interfaces on PL
4. Host CPU Execution Path (for software fallback via onnx_exec)
- Grad-CAM interpreter (utils/bnn_interpretability)
- DSP-BitPacking script & VHDL module (utils/mvtu_dsp_bitpacking)
- Notebook → invokes → Python Runtime Layer
- Runtime Layer →
– branches → onnx_exec → CPU → outputs label
– or → remote_exec → PYNQ PL (over resizer overlay) → outputs label
- Runtime Layer → can invoke → Vivado via finn/util/vivado for bitstream generation (development path, not runtime)
- Notebook (or a separate CLI) → calls → Grad-CAM tool (reads model & input data → writes heatmap)
- Development flow: DSP-BitPacking script → generates modified VHDL → integrate into Vivado project
c. Architectural patterns & principles:
- Modular layering: UI / runtime / hardware / external utilities
- Pipeline pattern: input acquisition → preprocessing → BNN inference → result output
- Hardware-software co-design: interchangeable software/FPGA backends using the same runtime interface
d. Key technologies & frameworks:
- Jupyter Notebook
- Python + FINN framework (ONNX)
- PYNQ-Z1 FPGA (Overlay .bit/.hwh)
- Vivado 2018.1 (HDL synthesis)
- VHDL DSP48E1 modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Software Layer
    subgraph "User Interface" 
        Notebook["Jupyter Notebook\n(BinaryCoP_Demo.ipynb)"]:::software
    end

    subgraph "Python Runtime Layer"
        subgraph Drivers
            DriverBase["driver_base.py"]:::software
            Driver["driver.py"]:::software
        end
        subgraph "FINN Core"
            Onnx["onnx_exec.py"]:::software
            Remote["remote_exec.py"]:::software
            RTLSim["rtlsim_exec.py"]:::software
        end
        subgraph "FINN Utils"
            DataPack["data_packing.py"]:::software
            Vivado["vivado.py"]:::software
        end
    end

    subgraph "Software Path (CPU)"
        CPU["Host CPU"]:::software
    end

    subgraph "Hardware Layer"
        FPGAOverlay["PYNQ Overlay\n(resizer.bit/.hwh)"]:::hardware
        PL["FPGA PL (DMA interfaces)"]:::hardware
    end

    subgraph "External Tools (Offline)"
        GradCAM["Grad-CAM Interpreter\ngcam.py"]:::offline
        DSP["DSP BitPacking\n(VHDL & Python)"]:::offline
    end

    %% Connections
    Notebook -->|"invoke"| Driver
    DriverBase --> Driver
    Driver -->|branch: onnx_exec| Onnx
    Driver -->|branch: remote_exec| Remote
    Onnx -->|inference| CPU
    Remote -->|load bitstream & DMA| FPGAOverlay
    FPGAOverlay -->|process data| PL
    Vivado -->|synthesize bitstream| FPGAOverlay
    Notebook -->|calls| GradCAM
    DSP -->|generates VHDL| Vivado

    %% Click Events
    click Notebook "https://github.com/naelf/binarycop/blob/master/notebook/BinaryCoP_Demo.ipynb"
    click DriverBase "https://github.com/naelf/binarycop/blob/master/notebook/driver_base.py"
    click Driver "https://github.com/naelf/binarycop/blob/master/notebook/driver.py"
    click Onnx "https://github.com/naelf/binarycop/blob/master/notebook/finn/core/onnx_exec.py"
    click Remote "https://github.com/naelf/binarycop/blob/master/notebook/finn/core/remote_exec.py"
    click RTLSim "https://github.com/naelf/binarycop/blob/master/notebook/finn/core/rtlsim_exec.py"
    click DataPack "https://github.com/naelf/binarycop/blob/master/notebook/finn/util/data_packing.py"
    click Vivado "https://github.com/naelf/binarycop/blob/master/notebook/finn/util/vivado.py"
    click FPGAOverlay "https://github.com/naelf/binarycop/blob/master/notebook/resizer.bit"
    click GradCAM "https://github.com/naelf/binarycop/blob/master/utils/bnn_interpretability/gcam.py"
    click DSP "https://github.com/naelf/binarycop/blob/master/utils/mvtu_dsp_bitpacking/DSP48E1_MOD.vhd"

    %% Styles
    classDef software fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef hardware fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef offline fill:#e0e0e0,stroke:#424242,color:#424242;
```
