How naelf/binarycop works
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