adolforeyna/mcp_screen
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix(audio): resolve ES7210 microphone popping sound by correcting OSR and clock division configuration

Browse Source
This commit is contained in:
Adolfo Reyna
2026-06-18 22:38:47 -04:00
parent 9eca3549c3
commit d778391c5c
7 changed files with 212 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+9
View File
@@ -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
README.md
+7
View File
@@ -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).
demo_audio_loopback.py
+39 -34
View File
@@ -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)
hardware_findings.md
+32
View File
@@ -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.
lib/audio_util.py
+88 -37
View File
@@ -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
lib/board_config.py
+23
View File
@@ -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:
main.py
+14 -6
View File
@@ -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: