Testing & Tuning
A staged process for verifying a working installation and tuning the echo cancellation pipeline. Start from the known-good configuration and change one setting at a time.
1. Verify startup
Compile and flash over USB for the first bring-up, then inspect logs.
With aec_speexdsp, a healthy startup reports paired TDM initialization,
creation of both audio tasks, and the canceller memory placement:
SpeexDSP state memory: 118 KB internal, 0 KB PSRAM
If the state lands in PSRAM, reduce filter_length until it fits in internal
RAM — PSRAM-resident state measurably slows the frame loop. Once running, the
audio task logs its load every five seconds:
DSP load: 313 frames in 5002 ms: processing avg 2210 us/frame (13.8% of real time), peak 4980 us (31.1%), frame budget 16000 us
2. Map TDM slots
Temporarily enable:
aec_speexdsp:
# ...
diagnostic_raw_slot: 0
slot_logs: true
Speak close to each microphone and play a tone. Repeat slots 0 through 3.
Use the logs/listening tests to identify both microphone slots and, if present,
the analog reference. Update microphone_slots and reference_slot, then
remove diagnostic_raw_slot so the published stream comes from the DSP.
3. Verify full-duplex routing
Play a known 16-bit/16 kHz WAV through the component’s speaker while listening to or recording the component’s microphone. Check that:
- playback is clean and reaches the intended DAC channels;
- microphone capture continues throughout playback;
- the reference meter is active during playback;
rx_errors,tx_errors, underruns, and dropped frames do not continually increase whendiagnostics: trueis enabled.
If long-form audio slowly underruns or overruns while short clips work, follow the automatic rate-matching test below.
Automatic rate matching
The actual I2S sample clock can differ slightly from the requested 16,000 Hz because of clock-divider rounding and source clock tolerance. To test the correction for this hardware sample-rate error:
- Enable
resampler: trueanddiagnostics: true. - Play continuous, nominally 16 kHz PCM for at least 30 seconds. Several minutes is better for exposing a small mismatch.
- Confirm the log initially reports
Playback resampler enabledat 16000 Hz. - Watch
Playback rate adjustfor the estimated I2S rate and the gradually adjusted playback rate.Playback input rateis informational only — bursty offered/accepted throughput is normal and does not move the target. - Confirm playback remains continuous and that underrun, TX-error, and dropped frame counters do not continually rise.
A settled playback rate slightly above or below 16 kHz means the component is adding or removing a small number of interpolated samples to compensate for the estimated hardware rate. The estimate comes from blocking write timing, so DMA buffering and task scheduling can also influence it. The correction is retained for the next response and refined as new measurements arrive.
Rate matching is not a cure for the host sending the wrong format, large network gaps, an overloaded device, or persistent I2S errors. Convert all input to signed 16-bit, nominally 16 kHz PCM before it reaches the speaker. If the playback rate repeatedly settles at the 15 kHz or 17 kHz clamp, measure the board’s actual audio clocks rather than treating the limit as normal drift.
4. Prevent reference clipping
Clipping must be fixed before delay or DSP tuning. A reference channel that
reaches digital full scale has lost information, even if its ADC gain is already
at minimum. Use playback_gain_db to attenuate media before it reaches both the
DAC and reference tap. The Waveshare 7B examples use -12 dB because its
hardware loopback clips when the DAC is driven close to full scale. Re-test the
speaker and raw reference at the loudest intended setting after changing it.
5. Reference timing
AEC is very sensitive to timing alignment between the reference and the microphones. It will only work effectively with a hardware reference captured in sync with the microphone channels. Use the captured slot directly and verify its mapping and level. See reference timing.
6. Measure cancellation and double-talk
Enable telemetry: true, play a repeatable speech/noise clip, and compare its
AEC_EFFECT lines. Effective cancellation normally reduces cleaned/reference
correlation and reduces cleaned RMS during playback-only sections. Also speak
while playback continues: a setting that removes echo but destroys near-end
speech is not acceptable full-duplex performance.
Tune in this order:
- correct slot mapping and unclipped ADC/DAC levels;
- correct hardware reference alignment and
playback_gain_db; noise_suppression_level_db;echo_suppress_db/echo_suppress_active_db— higher values remove more residual echo; lowerecho_suppress_active_dbpreserves double-talk;filter_length— the main quality knob. The complete Waveshare examples start at1024for workload headroom;2048is the component default. Try longer tails only when measurements show they are needed and the DSP/memory budget allows. The adaptive filter models the causal echo path within that tail; it cannot compensate a reference shifted later than the earliest echo;agc.target_level, then optional meters and resampling.
With the AGC gate enabled, verify its decisions during playback: enable
telemetry: true and watch the once-second AGC_GATE line. Quiet speech that
cannot acquire boost during playback means open_rms is too high or
open_delay_ms/startup_guard_ms too long for the material; residual echo
that acquires boost means raise open_rms, open_delay_ms, or
startup_guard_ms. Set reference_open_rms above the measured idle floor of
the reference slot, and lengthen tail_ms if protection releases during
quiet playback tails. Remember the gate controls boost only: it never mutes,
and it cannot remove echo that passes at unity gain.
Test at several playback volumes and distances. Include playback-only, speech- only, and simultaneous speech/playback cases, then test the real wake-word and voice-assistant hand-off. Objective telemetry is useful, but listening and recognition success during double-talk are the final quality tests.
With beamforming enabled, inspect the periodic Beamformer profile
TDOA/confidence log and set max_lag from the physical microphone spacing
(about one sample per 21 mm at 16 kHz) before relaxing the confidence
thresholds. Without beamforming, try output_channel: second if
the first microphone is weaker.
Validate filter length against real-time throughput
Increase filter_length only after routing, reference level/delay, and the
lower-cost settings work. For each candidate value:
- Cold boot several times and confirm there is no startup watchdog reset.
- Stream microphone audio for at least a minute while the display, network, wake-word engine, and playback path are active.
- With a listener active and response muting/capture gating disabled, five seconds of mono 16-bit audio should produce approximately 160,000 bytes at nominal 16 kHz. Allow for frame boundaries and the actual hardware clock. Measure over a settled interval without pre-roll replay or backlog draining; a materially lower sustained rate can indicate that the system is falling behind.
- Watch
max_processing_us, RX/TX errors, dropped frames, and microphone queue overflow logs with diagnostics enabled. Onaec_speexdsp, watch the five-secondDSP loadline: the average percentage is the share of one core needed to keep up, and values near 100% mean frames will be dropped. Also confirm the startup memory log still reports the canceller state in internal RAM. - Repeat playback-only and double-talk tests. Retain the longer filter only if cancellation improves without harming voice delivery or stability.
If a longer filter is required, first reduce other CPU costs — for example spectrum metering, display work, or other optional processing — then repeat the full throughput test.