Einstellungen auf dem Data Layer

Data Layer

LumiScan Cam Driver bietet seine Funktionen auf dem Data Layer unter hdvisionsystems/lumiscan-cam-driver an.

Auf ctrlX OS (ctrlX CORE oder ctrlX IPC) nutzt LumiScan Cam Driver den ctrlX Data Layer.

Auf einem PC mit Windows 11 oder Ubuntu 24.04 nutzt LumiScan Cam Driver LumiScan Keryx.

Knotenadressen, Typen und Aufrufmuster sind auf beiden gleich. LumiScan Cam Driver bietet:

Wie Adressen aufgebaut sind, wie Funktionen aufgerufen werden, die Statuscodes und die Werkzeuge sind in LumiScan Keryx beschrieben.

LumiScan Cam Driver zeigt die Einstellungen, mit denen er gestartet wurde, auf dem Data Layer an, auf hdvisionsystems/lumiscan-cam-driver/system/settings. Sie können sie dort ohne Zugriff auf den Konfigurationsordner lesen und dort ändern: Die Anwendung prüft eine Änderung, speichert sie in ihren Einstellungsdateien und verlangt einen Neustart. hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute startet sie neu.

Für einen Überblick über den Knoten system in allen LumiScan-Apps siehe Einstellungen, Module und Neustart.

Was der Knoten zeigt

settings enthält ein JSON-Dokument, als Text:

  • die Anwendungs-Einstellungsdatei lumiscan-cam-driver.json, wie sie gelesen wurde;

  • in ihrer Liste modules den Inhalt jeder Modulkonfigurationsdatei anstelle des Dateinamens. "$file" nennt die Datei, aus der jedes Modul stammt;

  • eine Moduldatei, die nicht gelesen werden konnte, erscheint als {"$file": ..., "$error": ...}, wobei "$error" den Grund nennt. Das ist auch der Grund, warum das Modul nicht gestartet ist;

  • jeder Wert mit dem Namen password wird als "***" angezeigt.

Zum Beispiel:

{
  "$schema": "schemas/lumiscan-cam-driver.schema.json",
  "meta": { ... },
  "modules": [
    {
      "$file": "lumiscan-cam-driver-example-module.json",
      "$schema": "schemas/lumiscan-cam-driver-module.schema.json",
      "id": "camera1",
      "serial": "simulation",
      "exposureTimeUS": 6000,
      ...
    }
  ],
  "system": { ... }
}

Kommentare in den Dateien werden nicht angezeigt.

Der Knoten zeigt die Dateien so, wie die Anwendung sie beim Start gelesen hat. Der Cam Driver liest seine Dateien nur beim Start.

Die Einstellungen ändern

Lesen Sie settings, ändern Sie, was Sie benötigen, und schreiben Sie das gesamte Dokument zurück. Dabei gelten diese Regeln:

  • Jedes Modul behält sein "$file". Es muss eine der Moduldateien der Anwendung benennen: Ein Modul kann hier nicht hinzugefügt werden. Wie Sie eines hinzufügen, siehe Module hinzufügen und entfernen.

  • Ein Modul, das in modules weggelassen wird, ist in lumiscan-cam-driver.json nicht mehr aufgeführt. Seine Datei bleibt, wo sie ist.

  • "***" als Passwort behält das Passwort, das die Datei enthält. Jeder andere Wert ersetzt es.

  • Eine Datei, deren Inhalt sich nicht ändert, wird nicht geschrieben. Eine geänderte Datei wird nur dort geändert, wo sich ihr Inhalt geändert hat: Kommentare und Layout bleiben erhalten. Ein neuer Schlüssel oder ein neues Listenelement kommt hinter das letzte vorhandene; ein entfernter Schlüssel verschwindet mit seiner Zeile, einschließlich eines Kommentars in dieser Zeile. Nur ein Objekt, das sowohl Schlüssel gewonnen als auch verloren hat, oder eine Liste, die ein Element verloren hat, wird neu geschrieben, ohne die Kommentare darin. Die vorherige Datei bleibt daneben als <file>.bak erhalten.

  • Ein Schlüssel wie "_comment" ist Inhalt wie jeder andere, wird also angezeigt und behalten.

Die Anwendung prüft die Änderung, bevor etwas geschrieben wird: Die Anwendungs-Einstellungsdatei und jede geänderte Kamera-Einstellungsdatei müssen sich als die Einstellungen lesen lassen, für die sie stehen, mit den richtigen Namen und Typen. Ob die Kamera gefunden werden kann oder einen Wert annimmt, zeigt sich erst beim nächsten Start. Eine Änderung, die die Prüfung ablehnt oder die kein gültiges JSON ist, wird mit DL_INVALID_VALUE (ctrlX Data Layer) oder Rejected (LumiScan Keryx) beantwortet. Der Grund steht im Protokoll, und nichts wird geschrieben.

Eine Änderung, die nichts schreibt, antwortet mit DL_OK und ändert nichts.

Neustart erforderlich

Eine gespeicherte Änderung wirkt erst beim nächsten Start. Bis dahin läuft die Anwendung mit Einstellungen, die nicht mehr die ihrer Dateien sind, und stellt deshalb ihre Arbeit ein:

  • hdvisionsystems/lumiscan-cam-driver/system/restart-required ist true;

  • hdvisionsystems/lumiscan-cam-driver/system/status-text nennt die geänderten Dateien;

  • jedes Modul meldet Status -5 (restartRequired). Es beantwortet keinen Request, und seine ready-Signale sind false;

  • jede execute-Methode eines Moduls antwortet mit DL_RESOURCE_UNAVAILABLE. Das schließt reset ein, das sonst einen Teil der neuen Einstellungen laden würde;

  • ein laufender Bild-Stream stoppt.

