🤖 RoboPlotter

Robô de chão que desenha plantas baixas em escala real no piso, a partir de um arquivo DXF.

Tração diferencial (duas rodas + caneta no centro de rotação), cérebro em ESP32 (DevKit V1). O firmware sobe um Access Point WiFi e serve uma página onde você carrega o DXF, vê a pré-visualização e manda o robô desenhar — ele percorre os traços levantando e baixando a caneta sozinho.

🟢 Novo aqui?	🔌 Eletrônica	📐 Pinagem
GUIA.md — explicação sem termos técnicos	Diagrama elétrico	PINOUT.md

---

Índice

• Destaques
• Como funciona
• Hardware
• Estrutura de arquivos
• Compilar e gravar
• Como usar
• Calibração
• Testes
• Documentação
• Autor

---

✨ Destaques

• DXF → chão: carrega o desenho no navegador, otimiza a ordem do traçado e envia por WiFi.
• Controle em tempo real: malha a 100 Hz no core 1 (PID de velocidade por roda, odometria, fusão de pose e seguidor de trajetória estilo pure-pursuit); WiFi + servidor web no core 0.
• Heading sem drift: encoders de quadratura (PCNT) + IMU 9-DoF ICM-20948 (giroscópio + magnetômetro), com filtro complementar.
• Calibração automática pela página web: auto-tune de PID (relay-feedback), bússola (hard/soft-iron), checagem de sentido motor/encoder, e ensaios de roda/bitola — com passo a passo.
• Tudo num lugar só: cada parâmetro calibrável vive em src/config.h — sem "número mágico" espalhado.
• Verificado: os 3 ambientes compilam e há testes Unity da matemática (Kinematics, PID, PathFollower).

🧠 Como funciona

   Desenho (DWG) ──► converte p/ DXF ──► página web ──► (WiFi) ──► ROBÔ desenha no chão

O robô sabe onde está combinando quanto andou (encoders nas rodas) com para onde aponta (IMU/bússola). A página transforma o DXF em uma lista de waypoints com comandos de caneta (sobe/desce); o firmware segue essa trajetória corrigindo rumo e velocidade em malha fechada.

Explicação completa para leigos em GUIA.md. O fluxo elétrico inteiro está desenhado em docs/diagrama_eletronico.svg.

🔩 Hardware (resumo da BOM)

Item	Peça	Notas
MCU	ESP32 DevKit V1 (WROOM-32)	core 0 = rede, core 1 = controle
Motores	2× JGA25-370 (6 V) c/ encoder	redução 74.83, 11 PPR no motor
Driver	L298N (ponte H dupla)	PWM por LEDC a 20 kHz, 10 bits, teto de duty
Rodas	Ø 68 mm	bitola ~184,2 mm (centro a centro)
IMU	SparkFun ICM-20948 (I2C, 0x69)	heading absoluto
GPS	u-blox NEO-M8N (UART2)	opcional, só uso externo (USE_GPS 0 no MVP)
Caneta	servo MG995	2 posições calibráveis (sobe/desce)
Energia	pack 3S 12 V + buck 8 V + 2× step-down 5 V	monitor de tensão por ADC, fusível, GND comum

Onde ligar cada fio: PINOUT.md (pino a pino) · alimentação e montagem em docs/WIRING.md · fonte dos números em src/config.h (seções 11–12).

🗂️ Estrutura de arquivos

