Neutron OPC UA — manuale di integrazione

Versione del manuale: 1.0 · Data di pubblicazione: 18 ottobre 2026
Si applica a: firmware Neutron 2.5.0 con supporto OPC UA · Modello informativo del produttore 1.3.0

Guarda il video Neutron OPC UA su YouTube

PRECIZ è un membro ufficialmente registrato di OPC Foundation. Visualizza la voce ufficiale PRECIZ nell’elenco dei membri di OPC Foundation.

Scarica NodeSet2 XML · Modello 1.3.0 · Apri il configuratore Neutron BLE

Neutron di PRECIZ offre un server OPC UA per l’integrazione con PLC, SCADA, MES e applicazioni PC. L’interfaccia utilizza la comunicazione OPC UA Client/Server su UA-TCP con codifica UA Binary.

Il server offre:

Tutte le variabili di processo esposte sono di sola lettura. Le operazioni vengono eseguite tramite metodi. L’interfaccia non offre esecuzione arbitraria di comandi nativi, taratura, controllo delle uscite, selezione dell’applicazione, risultati del conteggio, storico, eventi o OPC UA PubSub. Il modello informativo è un modello proprietario PRECIZ, non il modello complementare OPC UA Weighing o Device Integration.

Tre modi di ottenere una misura rispondono a finalità diverse:

Esempio di endpoint:

opc.tcp://192.168.50.73:4840

Utilizzate un valore soltanto quando il relativo StatusCode OPC UA è Good. ErrorCode=1 indica che la bilancia nativa non ha errori. Status=1 o Status=3 descrive un’indicazione stabile.

L’endpoint ha la forma opc.tcp://<assigned-device-IP>:<port>. Utilizzate l’indirizzo dell’interfaccia Wi-Fi, Ethernet o LTE selezionata. La scheda OPC UA mostra l’indirizzo e offre un pulsante per copiarlo. Un indirizzo IP stabile semplifica l’integrazione.

Non è necessario configurare nel dispositivo l’indirizzo IP del PLC. Consentite il traffico TCP in entrata verso la porta selezionata. Il client deve disporre di un percorso di rete verso Neutron; un indirizzo LTE dietro NAT dell’operatore non è automaticamente raggiungibile dall’esterno di tale rete. Utilizzate una rete instradata adeguata, un APN privato o una VPN.

Il salvataggio delle impostazioni OPC UA riavvia il servizio OPC UA e disconnette i client. Anche le modifiche a utenti e attendibilità riavviano il servizio. Riconnettetevi dopo queste modifiche. Vengono riutilizzate le impostazioni esistenti di IP del dispositivo, bilancia e orologio.

L’intervallo minimo è un limite inferiore, non un periodo fisso di trasmissione né una garanzia di latenza complessiva. I client richiedono i propri intervalli e devono utilizzare i valori rivisti restituiti dal server.

In modalità cifrata non sono supportate sessioni anonime né l’autenticazione utente basata su certificati. Il certificato applicativo del client identifica il software client; non sostituisce l’autenticazione con nome utente e password. Il PIN della configurazione web e il certificato HTTPS sono separati dalle credenziali e dai certificati OPC UA.

Utilizzate la modalità non protetta su una rete isolata e attendibile. Non cifra i dati e non autentica i singoli utenti.

Il client deve considerare attendibile Neutron prima di poter proseguire fino all’invio del proprio certificato. L’approvazione non esclude la verifica di scadenza, firma, utilizzo della chiave o URI dell’applicazione.

I ruoli memorizzati Reader e Operator corrispondono a queste due autorizzazioni. Non esistono livelli di autorizzazione per singolo comando. In modalità cifrata si applica l’autorizzazione dell’utente; OUC viene ignorato. In modalità non protetta OUC autorizza tutti i comandi supportati oppure nessuno.

Cinque accessi falliti provocano un blocco degli accessi di 30 secondi per l’intero server. Ciò può temporaneamente interessare anche altri utenti. Le password degli utenti vengono memorizzate come hash PBKDF2-HMAC-SHA256 con salt; l’interfaccia di amministrazione non esporta password o chiavi private.

L’URI applicativo di Neutron è:

urn:preciz:cs-neutron:<MID>

