Fist commit

docs/BACKUP.md

@@ -0,0 +1,68 @@
+# Copia de seguridad del ESP32
+
+`scripts/backup_device.py` realiza una copia de solo lectura de las regiones críticas del ESP32. No escribe en la flash y no ejecuta `erase_flash`.
+
+## Copia recomendada
+
+Cerrar el Serial Monitor y ejecutar:
+
+```bash
+cd ~/Desktop/TimbreESPv2
+python3 scripts/backup_device.py --scope data
+```
+
+El script autodetecta el puerto USB y usa 115200 baudios, que es más seguro para cables CH340 y hubs USB.
+
+Para incluir también la imagen completa de 4 MiB:
+
+```bash
+python3 scripts/backup_device.py --scope full
+```
+
+La copia completa puede fallar en algunos cables CH340. Si falla, usar la copia de datos:
+
+```bash
+python3 scripts/backup_device.py --scope data --baud 115200
+```
+
+## Regiones guardadas
+
+| Archivo | Offset | Tamaño |
+|---|---:|---:|
+| `bootloader.bin` | `0x01000` | 32 KiB |
+| `partitions.bin` | `0x08000` | 4 KiB |
+| `nvs.bin` | `0x09000` | 20 KiB |
+| `otadata.bin` | `0x0E000` | 8 KiB |
+| `littlefs.bin` | `0x350000` | 704 KiB |
+
+En el modo `full` también se guardan `app0.bin`, `app1.bin` y `flash-full.bin`.
+
+## Archivos generados
+
+Cada copia incluye:
+
+- `manifest.json`: fecha, puerto, baudios, tamaños y hashes SHA-256;
+- `partitions.csv`: tabla de particiones decodificada;
+- `device-info.txt`: identificación del chip y flash;
+- `README.txt`: advertencia de restauración;
+- `logs/`: salida de `esptool`.
+
+El directorio predeterminado es:
+
+```text
+~/Documents/TimbreESPv2-backups/backup-YYYYMMDD-HHMMSS/
+```
+
+Los archivos se crean con permisos privados porque `nvs.bin` puede contener credenciales WiFi y autenticación.
+
+## Restauración
+
+No hay restauración automática. Antes de escribir cualquier imagen:
+
+1. Comparar `partitions.csv` con la tabla esperada.
+2. Verificar el tamaño de flash del ESP32.
+3. Confirmar offsets y tamaños.
+4. Guardar otra copia antes de modificar la flash.
+5. No utilizar un directorio marcado con `INCOMPLETE.txt`.
+
+La copia raw de LittleFS contiene el sistema de archivos completo; no son archivos individuales extraídos. Para consultar o migrar su contenido hay que montarlo en un entorno compatible o implementar una extracción posterior.