Configuring The OPC UA Collector

Introduction

The Timebase OPC UA Collector connects directly to OPC UA servers to subscribe to live industrial data and log it to the Timebase historian. It supports continuous sampling, event-driven updates, and data change notifications, ensuring that value changes from PLCs, equipment controllers, and SCADA systems are captured reliably and without polling overhead. 

To create and configure your OPC UA logging session, follow these steps:

1. Launch your browser and connect to the Collector. The Collector browser config provides a front end editor for the OPC UA Collector. By default, this is found at either http://localhost:4521 (unsecure) or https://localhost:4522 (secure).
2. Select the Config tab at the top of the browser, just to the right of the Timebase Collector logo.
3. Configure each of the primary sections, Logging Session, Target Historians, and OPC UA Configuration.
4. Save your work between each section using the save button in the right hand corner.

 

 

Configuration Properties

The Logging Session Properties and Target Historian settings are universal to every Collector type in Timebase and define how the session behaves.

 

Logging Session Properties

Type: Ensure you have selected OPC UA. 

Dataset: The dataset name within the Timebase Historian you wish to target from this logging session. Datasets are automatically created for you if they do not exist. It is recommended you maintain a single logging session to dataset relationship.

 

Target Historians

You can create multiple connections to target more than one historian. Each historian targeted will receive it's own data stream providing for redundancy.

Identifier: The label used to identify this historian target within the session; does not affect network routing but helps in diagnostics.

Host: The DNS name or IP address of the target historian that receives data.

Port: The port on which the historian accepts write requests; this must match the historian’s ingest configuration.

Use TLS: Enables encrypted communication between the collector and the historian; recommended for any environment where the collector and historian are not on the same protected network.

Authentication Enabled: Indicates whether the collector should authenticate using the Timebase Pulse Identity Provider before sending data.

IdP Host: The DNS name or IP address of the Pulse Identity Provider (IdP) used to obtain authentication tokens.

IdP Port: The port the IdP exposes for token requests.

IdP Use TLS: Enables TLS for communication with the Identity Provider.

Client ID: The client identity this collector uses when requesting tokens from the IdP.

Client Secret: The credential associated with the Client ID; it allows the collector to authenticate with Pulse.

 

OPC UA Configuration

Connection

Url: The DNS name or IP address of the OPC UA server in the form opc.tcp://host:port.

Session Timeout: (milliseconds) The maximum amount of time that the OPC UA session can remain inactive before the server treats the session as expired and requires a new connection.

Keep Alive Period: (milliseconds)The interval at which the Collector sends keep-alive messages to confirm the session is still valid and responsive, helping detect stalled or broken connections quickly.

Reconnect Period: (milliseconds) The delay before the collector attempts to automatically reconnect after a lost session or failed network communication, ensuring recovery without manual intervention.

Refresh Interval: (seconds) The frequency at which the collector refreshes metadata such as node references, browsing information, and subscription health to maintain accurate visibility into the connected OPC UA server.

 

Authentication

Username: The username that the collector will present to the OPC UA server when establishing the session, used when the server requires user-based authentication rather than anonymous access.

Password: The password associated with the username.

 

SECURITY

Before the collector can connect securely, the client certificate generated by Timebase must be trusted on the OPC UA server, and the server must allow the chosen Security Policy and Security Mode.

Most connection failures in secure OPC UA environments occur because the server administrator has not yet approved the client certificate or because the server is configured to allow only a different combination of policy and mode than what the Collector is using.

Security Policy: Specifies the cryptographic algorithm suite used to secure the OPC UA session, determining how messages are signed and encrypted during communication with the server.

Diving Deeper

Most modern OPC UA deployments use Basic256Sha256 for strong encryption while older systems may only support weaker policies such as Basic128Rsa15, so if you are unsure where to start, choose the strongest policy supported by the server and ensure the server trusts the client certificate before a secure connection will succeed.

Security Mode: Defines the level of protection applied to OPC UA messages, where options include no security, sign only, or sign and encrypt, allowing you to match the server’s required balance between performance and confidentiality.

Diving Deeper

The Security Mode determines how each OPC UA message is protected and typically offers None, Sign, or Sign and Encrypt, where None should only be used in development environments, Sign protects message integrity without encrypting data, and Sign and Encrypt offers full confidentiality for production systems. 

Both the Security Mode and Security Policy must match the server configuration, and the server must be configured to accept encrypted client connections if you select a secure mode here.

The video below featuring Lenny Smit demonstrates these security principals and will be helpful if you are new to securing an OPC server. This highlights the older JSON configuration option (Timebase Collector v1.0), but is still relevant in concept and application for the latest version.

 

 

CERTIFICATE

