Device profiles

Un device profile es un paquete reutilizable de valores por defecto y políticas que los dispositivos heredan en el momento en que se crean. En lugar de configurar cada dispositivo a mano, defines un profile una vez —“Temperature Sensor v2”— y lo adjuntas durante el registro manual, la reclamación de clave o la importación masiva. Cada dispositivo que lo referencia arranca de forma consistente.

Los profiles tienen alcance de tenant. Mutarlos requiere el permiso profiles (admin del tenant). Se gestionan vía DeviceRegistryService en /api/v1/device-profiles.

Qué aporta un profile

Un profile define los siguientes valores por defecto y políticas:

Campo	Qué establece
default_tags	Tags aplicados a cada dispositivo que use el profile (p. ej. region=eu)
default_config	Configuración de estado deseado entregada al dispositivo al conectar
telemetry_schema	Claves y tipos de telemetry requeridos usados para validar los puntos entrantes
protocol_config	Valores por defecto del transporte (p. ej. límites de tasa, ajustes específicos del transporte)
anchoring_policy	Modo de anchoring en blockchain por defecto — Merkle batch, por evento o cadena de hash
credentials_policy	Qué tipo de credencial reciben los dispositivos nuevos — API key, PSK o certificado X.509
offline_threshold_seconds	Segundos sin telemetry antes de marcar el dispositivo como offline (valor por defecto de la plataforma 120)
ota_policy	Comportamiento de rollout OTA por defecto para los dispositivos que usen el profile

Nota

El offline_threshold_seconds controla cuándo un dispositivo se degrada a offline por el verificador de estado. El valor por defecto de la plataforma es 120 segundos (DEVICE_OFFLINE_THRESHOLD_SECONDS); establécelo en el profile para ajustarlo a dispositivos parlanchines o dormilones.

Validación del esquema de telemetry

El telemetry_schema es el campo más importante operativamente: es lo que impide que datos malformados contaminen tu telemetry. El esquema declara qué claves debe contener un punto de telemetry y sus tipos.

Cuando un dispositivo envía un punto al que le falta una clave numérica requerida, la plataforma rechaza ese punto con INVALID_ARGUMENT e incrementa corem_telemetry_schema_rejections_total{profile="…"}. El resto de los puntos válidos del dispositivo no se ven afectados — la validación es por punto.

Precaución

Los rechazos de esquema fallan el punto, no el dispositivo. Un sensor que omita su clave temperature tendrá esas lecturas concretas rechazadas mientras sigue contando como online. Vigila corem_telemetry_schema_rejections_total — un conteo creciente suele significar que el firmware está enviando nombres de clave o unidades equivocados, no que el dispositivo esté caído.

Orden de herencia y sobrescritura

Los ajustes efectivos de un dispositivo se resuelven superponiendo tres fuentes, de menor a mayor prioridad:

flowchart LR
  A["Valor por defecto del tenant"] --> B["Valores por defecto del profile"] --> C["Campos explícitos del dispositivo"]
  C --> R[["Ajustes efectivos del dispositivo"]]

1. Valor por defecto del tenant — la política base que la plataforma aplica cuando no hay nada más establecido.
2. Profile — los valores por defecto del profile sobrescriben el valor por defecto del tenant para cualquier campo que el profile especifique.
3. Campos explícitos del dispositivo — los valores establecidos directamente en el dispositivo (en el payload de registro o una actualización posterior) sobrescriben el profile, donde la sobrescritura esté permitida.

Así que si el modo de anchoring por defecto del tenant es Merkle batch, un profile lo establece a por evento, y un dispositivo concreto se registra con anchor_mode cadena de hash, ese dispositivo ancla vía cadena de hash — gana el valor más específico.

Consejo

Pon todo lo estable en el profile y reserva los campos explícitos del dispositivo para genuinas excepciones. Un dispositivo que sobrescribe la mitad de su profile es señal de que el profile es demasiado amplio — divídelo en dos profiles en su lugar.

Profile de ejemplo

Un profile para sensores de temperatura de almacenamiento refrigerado:

{
  "profile_id": "p_temp_sensor_v2",
  "name": "Temperature Sensor v2",
  "type": "temp-sensor",
  "description": "Cold-store temperature probes, EU region",
  "default_tags": { "region": "eu", "class": "cold-store" },
  "default_config": { "report_interval_s": 60 },
  "telemetry_schema": {
    "required": {
      "temperature": "number",
      "battery": "number"
    }
  },
  "protocol_config": { "rate_limit_per_minute": 120 },
  "anchoring_policy": { "mode": "ANCHOR_MODE_MERKLE_BATCH" },
  "credentials_policy": { "type": "api_key" },
  "offline_threshold_seconds": 180,
  "ota_policy": { "canary_percent": 5, "failure_threshold_percent": 10 }
}

Un dispositivo creado con profile_id: "p_temp_sensor_v2" arranca entonces su vida etiquetado region=eu/class=cold-store, reportando cada 60s, validado contra el esquema temperature + battery, anclado en Merkle batches, autenticando con una API key, marcado como offline tras 180s de silencio y elegible para la política de rollout OTA del profile — todo sin configuración por dispositivo.

Relacionado

Registro manual Adjunta un profile con profile_id al registrar un dispositivo.

Provisioning por reclamación de clave Una plantilla de provisioning referencia un profile para que los dispositivos reclamados lo hereden.

Modos de anchoring Los modos Merkle-batch, por evento y cadena de hash que selecciona la política de anchoring de un profile.

Tutorial del primer dispositivo Ve un profile en acción de principio a fin mientras envías tu primera telemetry.