OPC DA Integration Guide

Connect MaestroHub to OPC DA servers through a Windows agent for tag browsing, reading, writing, and real-time subscriptions. The agent runs on a Windows machine with access to OPC DA servers and exposes a WebSocket interface for MaestroHub communication.

Overview

The OPC DA connector provides:

• WebSocket-based communication with a Windows agent that bridges to OPC DA servers via COM/DCOM
• Server discovery to list available OPC DA servers on the agent machine
• Interactive tag browsing to explore the OPC DA address space hierarchy
• Read/write operations with OPC quality codes and timestamps
• Real-time subscriptions with configurable update rates and deadband filtering
• Server health monitoring via on-demand status queries

Prerequisites

The MaestroHub OPC DA Windows Agent must be installed and running on a Windows machine that has access to the target OPC DA server(s). The agent provides the WebSocket endpoint and handles all COM/DCOM communication with OPC DA servers.

Connection Configuration

Creating an OPC DA Connection

Navigate to Connections -> New Connection -> OPC DA and configure the following fields.

1. Profile Information

Field	Type	Required	Default	Description
Connection Name	Text	Yes	-	A unique, descriptive name for this connection (1-100 characters)
Description	Text	No	-	Optional description for this OPC DA connection

2. Agent Configuration

Field	Type	Required	Default	Validation	Description
Host	Text	Yes	localhost	Non-empty string	Hostname or IP address of the Windows machine running the OPC DA agent
Port	Number	No	45281	1 - 65535	WebSocket port of the OPC DA agent
ProgID	Text	Yes	-	Non-empty string	OPC DA server ProgID to connect to (e.g. Matrikon.OPC.Simulation.1)

Agent URL Format

The full WebSocket URL is automatically constructed: ws://{host}:{port} Example: ws://192.168.1.100:45281

3. Authentication

Field	Type	Required	Default	Description
API Token	Password	Yes	-	API token for authenticating with the Windows agent (stored securely, encrypted at rest)

4. Connection Behavior

Field	Type	Required	Default	Description
Auto Connect	Boolean	No	true	Automatically connect to the OPC server (using the configured ProgID) when the connection starts

5. Timeout Configuration

Field	Type	Required	Default	Validation	Description
Connect Timeout (seconds)	Number	No	30	5 - 120	Maximum time to wait when establishing the WebSocket connection to the agent
Reconnect Interval (seconds)	Number	No	5	1 - 60	Time to wait before attempting to reconnect after connection loss
Ping Interval (seconds)	Number	No	30	10 - 300	Interval for sending keep-alive pings to the agent
Request Timeout (seconds)	Number	No	30	1 - 120	Maximum time to wait for individual operation responses (browse, read, write, etc.)

6. Limits

Field	Type	Required	Default	Validation	Description
Browse Limit	Number	No	5000	100 - 50,000	Maximum number of nodes returned per browse operation
Max Subscriptions	Number	No	10000	1 - 50,000	Maximum number of subscribed tags across all subscription functions
Max Subscription Groups	Number	No	100	1 - 500	Maximum number of subscription groups (each subscribe function creates one group)

7. Subscription Defaults

Field	Type	Required	Default	Validation	Description
Default Update Rate (ms)	Number	No	1000	100 - 60,000	Default update rate in milliseconds for subscriptions. The OPC server may negotiate a different actual rate.
Default Deadband (%)	Number	No	0.0	0.0 - 100.0	Default deadband percentage for subscriptions. Only value changes exceeding this percentage are reported.

8. Connection Labels

Field	Type	Required	Default	Description
Labels	Key-Value Pairs	No	-	Key-value pairs to categorize and organize this connection (max 10 labels)

Notes

