Erstellen eines PlugIns

Transkript

1 Erstellen eines PlugIns Mai 2013

2 Inhaltsverzeichnis Inhaltsverzeichnis Inhaltsverzeichnis Einleitung Ablauf Weitere Dokumentation Wichtige Hinweise Beschreibung PlugIn-Designer starten Neues Projekt Projekteinstellungen eingeben Beschreibung ausfüllen Templates Grundlagen MalConfiguration MalSystem MalPacket Hierarchie Tabs Grundlagen Konfigurationstab Quellcode Codegenerierung Programmierung des Messteils MalPacket MalSystem MalConfiguration Programmierung des Konfigurationsteils Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 2/ 18

3 Einleitung 1 Einleitung Ein PlugIn ist ein Softwaremodul, das von IPEmotion erkannt und eingebunden werden kann, um Daten anzuzeigen, auszugeben oder zu verändern. Dadurch ist es möglich, jede Hardware, die mit dem Computer verbunden und über Treiber ansprechbar ist, in IPEmotion einzubinden. So können zum Beispiel Messdaten von verschiedensten Messgeräten zeitsynchron mit einer Software erfasst und anschließend ausgewertet werden. 1.1 Ablauf Ein PlugIn wird in zwei Schritten erstellt. Zuerst legt man die Struktur und die Konfigurationsmöglichkeiten im PlugIn-Designer an. Diese lassen sich dann bereits in IPEmotion überprüfen, ohne dass eine Messung bzw. Speicherung ausgeführt wird. Ist dieser Teil abgeschlossen, kann ein Codegerüst erstellt und in der Entwicklungsumgebung vervollständigt werden. In diesem Dokument wird die Erstellung eines PlugIns für IPEmotion anhand eines einfachen Beispiels erläutert. Ziel ist es, zwei Kanäle in IPEmotion zu erzeugen, die die Position des Mauszeigers als x- und y- Koordinate anzeigen. 1.2 Weitere Dokumentation Eine genaue Beschreibung der PlugIn-Schnittstelle von IPEmotion finden Sie im Programmverzeichnis, bei einer Standardinstallation unter folgendem Pfad: C:\Program Files (x86)\ipetronik\ipemotion V \MAL Als alternatives Beispiel finden Sie den Quellcode des Demo-PlugIns unter: C:\Users\Public\Documents\IPETRONIK\IPEmotion\MAL-Designer 1.3 Wichtige Hinweise Verzeichnisse Bitte beachten Sie, dass sich die Verzeichnispfade Ihrer lokalen Installation von den hier genannten unterscheiden können, besonders dann, wenn Sie eine benutzerdefinierte Installation ausgeführt haben. Installation Wählen Sie den Installationstyp Vollständig oder Benutzerdefiniert (Komponente SDK aktivieren), um den aktuellen PlugIn-Designer automatisch mit IPEmotion zu installieren. Um den PlugIn-Designer nachträglich zu installieren, starten Sie die Setupdatei Setup IPEmotion.exe erneut und wählen Sie Ändern, um den Dialog zur Auswahl der Komponenten zu öffnen. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 3/ 18

4 Beschreibung 2 Beschreibung Der aktuelle PlugIn-Designer befindet sich in der jeweiligen IPEmotion Installation, z.b. : C:\Program Files (x86)\ipetronik\ipemotion V PlugIn-Designer starten Führen Sie die Datei IPEmotion.MalDesigner.exe im oben genannten Verzeichnis der IPEmotion Installation aus. 2.2 Neues Projekt Starten Sie den PlugIn-Designer und legen Sie ein neues Projekt an. 2.3 Projekteinstellungen eingeben Die ersten Entwicklungsschritte werden mit dem Manufacturer-Code TEST durchgeführt. Dieser kann später durch einen individuellen Manufacturer-Code ersetzt werden. Der Product-Code dient zur Unterscheidung verschiedener PlugIns. So kann man mit einem Manufacturer- Code beliebig viele PlugIns erstellen. Für Ihr erstes PlugIn können Sie dann einen eigenen Produktcode vergeben. Wählen Sie zum Schluss den Ordner aus, in dem die Dateien abgelegt werden sollen. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 4/ 18

