Eigene Werkzeuge erstellen

Der TwinCAT Building Automation Manager bietet die Möglichkeit eigene Werkzeuge (AddIns) zu erstellen. AddIns haben die Möglichkeit über ein Objektmodel auf die interne Datenhaltung des TwinCAT Building Automation Managers zuzugreifen. Diese Zugriffe können lesend, sowie schreibend erfolgen. Somit können AddIns erstellt werden, mit denen eine Dokumentation der Anlage automatisch generiert werden kann. Ebenfalls realisierbar sind AddIns zum Einlesen von Dateien (z.B. Exeldateien) aus denen die Projektdatei erzeugt wird. Besonders von Bedeutung ist die Möglichkeit ganze Bedieneroberflächen zu generieren.

Die nachfolgenden Ausführungen zeigen alle notwendigen Schritte auf, um eine Grundlage für die eigentliche AddIn Entwicklung zu schaffen. Das vollständige Microsoft Visual Studio 2010 Projekt steht am Ende der Seite im Downloadbereich zur Verfügung.

Voraussetzungen

Microsoft Visual Studio 2010 (oder höher)
Microsoft .NET Framework 4.0 (oder höher)
Kenntnisse in der Programmiersprache C#

Projekt erstellen

Starten Sie das Microsoft Visual Studio 2010 und legen Sie ein neues Projekt an. Das Projekt muss vom Typ Class Library sein.

Entfernen Sie die standardmäßig erstellte Class1.cs Datei im Solution Explorer und fügen Sie dem Projekt eine neue Windows Form hinzu. Markieren Sie die neu hinzugefügte Form1.cs Datei und öffnen Sie die Code Ansicht. Der zu sehende Quelltext sollte nun wie folgt aussehen:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;

namespace Sample
{
    public partial class Form1 : Form
    {
    public Form1()
    {
        InitializeComponent();
    }
    }
}

Referenzen hinzufügen

Der nächste Schritt umfasst das Hinzufügen von drei Referenzen.

System.ComponentModel.Composition: Stellt die benötigten Attribute ExportMetadata und Export bereit.
TcBAManager.AddIn: Bietet Zugriff auf Klassen, die zur Arbeit mit dem TwinCAT Building Automation Manager notwendig sind.
TcBAManager.AddIn.Contract: Schnittstellen und Aufzählungstypen die das AddIn dem TwinCAT Building Automation Manager zur Verfügung stellen.

Rechtsklicken Sie im Solution Explorer auf References und wählen Add Reference... aus. Im neu geöffneten Fenster wählen Sie den .NET Tab aus und suchen nun die Referenz System.ComponentModel.Composition. Ein Doppelklick fügt sie zum Projekt hinzu.

Als nächstes folgen die Referenzen vom TwinCAT Building Automation Manager. Dazu betätigen Sie den Browse Tab und navigieren in das TwinCAT Building Automation Manager Verzeichnis (standardmäßig C:\TwinCAT\BAFrameworkV2.20\BAManager). Dort befinden sich die TcBAManager.AddIn.dll und die TcBAManager.AddIn.Contract.dll. Fügen Sie beide dem Projekt hinzu. Das Fenster kann nun geschlossen werden.

Bereitstellung

Damit das AddIn im TwinCAT Building Automation Manager zur Verfügung steht und korrekt angezeigt werden kann, sind ein paar Erweiterungen im Quelltext der Form1.cs Datei notwendig.

Beginnen Sie mit der Erweiterung der Namensräume. Es kommen System.ComponentModel.Composition, TwinCAT.BAManager.AddIns.Model und TwinCAT.BAManager.AddIns.Contract hinzu.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using System.ComponentModel.Composition;
using TwinCAT.BAManager.AddIns.Model;
using TwinCAT.BAManager.AddIns.Contract;

namespace Sample
{
    public partial class Form1 : Form
    {
    public Form1()
    {
        InitializeComponent();
    }
    }
}

