Difference between revisions of "THD Sweep Measurement"

From OROS Wiki
Jump to navigation Jump to search
Line 1: Line 1:
== 💠 THD Sweep Measurement Utility - User Guide ==
== THD SWEEP MEASUREMENT - USER GUIDE ==
''Master the art of measuring Total Harmonic Distortion with style''


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.
__TOC__


=== 🚀 Overview ===
{| style="width:100%; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 30px; border-radius: 10px; margin: 20px 0; text-align: center;"
|-
| style="font-size: 2.5em; font-weight: bold;" | 🎵 THD SWEEP MEASUREMENT
|-
| style="font-size: 1.2em; opacity: 0.95;" | Professional Acoustic Testing Made Simple
|}
 
---
 
== ⚡ QUICK START - 30 SECONDS ==
 
{| style="width: 100%; border-collapse: collapse; margin: 20px 0;"
|-
| style="background: #f0f4ff; padding: 20px; border-left: 5px solid #667eea; font-weight: bold; width: 50%;" | STEP
| style="background: #f0f4ff; padding: 20px; border-left: 5px solid #667eea; font-weight: bold; width: 50%;" | ACTION
|-
| style="padding: 15px; background: #fafbff;" | 1️⃣ Launch
| style="padding: 15px; background: #fafbff;" | Double-click <code>Lancer_THD.bat</code>
|-
| style="padding: 15px; background: white;" | 2️⃣ Connect
| style="padding: 15px; background: white;" | Check top right: <span style="color: green; font-weight: bold;">● Connected</span>
|-
| style="padding: 15px; background: #fafbff;" | 3️⃣ Start
| style="padding: 15px; background: #fafbff;" | Click green <code>▶ START</code> button
|-
| style="padding: 15px; background: white;" | 4️⃣ Monitor
| style="padding: 15px; background: white;" | Watch 4 metrics update live
|-
| style="padding: 15px; background: #fafbff;" | 5️⃣ Stop
| style="padding: 15px; background: #fafbff;" | Click red <code>■ STOP</code> button
|}


The utility automates the tracking of a moving sine peak (sweep) to compute distortion THD in real-time.
<div style="background: #e8f5e9; border-left: 5px solid #4caf50; padding: 20px; margin: 20px 0; border-radius: 5px;">
✅ '''That's it!''' Your first THD measurement is complete. You're now a certified acoustic engineer. (Not really, but it feels good.)
</div>


==== 💎 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 ===
== 👀 YOUR INTERFACE - WHAT YOU SEE ==


Before running the software, ensure your NVGate project is set up as follows:
=== 🟢 Status Indicators (Top Right) ===


# '''Windows Setup''':
{| style="width: 100%; margin: 15px 0; border-collapse: collapse;"
#* '''Reference Window''' (Window2): FFT trace of the source signal (Generator output).
|-
#* '''Response Window''' (Window1): FFT trace of the tested device (Microphone/Sensor).
| style="width: 50%; background: #e8f5e9; padding: 15px; border: 1px solid #c8e6c9; font-weight: bold;" | INDICATOR
# '''Marker Setup''':
| style="width: 50%; background: #e8f5e9; padding: 15px; border: 1px solid #c8e6c9; font-weight: bold;" | MEANING
#* Add a '''Max Marker''' in the Reference Window.
|-
#* Add a '''Harmonic Marker''' in the Response Window.
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | <span style="color: green; font-size: 1.2em;">●</span> NVGate Connected
# '''DC Inputs''':
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | Perfect! NVGate is ready to rock 🎸
#* Enable '''Simulated DC Inputs 1, 2, and 3''' in the Frontend configuration.
|-
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | <span style="color: red; font-size: 1.2em;">●</span> NVGate Disconnected
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | Oops! Start NVGate first 🤔
|-
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | <span style="color: green; font-size: 1.2em;">●</span> Measurement Running
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | Data is flowing! 📊
|-
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | <span style="color: #999; font-size: 1.2em;">●</span> Measurement Stopped
| style="padding: 12px; background: white; border: 1px solid #c8e6c9;" | Ready for the next round ⏸️
|}