Il certificato generato include questo URI, il nome host <MID>.local in minuscolo e l’IP del dispositivo al momento della generazione. Mantenete stabile l’indirizzo oppure emettete un certificato sostitutivo che contenga gli indirizzi utilizzati dai client.

Non serve un certificato CA per certificati applicativi autofirmati esplicitamente considerati attendibili. Per una PKI gestita dall’azienda:

Sono supportate importazioni PEM o DER, fino a 8192 byte per file. Ciascun archivio di certificati attendibili, rifiutati, emittenti e CRL contiene fino a 12 voci. Rimuovete le voci rifiutate obsolete quando l’archivio è pieno. Per le CRL installate vengono controllate date e firma dell’emittente; le CRL scadute causano il rifiuto delle nuove connessioni interessate. Senza CRL installate, il controllo delle revoche non viene eseguito. Le CRL non vengono scaricate automaticamente; non sono offerte la gestione OCSP e GDS.

Rinnovate un certificato creando una CSR e importando il certificato rinnovato. Un certificato del dispositivo scaduto impedisce l’avvio sicuro. Replace device identity rimuove chiave, certificato e CSR attuali e genera una nuova identità all’avvio sicuro successivo; i client devono considerarla nuovamente attendibile. Utenti e client attendibili vengono mantenuti.

Utenti e archivi dei certificati restano disponibili dopo normali riavvii e aggiornamenti OTA. La cancellazione del filesystem del dispositivo li rimuove. Prima di trasferire la proprietà del dispositivo, rimuovete esplicitamente gli utenti precedenti e le voci di attendibilità.

URI del namespace del produttore:

urn:preciz:cs-neutron:weighing:1

Risolvete questo URI in Server/NamespaceArray a ogni connessione. Non impostate nel codice un indice di namespace fisso pari a 1 o 2. Il suffisso di versione :1 appartiene all’URI stabile del namespace; la versione del modello scaricabile è 1.3.0.

Esempi di forme per la stessa variabile:

nsu=urn:preciz:cs-neutron:weighing:1;s=Scale.Gross
ns=2;s=Scale.Gross

La forma numerica è valida soltanto quando il server assegna attualmente questo URI all’indice 2. Se un client non accetta la sintassi nsu=, risolvete l’URI e costruite il NodeId con indice numerico. Gli identificatori del produttore sono stringhe che distinguono maiuscole e minuscole, compresi i punti in Scale.Gross.

I metodi devono essere richiamati con Scale come ObjectId padre e con il NodeId del metodo come MethodId.

Gross, Net e Tare vengono esportati come valori Double normalizzati al numero di decimali configurato. HR è il peso lordo ad alta risoluzione prima dell’arrotondamento del display, non il peso netto né l’ADC grezzo. Ogni peso utilizza l’unità attuale Scale.Unit; OPC UA non converte le unità. Il tipo di trasporto Double non aumenta la precisione del sensore.

I valori binari in virgola mobile non rappresentano esattamente ogni decimale. Formattate i pesi visualizzati utilizzando Scale.Decimals e utilizzate Scale.Division come passo di pesatura. HR può apparire in notazione scientifica: 9.31e-5 kg significa 0.0000931 kg.

Neutron copia gli ultimi valori di pesatura nell’istantanea OPC UA approssimativamente ogni min(OUI, 50) millisecondi, secondo la disponibilità dell’acquisizione. Letture e sottoscrizioni non avviano un’altra conversione ADC.

SourceTimestamp identifica l’istante dell’istantanea di misura quando l’orologio del dispositivo è sincronizzato. È assente prima della sincronizzazione. ServerTimestamp è il riferimento temporale fornito dal server per il DataValue; non deve necessariamente coincidere con SourceTimestamp. I riferimenti temporali OPC UA utilizzano UTC.

Letture separate o notifiche di sottoscrizione possono riferirsi a istantanee diverse. Utilizzate ReadMeasurement o un risultato acquisito quando i campi devono appartenere alla stessa misura. Un valore monitorato invariato non deve necessariamente produrre una nuova notifica a ogni intervallo.

