Pular para o conteúdo principal

Guia de Implantação do Cliente de Conversação de Borda reSpeaker XVF3800 + Agora Conversational AI Agent v2

Objetivo: Fazer o ESP32S3 funcionar junto com o reSpeaker XVF3800 para estabelecer um link de áudio bidirecional estável e de baixa latência via Agora RTC. Código-fonte do projeto: https://github.com/Seeed-Projects/ESP32S3_reSpeaker_agora/tree/main Seeed-Projects: https://github.com/Seeed-Projects/ESP32S3_reSpeaker_agora/tree/main

Introdução​

Neste tutorial, vamos guiá-lo para usar o Seeed Studio reSpeaker XVF3800 (XIAO ESP32-S3) como um dispositivo de voz de borda para estabelecer um link de áudio bidirecional estável e de baixa latência via Agora RTC, e chamar diretamente a API v2 do Agora Conversational AI Agent no dispositivo para completar o loop conversacional de ASR → LLM → TTS: o dispositivo captura o áudio do microfone e o envia em uplink; a IA na nuvem gera respostas faladas e as envia em downlink; o dispositivo as reproduz em tempo real — oferecendo uma experiência de conversa por voz “como em uma chamada telefônica”.

respeaker xvf3800 with xiao

Adquira agora 🖱️

Escolha seu Backend​

Este guia fornece duas opções de backend. Escolha a que se encaixa no seu cenário:

OpçãoMelhor paraServidor NecessárioLink
Agora Conversational AI Agent v2 (Nuvem, direto)Configuração mais rápida / infraestrutura mínimaNãoVocê está aqui ✅
TEN Framework (self-hosted, ASR/LLM/TTS plugáveis)Pipeline customizado / troca de provider / recursos avançadosSim (Docker)👉 Ir para a versão com TEN Framework

Sumário​

  1. Principais Recursos
  2. Arquitetura do Sistema
  3. Pré-requisitos
  4. Notas de Firmware e Hardware
  5. Implantação no ESP32
  6. Verificação e Testes
  7. FAQ
  8. Referências

Principais Recursos​

  • Conversa por voz em tempo real: link de áudio bidirecional e baixa latência baseado em Agora RTC
  • Integração direta com AI Agent v2: o dispositivo conecta-se diretamente à API v2 do Agora Conversational AI Agent
  • Controle por botão do XVF3800: varredura I2C dos botões para iniciar/parar conversas
  • Cancelamento de Eco Acústico (AEC): AEC integrado no pipeline de áudio do dispositivo para melhorar a qualidade da conversa
  • Codec G.711 μ-law: codec/decodificador eficiente para cenários de voz embarcada
  • Backend de IA configurável: o exemplo oferece suporte a OpenAI / Azure OpenAI, etc.
  • Taxa de amostragem de 8 kHz: otimizada para cenários de conversação por voz

Arquitetura do Sistema​

Visão Geral da Arquitetura​

┌─────────────────────────────────────────────────────────────────────┐
│                          System Architecture                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌─────────────────┐                    ┌─────────────────────────┐ │
│  │   ESP32-S3 Device│                    │   Agora Conversational  │ │
│  │   (Edge)         │                    │      AI Agent v2        │ │
│  ├─────────────────┤                    ├─────────────────────────┤ │
│  │ • Microphone cap.│ ──── Agora RTC ──→ │ • ASR (speech recog.)   │ │
│  │ • WiFi           │     real-time audio│ • LLM (large language)  │ │
│  │ • Speaker play   │ ←── Agora RTC ──── │ • TTS (speech synth.)   │ │
│  │ • Button control │                    │ • Agent mgmt/auth       │ │
│  └─────────────────┘                    └─────────────────────────┘ │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Pipeline de Processamento de Áudio na Borda​

Microphone (XVF3800)
    ↓ I2S (DIN)
I2S Capture
    ↓
AEC / Audio Processing
    ↓
RTC Encode (G.711 μ-law, 8kHz)
    ↓
Agora RTC Uplink → AI Agent v2
    ↓
(Cloud: ASR → LLM → TTS)
    ↓
Agora RTC Downlink ← AI Agent v2
    ↓
RTC Decode
    ↓
I2S Playback (DOUT)
    ↓
Speaker (3.5mm / AIC3104)

