Instances & Commissioning

A device type is a reusable template — a signal surface, state machine, alarms, commands and UI declared once and published in a library. It carries no site-specific wiring. A device instance is what you get when you stamp that type into a real plant: a named asset at a site, whose canonical tags are mapped to actual controller tag paths.

This page covers stamping an instance, mapping its tags, the commissioning workflow designed to guard the model’s integrity, and how AI assists the workflow without ever commissioning on its own.

Note

Types are reusable (consystence.pump.centrifugal); instances are per-site (AssetNumber PP-01). The same type is stamped into many sites; each stamp is an independent instance with its own tag mappings and configuration. See the type system for the type side of this split.

From type to instance

Stamping a type into a site creates a DeviceInstance — the canonical process-model object. It carries the device’s stable identity and place in the plant, and is deliberately thin:

• a stable instance id (dev_… with a Crockford-base32 suffix, e.g. dev_7H2K9P4M), generated by Consystence when the instance is created, so operators never type it — the create call returns it, whether the instance is added on the web, through the API or with the CLI
• a display name
• a reference to its device type and version
• the controller its tags are acquired from (ctl_…) — required by the web form and the CLI, validated against the site’s controller model
• the AssetNumber — the operator-facing tag for the physical asset (e.g. PP-01)
• location (site code, optional area)
• relationships in the process graph (powered-by, feeds, isolates, monitors)

A device can also be placed in the site’s equipment hierarchy. A placed device takes its area from its place, and the web console’s plant-model navigator shows the hierarchy, read-only; each device’s faceplate and engineering page show where it sits.

The instance id is stable across an asset swap: replace the physical pump and the DeviceInstance — its identity, history and place in the process model — survives. (Asset-specific metadata such as vendor, model and serial is designed to separate into a DeviceInstanceProfile sibling; that separation is planned, so for now asset metadata travels on the instance configuration.)

Add an instance on the web: open the site’s Devices list and choose Add device. You can also create one through the API. The csy CLI does the same; CLI access is arranged through a beta engagement:

csy instance create \
  --site dam-pump-station \
  --name "Dam Transfer Pump 1" \
  --type consystence.pump.centrifugal \
  --type-version 1.0.0 \
  --asset-number PP-01 \
  --controller ctl_7Q4W9K2M \
  --area "Transfer" \
  --tag Running=Program:DamTransfer.Pump1.Running \
  --tag Speed=Program:DamTransfer.Pump1.Speed \
  --tag SpeedSetpoint=Program:DamTransfer.Pump1.SpeedSP

The controller (--controller, or the form’s Controller field) is required: every device is assigned to a controller (ctl_…) declared in the site’s controller model — see the engineering model — and that assignment determines how the device’s tags are acquired and where reads and writes execute.

csy instance list --site dam-pump-station
csy instance get  --site dam-pump-station dev_7H2K9P4M

Creating instances is an admin operation on the site surface (/api/sites/{siteId}/instances), so it requires the admin or owner org role — see roles and the API reference. On a site server, the Add device page also admits a user signed in by site PIN whose site role is owner, admin, site admin or engineer.

Note

Creating an instance is licence-consuming expansion, so it is gated by graceful degradation: when licence enforcement is active and the server’s licence is past grace, the create call returns 409 Conflict — “Licence lapsed: adding new device instances is blocked until it is renewed. Existing devices and plant control are unaffected.”

Tag mappings

A type declares canonical tag names (Running, Speed, SpeedSetpoint) with their dataType (Bool/Int/DInt/Real/String), access (Read/Write/ReadWrite), physicalRole (Input/Output/Internal/System) and engineering metadata. An instance’s tagMappings bind each canonical name to a real path in the controller’s address space:

tagMappings:                                       # canonical name → controller path
  Running:       "Program:DamTransfer.Pump1.Running"
  Speed:         "Program:DamTransfer.Pump1.Speed"
  FlowRate:      "Program:DamTransfer.FT001.PV"
  SpeedSetpoint: "Program:DamTransfer.Pump1.SpeedSP"

The mapping is the only place the vendor-specific address surfaces — everything above it (alarms, commands, UI, AI context) speaks the canonical names. A read of dev_7H2K9P4M/Speed returns the instance’s current value for Speed, with its quality and timestamp. That value is kept current from Program:DamTransfer.Pump1.Speed on the controller, which is read through an edge (see controller communication). The data type, access and physicalRole come from the type, not the mapping — see tags for what each carries.

The commissioning lifecycle

Consystence defines a lifecycle for instances, from declaration through to running control.

