Real-Time Dual-Channel Multi-Regime Oscilloscope, Audio Spectrum Analyzer & Hardware Filter Engine

A high-performance, dark-mode real-time Dual-Channel Multi-Regime Oscilloscope, Audio Spectrum Analyzer, Acoustic Analytics Engine, and Hardware-Accelerated Frequency Filter / IFFT Instrument running natively on PYNQ Linux platforms.

Features true simultaneous dual-ADC parallel sampling ($0.00,\mu\text{s}$ inter-channel skew), runtime-selectable operating regimes (Wideband Lab Scope, Full Audio, Speech, Deep Bass Zoom), FPGA-accelerated anti-aliasing decimation ($M \in {1, 10, 20, 50}$), wideband $10,\text{Hz} - 1,\text{MHz}$ signal generation with interactive Nyquist folding/aliasing exploration, sub-sample trigger phase-locking, dedicated passive microphone instruments (AudioDashboard), Hilbert analytic envelopes, STFT waterfall spectrograms, real-time frequency-domain spectral filtering (HardwareFilter) with Hermitian symmetry ($k_{\text{eff}} = \min(k, N-k)$), calibrated 1:1 hardware IFFT reconstruction ($V_{\text{pp, filt}} \approx V_{\text{pp, raw}}$ with $< 1%$ error), and direct in-Jupyter audio playback (ol.play_audio()).

🏛 System Architecture

This repository adopts the canonical PYNQ Custom Overlay pattern (OscilloscopeOverlay). It automatically pulls its compiled hardware bitstream and metadata from GitHub Releases (or loads local custom .bit builds) and encapsulates the 3-DMA stream receivers, AXI-Lite trigger registers, sequencer controls, dynamic decimators, spectral masking registers, and dual-wavegen into a unified Python object.

 [ Analog Discovery 3 ] ──(W1: Yellow)──────> [ PYNQ-Z2 Pin A0 (Vaux1) ]
 [      Wavegen       ] ──(W2: Yellow/White)─> [ PYNQ-Z2 Pin A1 (Vaux9) ]
 [         OR         ]                                       │
 [ MAX4466 Mics A0/A1 ]                       (XADC Dual Continuous Sequencer)
        │                                                     │ (1 MSPS Interleaved Stream, 0.00 µs Skew)
  (pydwf SDK)                                                 ▼
        │                                            [ axis_trigger_unit IP ]
        ▼                                      (Selectable Trigger Source: A0 / A1)
 [ AD3SignalGenerator ]                                       │ (Gated Stream)
 (Concurrent W1 & W2)                                         ▼
                                                     [ axis_decimator IP ]
                                           (Programmable M = 1, 10, 20, 50 in PL)
                                                              │ (Decimated Stream)
                                                              ▼
                                                     [ tlast_generator (Programmable N) ]
                                                              │ (w/ TLAST)
                                                    [ axis_broadcaster_0 ]
                                               ┌──────────────┴──────────────┐
                                               ▼ (Decimated Time Stream)     ▼ (Interleaved Stream w/ TLAST)
                                      [ AXI DMA 0 (Time) ]          [ axis_channel_demux ]
                                               │                             │ (Clean A0 vs A1 Routing)
                                               │                             ▼
                                               │                    [ xfft_0 Core (Forward FFT) ]
                                               │                             │ (Complex Re + j*Im)
                                               │                             ▼
                                               │                    [ axis_spectral_mask ]
                                               │                    (Hermitian Masking: k_eff = min(k, N-k))
                                               │                             │
                                               │                    [ axis_broadcaster_1 ]
                                               │                       ┌─────┴─────┐
                                               │                       ▼           ▼
                                               │                  [ cordic_0 ] [ xfft_1 (IFFT) ]
                                               │                  (Mag Engine) (Filtered Time)
                                               │                       │           │
                                               ▼                       ▼           ▼
                                      [ AXI DMA 0 (Time) ]    [ AXI DMA 1 ]  [ AXI DMA 2 ]
                                               │                       │           │
                                               └───────────────────────┼───────────┘
                                                                       ▼ (AXI SmartConnect HP0)
                                                            [ Processing System DDR ]

🎛 Multi-Regime Operating Profiles

The system seamlessly reconfigures sampling rate, packet duration, and FFT resolution on the fly via ol.set_profile():

🖥 4-Tier Interactive Instrument Suite

1. Real-Time Hardware Filter & IFFT Dashboard (ol.filter_dashboard())

Live 4-trace multi-domain instrument providing real-time hardware frequency filtering and IFFT reconstruction directly on the FPGA fabric:

• Interactive Frequency Cutoff Sliders: Real-time Lowpass, Highpass, Bandpass, and Notch cutoff tuning.
• Quick Presets: Instant configuration for Sub-Bass ($20-120,\text{Hz}$), Full Bass ($20-250,\text{Hz}$), Vocals ($300-3.4,\text{kHz}$), Highpass ($>1,\text{kHz}$), and $60,\text{Hz}$ Mains Hum Notch.
• Hermitian Symmetry ($k_{\text{eff}} = \min(k, N-k)$): Eliminates complex leakage and ensures $< 1%$ amplitude reconstruction error ($0.08%$).

