RealDeco/xiaozhi-esphome

ESPHome에서 Xiaozhi AI 기기를 Home Assistant용 음성 비서 새틀라이트로 사용하세요.

현재 개발 중인 버전은 다음 링크를 사용하세요:

Modular (모듈형)

ESPHome 2026.4+ 버전용

Modular with Sendspin (Sendspin을 포함한 모듈형)

ESPHome 2026.5.0b2 버전용

Devices/<device_name>/ 디렉토리 내의 YAML 파일들은 데모 설정 파일이며 구식일 수 있지만, 기기를 식별하는 데 유용합니다.

요청에 따라, 이 GitHub 프로젝트는 Xiaozhi 기반 기기를 ESPHome과 함께 사용하는 간단한 방법을 제공합니다. 이 소형 기기들은 Home Assistant와 통합된 음성 비서 역할을 할 수 있습니다.

기기 연결하기: USB를 통해 기기를 컴퓨터에 연결합니다. ESPHome Web을 열고 “+ NEW DEVICE”를 클릭한 다음, 안내에 따라 설정을 완료하고 Wi-Fi에 연결합니다.

• ESPHome Builder에서, **새로 발견된 기기를 제어(take over)**하고, 설정을 편집한 뒤, 기기용 코드를 붙여넣되 원래 기기의 name은 그대로 유지하세요. (friendly_name은 원하는 대로 사용자 정의할 수 있습니다.) 저장 및 무선(wirelessly)으로 설치를 진행하세요. 기기가 재부팅되고 코드가 실행될 때까지 기다립니다.

• 기기가 온라인 상태가 되면, Home Assistant > Devices로 이동하여 **새 기기를 수락(accept)**하세요. 그러면 음성 비서 설정 프로세스가 시작됩니다.

3단계 참고 사항: 무선 설치에 실패하여 USB 플래싱(flashing)을 사용하라는 메시지가 뜨는 경우:

• 필요한 경우 기기를 컴퓨터에 다시 연결하세요.
• 다시 저장 및 설치를 진행하되, “Plug into this computer”를 선택합니다. 펌웨어가 컴파일되고 다운로드될 때까지 기다린 후, ESPHome Web을 사용하여 USB를 통해 설치하세요. 이는 파티션 테이블(partition table)을 업데이트해야 하는 첫 번째 실행 시에만 발생합니다. 향후 업데이트는 무선으로 수행할 수 있습니다.

기기의 ESPHome 설치 과정을 담은 영상은 YouTube에 의해 삭제되었고 제 계정도 차단되었습니다. 참으로 이상한 세상입니다.

• Espressif EchoEar v1.0
• Espressif EchoEar v1.2
• Spotpear Ball v1
• Spotpear Ball v2
• Spotpear Muma Box v1
• Spotpear Muma Box v2
• Spotpear Muma Horse v1
• Spotpear Muma Horse v2
• Spotpear Puck
• DIY (브레드보드)
• Guition 1.8" Taichi pi (JC3636W518C) v1 (2025년 7월 이후 단종)
• Guition 1.8" Taichi pi (JC3636W518C) v2
• Xingzhi Cube 1.54
• "Breadboard Mini", 모든 것이 온보드된 $7짜리 커스텀 ESP32-S3
• Waveshare 2.06" OLED 손목시계
• Waveshare ESP32-S3-Touch-LCD-1.85C v1
• Waveshare ESP32-S3-Touch-LCD-1.85C v2
• Waveshare ESP32-S3-Touch-LCD-3.49
• Waveshare ESP32-P4-86-Panel-ETH-2RO
  신규 - Waveshare 오디오 보드
  신규 - Guition 4.3C
  신규 - Guition 7.0
  신규 - Freenove 2.8
  신규 - Waveshare amoled 1.75
  신규 - Xingzhi Cube 1.83 2-Mic
  신규

(새로운 장치는 테스트 중 모듈식 버전에서 먼저 나타납니다.)

EchoEar: https://www.aliexpress.com/item/1005009834934442.html

Ball v1 & v2: https://vi.aliexpress.com/item/1005008627679270.html
alternative link: https://www.aliexpress.com/item/1005009762104155.html
Muma Box: https://vi.aliexpress.com/item/1005009043526078.html
Muma Horse: https://vi.aliexpress.com/item/1005008884232596.html
Puck: https://www.aliexpress.com/item/1005009016529496.html

Guition Taichi pi: https://vi.aliexpress.com/item/1005007420092928.html
Xingzhi Cube 1.54: https://www.aliexpress.com/item/1005008565082769.html

Breadboard: devices/Breadboard에서 확인하세요: https://github.com/RealDeco/xiaozhi-esphome/tree/main/devices/Breadboard

Breadboard Mini: https://www.aliexpress.com/item/1005009448496585.html

Waveshare 2.06" OLED 손목시계: https://vi.aliexpress.com/item/1005009516438849.html

Waveshare ESP32-S3-Touch-LCD-1.85C: https://www.aliexpress.com/item/1005008634826817.html

Waveshare ESP32-S3-Touch-LCD-3.49: https://www.aliexpress.com/item/1005009894437640.html

Waveshare ESP32-P4-86-Panel-ETH-2RO: https://www.aliexpress.com/item/1005009197112179.html

Waveshare Audio Board: https://www.aliexpress.com/item/1005009819735457.html

Guition P4 4.3C: https://www.aliexpress.com/item/1005009673625472.html

Guition P4 7.0: https://www.aliexpress.com/item/1005010022828767.html

Freenove 2.8": https://www.aliexpress.com/item/1005009876628479.html

Xingzhi Cube 1.83 2-mic: https://www.aliexpress.com/item/1005010442374066.html

Waveshare amoled 1.75: https://www.aliexpress.com/item/1005008989323572.html

4인치용 후면 케이스 (벽걸이)으로 데스크톱 사용에 적합합니다. https://www.aliexpress.com/item/1005006149480110.html

위 이미지의 볼(Ball)을 고정하는 데 사용되는 'Eggvenger' 피규어 3D 파일입니다. v2는 v1보다 크므로 115%를 사용하세요. https://makerworld.com/en/models/1238732-eggvenger-superhero-egg-holder

Guition JC3636W518 디스플레이용 무선 충전기 거치대 3D 파일입니다. https://makerworld.com/en/models/238543-wireless-charger-holder

Guition JC3636W518 디스플레이용 무선 충전기: https://vi.aliexpress.com/item/1005005066837741.html

Guition JC3636W518 디스플레이용 코일 오디오 케이블: https://vi.aliexpress.com/item/1005007061609551.html

Freenove 2.8"용 케이스 (올바른 인쇄 프로필을 선택하는 것을 기억하세요): https://makerworld.com/en/models/1382304-aura-smart-weather-forecast-display

다른 3D 파일은 여기에서 확인하세요: https://github.com/RealDeco/xiaozhi-esphome/tree/main/3D_Files