WagoML : définition

Objectif

Le but est de définir une écriture de fichier xml situé dans un automate (WAGO), dans un dispositif similaire accessible sur Internet ou dans l'application PLCLink (iPhone, iPad). Ce fichier défini des items d'affichage avec plusieurs méthodes possibles pour atteindre les variables du dispositif à commander en écriture ou en lecture.

Définition de du fichier WagoML 1.0

Sur un automate Wago, le fichier wagoML est introduit dans l'automate dans le dossier "webserv", il est appelé régulièrement pour l'affichage de valeurs.
Une variante consiste à placer le fichier wagoML dans l'iPhone et de communiquer avec l'automate par ModBus.

La définition de WagoML comporte les spécifications des éléments (tags) xml utilisés dans ce fichier. Deux pages sur ce site pour réaliser un fichier de ce type :

Un Maker sans modbus est disponible : WagoMLMaker pour automate
Un Maker complet spécifique modbus : WagoMLMaker pour iPhone

WagoML 1.0 : début du fichier

Un fichier WagoML débute par les lignes suivantes :

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wagoml PUBLIC "-//wagoml org//DTD WAGOML 1.0//EN" 
"http://pautex.fr/wago/DTD/WagoML-1.0.dtd">
<wagoml version="1.0" xmlns="http://pautex.fr/wago/">

WagoML 1.0 : Liste des éléments

Les élements suivant sont utilisés (pas de traduction possible):

wagoml : Root, élément racine du fichier xml
- title : Titre général
- refresh : Temps de refresh des pages en ms, par défaut 2000ms
- items : Conteneur global niveau simple 1 seul écran de présentation
  - item : Chaque variable en lecture est décrite dans un block item. Un attribut "id" est ajouté pour indiquer l'ordre d'affichage, il sera numérique et débute à 0, exemple id="0"
    - ref : référence (pour enregistrement)
    - title : Titre local (non affiché)
    - pin : code PIN de l'item, numérique (pour certain objet)
    - email : email pour un envoi de valeur de la cellule.
    - display : | none | block | not | indique si affichage est à faire
    - name : Nom affiché, représentatif pour l'utilisateur
    - description : texte libre représentatif (origine de la data, etc ...)
    - type : Indique comment convertir : | direct | lineaire | varian | log11 | xml | json | text |
    - text : Liste de substitution : text1,text2,text3... sur type="text" ou XPATH pour type="xml"
    - unit : Unité °C, °F, V, A, Torr etc..., sera placé après la valeur numérique affichée
    - coef : multiplicateur de la valeur entrante
    - offset : Ajouté à la valeur uniquement après le multiplieur
    - format : Format du nombre affiché (défaut = %.1f)
    - minimum : utilisé pour certains objets, slider, wheel, moyenneur, et time pour "pulse"
    - maximum : Valeur maximum pour un slider ou wheel
    - IW : Valeur lue directement du PLC par SSI si supporté.
    - affichage : button, push, pulse, volet, switch, slider, date, text, time, light, door, shutter, lock, water, portal, fan, heater, wheel, bar, image, video,iframe, room, url, key. Affichage = text par défaut
    - iframedelegate ref de la cellule iframe cible.
    - height : Hauteur de la cellule de l'iFrame
    - link : URL d'action en "GET"
    - wagolink : URL d'action en "POST" (prioritaire)
    - url : URL d'un fichier local ou des data en relecture
    - user : user pour transactions sécurisés avec url
    - password : password pour url si nécessaire
    - IP : IP PLC ou dispositif pour lecture ou écriture Modbus (port 502)
    - unitID : unit logique Modbus (défaut = 0)
    - IB : variable Modbus en lecture = adresse décimale ou le nom IEC1131
    - OB : variable ModBus en écriture = adresse décimale ou le nom IEC1131
- rooms : (PLCLink only) Conteneur de cloisonnement des items.
  - setting Réglages pour la liste
    - title : Titre des settings
    - name : Nom des settings
    - modbuslog : Nom du fichier de log modbus en .csv, il sera global si présent
    - mbsynchrone : défaut = 0; 0 ou 1 si transaction synchrone en modbus
  - room : Attribut "id" et débute à 0
    - title : Nom de la room
    - refresh : Temps de refresh de room en ms, par défaut 2000ms
    - pin : code PIN de la room, numérique
    - modbuslog : Nom du fichier de log modbus pour cette room, utiliser un format .csv
    - record : Nom du fichier d'enregistrement, sera un .csv compatible Excel
    - items : conteneur global dans une room
      - item : Attribute id = n débute à zéro
        
        ref etc... comme "item" ci dessus

