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 at commission time so operators never type it — the create call returns it, whether initiated from the CLI or the API
• a display name
• a reference to its device type and version
• the controller its tags are acquired from (ctl_…) — required by 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)

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.)

Hand-register an instance with the CLI (csy):

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

--controller 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.

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 resolves through the mapping to Program:DamTransfer.Pump1.Speed, fetches the value over the edge PLC path, and returns it stamped with the unit and data type from the type definition. 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 Declared → Configured → Operational lifecycle above is the target model, not current behaviour. 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 — and there is no commissioned status, no “mark commissioned” operation and no commissioning audit event yet. 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 suggests mappings, classifies tags and explains 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. The AI tools available today span read-only discovery — controller identity, tag browse, device-type inspection — plus admin-gated configuration actions such as registering a controller; commands are propose-only (an operator confirms every execution) and control-code deployment requires out-of-band operator confirmation. The device-type and mapping proposal step, its confidence scoring and the bulk-approval review do not exist yet, and the object decomposition is landing incrementally: the native control topology is shipping, while the gateway and legacy-PLC topologies and the dedicated asset-profile object follow on customer pull. Creating device instances remains a human action through the CLI or API — the concrete, available path today; 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.