Application Subject: The unique name assigned to the Timebase OPC UA client certificate, which identifies the Collector to the server during the secure connection handshake and must match the subject entry that the OPC UA server approves when trusting the certificate.

Application Store: The folder path where the Collector stores its own certificate and private key, typically generated automatically on first launch, and this folder must remain accessible so the collector can reuse the same certificate for reconnects rather than creating new certificates each time.

Trusted Issuer Store: The folder path that contains certificate authorities (CAs) that the Collector trusts to sign OPC UA server certificates, and if the OPC UA server uses a CA-signed certificate rather than a self-signed one, the CA must be present here for the Collector to validate the server.

Trusted Peer Store: The folder path that contains individual server certificates that the Collector has explicitly trusted, and if the OPC UA server uses a self-signed certificate, the server’s certificate must be copied into this folder for the secure connection to succeed.

Rejected Store: The folder path where certificates are placed when the Collector receives them from an OPC UA server but does not yet trust them, making this the first place to check when a connection fails due to certificate trust issues because the administrator can promote a rejected certificate into the trusted store.

Accept Untrusted Certificates: Allows the collector to accept and use untrusted server certificates without requiring approval through the trust store, which can simplify development or testing environments but should not be enabled in production because it bypasses certificate validation and eliminates protection against man-in-the-middle attacks.

Troubleshooting Common Issues

If the collector cannot establish a secure OPC UA session, the problem is almost always related to trust configuration between the client (Timebase) and the server. The most common causes are:

1. The OPC UA server has not yet trusted the Timebase client certificate. Check the server’s rejected or pending certificates list and approve the Timebase certificate so it moves to the server’s trusted store.

2. The collector does not trust the OPC UA server’s certificate. If the server uses a self-signed certificate, download or copy the server certificate into the collector’s Trusted Peer Store; if the server uses a CA-signed certificate, ensure the CA certificate is in the Trusted Issuer Store.

3. The Security Policy and Security Mode do not match between client and server. The certificate will appear “invalid” if the server only accepts certain policy/mode combinations; confirm that both sides are configured for the same values.

4. File system access problems on the certificate folders. If the collector cannot read or write its Application Store, Trusted stores, or Rejected store due to file/folder permissions, the client certificate cannot be reused and the connection will fail.

5. A new certificate was generated but the server is still expecting an older one. If the Application Store was deleted or replaced, the collector may present a new certificate the server does not recognize; approve the new certificate on the server or restore the original Application Store.

6. “Accept Untrusted Certificates” was enabled too early or too late. If enabled before the first handshake, some servers will downgrade to insecure mode and block the session; if disabled in a mixed-trust environment, the secure connection may fail until the trust chain is fully configured.

 

SUBSCRIPTIONS

Interval: How often the collector requests fresh data from the OPC UA server for all monitored tags, in milliseconds.

Topics: A list of OPC UA namespace paths that serve as entry points for tag discovery, with one topic per line.

Diving Deeper

In OPC UA, a Topic represents the hierarchical path to an asset, subsystem, or data tree inside the server’s address space. By choosing the right topics, you decide what parts of the plant you intend to historize rather than logging the entire address space. Subscribing to broad topics provides for faster setup but does not require you to historize unnecessary data as adding Filters later in the config will provide for exclusion lists to be built.

Wildcards: Timebase supports two wildcard styles for OPC UA topic browsing, and both are designed to make large namespace subscriptions scalable without forcing you to list every device manually. The * wildcard matches any single node name at that specific level of the OPC UA hierarchy, so it is ideal when the structure is consistent across areas or lines. For example, Area */Line */Fillers collects all Fillers across all lines while still respecting the folder depth. The ** wildcard goes further by matching across any number of hierarchical levels, recursively collecting everything below that point regardless of how deeply nested it is. This is the best choice when equipment structures vary from one asset to another, such as Area */**/Fillers when some Lines have additional telemetry folders and others do not.

Unlike MQTT or Sparkplug, where wildcards operate on topic strings inside a broker, OPC UA wildcards operate on the server’s folder-based address space, allowing the collector to browse and discover tags directly from the server. Wildcards make OPC subscriptions future-proof: they allow new equipment added under the same structure to be discovered automatically, while still letting you target only the meaningful branches of the namespace instead of the entire server.

Topic Examples: The configuration in the below examples uses a mixed strategy, combining wildcard discovery for some equipment and explicit targeting for others:

Topic 1: Area 1/Line 1/Filler *

Focuses only on fillers in Area 1 Line 1, but still auto-discovers new fillers that appear under that branch. Useful when the location is fixed, but equipment may grow or change.

Topic 2: Area */Line */Cappers