La qualità si applica a pesi, ADC e Stable. Status, ErrorCode e Unit restano leggibili durante errori nativi della bilancia, ma diventano obsoleti se le istantanee si interrompono. La diagnostica di comandi e acquisizioni resta leggibile indipendentemente dalla qualità della bilancia in tempo reale. I metadati sono informazioni di configurazione; il loro stato Good non dimostra che il risultato di pesatura in tempo reale sia valido.

Tutte le voci seguenti sono di sola lettura. I NodeId sono identificatori stringa del produttore, salvo quelli indicati come namespace standard 0. Tutte le voci scalari hanno ValueRank −1.

ADC non è una scansione separata per ciascuna cella di carico. Non viene esposta alcuna variabile mV. Nonostante il nome, HRFilter controlla la funzione esistente FC/chopping ADC, non un filtro software applicato esclusivamente alla variabile HR di OPC UA.

Utilizzate Scale.Stable come indicatore di stabilità. Scale.Status e StatusCode OPC UA sono concetti separati; uno stato nativo pari a 3 non è un codice di qualità OPC UA.

Le proprietà hanno i seguenti NodeId String del produttore. I relativi BrowseName si trovano nel namespace 0, ad esempio 0:EngineeringUnits.

EURange è [0, Capacity], tranne per Net che utilizza [-Capacity, Capacity]. L’intervallo ingegneristico è un metadato, non un’istruzione per limitare i valori. ValuePrecision è il numero di decimali, non la divisione né una specifica di precisione. HR non ha una proprietà ValuePrecision.

EngineeringUnits utilizza i codici UN/CEFACT per kg (4933453), g (4674125), lb (4997714) e oz (5197402). Gli altri simboli di unità hanno UnitId −1 e un namespace standard vuoto. Aggiornate i metadati dopo modifiche a unità, campo o configurazione della bilancia.

Gli ID dei comandi e delle acquisizioni sono sequenze separate. Entrambe sono condivise da tutti i client, locali al servizio in esecuzione e azzerate al riavvio del servizio.

I valori di identificazione vengono caricati all’avvio di OPC UA. Riavviate il servizio dopo aver modificato il nome del dispositivo per aggiornare DeviceName.

I percorsi seguenti sono relativi a Objects / Server e utilizzano il namespace 0.

Le variabili array standard hanno ValueRank 1 e ArrayDimensions [0]; zero indica una lunghezza massima non specificata. ServerProfileArray identifica il target di implementazione Micro Embedded Device 2017 e i facet attivi di trasporto, metodi e sicurezza. Questo identificatore di profilo non è un marchio di certificazione OPC Foundation.

Scale.ActiveChannel è una variabile UInt16 che mostra il canale di pesatura attualmente attivo. È di sola lettura; selezionate un canale tramite Scale.SetChannel. NodeSet2 1.3.0 supporta la selezione dei canali 1–4. Risolvete l’URI del namespace alla connessione, come descritto nella sezione 5.1.

Richiamate ogni metodo sull’oggetto padre Scale. Fornite argomenti scalari con i tipi OPC UA esatti indicati; non sostituite String, Int32 o Double a un argomento UInt32 o Boolean.

SetChannel utilizza Channel: UInt16 (1–4) e restituisce RequestId: UInt32; vedere la sezione 7.9.

Esegue la tara del peso lordo stabile attuale tramite l’operazione nativa T. Imposta la tara uguale al lordo e il netto diventa zero; non modifica il punto di zero del lordo. La bilancia deve accettare l’operazione di tara stabile entro il timeout del comando.

Esempio con 1.11 kg sulla bilancia: Gross resta 1.11 kg, Tare diventa 1.11 kg e Net diventa 0.00 kg. Una risposta nativa riuscita è simile a T S 1.11 kg.

Imposta una tara preimpostata in Scale.Unit tramite l’operazione nativa TA. Value deve essere finito, non negativo, non superiore a 1.000.000.000 e non superiore alla portata. La tara applicata viene arrotondata alla divisione della bilancia. Leggete Scale.Tare al termine per ottenere il valore applicato. Esempio di ingresso: Double 0.250 quando Unit è kg.

Esegue il comando nativo Z, secondo la stabilità e l’intervallo di zero configurato. Se riesce, il punto di zero viene regolato e la tara applicata o preimpostata esistente viene cancellata. La risposta nativa riuscita è Z A. Questa operazione è distinta da TareCurrent.

Esegue il comando nativo TAC, rimuovendo la tara applicata e preimpostata. Gross viene mantenuto e Net torna uguale a Gross. Non vi sono argomenti di ingresso.

Value è UInt16, 1–1023 inclusi. Imposta FT per il canale di pesatura attivo tramite il gestore esistente della configurazione del filtro. Zero e valori superiori a 1023 restituiscono BadOutOfRange. Esempio: UInt16 512.

Enabled è Boolean: true attiva il chopping FC/ADC, false lo disattiva. Un valore numerico inviato con un tipo OPC UA numerico non è un Boolean e viene rifiutato.

FT e FC vengono attivati e salvati per il canale attivo tramite i gestori di configurazione nativi. Un errore della verifica hardware produce un esito del comando non riuscito. L’acquisizione può interrompersi durante l’applicazione dell’impostazione. Leggete Scale.Filter o Scale.HRFilter al termine per conoscere l’impostazione attiva.

Per TareCurrent, SetTare, Zero, ClearTare, SetChannel, SetFilter e SetHRFilter:

Un risultato Call Good conferma l’accettazione, non il completamento. Soltanto uno di questi comandi può essere in coda o in esecuzione alla volta; un altro riceve BadResourceUnavailable. Restano validi i vincoli esistenti di stabilità, disponibilità, stato occupato e interblocchi applicativi della bilancia.

Lo slot del comando e la diagnostica dell’ultimo risultato sono condivisi dall’intero dispositivo. Coordinate chi invia i comandi se due client possono farlo: un comando successivo può sostituire la diagnostica dell’ultimo completato prima che un altro client la legga. Non costituisce uno storico dei comandi.

Gli ID delle richieste non sono identificatori persistenti delle operazioni. Dopo una perdita di connessione, controllate lo stato della bilancia interessato prima di riprovare un comando il cui esito è sconosciuto. Il riavvio del servizio cancella la diagnostica e annulla i comandi della bilancia gestiti da OPC UA ancora incompleti; non annulla una tara, un azzeramento o una modifica delle impostazioni già completati.

Richiamate Scale.SetChannel sull’oggetto Scale. Il suo argomento di ingresso Channel è uno scalare UInt16 con valore 1–4; gli altri valori vengono rifiutati. L’argomento di uscita RequestId è un UInt32.

La chiamata richiede l’autorizzazione ai comandi e reinizializza la bilancia. Coordinate l’esecuzione con gli altri comandi e seguite la sequenza asincrona della sezione 7.8. Leggete il canale selezionato da Scale.ActiveChannel.

ReadMeasurement() restituisce immediatamente l’ultima istantanea valida. Non attende la stabilità e non richiede una nuova lettura ADC. GetCapturedMeasurement restituisce la stessa struttura di uscita per un risultato stabile memorizzato.

Tutti i campi appartengono a un’unica istantanea. MeasurementId aumenta per ogni istantanea OPC UA, non per ogni conversione ADC fisica, e si azzera con il servizio. Conservate la precisione UInt64 quando lo memorizzate. ADC, metadati e filtri sono nodi in tempo reale separati e non sono inclusi nel risultato a undici campi di questo metodo.

Se TimeSynchronized è false, non interpretate Timestamp come una data di calendario. ReadMeasurement restituisce BadNoCommunication, BadSensorFailure o BadOutOfRange quando l’istantanea in tempo reale è assente o obsoleta, presenta un errore nativo oppure è fuori campo.

In alternativa, sottoscrivete LastCaptureId e LastCaptureState, quindi recuperate il risultato quando la richiesta corrispondente raggiunge lo stato 2.

L’istantanea acquisita deve essere pubblicata dopo l’avvio della richiesta e deve essere stabile, recente, priva di errori nativi ed entro il campo. Le istantanee non valide vengono saltate finché ne arriva una adeguata o scade il timeout. Se la bilancia è già stabile, l’istantanea valida successiva può completare subito l’acquisizione; non serve una transizione da instabile a stabile né un ulteriore periodo di mantenimento.

L’operazione non esegue la tara o l’azzeramento della bilancia e non blocca gli altri client. Può essere in attesa una sola acquisizione. Esiste un solo risultato memorizzato per l’intero dispositivo, condiviso da tutti i client. Rimane invariato anche se il peso in tempo reale cambia o diventa indisponibile. L’avvio di una nuova acquisizione sostituisce richiesta e risultato precedenti. Non esiste uno storico delle acquisizioni.

