OPC-UA Pipe Gateway

Introduzione

opcua_pipe_gateway è un client OPC-UA che permette di leggere e scrivere variabili OPC-UA tramite interfaccia a riga di comando, utilizzando STDIN per i comandi e STDOUT per i risultati. L'applicazione è disponibile in due implementazioni: una versione Perl (opcua_pipe_gateway.pl) e una versione Python (opcua_pipe_gateway.py).

Entrambe le versioni condividono le stesse funzionalità di base e la stessa interfaccia utente, garantendo compatibilità e intercambiabilità nell'uso.

Funzionalità Comuni

Le seguenti funzionalità sono implementate in entrambe le versioni (.pl e .py):

Interfaccia a Riga di Comando

• Lettura di variabili da STDIN
• Output dei risultati su STDOUT
• Messaggi di log e debug su STDERR
• Processing line-buffered per uso in pipeline Unix

Operazioni su Variabili

• Lettura di variabili scalari: lettura del valore completo di una variabile
• Lettura di elementi array: accesso a singoli elementi tramite sintassi variabile[indice]
• Scrittura di variabili scalari: scrittura di valori completi
• Scrittura di elementi array: modifica di singoli elementi di array
• Preservazione del tipo di dato: il tipo originale della variabile viene mantenuto durante le scritture

Formato NodeId Standard OPC-UA

• Supporto per il formato standard ns=;=
• Tipi supportati: s (stringa), i (numerico), g (GUID), b (bytestring)
• Esempio: ns=2;s=Eth50._System._NetworkAdapter

Nomi Variabili con Spazi

• Supporto per nomi variabili con spazi utilizzando virgolette
• Sintassi: "variabile con spazi" := valore
• Escape di virgolette e caratteri speciali

Tipi di Dato Supportati

• Scalari: Int32, Double, Float, String, Boolean, UInt16, Int16, Int64, UInt32, UInt64, Byte, SByte
• Array: tutti i tipi scalari supportati
• Gestione automatica del tipo: inferenza e conversione automatica dei tipi

Autenticazione e Sicurezza

• Autenticazione username/password: supporto per autenticazione basata su credenziali
• Crittografia con certificati: supporto per certificati client (.pem o .der)
• Chiave privata client: supporto per chiavi private (.pem o .der)
• Certificato server: supporto per trust list con certificato server
• Security policy: Basic256Sha256 SignAndEncrypt

Configurazione

• File di configurazione: supporto per file di configurazione in formato key=value
• Opzioni da riga di comando: tutte le opzioni possono essere specificate da riga di comando
• Priorità configurazione: i valori da riga di comando hanno priorità su quelli nel file
• Parametri configurabili: cert, key, server_cert, user, password, endpoint, log_level

Gestione Errori

• Codici di uscita: sistema di codici di uscita per gestione errori
  • 0: Nessun errore
  • 1: Almeno una variabile ha restituito (error)
  • 2: Almeno una variabile ha restituito (out of band)
  • 3: Sia errori che "out of band" sono stati rilevati
• Messaggi di errore: output su STDERR per diagnostica
• Gestione array out of bounds: messaggio (out of band) per indici fuori dai limiti

Logging e Debug

• Livelli di log configurabili: none, fatal, error, warn, info, debug, trace
• Output debug: opzione --debug per output dettagliato
• Log su STDERR: tutti i messaggi di log vengono inviati su STDERR

Formato Input/Output

• Sintassi lettura: variabile o variabile[indice]
• Sintassi scrittura: variabile := valore o variabile = valore (per retrocompatibilità)
• Formato output: variabile = valore per scalari, variabile = [elemento1, elemento2, ...] per array
• Caratteri speciali (Escape): gestione automatica di newline, tab, virgolette, ecc.

Compatibilità

• Pipeline Unix: progettato per uso in pipeline e script shell
• Processing line-buffered: ogni riga viene processata immediatamente
• Compatibilità KEPServerEX: supporto per server industriali come KEPServerEX (TEstata versione V6)
• Gestione ApplicationUri: estrazione automatica da certificati per compatibilità

Implementazioni

L'applicazione opcua_pipe_gateway è disponibile in due implementazioni che condividono le stesse funzionalità ma utilizzano librerie e approcci diversi:

Versione Perl (opcua_pipe_gateway.pl)

Libreria Utilizzata

• Libreria base: OPCUA::Open62541 (wrapper Perl per la libreria C open62541)
• Libreria C sottostante: open62541 v1.3.8 o superiore
• Licenza libreria: MPL-2.0 (open62541), GPL v1 / Artistic License 1.0 (OPCUA::Open62541)

Caratteristiche Implementative

• Gestione event loop: utilizza run_iterate() per processare eventi OPC-UA
• Gestione connessione: controllo esplicito dello stato della sessione (SESSIONSTATE_ACTIVATED)
• Gestione timestamp KEPServerEX: la libreria open62541 gestisce automaticamente i timestamp
• Stabilizzazione sessione: esegue iterazioni aggiuntive dopo l'attivazione per stabilizzare la connessione
• Gestione memoria: cleanup conservativo per evitare problemi di memoria

Dipendenze