Every mapped path should resolve to a data point in the authoritative tag register the controller exposes (built from its modules and a full tag browse — see the engineering model). Confirming the signal surface against the register — rather than against a proposal — is what keeps the model tractable for alarms, P&ID bindings, AI context and the historian. The target lifecycle:

flowchart LR
  D["Declared<br/>DeviceInstance exists<br/>no tag mappings yet"] --> C["Configured<br/>type stamped<br/>tag mappings declared"]
  C --> V{"Mappings resolve to<br/>controller data points?"}
  V -- "no — fix mapping" --> C
  V -- "yes — deploy & start control" --> O["Operational<br/>alarms · historian · AI live"]

• Declared — the engineer has surveyed the site and added the device to the process model. The DeviceInstance exists and is visible, but has no confirmed control wiring. Not operational, not simulatable.
• Configured — the type is stamped and tagMappings are declared. The device’s control behaviour is described (modelled as a DeviceControlInstance), but it is not yet running.
• Operational — control is deployed to its target topology and started; real or simulated inputs now produce live state. Confirming the mappings against the register is the engineering discipline that precedes this step.

Commissioning is done device by device, mirroring physical commissioning: the engineer reviews each device’s mappings, corrects exceptions, and confirms.

Mapping validation is not yet enforced

The lifecycle above is not enforced. Today an instance is live the moment it is created: the create call activates it immediately — alarms, state evaluation and historian wiring start straight away. No commissioning status is stored, and there is no “mark commissioned” operation. The engineering pages show each device’s level (Declared, Configured or Operational), derived from the model and live reporting rather than recorded: a device is Configured once it has a known controller and at least one tag mapping, and Operational once it reports with Good input quality and an evaluated state (simulated inputs count, and the page says so). On a site server, the commissioning checkout lets an engineer record, point by point, what the controller delivered against what the model expects. The server stamps each record with the value, quality and time it read, refuses a pass on simulated or non-Good values, and never writes to an output. The records are kept in the operational journal as evidence, not a gate: nothing waits for them. Tag mappings are accepted as-is at creation (the device type and, when supplied, the controller assignment are validated; the mappings themselves are not): a mapping that points at a data point the controller does not expose is not rejected — it surfaces later as a runtime read/write failure. Verify mappings against the controller’s tag register yourself before relying on alarms, historian attribution, AI context or P&ID bindings built on them.

AI-assisted generation and commissioning

On first connect to a controller, the platform is designed to use AI to accelerate the engineering work that precedes commissioning. The designed pipeline:

1. Connect controller — read identity, firmware and the backplane slot map.
2. Enumerate modules — read each module’s identity, channel count and channel types; propose module profiles. High confidence, because hardware identity is deterministic.
3. Build the tag register — full tag browse, so every tag has physical context (which module and channel it originates from).
4. Propose device types and instances — read the program structure (AOI/UDT usage) and configuration values, and propose a signal surface, state machine, config and candidate tagMappings. Each proposed mapping is confidence-scored, and uncertain mappings are flagged.
5. Commission — the engineer reviews proposals per device, bulk-approves the high-confidence mappings, corrects the flagged exceptions, confirms the tag mappings against the register, and marks the device commissioned.

Advisory only

The AI proposes; a human commissions. The AI is advisory across the platform — here it is designed to suggest mappings, classify tags and explain program structure, but it never confirms a mapping, never marks a device operational, and never commands equipment. Hard interlocks live in the IO modules and safety relays. The commissioning confirmation is always a human action. The Consystence state-machine shadow that the AI reports on is a read-only mirror of live tag values, not a controller.

Caution

Most of this pipeline is design rather than shipped capability. Today the assistant reads what the platform already holds (the site’s registered controllers, their cached data points and the device types) and can propose a live tag browse, which an engineer runs from the controller’s page. It does not register controllers or change tag bindings. It can propose a command, and an operator confirms each one before anything executes. It never deploys control code. The device-type and mapping proposal step, its confidence scoring and the bulk-approval review do not exist yet, and the dedicated asset-profile object is planned. Creating device instances remains a human action, on the web (Add device), through the API or with the CLI; treat the auto-generation flow as roadmap.

Where to next

• Type system — the reusable template you stamp from.
• Tags — data types, access and physicalRole that an instance’s mappings bind to.
• Engineering model — controller → module → channel → tag register that mappings resolve against.
• Alarms & commands — the alarm and command surfaces an instance carries.
• Simulation — running a device’s behaviour against the same instance before, or instead of, real IO.