5 Beschreibung 2.4 Beschreibung ausfüllen Bei "manufacturer" steht standardmäßig Ihr Manufacturer-Code. Tragen Sie dort Ihren Firmennamen ein. Unter "symbol" laden Sie eine png-bilddatei hoch, die mit Ihrem PlugIn angezeigt werden soll. Die optimale Größe dieser Datei beträgt 32x32 Pixel. Nach erfolgreichem Laden sehen Sie unter "symbolpreview" eine Vorschau der Grafik. Der Name Ihres PlugIns wird unter "caption" eingetragen, eine kurze Beschreibung bei "description". Geben Sie dann ist die Versionsnummer bei "version" an. Wichtig für die spätere Programmierung sind die Vergabe des Namensraumes unter "codenamespace" sowie die Dateinamen (inklusive.dll) für die Messung ("acquisitionfile") und die Konfiguration ("configurationfile"). Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 5/ 18

6 Templates 3 Templates 3.1 Grundlagen Das erste Template vom Typ "MalConfiguration" ist bereits angelegt. Dieses gibt es nur einmal; es ist der Ausgangspunkt des PlugIns. Zwingend erforderlich ist, mindestens ein "MalSystem" anzulegen; auch die Anlage eines "MalPacket" wird dringend empfohlen. Ein "MalSystem" stellt die oberste Ebene dar; es können jedoch verschiedene "MalSysteme" in einem PlugIn existieren. Dabei können auch Basis-Templates angelegt und andere Templates davon abgeleitet werden. Für die Kanäle wird ein Template vom Typ "MalPacket" benötigt. Die Struktur und Anzahl der Templates zwischen System und Packet ist nicht vorgegeben und kann passend zur Hardware angelegt werden. Der zu vergebende "typename" sollte eine sinnvolle Bezeichnung sein, da dieser bei Zugriffen über die COM-Schnittstelle verwendet wird. 3.2 MalConfiguration Auch hier muss ein "symbol" zugewiesen werden, das dann in IPEmotion als PlugIn-Logo angezeigt wird. Bei der "MalConfiguration" sind "creationcaption" und "creationname" identisch und geben den Namen des PlugIns in der Hardwareauswahl von IPEmotion an. Eine kurze Beschreibung kann bei "description" angegeben werden. Danach müssen die Namen der Klassen für die Messung ("acquisitionclass") und die Konfiguration ("configurationclass") vergeben werden, wenn diese Funktionalitäten genutzt werden sollen. Diese erscheinen dann im später generierten Quellcode. Interessant ist zudem der Parameter "maxsubsystemcount", der die maximale Anzahl der in IPEmotion anlegbaren "MalSysteme" bestimmt. 3.3 MalSystem Wechselt man nun zum "MalSystem", werden die Parallelen zur "MalConfiguration" schnell ersichtlich. Auch hier sind wieder "symbol", "creationcaption", "creationname", "description", "acquisitionclass" und "configurationclass" auszufüllen. Im Reiter "PropertyList" können IPEmotion-spezifische Eigenschaften angelegt werden. Wichtig ist hier, dass die Property "SampleRate" einmal je "MalPacket" vorkommt. Diese kann für das übergeordnete "MalSystem", direkt für die einzelnen Kanälen ("MalPacket") oder für ein Template dazwischen gelten, je nachdem, ob die Hardware erlaubt, verschiedene Abtastraten für die Kanäle einzustellen. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 6/ 18

7 Templates Nach dem Hinzufügen des "MalPacket" über den Add-Button muss dieses mit dem System verknüpft werden. Dazu wählt man das entsprechende "MalSystem" aus und öffnet den Reiter "ChildList". Über den Add-Button und "ChildAtBase" werden die vorhandenen Templates angezeigt und man kann das "MalPacket" auswählen. Über "mincount", "maxcount" und "defaultcount" kann die Anzahl der Kind-Elemente (hier der einzelnen Kanäle vom Typ "MalPacket") festgelegt werden. Sind alle drei Parameter identisch, kann der Benutzer später keine Kind-Elemente löschen oder hinzufügen. So kann man eine fest vorgegebene Konfiguration für eine bestimmte Hardware erreichen. 3.4 MalPacket Das "MalPacket" stellt den Grundtypen eines Kanals dar. Da es davon üblicherweise mehrere gibt, ist es sinnvoll, diese durchzunummerieren. Dazu vergibt man bei "creationcaption" eine allgemeine Bezeichnung und trägt bei "creationname" zusätzlich eine Null in geschweiften Klammern ein. Weiterhin sind hier schon die Klassennamen für "acquisitionclass" oder "configurationclass" anzugeben, sofern diese benötigt werden. Das "MalPacket" hat ganz rechts noch zwei zusätzliche Reiter: Bei der "SensorDefinition" können Sensordaten angegeben werden. Dies ist nur notwendig, wenn der Kanal wirklich über Sensorbereiche verfügt. Die "FormatDefinition" enthält die eigentlichen Kanalinformationen. Dort werden die unterstützten Datenformate über "Add" hinzugefügt und anschließend konfiguriert. Es muss mindestens ein Format angelegt sein. Bei mehreren Formaten entspricht das oberste dem Standardformat. Die Reihenfolge kann im PlugIn-Designer über die beiden Schaltflächen "MoveUp" und "MoveDown" geändert werden. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 7/ 18

