SF32 Xiaozhi 음성 어시스턴트¶

Xiaozhi란 무엇인가?¶

Xiaozhi는 MCP 기반의 오픈소스 음성 챗봇으로, 2025년 ESP32 구현을 통해 널리 알려졌습니다. 음성 상호작용 기기에 클라우드 대규모 언어 모델 서비스와 디바이스 측 또는 클라우드 측 MCP 확장을 결합합니다. 따라서 단순한 텍스트 채팅 애플리케이션이 아니라 대화형 AI 기기를 개발할 때 실용적인 출발점이 됩니다.

왜 SF32 구현인가?¶

78/xiaozhi-sf32는 SF32 구현이지만, 의도적으로 다른 연결 방식을 사용합니다. 원본 ESP32 프로젝트는 Wi-Fi 등의 직접 네트워킹 옵션을 지원하는 반면, SF32 버전은 Classic Bluetooth PAN을 사용하여 페어링된 휴대폰을 통해 인터넷에 접속합니다. 이렇게 하면 광역 연결의 부담이 디바이스에서 휴대폰으로 옮겨지므로, 휴대폰 테더링 설계에서는 디바이스 측 네트워킹 전력을 크게 줄일 수 있습니다. 실제 절감량은 휴대폰, 무선 환경, 대화 듀티 사이클, 전력 정책에 따라 달라집니다. 따라서 SF32 방식은 펜던트, 배지, 소형 어시스턴트, 소형 웨어러블처럼 배터리로 동작하는 개인용 휴대 제품에 특히 적합합니다.

디스플레이와 오디오 하드웨어, 휴대폰이 제공하는 네트워킹, 클라우드 음성 서비스, 사용자 대상 활성화 흐름, 디바이스 제어, 현장 업데이트 기능처럼 흔히 따로 다루는 작업을 하나로 묶고 있어서 제품 레퍼런스로 매우 유용합니다.

목표, 범위, 시작 조건¶

이 페이지는 해당 레퍼런스를 제품 방향에 맞게 적용하기 위한 완전한 엔지니어링 경로입니다. Xiaozhi가 오프라인 온디바이스 LLM이라거나, 업스트림의 모든 기능이 양산 수준으로 검증되었다거나, 지원되는 개발 보드가 인증된 완제품과 동등하다고 주장하지 않습니다. 디바이스는 Bluetooth PAN을 사용하여 페어링된 휴대폰을 통해 인터넷에 접속하고, 대화 흐름은 Xiaozhi 클라우드 서비스에 의존합니다. 제품을 확정하기 전에 서비스 약관, 계정 소유권, 개인정보 보호, 보안, 비용, 가용성, 지역별 적합성을 확인하십시오.

목표: 휴대폰을 통해 프로비저닝하고, 클라우드 기반 대화를 완료하고, 안전한 디바이스 기능 하나를 제어하고, PAN 연결 끊김에서 복구하며, 커스텀 하드웨어 제작 여부를 판단하는 데 필요한 증거를 만들어 내는, 반복 가능한 음성 및 디스플레이 어시스턴트입니다.

대상 독자: 이미 SF32 기준 구성을 빌드하고 플래시에 기록할 수 있으며, C/C++, 보드 회로도, Bluetooth 설정, 클라우드 서비스 연동 작업을 수행할 준비가 된 펌웨어, 하드웨어, 제품 엔지니어입니다.

하드웨어 및 소프트웨어 사양¶

아래 명세는 구체적인 소스 빌드 레퍼런스 하나를 정의합니다. SiFli가 문서화한 외부 디스플레이 및 오디오 회로를 갖춘 SF32LB52-DevKit-Nano-R16N16 V1.0.0입니다. 지원되는 모든 Xiaozhi 보드에 공통으로 적용되는 BOM이 아닙니다. DevKit-ULP, DevKit-LCD 또는 Xiaotangyuan을 선택하는 경우, 이 하드웨어 명세 전체를 해당 보드의 문서화된 구성으로 교체하고 정확한 공급업체 부품과 보드 리비전을 유지하십시오.

하드웨어 사양¶