Erweitern Sie nun den Konstruktor um die Schnittstellen IAddInContractV1 und IDisposable. Anschließend folgen die Attribute über die zusätzlichen Informationen innerhalb des TwinCAT Building Automation Managers zur Verfügung gestellt werden.

Dazu gehören der Anzeigename und die Beschreibung in der entsprechenden Sprache, die Versionsnummer und der AddIn Typ. Dieser legt den Anzeigeort des AddIns beim Menüpunkt Werkzeuge innerhalb des TwinCAT Building Automation Managers fest.

Die Angabe beim Attribut Export dient dem TwinCAT Building Automation Manager zur Identifikation gültiger AddIns.

Nun muss noch die Schnittstelle IAddInContractV1 implementiert und die globale Variable der Klasse Project angelegt und initialisiert werden.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;
using System.ComponentModel.Composition;
using TwinCAT.BAManager.AddIns.Model;
using TwinCAT.BAManager.AddIns.Contract;

namespace Sample
{
    [ExportMetadata("Name1031", "Beispiel")]
    [ExportMetadata("Name1033", "Sample")]
    [ExportMetadata("Description1031", "Ein Beispielprogramm.")]
    [ExportMetadata("Description1033", "A sample program.")]
    [ExportMetadata("Version", "V1.0.0")]
    [ExportMetadata("Target", AddInTarget.Extension)]
    [Export(typeof(IAddInContractV1))]
    public partial class Form1 : Form, IAddInContractV1, IDisposable
    {
    
    private Project project;
        
    public Form1()
    {
        InitializeComponent();
        project = Project.Instance;
    }
        
    public Form AddInUserControl
    {
        get
        {
        return this;
        }
    }
    }
}

Die Instanz der Klasse Project bietet jetzt den Zugriff auf alle vom TwinCAT Building Automation Manager zur Verfügung gestellten Funktionen und Informationen.

Da es sich bei diesem Projekt um eine Klassenbibliothek handelt, müssen Sie zum Starten und Debuggen vorher noch in den Eigenschaften des Projekts ein externes Programm definieren mit dem das AddIn gestartet werden soll. Gehen Sie dazu in den Solution Explorer und rufen Sie mit einem Rechtsklick auf das Projekt die Properties auf. Im Menüpunkt Debug tragen Sie bei Start external program den Pfad zum TwinCAT Building Automation Manager ein.

Wechseln Sie zum Menüpunkt Build und tragen Sie im Bereich Output den Pfad zum AddIn Ordner des TwinCAT Building Automation Managers ein (standardmäßig C:\TwinCAT\BAFrameworkV2.20\BAManager\AddIns). Die Eigenschaften können nun geschlossen werden.

Zum Schluss muss noch verhindert werden, dass der gesamte TwinCAT Building Automation Manager beim Kompilieren in den AddIn Ordner kopiert wird. Hierfür gehen Sie in den Solution Explorer und erweitern den Ordner References. Öffnen Sie mit einem Rechtsklick die Eigenschaften der Referenz TcBAManager.AddIn und setzen Copy Local auf false. Wiederholen Sie diesen Vorgang für die Referenz TcBAManager.AddIn.Contract.

Informationen und Funktionen der Schnittstelle

Das Abfragen oder Setzen einfacher Informationen von Objekten, wie z.B. Name oder Kommentar, erfolgt über die Eigenschaften. Komplexere Informationen, wie z.B. Verlinkungen oder belegte Klemmenkanäle, stehen als XML Dokument zur Verfügung und können mit der Methode GetParameters( ) abgefragt bzw. mit SetParameters( ) gesetzt werden. Die Struktur zum Setzen von Parametern entspricht dabei exakt der gelieferten Struktur von GetParameters( ).

Des Weiteren können auch Meldungen in das Meldungsfenster des TwinCAT Building Automation Managers abgesetzt werden.

Einen ausführlichen Einblick in die Funktionen und den Aufbau liefert das angehängte Projekt AddIns.Test im Downloadbereich.

