SF32-Sprachassistent Xiaozhi¶

Was ist Xiaozhi?¶

Xiaozhi ist ein Open-Source-Sprach-Chatbot auf Basis von MCP, der 2025 durch seine ESP32-Implementierung breite Bekanntheit erlangte. Er verbindet ein Gerät für Sprachinteraktion mit Cloud-Diensten für große Sprachmodelle sowie MCP-Erweiterungen auf dem Gerät oder in der Cloud. Damit ist er ein praktischer Ausgangspunkt für Hardware mit dialogbasierter KI und nicht nur eine Text-Chat-Anwendung.

Warum die SF32-Implementierung?¶

78/xiaozhi-sf32 ist die SF32-Implementierung, verwendet jedoch bewusst ein anderes Verbindungskonzept. Während das ursprüngliche ESP32-Projekt WLAN und weitere direkte Netzwerkverbindungen unterstützt, bezieht die SF32-Version den Internetzugang über Bluetooth PAN im Classic-Modus von einem gekoppelten Smartphone. Dadurch wird die Netzwerkanbindung des Geräts an das Smartphone ausgelagert. Bei einem smartphonegebundenen Produkt kann das den netzwerkbedingten Stromverbrauch des Geräts deutlich senken; die tatsächliche Einsparung hängt jedoch vom Smartphone, den Funkbedingungen, dem Zeitanteil aktiver Dialoge und der Energierichtlinie ab. Der Ansatz eignet sich daher besonders für akkubetriebene, persönliche Geräte wie Anhänger, Smart-Badges, kompakte Assistenten und kleine Wearables.

Besonders wertvoll ist das Projekt als Produktvorlage, weil es Bereiche zusammenführt, die oft getrennt betrachtet werden: Display- und Audiohardware, die vom Smartphone bereitgestellte Netzwerkverbindung, einen Cloud-Sprachdienst, die Geräteaktivierung, Gerätesteuerung und Updates im Einsatz.

Ergebnis, Umfang und Eintrittskriterien¶

Diese Seite beschreibt einen vollständigen technischen Weg, um die Referenz in eine Produktrichtung zu überführen. Sie behauptet nicht, dass Xiaozhi ein Offline-LLM auf dem Gerät ist, jede Upstream-Funktion für die Produktion qualifiziert wurde oder ein unterstütztes Entwicklungsboard einem zertifizierten Endprodukt entspricht. Das Gerät erhält den Internetzugang über Bluetooth PAN von einem gekoppelten Smartphone und nutzt für den Dialog die Xiaozhi-Cloud-Dienste. Vor einer Produktentscheidung sind Nutzungsbedingungen, Kontoinhaberschaft, Datenschutz, Sicherheit, Kosten, Verfügbarkeit und regionale Eignung zu klären.

Ergebnis: ein reproduzierbarer Sprach- und Displayassistent, der über ein Smartphone eingerichtet werden kann, einen Cloud-gestützten Dialog führt, eine sichere Gerätefunktion steuert, eine unterbrochene PAN-Verbindung wiederherstellt und die Nachweise für die Entscheidung über eigene Hardware liefert.

Zielgruppe: Firmware-, Hardware- und Produktentwickler, die bereits eine SF32-Basis bauen und flashen können und mit C/C++, Board-Schaltplänen, Bluetooth-Konfiguration und Cloud-Dienstintegration zu arbeiten bereit sind.

Hardware- und Software-Spezifikationen¶

Das folgende Manifest beschreibt eine konkrete Referenz für den Build aus Quellcode: SF32LB52-DevKit-Nano-R16N16 V1.0.0 mit dem von SiFli dokumentierten externen Display und Audiokreis. Es ist keine allgemeingültige Stückliste für alle unterstützten Xiaozhi-Boards. Wenn Sie DevKit-ULP, DevKit-LCD oder Xiaotangyuan verwenden, ersetzen Sie das gesamte Hardwaremanifest durch die dokumentierte Bestückung dieses Boards und halten Sie die genauen Lieferantenteile und die Boardrevision fest.

Hardware-Spezifikation¶