Pré-requisitos​

Requisitos de Hardware​

HardwareDescrição
Seeed Studio XIAO ESP32-S3Placa controladora principal (versão com PSRAM recomendada)
reSpeaker XVF3800Placa de expansão com matriz de 4 microfones (com DSP)
Alto-falanteConectar ao conector de áudio de 3,5 mm para reprodução
Cabo de dados USB-CPara gravação de firmware e alimentação
Note

Neste projeto, o codec/decodificação de áudio é tratado pelo XVF3800 juntamente com o AIC3104. O ESP32-S3 transfere dados de áudio via I2S e controla o codec/botões via I2C.

Requisitos de Software​

SoftwareVersão RecomendadaFinalidade
ESP-IDFv5.2.3Framework de desenvolvimento para ESP32
ESP-ADFv2.7Framework de desenvolvimento de áudio para ESP32
Python3.8+Dependências da toolchain/build
GitMais recenteObtenção e gerenciamento de código

Habilitar Conversational AI (Console Agora)​

Esta seção garante que seu projeto Agora tenha a opção Enable Conversational AI ativada no Console, e que você tenha preparado o App ID / App Certificate / RTC Token necessários para chamadas subsequentes. Se você pular esta etapa, o dispositivo pode ingressar no canal RTC com sucesso, mas ainda assim falhar em acionar o pipeline de conversação do Conversational AI Engine.

O que você precisa​

  • Uma conta Agora
  • Um Projeto Agora (recomendado: criar com Secured mode: APP ID + Token (Recommended))
  • Informações do projeto:
    • App ID
    • App Certificate (para geração de token no servidor)
    • RTC Token (temporário ou gerado no servidor) (para teste de ingresso no RTC)

1) Criar conta / Fazer login no Agora (Visão geral)​

  • Suporta registro por e-mail/telefone e login de terceiros.
  • Após o registro, faça login no Agora Console; normalmente você será guiado para criar um projeto.

2) Criar um Projeto Agora (Visão geral)​

Na página Projects no Agora Console:

  1. Clique em Create New
  2. Preencha o nome do Projeto / Caso de uso
  3. Método de autenticação: APP ID + Token (recomendado)
  4. Envie para criar

Create project

Por que o modo Token é recomendado?

Ele é mais seguro para produção e se alinha melhor com o fluxo de autenticação oficialmente recomendado para integração de Conversational AI / RTC.

3) Obter o App ID​

Na lista de Projects, encontre seu projeto e copie o App ID. Get App ID

4) Obter o App Certificate (para geração de token no servidor)​

  1. Na lista de Projects, clique no ícone ✏️ (editar/configurar) à direita do projeto. Get App Certificate
  2. Na página de configuração do projeto, copie o App Certificate na seção Primary Certificate. Get App Certificate
Importante

O App Certificate é uma informação sensível. Não o envie para repositórios públicos nem o imprima em logs públicos.

5) Gerar um RTC Token (para teste rápido)​

Dois métodos comuns:

  • Gerar um token temporário no Console (Temp Token)

    1. Vá para a página de configuração do projeto
    2. Clique em Generate Temp Token no painel Security
    3. Insira o nome do Canal → Generate → copie o Token

  • Usar o Agora Token Builder (web)

    • Preencha App ID / App Certificate, nome do canal, UID, etc. para gerar um Token (útil para validação rápida antes de você implementar a geração de token no servidor)

6) Ativar Enable Conversational AI (Crítico)​

Antes de usar o Conversational AI Engine, você deve ativá-lo no Console para o seu aplicativo:

  1. Vá para Projects, encontre o projeto de destino e clique em ✏️ para entrar na configuração. Enable Conversational AI
  2. Em All features, encontre Conversational AI > Configurations
  3. Ative a chave Enable Conversational AI. Enable Conversational AI
Console antigo vs. novo

Se você estiver vendo a interface antiga, mude primeiro para o novo Console (a página normalmente oferece uma opção como “Switch to the new version”).

Notas de Firmware e Hardware​

Mapeamento de Pinos Principal (reSpeaker XVF3800 + XIAO ESP32-S3)​