Utilizzate il RequestId dell’acquisizione, non il MeasurementId del risultato, come ingresso di GetCapturedMeasurement. L’acquisizione può terminare dopo la disconnessione del client che l’ha avviata. Può essere recuperata dopo la riconnessione con lo stesso ID se il servizio OPC UA è rimasto in esecuzione. Il riavvio del servizio cancella acquisizioni in attesa, risultati memorizzati e ID; coordinate le richieste di acquisizione tra client.

Iniziate con 100–250 ms e dimensione della coda 1 per una visualizzazione in tempo reale. Per l’aggiornamento più rapido disponibile, impostate OUI a 10 ms, riconnettetevi dopo il salvataggio e richiedete campionamento e pubblicazione a 10 ms. Utilizzate gli intervalli rivisti dal server nella logica del client.

Campionare più rapidamente della frequenza fisica di acquisizione non crea nuove misure. Latenza di rete, cifratura, carico del client e impostazioni di pubblicazione influiscono sul tempo di risposta osservato. Server Status / Response Time di UAExpert non è l’intervallo di campionamento o pubblicazione della sottoscrizione.

Si tratta di totali per l’intero server, salvo quando è indicato un ambito per sessione o sottoscrizione. Se la coda delle richieste Publish è piena, la richiesta in attesa più vecchia riceve BadTooManyPublishRequests, così può essere accodata una nuova richiesta. Conferme e Republish operano sulla coda di ritrasmissione limitata. Il limite delle operazioni Write non rende scrivibili le variabili di sola lettura.

Chiudete correttamente le sessioni. Un client disconnesso può lasciare la sessione precedente a occupare uno slot fino alla scadenza. Riutilizzate o riattivate una sessione esistente, se supportato; altrimenti attendete la scadenza. Una nuova istanza del server non può riattivare una sessione precedente al riavvio del servizio: create una sessione, risolvete i namespace e ricreate le sottoscrizioni. I client TCP che non ricevono i dati possono essere disconnessi dopo una scadenza di invio di un secondo.

Installate il pacchetto client in un ambiente virtuale Python:

python -m pip install asyncua

Preparate un certificato applicativo del client OPC UA e la relativa chiave privata. Il relativo URI applicativo SAN deve corrispondere a CLIENT_URI qui sotto. Approvate il certificato su Neutron e scaricate il certificato di Neutron come neutron.der. Sostituite endpoint, nome utente e URI del client con i vostri valori. Il file della chiave privata di questo esempio è accessibile al client Python; non è la chiave privata di Neutron.

import asyncio
import getpass

from asyncua import Client, ua
from asyncua.crypto.security_policies import SecurityPolicyBasic256Sha256
from asyncua.ua.uaerrors import UaStatusCodeError

URL = "opc.tcp://192.168.50.73:4840"
NS_URI = "urn:preciz:cs-neutron:weighing:1"
CLIENT_URI = "urn:example:neutron-client"
FIELDS = ("MeasurementId", "Gross", "Net", "Tare", "HR", "Stable",
          "Status", "ErrorCode", "Unit", "Timestamp", "TimeSynchronized")
CAPTURE = False  # Set True when logged in with command permission.


async def main():
    client = Client(URL, timeout=10)
    client.application_uri = CLIENT_URI
    await client.set_security(
        SecurityPolicyBasic256Sha256,
        certificate="client.der",
        private_key="client-key.pem",
        server_certificate="neutron.der",
        mode=ua.MessageSecurityMode.SignAndEncrypt,
    )
    client.set_user(input("Username: "))
    client.set_password(getpass.getpass("Password: "))

    async with client:
        ns = await client.get_namespace_index(NS_URI)
        scale = client.get_node(ua.NodeId("Scale", ns))

        def method(name):
            return ua.NodeId("Scale." + name, ns)

        values = await scale.call_method(method("ReadMeasurement"))
        result = dict(zip(FIELDS, values))
        print("Current snapshot:", result)

        if CAPTURE:
            request_id = await scale.call_method(
                method("CaptureStableWeight"),
                ua.Variant(5000, ua.VariantType.UInt32),
            )
            deadline = asyncio.get_running_loop().time() + 7
            while True:
                try:
                    values = await scale.call_method(
                        method("GetCapturedMeasurement"),
                        ua.Variant(request_id, ua.VariantType.UInt32),
                    )
                    print("Capture", request_id, dict(zip(FIELDS, values)))
                    break
                except UaStatusCodeError as exc:
                    if exc.code != ua.StatusCodes.BadWaitingForInitialData:
                        raise
                    if asyncio.get_running_loop().time() >= deadline:
                        raise TimeoutError("Client capture wait expired") from exc
                    await asyncio.sleep(0.1)