8 Templates In der "ParameterList" können für das Template eigene Variablen angelegt werden, zum Beispiel für hardwarespezifische Einstellungen. Hier stehen String, Boolean, Enumerationen und verschiedene Zahlenformate zur Auswahl. Weiterhin können an vielen Stellen Notifications gesetzt werden. Dabei vergibt man den Namen eines Events, das bei einer Aktion (zum Beispiel "selectnotification") ausgelöst wird. In den Konfigurationsklassen kann das Event dann verwendet werden. 3.5 Hierarchie MalConfiguration MalSystem MalPacket Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 8/ 18

9 Tabs 4 Tabs 4.1 Grundlagen Hardwarespezifische Dialoge, die bei der Konfiguration in IPEmotion angezeigt werden, können als Tab erstellt werden. Neben einem sinnvollen "typename" ist auch eine "caption" zu vergeben, die auf dem Reiter des Tabs angezeigt wird. Die "description" wird als Tooltip angezeigt, wenn sich der Mauszeiger über der "caption" befindet. Über eine "UiCondition" kann das Anzeigen eines Elements oder des gesamten Tabs von Variablen abhängig gemacht werden. 4.2 Konfigurationstab Nach dem Anlegen eines neuen Tabs und der Eingabe der Grundeinstellungen kann die Oberfläche gestaltet werden. Dafür stehen 14 verschiedene Elemente, unter anderem Eingabefelder und Schaltflächen, zur Verfügung, die über "Add" hinzugefügt werden können. Vor den Eingabefeldern sollte sich jeweils ein LABEL befinden, dass mit "caption" und "description" den einzugebenden Wert beschreibt. Die Elemente werden automatisch positioniert. Sollte eine Überarbeitung notwendig sein, kann die Position über "locationx" bzw. "locationy" korrigiert werden. Hinweis: Aufgrund der unterschiedlichen Sprachversionen von IPEmotion werden die LABEL per Far- Alignment ausgerichtet. Die Verknüpfung eines Eingabefelds mit dem Parameter eines Templates wird durch das Eintragen des Parameternamens in "member" erreicht. Der fertige Tab muss dann noch mit dem Template verknüpft werden, bei dem er angezeigt werden soll. Dazu wählt man das Template und dann dessen Reiter "UITabLinkList" aus. Dort erhält man über "Add" "UITabLink" eine Auswahl aller Tabs, die noch keinem Template zugewiesen wurden. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 9/ 18

10 Quellcode 5 Quellcode 5.1 Codegenerierung Wenn alle notwendigen Eingaben im PlugIn-Designer getätigt wurden, die Hierarchie der Templates vollständig ist und alle benötigten Parameter angelegt sind, sollte das PlugIn in IPEmotion geladen und überprüft werden. Dazu muss IPEmotion mitgeteilt werden, dass das PlugIn existiert und unter welchem Pfad es abgelegt ist. Diese Angaben, die später vom Setup des PlugIns gemacht werden, müssen nun manuell im Registrierungseditor von Windows (C:\Windows\regedit.exe) eingetragen werden. Unter HKEY_LOCAL_MACHINE SOFTWARE IPETRONIK IPEmotion MAL ist ein neuer Schlüssel mit der UUID des PlugIns ("typeid" im Reiter "Description") als Name zu erstellen. In einem Unterschlüssel ist dann die MAL-Definition als Name einzutragen. Dieser erhält eine Zeichenfolge mit der Versionsnummer als Name und dem Pfad des PlugIns als Wert. Ist man mit der Oberfläche und den Konfigurationsmöglichkeiten zufrieden, kann ein Quellcodegerüst erstellt werden. Erzeugt wird eine Microsoft VisualStudio 2005 Solution. Bei nachträglichen Änderungen im PlugIn- Designer muss eine neue Quellcodevorlage erzeugt werden. Alle späteren Erweiterung im PlugIn Designer müssen dann in der bestehenden Entwicklungsumgebung manuell nachgetragen werden. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 10/ 18

11 Quellcode 5.2 Programmierung des Messteils Der Messteil, also die Acquisition-Klassen, ist in C++ geschrieben, während der Konfigurationsteil in C# erstellt wird. Im Folgenden wird die Vervollständigung anhand des Beispiel-PlugIns "SystemValues" gezeigt. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 11/ 18