InterfaceFunçãoPino do ESP32-S3
I2CControle do codec + botõesSDA=GPIO5, SCL=GPIO6
I2SDados de áudioBCLK=GPIO8, WS=GPIO7, DOUT=GPIO44, DIN=GPIO43
PowerAlimentação/GravaçãoUSB-C (XIAO ESP32-S3)
Importante

A configuração padrão de placa do ESP-ADF geralmente é preparada para a Korvo-2-V3. Seu mapeamento de pinos é diferente do XVF3800. Se você não configurar de acordo com este guia, sintomas comuns incluem codec não detectado via I2C / nenhum áudio em I2S.

Implantação no ESP32​

Clone este repositório​

git clone https://github.com/AgoraIO-Conversational-AI/esp32-client/tree/main/esp32-respeaker

Configuração do Ambiente de Desenvolvimento​

Etapa 1: Instalar ESP-IDF v5.2.3​

mkdir -p ~/esp
cd ~/esp
git clone -b v5.2.3 --recursive https://github.com/espressif/esp-idf.git

cd esp-idf
./install.sh esp32s3

# (Recommended) Create an environment load alias (write into ~/.bashrc or ~/.zshrc)
alias get_idf='. $HOME/esp/esp-idf/export.sh'

Etapa 2: Instalar ESP-ADF v2.7​

cd ~/esp
git clone -b v2.7 --recursive https://github.com/espressif/esp-adf.git

export ADF_PATH=~/esp/esp-adf
echo 'export ADF_PATH=~/esp/esp-adf' >> ~/.bashrc  # or ~/.zshrc

Etapa 3: Aplicar patches do IDF (requerido pelo ESP-ADF)​

cd ~/esp/esp-idf
git apply $ADF_PATH/idf_patches/idf_v5.2_freertos.patch

Baixar o Agora IoT SDK​

Extraia o Agora IoT SDK no diretório components/ do projeto (usando a raiz do projeto como exemplo):

cd /path/to/esp32-client-Respeaker-convo/components

wget https://rte-store.s3.amazonaws.com/agora_iot_sdk.tar
tar -xvf agora_iot_sdk.tar

Após a extração, a estrutura de diretórios deve ser semelhante a:

components/agora_iot_sdk/
├── CMakeLists.txt
├── include/
│   └── agora_rtc_api.h
└── libs/
    ├── libagora-cjson.a
    ├── libahpl.a
    └── librtsa.a

Configurar Pinos da Placa ESP-ADF (Crítico)​

Este projeto usa a placa ESP-ADF Korvo-2-V3 como base, mas você deve substituir seu mapeamento de pinos pela configuração do XVF3800.

Método A (Recomendado): sobrescrever board_pins_config.c diretamente

cp board_configs/board_pins_config_respeaker.c    $ADF_PATH/components/audio_board/esp32_s3_korvo2_v3/board_pins_config.c

Verifique se entrou em vigor:

grep "TAG =" $ADF_PATH/components/audio_board/esp32_s3_korvo2_v3/board_pins_config.c

A saída esperada inclui:

static const char *TAG = "RESPEAKER_XVF3800";
Por que modificar isto?

Porque o controle do codec (AIC3104) e a captura/reprodução I2S dependem do mapeamento correto dos pinos I2C/I2S. Se os pinos estiverem errados, você verá problemas como timeout de I2C / não consegue detectar 0x18 / sem som, etc.

Configuração de Parâmetros do Projeto​

Edite main/app_config.h e configure o seguinte:

1) WiFi​

#define WIFI_SSID                "Your_WiFi_SSID"
#define WIFI_PASSWORD            "Your_WiFi_Password"

2) Informações da conta Agora​

#define AGORA_APP_ID             "your_agora_app_id"
#define AGORA_API_KEY            "your_agora_api_key"
#define AGORA_API_SECRET         "your_agora_api_secret"

3) Canal e UID do RTC​

#define CONVO_CHANNEL_NAME       "your_unique_channel"
#define CONVO_RTC_TOKEN          ""  // Optional: tokens recommended in production
#define CONVO_AGENT_RTC_UID      1001
#define CONVO_REMOTE_RTC_UID     1000

4) Configuração de LLM (exemplos: OpenAI / Azure OpenAI)​