robotPlotter/
├─ platformio.ini        # ambientes esp32dev / bench / test_logic, libs, partições
├─ GUIA.md               # explicação para leigos
├─ PINOUT.md             # onde ligar cada fio no ESP32
├─ src/
│  ├─ config.h           # PONTO ÚNICO DE CALIBRAÇÃO (leia primeiro)
│  ├─ main.cpp           # setup() + task de controle (core 1) e loop() (core 0)
│  ├─ bench_main.cpp     # firmware de TESTE DE BANCADA (env bench)
│  ├─ RobotController.*  # orquestra os módulos e o buffer da trajetória
│  ├─ Calibration.*      # rotinas de calibração automática
│  ├─ Comms.*            # WiFi AP + AsyncWebServer + WebSocket (/ws) + LittleFS
│  ├─ Encoders.*  MotorDriver.*  Pid.*  Kinematics.*   # malha de baixo nível
│  ├─ PoseEstimator.*  Imu.*  Gps.*                     # odometria / heading
│  ├─ PathFollower.*  PenServo.*  Types.h               # trajetória / caneta
├─ data/                 # UI web servida da LittleFS (vai pro ESP32 via uploadfs)
├─ web/index.html        # cópia STANDALONE da UI (abre no navegador, sem o robô)
├─ tools/build_standalone.py   # gera o web/index.html a partir de data/
├─ test/                 # testes (ver test/README.md)
└─ docs/                 # WIRING · CALIBRATION · PROTOCOL · diagrama_eletronico.svg

🛠️ Compilar e gravar

Pré-requisito: PlatformIO (pip install platformio ou a extensão do VS Code).

pio run -e esp32dev -t upload     # grava o firmware no ESP32
pio run -e esp32dev -t uploadfs   # grava a UI web (data/ -> LittleFS)
pio device monitor                # console serial a 115200

⚠️ Grave os dois. upload envia só o firmware; uploadfs é obrigatório para a página web chegar ao ESP32 — sem ele a UI em 192.168.4.1 não carrega. No Windows, use PYTHONIOENCODING=utf-8 se o pio reclamar de acentos no console.

▶️ Como usar

1. Ligue o robô → ele cria a rede WiFi RoboPlotter (senha plotter123).
2. Conecte o celular/PC nessa rede.
3. Abra http://192.168.4.1 (ou o web/index.html no PC).
4. Carregue o DXF, ajuste escala/posição e confira a prévia.
5. Conectar → Enviar → Iniciar. A página mostra pose, progresso e bateria em tempo real; há Pausar, Parar e E-STOP.

Não tem DXF? Converta seu DWG → DXF de graça no ODA File Converter (o navegador não lê DWG).

🎯 Calibração

A própria página tem um painel Calibração com botões automáticos e instruções passo a passo:

• Auto-tune PID · Bússola (mag) · Checar direção (rodas no ar)
• Andar reto · Girar 360° (rodas no chão, você mede e digita)

Cada rotina sugere o valor para colar no src/config.h. Procedimento detalhado em docs/CALIBRATION.md. O auto-tune também existe no firmware de bancada (modo a).

🧪 Testes

Comando	O que faz
pio run -e bench -t upload	Teste de bancada (menu serial: testa cada módulo de hardware ao vivo)
pio test -e test_logic	Testes Unity da matemática (Kinematics, PID, PathFollower) no ESP32

Detalhes em test/README.md.

📚 Documentação

Quero…	Abra
Entender o projeto (leigo)	GUIA.md
Ver o diagrama elétrico	docs/diagrama_eletronico.svg
Saber qual fio vai em qual pino	PINOUT.md
Montagem / alimentação	docs/WIRING.md
Calibrar o robô	docs/CALIBRATION.md
Protocolo PC ↔ ESP32 (WebSocket)	docs/PROTOCOL.md
Rodar os testes	test/README.md
Mexer nos ajustes	src/config.h

👤 Autor

Murillo Vinícius 💻 GitHub: @dantazzzz 📧 E-mail: murillovinicius18@gmail.com

Projeto pessoal de robótica (ESP32 + controle + visão de trajetória). Sugestões e issues são bem-vindas!

📄 Licença

Distribuído sob Creative Commons Atribuição-NãoComercial 4.0 (CC BY-NC 4.0) — veja LICENSE. © 2026 Murillo Vinícius.

Você pode estudar, usar, modificar e compartilhar sem fins comerciais, sempre creditando o autor. Uso comercial exige autorização por escrito (murillovinicius18@gmail.com).