TwinCAT Trigger Node

Overview

The TwinCAT Trigger Node automatically initiates MaestroHub pipelines when an ADS device notification arrives from a Beckhoff TwinCAT PLC. Unlike the TwinCAT Read nodes, which read a value inside an already-running pipeline, the TwinCAT Trigger starts a new pipeline execution on each push from the PLC — enabling fully event-driven automation without polling.

The PLC pushes a new sample whenever the monitored symbol changes (on-change) or on a fixed cycle (cyclic), and each push carries a server timestamp.

---

Core Functionality

What It Does

1. Event-Driven Pipeline Execution Start pipelines automatically whenever the PLC pushes a new sample for the monitored symbol. Latency is bounded by the PLC's change-check cycle, not by any polling interval.

2. Two Notification Modes The underlying Device Notification function subscribes in either on-change mode (push only when the value changes) or cyclic mode (push every cycle time). The mode, cycle time, and batching delay are configured on the function — see Device Notification.

3. Automatic Subscription Lifecycle The subscription is created when the pipeline becomes enabled and torn down when it's disabled. The connector re-subscribes automatically after reconnects — no manual subscription management required.

4. PLC-Enforced Change Detection There is no connector-side deduplication. ADS notifications carry a server timestamp, and on-change is enforced by the PLC, so every delivered sample is a real change. This mirrors the OPC UA subscription model.

---

How TwinCAT Triggering Works

TwinCAT triggering is fundamentally different from on-demand reads:

Aspect	Read Symbol / Block	Device Notification (Trigger)
Model	Request-response (pull)	Event-driven (push)
Execution	One-time read per call	Continuous streaming on each PLC push
Lifecycle	Stateless	Stateful ADS device-notification subscription
Use Case	On-demand data access	Real-time change detection, telemetry

When you configure a TwinCAT Trigger:

1. MaestroHub registers an ADS device notification on the symbol named by the Device Notification function, using its mode (on-change / cyclic) and cycle time.
2. The PLC pushes a sample whenever the value changes (on-change) or every cycle (cyclic).
3. Each sample is decoded according to the symbol's data type and one trigger event is emitted.
4. The pipeline executes with the sample available as $trigger.

Baseline value on subscribe

When a subscription registers, the PLC's first (baseline) push can arrive before the connector has finished recording the subscription. The connector buffers and replays that baseline sample rather than dropping it, so the first pipeline execution sees the initial value.

---

Reconnection Handling

MaestroHub automatically handles transport disruptions to ensure reliable monitoring.

Automatic Recovery

When the TwinCAT connection is lost and restored:

1. Connection Lost: The system detects the disconnection (transport error or failed health probe) and tears the session down.
2. Connection Restored: A fresh ADS session is opened. Because notification handles are per-session, the connector re-registers all active subscriptions on the new session.
3. Transparent Recovery: Pipelines continue to receive samples once the connection is restored — no manual intervention required.

What This Means for Your Workflows

Scenario	Behavior
Transient network error	Automatic resubscription after reconnection
PLC program download	The symbol table is re-uploaded and handles are re-resolved on the next session
PLC restart / power-cycle	Subscriptions are re-registered once the runtime is reachable again
MaestroHub restart	All triggers for enabled pipelines are restored on startup

Minimising data loss

Samples the PLC pushes while the connector is disconnected are lost — ADS has no replay buffer the client can rewind. For critical signals, complement the trigger with a periodic Read node driven by a Schedule trigger so a polled value lands even if a push is missed.

---

Configuration Options

Basic Information

Field	Type	Description
Node Label	String (Required)	Display name for the node on the pipeline canvas. Must be non-empty (trimmed).
Description	String (Optional)	Explains what this trigger initiates.

---

Configuration

The trigger configuration is organized across three tabs in the UI: Configuration, Test Data, and Basic.

Parameter	Type	Default	Required	Description
Connection	Connection ID	""	Yes	The TwinCAT connection profile to subscribe through. Filtered to TwinCAT connections only.
Device Notification Function	Function ID	""	Yes	The function that defines the subscription (symbol, mode, cycle time). Filtered to twincat.notify function types on the selected connection.
Enabled	Boolean	true	No	When disabled, the subscription is not created even if the pipeline is enabled.

