First-Time Board Setup and AEC Bring-Up

Porting the component to a new board is primarily a hardware-validation exercise. Display, networking, codec control, raw capture, playback, input gains, and the AEC reference are separate systems; prove each one before evaluating echo cancellation.

Eight-stage board bring-up sequence from basic boot through final DSP evaluation

The Waveshare ESP32-P4-WIFI6-Touch-LCD-7B settings in the installation guide are the tested reference. Do not copy its GPIOs or TDM slots to a similar-looking board without checking that board’s exact revision and schematic.

If you have the Waveshare 7B itself, use the ready-made audio-test example for the steps below. Its touch UI exposes all four raw slots, levels, spectrum, recording, and test playback without requiring a rebuild for every diagnostic selection.

Before you start

Collect the schematic and datasheets for the processor, microphone ADC, playback DAC/codec, and amplifier. Record:

  • ESP32 target, flash size, and PSRAM type and size;
  • I2C pins, codec addresses, and power rails;
  • MCLK, BCLK, LRCLK, DIN, and DOUT pins;
  • amplifier enable, mute, reset, and their active levels;
  • ADC input routing and four-slot TDM order; and
  • the two TDM slots consumed by the DAC.

The components require ESP-IDF, four-slot, 16-bit, 16 kHz TDM, and synchronized microphone channels. Use a TDM-capable target, preferably with a hardware FPU (ESP32-S3 or ESP32-P4), and working PSRAM for the microphone buffers. A hardware playback reference is required. See Hardware & Audio Design before selecting or wiring a board.

1. Prove the board without audio

Start with a minimal ESPHome configuration. Confirm that the processor boots reliably, PSRAM is detected, logs are stable, and API/OTA networking works. If the device also has a display or touch panel, prove those separately before adding the codecs or the audio hub.

Save this minimal configuration as a recovery image. It gives you a known-good baseline if later audio work causes memory pressure or boot failures.

2. Initialize the codecs

Add the I2C bus and the ADC/DAC control components, but keep the rest of the configuration simple. Enable I2C scanning during bring-up and confirm both devices acknowledge at their expected addresses.

Configure 16-bit samples at 16 kHz. The ADC must output four-slot TDM and the DAC must accept the same clocks and framing. If using the ES7210, follow the extra TDM-component note in the installation guide. Correct digital clocks can still produce silence if a codec rail, mute line, or amplifier enable is wrong, so verify those signals against the schematic.

3. Add the audio hub in diagnostic mode

Copy the hub, microphone, and speaker structure from the installation guide, then replace the board-specific pins. Begin with the conservative diagnostic baseline:

aec_speexdsp:
  # audio_adc and the five I2S/TDM pins go here
  tdm_slots: 4
  frame_size: 256
  filter_length: 1024
  diagnostic_raw_slot: 0
  slot_logs: true
  diagnostics: true

Do not configure another component to own the same I2S peripheral or GPIOs. Flash over USB and inspect the startup log. Resolve allocation, I2S, or codec errors before assessing audio quality.

4. Set microphone and reference gains

Correct input gains are a bring-up gate, not a later tuning detail. The AEC, AGC, and every subsequent check assume clean, unclipped microphone and reference signals; no DSP setting can repair samples that were already clipped by the ADC.

With the hub still in diagnostic mode (slot_logs: true or the audio-test meters), play a repeatable test signal through the component’s speaker at the loudest intended volume and set both levels:

  • Microphones. Speak at the normal usage distance and adjust the ADC gain (mic_gain on the ES7210) until speech is strong but peaks stay well below digital full scale. Both microphone slots should end up similarly sensitive. Leave headroom: AEC and AGC cannot recover clipped samples.
  • Reference. The analog reference must closely follow playback without reaching digital full scale. Lower that slot’s ADC gain first; if the reference level is still too high at the minimum gain, reduce the DAC output with the software DAC output gain playback_gain_db (the Waveshare 7B uses -12 dB). It attenuates audio before it reaches both the DAC and the reference tap, trading a little maximum playback volume for an undistorted reference. Re-test the speaker and the raw reference at the loudest intended volume afterwards. See Prevent reference clipping.

