carinha-control-panel/docs/BRACO.md

# Aba Braço robótico

## Calibração manual em passos de 100 µs

Dentro de Calibrar limites por canal: selecionar canal, habilitar testes, usar −100 / +100 µs ou Testar posição. Sinal expira em 2 s. Faixa absoluta 500–2500 µs, sem varredura automática nem detecção de batente. Marcar mínimo, centro ou máximo desliga os sinais e atualiza apenas a seleção local; Salvar calibração grava no Orange Pi, validando mínimo < centro < máximo e todas as posturas existentes. Se uma postura ficar fora da faixa nova, ajustar ou excluir a postura antes de salvar.

Canais 5/6 são testados em par, com deslocamentos opostos em relação aos centros salvos. Marcar um extremo de um canal também marca o extremo oposto do outro. Centro pode ser salvo individualmente; ambos precisam representar a montagem neutra correspondente. Mapeamento de graus agora é linear por trecho, 0°=500, 90°=centro calibrado, 180°=2500 µs, sempre restringido pelos extremos salvos. Graus são nominais, não medidos. Nenhum motor acionado durante validação automatizada.

Cinco sequências prontas: Acenar, Olhar para os lados, Alcançar e recolher, Garra e punho, Apresentação. São geradas dentro dos limites calibrados, sem sobrescrever posturas existentes. Prévia anima uma representação esquemática sem enviar movimento; solicita desligamento prévio dos sinais. Executar exige movimento ativado e envia sete ângulos/eight saídas com o antebraço espelhado. A interpolação usa uma fração comum para todas as articulações chegarem juntas ao fim de cada trecho; a sincronização é dos comandos, sem feedback mecânico. Animação mostra comandos nominais, não cinemática validada do modelo STEP. Testes de prévia verificam ausência de chamadas mover.

Bateria do celular adicionada ao painel principal: percentual e indicador carregando. Novo APK gerado e instalado por ADB no S10; precisa reabrir Carinha após instalação. O Android lê ACTION_BATTERY_CHANGED e inclui dados na telemetria. Sem conexão ou sem dado, o painel informa aguardando. Nenhum percentual é inferido do PC ou da placa.

Refinamento visual: sliders pretos largos com marcadores brancos, valores maiores, botões arredondados, fundo branco e ilustração SVG própria com volumes, juntas e conexões. Layout verificado em desktop e celular; testes simulados dos controles permanecem passando. Nenhuma alteração de pulsos, calibração ou canais nesta revisão visual.

Criada em 2026-10-05: http://192.168.1.35:8100/braco. Interface web inspirada na captura do aplicativo FABRI_CREATOR fornecida pelo usuário, com ilustração esquemática própria. Não é o executável Java incorporado nem uma cópia exata da arte original.

Sete controles: garra 0, punho 1 no canal 1, punho 2 no canal 2, braço superior 3, braço inferior 4, antebraço 5 com canal 6 espelhado, base 7. Cada postura enviada controla os oito canais. Confirmar ligações e montagem antes de ativar. Não misturar comandos das abas Servos e Braço ao mesmo tempo.

Movimento desativado ao abrir. Ativar movimento não envia pulsos por si só. Arrastar, carregar postura com movimento ativado ou Reproduzir envia a postura completa. O indicador de graus é nominal, conforme a fórmula do Arduino: 500 + ângulo * 2000 / 180 µs. Não mede o eixo físico. Velocidade de 5–90 graus/s é interpolação dos comandos no navegador; não há garantia da velocidade mecânica. A posição inicial estimada é a seleção da tela, não leitura do motor.

Calibração inicial independente da aba de testes: 1400–1600 µs nos oito canais (aproximadamente 81–99 graus nominais). Expandir gradualmente com os motores sem carga conforme montagem. API aceita 500–2500 µs; essa faixa do código original não é garantia de curso seguro do MG996R. O centro 1500 precisa estar dentro da calibração. Antebraço combina os limites dos canais 5 e 6 para ambos ficarem dentro da faixa.

Salvar postura grava a seleção sem movimentar e desativa o movimento. Centro na tela para os sinais e apenas seleciona 90 graus. Reproduzir executa todas as posturas uma vez, com intervalo de 700 ms entre elas. Parar sinais cancela reprodução e desliga o PWM; não corta a alimentação elétrica. Ao ocultar a aba, o cliente solicita parada. O watchdog do servidor também desliga cada canal cerca de 2 segundos após o último comando: um braço suspenso pode perder sustentação. Nesta etapa testar com braço apoiado. Não há manutenção indefinida de torque.

Configurações e até 100 posturas ficam em /opt/carinha-pc/braco.json. Não sobrescreve servos.json, app-config.json ou aparencia.json. Exportar gera JSON carinha-braco-v1. Importar aceita esse formato e valida todas as posições antes de salvar, sem mover. Não importa diretamente arquivos de postura do aplicativo original: formato ainda não analisado.

Backend compartilhado com o driver e watchdog de servos, validando a postura inteira antes de escrever I²C. Escrita de oito canais é sequencial sob lock, não eletricamente simultânea. Erro I²C solicita parada. Em falha de rede, não há novos comandos; watchdog limita duração do sinal. Movimentos são solicitados pelo navegador, não executados autonomamente na placa.

Verificado: quatro testes do braço (par espelhado, limites antes da escrita, persistência e abertura sem movimento), oito do driver, 12 do servidor; navegador com API simulada para controles, velocidade, parada, salvar/reproduzir, layout mobile; regressões das abas de servos. Nenhum motor acionado nos testes da implantação. Verificação física e calibração pendentes.

Retorno: backup anterior em /opt/carinha-pc/backup-braco-20261005. Parar carinha-pc, restaurar kiosk-server.py, painel.html e servos.html desse backup e reiniciar. Preservar braco.json. Arquivos da nova funcionalidade: braco.py, braco.html, braco.js. Serviço continua carinha-pc na porta 8100.