Asistente de voz SF32 Xiaozhi¶

¿Qué es Xiaozhi?¶

Xiaozhi es un chatbot de voz de código abierto basado en MCP que se hizo ampliamente conocido gracias a su implementación en ESP32 en 2025. Combina un dispositivo de interacción por voz con servicios de modelos grandes en la nube y extensiones MCP locales o en la nube, por lo que constituye un punto de partida práctico para crear hardware de IA conversacional, no solo una aplicación de chat de texto.

¿Por qué esta implementación en SF32?¶

78/xiaozhi-sf32 es la implementación para SF32, pero utiliza deliberadamente un esquema de conectividad distinto. Mientras que el proyecto ESP32 original admite Wi-Fi y otras opciones de conexión directa a la red, la versión SF32 usa Bluetooth PAN clásico para acceder a Internet a través de un teléfono emparejado. Así, la conexión de largo alcance se delega al teléfono, lo que, en un diseño que depende del teléfono, puede reducir considerablemente el consumo energético asociado a la conectividad de red en el dispositivo. El ahorro real depende del teléfono, las condiciones de radio, la proporción de tiempo dedicada a las conversaciones y la política de alimentación. Por ello, este enfoque resulta especialmente adecuado para productos personales portátiles con batería, como colgantes, insignias, asistentes compactos y dispositivos vestibles pequeños.

Es una referencia de producto especialmente útil porque integra aspectos que suelen tratarse por separado: hardware de pantalla y audio, conexión de red proporcionada por el teléfono, servicio de voz en la nube, flujo de activación para el usuario, controles del dispositivo y capacidad de actualización en campo.

Resultado, alcance y criterios de entrada¶

Esta página presenta una ruta completa de ingeniería para adaptar esa referencia a un producto. No afirma que Xiaozhi sea un LLM que funcione localmente sin conexión, que todas las funciones del proyecto de origen estén validadas para producción ni que una placa de desarrollo admitida equivalga a un producto terminado y certificado. El dispositivo obtiene acceso a Internet mediante Bluetooth PAN desde un teléfono emparejado y utiliza los servicios en la nube de Xiaozhi para las conversaciones. Antes de comprometerse con el producto, confirme las condiciones del servicio, la titularidad de la cuenta, la privacidad, la seguridad, el coste, la disponibilidad y la idoneidad regional.

Resultado: obtener un asistente de voz y pantalla reproducible que pueda configurarse mediante un teléfono, mantener una conversación respaldada por la nube, controlar una función segura del dispositivo, recuperarse de una pérdida de conexión PAN y generar las evidencias necesarias para decidir si se debe diseñar hardware propio.

Público objetivo: ingenieros de firmware, hardware y producto capaces de compilar y grabar una configuración base de SF32 y preparados para trabajar con C/C++, esquemáticos de placas, configuración Bluetooth e integración de servicios en la nube.

Especificaciones de hardware y software¶

El manifiesto siguiente define una referencia concreta para compilar desde el código fuente: SF32LB52-DevKit-Nano-R16N16 V1.0.0 con la pantalla externa y el circuito de audio documentados por SiFli. No es una lista universal de materiales para todas las placas compatibles con Xiaozhi. Si elige DevKit-ULP, DevKit-LCD o Xiaotangyuan, sustituya todo este manifiesto de hardware por el conjunto documentado de esa placa y conserve los números de pieza exactos del proveedor y la revisión de la placa.

Especificación de hardware¶

Las URL de componentes de terceros anteriores son enlaces a tiendas publicados por la guía oficial de SiFli Nano; no garantizan que los números de pieza del fabricante se mantengan sin cambios. Conserve capturas o registros de pedido de las piezas evaluadas y sustituya cada dependencia de una tienda en línea por una referencia de proveedor validada y su hoja de datos antes de diseñar el producto.

Especificación de software¶

Elegir una configuración de referencia admitida¶

La guía de inicio rápido de SiFli para Xiaozhi enumera cuatro destinos de firmware precompilado: SF32LB52-DevKit-ULP (Huangshan), SF32LB52-DevKit-LCD, SF32LB52-DevKit-Nano y la placa enchufable Xiaotangyuan. La documentación de compilación desde código fuente enumera actualmente DevKit-ULP, DevKit-LCD y DevKit-Nano. Si la personalización del código es un requisito del proyecto, elija una placa incluida en la lista de compilación desde código fuente; no suponga que disponer de una imagen precompilada implica que también haya un destino de compilación documentado.

Etapas del proyecto¶

Utilice las etapas como puntos de decisión, no como una lista de funciones. Cada una deja un artefacto que permita revisar y repetir la decisión siguiente.