5. Map every receive slot

Set diagnostic_raw_slot to each value from 0 through 3, rebuilding as needed. Listen to or record the published microphone while you:

  1. speak or rub a finger near each microphone in turn;
  2. play a repeatable test signal through the speaker; and
  3. observe the raw-slot RMS/peak logs.

Both microphone channels must be intelligible, similarly sensitive, and free of clipping, buzz, repeated samples, and incorrect pitch. If the levels are wrong, return to the gain check in step 4 before continuing.

Update microphone_slots only after this test. On the reference Waveshare 7B, the tested microphone slots are [0, 2] and slot 1 is the hardware reference; another board may differ.

6. Verify playback

Send signed 16-bit, 16 kHz mono or stereo PCM through the component’s speaker. Check that playback reaches the intended DAC channels cleanly and that capture continues during playback. If there is silence or distortion, verify DOUT, tx_slots, codec volume/mute, amplifier control, speaker wiring, and TDM framing.

resampler: true compensates for small sustained rate differences. It is not a decoder or a general sample-rate converter, so source audio must still be nominally 16 kHz PCM.

7. Verify the reference

For reference_source: analog_slot, test the proposed slot in diagnostic mode. Its level was set in step 4; re-check it here if playback sounds distorted. It should be quiet when playback is stopped, closely follow playback when it is active, and respond little to room speech. A spare or microphone-connected ADC channel is not a playback reference. Set the verified slot as reference_slot and use the captured reference directly.

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.

8. Enable and evaluate the DSP

Remove diagnostic_raw_slot to publish the cleaned output. Test the same phrase in three conditions: speech only, playback only, and simultaneous speech and playback. A successful configuration substantially reduces playback while keeping near-end speech intelligible; complete silence is not a realistic goal.

Tune in this order:

  1. correct slot mapping, clean levels, and stable TDM transport;
  2. correct hardware reference alignment and level;
  3. noise_suppression_level_db, then echo_suppress_db / echo_suppress_active_db;
  4. filter_length — a plain sample count (see choosing an echo filter length); and
  5. optional noise suppression, AGC, meters, and resampling.

Change one setting per test. Test several playback volumes and reject a setting that suppresses the user’s voice during double-talk, even if its playback-only result sounds quieter. See Testing & Tuning for the repeatable test procedure.

Filter length is also a CPU-budget decision. Start at the 2048-sample default and raise it only while the DSP load log stays comfortably below 100%. A firmware image booting successfully does not prove that it can process and deliver audio continuously.

Troubleshooting the bring-up

  • DSP load near 100% or PSRAM state: enable the performance sdkconfig_options, then reduce filter_length until the load log and memory placement are comfortable.
  • All slots are silent: verify codec power, MCLK/BCLK/LRCLK, DIN direction, and four-slot TDM mode.
  • One microphone is missing: scan all four slots, then check bias, routing, soldering, and per-channel gain.
  • Crackles or wrong pitch: recheck 16-bit framing, the 16 kHz clock, shared clock wiring, and diagnostics counters.
  • Reference behaves like a microphone: the proposed ADC input is not a real playback feedback path; inspect the schematic.
  • AEC fails only at high volume: the speaker, amplifier, reference input, or microphone ADC is probably clipping or nonlinear. Set playback_gain_db to retain digital headroom (the Waveshare example uses -12), lower analogue gain if possible, or improve the physical audio path. Once a sample is clipped, AEC and AGC cannot recover it.

Keep the final board revision, codec addresses, pins, verified RX/TX slots, gains, maximum clean playback volume, ESPHome version, and DSP settings with the working configuration. Those details make a port reproducible and upgrades testable.

After these checks pass on a Waveshare 7B, the complete voice-assistant example is the recommended next step.