Die oben genannten Links zu Drittanbieterkomponenten sind Marktplatzangebote aus der offiziellen SiFli-Nano-Anleitung und keine dauerhafte Zusicherung von Hersteller-Teilenummern. Bewahren Sie für die bewerteten Teile Screenshots oder Bestellnachweise auf und ersetzen Sie vor dem Produktdesign jede Marktplatzabhängigkeit durch eine qualifizierte Lieferanten-Teilenummer samt Datenblatt.

Software-Spezifikation¶

Unterstützte Referenzkonfiguration auswählen¶

Die SiFli-Schnellstartdokumentation für Xiaozhi nennt vier Ziele für vorgefertigte Firmware: SF32LB52-DevKit-ULP (Huangshan), SF32LB52-DevKit-LCD, SF32LB52-DevKit-Nano und das Xiaotangyuan-Steckmodul. Die Dokumentation zum Build aus Quellcode führt derzeit DevKit-ULP, DevKit-LCD und DevKit-Nano auf. Wenn Quellcodeanpassungen erforderlich sind, wählen Sie ein Board aus der Liste für den Quellcode-Build. Ein vorgefertigtes Image bedeutet nicht automatisch, dass ein dokumentiertes Quellcode-Buildziel existiert.

Projektphasen und Entscheidungspunkte¶

Betrachten Sie die Phasen als Entscheidungspunkte und nicht als Funktions-Checkliste. Jede Phase hinterlässt ein Artefakt, anhand dessen sich die nächste Entscheidung nachvollziehbar prüfen und wiederholen lässt.

Systemarchitektur und Abhängigkeiten¶

flowchart LR
    U["Nutzer: Aktivierungswort oder Dialogtaste"] --> D["SF32LB52-Gerät\nMikrofon, UI, lokale Steuerung"]
    D --> E["Audioverarbeitung\nOPUS / AEC / VAD, sofern aktiviert"]
    D <-->|"Bluetooth Classic PAN\nBNEP + IP"| P["Gekoppeltes Smartphone\nBluetooth-Internetfreigabe"]
    P <-->|"WebSocket; ausgewählte HTTP-APIs"| S["Xiaozhi-Cloud-Dienste\nStreaming-ASR / LLM / TTS"]
    S --> P --> D
    D --> O["Lautsprecher, Display\nund MCP-Aktionen auf dem Gerät"]

Der offizielle Architekturleitfaden beschreibt Bluetooth PAN über Bluetooth im Classic-Modus als Netzwerkpfad und ein leichtgewichtiges IP-Netzwerk auf dem Gerät. WebSocket dient als primärer Echtzeitkanal der Anwendung; ausgewählte API-Aufrufe laufen über HTTP. Die SiFli-Übersicht nennt Schlüsselwortaktivierung (KWS), fortlaufende Dialoge, AEC/VAD, dynamische Ausdrücke, Vektorschriften und lokales MCP als implementierte Funktionen. Weitere offizielle Projektunterlagen beschreiben außerdem Display-UI, Akku- und Energieverhalten, MCP-Erweiterungen in der Cloud und PAN-OTA; prüfen Sie die konkrete Unterstützung für das gewählte Board und die Firmware.

Daraus ergeben sich vier Fehlerbereiche, die unabhängig voneinander diagnostiziert werden müssen: lokale Hardware und Audio, Bluetooth-Kopplung und PAN, Erreichbarkeit des Internets und des Cloud-Dienstes sowie Anwendungs- und Dienstkonfiguration. Eine erfolgreiche BLE-Kopplung allein belegt weder den Internetzugang des Boards noch die Aktivierung des Sprachdienstes.

Phase 1 — Die unveränderte Referenzbasis einrichten¶

