Architecture & Troubleshooting Guide

March 9, 2026 · View on GitHub

Hardware

Board: M5Stack Atom Echo (ESP32-PICO-D4)
Microphone: SPM1423 PDM MEMS (built-in)
Audio: 16-bit PCM, 16kHz mono (configurable 8–48kHz)
Streaming: RTSP/RTP over TCP, port 8554

Pin Configuration

I2S_BCLK_PIN    = 19  // Bit Clock
I2S_LRCLK_PIN   = 33  // Left-Right Clock / Word Select
I2S_DATA_IN_PIN = 23  // Microphone Data Input (PDM)
I2S_DATA_OUT_PIN = 22 // Speaker Data Output (not used)

Architecture

Dual-Core Design (v2.3.0)

Core 1: Complete audio pipeline (I2S capture → HPF → AGC → gain → RTP → WiFi) + RTSP keepalive/TEARDOWN processing
Core 0: Web UI, RTSP negotiation, diagnostics, client management

Core 1 exclusively owns the WiFiClient socket during streaming — Core 0 never touches it:

Core 0 handles RTSP negotiation (OPTIONS → DESCRIBE → SETUP → PLAY)
On PLAY, Core 0 hands off the socket to Core 1 via streamClient pointer with memory barrier
Core 1 reads audio, processes, sends RTP packets, and handles RTSP keepalives/TEARDOWN
On disconnect, Core 1 closes the socket itself; Core 0 detects the transition and updates LED/logs
When Core 0 needs to stop streaming (TEARDOWN, overheat, WiFi loss), it signals via requestStreamStop() and waits for Core 1 to confirm cleanup

Cross-Core Safety

FreeRTOS semaphore with 2s timeout for confirmed task exit
portMUX_TYPE spinlock for shared log buffer
Xtensa memw memory barriers on critical flag transitions
core1OwnsLED flag prevents concurrent FastLED/RMT driver access

Audio Tuning

Signal Levels

Target: 30–70% (about -10 to -3 dBFS)
LED green: Good level
LED orange: Getting hot — consider reducing gain
LED red: Clipping — reduce gain immediately
LED dim purple: Very quiet — increase gain or enable AGC

AGC vs Manual Gain

AGC OFF: Consistent, predictable levels (e.g., close-range recording)
AGC ON: Outdoor BirdNET-Go deployment where bird distance varies. AGC multiplies on top of your manual gain setting.

Buffer Size Profiles

Size	Latency	Stability	Use Case
256	16ms	Low	Ultra-low latency, may drop packets
512	32ms	Medium	Balanced for good WiFi
1024	64ms	High	Recommended — stable streaming
2048+	128ms+	Very High	Poor WiFi, maximum stability