Alarms & Commands¶

Alarms detect abnormal conditions and notify operators. Commands allow operators to interact with equipment through the platform.

Alarm definitions¶

Alarms are defined in alarms/alarms.yaml within the device type directory:

alarms:
  - id: bearing_temp_high
    name: Bearing Temp High
    condition: "{tags.BearingTempDE} > 75 || {tags.BearingTempNDE} > 75"
    priority: warning
    category: mechanical
    delay: 5s
    message: "Bearing temperature exceeds 75°C"

  - id: bearing_temp_hh
    name: Bearing Temp High-High
    condition: "{tags.BearingTempDE} > 90 || {tags.BearingTempNDE} > 90"
    priority: critical
    category: mechanical
    delay: 2s
    message: "Bearing temperature exceeds 90°C — shutdown imminent"

  - id: overcurrent
    name: Overcurrent
    condition: "{tags.Current} > 180"
    priority: critical
    category: electrical
    delay: 1s
    message: "Motor current exceeds 180A"

  - id: drive_fault
    name: Drive Fault
    condition: "{tags.Faulted}"
    priority: critical
    category: electrical
    delay: 0s
    message: "Variable speed drive fault active"

  - id: high_vibration
    name: High Vibration
    condition: "{tags.VibrationDE} > 7.5 || {tags.VibrationNDE} > 7.5"
    priority: warning
    category: mechanical
    delay: 10s
    message: "Vibration exceeds 7.5 mm/s RMS"

  - id: low_speed
    name: Low Speed Warning
    condition: "{tags.Running} && {tags.Speed} < {tags.SpeedSetpoint} * 0.9"
    priority: warning
    category: process
    delay: 30s
    message: "Pump running below 90% of speed setpoint"

Alarm fields¶

Field	Required	Description
`id`	Yes	Unique identifier within the type
`name`	Yes	Human-readable alarm name
`condition`	Yes	Binding expression that evaluates to `true` when the alarm is active
`priority`	Yes	`info`, `warning`, `critical`
`category`	No	Grouping for filtering: `mechanical`, `electrical`, `process`, `safety`
`delay`	No	Time the condition must be continuously true before the alarm activates (debounce). Default `0s`
`message`	No	Operator-facing description

Alarm lifecycle¶

stateDiagram-v2
    [*] --> Normal
    Normal --> Active: Condition true for delay period
    Active --> Acknowledged: Operator acknowledges
    Active --> Normal: Condition clears
    Acknowledged --> Normal: Condition clears
    Normal --> [*]

All alarm transitions — activation, acknowledgement, shelving, clearing — are recorded in the event log with timestamp and user identity.

Command definitions¶

Commands are defined in commands/commands.yaml:

commands:
  - id: start
    name: Start Pump
    tags:
      - tag: CmdStart
        value: true
        pulse: 500ms
    preconditions:
      - "!{tags.Running}"
      - "!{tags.Faulted}"
    confirm:
      title: Start Pump
      message: "Start {instance.name}?"
    audit: true

  - id: stop
    name: Stop Pump
    tags:
      - tag: CmdStop
        value: true
        pulse: 500ms
    preconditions:
      - "{tags.Running}"
    confirm:
      title: Stop Pump
      message: "Stop {instance.name}? The pump will decelerate to zero."
    audit: true

  - id: reset
    name: Reset Fault
    tags:
      - tag: CmdReset
        value: true
        pulse: 500ms
    preconditions:
      - "{tags.Faulted}"
    confirm:
      title: Reset Fault
      message: "Reset fault on {instance.name}?"
    audit: true

  - id: set_speed
    name: Set Speed
    tags:
      - tag: SpeedSetpoint
        value: "{input.speed}"
    preconditions:
      - "{input.speed} >= 0"
      - "{input.speed} <= 3000"
    confirm:
      title: Change Speed Setpoint
      message: "Set {instance.name} speed to {input.speed} RPM?"
    audit: true

Command fields¶

Field	Required	Description
`id`	Yes	Unique identifier within the type
`name`	Yes	Human-readable command name
`tags`	Yes	Array of tag writes to execute
`tags[].tag`	Yes	Tag name to write
`tags[].value`	Yes	Value to write (literal or binding)
`tags[].pulse`	No	Auto-reset the tag after this duration (for momentary commands)
`preconditions`	No	Array of binding expressions that must all be true to enable the command
`confirm`	No	Confirmation dialog shown before executing
`audit`	No	Whether to log execution in the command audit trail. Default `true`

Pulse commands¶

Most PLC commands are pulse commands — the tag is set to true for a short duration, then automatically reset to false. This matches how PLC programs typically consume commands: they latch the rising edge and the HMI resets the bit.

The pulse field specifies how long the value is held before resetting. A typical value is 500ms.

Audit logging¶

Every command execution is recorded by the CommandAuditGrain with:

Timestamp
User identity (from JWT)
Device instance and command ID
Tag values written
Precondition evaluation result
Success or failure outcome

This provides the audit trail required for regulatory compliance in mining operations.