Arquitectura del sistema y dependencias¶

flowchart LR
    U["Usuario: palabra de activación o tecla de diálogo"] --> D["Dispositivo SF32LB52\nmicrófono, interfaz y controles locales"]
    D --> E["Cadena de audio\nOPUS / AEC / VAD cuando están habilitados"]
    D <-->|"Bluetooth clásico PAN\nBNEP + IP"| P["Teléfono emparejado\ncompartición de Internet por Bluetooth"]
    P <-->|"WebSocket; algunas API HTTP"| S["Servicios en la nube de Xiaozhi\nASR / LLM / TTS en streaming"]
    S --> P --> D
    D --> O["Altavoz, pantalla y\nacciones MCP en el dispositivo"]

La guía oficial de arquitectura describe Bluetooth PAN sobre Bluetooth clásico como ruta de red, con conectividad IP ligera en el dispositivo. Identifica WebSocket como canal principal de aplicación en tiempo real y HTTP para algunas interacciones con API. La descripción general de SiFli incluye entre las funciones implementadas la activación por palabra clave (KWS), el diálogo continuo, AEC/VAD, las expresiones dinámicas, las fuentes vectoriales y MCP local. Otros materiales oficiales también describen la interfaz de pantalla, la gestión de batería y alimentación, las extensiones MCP en la nube y la OTA por PAN; verifique la compatibilidad concreta con la placa y el firmware elegidos.

Este flujo crea cuatro ámbitos de fallo que se deben diagnosticar por separado: hardware y audio locales, emparejamiento Bluetooth y PAN, acceso a Internet y al servicio en la nube, y configuración de la aplicación y del servicio. Que el emparejamiento BLE tenga éxito no demuestra que la placa tenga acceso a Internet ni que el servicio de voz esté activado.

Etapa 1 — Establecer la configuración de referencia intacta¶

1. Complete la configuración oficial de hardware específica de la placa. Para DevKit-LCD incluye el conjunto AMOLED/FPC indicado, un altavoz conectado a SPK, KEY1 para activar/iniciar un diálogo y KEY2 para apagar mediante pulsación larga.
2. Grabe el firmware precompilado admitido siguiendo el procedimiento oficial de Xiaozhi. La guía de inicio rápido recomienda la herramienta gráfica de grabación; en el momento de esa guía indica que el firmware v1.4.0 y posterior no admite la grabación desde terminal.
3. Antes de emparejar, active en el teléfono la compartición de Internet por Bluetooth. Empareje el dispositivo sifli-pan y compruebe, mediante la interfaz de la placa y el estado de compartición del teléfono, que está activo PAN y no solo el emparejamiento Bluetooth. Para iOS, la guía oficial indica que puede ser necesario reiniciar el teléfono si no aparece sifli-pan.
4. Siga el flujo de activación oficial en la consola de Xiaozhi en xiaozhi.me: cree/configure un agente y añada el código del dispositivo que muestra la placa.
5. Inicie un diálogo con la tecla de diálogo de la placa o con la ruta de activación configurada. Registre en el proyecto la versión del firmware, la placa, el modelo/sistema operativo del teléfono y el identificador de cuenta/agente del servicio.

Criterio de salida del punto de control 1: tras un arranque en frío, el dispositivo establece PAN, se identifica como activado, acepta una solicitud de diálogo, reproduce la respuesta y presenta el estado de interfaz esperado.

Etapa 2 — Demostrar la recuperación y el comportamiento crítico para el producto¶

Ejecute estas pruebas antes de modificar el código fuente. Transforman la demostración en una referencia fiable:

La guía oficial advierte que la curva battery_table.c predeterminada para cada placa puede ser inexacta con otra batería. Para la batería del producto, obtenga los datos de carga/descarga del proveedor o mídalos; actualice charging_curve_table y discharge_curve_table, vuelva a compilar y repita las pruebas de batería.

Criterio de salida del punto de control 2: se registra el resultado de cada prueba, los fallos se distinguen por su ámbito y todas las rutas de recuperación documentadas funcionan sin volver a grabar el firmware ni corregir manualmente el estado.

Etapa 3 — Crear una referencia reproducible desde el código fuente¶

El repositorio incluye SiFli-SDK como submódulo. Clónelo de forma recursiva y registre tanto el commit de Xiaozhi como el del submódulo 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

Para el ejemplo oficial de compilación mediante scripts de DevKit-ULP, compile desde app/project con la ruta externa documentada de la placa:

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

