superguardado: README + AGENTS + lecciones aprendidas vigilancia (26 lecciones)

docs/lecciones_aprendidas_vigilancia.md

@@ -0,0 +1,73 @@
+# Lecciones Aprendidas — Sistema de Vigilancia
+
+## Fecha: 02 agosto 2026
+
+### Hardware
+
+1. **Raspberry Pi 3 NO soporta USB gadget** — eso es solo Pi Zero/Zero 2/CM4. La Pi 3 necesita red (WiFi/Ethernet) para acceso remoto.
+
+2. **Undervoltage en Pi 3**: LED rojo parpadeante = cargador insuficiente. Necesita **5V/2.5A** dedicado. Un cargador de móvil débil puede causar inestabilidad, reinicios y fallos en WiFi/USB.
+
+3. **numpy 2.5 no compila en ARM (Pi 3)**: Las extensiones C fallan en armhf. Solución: usar `math` puro de Python para generar audio, o instalar numpy desde apt (`python3-numpy` si está disponible).
+
+4. **OpenCV-python no compila en ARM**: pip instala opencv-python-headless pero numpy roto impide su uso. Solución: usar **ffmpeg** (apt install ffmpeg) para capturar frames y procesar multimedia sin dependencias Python pesadas.
+
+### Red y WiFi
+
+5. **DHCP por WiFi puede fallar en Pi 3**: Aunque el router da DHCP en eth0, wlan0 puede quedarse en link-local (169.254.x.x). Solución: **IP fija por nmcli** (`nmcli connection modify <uuid> ipv4.method manual ipv4.addresses 192.168.50.251/24`).
+
+6. **netplan SÍ se aplica en Raspberry Pi OS Trixie**: Las configuraciones de `/etc/netplan/*.yaml` son generadas por cloud-init y NetworkManager. La config `network-config` del boot partition se aplica.
+
+7. **PEP 668 en Raspberry Pi OS**: pip install requiere `--break-system-packages` o usar un venv.
+
+### SSH y Acceso Remoto
+
+8. **ProxyJump SSH**: Desde el portátil, `ssh minipc` conecta vía VPS (`ProxyJump vps`) → Pi. Config en `~/.ssh/config`. El VPS usa la llave `C:\Users\juanm\Documents\GitHub\contabo`.
+
+9. **Autossh tunnel inverso**: `autossh -M 0 -N -R 2222:localhost:22 -R 8600:localhost:8600 root@VPS`. Necesita `ServerAliveInterval 30` y `ExitOnForwardFailure yes`.
+
+10. **Clave SSH de la Pi en el VPS**: La línea completa `ssh-ed25519 <base64>` debe estar en `/root/.ssh/authorized_keys`. Si solo se pone el base64 sin el prefijo, la autenticación falla.
+
+### Telegram Bot
+
+11. **Canal IDD vs bot privado**: Si hay múltiples bots usando el mismo token, compiten por `getUpdates`. Solución: **bot dedicado** para la Pi (`@juanjer_casa_bot`).
+
+12. **Canal de Telegram vs bot**: Los mensajes en canales llegan como `channel_post`, no `message`. El bot debe manejar ambos: `upd.get("message") or upd.get("channel_post")`.
+
+13. **systemd y stdout de threads**: El stdout de threads daemon no siempre aparece en `journalctl`. Para debugging: logear a un archivo (`bot.log`).
+
+### TV y AndroidTVRemote
+
+14. **ADB no funciona en TCL Smart TV Pro**: No muestra el aviso de autorización por red (wireless debugging). Se revocaron autorizaciones, se toggled USB debugging, se intentó con claves del portátil — nada. Limitación del modelo.
+
+15. **AndroidTVRemote2 funciona**: Protocolo oficial de Google (emparejamiento por PIN TLS en puerto 6467). La API es: `remote.is_on` (propiedad), `remote.send_key_command("POWER")` (síncrono, NO async). El certificado se guarda en `tv_cert/` y es persistente (no caduca con reinicios).
+
+16. **POWER es toggle**: No es unidireccional. Si la TV está encendida se apaga, si está apagada se enciende. Para controlarlo: verificar `is_on` antes de enviar POWER.
+
+### Sirena y Audio
+
+17. **numpy roto en ARM → sirena con math**: El pitido de emergencia (wail) se sintetiza con `math.sin` en bucle, sin numpy. Funciona bien.
+
+18. **pychromecast con netplan**: Las conexiones de netplan usan `netplan-wlan0-*`. El DHCP puede fallar en wlan0. Solución: IP fija o usar eth0.
+
+19. **ffmpeg funciona en ARM** (paquete apt): Versión 7.1.5 compilada para armhf. Funciona para capturar frames RTSP y procesar multimedia.
+
+### Despliegue
+
+20. **systemd en Pi**: La forma fiable de escribir la unidad es via SFTP + `sudo cp` (el `tee` con `sudo -S` consume el stdin y la unidad no se escribe).
+
+21. **PEP 668**: `pip3 install --user --break-system-packages` necesario en Raspberry Pi OS para instalar paquetes Python.
+
+22. **cloud-init**: El `user-data` y `network-config` se procesan en el primer arranque. Si el primer arranque ya pasó, hay que re-grabar la SD para que se apliquen los cambios.
+
+23. **userconf.txt**: Método fiable para crear el usuario `pi` en el primer arranque. Se escribe en la partición boot: `pi:<hash_sha512>`. Funciona incluso si cloud-init falla.
+
+### Cámaras
+
+24. **Panorámica con ffmpeg**: Sin OpenCV en la Pi, se usan `ffmpeg -i <rtsp_url> -frames:v 1 snapshot.jpg` para capturar frames de las cámaras Tapo.
+
+### Monitoreo
+
+25. **Bot de Telegram en la Pi**: Responde a `estado`, `temperatura`, `tv`, `alarma`, `youtube`, `panorama`. Usa `requests` para getUpdates (long polling) y `sendMessage`/`sendPhoto` para responder.
+
+26. **Alerta de temperatura**: Monitor en background (cada 5 min) que envía alerta si supera el umbral (80°C default).