Function Requirement

The selected function must be a Device Notification function type (twincat.notify). Read Symbol, Read Block, Read Struct, Write Symbol, and Write Struct functions cannot be used with TwinCAT Trigger nodes.

If the selected connection has no Device Notification functions yet, the node configuration panel surfaces a link straight to the connection's Functions tab so you can author one.

Device Notification Function Configuration

The selected function (authored in the Connect module) controls what gets monitored and how often:

Setting	Description
Symbol / Tag	The PLC symbol path to monitor (or a tag-map alias).
Mode	onChange (push only when the value changes) or cyclic (push every cycle time).
Cycle Time (ms)	The sampling cycle for cyclic mode, and the server's change-check interval for on-change. 0 = server default.
Max Delay (ms)	Maximum time the server batches samples before pushing. 0 = no batching (push immediately).
Data Type	Optional override for decoding each sample; blank uses the symbol table type.

See Device Notification for the full function reference.

Test Data

The Test Data tab holds a Sample Payload editor and a Sample Quality picker. When you run the node with Test Node in Sandbox mode, the trigger emits the sample payload as result instead of waiting for a real notification, so you can validate downstream nodes before a PLC is wired up. When the editor is empty, a built-in sample is used. Sample Quality sets the quality the sample reports in $trigger._metadata.quality (good, uncertain or bad). The live subscription and the node's Fire Trigger action do not use the sample.

{
  "value": 23.5,
  "symbol": "MAIN.fTemperature"
}

---

Settings

Description

A free-text area for documenting the node's purpose and behavior. Notes entered here are saved with the pipeline and visible to all team members.

Execution Settings

Setting	Options	Default	Description
On Error	Pipeline Default / Stop Pipeline / Continue Execution	Pipeline Default	Behavior when the node fails.

---

Output Data Structure

When an ADS device notification arrives and triggers pipeline execution, the trigger produces a structured output with two top-level keys: _metadata and result. One event is emitted per delivered sample.

Output Format

{
  "_metadata": {
    "type": "twincat_trigger",
    "protocol": "twincat",
    "connectionId": "bf29be94-fc0a-4dc4-8e5c-092f1b74eb4b",
    "functionId": "aef374c3-aa2b-454e-aabc-5657faac5950",
    "symbol": "MAIN.fTemperature",
    "dataType": "LREAL",
    "timestamp": "2026-05-20T10:30:45.123456789Z"
  },
  "result": {
    "symbol": "MAIN.fTemperature",
    "value": 23.5,
    "dataType": "LREAL",
    "timestamp": "2026-05-20T10:30:45.123456789Z"
  }
}

result Fields

Field	Type	Description
symbol	string	The monitored PLC symbol path.
value	any	The decoded sample value — BOOL → boolean, integer types → number, REAL/LREAL → number, STRING/WSTRING → string.
dataType	string	The data type used to decode the sample.
timestamp	string	ISO 8601 / RFC 3339 (nanoseconds) — the PLC server timestamp for this sample, UTC.

_metadata Fields

Field	Type	Description
type	string	Always "twincat_trigger".
protocol	string	Always "twincat".
connectionId	string	The TwinCAT connection profile ID.
functionId	string	The Device Notification function ID.
symbol	string	The monitored symbol path.
dataType	string	The data type used to decode the sample.
timestamp	string	ISO 8601 / RFC 3339 (nanoseconds) — the sample's server timestamp, UTC.
quality	string	good for every decoded sample. bad on a failure event: once per outage, when a sample cannot be decoded or the ADS connection is lost, the trigger fires with the last decoded payload, quality: "bad" and the cause under error. The next decoded sample is good again. A UNS Publish node downstream inherits the verdict.
quality_reason	string	Only on a failure event: comm_error. A UNS Publish node downstream forwards it, so the stored sample reads bad · comm_error rather than just bad.
error	string	Only on a failure event: the decode error or ADS connection lost.