1. Richten Sie die Hardware gemäß der offiziellen Anleitung für das jeweilige Board ein. Beim DevKit-LCD gehören dazu die vorgesehene AMOLED-/FPC-Anordnung, ein Lautsprecher an SPK, KEY1 zum Aktivieren und Starten eines Dialogs sowie langes Drücken von KEY2 zum Ausschalten.
2. Flashen Sie die unterstützte vorgefertigte Firmware nach dem offiziellen Xiaozhi-Verfahren. Die Schnellstartanleitung empfiehlt das grafische Flash-Tool. Zum Zeitpunkt der Anleitung wird das Flashen über das Terminal für Firmware ab Version 1.4.0 nicht unterstützt.
3. Aktivieren Sie auf dem Smartphone Bluetooth Internet sharing (Bluetooth-Internetfreigabe) vor dem Koppeln. Koppeln Sie es mit sifli-pan und prüfen Sie in der Board-UI sowie am Freigabestatus des Smartphones, dass PAN aktiv ist und nicht nur eine Bluetooth-Kopplung besteht. Laut offizieller Anleitung kann unter iOS ein Neustart des Smartphones erforderlich sein, wenn sifli-pan nicht angezeigt wird.
4. Führen Sie den offiziellen Aktivierungsablauf in der Xiaozhi-Konsole unter xiaozhi.me aus: Erstellen und konfigurieren Sie einen Agenten und fügen Sie den vom Board angezeigten Gerätecode hinzu.
5. Führen Sie mit der Dialogtaste des Boards oder dem konfigurierten Aktivierungspfad einen Dialog. Halten Sie Firmwareversion, Board, Smartphone-Modell und Betriebssystem sowie Konto- und Agentenkennung im Projektprotokoll fest.

Abnahmekriterium für Kontrollpunkt 1: Nach einem Kaltstart stellt das Gerät PAN her, meldet seine Aktivierung, nimmt eine Dialoganfrage an, gibt eine Antwort wieder und zeigt den erwarteten UI-Zustand.

Phase 2 — Wiederherstellung und produktkritisches Verhalten nachweisen¶

Führen Sie diese Tests vor jeder Quellcodeänderung aus. So wird aus der Demonstration eine belastbare Referenzbasis:

Die offizielle Anleitung weist darauf hin, dass die standardmäßige battery_table.c-Kurve eines Boards für einen anderen Akku ungenau sein kann. Beschaffen Sie für den Produktakku die Lade-/Entladedaten des Lieferanten oder messen Sie sie selbst. Aktualisieren Sie charging_curve_table und discharge_curve_table, erstellen Sie den Build neu und wiederholen Sie die Akkutests.

Abnahmekriterium für Kontrollpunkt 2: Für jeden Test liegt ein Ergebnis vor, Fehler lassen sich den jeweiligen Fehlerbereichen zuordnen und jeder dokumentierte Wiederherstellungspfad funktioniert ohne erneutes Flashen oder manuelle Zustandskorrektur.

Phase 3 — Eine reproduzierbare Quellbasis erstellen¶

Das Repository bindet SiFli-SDK als Submodul ein. Klonen Sie rekursiv und halten Sie sowohl den Xiaozhi-Commit als auch den Commit des SDK-Submoduls fest:

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

Für das offizielle Skript-Build-Beispiel des DevKit-ULP erstellen Sie den Build in app/project und verwenden den dokumentierten Pfad zum externen Board:

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

Verwenden Sie für das genaue Buildziel und das Download-Skript die offizielle Build-Seite des jeweiligen Boards. Übernehmen Sie weder den ULP-Boardnamen noch den Pfad des erzeugten Artefakts für ein anderes Board. Ein reproduzierbares Buildprotokoll muss Hostbetriebssystem, Ergebnis der Tool-Installation, exportierte Umgebung, Boardargument, Upstream-/SDK-Revision, Buildprotokoll, heruntergeladenes Image und serielles Protokoll enthalten.

Abnahmekriterium für Kontrollpunkt 3: Ein sauberer Checkout auf einem zweiten Rechner oder nach dem Löschen des Build-Verzeichnisses erzeugt ein Image, das alle Prüfungen aus Phase 2 besteht.

Phase 4 — Gezielt anpassen¶

Nehmen Sie jeweils nur eine Änderung vor und bewahren Sie das bestandene Basisimage auf. Die offizielle Anpassungsdokumentation behandelt Bluetooth-Namen, statische und animierte Grafiken, Schriftarten, PAN-DFU und MCP.

Für MCP auf dem Gerät verwendet die offizielle Anleitung McpServer::AddCommonTools() in app/src/mcp/mcp_server.cc. Behandeln Sie eine vom LLM angeforderte Aktion als nicht vertrauenswürdige Anfrage: Prüfen Sie Wertebereich und Zustand im Callback, setzen Sie Ausgänge standardmäßig in einen sicheren Zustand und geben Sie irreversible, gefährliche oder sicherheitskritische Steuerungen nur mit produktspezifischer Autorisierung frei.