#define LLM_URL                  "https://api.openai.com/v1/chat/completions"
#define LLM_API_KEY              "sk-your-openai-api-key"
#define LLM_MODEL                "gpt-4o-mini"
#define LLM_SYSTEM_MESSAGE       "You are a helpful AI assistant."
#define LLM_URL                  "https://your-resource.openai.azure.com/openai/deployments/..."
#define LLM_API_KEY              "your-azure-api-key"
#define LLM_MODEL                "gpt-4"

5) Configuração de TTS (exemplo: Azure TTS)​

#define TTS_VENDOR               "azure"
#define TTS_API_KEY              "your-azure-speech-key"
#define TTS_REGION               "tts-region"
#define TTS_VOICE_NAME           "en-US-JennyNeural"

6) Configuração de ASR​

#define ASR_LANGUAGE             "en-US"

Compilar e Gravar​

Etapa 1: Carregar o ambiente ESP-IDF​

get_idf
# or
. $HOME/esp/esp-idf/export.sh

Etapa 2: Entrar no diretório do projeto e definir o alvo​

cd /path/to/esp32-client-Respeaker-convo
idf.py set-target esp32s3

Etapa 3: Compilar​

idf.py build

Etapa 4: Gravar e monitorar​

# Linux
idf.py -p /dev/ttyUSB0 flash monitor

# macOS
idf.py -p /dev/cu.usbmodem* flash monitor

# Windows
idf.py -p COM3 flash monitor
Permissões seriais no Linux

Se você vir “permission denied”, execute:

sudo usermod -aG dialout $USER
# Then log out and log back in

Verificação e Testes​

Lista de Verificação do Log de Inicialização​

Em uma inicialização bem-sucedida, o log serial normalmente inclui:

  • WiFi conectado e IP obtido
  • AIC3104 detectado (o endereço I2C geralmente é 0x18)
  • Pipeline de áudio iniciado com sucesso
  • Agora RTC entrou com sucesso (ou está pronto)

Exemplo (apenas para referência):

WiFi connected
got ip: 192.168.x.x
Found device at address 0x18
AIC3104 Codec initialized successfully
agora_rtc_join_channel success

Iniciar uma Conversa (Controle por Botão)​

  1. Ligue e aguarde até que o dispositivo esteja pronto
  2. Pressione o botão SET uma vez: iniciar/entrar na conversa (o Agente entra no canal RTC)
  3. Fale no microfone e aguarde o alto-falante reproduzir a resposta da IA
  4. Pressione SET novamente (ou pressione MUTE) para encerrar a conversa

FAQ​

P1: Timeout de I2C / AIC3104 (0x18) não encontrado​

Causas possíveis:

  • board_pins_config.c do ESP-ADF não foi substituído conforme descrito neste guia
  • Mapeamento incorreto de pinos I2C (deve ser SDA=GPIO5, SCL=GPIO6)
  • Problema de conexão de hardware (XIAO e XVF3800 não estão encaixados corretamente)

Verificações sugeridas:

  • Repita a etapa “Configurar Pinos da Placa ESP-ADF” e, em seguida, execute idf.py fullclean e faça o build novamente
  • Verifique se o log de inicialização consegue detectar 0x18

Causas comuns:

  • Direção DIN/DOUT de I2S configurada incorretamente (DIN=GPIO43, DOUT=GPIO44)
  • Alto-falante não conectado ao conector de 3,5 mm ou volume muito baixo
  • AEC/pipeline de áudio não iniciou corretamente

P3: Erros de build ou dependências ausentes​

Sugestões:

  • Confirme se as versões do ESP-IDF / ESP-ADF correspondem a este guia
  • Re-inicialize os submódulos (se o projeto usar submódulos): 
    git submodule update --init --recursive
  • Faça uma limpeza completa: 
    idf.py fullclean

Referências​

  • Agora Console (App ID / API Key)
  • Documentação do Agora RTC e documentação do IoT SDK
  • Documentação do ESP-IDF v5.2.3
  • Documentação do ESP-ADF v2.7
  • Introdução e guia de atualização de firmware do reSpeaker XVF3800
  • Clientes de IA Conversacional em ESP32

Suporte Técnico e Discussão sobre o Produto​

Obrigado por escolher nossos produtos! Estamos aqui para fornecer diferentes tipos de suporte para garantir que sua experiência seja o mais tranquila possível. Oferecemos vários canais de comunicação para atender a diferentes preferências e necessidades.

Loading Comments...