• Windows Agent Required: The MaestroHub OPC DA agent must be installed and running on a Windows machine before creating this connection.
• Default Port: The standard agent port is 45281.
• ProgID: This is the COM identifier for the OPC DA server. Use the Discover function to list available servers and their ProgIDs on the agent machine.
• Auto Connect: When enabled, the agent automatically connects to the OPC DA server (identified by ProgID) as soon as the WebSocket connection is established. When disabled, the WebSocket connects but OPC operations will fail until a server connection is established.
• Deadband: A deadband of 0.0 means every value change is reported. A deadband of 5.0 means only changes greater than 5% of the value range are reported, reducing network traffic for noisy analog signals.
• Secret Fields: apiToken is encrypted at rest and masked in API responses.

Function Builder

Available Function Types

Once the connection is saved, the following function types are available:

Function Type ID	Name	Testable	Category	Description
opcda.discover	Discover OPC Servers	Yes	Discovery	Lists available OPC DA servers on the agent machine
opcda.browse	Browse Tag Hierarchy	Yes	Discovery	Browses the OPC DA address space
opcda.read	Read Tag Values	Yes	Read	Reads current values from OPC DA tags
opcda.write	Write Tag Values	Yes	Write	Writes values to OPC DA tags
opcda.subscribe	Subscribe to Tag Changes	No	Subscription	Subscribes to real-time tag value changes
opcda.status	Get Server Status	Yes	Monitoring	Gets OPC server health and status information

---

Browse Tag Hierarchy

Function Type ID: opcda.browse Testable: Yes

Browses the OPC DA address space to discover available tags. Navigate through the hierarchy from root to leaf nodes. Requires an active OPC server connection.

Configuration Fields

Field	Type	Required	Default	Description
Path	Text	No	"" (empty)	Item ID to browse. Leave empty to browse from root. Example: Simulation.Random
Limit	Number	No	Connection's browseLimit	Maximum number of nodes to return. Capped at the connection's configured browse limit.

Response Structure

Field	Type	Description
path	String	The browsed path
nodes	Array	List of child nodes
nodes[].name	String	Node display name
nodes[].itemId	String	Full OPC Item ID (used for read/write/subscribe operations)
nodes[].type	String	Node type: leaf (readable tag) or branch (folder/container)
nodes[].accessRights	String	Access permissions: read, write, or readWrite
nodes[].hasChildren	Boolean	Whether the node has child nodes
truncated	Boolean	true if results were truncated due to the limit

---

Read Tag Values

Function Type ID: opcda.read Testable: Yes

Reads current values from one or more OPC DA tags. Each tag value includes OPC quality information and a timestamp. Requires an active OPC server connection.

Configuration Fields

Field	Type	Required	Default	Description
Tags	Array of Strings	Yes	-	Array of tag Item IDs to read (minimum 1 tag). Example: ["Simulation.Random.Int1", "Simulation.Random.Real4"]
From Device	Boolean	No	false	When true, reads directly from the device. When false, reads from the OPC server's cache (faster).

Response Structure