Für PAN-OTA beschreibt die offizielle Dokumentation drei unabhängig bereitstellbare Image-Klassen: Code, Bildressourcen und Schriftressourcen. Adresse und Größe der Images sind der Partitionstabelle zu entnehmen. Vor der Freigabe eines OTA-Updates für Nutzer braucht es in der Produktion eine Versionsrichtlinie, Zugriffskontrolle für den Server, Integritätsprüfung, einen Unterbrechungstest und einen kabelgebundenen oder lokalen Wiederherstellungspfad.

Abnahmekriterium für Kontrollpunkt 4: Die ausgewählte Änderung, ihr Rollback- oder Wiederherstellungspfad und alle einschlägigen Regressionsergebnisse sind dokumentiert. Der ursprüngliche Dialogablauf und die Sicherheitsgrenzen jeder Geräteaktion funktionieren weiterhin.

Phase 5 — Produktreife-Überprüfung¶

Wechseln Sie erst zu kundenspezifischer Hardware, wenn das Team alle folgenden Fragen beantworten kann:

• Welche Smartphone-/Betriebssystemversionen unterstützen genau diesen PAN-Einrichtungsablauf, und welche Ausweichlösung gibt es für nicht unterstützte Versionen?
• Welche Cloud-Endpunkte, Konten, Agenten, MCP-Endpunkte und Zugangsdaten werden verwendet, und wer ist für sie verantwortlich und erneuert sie turnusmäßig?
• Welche Audio-, Geräte- und Nutzerdaten verlassen das Gerät? Wie wird die Einwilligung eingeholt, und welche Anforderungen gelten für Aufbewahrung und Region?
• Welche Ströme wurden bei aktivem Dialog, verbundenem Ruhezustand, Schlaf, Laden und Aufwachen mit dem vorgesehenen Akku und Gehäuse gemessen?
• Wie erholt sich das Gerät nach einem fehlgeschlagenen Update, einem verlorenen Smartphone, einem Cloud-Ausfall, beschädigten Ressourcen oder einer fehlerhaften Konfiguration?
• Welche Teile des Upstream-Codes, des Dienstes, des Modellverhaltens und der OTA-Infrastruktur kontrolliert Ihr Produktteam, und welche werden von externen Anbietern bereitgestellt?

Abnahmekriterium für Kontrollpunkt 5: Das Produktteam hat die Antworten, verantwortlichen Personen und verbleibenden Risiken dokumentiert und akzeptiert. Für jeden offenen Punkt gibt es eine Gegenmaßnahme, einen ausdrücklich beschlossenen Aufschub oder eine Abbruchentscheidung.

Übergabe an das Produktdesign¶

Übernehmen Sie das ausgewählte SF32-Gerät, die Stromversorgungsarchitektur, das Display-/Audiodesign, die RF-Strategie, den Speicher- und Partitionsplan, die Produktionstests sowie die Annahmen zur Wiederherstellung in Design für die Produktion. Verwenden Sie den Integrationspfad für SF32LB52, um den passenden Chip, das Modul, Board, den Leitfaden und die Checkliste auszuwählen.

Definition des Projektabschlusses: Die Referenz hat ihren Zweck erfüllt, wenn ein neues Teammitglied die ausgewählte Basis reproduzieren, jeden beobachteten Fehler seinem Verantwortlichen oder Wiederherstellungspfad zuordnen, das angepasste Image neu erstellen und die Nachweise für die Entscheidung über kundenspezifische Hardware prüfen kann. Sie dient dann als Referenz für die Produktentwicklung und nicht als ungeprüfte Demonstration, die in die Produktion übernommen wird.

Maßgebliche Quellen¶

• Repository 78/xiaozhi-esp32
• Repository 78/xiaozhi-sf32
• SiFli-Wiki: Überblick zu AI Xiaozhi (Chinesisch)
• SiFli-Schnellstart für Xiaozhi
• SiFli-Anleitung zum Build von Xiaozhi aus dem Quellcode
• SiFli-Architektur von Xiaozhi
• SiFli-Anleitung zur Anpassung von Xiaozhi
• SiFli-Anleitung zu DFU_PAN für Xiaozhi
• SiFli-Anleitung zu MCP für Xiaozhi

Zuletzt aktualisiert: 2026-10-21