• Perl 5.24 o superiore
• Modulo OPCUA::Open62541 da CPAN
• Libreria open62541 compilata e installata
• Moduli Perl standard: Time::HiRes, Data::Dumper

Vantaggi

• Prestazioni: libreria C nativa per prestazioni ottimali
• Stabilità: libreria open62541 ampiamente testata e utilizzata
• Compatibilità: supporto completo per tutte le funzionalità OPC-UA
• Eseguibile standalone: possibilità di creare eseguibili standalone con tutte le dipendenze

Versione Python (opcua_pipe_gateway.py)

Libreria Utilizzata

• Libreria base: python-opcua (freeopcua)
• Licenza libreria: LGPL-3.0

Caratteristiche Implementative

• Gestione connessione: utilizza l'API ad alto livello di python-opcua
• Discovery endpoint: esegue discovery automatico degli endpoint per trovare Basic256Sha256
• Gestione timestamp KEPServerEX: implementazione esplicita per evitare timestamp nelle scritture
  • Utilizza set_attribute() invece di set_value() per controllo diretto
  • Imposta esplicitamente SourceTimestamp e ServerTimestamp a None
• Gestione DataValue: creazione esplicita di DataValue senza timestamp per compatibilità KEPServerEX
• Gestione errori: try/except per gestione robusta delle eccezioni

Dipendenze

• Python 3.6 o superiore
• Modulo opcua da pip
• Moduli Python standard: sys, os, re, argparse, json, io

Vantaggi

• Facilità di installazione: installazione semplice tramite pip
• API ad alto livello: interfaccia più semplice e intuitiva
• Gestione automatica: molte operazioni gestite automaticamente dalla libreria
• Ambienti virtuali: supporto per ambienti virtuali Python per isolamento dipendenze

Differenze Principali

Gestione Timestamp per KEPServerEX

• Versione Perl: la libreria open62541 gestisce automaticamente i timestamp. Non è necessario intervento esplicito.
• Versione Python: implementazione esplicita per evitare timestamp. Utilizza set_attribute() con DataValue senza timestamp per evitare che KEPServerEX rifiuti le scritture.

Gestione Connessione

• Versione Perl: controllo esplicito dello stato della sessione con getState() e iterazioni manuali con run_iterate().
• Versione Python: gestione più automatica tramite l'API di python-opcua, con discovery automatico degli endpoint.

Gestione Tipi di Dato

• Versione Perl: utilizza le costanti di tipo di open62541 (TYPES_INT32, TYPES_DOUBLE, ecc.).
• Versione Python: utilizza gli enum di python-opcua (ua.VariantType.Int32, ua.VariantType.Double, ecc.).

Prestazioni

• Versione Perl: prestazioni ottimali grazie alla libreria C nativa.
• Versione Python: prestazioni generalmente buone, possono variare a seconda del carico e della versione di Python.

Installazione e Distribuzione

• Versione Perl: richiede compilazione di open62541 e installazione del modulo Perl. Possibilità di creare eseguibili standalone.
• Versione Python: installazione più semplice tramite pip, ma richiede Python e le dipendenze sul sistema target.

Gestione Errori

• Versione Perl: gestione errori tramite status code e controllo esplicito dello stato.
• Versione Python: gestione errori tramite eccezioni Python con try/except.

Esempi d'Uso

Entrambe le versioni supportano gli stessi esempi d'uso:

Lettura di Variabili

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

Scrittura di Variabili

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

Array

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

Con Configurazione

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

Requisiti di Sistema

Versione Perl

• Sistema operativo: Debian 10+ o Ubuntu 18.04+
• Perl: versione 5.24 o superiore
• Libreria open62541: versione 1.3.8 o superiore
• Modulo Perl OPCUA::Open62541
• Moduli Perl standard: Time::HiRes, Data::Dumper

Versione Python

• Sistema operativo: Debian 10+ o Ubuntu 18.04+
• Python: versione 3.6 o superiore
• Libreria python-opcua (freeopcua)
• Moduli Python standard: sys, os, re, argparse, json, io

Supporto

Per problemi o domande:

• Repository del progetto: https://www.leader.it/Portal/OpcUApipeGateway
• Documentazione POD (versione Perl): perldoc opcua_pipe_gateway
• Log del server OPC-UA per diagnostica

Copyright e Disclaimer

Copyright (c) 2025 Guido Brugnara <gdo@leader.it>. Tutti i diritti riservati.

Sono disponibili due licenze:

• Commerciale (con supporto)
• Open Source Artistic Lic. nella versione Perl

Il codice e la documentazione sono state redatte con l'ausilio di strumenti di supporto al lavoro basati su Intelligenza Artificiale.

Si declina ogni responsabilità nell'uso del software in caso di danni diretti o indiretti.

Questo software utilizza le seguenti librerie open source:

• OPCUA::Open62541 (GPL v1 / Artistic License 1.0): https://github.com/bluhm/p5-opcua-open62541
• open62541 (MPL-2.0): https://github.com/open62541/open62541
• python-opcua (LGPL-3.0): https://github.com/FreeOpcUa/python-opcua

Per i dettagli completi delle licenze, consultare i file LICENSE delle rispettive librerie.

Per informazioni: ContattiLeader