From d778391c5cf5ac6a43672d78ca07eaea38460e1b Mon Sep 17 00:00:00 2001 From: Adolfo Reyna Date: Thu, 18 Jun 2026 22:38:47 -0400 Subject: [PATCH] fix(audio): resolve ES7210 microphone popping sound by correcting OSR and clock division configuration --- .gitignore | 9 +++ README.md | 7 +++ demo_audio_loopback.py | 73 +++++++++++++----------- hardware_findings.md | 32 +++++++++++ lib/audio_util.py | 125 +++++++++++++++++++++++++++++------------ lib/board_config.py | 23 ++++++++ main.py | 20 +++++-- 7 files changed, 212 insertions(+), 77 deletions(-) create mode 100644 hardware_findings.md diff --git a/.gitignore b/.gitignore index 82cf00a..c750cf3 100644 --- a/.gitignore +++ b/.gitignore @@ -14,3 +14,12 @@ __pycache__/ # Log files desktop_client/*.log +# Helper scripts and datasheets +deploy_main_serial.py +dtr_reset.py +hard_reset.py +pcm2wav.py +plot_audio.py +*.pdf + + diff --git a/README.md b/README.md index c518d61..6157410 100644 --- a/README.md +++ b/README.md @@ -137,3 +137,10 @@ Here is a summary of the MCP tools exposed by the bridge: | `write_file` | `path`, `content` | Writes text file to board flash. | | `read_file` | `path` | Reads text file from board flash. | | `execute_python` | `code` | Executes arbitrary Python code dynamically. | + +--- + +## 5. Hardware & Troubleshooting Findings + +For detailed technical findings regarding the board's hardware (e.g. I2S bit-depth configuration, I2C bus lockup recovery, pinout configuration, and ES7210 microphone clock/OSR registers to resolve popping sound issues), refer to [hardware_findings.md](hardware_findings.md). + diff --git a/demo_audio_loopback.py b/demo_audio_loopback.py index ce3b0ff..a81fe67 100644 --- a/demo_audio_loopback.py +++ b/demo_audio_loopback.py @@ -2,9 +2,8 @@ import time import machine from machine import Pin, I2S import board_config -import audio_util -def play_raw_pcm(filename, channels=2, rate=16000, bits=16, volume=90): +def play_ram_pcm(audio_chunks, channels=2, rate=16000, bits=16, volume=90): from audio_util import ES8311 # 1. Start MCLK PWM using board config parameters @@ -38,16 +37,11 @@ def play_raw_pcm(filename, channels=2, rate=16000, bits=16, volume=90): amp_pin = Pin(board_config.audio_amp_pin, Pin.OUT, value=on_val) try: - print(f"Streaming raw audio to speaker from '{filename}'...") - with open(filename, 'rb') as f: - buf = bytearray(2048) - while True: - bytes_read = f.readinto(buf) - if bytes_read == 0: - break - i2s.write(buf[:bytes_read]) + print(f"Streaming raw audio to speaker from RAM ({len(audio_chunks)} chunks)...") + for chunk in audio_chunks: + i2s.write(chunk) except Exception as e: - print("Error during raw playback:", e) + print("Error during RAM playback:", e) finally: time.sleep_ms(100) # Let buffer play out amp_pin.value(off_val) # Disable amp @@ -58,10 +52,10 @@ def play_raw_pcm(filename, channels=2, rate=16000, bits=16, volume=90): def main(): display = board_config.display_instance - print("=== Dynamic Audio Loopback Utility Script ===") + print("=== Dynamic RAM-based Audio Loopback Script ===") print(f"Board Detected: {board_config.BOARD_TYPE}") - # Initialize buttons using polling Pins instead of BoardButtons class (to avoid edge-triggered interrupt storms) + # Initialize buttons using polling Pins instead of BoardButtons class key_pin = Pin(18, Pin.IN, Pin.PULL_UP) boot_pin = Pin(0, Pin.IN, Pin.PULL_UP) @@ -71,8 +65,6 @@ def main(): return board_config.touch.is_touched() return key_pin.value() == 0 - filename = "local_audio_test.pcm" - while True: if display: display.clear(0) @@ -81,13 +73,13 @@ def main(): display.line(10, 20, 390, 20, 1) display.text("1. Press KEY button to record 10s", 15, 60, 1) display.text("2. Playback will start automatically", 15, 80, 1) - display.text("Ready...", 15, 120, 1) + display.text("Ready (RAM-based)...", 15, 120, 1) else: display.text("Touch Audio Loopback Test", 10, 10, 1) display.line(10, 20, 310, 20, 1) display.text("1. Press screen/KEY to record 10s", 10, 50, 1) display.text("2. Playback starts automatically", 10, 70, 1) - display.text("Ready...", 10, 100, 1) + display.text("Ready (RAM-based)...", 10, 100, 1) display.show() print("Ready: Press and hold key/screen to record...") @@ -129,8 +121,6 @@ def main(): display.text("Speak now!", 10, 80, 1) display.show() - # We record as long as the button is pressed (or up to 10 seconds max) - # 1. Start MCLK PWM using board config parameters mclk_pwm = None if board_config.audio_mclk_pin is not None: @@ -139,26 +129,28 @@ def main(): mclk_pwm.freq(board_config.audio_mclk_freq) mclk_pwm.duty_u16(32768) - # 2. Configure I2S RX (Stereo 16kHz) + # 2. Configure I2S RX (Stereo 16kHz) - ibuf set to 16000 for safety i2s_rx = I2S(1, sck=Pin(board_config.audio_i2s_sck), ws=Pin(board_config.audio_i2s_ws), sd=Pin(board_config.audio_i2s_rx_sd), mode=I2S.RX, - ibuf=8000, + ibuf=16000, rate=16000, bits=16, format=I2S.STEREO) # 3. Wake up and configure the microphone chip (ES7210 vs ES8311) + init_ok = False if board_config.audio_mic_codec == "ES7210": from audio_util import ES7210 mic_adc = ES7210(board_config.i2c_bus) - mic_adc.init(sample_rate=16000, bit_width=16) + init_ok = mic_adc.init(sample_rate=16000, bit_width=16) else: from audio_util import ES8311 mic_adc = ES8311(board_config.i2c_bus) if mic_adc.init(sample_rate=16000): + init_ok = True mic_adc.set_volume(80) try: mic_adc._write(0x14, 0x1A) # Enable analog mic input & PGA @@ -166,19 +158,32 @@ def main(): mic_adc._write(0x17, 0xC8) # Set ADC digital volume except: pass + + if not init_ok: + print("Microphone codec initialization failed! Aborting recording.") + i2s_rx.deinit() + if mclk_pwm: + mclk_pwm.deinit() + if display: + display.clear(0) + display.text("Codec Init Failed!", 15, 80, 1) + display.show() + time.sleep(3) + continue - # Record loop - buffer = bytearray(1024) + # Record loop to RAM - using ticks_ms for safe timing + buffer = bytearray(2048) + audio_chunks = [] total_bytes = 0 - start_rec_time = time.time() + start_rec_time = time.ticks_ms() + max_duration_ms = 10000 # 10 seconds try: - with open(filename, 'wb') as f: - while (time.time() - start_rec_time) < 10: - bytes_read = i2s_rx.readinto(buffer) - if bytes_read > 0: - f.write(buffer[:bytes_read]) - total_bytes += bytes_read + while time.ticks_diff(time.ticks_ms(), start_rec_time) < max_duration_ms: + bytes_read = i2s_rx.readinto(buffer) + if bytes_read > 0: + audio_chunks.append(bytes(buffer[:bytes_read])) + total_bytes += bytes_read except Exception as e: print("Recording failed:", e) finally: @@ -186,12 +191,12 @@ def main(): if mclk_pwm: mclk_pwm.deinit() - print(f"Recorded {total_bytes} bytes to '{filename}'.") + print(f"Recorded {total_bytes} bytes in RAM ({len(audio_chunks)} chunks).") # Wait for release of key/trigger to debounce time.sleep_ms(200) - # 4. Playback + # 4. Playback from RAM if display: display.clear(0) if board_config.BOARD_TYPE == 'WAVESHARE_RLCD': @@ -206,7 +211,7 @@ def main(): display.text(f"Bytes: {total_bytes}", 10, 80, 1) display.show() - play_raw_pcm(filename, channels=2, rate=16000, bits=16, volume=95) + play_ram_pcm(audio_chunks, channels=2, rate=16000, bits=16, volume=95) if display: display.clear(0) diff --git a/hardware_findings.md b/hardware_findings.md new file mode 100644 index 0000000..f8a20ea --- /dev/null +++ b/hardware_findings.md @@ -0,0 +1,32 @@ +# Waveshare ESP32-S3-RLCD-4.2 & ES7210 Microphone Diagnostics + +This document outlines the root causes of the audio recording failures and hardware crashes we encountered with the Waveshare ESP32-S3 board and its onboard ES7210 microphone array, along with their solutions. + +## 1. I2S Bit-Depth Mismatch (The "Static Noise" Issue) +**Problem:** The audio captured by the board was entirely flat or unrecognizable static noise. The audio signal sent to the Whisper pipeline had extremely low RMS levels (25-120), leading to transcription timeouts. +**Root Cause:** The ES7210 microphone ADC was configured via its internal registers to stream **24-bit** audio (Register `0x11` was set to `0x00`). However, the ESP32's I2S hardware peripheral was configured to receive **16-bit** audio. The ESP32 sliced the 24-bit audio frames into misaligned 16-bit chunks, completely destroying the waveform. +**Solution:** Modified `audio_util.py` to write `0x60` to Register `0x11`. This locks the ES7210 into native 16-bit Standard I2S output, perfectly aligning it with the ESP32's buffer. + +## 2. I2C Bus Deadlocks (The "Bootloop / Hang" Issue) +**Problem:** The board would frequently hang during the boot sequence or when attempting to re-initialize the audio components. This occurred primarily after soft-reboots or abrupt script terminations. +**Root Cause:** The ES7210 chip does not gracefully release the I2C SDA (data) line if communication is interrupted midway. When the ESP32 soft-reboots, the SDA line remains held low by the ES7210, which permanently hangs the ESP32's internal I2C driver on the next boot attempt. +**Solution:** Added a manual 9-clock I2C hardware recovery sequence to `board_config.py`. Before the `SoftI2C` interface is initialized, the ESP32 manually toggles the SCL pin 9 times as an output to force the ES7210 to release the SDA line, followed by generating a standard I2C STOP condition. + +## 3. Incorrect I2C Pin Assignments (The "ENODEV" Issue) +**Problem:** The audio configuration would occasionally fail with `OSError: [Errno 19] ENODEV`, indicating the I2C bus could not find the microphone at address `0x40`. +**Root Cause:** The dynamic board-detection logic in `board_config.py` was originally configured to scan for I2C devices on pins 15 and 16 (the default for the Hosyond board). The Waveshare RLCD board uses pins 13 and 14 for the audio I2C bus. +**Solution:** Hardcoded the correct I2C pins (SDA=13, SCL=14) for the Waveshare board profile and ensured the I2C scan and initialization processes execute on the correct pins. + +## 4. Invalid OSR & Clock Division (The "Popping Sound" Issue) +**Problem:** Even when I2S and I2C connected successfully, the recorded audio consisted only of loud, constant popping and clipping at max/min bounds (amplitude 32768), with no recognizable voice signal. +**Root Cause:** The ES7210 microphone ADC was initialized with an incorrect clock and oversampling configuration: +1. Register `0x07` was written with `0x40` to select an oversampling ratio (OSR) of 64. However, the register allocation for `ADC_OSR` is only 6 bits (`bits 5:0`), meaning `0x40` overflowed and set the OSR value to `0`, causing the internal modulator state machines to malfunction. +2. Register `0x02` was configured as a flat division of 12 (`0x0C`), which failed to route and clock the delta-sigma modulators properly. +**Solution:** We analyzed the official C++ implementation of the ES7210 driver in the ESPHome repository (`es7210.cpp` and `es7210_const.h`). By cross-referencing its clock coefficient lookup table for a 12.288MHz Master Clock and 16kHz sample rate, we retrieved the correct register values. We modified `audio_util.py` to match this C++ clock configuration: +* Set OSR configuration register `0x07` to `0x20` (OSR = 32). +* Set main clock control register `0x02` to `0xC3` (enables clock doubler, sets multiply by 2 via bits 7:6 = `11`, and sets division to 3 via bits 4:0 = `0x03`). +* Configured LRCK divider registers `0x04`/`0x05` to `0x03` and `0x00` (division factor of 768). +* Gated unused clocks by writing `0x34` to Register `0x01` (keeps only active ADC12 channels and master MCLK active). +* Corrected the power sequence by initially clearing all MIC bias and PGA settings (`0xFF` to `0x4B`/`0x4C`) before enabling MIC1 and MIC2. + + diff --git a/lib/audio_util.py b/lib/audio_util.py index d805a11..7ea45bf 100644 --- a/lib/audio_util.py +++ b/lib/audio_util.py @@ -13,6 +13,12 @@ class ES7210: def __init__(self, i2c): self.i2c = i2c + def _write(self, reg, val): + self.i2c.writeto_mem(self.ADDR, reg, bytes([val])) + + def _read(self, reg): + return self.i2c.readfrom_mem(self.ADDR, reg, 1)[0] + def init(self, sample_rate=16000, bit_width=16): """Initializes the ES7210 registers for dual-microphone recording. @@ -23,45 +29,85 @@ class ES7210: Returns: bool: True if initialization was successful, False otherwise. """ - print("Initializing ES7210 Microphone ADC...") + print("Initializing ES7210 Microphone ADC (ESPHome sequence)...") try: - # 1. Reset the chip - self._write(0x00, 0xFF) # Write all 1s to reset register - time.sleep_ms(10) - self._write(0x00, 0x00) # Release reset + # 1. Software reset + self._write(0x00, 0xFF) + time.sleep_ms(20) + self._write(0x00, 0x32) + time.sleep_ms(20) + self._write(0x01, 0x3F) # Clock off during config - # 2. Power management and system configuration - self._write(0x01, 0x00) # Enable analog power, reference voltage - self._write(0x11, 0x60) # Enable master clock PLL + # 2. Timing control + self._write(0x09, 0x30) + self._write(0x0A, 0x30) - # 3. Configure Clock Dividers - if sample_rate == 16000: - self._write(0x02, 0x0C) # BCLK divider - self._write(0x03, 0x10) # LRCK divider - else: # 44100 / 48000 defaults - self._write(0x02, 0x04) - self._write(0x03, 0x08) + # 3. High-pass filter + self._write(0x23, 0x2A) + self._write(0x22, 0x0A) + self._write(0x20, 0x0A) + self._write(0x21, 0x2A) + + # 4. Mode config: clear bit 0 of Reg 0x08 + val08 = self._read(0x08) + self._write(0x08, val08 & ~0x01) + + # 5. Configure analog power + self._write(0x40, 0xC3) + + # 6. Mic bias voltage + self._write(0x41, 0x70) + self._write(0x42, 0x70) + + # 7. Configure I2S format (16-bit, standard I2S, TDM disabled) + self._write(0x11, 0x60) + self._write(0x12, 0x00) + + # 8. Configure sample rate (16kHz with 12.288MHz MCLK) + # adc_div = 0x03, dll = 0x01, doubler = 0x01, osr = 0x20, lrck_h = 0x03, lrck_l = 0x00 + reg02_val = 0x03 | (1 << 6) | (1 << 7) # 0xC3 + self._write(0x02, reg02_val) + self._write(0x07, 0x20) + self._write(0x04, 0x03) + self._write(0x05, 0x00) + + # 9. Clear select bits for MIC gain registers + for i in range(4): + val_gain = self._read(0x43 + i) + self._write(0x43 + i, val_gain & ~0x10) - # 4. Input Configuration (Enable Mics 1 and 2, power down Mics 3 and 4) - self._write(0x47, 0x00) # Enable MIC1 / MIC2 analog front-ends - self._write(0x48, 0xFF) # Power down MIC3 / MIC4 path - self._write(0x49, 0x0A) # Power up PGA (Programmable Gain Amplifier) 1 and 2 - self._write(0x4A, 0x00) # Power down PGA 3 and 4 + # 10. Power down all MIC bias & PGA initially + self._write(0x4B, 0xFF) + self._write(0x4C, 0xFF) - # 5. Microphone Gain Settings (+24dB standard) - # Gain range: 0x00 (0dB) to 0x0F (+45dB) in 3dB steps. 0x08 = +24dB. - self._write(0x43, 0x08) # Set MIC1 Gain (+24dB) - self._write(0x44, 0x08) # Set MIC2 Gain (+24dB) + # 11. Configure MIC1 and MIC2 (gain = 30dB -> 0x0A, enable SELMIC) + gain_reg_val = 0x0A + # Enable ADC12 clocks + val01 = self._read(0x01) + self._write(0x01, val01 & ~0x0B) + # Power on MIC1/2 bias, ADC, PGA + self._write(0x4B, 0x00) + # Select MIC1 and gain + val43 = self._read(0x43) + self._write(0x43, (val43 & ~0x0F) | 0x10 | gain_reg_val) + # Select MIC2 and gain + val44 = self._read(0x44) + self._write(0x44, (val44 & ~0x0F) | 0x10 | gain_reg_val) - # 6. Set Digital Interface Format (I2S standard format) - # Bit width: 0x00 = 24-bit, 0x01 = 16-bit, 0x02 = 8-bit, 0x03 = 32-bit - fmt = 0x01 if bit_width == 16 else 0x00 - self._write(0x13, fmt) # Set serial output interface format - self._write(0x14, 0x18) # Enable frame clock / bit clock output + # 12. Power on mics low power registers + self._write(0x47, 0x08) + self._write(0x48, 0x08) + self._write(0x49, 0x08) + self._write(0x4A, 0x08) - # 7. Unmute ADCs and enable output - self._write(0x12, 0x00) # Enable ADC digital filters (unmute) - self._write(0x15, 0x30) # Enable output data pin (SDOUT) active + # 13. Power down DLL + self._write(0x06, 0x04) + + # 14. Enable device state machine + self._write(0x00, 0x71) + time.sleep_ms(20) + self._write(0x00, 0x41) + time.sleep_ms(100) print("ES7210 initialization complete.") return True @@ -69,9 +115,6 @@ class ES7210: print(f"Failed to initialize ES7210: {e}") return False - def _write(self, reg, val): - self.i2c.writeto_mem(self.ADDR, reg, bytes([val])) - def record_audio(duration_seconds=10, filename='recording.pcm'): """Records raw stereo PCM data from the dual microphones to a file. @@ -120,6 +163,7 @@ def record_audio(duration_seconds=10, filename='recording.pcm'): # Create reading buffer (reads 100ms chunks: 16000 samples/sec * 2 channels * 2 bytes/sample * 0.1s = 6400 bytes) buffer = bytearray(6400) + mono_buf = bytearray(3200) # Half size for mono extraction start_time = time.time() total_bytes = 0 @@ -130,8 +174,15 @@ def record_audio(duration_seconds=10, filename='recording.pcm'): # Read raw stereo PCM data from I2S bytes_read = i2s.readinto(buffer) if bytes_read > 0: - f.write(buffer[:bytes_read]) - total_bytes += bytes_read + # Stereo-to-mono: extract left channel (every other 16-bit sample) + mono_len = bytes_read // 2 + j = 0 + for i in range(0, bytes_read, 4): + mono_buf[j] = buffer[i] + mono_buf[j + 1] = buffer[i + 1] + j += 2 + f.write(mono_buf[:mono_len]) + total_bytes += mono_len print(f"Recording saved successfully to '{filename}' ({total_bytes} bytes).") return True diff --git a/lib/board_config.py b/lib/board_config.py index 124faaa..aad9017 100644 --- a/lib/board_config.py +++ b/lib/board_config.py @@ -34,6 +34,26 @@ audio_amp_pin = None audio_amp_active_level = 0 # 0 = Active Low, 1 = Active High audio_mic_codec = "ES8311" # "ES7210" or "ES8311" +def _i2c_recovery(sda_pin, scl_pin): + import time + scl = Pin(scl_pin, Pin.OUT) + sda = Pin(sda_pin, Pin.OUT) + scl.value(1) + sda.value(1) + time.sleep_ms(1) + for _ in range(9): + scl.value(0) + time.sleep_ms(1) + scl.value(1) + time.sleep_ms(1) + scl.value(0) + sda.value(0) + time.sleep_ms(1) + scl.value(1) + time.sleep_ms(1) + sda.value(1) + time.sleep_ms(1) + def detect_board(): global BOARD_TYPE, DISPLAY_TYPE, DISPLAY_WIDTH, DISPLAY_HEIGHT global spi_bus, i2c_bus, display_instance, touch @@ -60,6 +80,7 @@ def detect_board(): # Setup Touch: FT6336U on I2C(1) try: + _i2c_recovery(2, 3) touch_i2c = I2C(1, sda=Pin(2), scl=Pin(3), freq=400000) from ft6336u import FT6336U touch = FT6336U(touch_i2c, rst_pin=28, int_pin=25) @@ -73,6 +94,7 @@ def detect_board(): # Try scanning SDA=16, SCL=15 (Hosyond pins) try: + _i2c_recovery(16, 15) test_i2c = SoftI2C(sda=Pin(16), scl=Pin(15)) devices = test_i2c.scan() if 0x38 in devices: @@ -121,6 +143,7 @@ def detect_board(): # 3. Try scanning SDA=13, SCL=14 (Waveshare RLCD pins) try: + _i2c_recovery(13, 14) test_i2c = SoftI2C(sda=Pin(13), scl=Pin(14)) devices = test_i2c.scan() if 0x70 in devices or 0x51 in devices: diff --git a/main.py b/main.py index e199bde..7852167 100644 --- a/main.py +++ b/main.py @@ -366,19 +366,20 @@ def main(): except Exception as e: print("Failed to set mic gain:", e) - # 2. Configure I2S RX for recording (Mono 16kHz) + # 2. Configure I2S RX for recording (Stereo 16kHz — ES7210 outputs stereo) i2s_rx = I2S(1, sck=Pin(board_config.audio_i2s_sck), ws=Pin(board_config.audio_i2s_ws), sd=Pin(board_config.audio_i2s_rx_sd), mode=I2S.RX, - ibuf=8000, + ibuf=16000, rate=16000, bits=16, - format=I2S.MONO) + format=I2S.STEREO) total_data_bytes = 0 - buffer = bytearray(1024) + buffer = bytearray(2048) + mono_buf = bytearray(1024) # Half size for mono extraction rec_start_time = time.ticks_ms() max_rec_duration_ms = 10000 # 10 seconds max duration @@ -395,8 +396,15 @@ def main(): # Read I2S chunk bytes_read = i2s_rx.readinto(buffer) if bytes_read > 0: - f.write(buffer[:bytes_read]) - total_data_bytes += bytes_read + # Stereo-to-mono: extract left channel (every other 16-bit sample) + mono_len = bytes_read // 2 + j = 0 + for i in range(0, bytes_read, 4): + mono_buf[j] = buffer[i] + mono_buf[j + 1] = buffer[i + 1] + j += 2 + f.write(mono_buf[:mono_len]) + total_data_bytes += mono_len except Exception as e: print("Error recording:", e) finally: