Adds artifact test.
This commit is contained in:
Pbopbo
193
ARTIFACT_DETECTION_README.md
Normal file
193
ARTIFACT_DETECTION_README.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Artifact Detection Test
|
||||
|
||||
## Overview
|
||||
This test plays a 1kHz sine wave for a configurable duration (default 60 seconds) and records both channels simultaneously:
|
||||
- **Channel 1**: Loopback path (direct audio interface connection)
|
||||
- **Channel 2**: DUT/Radio path (through beacon and radio transmission)
|
||||
|
||||
The test detects buzzing, clicks, dropouts, and other audio artifacts using multiple configurable algorithms.
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
python test_artifact_detection.py \
|
||||
--serial-number SN001234 \
|
||||
--software-version abc123 \
|
||||
--comment "Testing new firmware"
|
||||
```
|
||||
|
||||
## Detection Algorithms
|
||||
|
||||
The test uses four configurable detection algorithms (spectral_anomaly is **disabled by default** due to false positives):
|
||||
|
||||
### 1. Spectral Anomaly Detection (DISABLED BY DEFAULT)
|
||||
- **Status**: ⚠️ Currently generates too many false positives - disabled by default
|
||||
- **What it detects**: Unexpected frequencies that aren't harmonics of the fundamental tone
|
||||
- **Use case**: Buzzing, interference, crosstalk
|
||||
- **Configuration**: `threshold_db` - how far below fundamental to search (-60 dB default)
|
||||
|
||||
### 2. Amplitude Spike Detection (WORKING)
|
||||
- **What it detects**: Sudden changes in signal amplitude (RMS)
|
||||
- **Use case**: Clicks, pops, dropouts
|
||||
- **Configuration**: `threshold_factor` - number of standard deviations (3.0 default)
|
||||
|
||||
### 3. Zero-Crossing Anomaly Detection (WORKING)
|
||||
- **What it detects**: Irregular zero-crossing patterns
|
||||
- **Use case**: Distortion, clipping, non-linear artifacts
|
||||
- **Configuration**: `threshold_factor` - number of standard deviations (2.0 default)
|
||||
|
||||
### 4. Energy Variation Detection (WORKING)
|
||||
- **What it detects**: Rapid energy changes between time windows
|
||||
- **Use case**: Dropouts, level fluctuations, intermittent issues
|
||||
- **Configuration**: `threshold_db` - energy change threshold (6.0 dB default)
|
||||
|
||||
## Configuration
|
||||
|
||||
Edit `config.yaml` to customize the test:
|
||||
|
||||
```yaml
|
||||
artifact_detection:
|
||||
test_frequency: 1000 # Hz
|
||||
duration: 60.0 # seconds
|
||||
amplitude: 0.5 # 0.0 to 1.0
|
||||
detectors:
|
||||
spectral_anomaly:
|
||||
enabled: true
|
||||
threshold_db: -40
|
||||
amplitude_spikes:
|
||||
enabled: true
|
||||
threshold_factor: 3.0
|
||||
zero_crossing:
|
||||
enabled: true
|
||||
threshold_factor: 2.0
|
||||
energy_variation:
|
||||
enabled: true
|
||||
threshold_db: 6.0
|
||||
```
|
||||
|
||||
## Command Line Options
|
||||
|
||||
- `--serial-number`: Serial number (required)
|
||||
- `--software-version`: Git commit hash or version (required)
|
||||
- `--comment`: Optional comments about the test
|
||||
- `--config`: Path to config file (default: config.yaml)
|
||||
- `--duration`: Override duration in seconds
|
||||
- `--frequency`: Override test frequency in Hz
|
||||
|
||||
## Example: Quick 10-second Test
|
||||
|
||||
```bash
|
||||
python test_artifact_detection.py \
|
||||
--serial-number SN001234 \
|
||||
--software-version abc123 \
|
||||
--duration 10
|
||||
```
|
||||
|
||||
## Example: Custom Frequency
|
||||
|
||||
```bash
|
||||
python test_artifact_detection.py \
|
||||
--serial-number SN001234 \
|
||||
--software-version abc123 \
|
||||
--frequency 440
|
||||
```
|
||||
|
||||
## Tuning Detection Algorithms
|
||||
|
||||
### More Sensitive Detection
|
||||
To catch more subtle artifacts, make thresholds stricter:
|
||||
|
||||
```yaml
|
||||
detectors:
|
||||
spectral_anomaly:
|
||||
threshold_db: -50 # Lower = more sensitive
|
||||
amplitude_spikes:
|
||||
threshold_factor: 2.0 # Lower = more sensitive
|
||||
zero_crossing:
|
||||
threshold_factor: 1.5 # Lower = more sensitive
|
||||
energy_variation:
|
||||
threshold_db: 3.0 # Lower = more sensitive
|
||||
```
|
||||
|
||||
### Less Sensitive Detection
|
||||
To reduce false positives in noisy environments:
|
||||
|
||||
```yaml
|
||||
detectors:
|
||||
spectral_anomaly:
|
||||
threshold_db: -30 # Higher = less sensitive
|
||||
amplitude_spikes:
|
||||
threshold_factor: 4.0 # Higher = less sensitive
|
||||
zero_crossing:
|
||||
threshold_factor: 3.0 # Higher = less sensitive
|
||||
energy_variation:
|
||||
threshold_db: 10.0 # Higher = less sensitive
|
||||
```
|
||||
|
||||
### Disable Specific Detectors
|
||||
```yaml
|
||||
detectors:
|
||||
spectral_anomaly:
|
||||
enabled: false # Turn off this detector
|
||||
```
|
||||
|
||||
## Output
|
||||
|
||||
The test generates:
|
||||
1. **YAML results file**: `test_results/{timestamp}_artifact_detection_results.yaml`
|
||||
2. **JSON results file**: `test_results/{timestamp}_artifact_detection_results.json`
|
||||
3. **Summary plots** (if enabled): `test_results/{timestamp}_artifact_detection/`
|
||||
- Time domain waveforms with artifact markers
|
||||
- Frequency spectrum analysis
|
||||
4. **Individual anomaly plots**: `test_results/{timestamp}_artifact_detection/individual_anomalies/`
|
||||
- Each anomaly plotted individually with ~20 periods of context
|
||||
- Detailed view showing exactly what the anomaly looks like
|
||||
- Named by channel, type, and timestamp for easy identification
|
||||
|
||||
### Results Structure
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
test_id: "20260317_140530"
|
||||
timestamp: "2026-03-17T14:05:30.123456"
|
||||
test_type: "artifact_detection"
|
||||
pcb_version: "v2.1"
|
||||
pcb_revision: "A"
|
||||
software_version: "abc123"
|
||||
|
||||
artifact_detection_result:
|
||||
test_frequency_hz: 1000
|
||||
duration_sec: 60.0
|
||||
channel_1_loopback:
|
||||
total_artifacts: 5
|
||||
artifact_rate_per_minute: 5.0
|
||||
artifacts_by_type:
|
||||
spectral_anomaly: 2
|
||||
amplitude_spike: 3
|
||||
channel_2_dut:
|
||||
total_artifacts: 23
|
||||
artifact_rate_per_minute: 23.0
|
||||
artifacts_by_type:
|
||||
spectral_anomaly: 8
|
||||
amplitude_spike: 10
|
||||
energy_variation: 5
|
||||
detector_config: {...}
|
||||
```
|
||||
|
||||
## Interpreting Results
|
||||
|
||||
- **Zero artifacts in both channels**: Excellent signal quality
|
||||
- **Same artifacts in both channels**: Likely environmental interference or audio interface issue
|
||||
- **More artifacts in Channel 2 (radio path)**: Radio transmission degradation detected
|
||||
- **High spectral_anomaly count**: Interference or crosstalk
|
||||
- **High amplitude_spike count**: Clicks, pops, or dropouts
|
||||
- **High energy_variation count**: Level instability or dropouts
|
||||
|
||||
## Comparison with Loopback Baseline
|
||||
|
||||
The loopback path (Channel 1) serves as a baseline reference. Any additional artifacts in the radio path (Channel 2) indicate degradation introduced by the radio transmission system.
|
||||
|
||||
Expected behavior:
|
||||
- Loopback should have minimal artifacts (ideally zero)
|
||||
- Radio path may have some artifacts due to transmission
|
||||
- Large difference indicates issues in radio hardware/firmware
|
||||
Reference in New Issue
Block a user