original site: https://github.com/heytcass/louder-esphome-sendspin

heytcass (Tom Cassady): Homelabber & Open Source Advocate

Tom Cassady, known as heytcass, is a Detroit-based Technical Writer and self-taught "Homelabber" dedicated to bridging the gap between complex technology and everyday life. Since 2015, he has been a prominent figure in the Home Assistant community, specializing in YAML and AI integrations to create smarter, more efficient living spaces.

Core Expertise

The HomeLab: Treats his home as a laboratory for server management, network configuration, and self-hosting.

Open Source Advocacy: Champions transparency by meticulously documenting project files and troubleshooting steps for the community.

Technical Writing: Leverages his professional background to craft clear, approachable guides that explain both the "how" and the "why."

Key Project: louder-esphome-sendspin

Tom’s expertise in hardware-software integration is best showcased in his louder-esphome-sendspin project.

Innovation: Developed firmware configurations for the Sonocotta Louder-ESP32S3 hardware using ESPHome.

Impact: Enabled high-fidelity, synchronized multi-room audio with advanced room correction, making professional-grade sound accessible to Home Assistant users.

Conclusion

Driven by curiosity and a commitment to shared knowledge, heytcass continues to innovate at the intersection of smart home technology and community support, empowering others to build their own connected worlds.

The image Gemini made

1) Introduction

heytcass는 GitHub 프로필에서 자신을 독학으로 기술을 익힌 homelabber이자 오픈소스 지향 개발자로 소개한다. 또한 기술과 글쓰기를 배경으로 갖고 있으며, 2015년 3월부터 Home Assistant 커뮤니티에서 활동해 왔고 YAML에 익숙하다고 밝히고 있다. 이 점은 단순히 코드만 작성하는 개발자가 아니라, 설정 기반 자동화와 문서화 능력을 함께 갖춘 메이커라는 뜻이다.

이번 프로젝트가 흥미로운 이유는 단순한 “ESP32 오디오 보드 활용기”가 아니기 때문이다. 기존 maker.wiznet.io에서 소개된 Sonocotta의 Louder 계열은 오픈 하드웨어/펌웨어 기반의 ESP32 오디오 생태계로 설명되었고, heytcass의 louder-esphome-sendspin 저장소는 그 하드웨어를 Sendspin 멀티룸 오디오 엔드포인트, Home Assistant 미디어 플레이어, 룸 보정 실험 플랫폼으로 한 단계 더 확장한다. 즉, 하드웨어 소개에서 끝나지 않고 실제 생활형 네트워크 오디오 시스템으로 발전한 사례다.

이 흐름을 더 넓게 보면 heytcass의 관심사는 “ESP32 기기 하나”가 아니라 ESPHome 기반 장치 생태계 전체로 확장되고 있다. 그의 esphome-device-library는 커뮤니티가 유지보수하는 ESPHome 장치 구성 라이브러리를 표방하며, 최신 ESPHome 관행, 모듈식 구조, OTA 업데이트 가능성을 강조한다. 그리고 이 라이브러리 안에는 이미 Sonocotta Louder ESP32-S3용 adoptable configuration이 포함되어 있다. 즉, 개별 프로젝트 실험이 다시 재사용 가능한 장치 라이브러리로 환원되는 구조다.

여기에 CLAUDE.md가 더해지면서 개발 방식의 변화도 보인다. louder-esphome-sendspin 저장소의 CLAUDE.md는 이 리포지토리를 Claude Code가 이해하고 작업할 수 있도록 안내하는 문서이며, 별도 home-assistant-addons 저장소에서는 아예 Claude Code CLI가 미리 설치된 Claude Terminal add-on을 제공한다. 이를 종합하면 heytcass는 YAML/ESPHome 중심 개발에서 출발해, 이제는 AI가 저장소 구조·테스트·문서까지 함께 다루는 개발 환경으로 이동하고 있다고 해석할 수 있다. 이 마지막 문장은 저장소 문서와 부가 프로젝트를 바탕으로 한 해석이다.

이 글이 다루는 핵심 변화

• ESP32/ESPHome 중심 메이커 활동
• Sonocotta Louder-ESP32S3 하드웨어 채택
• Sendspin 기반 멀티룸 오디오 엔드포인트 구현
• TAS5805M DSP를 활용한 룸 보정
• Claude Code 친화적 저장소 문서와 개발 워크플로 도입 

2) Required Components

저장소 README와 CLAUDE.md 기준으로 이 프로젝트의 핵심 하드웨어는 Sonocotta Louder-ESP32S3 보드, W5500 SPI Ethernet 모듈(권장), 128x64 OLED(SPI), 패시브 스피커, 65W USB-C PD 전원이다. 소프트웨어 측면에서는 ESPHome, Home Assistant, Sendspin 베타 구성 요소, 그리고 선택적으로 룸 보정용 웹 UI가 포함된다.

