Module `opcxmlda`

Le module opcxmlda permet de communiquer avec des serveurs OPC XML-DA (Data Access) pour lire et écrire des données industrielles via le protocole SOAP/HTTP.

Import

Pour importer le module en Lua :

local opc = require("opcxmlda1")

Configuration YAML

Le module opcxmlda nécessite une configuration dans le fichier YAML de l'agent :

iot:
  modules:
    opcxmlda:
      - name: opcxmlda1                          # nom unique de l'instance
        endpoint: "http://server:8080/OPC/DA"    # URL du serveur OPC XML-DA
        timeout: 30                              # timeout en secondes (optionnel, défaut: 30)
        locale_id: "en-US"                       # locale pour les messages (optionnel, défaut: "en-US")
        username: ""                             # nom d'utilisateur (optionnel)
        password: ""                             # mot de passe (optionnel)
        # Options TLS (optionnel, pour HTTPS)
        cert_file: ""                            # chemin vers le certificat client
        key_file: ""                             # chemin vers la clé privée
        ca_file: ""                              # chemin vers le certificat CA
        insecure: false                          # ignorer la vérification TLS (défaut: false)

Détails de la configuration

name : Nom unique de l'instance du module. Utilisé pour l'import en Lua.
endpoint : URL complète du endpoint OPC XML-DA du serveur.
timeout : Délai d'attente pour les requêtes SOAP, en secondes (défaut: 30).
locale_id : Identifiant de locale pour les messages du serveur (défaut: "en-US").
username : Nom d'utilisateur pour l'authentification HTTP Basic (optionnel).
password : Mot de passe pour l'authentification HTTP Basic (optionnel).
cert_file : Chemin vers le certificat client pour l'authentification TLS mutuelle (optionnel).
key_file : Chemin vers la clé privée du certificat client (optionnel).
ca_file : Chemin vers le certificat de l'autorité de certification (optionnel).
insecure : Ignorer la vérification du certificat TLS du serveur (défaut: false).

API Lua

Liste des fonctions

Fonction	Signature Lua	Rôle	Retour (succès)	Retour (échec)
`connect`	`bool, err = opc.connect()`	Initialise le client HTTP.	`true, nil`	`nil, "msg"`
`disconnect`	`bool, err = opc.disconnect()`	Ferme les connexions.	`true, nil`	`nil, "msg"`
`getStatus`	`status, err = opc.getStatus()`	Récupère le statut du serveur.	`table, nil`	`nil, "msg"`
`browse`	`items, err = opc.browse([path])`	Parcourt l'arborescence des items.	`table, nil`	`nil, "msg"`
`read`	`values, err = opc.read(items)`	Lit les valeurs d'items.	`table, nil`	`nil, "msg"`
`write`	`results, err = opc.write(items)`	Écrit des valeurs dans des items.	`table, nil`	`nil, "msg"`
`getProperties`	`props, err = opc.getProperties(items)`	Récupère les propriétés d'items.	`table, nil`	`nil, "msg"`
Champs	`opc.name`, `opc.type`	Métadonnées du module.	–	–

`opcxmlda.connect()`

Initialise le client HTTP avec la configuration. Doit être appelé avant toute autre opération.

Paramètres : Aucun
Retour :
true si l'initialisation est réussie.
nil et un message d'erreur en cas d'échec (erreur de configuration TLS).

local opc = require("opcxmlda1")

local ok, err = opc.connect()
if not ok then
    print("Erreur de connexion : " .. err)
    return
end

print("Client OPC XML-DA initialisé")

`opcxmlda.disconnect()`

Ferme les connexions HTTP inactives et libère les ressources.

Paramètres : Aucun
Retour :
true si la déconnexion est réussie.
nil et un message d'erreur en cas d'échec.

local opc = require("opcxmlda1")

local ok, err = opc.disconnect()
if not ok then
    print("Erreur de déconnexion : " .. err)
end

`opcxmlda.getStatus()`

Récupère le statut du serveur OPC XML-DA.

Paramètres : Aucun
Retour :
Une table Lua contenant les informations du serveur.
nil et un message d'erreur en cas d'échec.

Champs retournés : - StartTime : Heure de démarrage du serveur - ProductVersion : Version du produit - ServerState : État du serveur - StatusInfo : Information de statut - VendorInfo : Information sur le fournisseur - SupportedLocales : Table des locales supportées

local opc = require("opcxmlda1")

opc.connect()
local status, err = opc.getStatus()
if not status then
    print("Erreur : " .. err)
else
    print("Serveur : " .. status.VendorInfo)
    print("Version : " .. status.ProductVersion)
    print("État : " .. status.ServerState)
end
opc.disconnect()

`opcxmlda.browse([itemPath])`

Parcourt l'arborescence des items disponibles sur le serveur.

Paramètres :
itemPath (string, optionnel) : Chemin de l'item à parcourir. Si omis, parcourt la racine.
Retour :
Une table Lua (array) contenant les éléments enfants.
nil et un message d'erreur en cas d'échec.

Chaque élément contient : - Name : Nom de l'élément - ItemName : Nom complet de l'item - ItemPath : Chemin de l'item - IsItem : true si l'élément est un item lisible - HasChildren : true si l'élément a des enfants

