# Quick Start Guide

## Installation

```bash
# Install dependencies
pip install -r requirements.txt
```

## Basic Usage

### 1. Run Your First Test

```bash
python run_test.py \
  --serial-number "SN001234" \
  --software-version "initial" \
  --comment "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

```bash
# 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:

```bash
# Test unit SN001234
python run_test.py --serial-number "SN001234" --software-version "abc123"

# Test unit SN001235  
python run_test.py --serial-number "SN001235" --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:

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

## Troubleshooting

**Audio device not found:**
```bash
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):
```bash
chmod +x run_test.py view_results.py
```

## Next Steps

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