You are here: Leader.IT>Portal Web>OpcUApipeGateway (05 Jun 2026, 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

System Requirements

Perl Version

Operating system: Debian 10+ or Ubuntu 18.04+
Perl: version 5.24 or higher
open62541 library: version 1.3.8 or higher
Perl module OPCUA::Open62541
Standard Perl modules: Time::HiRes, Data::Dumper

Python Version

Operating system: Debian 10+ or Ubuntu 18.04+
Python: version 3.6 or higher
python-opcua library (freeopcua)
Standard Python modules: sys, os, re, argparse, json, io

Documentation

For detailed information on installation and configuration, see:

Perl version: LEGGIMI.opcua_pipe_gateway.pl.txt (Italian)
Python version: LEGGIMI.opcua_pipe_gateway.py.txt (Italian)

Source code

Subversion: https://guest@svn.leader.it/svn/opcua_pipe_gateway/tag/

⚠️ NOTICE – NOT SUPPORTED SOFTWARE

This software module is no longer maintained or supported by the original author.

This module was developed for customer internal use. The Perl/Python dual implementation was also a useful exercise in using Cursor.com (a VSCode fork)

As such, the module is not subject to obligations under the EU Cyber Resilience Act (CRA), which applies to software products placed on the market or provided to third parties under a commercial context.

No security updates, bug fixes, or official support will be provided. Users are advised not to use this software in production environments.