Visión general

AlertIA conecta dispositivos de campo (ESP32 con TPDeviceLib, agentes Windows/Linux u otros firmwares compatibles) con la nube (API + broker MQTT) y con herramientas de alta (app móvil de campo, launcher de fábrica).

Este portal documenta el contrato público de integración para fabricantes y equipos que implementan un agente propio. No cubre el uso del dashboard de producto ni la API OAuth de consumo de datos (ver API pública).

Actores

Actor	Rol
Dispositivo / agente	Lee sensores, publica telemetría, ejecuta triggers, hace register/ping
Core API	Alta (/devices/register), ping, asignación por serial (launcher)
Broker MQTT	Telemetría, triggers, status, config, OTA
App de campo	Provisión local por BLE (credenciales de red + alta)
Fabricante	Flashea launcher/firmware, asigna preset, define params/triggers

Ciclo de vida (resumen)

flowchart TD
  factory[Fábrica: launcher o firmware] --> orphan[ORPHAN / serial]
  orphan --> assign[Asignación preset]
  assign --> field[Campo: provisión BLE]
  field --> register[POST /devices/register]
  register --> mqtt[MQTT telemetría y triggers]
  mqtt --> ops[Ping / OTA / operación]

1. Fábrica (opcional): launcher pide serial, el panel asigna preset y el equipo descarga firmware de producto por OTA.
2. Campo: la app móvil empareja por BLE, envía WiFi/Ethernet + identidad de cliente, y el firmware registra en la API sin reiniciar.
3. Operación: el dispositivo usa las credenciales y topics MQTT que devolvió el register; mantiene presencia con ping HTTPS y LWT MQTT.

Qué es canónico hoy

Tema	Estado
Provisión local	Solo BLE (servicio GATT AlertIA). Ver Provisión BLE.
AP WiFi + HTTP /provision	Deprecado (histórico). Ver changelog.
Topics MQTT	Los entrega el register / ping; no hardcodear entornos de lab.
Telemetría	data puede ser objeto o array; el backend normaliza ambos.

Seguridad

• No publiques en firmwares ni docs passwords de brokers de laboratorio.
• El user_secret de provisión es el JWT del técnico: trátalo como secreto de sesión.
• deviceSecret y mqtt_pass del register son secretos de dispositivo: guárdalos en NVS/secure store, nunca en repos públicos.