HSL2.0 - XML-Definitionsdatei
Inhalt
1.
Einleitung
2.
Aufbau der XML-Definitionsdatei
3.
Beispiel einer XML-Definitionsdatei
Beschreibung der XML-Definitionsdatei

## 1.Einleitung

Die XML-Definitionsdatei legt die grundlegenden Eigenschaften von HSL-2.0 Logikbausteinen fest:

- Name, ID, Kategorie (zur Verwaltung im Experten und zur Anzeige im GLE)
- Kontext
- Anzahl, Bezeichnungen und Typen von Ein- und Ausgängen
- Anzahl und Bezeichnungen von remanenten Variablen
- Framework- und Standardmodule, die importiert werden müssen
- Art des Logging

Aus dieser XML-Definitionsdatei erzeugt der HSL 2.0-Generator im ersten Schritt eine Python-Datei. Diese enthält eine Python-Klasse, die vom Entwickler ergänzt und ausprogrammiert werden muss. Mit Hilfe der Python-Datei und der XML-Definitionsdatei kann der HSL 2.0-Generator dann den fertigen Logikbaustein (.hsl-Datei) erzeugen.

## 2.Aufbau der XML-Definitionsdatei

    <?xml version="1.0" encoding="UTF-8"?>
    <config>
       <modules>
          <module category="" context="" id="" name="" version="">

             <inputs>
                <input type="" init_value="" const_name="">E_BEZ</input>
             </inputs>

             <outputs>
                <output type="" init_value="" const_name="">A_BEZ</output>
             </outputs>

             <remanent_variables>
                <remanent_variable type="" init_value="" const_name="">V_BEZ</remanent_variable>
             </remanent_variables>

             <imports>
                <import>M_NAME</import>
             </imports>

             <translations>
                <translation language="XX" name="" category="">
                   <translation_inputs>
                      <translation_input>E_BEZ_IN_SPRACHE_XX</translation_input>
                   </translation_inputs>
                   <translation_outputs>
                      <translation_output>A_BEZ_IN_SPRACHE_XX</translation_output>
                   </translation_outputs>
                </translation>
             </translations>

          </module>
       </modules>
       <logging type="" ip="" port="" />
    </config>

- <config>
  Container.
- <modules>
  Enthält alle Logik-Baustein-Definitionen des Projekts. Beliebig viele Bausteine können hier definiert werden.
- <module>
  Definition eines einzelnen Logik-Bausteins.
  - category
    Baustein-Kategorie für den GLE (Grafischer Logikeditor) im HS/FS Experte.
  - context
    Kontext, in dem der Baustein definiert ist. Siehe auch: Threading.
  - id
    ID des Bausteins
  - name, internal_name, external_name
    - internal_name:
      Name der Python-Klasse. Wird auch für den Namen der Baustein-Datei (.hsl) verwendet. (Sollte keine Umlaute enthalten)
    - external_name:
      Name im GLE (Grafischer Logik-Editor des Experten)
    - name:
      Wird verwendet, falls external_name und/oder internal_name nicht angegeben sind. (Sollte keine Umlaute enthalten)
  - version
    Versionsbezeichnung des Bausteins
- <inputs>
  Enthält alle Eingänge eines Logikbausteins
- <input> Definiert einen einzelnen Eingang eines Logikbausteins
  - type
    Eingangstyp: number, string, destination_port oder base_path.
    - number: Numerischer Wert.
    - string: Alphanumerischer Wert / Zeichenkette.
      Hinweis
      Bei Fixtexten, die auf dem Eingang eines Logikbausteins liegen, wird das Encoding "iso-8859-1" verwendet.
    - destination_port: Port, an dem der Baustein lauschen muss, wenn er von aussen über den Basis-Pfad erreicht werden soll. Nähere Erläuterungen siehe hier.
    - base_path: Basis-Pfad, über den alle Aufrufe an den Baustein weitergeleitet werden. Wird der HomeServer URL angehangen. Nähere Erläuterungen siehe hier.
      Hinweis
      Die Eingangstypen destination_port und base_path dürfen pro Baustein nur in jeweils einem Eingang verwendet werden. Besitzt ein Eingang den Typ destination_port, muss auch ein Eingang mit dem Typ base_path existieren und umgekehrt.
  - init_value
    Wert, mit dem der Eingang initialisiert wird. Der Generator prüft bei Eingängen vom Typ number, ob das angegebene init_value gültig ist.
    Beispiel (number): `init_value="5"`
    Beispiel (string): `init_value="abc"`
  - const_name
    (optional) Bezeichnung der Konstanten für diesen Eingang im Python-Skript. Ist const_name nicht angegeben, wird stattdessen E_BEZ verwendet.
  - E_BEZ
    Bezeichnung des Eingangs. Wird im GLE angezeigt.