위의 서드파티 부품 URL은 공식 SiFli Nano 가이드에 게시된 마켓플레이스 링크이며, 제조업체 부품 번호를 영구적으로 보증하는 것이 아닙니다. 평가한 부품의 스크린샷이나 주문 기록을 보존하고, 제품 설계 전에 각 마켓플레이스 의존 항목을 검증된 공급업체 부품 번호와 데이터시트로 교체하십시오.

소프트웨어 사양¶

지원되는 기준 구성 선택¶

SiFli Xiaozhi 퀵 스타트 문서에는 사전 빌드 펌웨어 타깃이 네 가지로 나열되어 있습니다. SF32LB52-DevKit-ULP(Huangshan), SF32LB52-DevKit-LCD, SF32LB52-DevKit-Nano, Xiaotangyuan 플러그인 보드입니다. 소스 빌드 문서에는 현재 DevKit-ULP, DevKit-LCD, DevKit-Nano가 나열되어 있습니다. 소스 커스터마이징이 프로젝트 요구 사항이라면 소스 빌드 목록에 있는 보드를 선택하십시오. 사전 빌드 이미지가 있다고 해서 문서화된 소스 빌드 타깃이 있다고 가정하면 안 됩니다.

프로젝트 개발 단계와 의사결정 지점¶

각 단계를 기능 체크리스트가 아니라 의사결정 지점으로 사용하십시오. 각 단계는 다음 의사결정을 검토하고 반복할 수 있게 해 주는 산출물을 남깁니다.

시스템 아키텍처와 의존성¶

flowchart LR
    U["사용자: 웨이크 워드 또는 대화 키"] --> D["SF32LB52 디바이스\n마이크, UI, 로컬 제어"]
    D --> E["오디오 파이프라인\n활성화 시 OPUS / AEC / VAD"]
    D <-->|"Classic Bluetooth PAN\nBNEP + IP"| P["페어링된 휴대폰\nBluetooth 인터넷 공유"]
    P <-->|"WebSocket; 일부 HTTP API"| S["Xiaozhi 클라우드 서비스\n스트리밍 ASR / LLM / TTS"]
    S --> P --> D
    D --> O["스피커, 디스플레이,\n디바이스 측 MCP 동작"]

공식 아키텍처 가이드는 네트워크 경로로 Classic Bluetooth 기반의 Bluetooth PAN을 설명하며, 디바이스에서는 경량 IP 네트워킹을 사용합니다. 주요 실시간 애플리케이션 채널은 WebSocket으로, 일부 API 상호작용에는 HTTP를 사용하는 것으로 명시되어 있습니다. SiFli 개요에는 구현된 기능으로 키워드 웨이크업(KWS), 연속 대화, AEC/VAD, 동적 표정, 벡터 폰트, 로컬 MCP가 나열되어 있습니다. 그 밖의 공식 프로젝트 자료에는 디스플레이 UI, 배터리/전원 동작, 클라우드 측 MCP 확장, PAN OTA도 설명되어 있습니다. 선택한 보드와 펌웨어에서 정확한 지원 여부를 확인하십시오.

이 흐름에는 서로 독립적으로 진단해야 하는 네 가지 장애 영역이 있습니다. 로컬 하드웨어/오디오, Bluetooth 페어링과 PAN, 인터넷/클라우드 서비스 도달 가능성, 애플리케이션/서비스 설정입니다. BLE 페어링에 성공했다는 것만으로는 보드가 인터넷에 접속되었다거나 음성 서비스가 활성화되었다는 것이 증명되지 않습니다.

1단계 — 수정하지 않은 레퍼런스 기준 구성 확립¶

