Device Types

Overview

Devices of the same model share the same capabilities. Instead of describing them on every device, you describe them once in a device type and link each device to it with deviceTypeId. When you read a device, its device type is returned in the deviceType field.

A device type is used to:

• give each measured property a label, a unit of measurement and a data type, used for example in Excel exports
• declare which aggregated series the platform computes for each property
• document the commands and events of the device
• link the device model to its firmware

Key Properties

• name (required): Name of the device type, e.g. “ACME Energy Meter 500”
• manufacturer, model, category, description: Descriptive information. category is a broad class such as energy-meter or inverter, and can be used to filter devices
• visibility: project (default) or public. See Visibility
• properties: The properties measured by the device. See Properties
• commands: The commands accepted by the device. See Commands
• events: The events emitted by the device, as a map of event name to description
• firmwareId: The firmware of this device model
• firmwareVersions: The firmware versions supported by this device model
• metadata: Flexible key-value storage for custom attributes

Properties

properties maps each property name, as it appears in the measurements, to its definition:

{
  "name": "ACME Energy Meter 500",
  "manufacturer": "ACME",
  "category": "energy-meter",
  "properties": {
    "activePower": {
      "displayName": "Active power",
      "description": "Active power absorbed by the load",
      "uom": "kW",
      "type": "number",
      "aggregations": ["avg:quarter", "avg:hourly"]
    },
    "activeEnergy": {
      "displayName": "Active energy",
      "uom": "kWh",
      "type": "number",
      "aggregations": ["delta:quarter", "delta:hourly", "delta:daily"]
    }
  }
}

Commands

commands maps each command name to its description and parameters. Each parameter has a type (string, number, boolean or object) and can be marked as required:

{
  "commands": {
    "setPowerLimit": {
      "description": "Limits the power absorbed by the load",
      "parameters": {
        "limit": { "type": "number", "required": true },
        "duration": { "type": "number" }
      }
    },
    "reboot": {
      "description": "Restarts the device"
    }
  }
}

This catalog documents the commands for the applications that send them; the platform does not validate the commands you send against it.

Visibility

A device type with visibility: project can only be used by the devices of its project. A public device type can be referenced by devices of any project: this is how device types shared across projects, for example for widely used hardware, are made available.