Device profiles

A device profile is a reusable bundle of defaults and policies that devices inherit the moment they are created. Instead of configuring every device by hand, you define a profile once — “Temperature Sensor v2” — and attach it during manual registration, key claim, or bulk import. Every device that references it starts out consistent.

Profiles are tenant-scoped. Mutating them requires the profiles permission (tenant admin). They are managed via DeviceRegistryService at /api/v1/device-profiles.

What a profile carries

A profile defines the following defaults and policies:

Field	What it sets
default_tags	Tags applied to every device using the profile (e.g. region=eu)
default_config	Desired-state config delivered to the device on connect
telemetry_schema	Required telemetry keys and types used to validate incoming points
protocol_config	Transport defaults (e.g. rate limits, transport-specific settings)
anchoring_policy	Default blockchain anchoring mode — Merkle batch, per-event, or hash chain
credentials_policy	Which credential type new devices receive — API key, PSK, or X.509 cert
offline_threshold_seconds	Seconds without telemetry before the device is marked offline (platform default 120)
ota_policy	Default OTA rollout behavior for devices using the profile

Note

The offline_threshold_seconds controls when a device is demoted to offline by the status checker. The platform default is 120 seconds (DEVICE_OFFLINE_THRESHOLD_SECONDS); set it on the profile to tune for chatty or sleepy devices.

Telemetry schema validation

The telemetry_schema is the most operationally important field: it is what stops malformed data from polluting your telemetry. The schema declares which keys a telemetry point must contain and their types.

When a device sends a point that is missing a required numeric key, the platform rejects that point with INVALID_ARGUMENT and increments corem_telemetry_schema_rejections_total{profile="…"}. The rest of the device’s valid points are unaffected — validation is per point.

Caution

Schema rejections fail the point, not the device. A sensor that drops its temperature key will have those specific readings rejected while still being counted as online. Watch corem_telemetry_schema_rejections_total — a rising count usually means firmware is sending the wrong key names or units, not that the device is down.

Inheritance and override order

A device’s effective settings are resolved by layering three sources, lowest to highest priority:

flowchart LR
  A["Tenant default"] --> B["Profile defaults"] --> C["Explicit device fields"]
  C --> R[["Effective device settings"]]

1. Tenant default — the baseline policy the platform applies when nothing else is set.
2. Profile — the profile’s defaults override the tenant default for any field the profile specifies.
3. Explicit device fields — values set directly on the device (in the registration payload or a later update) override the profile, where overriding is allowed.

So if the tenant default anchoring mode is Merkle batch, a profile sets it to per-event, and a specific device is registered with anchor_mode hash chain, that device anchors via hash chain — the most specific value wins.

Tip

Put everything stable on the profile and reserve explicit device fields for genuine exceptions. A device that overrides half its profile is a sign the profile is too broad — split it into two profiles instead.

Example profile

A profile for refrigerated-storage temperature sensors:

{
  "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 }
}

A device created with profile_id: "p_temp_sensor_v2" then starts life tagged region=eu/class=cold-store, reporting every 60s, validated against the temperature + battery schema, anchored in Merkle batches, authenticating with an API key, marked offline after 180s of silence, and eligible for the profile’s OTA rollout policy — all without per-device configuration.

Related

Manual registration Attach a profile with profile_id when registering a device.

Provisioning by key claim A provisioning template references a profile so claimed devices inherit it.

Anchoring modes The Merkle-batch, per-event, and hash-chain modes a profile's anchoring policy selects.

First-device walkthrough See a profile in action end-to-end while sending your first telemetry.