How mazinlab/mkidgen3 works
To accurately capture the architecture of MKIDGen3 and guide your diagramming effort, follow these tailored steps.
Project type and purpose
• This is a mixed embedded-hardware and Python software system for RF-multiplexed MKID readout.
• It comprises:
• A host-side Python “client” (CLI, Jupyter notebooks, plotting)
• A networked Python “server” running on a PYNQ-Linux RFSoC board
• FPGA gateware/HLS overlay (built separately in gen3-vivado-top)
• Physical RFSoC hardware (DAC/ADC/PLL), an IF board, and external test equipment
File structure
• Top-level directories:
• firmware/ – Vivado/HLS gateware (external repo)
• mkidgen3/ – Python package: drivers, server, client utilities, config loaders, plotting
• scripts/ – helper scripts for array setup, sweeps, testing
• notebooks/– Jupyter notebooks driving experiment flows
• arduino/ – C++ libraries (ArduinoJson, OneWire, SdFat) for IF-board microcontrollers
• config/ – udev rules, hardware config files
• Key config/build files: pyproject.toml, README.md, mkidgen3/config/*.yaml/.txt
README for insights
• Emphasizes a Python client/server model over Ethernet to the RFSoC board
• Relies on PYNQ environment, patched xrfdc driver, and bitstream built in a separate repo
• Installation groups: [client, plotting] on host; [server, plotting] on the board
Main components and their interactions
a. Host-side components:
• CLI & Jupyter notebooks (scripts in notebooks/, mkidgen3.plotting)
• mkidgen3.client modules (e.g., feedline_client.py)
• Configuration files (mkidgen3/config/*.yaml)
b. Network layer:
• TCP/ZeroMQ or simple socket RPC between feedline_client and feedline_server
c. Board-side Python server:
• mkidgen3.server package: feedline_server, aggregator, captures, fpga_objects
• Uses overlay_helpers to load the FPGA bitstream and map AXI-registers/fifos
d. Driver abstraction layer:
• mkidgen3.drivers: Python wrappers around hardware blocks (axi-fifo, dactable, ddc, etc.)
• mkidgen3.equipment_drivers: instrument control (e.g., Anritsu signal source)
e. FPGA overlay & gateware:
• Vivado-built HLS/RTL IP blocks (in firmware repo) providing DDC, FFT, phase match, etc.
• Exposed via PYNQ overlay into Python through FPGAObjects
f. Physical hardware:
• RFSoC ZCU111 (DAC → mixers → IF board → detectors → ADC back into FPGA)
• External instruments controlled via Ethernet or serial
Architectural patterns & design principles
• Client–server separation: clear host vs. board responsibilities
• Layered hardware abstraction: drivers hide register-level details
• Modular design: each driver or server piece is a standalone Python module
• Configuration-driven: YAML/TXT files drive register values and sweep parameters