Notes :

- Un item est un block autonome, il comporte le titre de la variable, sa valeur et sa représentation sur l'iPhone, celle-ci est souvent issue d'un calcul pour la mise à l'échelle de la variable. L'item comporte aussi un lien de retour pour une action (souvent une écriture).
- Une Room est une organisation logique des items.

Exemple de fichier WagoMl

Un fichier texte à charger dans l'automate dans le dossier "/webserv" via une connexion FTP sur l'automate :
Fichier disponible sur le lien suivant pour test : http://pautex.fr/wago/automat.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wagoml PUBLIC "-//wagoml//DTD WAGOML 1.0//EN" 
"http://pautex.fr/wago/DTD/WagoML-1.0.dtd">
<wagoml version="1.0">
  <items>
	<item id="0">
		<title>Test</title>
		<name>Température</name>
		<description>IW1</description>
		<type>lineaire</type>
		<unit>°C</unit>
		<coef>0.00793481</coef>
		<offset>-200</offset>
		<IW><!--#READPI ADR=IW1&FORMAT=%d--></IW>
	</item>
    <item id="1">
		<title>Test</title>
		<name>Lampe</name>
		<description>QX0</description>
		<type>direct</type>
		<coef>1</coef>
		<offset>0</offset>
		<IW><!--#READPI ADR=QX0.0&FORMAT=%d--></IW>
	</item>
  </items>
</wagoml>

Est indiqué, dans la balise "IW" la syntaxe de remplacement de l'automate lors d'un appel de ce fichier, à voir les détails dans la documentation wago. Est affiché la température, étiquette "Température" du tag <name>, la variable est dans le tag <IW> en texte, elle represente un nombre (WORD).
Le calcul est une équation linéaire t = ax+b avec a = 0.00793481 indiqué dans le tag : <coef>,
le terme b = -200 indiqué dans le tag <offset>
L'unité sera derrière la valeur indiquée est ici : °C dans <unit>. La plage de mesure est définie sur le module d'entrée de l'automate par l'intégrateur du dispositif.

DTD de WagoML 1.0

Le fichier de DTD 1.0 est le suivant :

<!--
  Document type declaration : wagoml
  Pautex JF 10/2009-2010
  adresse du doc : http://pautex.fr/wago/DTD/WagoML-1.0.dtd
-->

<!-- wagoml : root element of any WagoMl document -->
<!ELEMENT wagoml (title?, refresh?, items?, rooms?)>
<!ATTLIST wagoml version CDATA #FIXED '1.0'>
<!ATTLIST wagoml xmlns CDATA #IMPLIED>
<!ATTLIST wagoml xmlns:xml CDATA #IMPLIED>

<!-- rooms  -->
<!ELEMENT rooms  (setting?,room*)>
<!ELEMENT room   (title, refresh?,pin?,modbuslog?,record?, items)>

