Skip to content

README.md

Latest commit

 

History

History
254 lines (190 loc) · 5.55 KB

README.md

File metadata and controls

254 lines (190 loc) · 5.55 KB
Raw

PC-Side Service

Serviço HTTP local em Python para comunicação com ESP32. Fornece endpoints para verificar o status do PC e receber eventos.

🎯 Objetivo

  • Manter um serviço rodando no PC que responde via HTTP
  • Permitir que o ESP32 verifique se o PC está online e pronto
  • Receber e processar eventos do ESP32 ou outros módulos
  • Base para futuras integrações (logs, persistência, autenticação)

📋 Stack

  • Python 3.12
  • FastAPI - Framework web moderno e rápido
  • Uvicorn - Servidor ASGI
  • Docker & Docker Compose - Containerização

🚀 Início Rápido

Opção 1: Rodar com Docker Compose (Recomendado)

# Clone ou navegue para o diretório do projeto
cd /home/alvaro/to-ligado

# Suba o serviço
docker-compose up -d

# Verifique se está rodando
curl http://localhost:8888/health

# Ver logs
docker-compose logs -f pc-side

# Parar o serviço
docker-compose down

Opção 2: Rodar localmente (sem Docker)

# Criar ambiente virtual
python3.12 -m venv venv
source venv/bin/activate  # No Windows: venv\Scripts\activate

# Instalar dependências
pip install -r requirements.txt

# Copiar arquivo de configuração
cp .env.example .env

# Rodar
python main.py

📡 Endpoints da API

1. GET /health

Verificação básica de saúde do serviço.

Request:

curl -X GET http://localhost:8888/health

Response:

{
  "status": "ok",
  "timestamp": "2026-05-01T10:30:00Z"
}

2. GET /status

Retorna status detalhado do PC e serviço.

Request:

curl -X GET http://localhost:8888/status

Response:

{
  "online": true,
  "hostname": "meu-pc",
  "service_version": "0.1.0",
  "timestamp": "2026-05-01T10:30:00Z",
  "pc_uptime_seconds": null
}

3. POST /event

Recebe eventos do ESP32 ou de outros módulos.

Request:

curl -X POST http://localhost:8888/event \
  -H "Content-Type: application/json" \
  -d '{
    "source": "esp32-sensor-1",
    "event_type": "temperature",
    "data": {
      "temperature": 25.5,
      "humidity": 60,
      "location": "sala"
    },
    "timestamp": "2026-05-01T10:30:00Z"
  }'

Response:

{
  "success": true,
  "message": "Evento 'temperature' recebido de 'esp32-sensor-1'",
  "timestamp": "2026-05-01T10:30:01Z"
}

🔧 Configuração

As variáveis de ambiente estão em .env.example. Copie para .env e customize:

SERVICE_HOST=0.0.0.0      # Interface de escuta
SERVICE_PORT=8888         # Porta do serviço
SERVICE_VERSION=0.1.0     # Versão da API
LOG_LEVEL=INFO            # Nível de log (DEBUG, INFO, WARNING, ERROR)

📚 Exemplos para ESP32

Arduino/ESP32 - Verificar Status do PC

#include <WiFi.h>
#include <HTTPClient.h>
#include <ArduinoJson.h>

const char* PC_IP = "192.168.1.100";  // IP do seu PC
const int PC_PORT = 8888;

void checkPCStatus() {
  HTTPClient http;
  String url = String("http://") + PC_IP + ":" + String(PC_PORT) + "/status";
  
  http.begin(url);
  int httpCode = http.GET();
  
  if (httpCode == 200) {
    String payload = http.getString();
    DynamicJsonDocument doc(200);
    deserializeJson(doc, payload);
    
    bool pcOnline = doc["online"];
    String hostname = doc["hostname"];
    
    Serial.println("PC está online: " + String(pcOnline ? "SIM" : "NÃO"));
    Serial.println("Hostname: " + hostname);
  } else {
    Serial.println("PC offline ou serviço não responde");
  }
  
  http.end();
}

Arduino/ESP32 - Enviar Evento de Sensor

void sendSensorEvent(float temperature, float humidity) {
  HTTPClient http;
  String url = String("http://") + PC_IP + ":" + String(PC_PORT) + "/event";
  
  http.begin(url);
  http.addHeader("Content-Type", "application/json");
  
  // Criar JSON
  StaticJsonDocument<300> doc;
  doc["source"] = "esp32-sensor-1";
  doc["event_type"] = "temperature_humidity";
  doc["data"]["temperature"] = temperature;
  doc["data"]["humidity"] = humidity;
  doc["data"]["location"] = "sala";
  doc["timestamp"] = getCurrentTimestamp();
  
  String payload;
  serializeJson(doc, payload);
  
  int httpCode = http.POST(payload);
  
  if (httpCode == 200) {
    String response = http.getString();
    Serial.println("Evento enviado com sucesso: " + response);
  } else {
    Serial.println("Erro ao enviar evento: " + String(httpCode));
  }
  
  http.end();
}

📖 Documentação Interativa

Acesse a documentação interativa em: http://localhost:8888/docs

(Powered by Swagger UI - permite testar endpoints diretamente no navegador)

🔄 Próximos Passos

  • Adicionar autenticação por token simples
  • Implementar persistência local de eventos (SQLite)
  • Adicionar logs estruturados em arquivo
  • Comunicação bidirecional com ESP32
  • Endpoints para sincronizar hora e configurações
  • Suporte a múltiplos ESP32

📝 Notas

  • O serviço roda em modo de desenvolvimento por padrão
  • Para produção, adicione autenticação e use HTTPS
  • Os logs estruturados facilitarão debug e análise
  • A arquitetura é simples de estender com persistência

🐛 Troubleshooting

Porta 8888 em uso:

# Mude a porta no docker-compose.yml ou .env
docker-compose down
docker-compose up -d

Conexão recusada pelo PC:

  • Verifique se o serviço está rodando: docker-compose ps
  • Verifique firewall do PC
  • Confirme o IP do PC: hostname -I (Linux) ou ipconfig (Windows)

ESP32 não consegue conectar:

  • Verifique se ESP32 e PC estão na mesma rede
  • Teste a conectividade: ping <IP_do_PC>
  • Verifique logs: docker-compose logs pc-side

📄 Licença

MIT