Field	Type	Description
values	Array	List of tag values
values[].path	String	Tag Item ID
values[].value	Any	Current tag value (type depends on the tag's data type)
values[].quality	String	OPC quality code string
values[].timestamp	String	ISO 8601 timestamp of last value change

OPC Quality Codes

Quality	Description
Good	Value is valid and reliable
Bad	Value is invalid or unreliable
Bad_CommFailure	Communication failure with the device
Bad_DeviceFailure	Device has failed
Bad_SensorFailure	Sensor has failed
Bad_OutOfService	Tag is out of service
Bad_ConfigurationError	Tag configuration error
Uncertain	Value may be questionable
Uncertain_LastUsableValue	Last known good value, device currently unreachable
Uncertain_SensorNotAccurate	Sensor reading may be inaccurate

tip

Individual tag errors are reflected in the quality field rather than failing the entire request. Always check the quality field for each value to ensure data reliability.

---

Write Tag Values

Function Type ID: opcda.write Testable: Yes

Writes values to one or more OPC DA tags. Supports partial success -- individual tag write failures are reported per-item without failing the entire operation. Requires an active OPC server connection.

Configuration Fields

Field	Type	Required	Description
Data	Array of Objects	Yes	Array of write items (minimum 1 item)
Data[].path	Text	Yes	Tag Item ID to write to. Example: Simulation.Random.Int1
Data[].value	Any	Yes	Value to write. Type should match the tag's data type.

Response Structure

Field	Type	Description
results	Array	Per-item write results
results[].path	String	Tag Item ID
results[].success	Boolean	Whether the write succeeded
results[].error	String	Error message if the write failed (empty on success)
successCount	Number	Number of successful writes
failureCount	Number	Number of failed writes

tip

Check accessRights from the Browse function to confirm a tag is writable before attempting writes. Tags with read access rights will fail on write.

---

Subscribe to Tag Changes

Function Type ID: opcda.subscribe Testable: No (event-driven)

Subscribes to real-time value changes for one or more tags. When subscribed tag values change, events are automatically pushed to connected pipelines. Each subscription function creates one OPC DA subscription group. Requires an active OPC server connection.

Configuration Fields

Field	Type	Required	Default	Validation	Description
Tags	Array of Strings	Yes	-	Non-empty array	Array of tag Item IDs to subscribe to. Example: ["Simulation.Random.Int1"]
Update Rate (ms)	Number	No	Connection's defaultUpdateRateMs	100 - 60,000	Requested update rate in milliseconds. The OPC server may negotiate a different actual rate.
Deadband (%)	Number	No	Connection's defaultDeadbandPercent	0.0 - 100.0	Deadband percentage. Only value changes exceeding this percentage are reported.

Event Payload Structure (DATA_CHANGE)

When tag values change, events are pushed with the following structure:

Field	Type	Description
payload	Array	Array of changed tag values
payload[].path	String	Tag Item ID
payload[].value	Any	New tag value
payload[].quality	String	OPC quality code string
payload[].timestamp	String	ISO 8601 timestamp

Event Metadata

Key	Description
protocol	Always opcda
group	OPC DA subscription group identifier
tagCount	Number of changed tags in this event
eventType	Always DATA_CHANGE

Important Notes

• Subscribe functions are event-driven and cannot be tested directly.
• Events fire automatically when any subscribed tag value changes.
• The connection must be active for subscriptions to work.
• Subscriptions are automatically restored after connection loss and reconnection.
• Each subscription function creates one OPC DA subscription group on the server.

---

Error Codes

The OPC DA connector classifies errors into specific categories for easier troubleshooting:

Error Code	Description	Troubleshooting
OPCDA_AUTH_ERROR	Authentication failed	Verify the API token is correct and the agent accepts it
OPCDA_NOT_CONNECTED	Not connected to OPC server	Check that the ProgID is correct and the OPC server is running
OPCDA_SERVER_ERROR	OPC server not found	Verify the ProgID, use the Discover function to list available servers
OPCDA_TAG_ERROR	Tag not found	Verify the tag Item ID, use the Browse function to discover valid tags
OPCDA_WRITE_ERROR	Write operation failed	Check tag access rights and value data type compatibility
OPCDA_LIMIT_ERROR	Subscription or group limit reached	Reduce subscriptions or increase limits in connection configuration
OPCDA_TIMEOUT_ERROR	Operation timed out	Increase request timeout or check network connectivity
OPCDA_COM_ERROR	COM/DCOM error on the agent	Check Windows DCOM configuration and OPC server health
OPCDA_CONNECTION_ERROR	Cannot reach the agent	Verify agent host/port and network connectivity
OPCDA_ERROR	General error	Check the error message for details

Scaling

The OPC DA connector operates in Exclusive mode with a single replica. This is because:

• The WebSocket connection maintains stateful sessions
• The OPC DA server connection is tied to a specific WebSocket session
• Subscription state must remain consistent within a single connection

This is managed automatically by MaestroHub and requires no user configuration.