1. 보드별 공식 하드웨어 설정을 완료하십시오. DevKit-LCD의 경우 지정된 AMOLED/FPC 배치, SPK에 연결한 스피커, 웨이크/대화용 KEY1, 길게 눌러 전원을 끄는 KEY2가 여기에 포함됩니다.
2. 공식 Xiaozhi 절차에 따라 지원되는 사전 빌드 펌웨어를 플래시에 기록하십시오. 퀵 스타트 가이드는 UI 플래싱 도구를 권장하며, 해당 가이드 작성 시점에는 펌웨어 버전 1.4.0 이상에서 터미널 플래싱이 지원되지 않는다고 밝히고 있습니다.
3. 휴대폰에서 페어링 전에 Bluetooth 인터넷 공유를 활성화하십시오. sifli-pan 디바이스와 페어링한 다음, 보드 UI와 휴대폰의 공유 상태를 확인하여 단순한 Bluetooth 페어링이 아니라 PAN이 활성 상태인지 확인하십시오. iOS의 경우, sifli-pan이 보이지 않으면 휴대폰을 재시작해야 할 수 있다고 공식 가이드에 나와 있습니다.
4. Xiaozhi 콘솔 xiaozhi.me에서 공식 활성화 절차를 따르십시오. 에이전트를 생성/구성하고 보드에 표시되는 디바이스 코드를 추가하십시오.
5. 보드의 대화 키 또는 구성된 웨이크 경로를 사용하여 대화를 한 번 수행하십시오. 프로젝트 기록에 펌웨어 버전, 보드, 휴대폰 모델/OS, 서비스 계정과 에이전트 식별자를 기록하십시오.

게이트 1 종료 기준: 콜드 부트 후 디바이스가 PAN을 수립하고 활성화된 상태를 보고하며, 대화 요청을 받아들이고 응답을 재생하고 기대하는 UI 상태를 표시합니다.

2단계 — 복구 및 제품 핵심 동작 증명¶

소스를 변경하기 전에 다음 테스트를 수행하십시오. 이 테스트는 시연을 신뢰할 수 있는 기준 구성으로 바꿔 줍니다.

공식 가이드는 보드별 기본 battery_table.c 곡선이 다른 배터리에서는 부정확할 수 있다고 경고합니다. 제품 배터리의 경우 공급업체의 충전/방전 데이터를 입수하거나 직접 측정하여 charging_curve_table과 discharge_curve_table을 업데이트하고, 다시 빌드한 뒤 배터리 테스트를 반복하십시오.

게이트 2 종료 기준: 모든 테스트에 결과가 기록되어 있고, 실패를 장애 영역별로 구별할 수 있으며, 문서화된 각 복구 경로가 재플래싱이나 수동 상태 복구 없이 동작합니다.

3단계 — 재현 가능한 소스 기준 구성 빌드¶

이 저장소는 SiFli-SDK를 서브모듈로 가져옵니다. 재귀적으로 클론하고 Xiaozhi 커밋과 SDK 서브모듈 커밋을 모두 기록하십시오.

git clone --recursive https://github.com/78/xiaozhi-sf32.git
cd xiaozhi-sf32
git checkout 1d3ef641ace47fae68227e9173647fd5db01f6f5
git submodule update --init --recursive
cd sdk
# Windows: .\install.ps1, then .\export.ps1
# macOS/Linux: ./install.sh, then . ./export.sh

공식 DevKit-ULP 스크립트 빌드 예제에서는 문서화된 외부 보드 경로를 지정하여 app/project에서 빌드합니다.

scons --board=sf32lb52-lchspi-ulp --board_search_path="../boards" -j8

정확한 타깃과 플래싱 스크립트는 보드별 공식 빌드 페이지를 참조하십시오. ULP 보드 이름이나 생성된 산출물 경로를 다른 보드에 그대로 복사하면 안 됩니다. 재현 가능한 빌드 기록에는 호스트 OS, 도구 설치 결과, 익스포트된 환경, 보드 인자, 업스트림/SDK 리비전, 빌드 로그, 기록한 이미지, 시리얼 로그가 포함되어야 합니다.

게이트 3 종료 기준: 두 번째 머신에서 클린 체크아웃을 하거나 빌드 디렉터리를 삭제한 뒤에도, 2단계의 모든 검사를 통과하는 이미지가 만들어집니다.

4단계 — 신중하게 적용하기¶

한 번에 하나씩만 변경하고, 통과한 기준 구성 이미지를 보존하십시오. 공식 커스터마이징 자료는 Bluetooth 이름 지정, 정적 및 애니메이션 그래픽, 폰트, PAN DFU, MCP를 다룹니다.

