Conexión por MQTT

MQTT es el protocolo de carga para flotas que mantienen una conexión persistente y necesitan tanto telemetry hacia arriba como comandos hacia abajo sobre la misma sesión. CORE-M sirve MQTT a través de EMQX; el adaptador device-link se suscribe al broker, normaliza cada mensaje en un TelemetryPoint y lo publica en el bus interno — exactamente igual que cualquier otro protocolo.

Nota

Esta página asume un dispositivo provisionado (provisioning) con una API key (o PSK). Si aún no has provisionado, ver identidad y credenciales.

Broker y puertos

Broker	EMQX
MQTT simple	1883
MQTT sobre TLS	8883

Usa 8883 en producción. El puerto simple 1883 existe solo para desarrollo local y despliegues en redes de confianza — sobre 1883 la API key viaja en texto claro.

Credenciales de CONNECT

La autenticación ocurre en el paquete CONNECT de MQTT. El dispositivo se identifica con su device_id y se autentica con su API key (o PSK):

Campo de CONNECT	Valor
Client ID	el device_id del dispositivo
Username	el device_id del dispositivo
Password	la API key del dispositivo (sk_live_...) o PSK

Como el client ID es la identidad del dispositivo, el broker rechaza una segunda conexión que intente usar el mismo client ID, y el adaptador atribuye cada mensaje de esa sesión a ese dispositivo. La identidad proviene de la sesión autenticada — nunca de nada dentro del payload.

Convenciones de topics

Dirección	Topic	Propósito
Dispositivo → plataforma	devices/{device_id}/telemetry	Publicar lecturas de telemetry.
Plataforma → dispositivo	devices/{device_id}/commands	Suscribirse para recibir comandos de downlink.

Sustituye {device_id} por el UUID propio del dispositivo. Un dispositivo solo debería publicar en su propio topic de telemetry y suscribirse solo a su propio topic de comandos.

Payload

Publica un objeto JSON de pares métrica → valor. El adaptador lo normaliza en un TelemetryPoint, mapeando los campos numéricos a numeric_values y los campos de string a string_values:

{
  "temperature": 22.5,
  "humidity": 65,
  "state": "running"
}

El device_id y el tenant_id se toman de la sesión autenticada, y el timestamp se sella a la llegada a menos que el decodificador de tu payload extraiga uno. Ver envío de telemetry para el modelo TelemetryPoint completo.

Un ejemplo completo

Usando el cliente estándar mosquitto_pub sobre TLS:

1. Conéctate y publica una lectura en el topic de telemetry del dispositivo.

   mosquitto_pub \
     --cafile /etc/ssl/certs/ca-bundle.crt \
     -h mqtt.kronoxdata.com -p 8883 \
     -i d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33 \
     -u d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33 \
     -P 'sk_live_8f3c2a...' \
     -t 'devices/d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33/telemetry' \
     -m '{"temperature":22.5,"humidity":65,"state":"running"}'

2. Para recibir comandos, suscríbete al topic de comandos con las mismas credenciales (normalmente se mantiene abierto durante toda la vida del dispositivo):

   mosquitto_sub \
     --cafile /etc/ssl/certs/ca-bundle.crt \
     -h mqtt.kronoxdata.com -p 8883 \
     -i d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33 \
     -u d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33 \
     -P 'sk_live_8f3c2a...' \
     -t 'devices/d7b1c0e2-3f44-4a91-9b2e-2c5a1f0e9d33/commands'

Consejo

Mantén la misma sesión MQTT tanto para publish como para subscribe. Una sola conexión persistente lleva la telemetry hacia arriba en el topic .../telemetry y los comandos hacia abajo en el topic .../commands, que es la razón principal para elegir MQTT en lugar de HTTP.

Cómo un publish de MQTT llega al bus

sequenceDiagram
    participant Dev as Dispositivo
    participant EMQX as EMQX broker :8883
    participant DL as adaptador MQTT device-link
    participant RP as Redpanda telemetry.raw.{tenant}

    Dev->>EMQX: CONNECT (clientid=device_id, user=device_id, pass=api_key)
    EMQX-->>Dev: CONNACK
    Dev->>EMQX: PUBLISH devices/{device_id}/telemetry {json}
    EMQX->>DL: Entregar mensaje
    DL->>DL: Resolver identidad desde la sesión, decodificar payload
    DL->>RP: Publicar TelemetryPoint normalizado
    Note over Dev,EMQX: Los comandos vuelven vía<br/>devices/{device_id}/commands

Comportamiento online / offline

El primer mensaje de telemetry pone el dispositivo en online. CORE-M rastrea la actividad a partir de la llegada de telemetry, no solo de la conexión TCP: si no llega telemetry durante más tiempo que el umbral de inactividad (120 segundos por defecto), el dispositivo se marca como offline aunque la sesión MQTT siga técnicamente abierta. Los dispositivos que reportan con poca frecuencia deberían publicar una lectura de heartbeat o tener su umbral ajustado en consecuencia.

Cuándo elegir MQTT

Recurre a MQTT cuando…

• El dispositivo permanece conectado y quieres publicación frecuente y de baja sobrecarga.
• Necesitas comandos fiables servidor→dispositivo sobre la misma sesión.
• Operas una flota donde la difusión y la gestión de sesiones de un broker ayudan.
• Quieres garantías de QoS y un ecosistema de clientes probado en batalla.

Para envíos puntuales o impulsados por el backend, HTTP es más sencillo. Para hardware limitado de clase UDP, ver CoAP.

Relacionado

Envío de telemetry El modelo TelemetryPoint y el ciclo de vida de la ingesta.

Conexión por CoAP Dispositivos limitados sobre UDP con DTLS y payloads CBOR.