Gira X1 – eigene Logikbausteine erstellen – profff

Voraussetzungen

Um für den Gira X1 eigene Logikbausteine zu erstellen, benötigt man zunächst folgenden Dinge:

Microsoft Visual Studio 2022 – mit Unterstützung für C#
Das Gira X1/L1 Logikbaustein SDK – kommt mit Beispielen, einer Anleitung und einem Template (der Download funktioniert z.Zt. unter Chrome nicht).
Zum Testen den Gira Projekt Assistenten in der aktuellen Version
Um die entwickelten Bausteine auch auf einen X1 oder L1 spielen zu können, benötigt man zusätzlich ein Entwicklerzertifikat, welches von Gira signiert werden muss. Zertifikat und spätere Signierung erstellt man am besten mit dem X Certificate and Key Management; das genaue Vorgehen ist in der Anleitung zum SDK beschrieben und beinhaltet das Senden einer E-Mail an Gira (und ggf. das Warten auf eine Antwort).

Meine ersten Schritte habe ich anhand der im SDK mitgelieferten Beispiele unternommen. Spätestens, wenn man etwas tatsächlich auf dem X1/L1 installieren möchte, muss man sich aber mit dem Entwickler-Zertifikat und dem entsprechenden Namespace auseinandersetzen. Ich selbst habe mir neben der Dokumentation (oben) auch dieses Video angesehen. Um aus dem mitgelieferten Beispiel-Projekt ein eigenes zu machen, muss man an ein paar Schrauben drehen:

Zertifikat erhalten – und nun?

Nachdem man von Gira die Mail mit dem Zertifikat erhalten hat, muss man es wieder durch das o.a. Tool jagen und erhält dann ein Zertifikat mit Endung .pfx – früher .p12. Das von Gira versendete Zertifikat hat auch einen Namen, der i.d.R. auf die (ebenfalls von Gira vergebene) Developer-ID lautet. Bei mir ist das flx_de. Diese ID müssen wir an mehreren Stellen einfügen – sie bestimmt maßgeblich den Namespace und trägt zur eindeutigen Identifizierung der entwickelten Module bei.

Developer-ID und Namespace in Manifest.json

In der Manifest.json-Datei müssen wir die neue Develover-ID bei DeveloperId eintragen – bei mir flx_de. Außerdem muss Assembly mit DeveloperId.logic beginnen; also im meinem Fall flx_de.logic.

ACHTUNG: Hier war auch einer meiner Fehler, der mich viel Zeit gekostet hat: Es reicht nicht, das Assembly DeveloperId.logic.dll zu nennen. Der Validator meckert dann und macht nicht weiter – aus den Fehlermeldungen ist allerdings nicht zu erkennen, warum. Fakt ist, es muss auch noch was zwischen DeveloperId.logic und .dll stehen – dann klappts auch. Deshalb habe ich der Einfachheit halber hier ein .a eingefügt; Assembly heißt bei mir nun flx_de.logic.a.dll.

Im weiteren Verlauf müssen auch vollständigen Klassennamen der Bausteine mit DeveloperId.logic. beginnen, um die Eindeutigkeit zu gewährleisten. Und zwar sowohl in der Manifest.json (unter "Type") als auch in den einzelnen Bausteinen am Anfang unter namespace – da steht bei mir dann jeweils namespace flx_de.logic.a.

csproj-Datei

Meine Projekt-Datei heißt flxNodes.csproj – ich habe sie von ExampleNodes.csproj umbenannt, was auch nicht ganz problemlos ist, da in dieser Datei auch der RootNamespace und der AssemblyName drinsteht. Dieses ist ebenfalls nach dem o.a. Schema anzupassen und sieht bei mir dann so aus.

<RootNamespace>flx_de.logic.a</RootNamespace>
<AssemblyName>flx_de.logic.a</AssemblyName>
Nun klappt auch das Kompilieren.

PackageID

Ich habe noch keine Ahnung, wie ich das mit der PackageID richtig mache. Es klappt aber gerade alles, weswegen ich das jetzt nicht weiter anfasse.

Kompilieren

Zum Kompilieren kann man am einfachsten in Projektmappen-Explorer (oben rechts in der Standardansicht) mit der rechten Maustaste auf das aktive Projekt klicken und neu erstellen auswählen. Wenn alles klappt bekommt man keine Fehlermeldung sondern lediglich den Hinweis, dass die erstellte ZIP-Datei nicht signiert ist und somit nicht auf echter Hardware lauffähig ist.

Signieren