=== ⚙️ Configuration Reference (The "Brain" of the App) ===
=== 📊 Four Metric Cards ===


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 heart of the interface. These four numbers tell the whole story:


{| class="wikitable"
{| style="width: 100%; margin: 20px 0; border-collapse: collapse;"
|-
|-
! Field !! Technical Role !! Detailed Function
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 25px; text-align: center; font-weight: bold; width: 25%; border: none;" | 📈<br/>THD (dB)
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 25px; text-align: center; font-weight: bold; width: 25%; border: none;" | 📊<br/>THD (%)
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 25px; text-align: center; font-weight: bold; width: 25%; border: none;" | 📡<br/>Frequency
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 25px; text-align: center; font-weight: bold; width: 25%; border: none;" | ⚡<br/>Fundamental
|-
|-
| '''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.
| style="background: #f5f5f5; padding: 20px; text-align: center; border: 1px solid #ddd;" | Harmonic distortion (log scale)
| style="background: #f5f5f5; padding: 20px; text-align: center; border: 1px solid #ddd;" | Harmonic distortion (%)
| style="background: #f5f5f5; padding: 20px; text-align: center; border: 1px solid #ddd;" | Current sweep point
| style="background: #f5f5f5; padding: 20px; text-align: center; border: 1px solid #ddd;" | Signal strength
|-
|-
| '''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.
| style="background: white; padding: 20px; text-align: center; border: 1px solid #ddd; font-family: monospace; font-weight: bold; color: #667eea;" | +5.42 dB
| style="background: white; padding: 20px; text-align: center; border: 1px solid #ddd; font-family: monospace; font-weight: bold; color: #667eea;" | 58.294 %
| style="background: white; padding: 20px; text-align: center; border: 1px solid #ddd; font-family: monospace; font-weight: bold; color: #667eea;" | 1234.56 Hz
| style="background: white; padding: 20px; text-align: center; border: 1px solid #ddd; font-family: monospace; font-weight: bold; color: #667eea;" | 5.0e-01 V
|}
 
=== 💬 Log Console (Bottom) ===
 
Real-time messages with color coding:
 
{| style="width: 100%; border-collapse: collapse; margin: 15px 0;"
|-
| style="width: 20%; background: #e8f5e9; padding: 10px; font-weight: bold;" | 🟢 GREEN
| style="width: 80%; background: #e8f5e9; padding: 10px;" | Everything OK - measurement working perfectly
|-
|-
| '''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.
| style="width: 20%; background: #ffebee; padding: 10px; font-weight: bold;" | 🔴 RED
| style="width: 80%; background: #ffebee; padding: 10px;" | Error occurred - something needs attention
|-
|-
| '''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.
| style="width: 20%; background: #e3f2fd; padding: 10px; font-weight: bold;" | 🔵 BLUE
| style="width: 80%; background: #e3f2fd; padding: 10px;" | Information - status updates and details
|}
 
---
 
== 🎯 UNDERSTANDING YOUR RESULTS ==
 
=== THD (%) - The Easy Number ===
 
<div style="background: linear-gradient(135deg, #c8e6c9, #a5d6a7); padding: 25px; border-radius: 10px; margin: 20px 0; color: #1b5e20;">
 
'''What is it?''' Percentage of unwanted harmonics in your signal.
 
Think of it this way:
* THD 5% = 95% pure signal, 5% noise
* THD 20% = 80% pure signal, 20% noise
 
'''The Quality Scale:'''
 
{| style="width: 100%; background: white; border-collapse: collapse; margin-top: 15px;"
|-
| style="padding: 12px; background: #fff3e0; border: 1px solid #ffe0b2; font-weight: bold;" | 🌟 1% - 5%
| style="padding: 12px; background: #fff3e0; border: 1px solid #ffe0b2;" | Excellent - Professional grade equipment
|-
| style="padding: 12px; background: #e8f5e9; border: 1px solid #c8e6c9; font-weight: bold;" | ✅ 5% - 15%
| style="padding: 12px; background: #e8f5e9; border: 1px solid #c8e6c9;" | Good - Solid speaker performance
|-
| style="padding: 12px; background: #fff9c4; border: 1px solid #fff59d; font-weight: bold;" | ⚠️ 15% - 30%
| style="padding: 12px; background: #fff9c4; border: 1px solid #fff59d;" | Acceptable - Consumer level equipment
|-
| style="padding: 12px; background: #ffebee; border: 1px solid #ffcdd2; font-weight: bold;" | ❌ > 30%
| style="padding: 12px; background: #ffebee; border: 1px solid #ffcdd2;" | Poor - Time for an upgrade 🛠️
|}
 
</div>
 
=== THD (dB) - The Technical Number ===
 
<div style="background: linear-gradient(135deg, #bbdefb, #90caf9); padding: 25px; border-radius: 10px; margin: 20px 0; color: #0d47a1;">
 
Same measurement as THD (%) but in decibels (logarithmic scale).
 
'''Quick Conversion Chart:'''
 
{| style="width: 100%; background: white; border-collapse: collapse; margin-top: 15px;"
|-
| style="padding: 12px; background: #f5f5f5; border: 1px solid #e0e0e0; font-weight: bold; text-align: center;" | THD %
| style="padding: 12px; background: #f5f5f5; border: 1px solid #e0e0e0; font-weight: bold; text-align: center;" | THD dB
| style="padding: 12px; background: #f5f5f5; border: 1px solid #e0e0e0; font-weight: bold; text-align: center;" | Quality
|-
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | 1%
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center; font-family: monospace;" | -40 dB
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | 🌟 Perfect
|-
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | 3%
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center; font-family: monospace;" | -30 dB
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | ✅ Great
|-
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | 10%
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center; font-family: monospace;" | -20 dB
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | ✅ Good
|-
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | 30%
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center; font-family: monospace;" | -10 dB
| style="padding: 12px; border: 1px solid #e0e0e0; text-align: center;" | ⚠️ Poor
|}
 
</div>
 
---
 
== 📋 TYPICAL MEASUREMENT WORKFLOW ==
 
=== Pre-Measurement Checklist ===
 
<div style="background: #fff3e0; border-left: 5px solid #ff9800; padding: 20px; margin: 20px 0; border-radius: 5px;">
Before you start, verify:
* ✓ NVGate is open and ready
* ✓ Sweep is configured (e.g., 10 Hz → 20 kHz)
* ✓ FFT traces are visible on screen
* ✓ Sine generator is active
* ✓ Speaker is connected and working
</div>
 
=== Step-by-Step Workflow ===
 
{| style="width: 100%; border-collapse: collapse; margin: 20px 0; background: white;"
|-
| style="background: #667eea; color: white; padding: 15px; font-weight: bold; width: 5%; text-align: center;" |
| style="background: #667eea; color: white; padding: 15px; font-weight: bold; width: 25%;" | PHASE
| style="background: #667eea; color: white; padding: 15px; font-weight: bold; width: 70%;" | WHAT TO DO
|-
| style="background: #f5f5f5; padding: 15px; text-align: center; font-size: 2em;" | 1️⃣
| style="background: #f5f5f5; padding: 15px; font-weight: bold;" | Prepare
| style="background: #f5f5f5; padding: 15px;" | Open NVGate → Set sweep → Verify FFT visible
|-
| style="background: white; padding: 15px; text-align: center; font-size: 2em;" | 2️⃣
| style="background: white; padding: 15px; font-weight: bold;" | Launch App
| style="background: white; padding: 15px;" | Double-click Lancer_THD.bat → Check Connected status
|-
| style="background: #f5f5f5; padding: 15px; text-align: center; font-size: 2em;" | 3️⃣
| style="background: #f5f5f5; padding: 15px; font-weight: bold;" | Start
| style="background: #f5f5f5; padding: 15px;" | Click ▶ START → Watch log for "Starting THD Measurement"
|-
| style="background: white; padding: 15px; text-align: center; font-size: 2em;" | 4️⃣
| style="background: white; padding: 15px; font-weight: bold;" | Monitor
| style="background: white; padding: 15px;" | Watch metrics update → Frequency should increase → THD should be stable
|-
| style="background: #f5f5f5; padding: 15px; text-align: center; font-size: 2em;" | 5️⃣
| style="background: #f5f5f5; padding: 15px; font-weight: bold;" | Stop
| style="background: #f5f5f5; padding: 15px;" | Click ■ STOP → Watch for "Measurement ended" → Note final values
|}
 
---
 
== ⚙️ CONFIGURATION ==
 
=== When Do I Need to Change This? ===
 
<div style="background: #e3f2fd; border-left: 5px solid #2196f3; padding: 20px; margin: 20px 0; border-radius: 5px;">
 
'''Honest answer: Almost never.'''
 
The default settings work for 95% of users. Only change if your NVGate project has:
* Different window names
* Different marker numbers
* Different DC input addresses
 
If you're not sure → Don't change anything. It works. Trust it.
 
</div>
 
=== How to Access Configuration ===
 
Click on '''▶ Configuration''' (section expands)
 
=== Important Settings ===
 
{| style="width: 100%; border-collapse: collapse; margin: 15px 0;"
|-
|-
| '''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).
| style="background: #667eea; color: white; padding: 12px; font-weight: bold; width: 30%;" | Setting
| style="background: #667eea; color: white; padding: 12px; font-weight: bold; width: 25%;" | Default
| style="background: #667eea; color: white; padding: 12px; font-weight: bold; width: 45%;" | When to Change
|-
|-
| '''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.
| style="padding: 12px; background: #f5f5f5; border: 1px solid #ddd;" | Window (sweep)
| style="padding: 12px; background: #f5f5f5; border: 1px solid #ddd; font-family: monospace;" | Window2
| style="padding: 12px; background: #f5f5f5; border: 1px solid #ddd;" | Your sweep FFT has different name
|-
|-
| '''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.
| style="padding: 12px; border: 1px solid #ddd;" | Window (response)
| style="padding: 12px; border: 1px solid #ddd; font-family: monospace;" | Window1
| style="padding: 12px; border: 1px solid #ddd;" | Your response FFT has different name
|-
|-
| '''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.
| style="padding: 12px; background: #f5f5f5; border: 1px solid #ddd;" | Number of harmonics
| style="padding: 12px; background: #f5f5f5; border: 1px solid #ddd; font-family: monospace;" | 9
| style="padding: 12px; background: #f5f5f5; border: 1px solid #ddd;" | 5 (faster), 15 (more detailed)
|}
|}


