Kill Switch - Protocolo Wireless

1. Botão Físico Wireless

O Botão Físico Wireless utiliza o microcontrolador ESP32C3 para monitorar o botão Metaltex e enviar comandos via WiFi.

1.1 Funcionamento do Hardware

• Hardware: Metaltex CP1-E + ESP32C3 Super Mini.
• Conectividade: WiFi 2.4GHz (Rede Unitree).
• Lógica: Ao detectar o pressionamento (GPIO 0 -> LOW), o ESP32C3 dispara uma requisição HTTP POST para o robô.

2. Visão Geral do Protocolo HTTP

As mudanças atuais adicionam um segundo canal de comunicação via HTTP/WiFi, complementando o canal Serial da sprint passada.

Características:

• Protocolo: HTTP/1.1
• Servidor: Axum (Rust async web framework)
• Porta: 3000
• Rede: WiFi Unitree interna
• Autenticação: Nenhuma (rede interna)

3. Endpoints do Kill Switch

3.1 POST /emergency/press

Inicia o Dump Mode continuamente.

Requisição:

POST /emergency/press HTTP/1.1
Host: robot.local:3000
Content-Type: application/json

{}

Resposta (200 OK):

{
  "status": "pressed",
  "message": "Kill Switch ativado",
  "timestamp": "2025-12-18T10:30:45Z"
}

Comportamento:

1. Muda estado para Pressed
2. Dispara callback
3. ROS 2 publica comando DAMP
4. Robô ativa Dump Mode
5. Continua enviando DAMP enquanto pressionado

3.2 POST /emergency/release

Para o Dump Mode e inicia Recover.

Requisição:

POST /emergency/release HTTP/1.1
Host: robot.local:3000
Content-Type: application/json

{}

Resposta (200 OK):

{
  "status": "released",
  "message": "Kill Switch liberado",
  "timestamp": "2025-12-18T10:30:46Z"
}

Comportamento:

1. Muda estado para Released
2. Para envio de DAMP
3. Dispara callback
4. ROS 2 publica comando RECOVER
5. Robô retorna ao estado normal

3.3 GET /emergency/status

Consulta o status atual do Kill Switch.

Requisição:

GET /emergency/status HTTP/1.1
Host: robot.local:3000

Resposta (200 OK):

{
  "status": "released",
  "last_pressed": "2025-12-18T10:30:45Z",
  "uptime_seconds": 3600
}

4. Endpoints de Emotes

4.1 POST "emote_name"

Aciona um emote específico.

Emotes Disponíveis:

• /emote/hello
• /emote/stretch
• /emote/content
• /emote/wallow
• /emote/dance1
• /emote/dance2
• /emote/pose
• /emote/scrape

Requisição:

POST /emote/hello HTTP/1.1
Host: robot.local:3001
Content-Type: application/json

{}

Resposta (200 OK):

{
  "emote": "hello",
  "id": 1016,
  "status": "executing",
  "duration_ms": 2000
}

Resposta (429 Too Many Requests):

{
  "error": "Rate limit exceeded",
  "retry_after_seconds": 15,
  "message": "Aguarde 20 segundos entre emotes"
}

Comportamento:

1. Verifica rate limit (20s)
2. Se OK, publica comando ROS 2
3. Robô executa emote
4. Retorna status

5. Máquina de Estados HTTP

O serviço HTTP implementa máquina de estados para evitar duplicatas:

┌─────────────┐
│  RELEASED   │ ◄─────────────────────┐
└──────┬──────┘                       │
       │                              │
       │ POST /emergency/press        │
       │                              │
       ▼                              │
┌─────────────┐                       │
│  PRESSING   │                       │
└──────┬──────┘                       │
       │                              │
       │ POST /emergency/release      │
       │                              │
       └──────────────────────────────┘

Transições:

• RELEASED → PRESSING: POST /emergency/press
• PRESSING → RELEASED: POST /emergency/release
• Requisições duplicadas são ignoradas

6. Rate Limiting para Emotes

O sistema implementa rate limiting para proteger contra abuso:

Regra:

• Máximo 1 emote a cada 20 segundos
• Contador por sessão/cliente
• Retorna 429 se limite excedido

Exemplo:

T+0s:   POST /emote/hello     → 200 OK
T+5s:   POST /emote/stretch   → 429 Too Many Requests
T+20s:  POST /emote/stretch   → 200 OK

7. Fluxo de Transmissão HTTP

Kill Switch via HTTP

1. Cliente envia POST /emergency/press
2. Servidor HTTP recebe requisição
3. Estado muda para Pressed
4. Callback dispara
5. ROS 2 publica comando de dump
6. Motor controller recebe comando
7. Dump Mode ativado

Emote via HTTP

1. Cliente envia POST /emote/hello
2. Servidor verifica rate limit
3. Se OK, callback dispara
4. ROS 2 publica comando de emote
5. Robô executa movimento
6. Retorna 200 OK

8. Integração Dual-Channel

Ambos os canais (Serial + HTTP) funcionam simultaneamente:

Serial:

• Botão físico pressionado
• ESP32C3 envia '1' via serial
• Rust recebe e processa

HTTP:

• Cliente envia POST /emergency/press
• Servidor HTTP recebe
• Callback processa

Resultado:

• Ambos disparam o mesmo ROS command
• Ambos ativam Dump Mode
• Ambos têm igual prioridade