Assistente de voz Xiaozhi para SF32¶

O que é o Xiaozhi?¶

Xiaozhi é um chatbot de voz de código aberto baseado em MCP, que ganhou notoriedade com sua implementação para ESP32 em 2025. Ele combina um dispositivo de interação por voz com serviços de modelos de linguagem de grande porte (LLMs) na nuvem e extensões MCP no dispositivo ou na nuvem. Por isso, é um ponto de partida prático para desenvolver hardware de IA conversacional, e não apenas um aplicativo de chat por texto.

Por que a implementação em SF32?¶

78/xiaozhi-sf32 é a implementação para SF32, mas adota deliberadamente outra estratégia de conectividade. Enquanto o projeto original para ESP32 oferece Wi-Fi e outras opções de conexão direta, a versão para SF32 usa Bluetooth PAN clássico para acessar a Internet por meio de um telefone pareado. Assim, o telefone assume a conexão de longa distância, o que pode reduzir significativamente o consumo de energia da conectividade no dispositivo em projetos dependentes do telefone. A economia real varia conforme o telefone, as condições de rádio, o tempo dedicado às conversas e a política de energia. Essa abordagem é especialmente adequada a produtos pessoais e portáteis alimentados por bateria, como pingentes, crachás, assistentes compactos e pequenos dispositivos vestíveis.

Esta é uma referência de produto particularmente útil porque reúne aspectos que muitas vezes são tratados separadamente: hardware de display e áudio, conectividade fornecida pelo telefone, serviço de voz na nuvem, fluxo de ativação para o usuário, controles do dispositivo e capacidade de atualização em campo.

Resultado, escopo e critérios de entrada¶

Esta página apresenta um roteiro de engenharia completo para transformar essa referência em uma direção de produto. Ela não afirma que o Xiaozhi seja um modelo de linguagem executado no próprio dispositivo sem depender da nuvem, que todos os recursos upstream estejam qualificados para produção ou que uma placa de desenvolvimento compatível equivalha a um produto final certificado. O dispositivo acessa a Internet por Bluetooth PAN por meio de um telefone pareado e depende dos serviços Xiaozhi na nuvem para a conversa. Antes de assumir um compromisso com o produto, confirme os termos do serviço, a titularidade da conta, a privacidade, a segurança, os custos, a disponibilidade e a adequação às regiões de lançamento.

Resultado esperado: um assistente de voz e display reproduzível, capaz de ser provisionado pelo telefone, concluir uma conversa apoiada pela nuvem, controlar uma função segura do dispositivo, recuperar-se da perda da conexão PAN e gerar evidências para decidir se vale a pena desenvolver hardware próprio.

Público-alvo: engenheiros de firmware, hardware e produto que já conseguem compilar e gravar uma base do SF32 e estão preparados para trabalhar com C/C++, esquemáticos da placa, configuração Bluetooth e integração com serviços na nuvem.

Especificações de hardware e software¶

O manifesto a seguir define uma referência concreta para compilação a partir do código-fonte: SF32LB52-DevKit-Nano-R16N16 V1.0.0, com o display e o circuito de áudio externos documentados pela SiFli. Esta não é uma lista de materiais universal para todas as placas Xiaozhi compatíveis. Se escolher DevKit-ULP, DevKit-LCD ou Xiaotangyuan, substitua todo este manifesto pelo conjunto documentado para essa placa e registre os componentes exatos do fornecedor e a revisão da placa.

Especificação de hardware¶

Os URLs de componentes de terceiros acima são links de marketplaces publicados no guia oficial do Nano SiFli, não garantias de códigos permanentes dos fabricantes. Guarde capturas de tela ou comprovantes dos componentes avaliados e, antes do projeto do produto, substitua cada dependência de marketplace por um código qualificado do fornecedor e seu datasheet.

Especificação de software¶

Escolher uma configuração de referência suportada¶

A documentação de início rápido do Xiaozhi da SiFli lista quatro alvos para firmware pré-compilado: SF32LB52-DevKit-ULP (Huangshan), SF32LB52-DevKit-LCD, SF32LB52-DevKit-Nano e a placa de expansão Xiaotangyuan. A documentação de compilação a partir do código-fonte lista atualmente DevKit-ULP, DevKit-LCD e DevKit-Nano. Se a personalização do código-fonte for requisito do projeto, escolha uma placa presente nessa lista; não presuma que a existência de uma imagem pré-compilada implique suporte documentado para compilação.

Etapas do projeto¶