asyncio.run(main())

ReadMeasurement richiede dati validi in tempo reale. Eccezioni come BadSensorFailure o BadOutOfRange devono essere gestite dall’applicazione chiamante. BadTimeout da GetCapturedMeasurement significa che il timeout di acquisizione del server è scaduto; non è un motivo per riutilizzare una vecchia misura memorizzata come nuova acquisizione riuscita.

Il codice seguente viene eseguito all’interno di una connessione async with client già stabilita. Il gestore verifica la qualità prima di utilizzare il valore.

class WeightHandler:
    def datachange_notification(self, node, value, data):
        status = data.monitored_item.Value.StatusCode
        if status.is_good():
            print(node.nodeid.to_string(), value)
        else:
            print("Invalid measurement:", status)


ns = await client.get_namespace_index(NS_URI)
gross = client.get_node(ua.NodeId("Scale.Gross", ns))
subscription = await client.create_subscription(100, WeightHandler())
try:
    await subscription.subscribe_data_change(gross, queuesize=1)
    await asyncio.sleep(30)
finally:
    await subscription.delete()

L’intervallo di pubblicazione richiesto è 100 ms. Configurate il campionamento degli elementi monitorati tramite la libreria client secondo necessità e rispettate i valori rivisti dal server.

Utilizzate i blocchi client OPC UA forniti dal produttore del PLC. Risolvete i NodeId String tramite l’URI del namespace del produttore. Quella seguente è una sequenza indipendente dal produttore, non un’implementazione in uno specifico linguaggio di programmazione PLC:

CONNECT -> TRUST / AUTHENTICATE -> RESOLVE NAMESPACE URI
        -> RESOLVE Scale object and required variable/method NodeIds
        -> CREATE SUBSCRIPTION -> MONITOR LIVE DATA

On a stable-result request:
  Call Scale.CaptureStableWeight(TimeoutMs := UInt32(5000))
  Save returned RequestId
  Call Scale.GetCapturedMeasurement(RequestId)
    BadWaitingForInitialData -> wait 100 ms and repeat retrieval
    Good                    -> store the eleven fields as one record
    BadTimeout              -> report no stable result
    Other failure           -> handle the error; do not use old data

On tare request:
  Call Scale.TareCurrent()
  Save returned command RequestId
  Wait for matching LastCommandId and LastCommandState 3 or 4
  On success read Gross / Net / Tare; on failure read LastCommandResult

Associate MeasurementId UInt64 a un tipo intero PLC appropriato. Non inviate a SetHRFilter un sostituto numerico di Boolean. Serializzate i comandi e la gestione dell’acquisizione stabile nel PLC o nell’applicazione quando più client hanno l’autorizzazione ai comandi.

NodeSet2 descrive lo spazio degli indirizzi del produttore, gli argomenti dei metodi, i riferimenti e i tipi per gli strumenti di modellazione offline. Gli indici dei namespace sono locali al file XML; risolvete l’URI del namespace sul dispositivo in funzione. L’XML contiene definizioni del modello, non misure attuali né un backup di utenti, certificati o impostazioni. Gli intervalli in esecuzione e le autorizzazioni di esecuzione seguono la configurazione attiva del dispositivo.

L’URI del namespace resta urn:preciz:cs-neutron:weighing:1. Le firme dei metodi esistenti vengono mantenute; ReadMeasurement/GetCapturedMeasurement restituiscono undici campi. Scegliete un firmware che contenga OPC UA e le funzioni richieste dall’integrazione. Una build del firmware senza OPC UA non può esporre un endpoint.