''💡 '''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.''
=== How to Apply Changes ===
 
# Modify field value
# Click '''Apply Configuration'''
# Log displays "Configuration applied" ✓
# Done!
 
---
 
== 🔧 TROUBLESHOOTING ==
 
=== Issue 1: NVGate Shows "Disconnected" ===
 
<div style="background: #ffebee; border-left: 5px solid #d32f2f; padding: 20px; margin: 15px 0; border-radius: 5px;">
 
'''What it means:''' Application can't reach NVGate
 
'''Solutions (in order):'''
# Is NVGate actually open? Check your screen.
# Restart NVGate
# Restart the THD application
# Check Windows firewall allows localhost connections
# Call your IT department and cry
 
'''Reality check:''' 99% of the time NVGate just wasn't open. No shame, happens to everyone.
 
</div>
 
=== Issue 2: Measurement Won't Start ===
 
<div style="background: #fff3e0; border-left: 5px solid #f57c00; padding: 20px; margin: 15px 0; border-radius: 5px;">
 
'''What it means:''' Something blocking the measurement
 
'''Solutions:'''
# Click '''Run Diagnostic''' - it will tell you exactly what's wrong
# Common causes:
#* No sweep configured in NVGate
#* Markers not properly created
#* Wrong window names in configuration
 
The diagnostic is your friend. Use it!
 
</div>
 
=== Issue 3: THD Values Show "--.-" (dashes) ===
 
<div style="background: #e8f5e9; border-left: 5px solid #388e3c; padding: 20px; margin: 15px 0; border-radius: 5px;">


=== 🕹️ Operational Workflow ===
'''What it means:''' No data is being read from harmonics


==== 1️⃣ Connectivity Test ====
'''Check these:'''
Click the '''🔍 DIAGNOSTIC''' button first.
# Are FFT traces actually visible in NVGate? (Most common issue)
* It checks if NVGate is open.
# Is the sweep running?
* It verifies that the markers exist in the right windows.
# Is there audio output to your speaker?
* It tests writing to the DC inputs and reads them back to ensure accuracy.
# Are markers properly set up?
* '''Result''': If the log turns '''GREEN''', you are ready to measure!


==== 2️⃣ Measuring ====
Fix one of these and you're golden!
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 ====
</div>
* '''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 ===
=== Issue 4: STOP Button Doesn't Work ===


