You are here: Leader.IT>Portal Web>OpcUApipeGateway (23 Nov 2025, GuidoBrugnara)Edit Attach

OPC-UA Pipe Gateway

Introduction

opcua_pipe_gateway is an OPC-UA client that allows reading and writing OPC-UA variables via command line interface, using STDIN for commands and STDOUT for results. The application is available in two implementations: a Perl version (opcua_pipe_gateway.pl) and a Python version (opcua_pipe_gateway.py).

Both versions share the same basic functionality and user interface, ensuring compatibility and interchangeability in use.

Common Features

The following features are implemented in both versions (.pl and .py):

Command Line Interface

Reading variables from STDIN
Output results to STDOUT
Log and debug messages to STDERR
Line-buffered processing for use in Unix pipelines

Variable Operations

Scalar variable reading: reading the complete value of a variable
Array element reading: access to individual elements via syntax variabile[indice]
Scalar variable writing: writing complete values
Array element writing: modifying individual array elements
Data type preservation: the original variable type is maintained during writes

Standard OPC-UA NodeId Format

Support for standard format ns=;=
Supported types: s (string), i (numeric), g (GUID), b (bytestring)
Example: ns=2;s=Eth50._System._NetworkAdapter

Variable Names with Spaces

Support for variable names with spaces using quotes
Syntax: "variabile con spazi" := valore
Escape of quotes and special characters

Supported Data Types

Scalars: Int32, Double, Float, String, Boolean, UInt16, Int16, Int64, UInt32, UInt64, Byte, SByte
Arrays: all supported scalar types
Automatic type management: automatic type inference and conversion

Authentication and Security

Username/password authentication: support for credential-based authentication
Certificate encryption: support for client certificates (.pem or .der)
Client private key: support for private keys (.pem or .der)
Server certificate: support for trust list with server certificate
Security policy: Basic256Sha256 SignAndEncrypt

Configuration

Configuration file: support for configuration files in format key=value
Command line options: all options can be specified from command line
Configuration priority: command line values take priority over those in the file
Configurable parameters: cert, key, server_cert, user, password, endpoint, log_level

Error Handling

Exit codes: exit code system for error handling
- 0: No errors
- 1: At least one variable returned (error)
- 2: At least one variable returned (out of band)
- 3: Both errors and "out of band" were detected
Error messages: output to STDERR for diagnostics
Array out of bounds handling: message (out of band) for indices out of bounds

Logging and Debug

Configurable log levels: none, fatal, error, warn, info, debug, trace
Debug output: --debug option for detailed output
Log to STDERR: all log messages are sent to STDERR

Input/Output Format

Read syntax: variabile or variabile[indice]
Write syntax: variabile := valore or variabile = valore (for backward compatibility)
Output format: variabile = valore for scalars, variabile = [elemento1, elemento2, ...] for arrays
Special characters (Escape): automatic handling of newline, tab, quotes, etc.

Compatibility

Unix pipeline: designed for use in pipelines and shell scripts
Line-buffered processing: each line is processed immediately
KEPServerEX compatibility: support for industrial servers like KEPServerEX (Tested version V6)
ApplicationUri handling: automatic extraction from certificates for compatibility

Implementations

The opcua_pipe_gateway application is available in two implementations that share the same functionality but use different libraries and approaches:

Perl Version (opcua_pipe_gateway.pl)

Library Used

Base library: OPCUA::Open62541 (Perl wrapper for the open62541 C library)
Underlying C library: open62541 v1.3.8 or higher
Library license: MPL-2.0 (open62541), GPL v1 / Artistic License 1.0 (OPCUA::Open62541)

Implementation Features

Event loop handling: uses run_iterate() to process OPC-UA events
Connection handling: explicit control of session state (SESSIONSTATE_ACTIVATED)
KEPServerEX timestamp handling: the open62541 library automatically handles timestamps
Session stabilization: performs additional iterations after activation to stabilize the connection
Memory management: conservative cleanup to avoid memory problems

Dependencies

Perl 5.24 or higher
OPCUA::Open62541 module from CPAN
Compiled and installed open62541 library
Standard Perl modules: Time::HiRes, Data::Dumper

Advantages

Performance: native C library for optimal performance
Stability: open62541 library widely tested and used
Compatibility: full support for all OPC-UA features
Standalone executable: possibility to create standalone executables with all dependencies

Python Version (opcua_pipe_gateway.py)

Library Used

Base library: python-opcua (freeopcua)
Library license: LGPL-3.0

Implementation Features

Connection handling: uses the high-level API of python-opcua
Endpoint discovery: performs automatic endpoint discovery to find Basic256Sha256
KEPServerEX timestamp handling: explicit implementation to avoid timestamps in writes
- Uses set_attribute() instead of set_value() for direct control
- Explicitly sets SourceTimestamp and ServerTimestamp to None
DataValue handling: explicit creation of DataValue without timestamp for KEPServerEX compatibility
Error handling: try/except for robust exception handling

Dependencies

Python 3.6 or higher
opcua module from pip
Standard Python modules: sys, os, re, argparse, json, io

Advantages

Easy installation: simple installation via pip
High-level API: simpler and more intuitive interface
Automatic management: many operations handled automatically by the library
Virtual environments: support for Python virtual environments for dependency isolation

Main Differences

Timestamp Handling for KEPServerEX

Perl version: the open62541 library automatically handles timestamps. No explicit intervention is necessary.
Python version: explicit implementation to avoid timestamps. Uses set_attribute() with DataValue without timestamp to prevent KEPServerEX from rejecting writes.

Connection Handling

Perl version: explicit control of session state with getState() and manual iterations with run_iterate().
Python version: more automatic handling via the python-opcua API, with automatic endpoint discovery.

Data Type Handling

Perl version: uses open62541 type constants (TYPES_INT32, TYPES_DOUBLE, etc.).
Python version: uses python-opcua enums (ua.VariantType.Int32, ua.VariantType.Double, etc.).

Performance

Perl version: optimal performance thanks to native C library.
Python version: generally good performance, may vary depending on load and Python version.

Installation and Distribution

Perl version: requires compilation of open62541 and installation of Perl module. Possibility to create standalone executables.
Python version: simpler installation via pip, but requires Python and dependencies on the target system.

Error Handling

Perl version: error handling via status codes and explicit state checking.
Python version: error handling via Python exceptions with try/except.

Usage Examples

Both versions support the same usage examples:

Reading Variables

echo "the.answer" | opcua_pipe_gateway opc.tcp://127.0.0.1:4840
echo "the.answer" | opcua_pipe_gateway.py opc.tcp://127.0.0.1:4840

Writing Variables

echo "the.answer := 42" | opcua_pipe_gateway opc.tcp://127.0.0.1:4840
echo "the.answer := 42" | opcua_pipe_gateway.py opc.tcp://127.0.0.1:4840

Arrays

echo "test.array[0]" | opcua_pipe_gateway opc.tcp://127.0.0.1:4840
echo "test.array[0] := 99" | opcua_pipe_gateway opc.tcp://127.0.0.1:4840

With Configuration

echo "variabile" | opcua_pipe_gateway --config config.conf opc.tcp://127.0.0.1:4840
echo "variabile" | opcua_pipe_gateway.py --config config.conf opc.tcp://127.0.0.1:4840