Skip to content

Creating Types

This guide walks through building a device type from scratch, using a centrifugal pump as the example.

manifest.yaml

The manifest is the core of every device type. It declares metadata, tags, states, calculations, and AI context.

id: consystence.pump.centrifugal
version: 1.2.0
name: Centrifugal Pump
description: Variable speed centrifugal pump with bearing monitoring
icon: pump
category: pumps

tags:
  - name: Running
    dataType: bool
    access: read
    description: Pump is running

  - name: Faulted
    dataType: bool
    access: read
    description: Drive fault active

  - name: Speed
    dataType: real
    access: read
    unit: RPM
    range: { min: 0, max: 3000 }
    description: Current motor speed

  - name: SpeedSetpoint
    dataType: real
    access: readwrite
    unit: RPM
    range: { min: 0, max: 3000 }
    default: 1500
    description: Speed setpoint

  - name: Current
    dataType: real
    access: read
    unit: A
    range: { min: 0, max: 200 }
    description: Motor current draw

  - name: BearingTempDE
    dataType: real
    access: read
    unit: °C
    range: { min: 0, max: 150 }
    description: Drive-end bearing temperature

  - name: BearingTempNDE
    dataType: real
    access: read
    unit: °C
    range: { min: 0, max: 150 }
    description: Non-drive-end bearing temperature

  - name: RunHours
    dataType: dint
    access: read
    unit: hours
    description: Cumulative run hours

  - name: StartCount
    dataType: dint
    access: read
    description: Cumulative start count

  - name: CmdStart
    dataType: bool
    access: write
    description: Start command

  - name: CmdStop
    dataType: bool
    access: write
    description: Stop command

  - name: CmdReset
    dataType: bool
    access: write
    description: Reset fault command

states:
  - name: Stopped
    condition: "!{tags.Running} && !{tags.Faulted}"
    color: slate

  - name: Running
    condition: "{tags.Running} && !{tags.Faulted}"
    color: emerald

  - name: Faulted
    condition: "{tags.Faulted}"
    color: red

calculations:
  - name: PowerEstimate
    expression: "{tags.Current} * 415 * 1.732 * 0.85 / 1000"
    unit: kW
    description: Estimated power consumption (3-phase, 415V, PF 0.85)

ai:
  description: >
    Centrifugal pump driven by a variable speed drive. Used for water
    transfer, dewatering, and process circulation in mining operations.
  typicalQueries:
    - "Why is this pump running hot?"
    - "What is the bearing temperature trend over the last week?"
    - "How many starts has this pump had this month?"
  troubleshooting:
    - symptom: "High bearing temperature"
      causes: ["Low lubrication", "Misalignment", "Overload"]
    - symptom: "High current at low speed"
      causes: ["Impeller blockage", "Mechanical seizure", "VSD fault"]
    - symptom: "Frequent faults"
      causes: ["Power supply issues", "Overload protection too sensitive"]

Component faceplate

The faceplate is the operator control screen for a single device instance. It is defined in components/faceplate.yaml using the GUI DSL.

type: Card
props:
  title: "{instance.name}"
  subtitle: "{instance.location}"
  statusColor: "{state.color}"
children:
  - type: Grid
    props:
      columns: 2
    children:
      - type: MetricCard
        props:
          label: Speed
          value: "{tags.Speed}"
          unit: RPM
          setpoint: "{tags.SpeedSetpoint}"

      - type: MetricCard
        props:
          label: Current
          value: "{tags.Current}"
          unit: A

      - type: MetricCard
        props:
          label: Bearing DE
          value: "{tags.BearingTempDE}"
          unit: °C

      - type: MetricCard
        props:
          label: Bearing NDE
          value: "{tags.BearingTempNDE}"
          unit: °C

  - type: Grid
    props:
      columns: 3
    children:
      - type: Button
        props:
          label: Start
          command: start
          variant: success
          disabled: "{tags.Running}"

      - type: Button
        props:
          label: Stop
          command: stop
          variant: danger
          disabled: "!{tags.Running}"

      - type: Button
        props:
          label: Reset
          command: reset
          variant: warning
          disabled: "!{tags.Faulted}"

  - type: TrendChart
    props:
      tags:
        - "{tags.Speed}"
        - "{tags.Current}"
        - "{tags.BearingTempDE}"
      timeRange: 1h

Binding syntax

Faceplate templates use binding expressions to reference live data:

Prefix Source Example
{tags.X} Tag value from the device instance {tags.Speed}
{state.X} Computed state property {state.color}
{config.X} Type configuration constant {config.maxSpeed}
{instance.X} Instance metadata {instance.name}, {instance.location}

Bindings are resolved at render time by the PageSessionGrain. When a bound tag value changes, only the affected components are re-rendered and pushed to the browser.

Next steps

  • Tag Schema — deep dive into data types, access levels, and tag mappings
  • Alarms & Commands — add alarm rules and operator commands