==== Data Mapping ====
<div style="background: #f3e5f5; border-left: 5px solid #7b1fa2; padding: 20px; margin: 15px 0; border-radius: 5px;">
The utility automatically configures NVGate Simulated DC inputs with the following:


* '''DC 1 (THD %)''': Magnitude set to ''Percentage'' (0.0 to 100.0).
'''What it means:''' Measurement is shutting down but taking its time
* '''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 ====
'''Solution:''' Wait 5 seconds. Seriously. The app is cleaning up.
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 ===
If it still doesn't respond after 30 seconds:
# Close the window
# Restart the application
# Continue with life


* '''Log is RED?''': Check if the Window names in NVGate match exactly (case sensitive) with the names in the Configuration panel.
</div>
* '''"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.
== 💡 PRO TIPS ==
* '''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 ===
{| style="width: 100%; background: linear-gradient(135deg, #fff9c4, #fffde7); padding: 20px; border-radius: 10px; margin: 20px 0; border: 2px solid #fbc02d;"
|-
| '''Tip 1: Start Simple'''
Always use default settings first. Change things later if needed.


==== Project Structure ====
'''Tip 2: Read the Log'''
{| class="wikitable"
The log console tells you everything. It's your best friend.
! File !! Role
 
'''Tip 3: Use Diagnostic'''
When something's wrong, click "Run Diagnostic". It's like magic.
 
'''Tip 4: Multiple Measurements'''
One measurement is interesting. Five measurements is scientific.
 
'''Tip 5: Document Results'''
Take a screenshot or copy the final THD values. You'll forget otherwise.
|}
 
---
 
== ❓ FREQUENTLY ASKED QUESTIONS ==
 
=== Q: Is THD 5% good? ===
 
'''A:''' For a speaker? Excellent! You can be proud of that equipment. 🎉
 
=== Q: Why does THD change with frequency? ===
 
'''A:''' Because speakers aren't perfect at all frequencies. Some frequencies cause more distortion than others. That's physics being weird.
 
=== Q: Can I use this on any speaker? ===
 
'''A:''' Yes! Desktop speakers, studio monitors, subwoofers, car speakers - if it's connected to NVGate, we can measure it.
 
=== Q: How many times should I measure? ===
 
'''A:''' Once for curiosity. Three times for reliability. Ten times if you're publishing a paper.
 
=== Q: Can I export the results? ===
 
'''A:''' Yes! Copy text from the log console and paste into Excel, Word, or wherever you need it.
 
=== Q: What if my project has different settings? ===
 
'''A:''' Use the Configuration panel to adjust. It's literally made for this.
 
=== Q: Does this work over WiFi? ===
 
'''A:''' No. It only works locally (same computer or local network). WiFi would add too much latency.
 
---
 
== 🎓 QUICK REFERENCE ==
 
{| style="width: 100%; border-collapse: collapse; margin: 20px 0;"
|-
|-
| thd_gui.py || Graphical user interface (Tkinter)
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 15px; font-weight: bold; width: 25%; text-align: center;" | ACTION
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 15px; font-weight: bold; width: 25%; text-align: center;" | SHORTCUT
| style="background: linear-gradient(135deg, #667eea, #764ba2); color: white; padding: 15px; font-weight: bold; width: 50%; text-align: center;" | RESULT
|-
|-
| thd_sweep_measurement.py || Core calculation and NVGate communication
| style="padding: 15px; background: #f5f5f5; text-align: center;" | Launch App
| style="padding: 15px; background: #f5f5f5; text-align: center; font-family: monospace;" | Double-click .bat file
| style="padding: 15px; background: #f5f5f5; text-align: center;" | Window appears ✓
|-
|-
| Toolkit NVdrive/ || pynvdrive library to control NVGate
| style="padding: 15px; text-align: center;" | Start Measurement
| style="padding: 15px; text-align: center; font-family: monospace;" | Click ▶ START
| style="padding: 15px; text-align: center;" | Metrics begin updating ✓
|-
| style="padding: 15px; background: #f5f5f5; text-align: center;" | Stop Measurement
| style="padding: 15px; background: #f5f5f5; text-align: center; font-family: monospace;" | Click ■ STOP
| style="padding: 15px; background: #f5f5f5; text-align: center;" | Log shows "ended" ✓
|-
| style="padding: 15px; text-align: center;" | Run Diagnostic
| style="padding: 15px; text-align: center; font-family: monospace;" | Click "Run Diagnostic"
| style="padding: 15px; text-align: center;" | See all [OK] or [FAIL] ✓
|-
| style="padding: 15px; background: #f5f5f5; text-align: center;" | Change Config
| style="padding: 15px; background: #f5f5f5; text-align: center; font-family: monospace;" | Click ▶ Configuration
| style="padding: 15px; background: #f5f5f5; text-align: center;" | Apply changes ✓
|}
|}


==== Recompiling the Executable ====
---
<syntaxhighlight lang="bash">
 
pyinstaller --onefile --windowed --name "THD_Sweep_Measurement" --add-data "Toolkit NVdrive;Toolkit NVdrive" thd_gui.py
== 📞 BEFORE YOU CONTACT SUPPORT ==
</syntaxhighlight>
 
Gather this information:
* Screenshot of the error message
* Last 5 lines of the log console
* Your NVGate window names
* Steps you took before the error
 
This helps us help you faster! 🚀
 
---
 
{| style="width: 100%; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); color: white; padding: 30px; border-radius: 10px; margin: 30px 0; text-align: center;"
|-
| style="font-size: 1.5em; font-weight: bold;" | You're Ready!
|-
| style="font-size: 1.1em; margin-top: 10px; opacity: 0.95;" | Go measure some THD and make your speakers proud 🎵
|}
 
---
 
'''Last Updated:''' 2026-04-15
 
'''Version:''' 1.0 - User Guide


=== ❓ Troubleshooting ===
'''Format:''' MediaWiki


* '''"Error 4 bytes"''': Network buffer error handled automatically by a 20ms pause. Check local network load if it persists.
For technical details, see DOCUMENTATION_EN.txt
* '''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.

