Envío de telemetry

La telemetry es todo el sentido de conectar un dispositivo. Cualquiera que sea el transporte que uses — HTTP, MQTT, CoAP, LwM2M, SNMP— cada lectura se normaliza en una sola forma interna: el TelemetryPoint. Esta página es la referencia definitiva de esa forma, los decodificadores que convierten tu formato de cable en ella, la validación que un punto debe pasar y qué hace CORE-M con un punto una vez aceptado.

El TelemetryPoint

Un TelemetryPoint es una lectura de un dispositivo en un instante. Lleva una identidad, un timestamp y dos mapas de valores con nombre:

message TelemetryPoint {
  string device_id = 1;
  string tenant_id = 2;
  google.protobuf.Timestamp timestamp = 3;
  map<string, double> numeric_values = 4;
  map<string, string> string_values = 5;
}

Campo	Significado
device_id	El identificador de CORE-M para el dispositivo (no el hardware_id).
tenant_id	El tenant propietario. Derivado de tu credencial — nunca lo estableces a algo que tu key no posea.
timestamp	Cuándo se tomó la lectura, RFC 3339 en el cable. Truncado a segundos enteros para anchoring — ver abajo.
numeric_values	Mapa de nombre de métrica → double. Úsalo para cualquier cosa medida: temperature, humidity, rpm, battery_v.
string_values	Mapa de nombre de métrica → string. Úsalo para estados y etiquetas: status, mode, firmware.

Valores numéricos vs de texto

Elige el mapa según qué es el valor, no según cómo se imprime:

• Numérico para mediciones que vas a graficar, umbralar o agregar. 22.5, 1013.2, -40.0. Incluso los enteros van aquí como doubles.
• Texto para estados discretos e identificadores que vas a filtrar o mostrar. "online", "heating", "v2.0.0".

Un solo punto puede mezclar ambos — comparten el mismo timestamp:

{
  "numeric_values": { "temperature": 22.5, "humidity": 65 },
  "string_values":  { "status": "ok", "mode": "auto" }
}

Precaución

No metas un número en string_values para conservar ceros a la izquierda o unidades — pierdes la capacidad de graficarlo y umbralarlo. Pon el número en numeric_values y la unidad en el nombre de tu métrica o en una métrica de texto separada si es imprescindible.

El timestamp son segundos Unix para anchoring

En el cable el timestamp es RFC 3339 (2026-05-29T14:30:00Z). Pero cuando un punto se hashea para anchoring en blockchain, ese timestamp se toma como segundos Unix — los nanosegundos se descartan. El hash canónico es:

SHA256( device_id_utf8 || timestamp_uint64_be(seconds) || jcs_payload_utf8 )

donde jcs_payload_utf8 es el payload canonicalizado según RFC 8785 (JCS).

Esto importa porque un verificador externo puede tener solo precisión de segundos. Al truncar a segundos enteros, CORE-M garantiza que el verificador puede reproducir el mismo hash exacto a partir de la misma lectura lógica. Si envías dos puntos para el mismo dispositivo en el mismo segundo, se hashean contra el mismo timestamp — dales valores distintos o sepáralos al menos un segundo si cada uno debe anclarse de forma independiente. Consulta Anchoring y Merkle proofs para ver cómo ese hash se convierte en una proof on-chain.

Decodificadores de payload

Los dispositivos rara vez hablan protobuf de forma nativa. Los adapters de ingesta de CORE-M decodifican formatos de cable comunes en la forma TelemetryPoint. La vía HTTP canónica (POST /api/v1/telemetry, puerto 8080) toma JSON; los dispositivos MQTT y CoAP pueden usar JSON, CBOR, protobuf binario, CSV o un mapeo de campos personalizado configurado en el device profile.

JSON

El formato por defecto y más simple. Las claves se mapean directamente sobre los campos del TelemetryPoint.

POST /api/v1/telemetry HTTP/1.1
Host: api.kronoxdata.com:8080
Authorization: Bearer sk_live_9Qk3pR2wXn7vJ4mB...
Content-Type: application/json

{
  "points": [
    {
      "device_id": "dev_8f3a",
      "timestamp": "2026-05-29T14:30:00Z",
      "numeric_values": { "temperature": 22.5, "humidity": 65 },
      "string_values":  { "status": "ok" }
    }
  ]
}

CBOR

CBOR es el primo binario y compacto de JSON — el mismo modelo de datos, muchos menos bytes, ideal para dispositivos CoAP/DTLS restringidos. Codifica la estructura idéntica como un mapa CBOR y envíala con Content-Type: application/cbor. El adapter la decodifica en el mismo TelemetryPoint.

Content-Type: application/cbor

A3                                  # map(3)
   69 6465766963655F6964            # "device_id"
   68 6465765F38663361              # "dev_8f3a"
   6E 6E756D657269635F76616C756573  # "numeric_values"
   A2                               # map(2): temperature=22.5, humidity=65
   ...

Un dispositivo CoAP normalmente hace POST de CBOR al recurso de telemetry; la semántica de los campos es byte por byte el modelo JSON de arriba.

protobuf

Los dispositivos que pueden enlazar el cliente generado envían el TelemetryPoint en formato de cable (o un IngestTelemetryRequest de muchos) directamente — sin paso de decodificación, la vía más pequeña y rápida. Envía con Content-Type: application/x-protobuf.

# Using the generated corem.v1 client
from corem.v1 import telemetry_pb2
from google.protobuf.timestamp_pb2 import Timestamp

