Introdução

O sistema de navegação AIGlasses integra inteligência artificial, sensores e funções de navegação em um dispositivo vestível, projetado para oferecer orientação intuitiva e segura através de interação multimodal. Muitos usuários enfrentam dificuldades durante a configuração inicial. Este guia aborda problemas comuns com a configuração da API, conexão do hardware e inicialização do serviço, fornecendo soluções detalhadas para colocar o sistema em funcionamento rapidamente.

1. Configuração da API: Resolução de Problemas

---

1.1. Importância da Chave de API

Funcionalidades essenciais como reconhecimento de fala, interação por IA e processamento multimodal dependem do serviço DashScope da Alibaba Cloud. Uma chave de API configurada corretamente é crucial; caso contrário, o sistema exibirá erros como "API não configurada" ou "Falha no reconhecimento de voz".

1.2. Obtendo e Configurando a Chave de API

Passo 1: Obtenção da chave

1. Acesse o console do DashScope (https://dashscope.console.aliyun.com/).
2. Faça login com sua conta Alibaba Cloud.
3. Navegue até "Gerenciamento de API-KEY" e crie uma nova chave. Copie o valor (geralmente no formato sk-xxxxxxxxxx...).

Passo 2: Inserção no sistema AIGlasses

1. Abra a interface web: http://IP_DO_SERVIDOR:8081.
2. No canto superior direito, clique no ícone de engrenagem e selecione "Configuração da API".
3. Colle a chave e salve as alterações.

Indicação de Sucesso: A interface exibirá "API configurada" e o status no painel do sistema mudará para verde.

1.3. Solução de Erros Comuns

Erro: Formato inválido da chave

Sintoma: Falha imediata ao salvar.

Solução: Verifique se a chave foi copiada integralmente, sem espaços extras, e começa com sk-.

Erro: Problemas de rede

Sintoma: A chave está configurada, mas o reconhecimento de voz falha.

Solução: Teste a conectividade com o domínio do serviço.

# Testar a resolução e conectividade DNS
nslookup dashscope.aliyuncs.com
traceroute dashscope.aliyuncs.com

Erro: Cota excedida

Sintoma: Funcionalidade cessa após uso inicial.

Solução: Verifique a cota restante no console da Alibaba Cloud e adicione créditos se necessário.

2. Conexão e Configuração de Hardware

---

2.1. Modos de Operação

O sistema pode operar em modo com hardware (usando ESP32-CAM para captura de vídeo em tempo real) ou em modo navegador (para testes e uso parcial sem dispositivo físico).

2.2. Funcionalidades do Modo Navegador

Sem hardware externo, você pode:

• Verificar o status de todos os serviços no painel de controle da web.
• Fazer upload de vídeos locais (MP4, AVI, etc.) para testar algoritmos de detecção (como faixas de pedestres e semáforos).

2.3. Passos para Conexão com ESP32-CAM

Etapa 1: Gravação do firmware

No Arduino IDE, abra o arquivo principal do projeto, selecione a placa ESP32 e a porta correta, e faça o upload do código.

Etapa 2: Configuração da rede Wi-Fi

Modifique as credenciais de rede diretamente no código-fonte antes da gravação.

// Definição das credenciais de rede no código do ESP32
const char* IDENTIFICACAO_REDE = "NomeDaMinhaRede";
const char* SENHA_REDE = "SenhaForte123";

Nota: O ESP32 deve estar na mesma rede local que o servidor do AIGlasses.

Etapa 3: Verificação da conexão

Após a inicialização, o ESP32 se conectará automaticamente ao servidor via WebSocket. O status da câmera deve aparecer como "Conectado" na interface web.

2.4. Resolução de Problemas de Hardware

Problema: ESP32 não conecta ao Wi-Fi

Diagnóstico: LED piscando rapidamente.

Ações: Verifique as credenciais, a intensidade do sinal e se o roteador bloqueia novos dispositivos.

Problema: Stream de vídeo instável

Diagnóstico: Imagens travadas ou com alto atraso.

Ações: Reduza a resolução no código do ESP32 e certifique-se de que ambos os dispositivos estejam na mesma rede local.

3. Gerenciamento e Inicialização do Serviço

---

3.1. Verificação do Status

Utilize o gerenciador de processos para verificar se o serviço está em execução.

# Comando para verificar o status do processo
supervisorctl status nome_do_servico
# Saída esperada: nome_do_servico   RUNNING   pid 1234, uptime ...

3.2. Diagnóstico de Falhas na Inicialização

Passo 1: Análise de logs

Os logs são a feramenta principal de diagnóstico.

# Visualizar as últimas linhas do log de aplicação
tail -n 50 /var/log/aiglasses/servidor.log

# Acompanhar os logs em tempo real
tail -f /var/log/aiglasses/servidor.log

Erros Comuns em Log:

Erro: Porta já em uso

Error: Address already in use: 0.0.0.0:8081

Solução: Identifique e encerre o processo que ocupa a porta.

# Encontrar processo usando a porta 8081
ss -tulpn | grep :8081
# Encerrar processo (use com cuidado)
kill -9 PID_DO_PROCESSO

Erro: Dependência Python ausente

ModuleNotFoundError: No module named 'nome_do_modulo'

Solução: Instale as dependências listadas no arquivo de requisitos do projeto.

pip install -r requirements.txt

Passo 2: Inicialização manual para teste

Execute o script principal diretamente para obter mensagens de erro mais detalhadas.

cd /diretorio/do/projeto
python app_principal.py

3.3. Comandos Essenciais de Gerenciamento

# Iniciar o serviço
supervisorctl iniciar nome_do_servico

# Parar o serviço
supervisorctl parar nome_do_servico

# Reiniciar o serviço (ação mais comum)
supervisorctl reiniciar nome_do_servico

# Recarregar a configuração do supervisord
supervisorctl recarregar

3.4. Configuração de Inicialização Automática

Para que o serviço inicie automaticamente com o sistema, configure seu gerenciador de serviços (como systemd ou supervisor).

Exemplo de unidade de serviço (systemd):

[Unit]
Description=Serviço de Navegação AIGlasses
After=network.target

[Service]
User=usuario_do_servico
WorkingDirectory=/caminho/para/o/projeto
ExecStart=/usr/bin/python3 app_principal.py
Restart=always

[Install]
WantedBy=multi-user.target

Após criar o arquivo, habilite e inicie o serviço:

sudo systemctl enable aiglasses
sudo systemctl start aiglasses

4. Otimização e Manutenção do Sistema

---

4.1. Dicas de Desempenho

Para melhorar a performance:

• Monitoramento: Use ferramentas como htop ou nmon para identificar gargalos de CPU ou memória.
• Espaço em disco: Limpe regularmente logs antigos e arquivos temporários.
• Modelos de IA: Considere usar versões quantizadas dos modelos para reduzir o consumo de recursos.

4.2. Rotina de Manutenção

Estabeleça uma rotina periódica para:

1. Gerenciamento de Logs: Configure rotação de logs para evitar consumo excessivo de espaço.
2. Atualizações: Mantenha as dependências do Python atualizadas, após testes em ambiente de desenvolvimento.
3. Backup: Realize backups regulares dos arquivos de configuração e dos pesos dos modelos customizados.

4.3. Recuperação de Falhas Graves

Em caso de falha sistêmica:

1. Pare todos os serviços do AIGlasses.
2. Faça um backup do diretório de instalação atual.
3. Analise os logs detalhadamente para identificar a causa raiz.
4. Considere re-instalar o sistema a partir de um backup estável, se necessário.