Revision as of 14:54, 15 April 2026

THD SWEEP MEASUREMENT - USER GUIDE

Master the art of measuring Total Harmonic Distortion with style

🎵 THD SWEEP MEASUREMENT
Professional Acoustic Testing Made Simple

---

⚡ QUICK START - 30 SECONDS

STEP ACTION
1️⃣ Launch Double-click Lancer_THD.bat
2️⃣ Connect Check top right: ● Connected
3️⃣ Start Click green ▶ START button
4️⃣ Monitor Watch 4 metrics update live
5️⃣ Stop Click red ■ STOP button

✅ That's it! Your first THD measurement is complete. You're now a certified acoustic engineer. (Not really, but it feels good.)

---

👀 YOUR INTERFACE - WHAT YOU SEE

🟢 Status Indicators (Top Right)

INDICATOR MEANING
● NVGate Connected Perfect! NVGate is ready to rock 🎸
● NVGate Disconnected Oops! Start NVGate first 🤔
● Measurement Running Data is flowing! 📊
● Measurement Stopped Ready for the next round ⏸️

📊 Four Metric Cards

The heart of the interface. These four numbers tell the whole story:

📈
THD (dB) 		📊
THD (%) 		📡
Frequency 		⚡
Fundamental
Harmonic distortion (log scale) Harmonic distortion (%) Current sweep point Signal strength
+5.42 dB 58.294 % 1234.56 Hz 5.0e-01 V

💬 Log Console (Bottom)

Real-time messages with color coding:

🟢 GREEN Everything OK - measurement working perfectly
🔴 RED Error occurred - something needs attention
🔵 BLUE Information - status updates and details

---

🎯 UNDERSTANDING YOUR RESULTS

THD (%) - The Easy Number

What is it? Percentage of unwanted harmonics in your signal.

Think of it this way:

  • THD 5% = 95% pure signal, 5% noise
  • THD 20% = 80% pure signal, 20% noise

The Quality Scale:

🌟 1% - 5% Excellent - Professional grade equipment
✅ 5% - 15% Good - Solid speaker performance
⚠️ 15% - 30% Acceptable - Consumer level equipment
❌ > 30% Poor - Time for an upgrade 🛠️

THD (dB) - The Technical Number

Same measurement as THD (%) but in decibels (logarithmic scale).

Quick Conversion Chart:

THD % THD dB Quality
1% -40 dB 🌟 Perfect
3% -30 dB ✅ Great
10% -20 dB ✅ Good
30% -10 dB ⚠️ Poor

---

📋 TYPICAL MEASUREMENT WORKFLOW

Pre-Measurement Checklist

Before you start, verify:

  • ✓ NVGate is open and ready
  • ✓ Sweep is configured (e.g., 10 Hz → 20 kHz)
  • ✓ FFT traces are visible on screen
  • ✓ Sine generator is active
  • ✓ Speaker is connected and working

Step-by-Step Workflow

PHASE WHAT TO DO
1️⃣ Prepare Open NVGate → Set sweep → Verify FFT visible
2️⃣ Launch App Double-click Lancer_THD.bat → Check Connected status
3️⃣ Start Click ▶ START → Watch log for "Starting THD Measurement"
4️⃣ Monitor Watch metrics update → Frequency should increase → THD should be stable
5️⃣ Stop Click ■ STOP → Watch for "Measurement ended" → Note final values

---

⚙️ CONFIGURATION

When Do I Need to Change This?

Honest answer: Almost never.

The default settings work for 95% of users. Only change if your NVGate project has:

  • Different window names
  • Different marker numbers
  • Different DC input addresses

If you're not sure → Don't change anything. It works. Trust it.

How to Access Configuration

Click on ▶ Configuration (section expands)

Important Settings

Setting Default When to Change
Window (sweep) Window2 Your sweep FFT has different name
Window (response) Window1 Your response FFT has different name
Number of harmonics 9 5 (faster), 15 (more detailed)

How to Apply Changes

  1. Modify field value
  2. Click Apply Configuration
  3. Log displays "Configuration applied" ✓
  4. Done!

---

🔧 TROUBLESHOOTING

Issue 1: NVGate Shows "Disconnected"

