From fd47a622ccba01f0f0e8c84e817bf807bcb5c312 Mon Sep 17 00:00:00 2001
From: javiservices <javiservices@anabolictrack.com>
Date: Wed, 17 Jun 2026 02:09:26 +0200
Subject: [PATCH] docs: README firmware

---
 README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 112 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e6cdbb8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,112 @@
+# DummyBot Firmware
+
+Firmware del ESP32 para **DummyBot**, task manager para TDAH.
+
+## Hardware
+
+- **ESP32-D0WD-V3** (DevKitC / WROOM-32, 4 MB flash)
+- **Pantalla M130T-240240-RGB-7-V1.1** (ST7789 240x240 SPI, sin CS)
+- **3× TTP223** (botones táctiles: Siguiente / Hecha / Snooze)
+- **1× motor vibrador 1027** (3V DC, controlado por MOSFET en GPIO 25)
+
+### Cableado
+
+```
+ESP32 (WROOM-32)        M130T-240240-RGB-7-V1.1
+─────────────────────   ─────────────────────────
+3V3          ───────▶   VCC
+GND          ───────▶   GND
+GPIO 18      ───────▶   SCL  (SPI clock)
+GPIO 23      ───────▶   SDA  (SPI MOSI)
+GPIO 2       ───────▶   RES  (reset)
+GPIO 4       ───────▶   DC   (data/command)
+GPIO 32      ───────▶   BL   (backlight)
+                        CS a GND (no se usa)
+
+ESP32                    TTP223 (×3)
+─────────                ───────────
+GPIO 26 ──▶ SIG TTP223 #1  Siguiente tarea
+GPIO 27 ──▶ SIG TTP223 #2  Marcar como hecha
+GPIO 14 ──▶ SIG TTP223 #3  Snooze 5 min
+3V3     ──▶ VCC de los 3
+GND     ──▶ GND de los 3
+
+ESP32                    Módulo vibrador (con MOSFET)
+─────────                ──────────────────────────────
+GPIO 25 ──▶ Gate del MOSFET
+5V (VIN) ──▶ V+ del vibrador
+GND     ──▶ GND del vibrador
+```
+
+Para el motor 1027 (3V, 70-100 mA), un MOSFET AO3400 o 2N7000 + resistencia 100Ω en gate. Si solo tienes NPN (BC547/2N2222), esquema alternativo: motor entre 3V3 y colector, resistencia 1kΩ en base.
+
+## Build
+
+```bash
+# 1. Compilar
+pio run -e esp32dev
+
+# 2. Flashear firmware
+pio run -e esp32dev -t upload --upload-port /dev/ttyUSB0
+
+# 3. Generar y flashear SPIFFS (caritas)
+python3 gen_gifs.py
+mkdir -p data/gifs && cp gifs/*.gif data/gifs/
+mkspiffs -c data -s 0xCF000 -b 4096 -p 256 spiffs.bin
+esptool --port /dev/ttyUSB0 write_flash 0x310000 spiffs.bin
+```
+
+## Configurar backend + token
+
+En `platformio.ini`:
+
+```ini
+[env:mi-server]
+platform = espressif32 @ 6.5.0
+board = esp32dev
+framework = arduino
+board_build.partitions = partitions.csv
+lib_deps =
+    bodmer/TFT_eSPI@^2.5.43
+    bblanchon/ArduinoJson@^7.0.4
+    tzapu/WiFiManager@^2.0.17
+    bitbank2/AnimatedGIF@^1.4.1
+build_flags =
+    -DCORE_DEBUG_LEVEL=3
+    -DUSER_SETUP_LOADED=1
+    -include $PROJECT_DIR/include/User_Setup.h
+    -DWM_DEBUG_LEVEL=3
+    -DBACKEND_URL=\"https://dummybot.example.com\"
+    -DDEVICE_TOKEN=\"1|abc...xyz\"
+build_src_filter = +<main.cpp> -<tests/>
+```
+
+## Caritas
+
+12 GIFs animados de 80x80, generados con `gen_gifs.py`:
+
+- 01_neutral, 02_happy, 03_worried, 04_sad, 05_cry
+- 06_surprised, 07_angry, 08_sleepy, 09_wink, 10_love
+- 11_working, 12_excited
+
+El firmware elige la emoción según:
+
+- Sin tareas → `SLEEPY` / rotando demo
+- Nueva tarea detectada → `EXCITED` + vibración
+- Prioridad `high` → `WORKING`
+- Hecha → `WINK`
+- Snooze → `WORRIED`
+
+## Tests
+
+```bash
+# Test de pantalla (colores + chip ID ST7789)
+pio run -e diag -t upload
+
+# Test de bus SPI (loopback MOSI↔MISO)
+pio run -e spiloop -t upload
+```
+
+## Licencia
+
+MIT