MQTT

Los dispositivos AlertIA hablan MQTT v3.1.1 (no v5) con el broker de la plataforma.

Conexión

Parámetro	Origen
URI	mqtt_uri del register
Usuario	mqtt_user (= DID del dispositivo)
Password	mqtt_pass (secreto generado en el alta)
Topics de telemetría / trigger	mqtt_telemetry_topic, mqtt_trigger_topic

No hardcodees topics de laboratorio (telemetry/alertia-dev, etc.) en firmwares de producción. Si el entorno cambia, el register (y el ping) entregan los valores vigentes.

Mapa de topics

Topic	Dirección	QoS	Retain	Uso
telemetry/{env}	Device → broker	0	no	Telemetría
triggers/{env}	Device → broker	1	no	ACK / estado de trigger
status/{deviceId}	Device → broker	1	sí	Online / LWT offline
broker/{deviceId}	Broker → device	1	—	Comandos (trigger)
config/{deviceId}	Broker → device	1	—	config_update
ota/{deviceId}	Broker → device	1	—	ota_available

{env} es el segmento de entorno configurado en la plataforma; {deviceId} es el DID.

Status / LWT

Publicar en status/{deviceId} (retain):

{ "state": "online" }

Configurar LWT con { "state": "offline" } para que el broker marque caída abrupta.

Telemetría

El backend acepta tres formas equivalentes:

1. Objeto único (data objeto)

{
  "v": 1,
  "did": "<deviceId>",
  "ts": 1704067200,
  "data": { "slug": "temp_amb", "value": 23.7 }
}

2. Array de mensajes del formato 1.

3. Batch (data array) — típico de TPDeviceLib:

{
  "v": 1,
  "did": "<deviceId>",
  "ts": 1704067200,
  "data": [
    { "slug": "temp_amb", "value": 23.7 },
    { "slug": "hum_rel", "value": 48 }
  ]
}

Divergencia documentada: algunos ejemplos históricos muestran solo data objeto; el firmware de referencia publica data como array. Ambos son válidos.

Más ejemplos: Telemetría.

Triggers

Entrada (subscribe broker/{deviceId}):

{
  "type": "trigger",
  "slug": "abrir_valvula",
  "id": "<uuid-ejecución>",
  "params": { "duracion_s": 5 }
}

Salida / ACK (publish triggers/{env}):

{
  "type": "trigger",
  "id": "<uuid-ejecución>",
  "status": "COMPLETED",
  "deviceId": "<deviceId>"
}

Estados canónicos del dispositivo: RUNNING, COMPLETED, FAILED.

El backend también acepta aliases tipo success / OK / SUCCESS al normalizar el ACK, pero preferí COMPLETED / FAILED / RUNNING en implementaciones nuevas.

Más detalle: Triggers y ACK.

Config y OTA (resumen)

• config/{deviceId}: mensajes con type: config_update (aplicar y persistir según tu agente).
• ota/{deviceId}: type: ota_available — el flujo completo de descarga depende del canal (HTTPS por serial / producto). Esta página no sustituye la guía OTA de fábrica.

Buenas prácticas

• QoS y retain según la tabla; no marques retain en telemetría.
• Reconectá con backoff; tras reconnect republicá online en status.
• Tras register, usá exactamente los topics de la respuesta (el ping puede re-sincronizarlos).