Use as etapas como pontos de decisão, não como uma lista de recursos. Cada uma deixa um artefato que permite revisar e repetir a decisão seguinte.

Arquitetura do sistema e dependências¶

flowchart LR
    U["Usuário: palavra de ativação ou botão de conversa"] --> D["Dispositivo SF32LB52\nmicrofone, interface, controles locais"]
    D --> E["Pipeline de áudio\nOPUS / AEC / VAD, quando habilitados"]
    D <-->|"Bluetooth PAN clássico\nBNEP + IP"| P["Telefone pareado\ncompartilhamento de Internet por Bluetooth"]
    P <-->|"WebSocket; APIs HTTP selecionadas"| S["Serviços Xiaozhi na nuvem\nASR / LLM / TTS em streaming"]
    S --> P --> D
    D --> O["Alto-falante, display\ne ações MCP no dispositivo"]

A documentação oficial de arquitetura descreve o Bluetooth PAN sobre Bluetooth clássico como caminho de rede, com uma pilha IP leve no dispositivo. O WebSocket é indicado como principal canal de aplicação em tempo real, enquanto algumas interações com APIs usam HTTP. A visão geral da SiFli lista como funções implementadas a ativação por palavra-chave (KWS), o diálogo contínuo, AEC/VAD, expressões dinâmicas, fontes vetoriais e MCP local. Outros materiais oficiais também descrevem a interface gráfica, o gerenciamento de bateria/energia, extensões MCP na nuvem e OTA por PAN; confirme o suporte específico na placa e no firmware escolhidos.

Esse fluxo cria quatro domínios de falha que precisam ser diagnosticados separadamente: hardware e áudio locais; pareamento Bluetooth e PAN; acesso à Internet e aos serviços na nuvem; e configuração do aplicativo e do serviço. Um pareamento BLE bem-sucedido, por si só, não comprova que a placa tenha acesso à Internet nem que o serviço de voz esteja ativado.

Etapa 1 — Estabelecer a base de referência sem modificações¶

1. Conclua a configuração de hardware oficial específica da placa. No DevKit-LCD, isso inclui a montagem indicada de AMOLED/FPC, um alto-falante em SPK, KEY1 para ativação/conversa e pressionamento prolongado de KEY2 para desligar.
2. Grave o firmware pré-compilado compatível seguindo o procedimento oficial do Xiaozhi. O guia de início rápido recomenda a ferramenta gráfica de gravação e informa que, na data do guia, a gravação pelo terminal não é compatível com o firmware v1.4.0 ou posterior.
3. No telefone, habilite o compartilhamento de Internet por Bluetooth antes do pareamento. Pareie com o dispositivo sifli-pan e use a interface da placa e o estado de compartilhamento do telefone para confirmar que o PAN está ativo, e não apenas o pareamento Bluetooth. No iOS, o guia oficial observa que talvez seja necessário reiniciar o telefone se sifli-pan não aparecer.
4. Siga o fluxo oficial de ativação no console Xiaozhi em xiaozhi.me: crie/configure um agente e adicione o código do dispositivo exibido pela placa.
5. Faça uma conversa usando o botão de conversa da placa ou o método de ativação configurado. Registre no projeto a versão do firmware, a placa, o modelo/SO do telefone e o identificador da conta/agente do serviço.

Critério de saída do ponto de controle 1: após uma inicialização a frio, o dispositivo estabelece o PAN, indica que está ativado, aceita uma solicitação de conversa, reproduz a resposta e apresenta o estado esperado na interface.

Etapa 2 — Comprovar a recuperação e os comportamentos essenciais do produto¶

Execute estes testes antes de alterar o código-fonte. Eles transformam a demonstração em uma base confiável:

O guia oficial alerta que a curva padrão em battery_table.c, específica de cada placa, pode não ser precisa para outra bateria. Para a bateria do produto, obtenha os dados de carga/descarga do fornecedor ou faça medições; atualize charging_curve_table e discharge_curve_table, recompile e repita os testes de bateria.

Critério de saída do ponto de controle 2: todos os testes têm resultados registrados, as falhas podem ser diferenciadas por domínio e cada método documentado de recuperação funciona sem nova gravação do firmware nem correção manual do estado.

Etapa 3 — Criar uma base de código-fonte reproduzível¶

O repositório inclui o SiFli-SDK como submódulo. Clone o repositório recursivamente e registre o commit do Xiaozhi e o commit do 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

No exemplo oficial de compilação por script para DevKit-ULP, compile a partir de app/project usando o caminho documentado para a placa externa:

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