Referencing in Downstream Nodes

Use expressions to access trigger data in subsequent nodes:

• $trigger.result.value — the decoded value of the monitored symbol
• $trigger.result.symbol — the symbol path
• $trigger.result.dataType — the data type used to decode
• $trigger.result.timestamp — the PLC server timestamp for the sample
• $trigger._metadata.connectionId — connection profile used
• $trigger._metadata.functionId — Device Notification function used

---

Validation Rules

Parameter Validation

Node Label

• Must not be empty
• Must not consist only of whitespace
• Error: "Node name is required"

Connection ID

• Must be provided and non-empty
• Must reference a valid TwinCAT connection profile
• Error: "TwinCAT connection is required"

Function ID

• Must be provided and non-empty
• Must reference a valid Device Notification function
• Function must belong to the specified connection
• Error: "Device notification function is required"

Enabled Flag

• Must be a boolean if provided
• Error: "Enabled must be a boolean value"

---

Usage Examples

Real-Time Temperature Monitoring

Key configuration

• Label: Furnace Temperature Monitor
• Connection: TC3 Line 1 PLC
• Function: Device Notification on MAIN.fTemperature, mode cyclic, cycle time 500 ms
• Enabled: true
• Settings: on error stop

Downstream usage: $trigger.result.value for the temperature reading, $trigger.result.timestamp for the sample time. Forward into the Aggregator node to compute a sliding-window average before publishing to MQTT.

Alarm / Flag Monitoring

Key configuration

• Label: E-Stop Monitor
• Connection: TC3 Line 1 PLC
• Function: Device Notification on GVL.bEStop, mode onChange
• Enabled: true
• Settings: on error continue

Downstream usage: $trigger.result.value for the current state. With onChange, the pipeline only fires on actual transitions — perfect for kicking off an alert on each edge without churning on the steady state.

Production Counter Tracking

Key configuration

• Label: Part Count Tracker
• Connection: TC3 Packaging PLC
• Function: Device Notification on MAIN.nPartCount, mode onChange
• Enabled: true

Downstream usage: $trigger.result.value for the counter value; compute production rate from consecutive values using $trigger.result.timestamp.

---

Best Practices

Subscription Design

• Choose onChange for slow-changing signals (door state, mode flag, alarm) so steady-state churn does not waste pipeline executions. Use cyclic when you need a sample on a fixed interval regardless of change.
• Tune the Cycle Time to the fastest rate you actually need. For on-change it is the server's change-check interval; a smaller value detects changes sooner but checks more often.
• Use Max Delay to let the server batch bursts of samples when sub-millisecond latency is not required.

Designing for Reliability

Practice	Rationale
Add a polled Read fallback for critical signals	Samples pushed during a disconnection are lost — a periodic Schedule-driven Read backstops the live trigger
Keep the subscribed symbol count reasonable per connection	Each subscription is a server-side notification on the PLC; many high-rate symbols add load
Buffer downstream with an Aggregator for high-rate signals	A slow consumer can cause samples to be dropped under backpressure (a one-time warning is logged)

Error Handling Strategies

For Critical Workflows:

• Set On Error to stopPipeline
• Monitor pipeline execution failures via the Health dashboard
• Implement alerting for stopped pipelines

For Best-Effort Processing:

• Set On Error to continueExecution
• Log failed executions for later analysis
• Ensure downstream nodes handle partial failures gracefully

Performance Considerations

Scenario	Recommendation
High-frequency changes	Use onChange with a sensible Cycle Time, or set a Max Delay to batch samples; buffer downstream so a slow consumer never stalls processing
Many monitored symbols	Spread subscriptions across connections; running multiple TwinCAT connections distributes the load
Dropped-sample warnings	If you see "dropping notification samples" warnings, the downstream consumer can't keep up — raise the Cycle Time, reduce subscribed symbols, or aggregate downstream

Enable vs. Disable

• Use the trigger's Enabled parameter to temporarily pause monitoring without changing pipeline state
• Disable triggers during maintenance windows to prevent processing stale reconnection data
• Document the reason for disabled triggers in the node's Description field