ts = Timestamp(); ts.FromJsonString("2026-05-29T14:30:00Z")
point = telemetry_pb2.TelemetryPoint(
    device_id="dev_8f3a",
    timestamp=ts,
    numeric_values={"temperature": 22.5, "humidity": 65.0},
    string_values={"status": "ok"},
)
req = telemetry_pb2.IngestTelemetryRequest(points=[point])
body = req.SerializeToString()   # POST body, application/x-protobuf

CSV

Los gateways y los data loggers heredados a menudo emiten filas CSV. Configura el mapeo columna→métrica en el device profile; el adapter parsea cada fila en un punto. Una fila de cabecera nombra las columnas:

device_id,timestamp,temperature,humidity,status
dev_8f3a,2026-05-29T14:30:00Z,22.5,65,ok
dev_8f3a,2026-05-29T14:31:00Z,22.6,64,ok

Las columnas numéricas aterrizan en numeric_values, las columnas de texto en string_values, según el mapeo del profile. Cada fila se convierte en un TelemetryPoint.

mapeo personalizado

Cuando un dispositivo emite una forma fija que no puedes cambiar —un blob JSON de proveedor, una trama binaria empaquetada o OIDs SNMP sondeados de equipo de red— adjunta un mapeo de campos personalizado al device profile. El mapeo declara, por campo de origen, el nombre de métrica de destino y si es numérico o de texto.

{
  "decoder": "custom",
  "mapping": {
    "$.payload.t":      { "metric": "temperature", "type": "numeric" },
    "$.payload.rh":     { "metric": "humidity",    "type": "numeric" },
    "$.payload.st":     { "metric": "status",      "type": "string"  },
    "1.3.6.1.2.1.1.3.0":{ "metric": "uptime_s",    "type": "numeric" }
  }
}

El adapter aplica el mapeo en la ingesta, produciendo el mismo TelemetryPoint canónico sin importar la forma nativa del dispositivo.

Nota

Cada decodificador produce el mismo TelemetryPoint. Nada downstream — validación, almacenamiento, anchoring, paneles— sabe ni le importa en qué formato de cable llegaron los datos. Elige el formato que se ajuste al dispositivo; la plataforma se comporta de forma idéntica.

Validación

Un punto decodificado aún no está aceptado. Primero debe pasar la validación.

1. Autenticación. La credencial debe ser válida y estar autorizada a ingerir para el tenant reclamado. Un punto no autenticado se rechaza y nunca se publica; la métrica telemetry_rejected_total{reason="auth"} se incrementa.

2. Dispositivo conocido. El device_id debe existir en el registro del tenant. Si no, el punto se descarta silenciosamente —no se publica en el subject validado— y telemetry_dropped_total{reason="unknown_device"} se incrementa, con un log de advertencia que lleva contexto de traza. Esta es la causa más común de “mis datos no aparecen”: el dispositivo no fue aprovisionado, o estás enviando el device_id equivocado.

3. Validación de esquema (si el profile define uno). Si el profile del dispositivo lleva un telemetry_schema, el punto se comprueba contra él. Un profile que requiere la clave numérica temperature rechaza un punto que la omita con INVALID_ARGUMENT, y corem_telemetry_schema_rejections_total{profile="…"} se incrementa. Los profiles sin esquema aceptan cualquier punto bien formado.

Precaución

Un dispositivo desconocido se descarta, no se rechaza con un error — la llamada HTTP puede aun así devolver un ack 2xx en el borde mientras el punto se descarta downstream. Si los puntos desaparecen sin un error, comprueba que el dispositivo está aprovisionado y que estás usando su device_id (no su hardware_id).

Qué ocurre tras la aceptación

Una vez que un punto pasa la validación, ocurren muchas cosas — y el dispositivo no espera por ninguna de ellas. El borde confirma de inmediato y el punto se propaga de forma asíncrona:

flowchart TB
  IN["Punto aceptado<br/>telemetry.raw.{tenant}"] --> VAL["validar + enriquecer<br/>(dispositivo conocido, esquema, last_seen)"]
  VAL --> VD["telemetry.validated.{tenant}"]
  VD --> HOT[("Aerospike hot<br/>CDT list · 900s TTL")]
  VD --> COLD[("TimescaleDB cold<br/>archivo histórico")]
  VD --> LIVE["telemetry.live.{tenant}.{device}<br/>fan-out en tiempo real"]
  VD --> ANC["en cola para anchoring<br/>(Merkle batch → on-chain)"]

Concretamente, en la aceptación CORE-M:

• Actualiza last_seen en el registro del dispositivo, y si el dispositivo estaba offline, lo cambia a online y publica un evento de cambio de estado.
• Enriquece el punto con el nombre, los grupos y los tags del dispositivo.
• Hace doble escritura: lo añade a la lista CDT hot de Aerospike (con clave {tenant}:{device}:{metric}, ventana de TTL de ~900 segundos — una caché rápida, no el sistema de registro) y lo inserta en la hypertable cold de TimescaleDB (en lotes para throughput) como el registro histórico duradero.
• Hace fan-out a telemetry.live.{tenant}.{device} para que los paneles y los suscriptores WebSocket lo vean en tiempo real.
• Lo pone en cola para anchoring — su hash se une a un Merkle batch que más tarde se compromete en la blockchain.

Que falle la escritura hot no bloquea la escritura cold; la vía cold siempre procede. Consulta Consulta y retención de telemetry para ver cómo se consultan los stores hot y cold y cuánto tiempo se conservan los datos.

A dónde ir después

Relacionado

• Consulta y retención de telemetry — cómo leer de vuelta tu telemetry almacenada y cuánto tiempo se conserva.
• Anchoring — cómo el hash de un punto aceptado se convierte en un compromiso on-chain.
• Merkle proofs — el hash canónico y cómo se prueba un único punto contra un batch.
• Tutorial del primer dispositivo — envía tu primer punto de principio a fin.