Difference between revisions of "THD Sweep Measurement"

From OROS Wiki
Jump to navigation Jump to search
Line 1: Line 1:
== Wiki: THD Sweep Measurement System ==
=== 💠 THD Sweep Measurement Utility - User Guide ==


This software allows for continuous measurement of '''Total Harmonic Distortion (THD)''' during a frequency sweep (sweep sine) with an OROS system.
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.


=== 🚀 Installation & Launch ===
=== 🚀 Overview ===


==== Using the Executable (Recommended) ====
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'''.
# Go to the {{code|dist/}} folder.
# Launch {{code|THD_Sweep_Measurement.exe}}.
''Note: The executable is standalone and contains all dependencies.''


==== Using Python Sources ====
==== 💎 Key Features ====
# Ensure you have Python 3.8+ (32-bit preferred for NVGate compatibility).
* '''Real-Time Tracking''': Follows the sweep peak across the frequency spectrum.
# Launch the script via {{code|Lancer_THD.bat}} or via command line: {{code|python thd_gui.py}}.
* '''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.


=== 🛠 Required NVGate Configuration ===
=== 🛠️ NVGate Pre-Requisites ===


For the software to function correctly, your NVGate project must be configured as follows:
Before running the software, ensure your NVGate project is set up as follows:


# '''FFT Analyzer''':
# '''Windows Setup''':
#* '''Window 1 (Window1)''': Must display the response channel (Microphone).
#* '''Reference Window''' (Window2): FFT trace of the source signal (Generator output).
#* '''Window 2 (Window2)''': Must display the reference channel (Sweep Sine).
#* '''Response Window''' (Window1): FFT trace of the tested device (Microphone/Sensor).
# '''Markers''':
# '''Marker Setup''':
#* The software will automatically create and manage a '''Max''' marker in Window2 and a '''Harmonic''' marker in Window1.
#* Add a '''Max Marker''' in the Reference Window.
# '''Simulated DC Inputs''':
#* Add a '''Harmonic Marker''' in the Response Window.
#* Enable simulated DC inputs in the Front-end.
# '''DC Inputs''':
#* '''DC1''' will receive the THD value in '''%'''.
#* Enable '''Simulated DC Inputs 1, 2, and 3''' in the Frontend configuration.
#* '''DC2''' will receive the THD value in '''dB'''.


=== 📊 Metrological Details ===
=== ⚙️ Configuration Reference (The "Brain" of the App) ===


==== Calculation Formula ====
The configuration panel maps the utility's logic to your specific NVGate project. '''Applying these settings correctly is critical for the tracking to work.'''
The software calculates THD relative to the fundamental ($THD_f$) according to the IEC 61000-4-7 standard:


<math>THD_{\%} = \frac{\sqrt{\sum_{n=2}^{10} H_n^2}}{H_1} \times 100</math>
{| class="wikitable"
|-
! 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.
|}


* '''H1''': Amplitude of the fundamental.
''💡 '''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.''
* '''H2 to H10''': Amplitude of harmonics (the software tracks the first 9 harmonics by default).
 
=== 🕹️ 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:
<pre>
THD = sqrt(H2² + H3² + ... + H10²) / H1
</pre>
''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''


==== Precision and Latency ====
* '''Maximum Asynchronous Mode''': There is no artificial delay between measurement cycles.
* '''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.
* '''Latency''': A total cycle time (Frequency Read -> Calculation -> DC Write) of < 150ms is recommended.

Revision as of 11:55, 15 April 2026

= 💠 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:

  1. Windows Setup:
    • Reference Window (Window2): FFT trace of the source signal (Generator output).
    • Response Window (Window1): FFT trace of the tested device (Microphone/Sensor).
  2. Marker Setup:
    • Add a Max Marker in the Reference Window.
    • Add a Harmonic Marker in the Response Window.
  3. 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.
Retrieved from "https://wiki.oros.com/index.php?title=THD_Sweep_Measurement&oldid=12710"