12 Quellcode MalPacket Zuerst werden in der Headerdatei "SystemValuesPacket.h" Funktionen und Variablen hinzugefügt, zu erkennen an den grünen Markierungen. Die Funktion "GetActualValue" bekommt hier auch eine Variable vom Typ POINT übergeben, da in diesem PlugIn das "MalSystem" mit der Hardware kommuniziert und die Daten an das "MalPacket" weitergibt. Da eine Enumeration für die Dimension verwendet wird, muss diese außerhalb der Klasse noch bekannt gemacht werden und der Typ von "m_ucdimension" angepasst werden. Auch der Konstruktor in "SystemValuesPacket.cpp" muss angepasst werden. Eine weitere Änderung erfolgt in der Funktion "ReadParameterList": Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 12/ 18

13 Quellcode Die letzte Anpassung wird in der Funktion "SetDimension" vorgenommen: Die deklarierten Funktionen werden am Ende hinzugefügt: Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 13/ 18

14 Quellcode Die Funktion "GetActualValue" berechnet den aktuellen Wert des Kanals anhand der übergebenen Variable "mousepoint". In "WriteData" wird über die Callback-Funktion der aktuelle Wert mit dem zugehörigen Zeistempel an IPEmotion übergeben. Aufgerufen werden diese Funktionen im "MalSystem". Die Callback-Funktion ist rot markiert, da in der obersten Header-Datei noch ein Eintrag fehlt, der später hinzugefügt wird (siehe Kapitel 5.2.3). Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 14/ 18

15 Quellcode MalSystem Auch hier werden zuerst wieder Deklarationen in der Headerdatei "SystemValuesSystem.h" hinzugefügt: Konstruktor und Destruktor müssen ebenfalls angepasst werden: Besonders wichtig ist nun der zyklische Datenaustausch zwischen der Hardware und IPEmotion. Wenn die Hardware einen eigenen Zeitstempel liefert, sollte dieser verwendet und in einen mit IPEmotion konformen Zeitstempel umgerechnet werden. Ist diese Möglichkeit nicht gegeben, wie in diesem Beispiel, dann sollte der interne Timer von IPEmotion verwendet werden, um Synchronizität zu gewährleisten. Dazu wird in einer vorbereitenden Funktion dem globalen Timer ein Element für das "MalSystem" hinzugefügt. Hierbei ist zwischen dem "PreTimer" und dem "PostTimer" zu unterscheiden. Der "PreTimer" wird vor Berechnungen von IPEmotion ausgeführt und ist daher für Eingänge geeignet. Mit dem "PostTimer" verhält es sich genau umgekehrt, sodass dieser für Ausgänge geeignet ist. Dadurch können Werte in einem Zyklus eingelesen, berechnet und wieder ausgegeben werden. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 15/ 18

16 Quellcode Der globale IPEmotion-Timer ruft nun zyklisch die Funktion "Timer" auf, welche wiederum die Funktion "DoTimer" ausführt. So werden in diesem Beispiel die Werte von der Hardware angefordert, und für alle aktiven und gültigen Kanäle werden die entsprechenden Funktionen des "MalPacket" aufgerufen. Die Verbindung zur Hardware könnte aber auch vom "MalPacket" ausgehen. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 16/ 18

17 Quellcode MalConfiguration Hier muss in der Headerdatei "SystemValues.h" lediglich die Callback-Funktion global bekannt gemacht werden, damit sie vom "MalPacket" verwendet werden kann. Die Funktion "PrepareAcquisition" wird durch "PrepareAcquisitionTimer" ersetzt. Dabei muss der "psystem"- Typ von "CMalSystem" auf "CmouseSystemAcquisition" geändert werden, damit die Funktion "PrepareDataThread" verwendet werden kann. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 17/ 18

18 Quellcode Zum Abschluss muss die neue Funktion noch in der Datei "SystemValues.def" aufgelistet werden. 5.3 Programmierung des Konfigurationsteils Die in Kapitel 3.4 hinzugefügte Notification soll nun zur Anpassung des physikalischen Bereichs und zur Ausgabe eines Warnhinweises genutzt werden. Dazu muss in der Datei "SystemValuesPacket.cs" eine Using-Direktive hinzugefügt und eine Funktion vervollständigt werden. Am Ende des Codes ist bereits der Rumpf einer Funktion vorbereitet, die beim Auslösen des Events aufgerufen wird. Erstellen eines PlugIns IPETRONIK GmbH & Co. KG ipetronik.com 18/ 18