Hardware

• Sonocotta Louder-ESP32S3
• WIZnet W5500 SPI Ethernet module
• 128x64 SSD1306/SH1106 OLED display
• Passive speakers
• 65W USB-C PD power supply
• USB cable for flashing

Software

• ESPHome
• Home Assistant
• Sendspin-compatible environment
• Optional room-correction web UI (calibrate.html, index.html) 

3) Hardware Setup

이 프로젝트의 하드웨어 구성은 단순하다. ESP32-S3가 네트워크 오디오 제어와 ESPHome 런타임을 담당하고, TAS5805M 클래스-D 앰프/DAC가 실제 오디오 출력을 담당하며, SPI OLED가 현재 재생 정보를 표시한다. 여기에 W5500을 사용하면 무선 대신 유선 기반으로 안정적인 스트리밍을 노릴 수 있다. README는 W5500을 “reliable, low-latency streaming”을 위한 구성으로 설명하고 있다.

특히 heytcass는 이 보드를 단순 스피커로만 쓰지 않았다. Sendspin 소스, resampler, mixer, I2S speaker, TAS5805M까지 이어지는 오디오 파이프라인을 구성해 멀티룸 재생, 공지/알림 ducking, EQ 제어, 메타데이터 표시, 선택적 룸 보정을 한 시스템 안에 통합했다. 이것이 Sonocotta 하드웨어를 “제품”에서 “플랫폼”으로 바꾸는 지점이다.

4) Interface Explanation

4-1. I2S: 디지털 오디오 출력 경로

핵심 오디오는 Sendspin → Resampler → Mixer → I2S → TAS5805M → Speakers 구조로 흐른다. 저장소 문서에 따르면 LRCLK는 GPIO15, BCLK는 GPIO14, DOUT는 GPIO16을 사용하며, ESP32-S3가 만든 PCM 오디오 스트림이 I2S를 통해 TAS5805M으로 전달된다. 이 단계가 실제 음질과 지연시간을 결정하는 핵심 구간이다.

4-2. I2C: TAS5805M 제어 및 DSP 설정

I2C는 단순 센서 연결용이 아니라 오디오 DSP 제어 채널로 쓰인다. heytcass는 tas5805m_biquad_i2c.h와 tas5805m_profile_manager.h를 통해 biquad 계수 쓰기, 프로파일 저장/복원, 부팅 시 활성 프로파일 적용 같은 동작을 설계했다. 문서상 TAS5805M은 채널당 15개, 총 30개의 biquad 필터를 다룰 수 있다.

4-3. SPI: OLED와 문서화된 W5500 확장

SPI는 OLED 디스플레이에 명확히 사용된다. YAML에서 SPI 클럭은 GPIO12, MOSI는 GPIO11, MISO는 GPIO13으로 보이며, OLED 제어는 CS=GPIO47, DC=GPIO38, RST=GPIO48을 사용한다. 저장소 문서와 README는 W5500 Ethernet도 프로젝트의 핵심 요소로 설명하며, CLAUDE.md에는 W5500용 CS=GPIO10, INT=GPIO6, RST=GPIO5가 정리되어 있다. 다만 GitHub에서 확인되는 메인 YAML 스냅샷은 Wi-Fi 테스트용 설정과 OLED SPI 구성을 분명히 보여 주는 반면, W5500용 ethernet: 블록은 문서에서 강조되는 것만큼 직접적으로 드러나지 않는다. 따라서 W5500은 현재 저장소 설명상 핵심 하드웨어이지만, 실제 적용은 문서와 실험 브랜치/구성에 따라 달라질 수 있다.

4-4. Sendspin / Home Assistant: 오디오 서비스 레이어

이 프로젝트는 ESPHome 베타 기능과 외부 컴포넌트에 크게 의존한다. sendspin, mixer, resampler, media_player, file, http_request, speaker_source 등의 기능이 외부 PR 또는 베타 컴포넌트에서 끌어와지고, Home Assistant에서는 미디어 플레이어 엔티티, EQ 숫자 엔티티, 각종 서비스 호출을 통해 장치를 제어한다. 이 구조 덕분에 단순 재생기보다 훨씬 높은 확장성을 확보한다.

5) Wiring Table

아래 표는 저장소 문서에 정리된 GPIO 매핑을 기준으로 재구성한 것이다. OLED 쪽은 YAML에서도 직접 확인되고, W5500 핀은 CLAUDE.md에 문서화되어 있다.

6) Software Environment Setup

louder-esphome-sendspin 저장소는 기본적으로 ESPHome 명령 기반 빌드/업로드 워크플로를 사용한다. CLAUDE.md에는 esphome run, esphome compile, esphome logs가 핵심 명령으로 안내되어 있으며, README 역시 secrets.yaml을 준비한 뒤 메인 YAML을 플래싱하는 방식으로 시작한다. 즉, 사용자는 복잡한 IDE보다 ESPHome 중심의 선언형 워크플로로 접근할 수 있다.