디바이스 측 MCP의 경우, 공식 가이드는 app/src/mcp/mcp_server.cc의 McpServer::AddCommonTools()를 사용합니다. LLM이 요청한 동작은 신뢰할 수 없는 요청으로 취급하십시오. 콜백에서 범위와 상태를 검증하고, 출력의 기본값을 안전한 상태로 설정하며, 되돌릴 수 없거나 위험하거나 보안에 민감한 제어는 제품별 인가 없이 절대 노출하지 마십시오.

PAN OTA의 경우, 공식 문서는 별도로 배포할 수 있는 세 가지 이미지 종류인 코드, 이미지 에셋, 폰트 에셋을 설명하며, 이미지 주소와 크기는 파티션 테이블을 사용하도록 안내합니다. 양산용 OTA는 사용자에게 활성화하기 전에 버전 정책, 서버 접근 제어, 무결성 검증, 중단 테스트, 유선 또는 로컬 복구 경로가 필요합니다.

게이트 4 종료 기준: 선택한 변경, 롤백 또는 복구 경로, 해당하는 모든 회귀 테스트 결과가 기록되어 있어야 합니다. 기존 대화 흐름이 계속 동작하고 디바이스 동작에 설정한 안전 경계도 유지되어야 합니다.

5단계 — 제품 준비 상태 검토¶

팀이 다음 질문에 모두 답할 수 있기 전에는 커스텀 하드웨어로 넘어가지 마십시오.

• 어떤 휴대폰/OS 버전이 해당 PAN 온보딩 흐름을 정확히 지원하며, 지원하지 않을 때의 대체 수단은 무엇인가?
• 어떤 클라우드 엔드포인트, 계정, 에이전트, MCP 엔드포인트, 자격 증명을 사용하며, 이를 누가 소유하고 교체하는가?
• 어떤 오디오, 디바이스, 사용자 데이터가 디바이스 밖으로 나가며, 동의는 어떻게 받고, 보존 기간과 지역별 요구 사항은 무엇인가?
• 의도한 배터리와 인클로저에서 측정한 활성 대화, 연결 유휴, 슬립, 충전, 웨이크 전류는 얼마인가?
• 업데이트 실패, 휴대폰 분실, 클라우드 장애, 에셋 손상, 잘못된 설정이 발생했을 때 디바이스는 어떻게 복구하는가?
• 업스트림 코드, 서비스, 모델 동작, OTA 인프라 중 어느 부분을 제품 팀이 통제하고 어느 부분을 외부 제공자가 통제하는가?

게이트 5 종료 기준: 답변, 지정된 담당자, 잔여 리스크가 기록되어 제품 팀이 수용했으며, 미해결 항목마다 완화책, 명시적 보류, 중단 결정 중 하나가 있습니다.

제품 설계로의 인계¶

선택한 SF32 부품, 전원 아키텍처, 디스플레이/오디오 설계, RF 전략, 스토리지/파티션 계획, 양산 테스트, 복구 가정을 양산 설계로 가져가십시오. SF32LB52 통합 경로를 사용하여 관련 칩, 모듈, 보드, 가이드, 체크리스트를 선택하십시오.

프로젝트 완료 정의: 새 팀원이 선택한 기준 구성을 재현하고, 관찰된 각 장애를 그 담당자 또는 복구 경로까지 추적하고, 커스터마이징된 이미지를 다시 빌드하고, 커스텀 하드웨어 결정에 필요한 증거를 검토할 수 있게 되면 이 레퍼런스는 제 목적을 다한 것입니다. 그때부터 이 레퍼런스는 검증 없이 양산에 가져가는 데모가 아니라 제품 개발 레퍼런스입니다.

주요 정보 출처¶

• 78/xiaozhi-esp32 저장소
• 78/xiaozhi-sf32 저장소
• SiFli Wiki: AI Xiaozhi 개요(중국어)
• SiFli Xiaozhi 퀵 스타트
• SiFli Xiaozhi 소스 빌드
• SiFli Xiaozhi 아키텍처
• SiFli Xiaozhi 커스터마이징
• SiFli Xiaozhi DFU_PAN 가이드
• SiFli Xiaozhi MCP 가이드

최종 업데이트: 2026-10-19