Zum Signieren der gerade erstellten ZIP-Datei muss das Kommandozeilen-Tool SignLogicNodes.exe aufgerufen werden – und zwar mit 3 Parametern:

Pfad (absolut oder relativ) zum pfx-Zertifikat
passendes Passwort zum Zertifikat (hat man selbst gewählt)
Pfad zur zu signierenden ZIP-Datei.

SignLogicNodes.exe liegt bei mir im Verzeichnis LogicNodesSDK – was bei mir zu folgendem Aufruf führt (relative Pfade zu Zertifikat und ZIP-Datei), wobei PASSWORD hier durch das tatsächliche Passwort ersetzt werden muss:
SignLogicNodes.exe ..\..\Felix.pfx PASSWORD ..\Zip\flx_de.logic.a-1.0.12.zip

In Gira Projekt Assistent (GPA) laden

Das entsprechende Projekt aufmachen und dort bei den Logikblättern importieren. Falls das nicht klappt, hat man wahrscheinlich noch alten Ballast in der ZIP-Datei mitgeschleppt: Am besten einmal alles unter \bin löschen und das Projekt neu erstellen.

Updates und Versionierung

Niemand verlangt, dass die Dinge sofort funktionieren – aber niemand will auch nachher 12 Million verschiedene Bausteine im GPA haben. Damit der GPA die einzelnen Bausteine updaten kann, behalten sie denselben namespace und i.d.R. auch denselben Namen. Was sich ändern muss, damit der GPA auch Korrekturen und Erweiterungen an den Bausteinen zulässt, ist die Versionsnummer "Version" in der Manifest.json – und zwar aufsteigend. Sprich: Hier wird (an beliebiger Stelle) nach oben gezählt. Im Beispiel hat die Manifest.json die Version 1.0.12. Gültige nächste Versionsnummern wären z.B. 1.0.13, 1.0.4711 oder auch 1.2.0 oder 2.0.0 oder was auch immer. Hier gilt: Vorwärts immer, rückwärts nimmer… 🙂

Logikbausteine aus dem GPA rausschmeißen

Wenn man z. B. mal einen Logikbaustein erdacht hat, der partout nicht funktionieren will oder sonst was falsch hat, sodass man diesen endgültig wieder aus dem GPA rausschmeißen möchte, kann man das folgendermaßen tun:

Sicherstellen, dass der störende Bausteine aus allen Logikblättern gelöscht wurde.
In das Verzeichnis C:\ProgramData\Gira\Gira Project Assistant\LogicNodes wechseln.
Dort gibt es ein Verzeichnis, das so heißt, wie der Namespace, dort sind die einzelnen Nodes in allen jemals importierten Version vorhanden. Wenn man sich das einfach machen will: Dieses Verzeichnis (bei mir flx_de.logic.a) löschen.
Im GPA die bereinigte/korrekte Version wieder importieren.

Icons erstellen und einfügen

Icons sollten im png-Format vorliegen. Standardmäßig sind sie 44 x 44 Pixel groß und haben einen transparenten Hintergrund. Es bietet sich an, sie im /icons-Unterverzeichnis abzulegen. Allerdings werden sie (bei mir?) beim Kompilieren nicht standardmäßig auch in die erstellte ZIP-Datei kopiert, sodass ich sie händisch in die ZIP-Datei kopieren muss. In der Manifest.json muss dann für jeden Block angegeben werden, welches Icon verwendet werden soll: "DefaultIcon": "icons/Delay_ms.png".

{
  "PackageFormatVersion": "1.0",
  "Assembly": "flx_de.logic.a.dll",
  "PackageName": {
    "en": "Logic Nodes A (flx.de)",
    "de": "Logikbausteine A (flx.de)"
  },
  "DependentFiles": [
    "LogicModule.Nodes.Helpers.dll"
  ],
  "Version": "1.0.12",
  "Author": "Felix Büsching",
  "Copyright": "flx.de (2022)",
  "DeveloperId": "flx_de",
  "License": "Free",
  "PackageId": "9E684D86-F645-4D1D-8EA1-CA7DF9FBBD23",
  "Nodes": [
      {
      "Type": "flx_de.logic.a.Delay_ms",
      "Name": {
        "en": "Timer (Delay in Milliseconds)",
        "de": "Timer (Verzögerung in Millisekunden)"
      },
      "IsConverter": false,
      "Category": "Node",
      "DefaultIcon": "icons/Delay_ms.png",
      "HelpTooltip": {
        "en": "Delay Telegrams in Milliseconds.",
        "de": "Verzögert Telegramme (Millisekunden)"
      },
      "HelpFileReference": null
    },
  ]
}