Uses the * wildcard to capture every Capper on every line in every area. Ideal when equipment is consistent across the plant and you want to scale without constantly editing the topic list.

Topic 3: Austin Site/**/Boilers

Collects boiler data only from a single site, but across all boiler rooms or utility sub-areas inside that site even if the folder structure has different levels from area to area.

Topic Definition: 

A slash-delimited list of semantic keys that tells the MQTT Collector how to interpret each segment of the MQTT topic so those values can be used as dynamic fields on the generated tags.

How Topic Definition Works

OPC UA address spaces usually encode meaningful structure such as area, line, equipment type, and physical asset name, but the OPC UA Collector cannot know which folder represents which concept unless you define it. Topic Definition allows you to map each level of the OPC UA path to a semantic role by listing the keys in order, and the Collector then extracts those values from every discovered tag to populate metadata fields and assist with tag naming.

Example: With a Topic Definition of area/line/equipment, and an OPC UA node path of Area 1/Line 1/Capper 4/Motor Speed, the collector resolves:

• • area = Area 1
  • line = Line 1
  • equipment = Capper 4

Anything deeper than the defined levels (in this case Motor Speed) is ignored for semantic mapping and can be handled separately using Fields, Filters, or naming options. This approach allows Timebase to derive meaningful context directly from the OPC UA namespace rather than requiring that information to be stored inside every tag.

Filter: A .NET regular expression (regex) used to omit metrics from logging; the collector evaluates the regex against each tag name and excludes any tag that matches the pattern, allowing broad subscriptions while preventing unwanted tags from being written to the historian.

How .NET Regex Filtering Works

The .NET regex engine matches your pattern against the full metric name provided in each Sparkplug message; if the name matches the pattern, the collector does not log that metric, which helps keep the historian focused on meaningful operational data.

Simple Contains Match

To exclude any metric containing the word Debug, simply enter Debug into the filter.

Prefix Based Filtering

To exclude all metrics beginning with a specific device prefix, use: ^Filler02_.* which removes Filler02_Speed, Filler02_Temp, and all other metrics starting with Filler02_.

Excluding Classes of Metrics

If alarm metrics follow a known prefix such as Alarm_, you can exclude them using: ^Alarm_.* which keeps the historian from filling with high-frequency alarm chatter.

Matching Multiple Patterns

To exclude metrics belonging to either of two prefixes, use: ^(Filler02_|Capper01_).* which uses .NET grouping and alternation.

Using Negative Lookahead

To keep all metrics except those containing the word Test, use: ^(?!.*Test).* which is a .NET negative lookahead pattern and excludes any name containing Test while allowing everything else.

For a online tutorial in regex or to learn more, we recommend the website RegExr - https://regexr.com/

Fields: Allows the Collector to extract values from each level of the OPC UA folder path and store them as metadata on every historized tag so the tag always carries context such as area, line, or equipment.

Diving Deeper

In OPC UA, Fields pull extra information from the node path and append it to each tag as metadata, the same way they do for MQTT or Sparkplug. The difference is that instead of pulling values out of a payload or topic string, OPC UA Fields extract values from the folder path of the node.

Fields in OPC UA can be populated in two ways: you can hardcode a value (for example, setting Site = Austin), or you can dynamically extract a value from the OPC UA folder path using Topic Definition. The dynamic method is especially powerful because it allows Timebase to derive metadata from the namespace automatically rather than forcing the user to manually type values for each subscription.

When you configure a Topic Definition such as namespace.channel.group1, each segment of the OPC UA path now has a semantic label that the collector can reference. If the OPC UA node being historized sits under a path like Austin/Packaging/Filler/Filler B/Motor Speed.pv, the collector does not inherently know that “Austin” represents a site, “Packaging” represents an area, or “Filler” represents an equipment type. However, because Topic Definition has mapped the first three segments of the path to meaningful labels, Fields can now pull those values automatically.

For example, you can create a Field where the Identifier is “Site” and the Value is [Topic.namespace]. This instructs the collector to take the first segment of the OPC UA path (mapped as namespace through Topic Definition) and record it as the Site metadata on the tag. The result is that every tag in that namespace will automatically include Austin as the  "Site" without hardcoding the word Austin anywhere in configuration.

You could achieve the same result by hardcoding Austin as the "Site", but the advantage of using Topic Definition becomes clear when dealing with attributes that vary, such as area, line, or equipment type. By linking Fields to Topic Definition rather than typed values, the tag metadata always stays correct even when new equipment appears or when multiple lines and asset types exist. This makes OPC UA subscriptions scalable, self-describing, and far easier to maintain as the plant evolves.

Tag Name Prefix: Static text automatically prepended to every generated tag name to help identify the data source or system origin.