반면 heytcass의 broader workflow는 여기서 한 단계 더 간다. esphome-device-library는 NixOS development environment를 전면에 내세우고, home-assistant-addons의 CLAUDE.md는 nix develop, direnv, Podman 기반 컨테이너 테스트, 그리고 Claude Terminal add-on 빌드/실행 절차까지 상세히 적어 두고 있다. 즉, heytcass의 개발 환경은 “YAML 파일 편집”에서 멈추지 않고, 재현 가능한 셸 환경 + 컨테이너 테스트 + AI 협업 문서화 쪽으로 이동 중이다. 이 부분은 여러 저장소를 종합한 해석이다.

Recommended Setup Flow

1. GitHub 저장소 클론
2. secrets.yaml.example 기반으로 비밀정보 파일 작성
3. ESPHome 설치
4. 기본 빌드/컴파일 확인
5. Home Assistant 통합
6. OLED / 오디오 / 룸 보정 기능 순차 검증
7. 필요 시 Claude Code용 저장소 문서(CLAUDE.md)를 함께 유지 

7) Full Code Examples

아래 예제는 저장소의 YAML 구조, README 설명, CLAUDE.md 내용을 바탕으로 설명용으로 재구성한 축약 버전이다. 실제 저장소는 외부 컴포넌트, room correction 서비스, HTML UI, 프로파일 저장 코드까지 포함하므로 더 크다.

7-1. Main ESPHome Configuration Example

7-2. Optional Room-Correction Concept

문서 기준으로 룸 보정은 packages로 포함되며, parametric EQ·shelf·notch·highpass·lowpass·profile management 서비스를 Home Assistant 쪽에 노출한다. 즉, 오디오 보드가 단순 앰프가 아니라 현장 보정 가능한 DSP 노드가 된다.

7-3. Example Home Assistant Service Call

README에 따르면 특정 방 모드를 줄이기 위해 Home Assistant 서비스로 biquad를 설정할 수 있다. 아래 예시는 그 개념을 단순화한 것이다.

7-4. Optional W5500 Block Example

저장소 문서상 W5500 핀은 정리되어 있지만, GitHub에서 바로 확인되는 메인 YAML에는 Ethernet 블록이 선명하게 노출되지 않는다. 아래는 문서화된 핀을 바탕으로 한 구성 예시다. 실제 적용 시 저장소 최신 상태에 맞춰 조정해야 한다.

8) Testing Steps

테스트는 한 번에 끝내기보다 기능을 층별로 분리해야 한다. 먼저 esphome compile로 외부 컴포넌트와 문법 오류를 확인하고, 그 다음 실제 플래싱 후 로그를 통해 PSRAM, I2C, Sendspin, 디스플레이 초기화를 점검한다. 저장소 문서에는 부팅 시 startup sync sound를 재생해 DSP 설정이 적용될 수 있도록 하는 흐름도 포함되어 있다.

Recommended Validation Order

1. Compile check
   esphome compile louder-s3-sendspin-ethernet-oled.yaml
2. Flash and run
   esphome run louder-s3-sendspin-ethernet-oled.yaml
3. Log check
   esphome logs louder-s3-sendspin-ethernet-oled.yaml
4. Home Assistant discovery
5. Track metadata on OLED
6. Sendspin playback
7. Announcement ducking test
8. Optional room correction UI test (/calibrate) 

README는 휴대폰으로 /calibrate 페이지를 열고 청취 위치에서 측정한 뒤 필터를 적용하는 흐름을 제시한다. 이 과정이 제대로 동작하면 heytcass의 프로젝트는 단순한 ESP32 오디오 예제를 넘어, 실제 실내 음향 보정까지 포함한 생활형 오디오 장치가 된다.

9) Troubleshooting

저장소 README는 대표적인 문제를 네 가지 축으로 정리한다. 오디오가 안 나올 때, 드롭아웃이 있을 때, OLED가 표시되지 않을 때, 룸 보정이 적용되지 않을 때다. 특히 스트리밍 안정성 측면에서는 Wi-Fi보다 Ethernet 사용을 권장하고, 룸 보정 쪽은 I2C 로그와 DAC 활성 상태 확인을 강조한다.

Common Issues

• No audio playback
  • Sendspin 서버 동작 여부 확인
  • DAC 활성 상태 확인
  • ESPHome 로그 확인
• Audio dropouts
  • 가능하면 W5500 유선 연결 사용
  • 네트워크 혼잡 확인
  • PSRAM 인식 여부 확인
• OLED not displaying
  • SPI 배선 확인
  • SH1106 / SSD1306 모델 설정 점검