Consulte la página oficial de compilación específica de cada placa para usar el destino y el script de descarga exactos; no reutilice el nombre de placa ULP ni la ruta de artefactos generados con otra placa. Un registro de compilación reproducible debe incluir el sistema operativo del equipo, el resultado de instalar las herramientas, el entorno exportado, el argumento de placa, la revisión del repositorio/SDK, el registro de compilación, la imagen descargada y el registro de consola serie.

Criterio de salida del punto de control 3: un checkout limpio en un segundo equipo —o después de borrar el directorio de compilación— genera una imagen que supera todas las comprobaciones de la Etapa 2.

Etapa 4 — Adaptar de forma deliberada¶

Realice un cambio cada vez y conserve la imagen de referencia aprobada. La documentación oficial de personalización cubre el nombre Bluetooth, gráficos estáticos y animados, fuentes, DFU por PAN y MCP.

Para MCP en el dispositivo, la guía oficial utiliza McpServer::AddCommonTools() en app/src/mcp/mcp_server.cc. Trate una acción solicitada por el LLM como una petición no confiable: valide el rango y el estado en el callback, establezca estados seguros por defecto y no exponga nunca controles irreversibles, peligrosos o sensibles para la seguridad sin autorización específica del producto.

La documentación oficial de OTA por PAN describe tres tipos de imágenes que se pueden desplegar por separado: código, recursos gráficos y fuentes. Indica que se debe consultar la tabla de particiones para conocer la dirección y el tamaño de cada imagen. La OTA de producción necesita una política de versiones, control de acceso al servidor, validación de integridad, una prueba de interrupción y una ruta de recuperación por cable o local antes de habilitarla para los usuarios.

Criterio de salida del punto de control 4: quedan registrados el cambio elegido, su ruta de reversión o recuperación y todos los resultados de regresión aplicables; el flujo de voz original y los límites de seguridad de las acciones del dispositivo siguen superando las pruebas.

Etapa 5 — Revisión de preparación del producto¶

No pase a hardware propio hasta que el equipo pueda responder a todo lo siguiente:

• ¿Qué versiones de teléfono y sistema operativo admiten exactamente la configuración inicial mediante PAN y cuál es la alternativa cuando no la admiten?
• ¿Qué endpoints de nube y MCP se utilizan, y con qué cuenta y agente? ¿Quién los administra y quién se encarga de rotar las credenciales?
• ¿Qué datos de audio, dispositivo y usuario salen del dispositivo? ¿Cómo se obtiene el consentimiento y cuáles son los requisitos de retención y región?
• ¿Cuáles son las corrientes medidas durante un diálogo activo, en reposo conectado, suspensión, carga y activación, con la batería y la carcasa previstas?
• ¿Cómo se recupera el dispositivo de una actualización fallida, la pérdida del teléfono, una interrupción de la nube, un recurso dañado o una configuración incorrecta?
• ¿Qué partes del código de origen, el servicio, el comportamiento del modelo y la infraestructura OTA controla el equipo de producto y cuáles dependen de proveedores externos?

Criterio de salida del punto de control 5: las respuestas, los responsables y los riesgos residuales están registrados y aceptados por el equipo de producto. Cada asunto sin resolver tiene una mitigación, una postergación explícita o una decisión de detenerse.

Traspaso a la fase de diseño del producto¶

Traslade la pieza SF32 seleccionada, la arquitectura de alimentación, el diseño de pantalla/audio, la estrategia RF, el plan de almacenamiento/particiones, las pruebas de producción y las hipótesis de recuperación a Diseño para producción. Utilice la ruta de integración de SF32LB52 para seleccionar el chip, módulo, placa, guía y lista de comprobación correspondientes.

Definición de finalización del proyecto: esta referencia habrá cumplido su propósito cuando un nuevo miembro del equipo pueda reproducir la configuración elegida, rastrear cada fallo observado hasta su responsable o ruta de recuperación, volver a compilar la imagen personalizada y revisar las evidencias necesarias para decidir sobre hardware propio. A partir de entonces es una referencia de desarrollo de producto, no una demostración sin examinar que deba llevarse directamente a producción.

Fuentes de referencia¶

• Repositorio 78/xiaozhi-esp32
• Repositorio 78/xiaozhi-sf32
• Wiki de SiFli: descripción general de AI Xiaozhi (en chino)
• Inicio rápido de Xiaozhi de SiFli
• Compilación de Xiaozhi desde el código fuente de SiFli
• Arquitectura de Xiaozhi de SiFli
• Personalización de Xiaozhi de SiFli
• Guía DFU_PAN de Xiaozhi de SiFli
• Guía MCP de Xiaozhi de SiFli

Última actualización: 2026-10-21