- <outputs>
  Enthält alle Ausgänge eines Logikbausteins
  Hinweis
  Mindestens ein Ausgang muss angelegt werden!
- <output>
  Definiert einen einzelnen Ausgang eines Logikbausteins.
  - type
    Ausgangstyp: number oder string.
  - init_value
    Wert, mit dem der Ausgang initialisiert wird. Der Generator prüft bei Ausgängen vom Typ number, ob das angegebene init_value gültig ist.
    Beispiel (number): `init_value="5"`
    Beispiel (string): `init_value="abc"`
  - const_name
    (optional) Bezeichnung der Konstanten für diesen Ausgang im Python-Skript. Ist const_name nicht angegeben, wird stattdessen A_BEZ verwendet.
  - A_BEZ
    Bezeichnung des Ausgangs. Wird im GLE angezeigt.
- <remanent_variables>
  Enthält alle remanenten Variablen eines Logikbausteins
- <remanent_variable>
  Definiert eine einzelne remanente Variable
  - type
    Typ der remanenten Variable: number oder string.
  - init_value
    (optional) Wert, mit dem die remanente Variable initialisiert wird. Der Generator prüft bei remanenten Variablen vom Typ number, ob das angegebene init_value gültig ist.
  - const_name
    (optional) Bezeichnung der Remanenten Variablen im Python-Skript. Ist const_name nicht angegeben, wird stattdessen V_BEZ verwendet.
  - V_BEZ
    Bezeichnung der Variablen.
- <imports>
  Enthält alle Import-Anweisungen für Framework-Module oder Verzeichnis- / ZIP-Archiv-Namen von externen Bibliotheken, die vom Baustein genutzt werden sollen.
- <import>
  Definiert einen einzelnen Modul-Import
  Hinweis
  Es handelt sich bei hierbei nicht um Logikbausteine, sondern um Module, die dem Framework beiliegen (z.B. Intervall-Timer) oder um nicht im Standardumfang von Python enthaltene Bibliotheken!
- M_NAME
  Absoluter oder relativer Pfad zu einem Verzeichnis oder einem ZIP-Archiv, oder der Name eines Framework-Moduls.
  - Verzeichnis:
    Das Verzeichnis repräsentiert eine einzelne Bibliothek, deren Name dem des Verzeichnisses entspricht (z.B. `C:\Python27\Lib\site-packages\websocket`).
  - ZIP-Archiv:
    Das ZIP-Archiv kann mehrere Verzeichnisse wie das zuvor beschriebene enthalten, und/oder einzelne Python-Dateien.
  - Framwork-Modul:
    Name eines Framework Moduls (z.B. `hsl20_4_timer`).
  - Für die Verwendung von Imports siehe auch: Code-Beispiel "EasterDate".
    Hinweis
    In der '.py'-Datei müssen im oberen nicht vom Generator überschriebenen Bereich Python 'Import'-Statements verwendet werden, um auf interne oder externe Bibliotheken zugreifen zu können.
    'Import'-Statements innerhalb von Methoden, bzw. zur Laufzeit, funktionieren nur bei Python Standard-Modulen (z.B. import math)!
- <translations>
  Enthält alle im GLE sichtbaren Texte des Bausteins. Pro Sprache muss eine translation Anweisung angegeben werden.
  Sind die Texte in der eingestellten Sprache nicht vorhanden, verwendet der Experte die bei den module, input und output Tags definierten Texte.
