mcp_screen/hardware_findings.md

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.