Quick Start Guide

Installation

# Install dependencies
pip install -r requirements.txt

Basic Usage

1. Run Your First Test

python run_test.py \
  --pcb-version "v1.0" \
  --pcb-revision "A" \
  --software-version "initial" \
  --notes "First test run"

What happens:

Auto-detects your Scarlett audio interface
Plays test tones at 7 frequencies (100 Hz to 8 kHz)
Records input/output on both channels
Calculates latency, THD, and SNR
Saves results to test_results/YYYYMMDD_HHMMSS_results.yaml

2. View Results

# List all test results
python view_results.py --list

# View specific test (example)
python view_results.py test_results/20260226_123456_results.yaml

# View example result
python view_results.py example_test_result.yaml

3. Compare Different PCB Versions

Run multiple tests with different metadata:

# Test PCB v1.0
python run_test.py --pcb-version "v1.0" --pcb-revision "A" --software-version "abc123"

# Test PCB v2.0  
python run_test.py --pcb-version "v2.0" --pcb-revision "A" --software-version "abc123"

# Compare by viewing both YAML files
python view_results.py test_results/20260226_120000_results.yaml
python view_results.py test_results/20260226_130000_results.yaml

Understanding the Output

Each test produces metrics at 7 frequencies:

Latency (ms): Delay between channels (should be near 0 for loopback)
THD Input (%): Distortion in channel 1 (lower is better)
THD Output (%): Distortion in channel 2 (lower is better)
SNR Input (dB): Signal quality in channel 1 (higher is better)
SNR Output (dB): Signal quality in channel 2 (higher is better)

Good values:

THD: < 0.1% (< 0.01% is excellent)
SNR: > 80 dB (> 90 dB is excellent)
Latency: < 5 ms for loopback

Configuration

Edit config.yaml to customize test parameters:

test_tones:
  frequencies: [1000]  # Test only 1 kHz
  duration: 3.0        # Shorter test (3 seconds)

Troubleshooting

Audio device not found:

python -c "import sounddevice as sd; print(sd.query_devices())"

Update device_name in config.yaml to match your device.

Permission errors: Make scripts executable (Linux/Mac):

chmod +x run_test.py view_results.py

Next Steps

Run baseline tests with known-good hardware
Test different PCB revisions
Track software version changes
Archive YAML files for long-term tracking
Build comparison scripts as needed

2.5 KiB Raw Blame History