What it means: Application can't reach NVGate

Solutions (in order):

  1. Is NVGate actually open? Check your screen.
  2. Restart NVGate
  3. Restart the THD application
  4. Check Windows firewall allows localhost connections
  5. Call your IT department and cry

Reality check: 99% of the time NVGate just wasn't open. No shame, happens to everyone.

Issue 2: Measurement Won't Start

What it means: Something blocking the measurement

Solutions:

  1. Click Run Diagnostic - it will tell you exactly what's wrong
  2. Common causes:
    • No sweep configured in NVGate
    • Markers not properly created
    • Wrong window names in configuration

The diagnostic is your friend. Use it!

Issue 3: THD Values Show "--.-" (dashes)

What it means: No data is being read from harmonics

Check these:

  1. Are FFT traces actually visible in NVGate? (Most common issue)
  2. Is the sweep running?
  3. Is there audio output to your speaker?
  4. Are markers properly set up?

Fix one of these and you're golden!

Issue 4: STOP Button Doesn't Work

What it means: Measurement is shutting down but taking its time

Solution: Wait 5 seconds. Seriously. The app is cleaning up.

If it still doesn't respond after 30 seconds:

  1. Close the window
  2. Restart the application
  3. Continue with life

---

💡 PRO TIPS

Tip 1: Start Simple

Always use default settings first. Change things later if needed.

Tip 2: Read the Log The log console tells you everything. It's your best friend.

Tip 3: Use Diagnostic When something's wrong, click "Run Diagnostic". It's like magic.

Tip 4: Multiple Measurements One measurement is interesting. Five measurements is scientific.

Tip 5: Document Results Take a screenshot or copy the final THD values. You'll forget otherwise.

---

❓ FREQUENTLY ASKED QUESTIONS

Q: Is THD 5% good?

A: For a speaker? Excellent! You can be proud of that equipment. 🎉

Q: Why does THD change with frequency?

A: Because speakers aren't perfect at all frequencies. Some frequencies cause more distortion than others. That's physics being weird.

Q: Can I use this on any speaker?

A: Yes! Desktop speakers, studio monitors, subwoofers, car speakers - if it's connected to NVGate, we can measure it.

Q: How many times should I measure?

A: Once for curiosity. Three times for reliability. Ten times if you're publishing a paper.

Q: Can I export the results?

A: Yes! Copy text from the log console and paste into Excel, Word, or wherever you need it.

Q: What if my project has different settings?

A: Use the Configuration panel to adjust. It's literally made for this.

Q: Does this work over WiFi?

A: No. It only works locally (same computer or local network). WiFi would add too much latency.

---

🎓 QUICK REFERENCE

ACTION SHORTCUT RESULT
Launch App Double-click .bat file Window appears ✓
Start Measurement Click ▶ START Metrics begin updating ✓
Stop Measurement Click ■ STOP Log shows "ended" ✓
Run Diagnostic Click "Run Diagnostic" See all [OK] or [FAIL] ✓
Change Config Click ▶ Configuration Apply changes ✓

---

📞 BEFORE YOU CONTACT SUPPORT

Gather this information:

  • Screenshot of the error message
  • Last 5 lines of the log console
  • Your NVGate window names
  • Steps you took before the error

This helps us help you faster! 🚀

---

You're Ready!
Go measure some THD and make your speakers proud 🎵

---

Last Updated: 2026-04-15

Version: 1.0 - User Guide

Format: MediaWiki

For technical details, see DOCUMENTATION_EN.txt

Retrieved from "https://wiki.oros.com/index.php?title=THD_Sweep_Measurement&oldid=12713"