- <translation>
  Definiert die Texte eines Bausteins für eine Sprache.
  - language
    Sprachkürzel. Gültig sind alle Sprachen, die der Experte unterstützt. Momentan sind das:
    - de (Deutsch)
    - en (Englisch)
    - fr (Französisch)
    - it (Italienisch)
  - name
    Anzeige-Name im GLE in Sprache language für den Baustein.
  - category
    Name und Pfad in Sprache language, unter dem der Baustein im Kontext-Menü des GLE angezeigt werden soll.
- <translation_inputs>
  Entält die Namen für alle Eingänge des Bausteins.
- <translation_input>
  Entält den Namen in Sprache language für einen Eingang des Bausteins. Für jeden im Baustein definierten Eingang (<input>) muss, in derselben Reihenfolge, ein translation_input Element angelegt werden.
- <translation_outputs>
  Entält die Namen für alle Ausgänge des Bausteins.
- <translation_output>
  Entält den Namen in Sprache language für einen Ausgang des Bausteins. Für jeden im Baustein definierten Ausgang (<output>) muss, in derselben Reihenfolge, ein translation_output Element angelegt werden.
- <logging>
  Optional. Definiert den Logging-Server und die Art des Loggings.
  - typ
    Logging-Typ. Ist entweder Syslog oder None (Kein Logging)
  - ip
    Nur bei Logging-Typ Syslog. IP-Adresse des Syslog-Servers
  - port
    Nur bei Logging-Typ Syslog. Port des Syslog-Servers. Standard ist 514.

## 3.Beispiel einer XML-Definitionsdatei

    01 <?xml version="1.0" encoding="UTF-8"?>
    02 <config>
    03   <modules>
    04     <module category="Blind-Shutter-Partition Wall" context="JALOUSIE" id="19015" name="Storm shutter control " version="v1.0">
    05       <inputs>
    06         <input type="number">Long-term (1 bit; 1=close, 0=open)</input>
    07         <input type="number">Short-term (1 bit)</input>
    08         <input type="number">Measured movement time for Leaf 1 in seconds</input>
    09         <input type="number">Measured movement time for Leaf 2 in seconds</input>
    10       </inputs>
    11       <outputs>
    12         <output type="number">Long-term object (1 bit) Leaf 1</output>
    13         <output type="number">Short-term object (1 bit) Leaf 1</output>
    14         <output type="number">Long-term object (1 bit) Leaf 2</output>
    15         <output type="number">Short-term object (1 bit) Leaf 2</output>
    16       </outputs>
    17       <remanent_variables>
    18         <remanent_variable>Movement time for Leaf 1</remanent_variable>
    19         <remanent_variable>Movement time for Leaf 1</remanent_variable>
    20         <remanent_variable>Condition of Leaf</remanent_variable>
    21       </remanent_variables>
    22       <imports>
    23         <import>hsl20_4_timer</import>
    24       </imports>
    25       <translations>
    26         <translation language="de" name="Schlagladensteuerung" category="Jalousie-Rollladen-Trennwand">
    27           <translation_inputs>
    28             <translation_input>Eingang 1 (1 Bit; 0=öffnen/1=schließen)</translation_input>
    29             <translation_input>Stop/Kurzzeit (1Bit)</translation_input>
    30             <translation_input>Fahrzeit Flügel 1 (sek.)</translation_input>
    31             <translation_input>Fahrzeit Flügel 2 (sek.)</translation_input>
    32           </translation_inputs>
    33           <translation_outputs>
    34             <translation_output>Flügel 1 (Langzeit)</translation_output>
    35             <translation_output>Flügel 1 (Kurzzeit)</translation_output>
    36             <translation_output>Flügel 2 (Langzeit)</translation_output>
    37             <translation_output>Flügel 2 (Kurzzeit)</translation_output>
    38           </translation_outputs>
    39         </translation>
    40       </translations>
    41     </module>
    42   </modules>
    43   <logging type="Syslog" ip="192.168.123.45" port="514" />
    44 </config>

In der Definition des Bausteins wird die englische Sprache verwendet und es gibt eine Übersetzung für die Sprache Deutsch.
Das bedeutet, dass bei Einstellung der Sprache "Deutsch" für den HS/FS Experte dieser Baustein im GLE in deutsch angezeigt wird.
Bei Verwendung einer beliebigen anderen Spracheinstellung im HS/FS Experte wird der Baustein im GLE in Englisch angezeigt, da dies die Standard-Einstellung ist.