• Room correction not applying
  • I2C 버스 로그 확인
  • TAS5805M 주소 및 enable 상태 점검 

실무적으로는 기능을 동시에 켜지 말고 단계적으로 켜는 것이 중요하다. 먼저 기본 오디오 재생, 다음 디스플레이, 그 다음 EQ, 마지막으로 룸 보정을 올리는 식으로 접근해야 원인 분리가 쉽다. 이 조언은 저장소 구조를 바탕으로 한 실무적 권장 사항이다.

10) Use Cases & Market Potential

이 프로젝트가 유용한 가장 큰 이유는 상용 스마트 스피커의 장점을 오픈소스 방식으로 재구성한다는 점이다. README는 이를 Sonos Trueplay와 유사한 룸 보정 개념으로 설명하고, 동시에 Sendspin 기반 멀티룸 엔드포인트로 정의한다. 즉, 단일 방 스피커, 멀티룸 싱크 오디오, Home Assistant 연동 TTS/공지, 소규모 커스텀 오디오 기기 제작에 모두 활용될 수 있다.

시장성 측면에서도 의미가 있다. Sonocotta 계열은 이미 maker.wiznet.io에서 오디오 중심 ESP32 생태계로 다뤄졌고, W5500을 결합한 Sonocotta 오디오 게이트웨이 사례 역시 소개된 바 있다. 이것은 ESP32 오디오 + Ethernet + Home Assistant 조합이 단순 취미 프로젝트가 아니라, 안정성이 중요한 홈 오디오·커스텀 설치형 오디오·DIY 멀티룸 제품군으로 확장될 여지가 있음을 보여 준다.

Potential Applications

• Home Assistant 기반 멀티룸 오디오
• DIY 네트워크 스피커
• TTS/공지 스피커
• 책상형 하이브리드 오디오 노드
• 소규모 상업 공간 BGM 장치
• 오디오 DSP 실험 플랫폼 

11) Module/Chip Technical Overview

ESP32-S3

이 프로젝트의 중심 MCU는 ESP32-S3다. 저장소는 esp32-s3-devkitc-1 보드를 기준으로 하며, 16MB flash, 240MHz CPU, octal PSRAM 80MHz 설정, 그리고 스트리밍에 유리한 여러 sdkconfig 최적화를 포함한다. 이는 네트워크 오디오, resampling, OLED 갱신, Home Assistant 연동을 동시에 처리하기 위한 선택이다.

TAS5805M

TAS5805M은 단순 DAC가 아니라 클래스-D 앰프와 DSP 기능이 결합된 오디오 칩으로 사용된다. heytcass의 문서에서는 15-band graphic EQ와 30개 biquad 필터, 프로파일 저장/복원, CRC32 기반 무결성 검증까지 다루고 있다. 즉, 이 칩은 “소리 나는 보드”가 아니라 “설정 가능한 디지털 오디오 처리기”로 취급된다.

W5500

W5500은 이 프로젝트에서 네트워크 안정성을 강화하는 선택지다. README는 저지연·안정적 스트리밍을 위해 Ethernet을 강조하고, maker.wiznet.io의 Sonocotta 오디오 게이트웨이 사례 역시 Wi-Fi 혼잡 환경에서 W5500이 유선 안정성을 제공한다고 설명한다. 멀티룸 오디오에서 순간적인 지연과 드롭아웃은 체감 품질에 바로 영향을 주기 때문에, W5500은 단순 부가 모듈이 아니라 제품 완성도를 올리는 부품으로 볼 수 있다.

OLED Display

OLED는 시스템 상태를 “장치 자체에서” 확인하게 해 준다. 제목, 아티스트, 앨범 같은 메타데이터를 즉시 볼 수 있기 때문에, 이 장치는 무화면(headless) 오디오 노드가 아니라 사용자 피드백이 있는 독립형 오디오 엔드포인트가 된다.

12) Conclusion

heytcass의 louder-esphome-sendspin은 Sonocotta Louder-ESP32S3를 활용한 흥미로운 응용 사례다. 시작점은 Home Assistant와 YAML에 강한 메이커의 개인적 실험처럼 보이지만, 실제 내용은 그보다 훨씬 크다. 이 저장소는 Sonocotta 하드웨어를 ESPHome 기반 멀티룸 스피커, DSP 제어 노드, Home Assistant 서비스 엔드포인트로 재해석한다.

또한 이 프로젝트는 개발 문화의 변화도 보여 준다. 예전의 ESP32 프로젝트가 회로와 YAML에서 끝났다면, heytcass의 최근 흐름은 모듈식 장치 라이브러리, Nix/컨테이너 기반 재현 가능한 환경, Claude Code를 위한 저장소 문서화까지 포괄한다. 즉, 하드웨어 프로젝트가 이제는 코드·문서·AI 협업 규칙까지 포함하는 방향으로 진화하고 있다는 뜻이다.