Anwendungs Snippets

Für die nachfolgenden Snippets dient das Projekt aus den vorherigen Schritten als Grundlage.

Snippet 1 - Szenen auslesen

Erstellen Sie mit dem TwinCAT Building Automation Manager ein neues Projekt und fügen Sie diesem einen beliebigen Controller mit mindestens vier Szenen und Lampen hinzu. Die erste Szene erhält ein Kommando, dass die erste Lampe einschaltet. Wiederholen Sie diesen Vorgang für die anderen Szenen.

foreach (Controller controller in project.Controllers)
{
    var scenes = from scene in controller.Scenes
         where (scene.Id % 2) == 0
         select scene;
    Debug.WriteLine("Controller {0}: {1} ", controller.Id, controller.Name);
    foreach (Scene scene in scenes)
    {
    XmlDocument doc = scene.GetParameters();
    Debug.WriteLine("  Scene {0}: {1}", scene.Id, scene.Name);
    }
}

Nach Aufruf des AddIns werden alle Szenen des Controllers, deren Id durch zwei teilbar ist, einer neuen Liste übergeben und anschließend in die Debug Konsole ausgegeben.

Die Methode GetParameters( ) liefert den Szeneninhalt in folgender XML Struktur:

‹?xml version="1.0" encoding="utf-16" ?›
‹Scene Id="2"›
    ‹ExternalImplementation›false‹/ExternalImplementation› 
    ‹SumUpScenes›false‹/SumUpScenes› 
    ‹SceneItem›
    ‹EntityControllerId›1‹/EntityControllerId›
    ‹EntityType›ActuatorLampBase‹/EntityType›
    ‹EntityId›2‹/EntityId›
    ‹EntityCommandId›3‹/EntityCommandId›
    ‹/SceneItem›
‹/Scene›

Snippet 2 - Projekt erstellen

project.CreateNew("Sample");

Controller controllerCX1010 = project.Controllers.Add(5);
controllerCX1010.Name = "My CX1010";

FieldBusDevice fieldBusDeviceCX1010 = controllerCX1010.FieldBusDevices.Add(1);
FieldBusCoupler fieldBusCouplerCX1010 = fieldBusDeviceCX1010.FieldBusCouplers.Add(4);

Terminal terminalKL2012 = fieldBusCouplerCX1010.Terminals.Add(project.TerminalDescriptions["2012_0"]);
terminalKL2012.Name = "My KL2012";

Lamp lampType1 = controllerCX1010.Lamps.Add(1);
lampType1.Name = "My Lamp";

XmlDocument doc = new XmlDocument();
doc.LoadXml(@"
    ‹Lamp›
    ‹Link›
        ‹LinkChannelId›0‹/LinkChannelId› 
        ‹BusDeviceId›1‹/BusDeviceId› 
        ‹BusCouplerId›1‹/BusCouplerId› 
        ‹TerminalId›1‹/TerminalId› 
        ‹ChannelId›1‹/ChannelId› 
        ‹ControllerId›1‹/ControllerId› 
    ‹/Link›
    ‹/Lamp›
");

lampType1.SetParameters(doc);

Hier wird ein neues Projekt mit Controller, Feldbusgerät, Feldbuskoppler, Klemme und Lampe erzeugt. Nach Erstellung der Parameter zum Verlinken der Lampe mit dem ersten Klemmenkanal wird die XML Struktur mit der Methode SetParameters( ) der Lampe übergeben.

Einen ausführlichen Einblick in die XML Struktur der jeweiligen Elemente liefert das Projekt AddIns.Test im Downloadbereich.

Schließen Sie das AddIn und den AddIn Auswahldialog. Das neu erzeugte Projekt erscheint jetzt im Navigationsbaum.

Downloadbereich

Projektvorlage für die AddIn Entwicklung.

Sample

Projekt das Funktionen und Aufbau der Schnittstelle aufzeigt.

AddIns.Test