THD Sweep Measurement
= 💠 THD Sweep Measurement Utility - User Guide
Welcome to the Total Harmonic Distortion (THD) Sweep Utility documentation. This tool is a high-performance bridge between OROS NVGate and real-time THD analysis, specifically optimized for sine sweep measurements.
🚀 Overview
The utility automates the tracking of a moving sine peak (sweep) to compute distortion in real-time. It uses the pynvdrive toolkit to communicate with NVGate, moving markers dynamically and feeding results back into the system via Simulated DC inputs.
💎 Key Features
- Real-Time Tracking: Follows the sweep peak across the frequency spectrum.
- High-Precision THD: Calculates THD using the fundamental + 9 harmonics.
- Live Data Feedback: Pushes results (%, dB, and Frequency) back into NVGate.
- Integrated Diagnostics: One-click verification of the entire measurement chain.
🛠️ NVGate Pre-Requisites
Before running the software, ensure your NVGate project is set up as follows:
- Windows Setup:
- Reference Window (Window2): FFT trace of the source signal (Generator output).
- Response Window (Window1): FFT trace of the tested device (Microphone/Sensor).
- Marker Setup:
- Add a Max Marker in the Reference Window.
- Add a Harmonic Marker in the Response Window.
- DC Inputs:
- Enable Simulated DC Inputs 1, 2, and 3 in the Frontend configuration.
⚙️ Configuration Reference (The "Brain" of the App)
The configuration panel maps the utility's logic to your specific NVGate project. Applying these settings correctly is critical for the tracking to work.
| Field | Technical Role | Detailed Function |
|---|---|---|
| Window Ch4 (Sweep) | Reference Source | The utility looks in this window to find the peak frequency of the sweep. It uses the Max Marker to "identify" where the generator is at any given millisecond. |
| Window Ch1 (Resp) | Analysis Target | This is where the actual THD measurement happens. The tool reads the signal amplitude from this window to calculate distortion relative to the reference frequency. |
| Max Marker # | Frequency Tracker | This marker is the "eyes" of the application. It constantly reports the X-axis (frequency) position of the strongest signal in the Sweep window. |
| Harmonic Marker # | Harmonic Sampler | The utility physically repositions this marker to the frequency found by the Max Marker. Once moved, it reads the Fundamental (H1) and all Harmonics (H2-H10) to compute the THD. |
| Nb Harmonics | Calculation Depth | Defines how many harmonics are summed. Default is 9, meaning the tool analyzes up to the 10th order (Fundamental + 9 harmonics). |
| DC1 IDN (THD %) | Linear Output Bridge | The Instrument Description Name (IDN) is the internal address in NVGate. This setting pushes the calculated THD percentage directly into the first Simulated DC input. |
| DC2 IDN (THD dB) | Logarithmic Bridge | Similar to DC1, but pushes the THD value converted to decibels (dB), allowing you to log or display dB values directly inside NVGate. |
| DC3 IDN (Freq) | Frequency Bridge | Pushes the current tracked frequency (in Hz) to a DC input. This allows NVGate to plot THD versus Frequency in a Cross-Plot or Waterfall. |
💡 Pro Tip: If you change these values, click "Apply Configuration" to update the logic immediately. If a window name is wrong, the Diagnostic will immediately turn RED.
🕹️ Operational Workflow
1️⃣ Connectivity Test
Click the 🔍 DIAGNOSTIC button first.
- It checks if NVGate is open.
- It verifies that the markers exist in the right windows.
- It tests writing to the DC inputs and reads them back to ensure accuracy.
- Result: If the log turns GREEN, you are ready to measure!
2️⃣ Measuring
Click ▶ START.
- The utility sends a Run command to NVGate.
- It stabilizes for 2 seconds (allowing the FFT to populate).
- It begins the loop: Track Peak → Move Harmonics → Calculate THD → Write to DC.
3️⃣ Monitoring
- Purple Card: Live THD in dB (Standard for audio).
- Yellow Card: Live THD in % (Linear scale).
- Teal/Blue Cards: Current tracked Frequency and Fundamental amplitude.
📊 Technical Specifications
Data Mapping
The utility automatically configures NVGate Simulated DC inputs with the following:
- DC 1 (THD %): Magnitude set to Percentage (0.0 to 100.0).
- DC 2 (THD dB): Magnitude set to Ratio (-200.0 to 0.0 dB).
- DC 3 (Frequency): Magnitude set to Frequency (0.0 to 40,000.0 Hz).
THD Formula
The tool uses the standard RMS summation:
THD = sqrt(H2² + H3² + ... + H10²) / H1
Where H1 is the Fundamental and H2-H10 are the Harmonics.
❓ Troubleshooting
- Log is RED?: Check if the Window names in NVGate match exactly (case sensitive) with the names in the Configuration panel.
- "Access Denied" Error: Ensure no other instance of the software is running in the background.
- Values not updating?: Ensure NVGate is in RUN mode and the traces are active.
--- Generated by OROS Gemini CLI - 2026
- Maximum Asynchronous Mode: There is no artificial delay between measurement cycles.
- Latency: A total cycle time (Frequency Read -> Calculation -> DC Write) of < 150ms is recommended.
- Recommended Sweep Speed: 4 octaves/min. This ensures a good balance between measurement speed and tracking accuracy.
- FFT Windowing: Use a Hanning window for the best frequency resolution during a sweep sine.
💻 Development and Compilation
Project Structure
| File | Role |
|---|---|
| thd_gui.py | Graphical user interface (Tkinter) |
| thd_sweep_measurement.py | Core calculation and NVGate communication |
| Toolkit NVdrive/ | pynvdrive library to control NVGate |
Recompiling the Executable
<syntaxhighlight lang="bash"> pyinstaller --onefile --windowed --name "THD_Sweep_Measurement" --add-data "Toolkit NVdrive;Toolkit NVdrive" thd_gui.py </syntaxhighlight>
❓ Troubleshooting
- "Error 4 bytes": Network buffer error handled automatically by a 20ms pause. Check local network load if it persists.
- THD at 0% or --: Ensure the signal is present in Window1 and the Max marker in Window2 detects a valid frequency (> 0 Hz).
- NVGate not connected: Verify that NVGate is running and the "NVDrive" option is enabled in settings.