Consulte a página oficial de compilação específica da placa para obter o alvo exato e o script de download; não reutilize o nome da placa ULP nem o caminho do artefato gerado para outra placa. O registro de uma compilação reproduzível deve incluir SO do host, resultado da instalação das ferramentas, ambiente exportado, argumento da placa, revisões upstream/SDK, log de compilação, imagem gravada e log serial.

Critério de saída do ponto de controle 3: um checkout limpo em outra máquina — ou após excluir o diretório de compilação — gera uma imagem aprovada em todos os testes da Etapa 2.

Etapa 4 — Fazer adaptações de forma deliberada¶

Faça uma alteração por vez e preserve a imagem de referência aprovada. O material oficial de personalização aborda o nome Bluetooth, gráficos estáticos e animados, fontes, DFU por PAN e MCP.

Para MCP no dispositivo, o guia oficial usa McpServer::AddCommonTools() em app/src/mcp/mcp_server.cc. Trate ações solicitadas por um LLM como solicitações não confiáveis: valide faixa e estado no callback, mantenha as saídas em estados seguros por padrão e não exponha controles irreversíveis, perigosos ou sensíveis à segurança sem autorização específica do produto.

Para OTA por PAN, a documentação oficial descreve três classes de imagem que podem ser distribuídas separadamente: código, recursos gráficos e fontes. Ela orienta o uso da tabela de partições para determinar o endereço e o tamanho de cada imagem. O OTA em produção exige política de versões, controle de acesso ao servidor, validação de integridade, teste de interrupção e um método de recuperação local ou com fio antes de ser habilitado para os usuários.

Critério de saída do ponto de controle 4: a alteração escolhida, seu método de rollback/recuperação e todos os resultados de regressão aplicáveis estão registrados; o fluxo original de conversa e os limites de segurança das ações do dispositivo continuam aprovados.

Etapa 5 — Avaliar a prontidão para o produto¶

Não avance para o hardware personalizado até que a equipe consiga responder a todas estas perguntas:

• Quais versões de telefone/SO são compatíveis com o fluxo exato de configuração do PAN e qual é a alternativa quando não forem?
• Quais endpoints de nuvem e MCP serão usados, e com que conta e agente? Quem será responsável por gerenciá-los e rotacionar as credenciais?
• Quais dados de áudio, dispositivo e usuário saem do dispositivo; como o consentimento é obtido; e quais são os requisitos de retenção e região?
• Quais valores de corrente foram medidos durante conversas ativas, repouso conectado, suspensão, carga e ativação, usando a bateria e o gabinete previstos?
• Como o dispositivo se recupera de uma atualização malsucedida, perda do telefone, indisponibilidade da nuvem, recurso corrompido ou configuração incorreta?
• Quais partes do código upstream, serviço, comportamento do modelo e infraestrutura OTA são controladas pela equipe do produto e quais dependem de fornecedores externos?

Critério de saída do ponto de controle 5: as respostas, os responsáveis e os riscos residuais estão registrados e foram aceitos pela equipe do produto; cada pendência tem uma mitigação, um adiamento explícito ou uma decisão de interromper.

Transição para o projeto do produto¶

Leve a seleção do componente SF32, a arquitetura de alimentação, o projeto do display e do áudio, a estratégia de RF, o plano de armazenamento/partições, os testes de produção e as premissas de recuperação para Projeto para produção. Use o caminho de integração do SF32LB52 para escolher o chip, módulo, placa, guia e checklist pertinentes.

Definição de conclusão do projeto: esta referência cumpriu seu papel quando uma nova pessoa da equipe consegue reproduzir a base selecionada, identificar o responsável ou o método de recuperação de cada falha observada, recompilar a imagem personalizada e revisar as evidências necessárias para decidir sobre hardware próprio. A partir daí, ela serve como referência de desenvolvimento de produto — não como uma demonstração não avaliada a ser levada diretamente à produção.

Fontes de referência¶

• Repositório 78/xiaozhi-esp32
• Repositório 78/xiaozhi-sf32
• Wiki da SiFli: visão geral do AI Xiaozhi (em chinês)
• Início rápido do Xiaozhi SiFli
• Compilação do Xiaozhi SiFli a partir do código-fonte
• Arquitetura do Xiaozhi SiFli
• Personalização do Xiaozhi SiFli
• Guia DFU_PAN do Xiaozhi SiFli
• Guia MCP do Xiaozhi SiFli

Última atualização: 2026-10-21