local opc = require("opcxmlda1")

opc.connect()

-- Parcourir la racine
local items, err = opc.browse()
if not items then
    print("Erreur : " .. err)
else
    for _, item in ipairs(items) do
        print("Item : " .. item.Name .. " (ItemPath: " .. item.ItemPath .. ")")
        if item.HasChildren then
            print("  -> A des enfants")
        end
    end
end

-- Parcourir un chemin spécifique
local subitems, err = opc.browse("Simulation Items")

opc.disconnect()

`opcxmlda.read(items)`

Lit les valeurs d'un ou plusieurs items OPC.

Paramètres :
items (string ou table) : Item unique (string) ou liste d'items (table) à lire.
Retour :
Une table Lua (array) contenant les valeurs lues.
nil et un message d'erreur en cas d'échec.

Chaque élément du résultat contient : - ItemName : Nom de l'item - ItemPath : Chemin de l'item - Value : Valeur de l'item - Quality : Qualité de la valeur (ex. "good") - Timestamp : Horodatage de la valeur - ResultID : Code de résultat (vide si succès)

local opc = require("opcxmlda1")

opc.connect()

-- Lecture d'un seul item
local values, err = opc.read("Simulation Items.Random.Real4")

-- Lecture de plusieurs items
local values, err = opc.read({
    "Simulation Items.Random.Real4",
    "Simulation Items.Random.Int4",
    "Simulation Items.Bucket Brigade.Real4"
})

if not values then
    print("Erreur : " .. err)
else
    for _, item in ipairs(values) do
        print(item.ItemName .. " = " .. tostring(item.Value) .. " [" .. item.Quality .. "]")
    end
end

opc.disconnect()

`opcxmlda.write(items)`

Écrit des valeurs dans un ou plusieurs items OPC.

Paramètres :
items (table) : Table contenant les items à écrire. Chaque élément est une table avec :
- ItemName (string) : Nom de l'item
- ItemPath (string, optionnel) : Chemin de l'item
- Value : Valeur à écrire
Retour :
Une table Lua (array) contenant les résultats de chaque écriture.
nil et un message d'erreur en cas d'échec.

Chaque élément du résultat contient : - ItemName : Nom de l'item - ItemPath : Chemin de l'item - ResultID : Code de résultat (vide si succès)

local opc = require("opcxmlda1")

opc.connect()

local results, err = opc.write({
    { ItemName = "Simulation Items.Bucket Brigade.Real4", Value = 42.5 },
    { ItemName = "Simulation Items.Bucket Brigade.Int4", Value = 100 }
})

if not results then
    print("Erreur d'écriture : " .. err)
else
    for _, result in ipairs(results) do
        if result.ResultID == "" then
            print(result.ItemName .. " : succès")
        else
            print(result.ItemName .. " : échec (" .. result.ResultID .. ")")
        end
    end
end

opc.disconnect()

`opcxmlda.getProperties(items)`

Récupère les propriétés d'un ou plusieurs items OPC.

Paramètres :
items (string ou table) : Item unique (string) ou liste d'items (table).
Retour :
Une table Lua (array) contenant les propriétés.
nil et un message d'erreur en cas d'échec.

Chaque élément contient : - Name : Nom de la propriété - Value : Valeur de la propriété - Description : Description de la propriété - ItemPath : Chemin de l'item - ItemName : Nom de l'item - ResultID : Code de résultat

local opc = require("opcxmlda1")

opc.connect()

local props, err = opc.getProperties("Simulation Items.Random.Real4")
if not props then
    print("Erreur : " .. err)
else
    for _, prop in ipairs(props) do
        print(prop.Name .. " = " .. tostring(prop.Value))
    end
end

opc.disconnect()

Exemple complet

local opc = require("opcxmlda1")
local json = require("json")
local alemca = require("alemca")

-- Connexion
local ok, err = opc.connect()
if not ok then
    printError("Connexion OPC XML-DA échouée : " .. err)
    return
end

-- Vérification du statut serveur
local status, err = opc.getStatus()
if not status then
    printError("Erreur statut : " .. err)
    opc.disconnect()
    return
end
printInfo("Serveur OPC XML-DA : " .. status.VendorInfo .. " - " .. status.ServerState)

-- Lecture des valeurs
local values, err = opc.read({
    "Process.Temperature",
    "Process.Pressure",
    "Process.Flow"
})

if not values then
    printError("Erreur lecture : " .. err)
else
    local data = {}
    for _, item in ipairs(values) do
        if item.Quality == "good" then
            data[item.ItemName] = item.Value
        end
    end

    -- Publication vers Alemca
    alemca.publish(json.encode(data), "opc_data")
end

-- Déconnexion
opc.disconnect()

Champs Lua associés

opcxmlda.name : Retourne le nom de l'instance du module.
opcxmlda.type : Retourne le type du module ("opcxmlda").

Module opcxmlda

Import

Configuration YAML

Détails de la configuration

API Lua

Liste des fonctions

opcxmlda.connect()

opcxmlda.disconnect()

opcxmlda.getStatus()

opcxmlda.browse([itemPath])

opcxmlda.read(items)

opcxmlda.write(items)

opcxmlda.getProperties(items)