<!-- items  -->
<!ELEMENT refresh (#PCDATA)>
<!ELEMENT items   (title?, item*)>
<!ELEMENT setting (title, name, modbuslog?, mbsynchrone?)>

<!-- item  -->
<!ELEMENT item  (ref?, title, pin?, email?, display?, name, description?, 
type?, text?,unit?, coef?, offset?, format?, minimum?, maximum?,
IW?, affichage?, iframedelegate?, height?, link?, wagolink?, url?, user?, password?,IP?,unitID?,IB?,OB?)>

<!ATTLIST item id CDATA #REQUIRED>
<!ATTLIST room id CDATA #REQUIRED>


<!-- elements de item  -->
<!ELEMENT ref  (#PCDATA)>
<!ELEMENT title  (#PCDATA)>
<!ELEMENT display  (#PCDATA)>
<!ELEMENT name  (#PCDATA)>
<!ELEMENT description  (#PCDATA)>
<!ELEMENT type  ( #PCDATA )>
<!ELEMENT text  ( #PCDATA )>
<!ELEMENT unit  (#PCDATA)>
<!ELEMENT coef  (#PCDATA)>
<!ELEMENT offset  (#PCDATA)>
<!ELEMENT format  (#PCDATA)>
<!ELEMENT minimum  (#PCDATA)>
<!ELEMENT maximum  (#PCDATA)>
<!ELEMENT IW  (#PCDATA)>
<!ELEMENT affichage  (#PCDATA)>
<!ELEMENT link  (#PCDATA)>
<!ELEMENT wagolink  (#PCDATA)>
<!ELEMENT url  (#PCDATA)>
<!ELEMENT user  (#PCDATA)>
<!ELEMENT password  (#PCDATA)>
<!ELEMENT IB  (#PCDATA)>
<!ELEMENT IP  (#PCDATA)>
<!ELEMENT OB  (#PCDATA)>
<!ELEMENT unitID  (#PCDATA)>
<!ELEMENT pin  (#PCDATA)>
<!ELEMENT modbuslog  (#PCDATA)>
<!ELEMENT record  (#PCDATA)>
<!ELEMENT mbsynchrone  (#PCDATA)>
<!ELEMENT email  (#PCDATA)>
<!ELEMENT height  (#PCDATA)>
<!ELEMENT iframedelegate  (#PCDATA)>

Il est possible de tester la validité du fichier WagoMl sur un validateur exemple : ici pour le fichier test
Le lien teste le fichier de démonstration.

Les élements en détails

1 - Elément <wagoml>

nom : wagoml
fonction : Element racine d'un fichier de type WagoML
type : texte
occurrence : unique
parents : aucun
attributs :
nom : version type : texte
nom : xmlns type : texte
nom : xmlns:xml type : texte

2 - Elément <title>

nom : title
fonction : Titre du fichier, titre de la mesure apparition non définie
type : texte
occurrence : simple, éventuelle
parents : wagoml, setting, item, room
attributs : aucun

3 - Elément <items>

nom : items
fonction : Conteneur des éléments item
type : texte
occurrence : simple
parents : wagoml
enfants : item
attributs : aucun

4 - Elément <item>

nom : item
fonction : Délimite un block pour affichage d'une information
type : texte
occurrence : multiple
parents : items
enfants : ref, title, display, name, description, type, unit, coef, offset, minimum, maximum, IW, link, affichage, wagolink
attributs : nom : id type : numérique, donne l'ordre d'affichage débute à zéro

5 - Elément <ref>

nom : ref
fonction : Référence de cette mesure.
type : texte
occurrence : simple éventuelle
parents : item
attributs : aucun

Pour enregistrement, unique

6 - Elément <title>

nom : title
fonction : Titre de la source
type : texte
occurrence : simple
parents : item
attributs : aucun

7 - Elément <display>

nom : display
fonction : | block | none | not | Mode d'affichage de la source, block par défaut.
type : texte
occurrence : simple, éventuelle
parents : item
attributs : aucun

8 - Elément <name>

nom : name
fonction : Nom de la variable, sera affichée avant la valeur
type : texte
occurrence : simple
parents : item
attributs : aucun

9 - Elément <description>

nom : description
fonction : Nom et description de la variable SSI pour un READPI sur automate, pour mémoire
type : texte
occurrence : simple
parents : item
attributs : aucun

10 - Elément <type>

Si type = "direct" par défaut, pas de transformation.
Si type = "lineaire" la valeur est transformé par équation y = <coef> * x + <offset>
Si type = "text"; fera la substitution de la variable par un élément de la liste des textes, voir balise 21 : <text>
Si type = "xml"; le fichier reçu est en xml, <text> est le XPATH d'accès à la variable.
Si type = "json" le fichier reçu est en JSON et <text> est un équivalent du XPATH d'accès à la variable. (v 1.6.2)

11 - Elément <unit>

nom : unit
fonction : Unité ajoutée après la mesure par exemple : °C, A, V etc...
type : texte
occurrence : simple
parents : item
attributs : aucun

12 - Elément <coef>

nom : coef
fonction : Coef multiplicateur de la mesure si besoin, mesure de type : lineaire
type : Valeur numérique du coef
occurrence : simple éventuelle
parents :
attributs : aucun

13 - Elément <offset>

nom : offset
fonction : Offset de la mesure sera ajouté si besoin, mesure de type : lineaire
type : valeur numérique de l'offset.
occurrence : simple éventuelle
parents : item
attributs : aucun

14 - Elément <format>

nom : format
fonction : format numérique d'affichage par exp %.2f pour les flottants. La format par défaut est : "%.1f"
type : texte
occurrence : simple éventuelle
parents : item
attributs : aucun

Sera appliqué avant représentation d'une valeur, pour limiter le nombre de chiffres significatifs.

%f : float et contrôle des décimales exp avec format = "%.2f" donne : 1,12
%x : hexadécimal exemple : 0xEB10

15 - Elément <minimum>

nom : minimum
fonction : Valeur minimum du slider si défini dans affichage
type : Entier numérique
occurrence : simple éventuelle
parents : item
attributs : aucun

Sera appliqué visible sur un slider à sa gauche.

16 - Elément <maximum>

nom : maximum
fonction : Valeur maximum du slider si ce type est défini dans affichage
type : Entier numérique
occurrence : simple éventuelle
parents : item
attributs : aucun

Sera appliqué et visible à droite du slider.

17 - Elément <IW>

nom : IW
fonction : Mesure directe remplacée par l'automate via une commande SSI READPI
type : texte
occurrence : simple
parents : item
attributs : aucun
C'est un élément important, la variable sera indiquée par l'automate via une commande SSI placée ici, exemple :
- Lecture du mot (W) entrée 0 <IW></IW>
- Lecture une sortie Byte (B) out 0.0 <IW></IW>

NOTE : Il ne faut pas utiliser l'écriture & sur cette commande, elle est typiquement pour l'automate et non destinée à un transfert sur Internet, étant dans un commentaire, la validité du fichier XML est préservé.

18 - Elément <affichage>

19 - Elément <link>

nom : link
fonction : Lien url éventuel vers le serveur pour exécution d'une fonction sur un serveur, pour button, switch, slider
type : texte
occurrence : simple éventuelle
parents : item
attributs : aucun

Lien vers le serveur que le bouton, le switch ou le slider fera sur activation, le lien débute par : http://... et sera toujours en mode "GET".
Le lien assurera que le fonction du bouton sera faite.
Dans ce lien, placer une variable sous la forme ( ....php?variable=%d ), la valeur "%d" (entier numérique) sera ajouté par l'application avant exécution.
l'expression "%d" dans le lien fixe indique un remplacement à faire par la nouvelle valeur.

Note 1 : Pour un slider

%d est remplacé par la valeur entière du curseur avec formulation inversé x = (y-b)/a
%f est remplacé par la valeur en float et calcul inverse comme %d
%c est remplacé par la valeur directe du curseur 4 décimales : %c -> 0.1564 par exemple.

La syntaxe de l'url du <link> est libre contrairement à la syntaxe de <wagolink> plus bas. Typiquement vous envoyez une commande vers une page du serveur qui est responsable de l'exécution de la commande via une programmation php.

Note 2 :

Dans tous les cas les paramètres seront passés en "GET".
Cette balise n'est pas prioritaire devant la suivante <wagolink> qui sera seule activée si elle est présente.
Plus de détails sur cette page : link ou wagolink ?

20 - Elément <wagolink>

nom : wagolink
fonction : Lien url éventuel vers automate pour exécution d'une fonction sur automate, pour button et slider et switch, prioritaire sur <link>
type : texte
occurrence : simple éventuelle
parents : item
attributs : aucun

Lien que le bouton, le switch ou le slider fera (http://) vers l'automate en mode "POST" (comme le formulaire). Ce type est prioritaire sur <link>
Placer une URL complète comme pour un formulaire de l'automate. la valeur "%d" entier numérique sera placée par l'application compatible avant exécution.
l'expression "%d" dans le lien indique un remplacement à faire par une nouvelle valeur.

Exemple : <wagolink>http://193.168.10.10/WRITEPI?ADR1=MW0&VALUE1=%d&FORMAT1=%d </wagolink>

Note 1 : La syntaxe des paramètres : ADR1=, VALUE1=, FORMAT1= est imposé par le plug-in SSI WAGO.

L'url commence par http://
Eviter de copier-coller les éléments de cette page, des éléments invisibles sont probablement présent.
l'url est complète mais ne peut en aucun cas être testé sur un navigateur. Réalisez un test sur un formulaire dans le serveur de l'automate.
Ici les paramètres seront passés en "POST" dans tout les cas.

La syntaxe est plus rigide que le "link" ci dessus puisque les paramètres sont obligatoires.
C'est un lien vers l'automate, pour un pseudo formulaire sur la méthode "WRITEPI", est spécifié ainsi la variable de l'automate à modifier et la valeur de la variable (%d) qui indique au remplaceur ou placer la nouvelle valeur (VALUE1=%d). Cette nouvelle valeur est l'état du switch "1" ou "0" ou la valeur d'un slider (nombre entier).

ATTENTION : former correctement l'url (écriture du symbole & = & en particulier).

Note 2 : Le mode de passage des paramètres en "POST" n'empêche pas de pointer vers un serveur autre que l'automate visé.
- Plus de détails sur le site de WagoLink.

21 - Elément <text>

nom : text
fonction : Liste des textes de substitution pour une variable entière ou XPATH d'une variable.
type : texte
occurrence : simple
parents : item
attributs : aucun

Liste de textes uniquement pour le type = "text" et affichage = "text", les items sont séparés par une simple virgule. Le premier item à pour indice la valeur "0".
Il fera la substitution de la variable entrante par un des texte de la liste.
exemple : <text>Arrêt,Marche,Erreur</text>, si "IW" = 1 alors il affichera "Marche"

22 - Elément <refresh>

nom : refresh
fonction : temps en ms du refresh de la page, par défaut 2000ms
type : numérique
occurrence : simple
parents : wagoml
attributs : aucun

23 - Elément <rooms>

nom : rooms
fonction : Réalise un cloisonnement des infos sur le même automate
occurrence : simple éventuelle
parents : wagoml
enfants : room
attributs : aucun

24 - Elément <room>

nom : room
fonction : conteneur des "item" descripteurs, title est le titre de la room
occurrence : multiple
parents : rooms
enfants : title, pin, modbuslog, record, item
attributs : nom : "id", type : numérique débute à zéro

25 - Elément <IP>

nom : IP
fonction : IP du dispositif à commander par transfert ModBus
type : texte
occurrence : unique
parents : item
enfants : aucun
attributs : non

26 - Elément <unitID>

nom : unitID
fonction : Unit logique dans le transfert ModBus
type : texte
occurrence : unique
parents : item
enfants : aucun
attributs : non

unitID est presque toujours 0 si vous avez 1 unité Modbus.
Ne pas confondre avec le port Ethernet modbus qui est toujours 502

27 - Elément <IB>

nom : IB
fonction : Nom variable ModBus en lecture ou adresse décimale
type : texte
occurrence : unique
parents : item
enfants : aucun
attributs : non

28 - Elément <OB>

nom : OB
fonction : Nom de variable ModBus en écriture ou adresse décimale
type : texte
occurrence : unique
parents : item
enfants : aucun
attributs : non

29 - Elément <pin>

nom : pin
fonction : Code PIN de blocage d'une room ou d'un item
type : numérique
occurrence : unique
parents : room ou item
enfants : aucun
attributs : non

Certains items peuvent être protégés par un code PIN.

30 - Elément <modbuslog>

nom : modbuslog
fonction : Nom du fichier des log modbus sera en csv type ";" séparateur
type : texte
occurrence : unique
parents : room, setting
enfants : aucun
attributs : non

heure et data sur le modbus en fichier csv, permet de retrouver une éventuelle panne.

31 - Elément <record>

nom : record
fonction : Nom du fichier d'enregistrement de la room, sera un csv type ";" séparateur
type : texte
occurrence : unique
parents : room
enfants : aucun
attributs : non

32 - Elément <setting>

nom : setting
fonction : Réglages de transfert de fichier
occurrence : unique
parents : rooms
enfants : title, name, modbuslog, mbsynchrone
attributs : non

33 - Elément <mbsynchrone>

nom : mbsynchrone
fonction : 1 pour transfert synchrone modbus (sur Schneider)
occurrence : unique
parents : setting
enfants : aucun
attributs : non

contact : Pautex JF