Nur ein Neustart beendet diesen Zustand. Ein Reset nicht. Das Protokoll enthält die Meldung auf Fehlerebene.

Weitere Änderungen sind in der Zwischenzeit möglich. Nach einer Änderung zeigt settings die Dateien, wie sie gespeichert sind - das, was der nächste Start lädt, nicht das, womit die Anwendung läuft.

Konnte eine Datei nicht gespeichert werden, antwortet der Schreibvorgang mit DL_CREATION_FAILED. Davor geänderte Dateien bleiben geändert, sodass die Anwendung trotzdem einen Neustart benötigt. Korrigieren Sie die Dateien, und starten Sie dann neu.

Module hinzufügen und entfernen

Drei Methoden von hdvisionsystems/lumiscan-cam-driver/system verwalten Module, jede unter control/<method>/, wie auch control/restart. Jede nimmt die ID des Moduls, den Namen seiner Datei ohne .json, in control/<method>/input/module-id entgegen:

Methode Was sie tut

create-module

Schreibt die Moduldatei <module-id>.json mit dem JSON aus control/create-module/input/content. Die Anwendung prüft es so, wie sie eine geänderte Moduldatei prüft. Das Modul ist noch nicht aktiv, es muss also nichts neu gestartet werden. Eine vorhandene Datei wird nicht überschrieben: Ändern Sie sie über settings.

activate-module

Fügt <module-id>.json, die vorhanden sein muss, der Liste modules hinzu, nachdem die Anwendung das Modul geprüft hat. Es läuft ab dem nächsten Start, die Anwendung benötigt dann also einen Neustart (siehe Neustart erforderlich).

deactivate-module

Nimmt <module-id>.json aus der Liste modules. Die Datei bleibt erhalten, sodass activate-module sie wieder aufnehmen kann. Es stoppt mit dem nächsten Start, die Anwendung benötigt dann also einen Neustart.

Jede Methode meldet auf control/<method>/output/status-code und control/<method>/output/status-text:

Code Bedeutung

1

Erledigt.

-2

Die Eingabe oder das Modul wurde abgelehnt: status-text nennt den Grund. Nichts wurde geschrieben.

-6

Eine Datei konnte nicht geschrieben werden.

-9

activate-module: Es gibt keine solche Datei. deactivate-module: Das Modul ist nicht aktiv.

-10

create-module: Die Datei existiert bereits. activate-module: Das Modul ist bereits aktiv.

Die Methode antwortet mit DL_OK, wenn sie erledigt ist, mit DL_INVALID_VALUE, wenn sie abgelehnt hat, und mit DL_CREATION_FAILED, wenn eine Datei nicht geschrieben werden konnte (Namen des ctrlX Data Layer; LumiScan Keryx antwortet mit Ok, Rejected und CreationFailed, siehe Ergebnisse eines Methodenaufrufs). Um zum Beispiel das Modul camera2 hinzuzufügen:

  1. Schreiben Sie das JSON des Moduls auf hdvisionsystems/lumiscan-cam-driver/system/control/create-module/input/content und camera2 auf control/create-module/input/module-id, und rufen Sie dann control/create-module/execute auf.

  2. Schreiben Sie camera2 auf control/activate-module/input/module-id, und rufen Sie dann control/activate-module/execute auf.

  3. Rufen Sie hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute auf.

Die Anwendung neu starten

hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute beendet die Anwendung und startet sie erneut. Sie liest ihre Einstellungsdateien neu ein, wodurch auch von Hand an den Dateien vorgenommene Änderungen wirksam werden, und beendet restart-required.

  • Auf ctrlX OS: Die Anwendung wird beendet, und ctrlX OS startet sie nach etwa fünf Sekunden erneut.

  • Auf einem PC: Die Anwendung startet sich selbst erneut, sobald sie alles freigegeben hat, was sie belegt hatte. Sie verwendet dasselbe Programm, dieselben Argumente und denselben Arbeitsordner. Es ist ein neuer Prozess in derselben Konsole, und seine Ausgabe geht dorthin, wohin die des ersten ging.

Die Methode antwortet mit DL_OK, sobald der Neustart begonnen hat. Die Knoten der Anwendung verschwinden dann, bis sie wieder läuft: Warten Sie, bis hdvisionsystems/lumiscan-cam-driver/system/restart-required wieder gelesen werden kann.

Ein Neustart ist nicht an eine Änderung gebunden. Er startet auch eine Anwendung neu, deren Einstellungen sich nicht geändert haben.

JSON-Schemas

Die Anwendung legt die JSON-Schemas ihrer Einstellungsdateien in ihrem Ordner schemas ab; diese Kopien passen immer zur installierten Version. Die Schemas von LumiScan Cam Driver 2.2.1 stehen außerdem zum Download bereit: JSON-Schemas von LumiScan Cam Driver 2.2.1.

Damit ein Editor wie Visual Studio Code eine Kopie einer Einstellungsdatei prüft, die Sie auf Ihrem PC bearbeiten, lassen Sie deren Eintrag $schema auf das veröffentlichte Schema zeigen:

{
  "$schema": "https://docs.hdvisionsystems.com/schemas/lumiscan-cam-driver/2.2.1/lumiscan-cam-driver.schema.json",
  ...
}

Lassen Sie den Eintrag $schema der Dateien auf dem Gerät so, wie die Anwendung ihn geschrieben hat.