Quad Filter View (Raw, IFFT & Masked Spectrum)	Time Domain Superimposed Overlay

2. Academic Laboratory Dual Scope & Aliasing Explorer (ol.ad3_dashboard())

Full-featured oscilloscope with live Analog Discovery 3 signal generation ($10,\text{Hz} - 1,\text{MHz}$) and $250,\text{kHz}$ Nyquist span. Allows students to dial beyond $250,\text{kHz}$ ($300,\text{kHz}, 450,\text{kHz}, 800,\text{kHz}$) to observe real-time spectral folding/aliasing.

Dual Time-Domain Scope (A0 & A1)	Dual FFT Spectrum Analyzer (0 to 250 kHz)

Dedicated Channel 1 View (A0)	Dedicated Channel 2 View (A1)

3. Dedicated Microphone & Audio Instrument (ol.audio_dashboard())

Designed specifically for passive MAX4466 electret microphones (or any analog audio sensor on pins A0 and A1), running completely independently without requiring an Analog Discovery 3:

• $20.48,\text{ms} - 102.4,\text{ms}$ Audio Timebase: Displays multi-cycle acoustic waveforms for speech, musical instruments, and bass frequencies ($20,\text{Hz} - 250,\text{Hz}$).
• Live VU Meters & Clipping Alerts: Status bar indicators that flash red if either microphone saturates ($V < 0.10,\text{V}$ or $V > 3.10,\text{V}$).
• Sub-Bin Quadratic Peak Pitch Tracking: Extracts the dominant acoustic fundamental ($f_0$) with $\pm 0.5,\text{Hz}$ accuracy.

Dual Audio Waveforms (Mic 1 & Mic 2)	Dual Audio Spectrum (0 to 25 kHz)

4. Multi-Domain Acoustic Analytics & Spectrogram Engine (ol.analytic_dashboard())

Advanced diagnostic instrument providing instantaneous mathematical decomposition of stereo sound fields:

• 3-Strip Stacked Amplitude: Instantaneous physical Hilbert analytic envelopes ($A(t) = \sqrt{x^2 + \hat{x}^2}$) and Inter-aural Level Differences ($\Delta L(t)$ in dB).
• Rolling STFT Waterfall Spectrogram: 2D time-frequency heatmaps with Blackman-Harris windowing.
• Continuous Phase Tracking ($\Delta \phi(t)$): Instantaneous inter-channel phase alignment enabled by true simultaneous dual-ADC sampling ($0.00,\mu\text{s}$ skew).

3-Strip Stacked Amplitude & ILD Balance	STFT Waterfall Spectrogram & Phase Tracking

🔌 Hardware Setup & Wiring

Option A: Dual MAX4466 Microphones (Acoustic Audio Mode)

Option B: Analog Discovery 3 (Signal Generator Mode)

Note: Connect the AD3 USB cable to the large rectangular USB HOST port on the PYNQ-Z2 board. Use an external 5V auxiliary power supply for the AD3 to ensure voltage rail stability under dual-channel generation.

🚀 Quick Start & Installation

1. Install Package from PyPI

pip install --upgrade pynq-oscilloscope

2. Copy Example Notebooks to Jupyter Workspace

pynq-oscilloscope-get-notebooks

3. Install Digilent AD3 Drivers (One-Time Setup for Wavegen)

from pynq_oscilloscope import install_ad3_drivers
install_ad3_drivers()

💻 Python API Usage

1. Real-Time Hardware Filtering & Capture

from pynq_oscilloscope import check_usb_permissions, OscilloscopeOverlay

check_usb_permissions()

# Load hardware overlay (auto-fetches v1.6.0 bitstream)
ol = OscilloscopeOverlay()
ol.set_profile("audio")

# Engage hardware Lowpass filter at 250 Hz
ol.filter.set_lowpass(cutoff_hz=250.0)

# Capture Raw Time (DMA 0), Filtered Time (DMA 2), and FFT Spectrum (DMA 1) in <2 ms
v_a0, v_a1, v_filt, freqs, mags = ol.capture_all()

2. Jupyter Audio Playback & Multi-Second Recording

# Record and listen to raw vs. FPGA-filtered audio directly in Jupyter Notebook
ol.set_profile("audio")

# 1. Listen to raw input
ol.play_audio(duration_sec=3.0, filtered=False)

# 2. Listen to real-time FPGA-filtered bass
ol.play_audio(duration_sec=3.0, filtered=True)

3. Launch Interactive Dashboards

# Launch 4-Trace Hardware Filter Dashboard:
app = ol.filter_dashboard()

# Launch Academic Lab Scope & AD3 Aliasing Explorer:
app = ol.ad3_dashboard()

# Launch dedicated passive Microphone Instrument:
app = ol.audio_dashboard()

# Launch Multi-Domain Acoustic Analytics Engine:
app = ol.analytic_dashboard()

📓 7-Notebook Progressive Curriculum

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.