# LumiScan Keryx 1.0.0.7 – complete documentation

> All pages of the LumiScan Keryx 1.0.0.7 manual (language: de) by HD Vision Systems GmbH, in navigation order. Each page starts with a level-1 heading followed by its URL; cite that URL. Manual: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/

# LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/index.html

|   |   |   |
| --- | --- | --- |
| ![Drei LumiScan-Apps, verbunden mit LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/_images/intro/step-1.svg)<br><br>**Jede App veröffentlicht ihre Knoten.** Werte, Funktionen und Ergebnisse landen in einem Baum. | ![Knotenbaum, die Adresse der Capture-Funktion hervorgehoben](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/_images/intro/step-2.svg)<br><br>**Eine Adresse für alles.** Dieselben Adressen auf ctrlX OS und am PC. | ![SPS, SCADA und ein Programm, verbunden über OPC UA](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/_images/intro/step-3.svg)<br><br>**Ihre SPS ruft sie direkt auf.** Über OPC UA, aus SCADA oder aus Ihrem eigenen Programm. |

LumiScan Keryx ist das Daten-Rückgrat der LumiScan-Apps. Jede App legt ihre Werte, Funktionen und Ergebnisse in einen Baum benannter, typisierter Knoten, und SPS, SCADA-Systeme, Testskripte und eigene Programme erreichen alles unter einer Adresse, ohne Punkt-zu-Punkt-Verdrahtung. Auf einem PC mit Windows 11 oder Ubuntu 24.04 stellt Keryx den Data Layer bereit; auf ctrlX OS nutzen die Apps den ctrlX Data Layer mit denselben Adressen und Aufrufmustern.

Die LumiScan-Vision-Apps - Cam Driver, AI Object Matching, Calibration, die Finder und die Code Reader - bieten ihre Funktionen als **Knoten eines Data Layers** an. Eine SPS, ein OPC-UA-Client oder Ihr eigenes Programm liest, schreibt und ruft diese Knoten auf, und die Apps übergeben einander über dieselben Knoten Bilder und Ergebnisse. LumiScan Cockpit liest sie, um Bilder und Ergebnisse anzuzeigen.

Dieses Handbuch beschreibt, was in jeder App gleich ist: wie Adressen aufgebaut sind, die drei Arten, eine Funktion aufzurufen, Streams, Statuscodes, Einstellungen und die Werkzeuge. Jedes Produkthandbuch beschreibt nur seine eigenen Knoten, in seiner **Data Layer Reference**, und verweist für alles Weitere hierher.

## Eine Schnittstelle, zwei Data Layer

| Die App läuft auf | Data Layer | Lesen Sie |
| --- | --- | --- |
| ctrlX OS (ctrlX CORE oder einem ctrlX IPC) | ctrlX Data Layer | [ctrlX Data Layer auf ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html) |
| einem PC mit Windows 11 oder Ubuntu 24.04 | LumiScan Keryx | [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html) |

**Knotenadressen, Knotentypen und Aufrufmuster sind auf beiden gleich.** Ein Programm, das für den einen geschrieben ist, funktioniert auch mit dem anderen; nur die Verbindung, die Werkzeuge und die Namen einiger Ergebnisse unterscheiden sich. Siehe [ctrlX Data Layer und LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/platforms.html).

> [!NOTE]
> Dieses Handbuch beschreibt die Data-Layer-Schnittstelle der kommenden Releases der Vision-Apps. Gegenüber früheren Releases sind mehrere Knoten umgezogen, ohne Alias unter der alten Adresse. Liest ein Programm, das für ein früheres Release geschrieben wurde, einen Knoten, der „not found" ist, vergleichen Sie es mit der **Data Layer Reference** der App-Version, die Sie einsetzen.

## Erste Schritte

Neu bei Keryx? Beginnen Sie mit [Was ist LumiScan Keryx?](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/what-is-keryx.html) und probieren Sie es in [Erste Schritte mit LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/getting-started.html) selbst aus. Danach:

1. Lesen Sie [Adressen und Module](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html), um zu verstehen, wo die Knoten einer App liegen.
2. Wählen Sie, wie Sie eine Funktion aufrufen: [Aufrufmuster wählen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/calling-functions.html).
3. Schlagen Sie die Knoten Ihrer App in der **Data Layer Reference** ihres Handbuchs nach.
4. Richten Sie auf einem PC den Broker ein wie in [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html) beschrieben. Um dort eine SPS oder ein SCADA-System anzubinden, verwenden Sie den [OPC UA Connector](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html).
5. Lesen Sie auf ctrlX OS [ctrlX Data Layer auf ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html): Es ist nichts einzurichten, und eine ctrlX PLC auf demselben Gerät nutzt die Knoten direkt.

Kurze Antworten: [FAQ zum Data Layer](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/faq.html). Wenn etwas nicht funktioniert: [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html).

## Die Apps auf dem Data Layer

| App | Basisadresse |
| --- | --- |
| [LumiScan Cam Driver](https://docs.hdvisionsystems.com/de/lumiscan-cam-driver/latest/index.html) | `hdvisionsystems/lumiscan-cam-driver` |
| [LumiScan AI Object Matching](https://docs.hdvisionsystems.com/de/lumiscan-ai-object-matching/latest/index.html) | `hdvisionsystems/lumiscan-ai-object-matching` |
| [LumiScan Calibration](https://docs.hdvisionsystems.com/de/lumiscan-calibration/latest/index.html) | `hdvisionsystems/lumiscan-calibration` |
| [LumiScan Template Finder](https://docs.hdvisionsystems.com/de/lumiscan-template-finder/latest/index.html) | `hdvisionsystems/lumiscan-template-finder` |
| [LumiScan Object Finder](https://docs.hdvisionsystems.com/de/lumiscan-object-finder/latest/index.html) | `hdvisionsystems/lumiscan-object-finder` |
| [LumiScan Area Detector](https://docs.hdvisionsystems.com/de/lumiscan-area-detector/latest/index.html) | `hdvisionsystems/lumiscan-area-detector` |
| [LumiScan Text Reader](https://docs.hdvisionsystems.com/de/lumiscan-text-reader/latest/index.html) | `hdvisionsystems/lumiscan-text-reader` |
| [LumiScan DMC Reader](https://docs.hdvisionsystems.com/de/lumiscan-dmc-reader/latest/index.html) | `hdvisionsystems/lumiscan-dmc-reader` |
| [LumiScan QR Code Reader](https://docs.hdvisionsystems.com/de/lumiscan-qr-code-reader/latest/index.html) | `hdvisionsystems/lumiscan-qr-code-reader` |
| [LumiScan Aztec Code Reader](https://docs.hdvisionsystems.com/de/lumiscan-aztec-code-reader/latest/index.html) | `hdvisionsystems/lumiscan-aztec-code-reader` |
| [LumiScan Barcode Reader](https://docs.hdvisionsystems.com/de/lumiscan-barcode-reader/latest/index.html) | `hdvisionsystems/lumiscan-barcode-reader` |
| [LumiScan Cockpit](https://docs.hdvisionsystems.com/de/lumiscan-cockpit/latest/index.html) | keine: Cockpit liest nur die Knoten der anderen Apps |

Die Lizenzierung ist im Handbuch [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html) beschrieben.

# Was ist LumiScan Keryx?

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/what-is-keryx.html

**LumiScan Keryx** ist das Daten-Rückgrat der LumiScan-Vision-Apps. Jede App legt ihre Werte, Funktionen und Ergebnisse in **einen Baum benannter Knoten**, und alles andere - eine SPS, ein SCADA-System, Ihr eigenes Programm, ein Testskript, die Menschen, die die Zelle in Betrieb nehmen - erreicht sie unter **einer Adresse**. Nichts wird Punkt zu Punkt verbunden.

Der Name kommt vom griechischen *kēryx*, dem Herold: dem Boten, der Nachrichten zwischen den Parteien überbringt.

**LumiScan Keryx verbindet die Apps, die Daten bereitstellen, mit allen, die sie nutzen**

```mermaid
%% LumiScan Keryx - Konzept. Mermaid rendert es im Browser; bearbeiten und Vorschau unter https://mermaid.live
flowchart LR
  subgraph users["Wer die Daten nutzt: lesen · schreiben · aufrufen · abonnieren"]
    plc["`**SPS oder SCADA**
    über den OPC UA Connector`"]
    prog["`**Ihr Programm**
    C++, Python oder OPC UA`"]
    tests["`**Skripte und Tests**
    krxclient`"]
    people["`**Menschen**
    Keryx-Seite, Cockpit`"]
  end
  keryx["`**LumiScan Keryx**
  der Broker, eine Adresse für alle:
  tcp://127.0.0.1:5555

  ein Baum benannter, typisierter Knoten:
  hdvisionsystems/lumiscan-cam-driver/camera1/...`"]
  subgraph apps["Wer sie bereitstellt: Knoten registrieren · veröffentlichen"]
    cam["`**Cam Driver**
    Kamerabilder`"]
    ai["`**AI Object Matching**
    neuronale Netze`"]
    find["`**Finder und Leser**
    Teile, Codes, Text`"]
    calib["`**Calibration**
    Pixel zu 3D`"]
    own["`**Ihre eigene Funktion**
    C++ oder Python`"]
  end
  plc & prog & tests & people <--> keryx
  keryx <--> cam & ai & find & calib & own
  class keryx key
  classDef key fill:#faf6dc,stroke:#a8961f,color:#1f2328
```

## Warum Keryx {#why}

In einem Vision-Projekt ist die Bildverarbeitung nur ein Teil der Arbeit. Der Rest ist, sie in die Maschine zu bringen: ein Handshake mit der SPS, ein Ergebnisformat, das die SPS lesen kann, eine Live-Ansicht, eine Möglichkeit herauszufinden, warum ein Teil aussortiert wurde, und Tests ohne die echte Linie. Ohne ein gemeinsames Rückgrat wird das für jedes Projekt und jeden Kunden neu gebaut.

Keryx erledigt diese Arbeit einmal, für alle LumiScan-Apps:

- Jede App bietet ihre Funktionen auf dieselbe Weise an, unter Adressen nach denselben Regeln.
- Eine SPS, ein Programm oder ein Mensch nutzt alle Apps über eine Verbindung.
- Eine zweite Kamera oder eine weitere App hinzuzufügen heißt, einen Teilnehmer mehr anzuschließen, nicht die Zelle neu zu verdrahten.

## Das Konzept {#concept}

### Ein Baum aus Knoten {#nodes}

Alles auf Keryx ist ein **Knoten** mit einer **Adresse**, geschrieben wie ein Dateipfad:

```none
hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute
```

Ein Knoten ist ein Wert (eine Zahl, ein Merker, ein Text, ein Bild), eine Funktion, die Sie aufrufen können, oder ein Ordner, der andere Knoten zusammenfasst. Jeder Knoten **beschreibt sich selbst**: was er ist, sein Typ und ob er gelesen, geschrieben, aufgerufen oder abonniert werden darf. Ein Client kann den Baum also durchsuchen und herausfinden, was eine App anbietet, ohne eine eigene Schnittstellenbeschreibung - so wie bei einem OPC-UA-Server.

Die Adressen folgen in jeder App einem Schema: `<App>/<Modul>/control/…` für die Funktionen, `input/…` für das, was Sie vor einem Aufruf schreiben, `output/…` für die Ergebnisse. Siehe [Adressen und Module](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html).

### Provider, Clients und der Broker {#participants}

| Rolle | Was sie tut |
| --- | --- |
| **Provider** | eine App, die Knoten bereitstellt: Sie registriert sie und veröffentlicht Änderungen. Cam Driver, AI Object Matching, die Finder, die Leser und Calibration sind Provider. |
| **Client** | jeder, der liest, schreibt, aufruft oder abonniert: eine SPS, Ihr Programm, `krxclient`, die Keryx-Seite, das Cockpit - und eine App, die die Ergebnisse einer anderen App nutzt. |
| **Broker** | das eine Programm, mit dem sich alle verbinden (`krxsystem`). Er hält den Baum und leitet jede Anfrage an den Provider des Knotens weiter. Auf einem PC gibt es einen Broker, unter `tcp://127.0.0.1:5555`; die erste App, die ihn braucht, startet ihn, und die Apps starten ihn neu, wenn er stoppt. |
| **Gateway** | ein Client, der den Baum über ein anderes Protokoll verfügbar macht. Der [OPC UA Connector](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html) zeigt den ganzen Baum als OPC-UA-Server, sodass jede SPS und jedes SCADA-System mit OPC-UA-Client die Apps nutzen kann. |

### Drei Arten, eine Funktion aufzurufen {#patterns}

Wie eine Funktion aufgerufen wird, hängt davon ab, wie lange sie dauert:

| Muster | Verwenden Sie es für |
| --- | --- |
| [Execute](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html) | Arbeit, die in etwa einer Sekunde erledigt ist: ein Schreibzugriff, beantwortet, wenn die Arbeit fertig ist. Beispiel: ein Bild aufnehmen. |
| [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) | Arbeit, die länger dauern kann: Der Client setzt `request`, die App antwortet über `ready` - das Muster, das jeder SPS-Programmierer kennt. Beispiel: eine Kamera verbinden. |
| [Stream](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) (experimentell) | fortlaufende Arbeit: einmal abonnieren und jedes Ergebnis erhalten. Beispiel: Jedes Kamerabild geht an AI Object Matching und jede Detektion an Ihr Programm. |

Die meisten Funktionen von Cam Driver, AI Object Matching und Calibration werden in mehr als einem Muster angeboten, mit einer Implementierung dahinter: Das Ergebnis ist dasselbe. Siehe [Aufrufmuster wählen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/calling-functions.html).

### Gleich auf ctrlX OS und auf einem PC {#platforms}

Auf einem PC mit Windows 11 oder Ubuntu 24.04 nutzen die Apps den Keryx-Broker. Auf ctrlX OS nutzen sie stattdessen den ctrlX Data Layer. **Adressen, Typen und Aufrufmuster sind auf beiden gleich**; ein SPS-Programm oder eine Anwendung, die für das eine geschrieben ist, funktioniert mit dem anderen. Siehe [ctrlX Data Layer und LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/platforms.html).

## Was es Ihnen bringt {#benefits}

### Entscheider und Projektleiter {#benefits-decision-makers}

- **Weniger Engineering je Projekt.** Die Anbindung an SPS, Live-Ansicht und Testwerkzeuge ist Teil des Produkts und wird nicht für jede Zelle neu gebaut.
- **Standardschnittstellen, keine Abhängigkeit.** Keryx folgt der Schnittstelle des ctrlX Data Layer; zur Maschine hin spricht es OPC UA; strukturierte Ergebnisse nutzen FlatBuffers, ein offenes Format mit veröffentlichtem Schema.
- **Modular.** Jede Funktion ist eine eigene App. Fügen Sie eine Kamera oder eine App hinzu oder ersetzen Sie eine, ohne die anderen anzufassen.
- **Ein Entwurf für zwei Plattformen.** Dieselben Apps und dieselbe Integration laufen auf einer ctrlX CORE und auf einem Windows- oder Linux-PC.

### SPS-Programmierer und Systemintegratoren {#benefits-plc}

- **Vertraute Muster.** Lange Operationen sind ein ready/request-Handshake, kurze ein einziger Aufruf.
- **Einfache Werte für die SPS-Logik.** Statuscodes, Zähler, Positionen und Texte sind einfache Variablen. Vollständige Ergebnisse gibt es als strukturierte Daten mit ihrem Schema.
- **Jede SPS mit OPC UA.** Auf einem PC zeigt der OPC UA Connector jeden Knoten als OPC-UA-Knoten; seine NodeId ist die Keryx-Adresse. Auf ctrlX OS liest die ctrlX PLC die Knoten direkt.
- **Apps arbeiten zusammen, ohne die SPS dazwischen.** Per Stream versorgt die Kamera AI Object Matching, und dessen Ergebnisse gehen an Calibration; die SPS liest nur das Endergebnis.

### Inbetriebnahme und Service {#benefits-commissioning}

- **Alles sehen.** Die [Keryx-Seite](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#data-layer-page) zeigt den ganzen Baum: jeden Wert, seinen Typ und seine Rechte. Werte schreiben, Funktionen aufrufen und Werte beim Ändern beobachten - ohne SPS und ohne Code zu schreiben.
- **Jedes Modul sagt, wie es ihm geht.** `control/status/code` und `control/status/text` zeigen, was die letzte Operation getan hat und warum sie fehlschlug. Siehe [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html).
- **Es läuft weiter.** Jede App ist ein eigener Prozess: Eine App, die stoppt, reißt keine andere mit. Stoppt der Broker, wird er innerhalb von Sekunden neu gestartet, und die Apps verbinden sich von selbst wieder.
- **Ergebnisse erklären sich selbst.** Jedes Stream-Ergebnis nennt die Kamera und das Bild, aus dem es stammt, die Module, die es durchlaufen hat, und die Einstellungen, die sie verwendet haben - so lässt sich ein aussortiertes Teil bis zu seinem Bild zurückverfolgen.

### Softwareentwickler {#benefits-developers}

- **Kein SDK nötig, um die Apps zu nutzen.** Jede OPC-UA-Client-Bibliothek, in jeder Sprache, erreicht jede Funktion. Für Skripte und Tests gibt es den Kommandozeilen-Client `krxclient`. Siehe [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html).
- **Jeden Schritt einzeln testen.** Rufen Sie eine Funktion einmal auf, prüfen Sie ihr Ergebnis, und verketten Sie die Schritte erst danach.
- **Selbstbeschreibend.** Durchsuchen Sie den Baum, um Knoten zu finden; die Schemas strukturierter Ergebnisse liegen im Baum selbst, unter `types/hdvisionsystems/<App>/…`.
- **Eigene Funktionen einbringen.** Algorithmen und Geräte lassen sich als eigene Provider hinzufügen, in C++ oder Python, neben den LumiScan-Apps. Fragen Sie HD Vision Systems nach dem Entwicklerpaket.

### IT und Sicherheit {#benefits-it}

- **Standardmäßig geschlossen.** Der Broker nimmt nur Verbindungen vom selben PC an (`127.0.0.1`), ebenso die Keryx-Seite. Ihn für ein Netzwerk zu öffnen, ist eine bewusste Einstellung.
- **Keine Cloud.** Keryx läuft vollständig auf der Maschine; es braucht keine Internetverbindung.
- **Kontrolle am Rand.** Der OPC UA Connector kann nur einen Teil des Baums bereitstellen und schreibgeschützt laufen. Auf ctrlX OS nutzen die Apps den ctrlX Data Layer mit der Benutzerverwaltung von ctrlX OS.

> [!IMPORTANT]
> Der Keryx-Broker und der OPC UA Connector haben derzeit **keine Authentifizierung und keine Verschlüsselung**. Betreiben Sie sie auf einem PC oder in einem getrennten, vertrauenswürdigen Maschinennetz hinter einer Firewall. Siehe [OPC UA Connector: Sicherheit](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#security).

## Gut zu wissen {#good-to-know}

- **Ein Broker je PC.** Alle Apps einer Installation nutzen denselben Broker. Mehrere Broker an verschiedenen Ports sind voneinander unabhängig; Broker auf mehreren PCs teilen sich keinen Baum.
- **Werte tragen keinen eigenen Zeitstempel.** Eine App, die einen braucht, veröffentlicht ihn in einem Knoten oder im Ergebnis.
- **Ein neuer Abonnent erhält keinen Anfangswert.** Lesen Sie den Knoten einmal, dann abonnieren Sie ihn.
- **Streams sind** in den aktuellen Versionen **experimentell**.

Mehr unter [LumiScan Keryx auf einem PC: Gut zu wissen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#limits).

## Wie es weitergeht {#next}

- Selbst ausprobieren in 30 Minuten: [Erste Schritte mit LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/getting-started.html).
- Keryx auf einem PC installieren und betreiben: [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html).
- Die Apps auf ctrlX OS nutzen: [ctrlX Data Layer auf ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html).
- Die Knoten einer App finden: [Adressen und Module](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html) und die **Data-Layer-Referenz** im Handbuch der App.
- Eine SPS anbinden: [OPC UA Connector](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html) (PC) [Eine SPS anbinden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html#connecting-a-plc) (ctrlX OS).

# Erste Schritte mit LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/getting-started.html

In dieser Anleitung probieren Sie LumiScan Keryx auf einem Windows-PC aus, ohne Kamera und ohne SPS. LumiScan Cam Driver mit einer **simulierten Kamera** stellt die Knoten bereit; Sie sind der Client - zuerst von Hand auf der Keryx-Seite, dann mit dem Kommandozeilen-Client `krxclient`, der genau so arbeitet wie eine SPS.

Am Ende haben Sie:

1. den Broker gestartet und den Baum angesehen,
2. Werte gelesen und einen geschrieben,
3. die Kamera mit einem ready/request-Handshake verbunden - von Hand und mit einem Befehl,
4. ein Bild mit einer Execute-Methode aufgenommen und das Ergebnis geprüft,
5. die Kamera wieder getrennt.

Was Sie hier lernen, gilt genauso für jede LumiScan-App, auf einem PC und auf ctrlX OS. Das Konzept erklärt [Was ist LumiScan Keryx?](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/what-is-keryx.html).

> [!NOTE]
> Diese Anleitung verwendet einen Windows-PC. Auf ctrlX OS folgen Sie [Anleitung: Mit Beispielbildern statt einer Kamera testen](https://docs.hdvisionsystems.com/de/lumiscan-cam-driver-de/latest/how-tos/test-with-example-images.html) im Handbuch des Cam Drivers: Sie verbindet eine simulierte Kamera und nimmt ein Bild in der Weboberfläche von ctrlX OS auf, deren Data-Layer-Ansicht dort leistet, was hier die Keryx-Seite leistet.

## Bevor Sie beginnen {#before-you-start}

- Ein PC mit Windows 11.
- **LumiScan Keryx** und **LumiScan Cam Driver** installiert: zuerst Keryx, jedes Installationsprogramm als Administrator. Siehe [Installation unter Windows](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#installing).
- Eine Lizenz für LumiScan Cam Driver: CodeMeter Runtime installiert und der LumiScan Key eingesteckt, siehe [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).
- Optional: ein paar PNG-Bilder, damit die simulierte Kamera in Schritt 6 etwas liefern kann.

Öffnen Sie nach der Installation ein **neues** Terminal (Eingabeaufforderung oder PowerShell), damit es die Einstellungen kennt, die das Keryx-Installationsprogramm vorgenommen hat. Wird `krxclient` nicht gefunden, starten Sie es aus dem Installationsordner von LumiScan Keryx.

> [!TIP]
> Unter Ubuntu 24.04 sind alle `krxclient`-Befehle gleich. Die Keryx-Seite und ihr Fenster gehören nur zur Windows-Installation.

## Schritt 1 - Keryx starten und die Keryx-Seite öffnen {#step-1}

1. Starten Sie **LumiScan Keryx** über das Windows-Startmenü.

   Ein Fenster mit der **Keryx-Seite** öffnet sich. Läuft noch kein Broker, startet LumiScan Keryx ihn.

2. Sehen Sie sich den Baum an. Ohne App ist er noch leer: Keryx selbst stellt keine Knoten bereit - das tun die Apps.

Dieselbe Seite ist in jedem Browser auf diesem PC unter `http://127.0.0.1:7555/` erreichbar.

**Fertig, wenn:** die Keryx-Seite zeigt, dass der Broker läuft.

## Schritt 2 - Eine App mit simulierter Kamera starten {#step-2}

Der Cam Driver schreibt Beispiel-Einstellungen mit einer simulierten Kamera. Eine Kamera, deren Seriennummer `simulation` enthält, braucht keine Hardware.

1. Schreiben Sie die Beispiel-Einstellungen in einen Arbeitsordner:
   ```shell
   lumiscan-cam-driver --generate-settings C:\work\cam-driver-settings
   ```

   Der Cam Driver schreibt `lumiscan-cam-driver.json`, die Moduldatei `lumiscan-cam-driver-example-module.json` und ihre Schemas, nennt den Ordner, aus dem er seine Einstellungen liest, und beendet sich.

2. Öffnen Sie die Moduldatei und prüfen Sie, dass `id` den Wert `camera1` und `serial` den Wert `simulation` hat. Weicht die `id` ab, verwenden Sie in allen Adressen unten Ihre `id` statt `camera1`.

3. Kopieren Sie die Dateien in den Einstellungsordner, den der Cam Driver genannt hat, standardmäßig `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver`.

4. Starten Sie den Cam Driver:
   ```shell
   lumiscan-cam-driver
   ```

   Lassen Sie das Terminal offen: Es zeigt die Meldungen des Cam Driver.

Auf der Keryx-Seite hat der Baum jetzt den Ordner `hdvisionsystems` mit `lumiscan-cam-driver` darin.

**Fertig, wenn:** `hdvisionsystems/lumiscan-cam-driver/system/found-modules` den Eintrag `camera1` enthält und der Ordner `hdvisionsystems/lumiscan-cam-driver/camera1` existiert.

## Schritt 3 - Werte lesen {#step-3}

**Auf der Keryx-Seite:** Öffnen Sie `hdvisionsystems/lumiscan-cam-driver/camera1/control/status` und wählen Sie `code`. Die Seite zeigt seinen Wert, seinen Typ und was damit getan werden darf. `0` bedeutet **bereit**.

**Mit krxclient:** Öffnen Sie ein zweites Terminal und lesen Sie denselben Knoten:

```shell
krxclient read hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code
krxclient read hdvisionsystems/lumiscan-cam-driver/camera1/control/status/text
```

`krxclient` gibt den Wert zusammen mit seinem Typ als JSON aus. Drei weitere Befehle helfen bei der Orientierung:

```shell
krxclient browse   hdvisionsystems/lumiscan-cam-driver/camera1/control
krxclient metadata hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute
krxclient tree     hdvisionsystems/lumiscan-cam-driver/camera1 --depth 2
```

`browse` listet die Kinder eines Ordners, `metadata` zeigt, was ein Knoten ist und was damit getan werden darf, `tree` gibt einen ganzen Zweig aus.

**Fertig, wenn:** `krxclient read` den Statuscode `0` zeigt.

## Schritt 4 - Einen Wert schreiben {#step-4}

Eingaben sind Knoten, die Sie schreiben, bevor Sie eine Funktion aufrufen. Schalten Sie als Beispiel die Vorschau des Kameramoduls ein, ein PNG jedes neuen Bildes:

**Auf der Keryx-Seite:** Wählen Sie `hdvisionsystems/lumiscan-cam-driver/camera1/input/preview/enable`, setzen Sie den Wert in seinem Editor auf `true` und bestätigen Sie.

**Mit krxclient:**

```shell
krxclient write hdvisionsystems/lumiscan-cam-driver/camera1/input/preview/enable true
krxclient read  hdvisionsystems/lumiscan-cam-driver/camera1/input/preview/enable
```

`krxclient write` übernimmt den Typ des aktuellen Werts des Knotens; ein Wert, der nicht zum Typ passt, wird abgelehnt, bevor etwas gesendet wird.

> [!TIP]
> Nehmen Sie die Knoten, die Sie verfolgen, in die **Beobachtungsliste** (Watch list) der Keryx-Seite auf. Sie zeigt ihre Werte, während sie sich ändern - nützlich im nächsten Schritt.

**Fertig, wenn:** `hdvisionsystems/lumiscan-cam-driver/camera1/input/preview/enable` den Wert `true` hat.

## Schritt 5 - Die Kamera mit einem Handshake verbinden {#step-5}

Das Verbinden einer Kamera kann einige Sekunden dauern, deshalb ist es ein **Handshake**: Sie und die App wechseln sich auf zwei Knoten ab, `ready` (gesetzt von der App) und `request` (gesetzt von Ihnen).

### Von Hand, auf der Keryx-Seite {#step-5-by-hand}

Nehmen Sie diese Knoten in die Beobachtungsliste auf:

- `hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/ready`
- `hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/request`
- `hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code`
- `hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected`

Dann:

1. Prüfen Sie, dass `ready` den Wert `true` hat: Die App kann die Funktion starten.
2. Setzen Sie `request` auf `true`: Sie fordern sie an.
3. Beobachten Sie, wie `ready` auf `false` wechselt: Die App hat die Anforderung gesehen. Der Statuscode zeigt `3` (wartet auf Sie).
4. Setzen Sie `request` wieder auf `false`: Sie bestätigen. Die App verbindet jetzt die Kamera.
5. Beobachten Sie, wie `is-connected` auf `true` wechselt und der Statuscode wieder `0` wird.

> [!NOTE]
> Nach einer erfolgreichen Verbindung bleibt `connect-camera/ready` auf `false` - die Kamera ist ja schon verbunden. Prüfen Sie das Ergebnis mit `is-connected`, nicht mit `ready`.

### Mit einem Befehl {#step-5-krxclient}

`krxclient handshake` führt dieselbe Abfolge so aus, wie es eine SPS tut. Um es auszuprobieren, trennen Sie die Kamera zuerst - ebenfalls ein Handshake - und verbinden sie dann wieder:

```shell
krxclient handshake hdvisionsystems/lumiscan-cam-driver/camera1/control/disconnect-camera --status hdvisionsystems/lumiscan-cam-driver/camera1/control/status
krxclient handshake hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera --status hdvisionsystems/lumiscan-cam-driver/camera1/control/status
krxclient read hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected
```

Jeder Handshake gibt am Ende Statuscode und -text aus. Mit `--trace handshake.jsonl` schreibt er jede Änderung von `ready` und des Status mit Zeitpunkt in eine Datei - ein Protokoll dessen, was die App wann getan hat.

**Fertig, wenn:** `hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected` den Wert `true` hat.

## Schritt 6 - Ein Bild mit einer Execute-Methode aufnehmen {#step-6}

Ein Bild aufzunehmen geht schnell, deshalb ist es eine **Execute-Methode**: ein Schreibzugriff, beantwortet, wenn die Arbeit erledigt ist.

```shell
krxclient read    hdvisionsystems/lumiscan-cam-driver/camera1/output/package-identifier
krxclient execute hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute
krxclient read    hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code
krxclient read    hdvisionsystems/lumiscan-cam-driver/camera1/output/package-identifier
```

Auf der Keryx-Seite hat dieselbe Methode eine Schaltfläche **Invoke**.

Prüfen Sie immer zwei Dinge:

1. **Konnte der Aufruf ausgeführt werden?** `krxclient` endet mit `0`, wenn die App den Aufruf angenommen hat, mit `1`, wenn Keryx ihn abgelehnt hat - zum Beispiel weil die Kamera nicht verbunden ist - und mit `2` bei einer Zeitüberschreitung.
2. **War er erfolgreich?** Der Statuscode ist `0`, und `output/package-identifier` ist um eins gestiegen. Das Bild liegt jetzt auf `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`, mit `width`, `height` und `pixel-type`.

> [!NOTE]
> Eine simulierte Kamera spielt die Bilder aus ihrem Speicherordner ab, eines je Aufnahme. Ist der Ordner leer, schlägt die Aufnahme fehl: Der Statuscode ist kleiner als `0`, und `control/status/text` nennt den Grund. Auch das ist eine nützliche Übung. Um Bilder zu bekommen, legen Sie ein paar PNG-Dateien in den Unterordner `camera1` des Speicherordners, den `system/storage` in `lumiscan-cam-driver.json` nennt - fügen Sie einen Speicher hinzu, wenn keiner eingetragen ist -, starten Sie den Cam Driver neu und verbinden Sie erneut. [Anleitung: Mit Beispielbildern statt einer Kamera testen](https://docs.hdvisionsystems.com/de/lumiscan-cam-driver-de/latest/how-tos/test-with-example-images.html) zeigt dasselbe auf ctrlX OS; die Einstellungen sind auf einem PC dieselben.

**Fertig, wenn:** Sie `capture/execute` aufgerufen und das Ergebnis auf `control/status/code` gelesen haben.

## Schritt 7 - Aufräumen {#step-7}

1. Trennen Sie die Kamera:
   ```shell
   krxclient handshake hdvisionsystems/lumiscan-cam-driver/camera1/control/disconnect-camera --status hdvisionsystems/lumiscan-cam-driver/camera1/control/status
   ```
2. Beenden Sie den Cam Driver mit Strg+C in seinem Terminal.

Der Broker läuft weiter; die nächste App, die Sie starten, nutzt ihn wieder.

## Was Sie getan haben {#what-you-did}

| Sie haben | Auf der Keryx-Seite | Mit krxclient - und in einer SPS oder einem Programm |
| --- | --- | --- |
| einen Wert gelesen | den Knoten wählen | `krxclient read`; eine SPS liest den OPC-UA- oder ctrlX-Data-Layer-Knoten |
| einen Wert geschrieben | der Editor des Knotens | `krxclient write`; eine SPS schreibt den Knoten |
| einen Handshake ausgeführt | `request` setzen, `ready` beobachten | `krxclient handshake`; eine SPS setzt `request` und fragt `ready` alle 50 bis 100 ms ab |
| eine Execute-Methode aufgerufen | **Invoke** | `krxclient execute`; über OPC UA ein Methodenaufruf |

## Wie es weitergeht {#next}

- Die Apps aus einer SPS nutzen: [OPC UA Connector](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html) auf einem PC [Eine SPS anbinden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html#connecting-a-plc) auf ctrlX OS.
- Jedes Bild ohne Aufruf je Bild erhalten: [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html).
- Die Regeln jedes Musters: [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) und [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html).
- Was die Statuscodes bedeuten: [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html).
- Eine vollständige Anwendung mit Kamera, Teilesuche und SPS: [Ihre erste industrielle Vision-Anwendung](https://docs.hdvisionsystems.com/de/getting-started/first-application.html).

# ctrlX Data Layer und LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/platforms.html

Auf ctrlX OS verwenden die LumiScan-Apps den **ctrlX Data Layer** von ctrlX OS. Auf einem PC mit Windows 11 oder Ubuntu 24.04 verwenden sie **LumiScan Keryx**, den Data Layer von HD Vision Systems, der dieselbe Schnittstelle bietet.

## Auf beiden gleich

- **Knotenadressen**, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/request`. Siehe [Adressen und Module](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html).
- **Knotentypen**: bool, Ganzzahlen, Gleitkommazahlen, Strings, Arrays sowie FlatBuffers für Ergebnisse und Bilder.
- **Aufrufmuster**: [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html), [Execute-Methoden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html) und [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html).
- **Modul-Statuscodes** auf `control/status/code`. Siehe [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html).

Ein Programm, das darauf aufbaut, funktioniert auf beiden Data Layern. Übersetzen Sie niemals eine Knotenadresse zwischen ihnen.

## Was sich unterscheidet

|   | ctrlX Data Layer (ctrlX OS) | LumiScan Keryx (PC) |
| --- | --- | --- |
| Bereitgestellt von | ctrlX OS | dem Broker von **LumiScan Keryx**. Eine App startet ihn, wenn keiner läuft. Siehe [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html) |
| Standardadresse | von ctrlX OS verwaltet | `tcp://127.0.0.1:5555`, nur auf diesem PC |
| Knoten von Hand ansehen | in der Weboberfläche von ctrlX OS | auf der Keryx-Seite `http://127.0.0.1:7555/`, mit **LumiScan Keryx Utilities** (Windows) und `krxclient`. Siehe [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html) |
| Eine SPS anbinden | ctrlX PLC auf demselben Gerät | über den [OPC UA Connector](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html) |
| Ergebnis eines Methodenaufrufs | `DL_OK`, `DL_INVALID_VALUE`, … | `Ok`, `Rejected`, … Siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results) |
| Einstellungsdateien einer App | über die ctrlX-Weboberfläche oder WebDAV hochgeladen, siehe das Handbuch der App | gewöhnliche Dateien auf dem PC, siehe [Speicherorte der Dateien](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files) |
| Lizenz | Siehe [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html): auf ctrlX OS eine ctrlX-Lizenz, auf einem PC der LumiScan Key |   |

## Produkthandbücher

Die Produkthandbücher geben mit den Bezeichnungen **ctrlX Data Layer** und **LumiScan Keryx** an, welchen Data Layer sie meinen. Wo sie nur „Data Layer" schreiben, gilt die Aussage für beide.

# LumiScan Keryx auf einem PC

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html

> [!NOTE]
> Auf ctrlX OS nutzen die Apps stattdessen den ctrlX Data Layer: siehe [ctrlX Data Layer auf ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html).

**LumiScan Keryx** ist der Data Layer von HD Vision Systems für PCs. Er bietet dieselbe Schnittstelle wie der ctrlX Data Layer; der Name kommt vom griechischen *kēryx*, dem Herold.

Auf einem PC tauschen die LumiScan-Apps ihre Daten über LumiScan Keryx aus. Ein Programm, der **Broker**, verbindet sie: Jede App registriert dort ihre Knoten, und jeder Client - eine andere App, Cockpit, der OPC UA Connector, Ihr Programm - liest, schreibt und ruft über ihn auf.

## Der Broker {#broker}

|   |   |
| --- | --- |
| Programm | `krxsystem`, Teil von **LumiScan Keryx** |
| Standardadresse | `tcp://127.0.0.1:5555`. Der Broker verwendet außerdem den nächsten Port, 5556, für seine Benachrichtigungen |
| Erreichbar von | nur diesem PC (`127.0.0.1`): Der Broker hat keine Authentifizierung |
| Einer pro PC | Alle Apps einer Installation verwenden denselben Broker |

**Normalerweise starten Sie den Broker nicht selbst.** Wenn eine App startet und auf diesem PC kein Broker antwortet, startet sie `krxsystem` als separaten Prozess. Mehrere gleichzeitig gestartete Apps starten einen einzigen Broker. Der Broker läuft weiter, wenn die Apps enden, und die Apps starten ihn erneut, wenn er stoppt. Provider registrieren sich von selbst erneut und Abonnements werden von selbst erneuert, sobald der Broker antwortet.

Der erste Start dauert länger: Der Broker braucht einige Sekunden, bis er antwortet. Eine App, die in dieser Zeit startet, protokolliert, dass sie auf den Broker wartet, und verbindet sich, sobald er antwortet.

Der **OPC UA Connector** ist die Ausnahme: Er startet nie einen Broker. Starten Sie ihn nach den Apps, siehe [OPC UA Connector](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html).

## Installation unter Windows {#installing}

1. Installieren Sie zuerst **LumiScan Keryx**, danach die Apps.
2. Führen Sie jedes Installationsprogramm als Administrator aus. Um dieselbe Version erneut zu installieren, deinstallieren Sie zuerst die alte: Ein Installationsprogramm akzeptiert nur eine höhere Version.
3. Öffnen Sie ein **neues** Terminal, bevor Sie eine App von der Kommandozeile starten.

Das Installationsprogramm von LumiScan Keryx setzt zwei systemweite Umgebungsvariablen, `HDV_KERYX_BROKER` und `HDV_KERYX_PAGE`. Sie teilen jeder App mit, welches Broker-Programm sie starten soll und welches Programm die Keryx-Seite anzeigt. Ein Programm oder Terminal, das bereits geöffnet war, sieht sie nicht. Ohne sie startet eine App das `krxsystem` neben ihrem eigenen Programm.

## Die Keryx-Seite {#data-layer-page}

Jeder Broker bringt eine Webseite mit, die seinen Baum zeigt: `http://127.0.0.1:7555/` für den Standard-Broker (Port des Brokers + 2000). Das Starten von **LumiScan Keryx** öffnet dieselbe Seite in einem Fenster und startet den Broker, falls keiner läuft.

- Wählen Sie einen Knoten aus, um seinen Wert, Typ und seine Berechtigungen zu sehen.
- Ein beschreibbarer Knoten hat einen Editor, eine Methode eine Schaltfläche **Invoke**.
- Eine Beobachtungsliste verfolgt Werte, während sie sich ändern.
- **Shut down broker** stoppt den Broker. Die Apps laufen weiter und warten: Sie starten ihn erst wieder, wenn Sie auf **Start broker** klicken, das LumiScan Keryx-Fenster öffnen, ein `krxsystem` von Hand starten oder den PC neu starten.

Das LumiScan Keryx-Fenster und die Keryx-Seite sind Teil der Windows-Installation.

## Die Apps starten {#start-order}

Starten Sie die Apps in beliebiger Reihenfolge. Warten Sie, bis jede App vollständig gestartet ist, bevor Sie sich auf ihre Knoten verlassen. Starten Sie den OPC UA Connector zuletzt.

Prüfen Sie den Start auf der Keryx-Seite (Windows) oder mit `krxclient tree hdvisionsystems --depth 1`: Der Baum zeigt den Ordner `hdvisionsystems` mit einem Ordner pro laufender App. Für jede App mit Modulen listet `hdvisionsystems/<app>/system/found-modules` diese auf. Ist eine Liste leer, nennt `hdvisionsystems/<app>/system/status-text` den Grund - meist eine Einstellungsdatei, die nicht geladen werden konnte, oder eine fehlende Lizenz.

Um eine App zu stoppen, drücken Sie Strg+C in ihrer Konsole. Der Broker läuft weiter.

## Speicherorte der Dateien {#files}

| Was | Wo |
| --- | --- |
| Programme | der im Installationsprogramm gewählte Installationsordner (`Program Files`) |
| Einstellungen einer App | `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\<program>\etc\<settings folder>`, oder `%APP_RESOURCE_DIR%\etc\<settings folder>`, wenn die Umgebungsvariable `APP_RESOURCE_DIR` gesetzt ist. Der Einstellungsordner jeder App ist in ihrem Handbuch genannt |
| Log, Aufzeichnungen und Einstellungen des Brokers (`broker.json`) | `C:\ProgramData\HD Vision Systems GmbH\LumiScan Keryx` |

Unter Ubuntu legt der Broker sein Log, seine Aufzeichnungen und Einstellungen in `/tmp/lumiscan-keryx` ab.

Jede App mit Einstellungen schreibt ein Beispiel davon in einen Ordner Ihrer Wahl und beendet sich:

```shell
lumiscan-cam-driver --generate-settings C:\work\cam-settings
```

Sie überschreibt nie eine Datei. Bearbeiten Sie das Beispiel, kopieren Sie es in den Einstellungsordner und starten Sie die App.

## Optionen und Umgebungsvariablen {#options}

Dieselben Optionen gelten für jede App.

| Option oder Variable | Wirkung |
| --- | --- |
| `--keryx-url <address>` | Der zu verwendende Broker. Standard `tcp://127.0.0.1:5555`. Übergeben Sie dieselbe Adresse an jede App, an Cockpit und an den OPC UA Connector |
| `LUMISCAN_KERYX_URL` | Dasselbe, für jedes Programm auf dem PC. Die Option hat Vorrang |
| `--no-keryx-autostart`, `LUMISCAN_KERYX_AUTOSTART=0` | Die App startet keinen Broker. Starten Sie selbst einen: `krxsystem --backend hdv --url <address>` |
| `HDV_KERYX_BROKER`, `HDV_KERYX_PAGE` | Vom Installationsprogramm von LumiScan Keryx gesetzt: das Broker-Programm und das Seitenprogramm |

Jede App nennt beim Start in ihrem Log die Broker-Adresse, die sie verwendet.

## Andere Adressen als die Standardadresse {#several-brokers}

- **Ein anderer Port**: `tcp://127.0.0.1:<port>`. Jeder Port ist ein eigener Broker, gestartet von der ersten App, die ihn benötigt. Ein Broker belegt seinen Port und den nächsten, daher müssen zwei Broker mindestens zwei Ports auseinanderliegen. Seine Keryx-Seite liegt auf dem Port + 2000.
- **Ein lokaler Socket**: `ipc://<name>`. Ein relativer Name bezieht sich auf den Ordner, in dem ein Programm startet: Starten Sie den Broker selbst und starten Sie jede App aus genau diesem Ordner.
- **Ein anderer PC**: Zu einer Adresse eines anderen Rechners wird nur eine Verbindung aufgebaut, dort wird nie ein Broker gestartet. Der Broker lauscht nur auf diesem PC, sofern seine Einstellungen nichts anderes festlegen, und er hat keine Authentifizierung. Der Betrieb von Apps auf mehreren PCs mit einem gemeinsamen Broker wird in diesem Handbuch nicht behandelt.

## Gut zu wissen {#limits}

- Werte tragen keinen eigenen Zeitstempel: Eine App, die einen benötigt, veröffentlicht ihn in einem Knoten oder im Ergebnis.
- Ein neuer Abonnent erhält keinen Anfangswert. Lesen Sie den Knoten einmal und abonnieren Sie ihn dann.
- Ein Methodenaufruf, der nach einem Timeout wiederholt wird, kann zweimal ausgeführt werden.

# ctrlX Data Layer auf ctrlX OS – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html

> [!NOTE]
> Auf einem PC mit Windows 11 oder Ubuntu 24.04 nutzen die Apps stattdessen LumiScan Keryx: siehe [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html).

Auf ctrlX OS - einer ctrlX CORE oder einem ctrlX IPC - werden die LumiScan-Apps aus dem ctrlX Store installiert und verwenden den **ctrlX Data Layer** von ctrlX OS. Für den Data Layer selbst ist nichts zu installieren oder zu starten.

## Wo die Knoten liegen

Jede App registriert ihre Knoten unter `hdvisionsystems/<app>/…`, mit denselben Adressen wie auf einem PC. Siehe [Adressen und Module](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html). In der Data-Layer-Ansicht der Weboberfläche von ctrlX OS können Sie sie ansehen, beschreiben und Methoden aufrufen.

## Eine SPS anbinden {#connecting-a-plc}

Ein ctrlX-PLC-Programm auf demselben Gerät liest, schreibt und ruft die Knoten der Apps direkt auf.

- Verwenden Sie für die SPS-Logik die einfachen Knoten - Zahlen, Booleans, Strings und Arrays.
- Ergebnisse, die FlatBuffers-Nachrichten sind, benötigen zum Dekodieren ihr Schema. AI Object Matching stellt sein Schema bereit und beschreibt in seinem Handbuch, wie Sie es in ctrlX PLC Engineering importieren.

## Ergebnisse eines Methodenaufrufs

Ein Methodenaufruf antwortet mit einem ctrlX-Ergebnis: `DL_OK`, wenn er ausgeführt wurde, andernfalls zum Beispiel `DL_TOO_MANY_OPERATIONS` oder `DL_INVALID_VALUE`. Die Bedeutung der einzelnen Ergebnisse steht in [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results).

## Einstellungsdateien

Die Einstellungen jeder App sind Dateien im Ordner der App in der aktiven Konfiguration, `/var/snap/rexroth-solutions/common/solutions/activeConfiguration`. Laden Sie sie über die ctrlX-Weboberfläche hoch, oder mit WebDAV, wo ein direktes Hochladen nicht möglich ist. Das Handbuch jeder App beschreibt ihre Dateien unter **Uploading Data**. Einstellungen lassen sich auch über den Data Layer ändern, siehe [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html).

## Logs

Eine App schreibt ihre Meldungen in das Systemprotokoll von ctrlX OS. Lesen Sie sie im Logbuch der ctrlX-Weboberfläche oder mit `journalctl`.

Eine App ohne gültige Lizenz beendet sich kurz nach dem Start; der Grund steht im Systemprotokoll. Siehe [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).

# Adressen und Module – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html

## Die Adresse eines Knotens

```none
hdvisionsystems/<app>/<module>/<folder>/...     die Knoten eines Moduls
hdvisionsystems/<app>/system/...                was die ganze App oder mehrere Module betrifft
types/hdvisionsystems/<app>/<type>              die FlatBuffers-Typen, die die App veröffentlicht
```

- **`<app>`:** Der Name der App auf dem Data Layer, in Kleinbuchstaben mit `-`, zum Beispiel `lumiscan-cam-driver`. Er ist nicht immer der Name des Programms: Das Programm `lumiscan-ai-obj-mat` bedient `lumiscan-ai-object-matching`, und `lumiscan-calib` bedient `lumiscan-calibration`.
- **`<module>`:** Eine Instanz innerhalb der App: eine Kamera, ein neuronales Netz, eine Kalibrierebene, ein Finder-Modul. Ihr Name stammt aus den Einstellungen der App. Die Code Reader haben keine Modulebene.

Beispiel: `hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/request`.

## Modulnamen {#module-names}

- Adressen sind **kleingeschrieben**. Ein Knoten, den Sie nicht finden, ist fast immer eine Abweichung in Groß-/Kleinschreibung oder Schreibweise.
- Modulnamen bestehen aus Kleinbuchstaben, Ziffern, `-` und `_`. Cam Driver und AI Object Matching lehnen jeden anderen Modulnamen ab: Ein solches Modul erscheint nicht auf dem Data Layer. Calibration benennt ein Modul nach seiner Datei und verwendet den Namen in Kleinbuchstaben.
- `system` ist reserviert und nie ein Modulname.

## Die Ordner eines Moduls {#folders}

| Ordner | Enthält |
| --- | --- |
| `control/` | die Funktionen: `control/<function>/ready` und `request` (ein [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html)), `control/<function>/execute` (eine [Execute-Methode](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html)); den Status des Moduls `control/status/code` und `control/status/text`; die [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) `control/publish/`, `control/subscribe/` und `control/unsubscribe/` |
| `input/` | was ein Client schreibt, bevor er eine Funktion startet |
| `output/` | die Ergebnisse der Funktionen, schreibgeschützt |
| `setting/` | eine schreibgeschützte Ansicht dessen, was das Modul anwendet, zum Beispiel `setting/settings-hash` und `setting/stream/…` |

Einige Apps haben eigene Ordner, zum Beispiel beim Cam Driver `device-info/`, `transport-layer/` und `features/`.

## Wo eine Funktion ihre Knoten ablegt {#layout}

**Eine Execute-Methode** legt alles, was zu ihr gehört, unter ihrer Funktion ab:

```none
<module>/control/<function>/execute
<module>/control/<function>/input/...
<module>/control/<function>/output/...
```

**Ein Handshake** hat `ready` und `request` unter seiner Funktion und verwendet die Eingaben und Ausgaben des Moduls:

```none
<module>/control/<function>/ready
<module>/control/<function>/request
<module>/input/...
<module>/output/...
<module>/control/status/code, text
```

**Eine Funktion, die beides hat** - die meisten Funktionen von Cam Driver, AI Object Matching und Calibration -, verwendet für beide Aufrufarten `input/` und `output/` des Moduls.

## Der Aufbau jeder App {#layouts-per-app}

Einige Apps behalten einen älteren Aufbau bei, damit Programme, die dafür geschrieben wurden, weiter funktionieren.

| App | Modul benannt nach | Funktionen |
| --- | --- | --- |
| Cam Driver | `id` in der Moduldatei | `<module>/control/<function>/…` |
| AI Object Matching | `name` in der Moduldatei, `default`, falls keiner angegeben ist | `<module>/control/<function>/…` |
| Calibration | dem Namen der Moduldatei ohne `.json` | `<module>/control/<function>/…` |
| Template Finder, Object Finder, Area Detector, Text Reader | der an `system/create-module` übergebenen Modul-ID oder der gespeicherten Modulliste; standardmäßig `module-1` | `<module>/<method>/execute`, `<module>/<method>/input/…`, `<module>/<method>/output/…`, zum Beispiel `module-1/find-template/execute`; Streams unter `<module>/control/` |
| DMC, QR, Aztec und Barcode Reader | keine Modulebene | `<app>/execute`, `<app>/input/…`, `<app>/output/results`; Streams unter `<app>/control/` |
| Cockpit | keine: Cockpit liest nur die Knoten der anderen Apps |   |

Die genauen Knoten jeder App stehen in der **Data Layer Reference** ihres Handbuchs.

## Der Knoten system {#system}

Alles, was nicht ein einzelnes Modul betrifft, liegt unter `hdvisionsystems/<app>/system/`: Module anlegen und entfernen, die Einstellungsdateien, die Geräteerkennung und Ressourcen, die alle Module gemeinsam nutzen. Die Code Reader haben dort nur `system/meta/subscription-schema`. Siehe [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html).

## Typen {#types}

| Typ | Verwendet für |
| --- | --- |
| bool, int16, int32, uint32, uint64, float32, float64, string | einfache Werte: Eingaben, Flags, Zähler, Statuscodes (`int32`) |
| Arrays dieser Typen | zum Beispiel die Koordinaten-Arrays von Calibration |
| FlatBuffers | Ergebnisse und Bilder. Ihre Schemas liegen auf dem Data Layer unter `types/hdvisionsystems/<app>/…` |

Bauen Sie SPS-Logik auf den einfachen Werten auf. Ein FlatBuffers-Ergebnis benötigt zum Dekodieren sein Schema; jedes Ergebnis, das eine SPS üblicherweise benötigt, ist auch als einfache Knoten verfügbar - siehe das Handbuch der App.

# Aufrufmuster wählen – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/calling-functions.html

Jede Funktion einer LumiScan-App wird auf eine von drei Arten aufgerufen.

|   | [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) | [Execute-Methode](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html) | [Stream](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html) |
| --- | --- | --- | --- |
| Für | Operationen, die länger als etwa 1 s dauern oder deren Dauer unbekannt ist | Operationen innerhalb von etwa 1 s | jedes Element, das eine Quelle erzeugt, sobald es eintrifft |
| Der Client | schreibt `request`, pollt `ready` und den Status; nichts blockiert | schreibt die Methode einmal; der Schreibvorgang kehrt zurück, wenn die Operation abgeschlossen ist | abonniert einmal; die Apps senden jedes Ergebnis |
| Das Ergebnis | `control/status/code` und die Ausgaben | das Ergebnis des Schreibvorgangs (konnte die Operation ausgeführt werden?), dann der Status (war sie erfolgreich?) | jedes gesendete Ergebnis |
| Beispiele | `connect-camera`, `reset`, `inference` | `capture`, `trigger`, `transform`, `find-template` | Kamerabilder in AI Object Matching, einen Finder oder einen Code Reader |

## Warum etwa 1 s

Eine Execute-Methode hält ihren Aufrufer fest, bis die Operation abgeschlossen ist: eine SPS-Task oder einen Client, dessen Anfrage in ein Timeout läuft. Bei LumiScan Keryx gibt ein Client standardmäßig nach 2 s auf. Eine Operation, die länger dauern kann, ist daher ein Handshake, den der Aufrufer pollt, statt zu warten. Deshalb bietet der Cam Driver `connect-camera`, `disconnect-camera` und `reset` nur als Handshakes an.

## Auf Anfrage oder als Stream

|   | Auf Anfrage (Handshake oder Execute) | Stream |
| --- | --- | --- |
| Wer die Arbeit anstößt | Ihr Programm: ein Aufruf pro Bild oder pro Punkt | die Quelle: Jedes Bild, das die Kamera liefert, startet die nächste App |
| Wie die Apps zusammenhängen | unabhängig; Ihr Programm trägt die Daten von einer zur nächsten | verkettet; jede App abonniert die vorherige |
| Geschwindigkeit (eine Kamera, ein PC, gemessen) | etwa 34 Bilder pro Sekunde vom Cam Driver | 63 bis 68 Bilder pro Sekunde vom Cam Driver |

Verwenden Sie **auf Anfrage** für einzelne, langsame oder unregelmäßige Operationen: die Kamera verbinden, ein Bild aufnehmen, einige bereits vorhandene Punkte transformieren. Verwenden Sie einen **Stream** für kontinuierliche Arbeit: Die Kamera liefert ein Bild, AI Object Matching findet die Objekte, Calibration wandelt sie in Koordinaten um, und Ihr Programm liest nur das Ergebnis.

**Eine Implementierung, mehrere Muster.** Wo eine App dieselbe Arbeit in mehr als einem Muster anbietet, teilen diese sich eine Implementierung und eine Sperre pro Modul. Das Ergebnis ist dasselbe, und zwei Operationen eines Moduls überschneiden sich nie.

## Welche App was bietet

| App | Handshake | Execute | Stream |
| --- | --- | --- | --- |
| Cam Driver | ja | ja | erzeugt Bilder |
| AI Object Matching | ja | ja | konsumiert Bilder, erzeugt Detektionen |
| Calibration | ja | ja | konsumiert Punkte oder Ergebnisse, erzeugt 3D-Punkte |
| Template Finder, Object Finder, Area Detector, Text Reader | – | ja | konsumieren Bilder, erzeugen Ergebnisse |
| DMC, QR, Aztec und Barcode Reader | – | ja | konsumieren Bilder, erzeugen Codes |

Das Handbuch jeder App listet ihre Funktionen auf und welche Muster jede davon bietet.

# Handshake – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html

Der Handshake ist für eine Operation gedacht, die länger als etwa 1 s dauern kann oder die ein Client starten muss, ohne auf sie zu warten. Client und Modul wechseln sich auf zwei Knoten ab, `ready` und `request`. Niemand wartet innerhalb eines Aufrufs: Der Client pollt, und das Modul antwortet über Knoten.

Cam Driver, AI Object Matching und Calibration bieten Handshakes an.

## Adressen {#addresses}

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `<module>/control/<function>/ready` | bool, schreibgeschützt | vom Modul gesetzt: `true`, wenn die Funktion gestartet werden kann |
| `<module>/control/<function>/request` | bool, beschreibbar | vom Client gesetzt, um die Funktion zu starten |
| `<module>/control/status/code` | int32, schreibgeschützt | der Status des Moduls, einer für alle seine Funktionen. Siehe [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html) |
| `<module>/control/status/text` | string, schreibgeschützt | dasselbe als Text, für Menschen - verwenden Sie in der Programmlogik den Code |
| `<module>/input/…` | beschreibbar | die Eingaben der Funktion, vor dem Request geschrieben |
| `<module>/output/…` | schreibgeschützt | ihre Ergebnisse |
| `<module>/output/package-identifier` | schreibgeschützt | zählt abgeschlossene Operationen: Ein neuer Wert bedeutet neue Ausgaben |

`<module>` ist `hdvisionsystems/<app>/<module name>`, zum Beispiel `hdvisionsystems/lumiscan-calibration/plane1/control/transform/request`.

## Der Ablauf {#sequence}

1. Warten Sie, bis `control/<function>/ready` `true` ist.
2. Schreiben Sie die Eingaben der Funktion.
3. Setzen Sie `control/<function>/request` auf `true`.
4. Warten Sie, bis `ready` `false` ist: Das Modul hat den Request erkannt.
5. Setzen Sie `request` auf `false`.
6. Warten Sie, bis `ready` wieder `true` ist: Die Funktion ist abgeschlossen.
7. Lesen Sie `control/status/code` und die Ergebnisse unter `output/`. `output/package-identifier` ist um eins gestiegen.

Pollen Sie im Abstand von 50 bis 100 ms.

## Was das Modul anzeigt {#module-states}

So, wie Calibration ihn ausführt:

| Schritt | `ready` | `request` | `status/code` |
| --- | --- | --- | --- |
| Leerlauf | `true` | `false` | `0` ready, oder der letzte Fehler |
| Der Client fordert an | `true` | `true` |   |
| Das Modul quittiert | `false` | `true` | `3` waitingForClient |
| Der Client bestätigt; die Funktion läuft | `false` | `false` | `2` running |
| Fertig | `true` | `false` | `0`, oder ein Fehler (unter `0`) |

## Regeln {#rules}

- **Nur ein Programm schreibt einen `request`-Knoten.** Schreiben zwei Programme ihn unabhängig voneinander, kann ein Request verloren gehen. Ein Programm, das sich nicht mit anderen abstimmen kann, verwendet die [Execute-Methode](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html), die einen zweiten Aufruf ablehnt, solange einer läuft.
- **Das Modul wartet darauf, dass `request` zurückfällt, so lange es dauert.** Es gibt kein Timeout: Ein `request`, das danach noch `true` ist, würde als neuer Request gelesen.
- **Ein Handshake und eine Execute-Methode desselben Moduls teilen sich eine Sperre.** Während ein Handshake läuft, antwortet ein Execute-Aufruf desselben Moduls, dass es belegt ist.

## Unterschiede zwischen den Apps {#differences}

Calibration folgt dem Ablauf genau. Cam Driver und AI Object Matching weichen in Punkten ab, die ein SPS-Programm kennen muss:

| App | Unterschied |
| --- | --- |
| Cam Driver | `capture` startet, sobald der Request erkannt wird, ohne zu warten, bis `request` zurückfällt. Ein **fehlgeschlagenes Capture endet mit Status `3`**, nicht mit seinem eigenen Fehlercode, und `capture/ready` bleibt `false`, bis ein `reset` erfolgreich ist. Ein fehlgeschlagenes `reset`, `save` oder `load` bleibt ebenfalls bestehen, bis ein `reset` erfolgreich ist. Jeder andere Fehler steht nur etwa 100 ms im Status: Prüfen Sie eine Verbindung mit `device-info/is-connected`, nicht mit dem Status. Ohne Lizenz ist jedes `ready` `false` und der Status ist `-4`. |
| AI Object Matching | `inference` startet, sobald der Request erkannt wird, und **endet unabhängig vom Ausgang mit Status `3`**; nur `output/package-identifier`, das ausschließlich bei Erfolg steigt, zeigt an, dass sie erfolgreich war. Nach einer fehlgeschlagenen Inferenz und solange das Modul einen Fehler hat, wird jeder Request außer `reset` ignoriert. `reset` wird sofort ausgeführt. Während der Stream läuft, ist `inference/ready` `false` und ein Request erhält Status `100002`. |

Um den Ausgang eines Cam-Driver-`capture` oder einer AI-`inference` direkt zu lesen, verwenden Sie die zugehörige Execute-Methode: Der Status behält dann den eigenen Code der Operation.

# Execute-Methoden – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html

Eine Execute-Methode ist für eine Operation gedacht, die innerhalb von etwa 1 s abgeschlossen ist. Der Client schreibt einen beliebigen Wert auf den `execute`-Knoten der Methode, und der Schreibvorgang kehrt zurück, wenn die Operation abgeschlossen ist. Ein Schreibvorgang, kein Zustand, den man verfolgen muss.

## Eine Methode aufrufen

1. Schreiben Sie die Eingaben der Methode. Eine Methode hat keine eigenen Argumente: Ihre Eingaben sind separate Knoten.

2. Schreiben Sie auf den `execute`-Knoten der Methode, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute`.

3. Prüfen Sie **beide** Ergebnisse:

   a. **Das Ergebnis des Schreibvorgangs: Konnte die Operation überhaupt ausgeführt werden?** Ein abgelehnter Schreibvorgang wird nie in eine Warteschlange gestellt. Siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results).

   b. **Der Ausgang: War die Operation erfolgreich?** Wo Sie ihn lesen, hängt von der App ab, siehe unten.

4. Lesen Sie die Ausgaben.

## Wo Eingaben, Ausgaben und Ausgang stehen {#where}

| Apps | Knoten | Eine fehlgeschlagene Operation zeigt sich als |
| --- | --- | --- |
| Cam Driver, AI Object Matching, Calibration | `<module>/control/<function>/execute`; `input/…` und `output/…` des Moduls, dieselben, die der Handshake verwendet | `control/status/code` und `text`, während der Schreibvorgang selbst meldet, dass sie ausgeführt wurde. **Lesen Sie nach dem Schreibvorgang immer den Status.** Ein abgelehnter Schreibvorgang lässt den Status unverändert |
| Template Finder, Object Finder, Area Detector, Text Reader | `<module>/<method>/execute`, `<module>/<method>/input/…`, `<module>/<method>/output/result`, `output/status-code`, `output/status-text` | `<method>/output/status-code` und `status-text`, **und** der Schreibvorgang schlägt mit dem passenden Ergebnis fehl |
| DMC, QR, Aztec und Barcode Reader | `<app>/execute`, `<app>/input/…`, `<app>/output/results` | der Schreibvorgang schlägt fehl; der Grund steht im Log der Anwendung |

Der `status-code` der Finder hat eigene Werte, siehe [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

Die Funktionen unter `system/` jeder App sind Methoden der zweiten Art: `system/<function>/execute` mit `input/…` sowie `output/status-code`, `status-text`. Eine Funktion der gesamten App im neueren Aufbau ist `system/control/<function>/execute`, zum Beispiel `system/control/restart/execute`.

## Wann eine Methode ausgeführt wird {#ready}

Eine Methode von Cam Driver, AI Object Matching oder Calibration prüft dasselbe Signal `control/<function>/ready`, das ihr Handshake verwendet, und wird abgelehnt, solange es `false` ist. Die meisten Funktionen hängen von etwas ab, das vorher geschehen muss - eine verbundene Kamera, ein geladenes Netz, ein Bild zum Speichern. Das Handbuch der App gibt an, wann jedes `ready` `true` ist.

Wird eine Methode abgelehnt, lesen Sie ihr `ready` zusammen mit `control/status/code` und `status/text`: `ready` benennt die fehlende Vorbedingung, und der Statustext enthält noch die Meldung des Fehlers, der sie verursacht hat.

## Timeouts {#timeouts}

Beachten Sie, dass der Aufrufer blockiert ist, bis die Methode zurückkehrt. Bei LumiScan Keryx gibt ein Client standardmäßig nach 2 s auf; der OPC UA Connector wartet bis zu 60 s auf einen Methodenaufruf. Eine Funktion, die länger dauern kann, wird nur als [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) angeboten.

## Eine Operation zur Zeit {#busy}

Ein Modul führt jeweils eine Operation aus. Eine Methode, die aufgerufen wird, während eine andere Operation desselben Moduls läuft - ein Execute, ein Handshake oder bei den Findern ein Bild eines Streams -, wird als belegt abgelehnt (`TooManyOperations`, ctrlX `DL_TOO_MANY_OPERATIONS`). Wiederholen Sie den Aufruf: Derselbe Aufruf gelingt, sobald die laufende Operation abgeschlossen ist.

Eine Operation, die mit einem laufenden Stream kollidiert, wird anders abgelehnt: `capture` des Cam Driver und `inference` von AI Object Matching sind nicht bereit, solange ihr Stream läuft (`InvalidOperationMode`, ctrlX `DL_INVALID_OPERATION_MODE`). Wiederholen hilft nicht; stoppen Sie zuerst den Stream, siehe [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#collisions).

# Streams (experimentell) – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html

> [!IMPORTANT]
> Streams sind **experimentell**: im Cam Driver ab v2.3.0, in AI Object Matching ab v2.2.0 und in Calibration ab v2.1.0. Ihre Knoten können sich noch ändern. Prüfen Sie einen Stream mit Ihrer Kamera und Ihrem Netz, bevor Sie sich darauf verlassen.

Ein Stream verarbeitet jedes Element, das eine Quelle erzeugt, sobald es eintrifft: Kamerabilder in AI Object Matching, einem Finder oder einem Code Reader; Detektionen oder Punkte in Calibration. Es gibt keinen Request pro Element. Der Produzent sendet jedes Element, ein Konsument verarbeitet es und sendet sein Ergebnis. Produzent und Konsument arbeiten gleichzeitig; deshalb ist ein Stream schneller als ein Execute-Aufruf pro Element.

## Produzenten und Konsumenten {#roles}

| App | Rolle |
| --- | --- |
| Cam Driver | erzeugt Bilder auf `<camera>/control/publish/output/stream/frame` |
| AI Object Matching | konsumiert Bilder, erzeugt Detektionen auf `<module>/control/subscribe/output/stream/result` |
| Template Finder, Object Finder, Area Detector, Text Reader | konsumieren Bilder, erzeugen ihre Ergebnisse auf `<module>/control/subscribe/output/stream/result` |
| DMC, QR, Aztec und Barcode Reader | konsumieren Bilder, erzeugen Codes auf `<app>/control/subscribe/output/stream/result` |
| Calibration | konsumiert Punkte oder das Ergebnis einer anderen App, erzeugt 3D-Punkte auf `<module>/control/subscribe/output/stream/points` und `plain-points` |

**Ein Konsument hat eine Quelle.** Um zwei Kameras zu verarbeiten, verwenden Sie zwei Module.

## Der Produzent: der Cam Driver {#producer}

Alle Adressen beginnen mit `hdvisionsystems/lumiscan-cam-driver/<camera>/`.

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/publish/execute` | Methode | wendet die folgenden Eingaben gemeinsam an |
| `control/publish/input/enable` | bool | veröffentlicht, solange `true` |
| `control/publish/input/keep-latest-output` | bool | schreibt jedes Bild zusätzlich in die normale Ausgabe |
| `control/publish/input/tag` | string | das Tag auf seinen Bildern; wird in der Moduldatei gespeichert |
| `control/publish/output/stream/frame` | FlatBuffers | jedes Bild, gesendet |
| `control/publish/output/stream/active` | bool | der Stream läuft |
| `control/publish/output/stream/statistics/…` | uint64 | Zähler |

Der Cam Driver triggert die Kamera nie von selbst. Ein Bild kommt, wenn die Kamera per Hardware oder per `control/trigger/execute` getriggert wird oder wenn ihr Trigger-Modus aus ist und sie frei läuft. Der Stream benötigt eine verbundene Kamera; `connect-camera`, `disconnect-camera` und `reset` stoppen einen laufenden Stream. Siehe das Handbuch des Cam Driver.

## Ein Konsument {#consumer}

Dieselben Knoten in jedem Konsumenten, unter `<module>/` (bei einem Code Reader: unter `<app>/`):

| Adresse | Typ | Bedeutung |
| --- | --- | --- |
| `control/subscribe/execute` | Methode | prüft, speichert und wendet die folgenden Eingaben an |
| `control/subscribe/input/enable` | bool | Stream-Modus |
| `control/subscribe/input/address` | string | die eine Quelle: der Stream-**Ordner** des Produzenten |
| `control/subscribe/input/tag` | string | das Tag auf der Ausgabe dieses Moduls; leer: die Modul-ID |
| `control/subscribe/input/queue-size` | uint32 | wie viele Elemente warten dürfen |
| `control/subscribe/input/keep-latest-output` | bool | schreibt jedes Ergebnis zusätzlich in die normale Ausgabe |
| `control/unsubscribe/execute` | Methode | entfernt die Quelle, die angegeben ist durch … |
| `control/unsubscribe/input/address` | string | … diese Adresse; eine andere Adresse wird abgelehnt |
| `setting/stream/…` | schreibgeschützt | was angewendet und gespeichert ist: `enable`, `address`, `tag`, `queue-size`, `keep-latest-output` |
| `control/subscribe/output/stream/active` | bool | der Stream läuft |
| `control/subscribe/output/stream/<result>` | FlatBuffers | jedes Ergebnis, gesendet |
| `control/subscribe/output/stream/statistics/…` | uint64 | Zähler, alle 250 ms veröffentlicht, bei jedem Start zurückgesetzt |

Die Finder und Code Reader haben außerdem `control/subscribe/output/stream/last-failure`: warum das letzte Element fehlgeschlagen ist.

Was die Quelle eines Konsumenten enthalten muss, steht als JSON Schema auf `hdvisionsystems/<app>/system/meta/subscription-schema`.

## Stream starten und stoppen {#running}

**Die Eingaben wirken erst bei `execute`.** `enable` allein zu schreiben startet nichts.

1. Starten Sie den Produzenten: Schreiben Sie an der Kamera `control/publish/input/enable` = `true` und rufen Sie dann `control/publish/execute` auf. Warten Sie, bis `control/publish/output/stream/active` `true` ist.
2. Schreiben Sie am Konsumenten `control/subscribe/input/address`, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`.
3. Schreiben Sie optional `tag`, `queue-size` und `keep-latest-output`.
4. Schreiben Sie `control/subscribe/input/enable` = `true` und rufen Sie dann `control/subscribe/execute` auf.
5. Warten Sie, bis `control/subscribe/output/stream/active` `true` ist. Ab dann treffen Ergebnisse ein.
6. Zum Stoppen schreiben Sie `enable` = `false` und rufen erneut `execute` auf.

Gut zu wissen:

- Der Stream-Modus ist ein **Pegel**, kein Befehl: Der Stream läuft, solange das angewendete `enable` `true` ist.
- Die Eingaben sind mit den angewendeten Werten vorbelegt; ändern Sie also nur, was Sie brauchen, und rufen Sie `execute` auf.
- Ein Konsument kann vor seinem Produzenten gestartet werden. Ergebnisse treffen ein, sobald Elemente eintreffen. Ein fehlgeschlagenes Abonnement wird alle 5 s erneut versucht, solange der Stream läuft.
- Eine andere Adresse ersetzt die Quelle.
- `enable` = `true` ohne Adresse wird abgelehnt (`Rejected`, ctrlX `DL_INVALID_VALUE`), und nichts ändert sich.

## Calibration als Konsument {#calibration-source}

Auch Calibration erhält einen Stream-Ordner, und ihre Moduldatei gibt an, welchen Knoten darin sie lesen und wie sie ihn in Punkte umwandeln soll: einen `onEntry`-Schritt im Abschnitt `stream`. Um die Objekte zu lesen, die AI Object Matching findet, nennt der Schritt den Knoten `result`, die Liste darin und die Felder, die den Punkt bilden. Ohne einen solchen Schritt liest Calibration ihre Quelle als einfaches Zahlen-Array, wie eine SPS-Variable sie liefert. Siehe das Handbuch von Calibration.

## Neuestes Ergebnis behalten {#keep-latest}

Mit eingeschaltetem `keep-latest-output` wird jedes Element - bzw. jedes Ergebnis - zusätzlich in die normale Ausgabe des Moduls geschrieben, so wie ein Aufruf auf Anfrage es schreiben würde, und `output/package-identifier` wird gezählt. Eine SPS, die die normale Ausgabe liest, sieht dann das neueste Stream-Ergebnis. Ist es ausgeschaltet, veröffentlicht der Stream nur unter `…/stream/…`, und die normale Ausgabe behält das Ergebnis des letzten Aufrufs.

Stream-Ergebnisse sind FlatBuffers-Datensätze. Für eine SPS schalten Sie `keep-latest-output` in dem Modul ein, dessen Ergebnis Sie benötigen, und lesen dessen einfache Ausgabeknoten. Calibration veröffentlicht außerdem `plain-points`: alle Punkte eines Ergebnisses in einem `float32`-Array `x0, y0, z0, x1, …`, ohne Lineage.

## Was bei einem Neustart erhalten bleibt {#saved}

| Was | Erhalten | Wie |
| --- | --- | --- |
| Der Stream eines Konsumenten (`enable`, `address`, `tag`, `queue-size`, `keep-latest-output`) | ja | `control/subscribe/execute` und `control/unsubscribe/execute` speichern ihn im Abschnitt `stream` der Einstellungsdatei des Moduls, bevor sie ihn anwenden. Ein Konsument, dessen gespeichertes `enable` `true` ist, abonniert beim Start von selbst |
| Der Stream des Cam Driver | **nein** | nur sein `tag` wird gespeichert. Rufen Sie nach jedem Start erneut `control/publish/execute` mit `enable` = `true` auf |
| Die Kameraverbindung | nein | führen Sie nach jedem Start den Handshake `connect-camera` aus |

Lässt sich eine Datei nicht schreiben, antwortet `execute` mit `CreationFailed` (ctrlX `DL_CREATION_FAILED`), und nichts ändert sich.

Der Abschnitt `stream` der Einstellungsdatei eines Konsumenten:

```json
"stream": {
    "enable": false,
    "address": "hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream",
    "tag": "",
    "queueSize": 1,
    "keepLatestOutput": false,
    "onEntry": []
}
```

## Warteschlangengröße {#queue}

| App | Bereich | Standard | Wenn die Warteschlange voll ist |
| --- | --- | --- | --- |
| AI Object Matching, die Finder, die Code Reader | 1 bis 64 | 1 | ein neues Element verdrängt das älteste |
| Calibration | 1 bis 4096 | 64 | ein neues Element verdrängt das älteste wartende |

Ein Element, das aus einer vollen Warteschlange verdrängt wird, zählt als **übersprungen**.

## Streams und einzelne Operationen {#collisions}

Während ein Stream läuft, werden Operationen abgelehnt, mit denen er kollidieren würde:

- Cam Driver: `capture/ready` ist `false`; `capture/execute` antwortet mit `InvalidOperationMode` (ctrlX `DL_INVALID_OPERATION_MODE`). Wiederholen Sie nicht in einer Schleife. Um während des Streamings einzelne Bilder aufzunehmen, lesen Sie `…/stream/frame` der Kamera, oder schalten Sie `keep-latest-output` ein und lesen Sie `output/image`, wenn sich `output/package-identifier` ändert.
- AI Object Matching: `inference/ready` ist `false`; ein Handshake-Request endet mit Status `100002`.
- Finder: Eine Methode, die aufgerufen wird, während ein Bild verarbeitet wird, wird als belegt abgelehnt.
- Code Reader: `execute` und der Stream behindern sich nicht; jedes Bild wird von einem eigenen Detektor gelesen.

Wird der Stream des Cam Driver gestoppt, verbindet er die Kamera neu, damit `capture` wieder funktioniert; das dauert etwa zwei Sekunden. Warten Sie, bis `capture/ready` `true` ist. Wechseln Sie so selten wie möglich zwischen Stream und Capture.

## Die Kette verfolgen {#counters}

Jede App zählt unter `…/stream/statistics/`, was sie empfängt. Der erste Zähler, der nicht steigt, zeigt, wo eine Kette stehen bleibt:

| App | Zähler |
| --- | --- |
| Cam Driver | `frames`, `published-frames`, `lost-frames`, `incomplete-frames` |
| AI Object Matching | `received-frames`, `inferred-frames`, `skipped-frames`, `failed-frames`, `lost-frames` |
| Finder, Code Reader | `received-frames`, `processed-frames`, `skipped-frames`, `failed-frames`, `lost-frames` |
| Calibration | `received-updates`, `transformed-updates`, `skipped-updates`, `failed-updates`, `lost-updates` |

`lost-` zählt Elemente, die nie eingetroffen sind, ermittelt aus Lücken in den Sequenznummern; `skipped-` Elemente, die aus einer vollen Warteschlange verdrängt wurden; `failed-*` Elemente, die nicht verarbeitet werden konnten.

## Das Ergebnis: ein Envelope mit seiner Lineage {#envelope}

Jedes Stream-Ergebnis ist ein **Envelope**: zuerst die Lineage (Herkunftskette) des Elements, dann die Nutzdaten - dasselbe Ergebnis wie die Nicht-Stream-Ausgabe der App, mit einigen Unterschieden, die im Handbuch der jeweiligen App beschrieben sind.

Die **Lineage** listet jedes Modul auf, das das Element durchlaufen hat. Jeder Schritt hat:

| Feld | Bedeutung |
| --- | --- |
| `producer` | die Data-Layer-Adresse des Moduls, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1` |
| `tag` | das Tag des Moduls, oder seine Modul-ID, wenn das Tag leer ist |
| `run` | wann der Stream des Produzenten gestartet wurde (µs seit der Epoche); ein neuer Lauf zählt wieder ab 1 |
| `sequence` | die Nummer des Elements im Lauf: 1, 2, … ohne Lücken, eine Lücke ist also ein verlorenes Element |
| `time_us` | wann der Schritt ausgeführt wurde |
| `settings_hash` | der Hash der Einstellungen, mit denen der Schritt ausgeführt wurde, wie auf `setting/settings-hash` |
| `elapsed_us` | wie lange der Schritt gedauert hat |
| `external_id` | die eigene Nummer des Produzenten für das Element, zum Beispiel die Block-ID der Kamera |

Die Lineage enthält höchstens 16 Schritte: den Ursprung und die neuesten. Ein geänderter `settings_hash` bedeutet, dass sich eine Einstellung geändert hat. Jeder Hash wird einmalig in `settings-history/` im Einstellungsordner der App gespeichert, sodass sich die Einstellungen hinter einem Ergebnis nachschlagen lassen.

Um auf einem PC ein Bild durch die Kette zu verfolgen, verwenden Sie **LumiScan Keryx Utilities**, siehe [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#utilities).

# Statuscodes und Ergebnisse – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html

Zwei Arten von Antworten teilen einem Client mit, was geschehen ist:

- das **Ergebnis eines Aufrufs** - ist der Schreibvorgang oder Methodenaufruf durchgegangen? -, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results);
- der **Status**, den die App in einen Knoten schreibt - war die Operation erfolgreich? -, siehe [Modulstatus: `control/status/code`](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#module-status) und [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

Verwenden Sie in der Programmlogik die Zahlen, niemals die Texte.

## Modulstatus: `control/status/code` {#module-status}

Cam Driver, AI Object Matching und Calibration melden den Zustand jedes Moduls auf `<module>/control/status/code` (`int32`) und `control/status/text`. Werte ab `0` sind normal, Werte unter `0` sind Fehler.

| Code | Text | Bedeutung |
| --- | --- | --- |
| `0` | `ready` | die letzte Funktion war erfolgreich; bereit für die nächste |
| `1` | `settingUp` | das Modul startet |
| `2` | `running` | eine Funktion läuft |
| `3` | `waitingForClient` | wartet auf den Client, meist darauf, dass `request` zurückfällt |
| `-1` | `undefinedError` | kein spezifischer Code |
| `-2` | `invalidSetting` | die Einstellungen konnten nicht geladen werden |
| `-3` | `invalidInput` | eine Eingabe ist ungültig |
| `-4` | `missingLicense` | die Lizenz fehlt |
| `-5` | `restartRequired` | die Einstellungen wurden über `system/settings` geändert: Starten Sie die App neu |

App-spezifische Codes, aufgeführt im Handbuch der jeweiligen App:

| App | Codes |
| --- | --- |
| Cam Driver | `-10000` bis `-10012` |
| Calibration | `-10001` (`inputXYSizeNotEqual`) |
| AI Object Matching | `100001` (`ImageQueueEmpty`), `100002` (`StreamActive`) |

## Ausführungsstatus der Finder {#execution-status}

Template Finder, Object Finder, Area Detector und Text Reader schreiben den Ausgang jeder Methode auf `<method>/output/status-code` (`int16`) und `status-text`. Diese Werte sind eigene, nicht der obige Modulstatus:

| Code | Text |
| --- | --- |
| `1` | `ok` |
| `0` | `idle` |
| `-1` | `busy` |
| `-2` | `invalidInput` |
| `-3` | `imageReadFailed` |
| `-4` | `sourceNotFound` |
| `-5` | `cropInvalid` |
| `-6` | `writeFailed` |
| `-7` | `algorithmFailed` |
| `-8` | `publishFailed` |
| `-9` | `moduleNotFound` |
| `-10` | `moduleExists` |
| `-11` | `licenseUnavailable` |

Beachten Sie, dass `-5` hier `cropInvalid` bedeutet, im Modulstatus dagegen `restartRequired`.

## Ergebnisse eines Methodenaufrufs {#method-results}

Ein Schreibvorgang auf einen `execute`-Knoten meldet, ob die Operation ausgeführt werden konnte. Die Namen unterscheiden sich zwischen den Data Layern; die Bedeutung ist dieselbe.

| LumiScan Keryx | ctrlX Data Layer | OPC UA Connector | Bedeutung und Vorgehen |
| --- | --- | --- | --- |
| `Ok` | `DL_OK` | `Good` | Die Operation wurde ausgeführt. Bei Cam Driver, AI Object Matching und Calibration lesen Sie für den Ausgang `control/status/code` |
| `TooManyOperations` | `DL_TOO_MANY_OPERATIONS` | `BadTooManyOperations` | Eine andere Operation des Moduls läuft. Wiederholen Sie den Aufruf |
| `InvalidOperationMode` | `DL_INVALID_OPERATION_MODE` | `BadInvalidState` | Die Funktion ist nicht bereit: Ihr `ready` ist `false`, keine Lizenz, die Kamera ist nicht verbunden, ein Stream läuft. Bringen Sie das Modul zuerst in den Zustand; bloßes Wiederholen schlägt weiter fehl |
| `ResourceUnavailable` | `DL_RESOURCE_UNAVAILABLE` | `BadResourceUnavailable` | Die App wird beendet, ein Neustart ist erforderlich (Status `-5`), oder ein AI-Modul hat einen Fehler. Lesen Sie den Status; starten Sie die App neu, wenn erforderlich |
| `Rejected` | `DL_INVALID_VALUE` | `BadRequestNotAllowed` | Eine Eingabe ist ungültig. Nichts wurde geändert. Korrigieren Sie die Eingabe |
| `NodeNotFound` | `DL_INVALID_ADDRESS` | `BadNodeIdUnknown` | Ein Bild, eine Quelle, ein Modul oder der Knoten selbst wurde nicht gefunden. Prüfen Sie die Adresse und ihre Groß-/Kleinschreibung |
| `CreationFailed` | `DL_CREATION_FAILED` | `BadCommunicationError` oder `BadInternalError` | Etwas konnte nicht geschrieben oder angelegt werden: eine Datei, ein bereits vorhandenes Modul, eine nicht verfügbare Lizenz. Das Log nennt den Grund |
| `InternalError` | `DL_FAILED` | `BadInternalError` | Die Operation ist fehlgeschlagen. Lesen Sie den Status oder das Log |

Auf dem ctrlX Data Layer erreichen Daten, die eine Methode an einen fehlgeschlagenen Aufruf anhängt, den Client nicht; ein abgelehnter Aufruf enthält daher keinen Grund. Die Apps schreiben den Grund deshalb in ihr Log und, wo vorhanden, in einen Statusknoten.

# Einstellungen, Module und Neustart – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html

Alles, was nicht ein einzelnes Modul betrifft, liegt unter `hdvisionsystems/<app>/system/`. Die Apps gehören zu zwei Familien, die ihre Module unterschiedlich verwalten. Die Code Reader haben dort nur `system/meta/subscription-schema` (siehe [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#consumer)).

## Cam Driver, AI Object Matching, Calibration: Einstellungsdateien {#settings-file-apps}

Ihre Module sind die Moduldateien, die die Anwendungs-Einstellungsdatei auflistet.

| Knoten | Art | Wirkung |
| --- | --- | --- |
| `system/settings` | string, lesen und schreiben | Alle geladenen Einstellungen als ein JSON-Dokument: die Anwendungsdatei, in die jede aufgeführte Moduldatei eingebettet ist (Passwörter als `*` angezeigt). Beim Schreiben werden die geänderten Dateien gespeichert - jede zuerst von der App geprüft, die alte als `.bak` aufbewahrt - und ein Neustart wird als erforderlich markiert |
| `system/restart-required` | bool, schreibgeschützt | `true` nach einer gespeicherten Änderung, bis die App neu startet. In dieser Zeit meldet jedes Modul Status `-5` (`restartRequired`), und seine Methoden antworten mit `ResourceUnavailable` (ctrlX `DL_RESOURCE_UNAVAILABLE`) |
| `system/control/restart/execute` | Methode | stoppt die App und startet sie erneut. Die Knoten der App verschwinden, bis sie wieder läuft: Warten Sie, bis `system/restart-required` wieder gelesen werden kann |
| `system/control/create-module/execute` | Methode, Eingaben `control/create-module/input/module-id` und `content` | schreibt `<module-id>.json`. Wird abgelehnt, wenn die Datei existiert |
| `system/control/activate-module/execute`, `system/control/deactivate-module/execute` | Methode, Eingabe `control/<function>/input/module-id` | fügt die Datei der Liste der Anwendungsdatei hinzu bzw. entfernt sie daraus. Die Datei bleibt erhalten. Erfordert einen Neustart |
| `system/found-modules`, `system/status-text` | schreibgeschützt | die bedienten Module; warum keine bedient werden |

Der Cam Driver ergänzt die Kameraerkennung: `system/found-camera-modules`, `found-camera-serials`, `found-camera-mac-addresses`, `found-camera-ip-addresses` und den Handshake `system/force-ip/`. AI Object Matching bedient höchstens ein Modul: `activate-module` lehnt ein zweites ab.

Beispiel - das Kameramodul `camera2` zum Cam Driver hinzufü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.

Eine Moduldatei kann auch auf dem Datenträger geändert werden. AI Object Matching und Calibration lesen ihre Moduldatei bei `reset` erneut ein; andernfalls wirkt eine Änderung beim nächsten Start.

## Template Finder, Object Finder, Area Detector, Text Reader: Module zur Laufzeit {#registry-apps}

Ihre Module werden angelegt und entfernt, während die App läuft.

| Knoten | Art | Wirkung |
| --- | --- | --- |
| `system/modules` | string[], schreibgeschützt | die aktuellen Module |
| `system/create-module/execute` | Methode, Eingabe `input/module-id` | ein neues Modul mit Standardeingaben, sofort. Nach einem Neustart verschwunden, sofern nicht gespeichert |
| `system/remove-module/execute` | Methode, Eingabe `input/module-id` | entfernt das Modul |
| `system/save-current-modules/execute` | Methode | schreibt die Modulliste in die Anwendungsdatei und löscht die Eingabedateien von Modulen, die nicht mehr darin stehen |
| `system/save-module-inputs/execute` | Methode, Eingabe `input/module-id` | schreibt die Eingaben des Moduls in `<module-id>.json`, beim nächsten Start wiederhergestellt |

Jeder Finder ergänzt eigene Funktionen, zum Beispiel Template Finder `system/create-template` und `system/set-template-dir`, Text Reader `system/set-tessdata-dir` und `system/refresh-languages`. Siehe das Handbuch der App.

Beachten Sie, dass `create-module` zwei verschiedene Dinge bedeutet: in den Apps mit Einstellungsdateien eine Datei, die beim nächsten Neustart angewendet wird, in den Findern ein laufendes Modul, das beim nächsten Neustart verloren geht, sofern es nicht gespeichert wird.

## Was bei einem Neustart erhalten bleibt {#kept}

| Was | Erhalten |
| --- | --- |
| Die Eingaben eines Finder-Moduls | wenn mit `system/save-module-inputs/execute` gespeichert; beim Start wiederhergestellt |
| Die Modulliste einer Finder-App | wenn mit `system/save-current-modules/execute` gespeichert |
| Einstellungen von Cam Driver, AI Object Matching und Calibration, die auf `system/settings` geschrieben wurden | ja, beim nächsten Start angewendet |
| Zur Laufzeit gewählte Ordner (Template-, Objekt- und tessdata-Ordner) | ja, automatisch in der Anwendungsdatei gespeichert |
| Der Stream eines Konsumenten | ja, siehe [Streams](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#saved) |
| Der Stream des Cam Driver und die Kameraverbindung | **nein**: Starten Sie sie nach jedem Start erneut |
| Werte, die auf `input/` von Cam Driver, AI Object Matching und Calibration geschrieben wurden | **nein**: Schreiben Sie sie erneut |

Es gibt keine Lademethode: Ohne Neustart liest nichts eine gespeicherte Datei erneut ein, außer dem `reset` von AI Object Matching und Calibration.

# Werkzeuge – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html

| Werkzeug | Data Layer | Wofür |
| --- | --- | --- |
| [Keryx-Seite](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#data-layer-page) | LumiScan Keryx, Windows | den Baum durchsuchen, lesen, schreiben, Methoden aufrufen, Werte beobachten |
| [LumiScan Keryx Utilities](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#utilities) | LumiScan Keryx, Windows | Knoten abonnieren und Stream-Ergebnisse durch die Kette verfolgen |
| [krxclient](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#krxclient) | LumiScan Keryx | von der Kommandozeile, in Skripten und Tests durchsuchen, lesen, schreiben und Methoden aufrufen |
| [die Weboberfläche von ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html#ctrlx-web-interface) | ctrlX Data Layer | auf ctrlX OS durchsuchen, lesen, schreiben und Methoden aufrufen |

## Die Keryx-Seite {#data-layer-page}

`http://127.0.0.1:7555/` für den Standard-Broker - Port des Brokers + 2000. Das Starten von **LumiScan Keryx** öffnet dieselbe Seite in einem Fenster. Siehe [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#data-layer-page).

## LumiScan Keryx Utilities {#utilities}

Ein Fenster zu einem Broker: Wählen Sie den Broker, durchsuchen Sie seine Knoten, abonnieren Sie die gewünschten und lesen Sie in einer Liste, was sie veröffentlichen. Es ist nur ein Client: Es stellt keine Knoten bereit und ändert nichts am Broker. Nur unter Windows.

1. Starten Sie es. Ein Fenster öffnet sich; es benötigt die Microsoft Edge WebView2 Runtime, die in Windows 11 enthalten ist. Ohne sie öffnet sich die Seite im Standardbrowser.
2. **Broker**: Geben Sie Host und Port ein (standardmäßig `127.0.0.1` und `5555`) und klicken Sie auf **Connect**. Der Punkt zeigt, ob der Broker antwortet.
3. **Add**: Geben Sie Wörter einer Adresse in das Suchfeld ein, zum Beispiel `camera1 stream frame`, und wählen Sie einen Knoten. Eine Adresse, die der Broker noch nicht kennt, kann so hinzugefügt werden, wie sie eingegeben wurde: Ein Abonnement kann vor seinem Provider da sein.
4. **Starten** und **stoppen** Sie jedes Abonnement mit seiner eigenen Schaltfläche. Nach einem Neustart und nach einem Wechsel des Brokers kommen Abonnements gestoppt zurück - ein Kamera-Stream umfasst mehrere zehn Megabyte pro Sekunde. **Resume on start** ändert das.
5. **Results**: eine Liste, neueste zuerst, jede Zeile nennt ihre Quelle. **Keep newest** legt fest, wie viele behalten werden.
6. **Ein Element verfolgen**: Klicken Sie auf eine Zeile. Für ein Stream-Ergebnis listet die Detailansicht jede Zeile zum selben Element auf, in der Reihenfolge ihres Eintreffens und mit dem Abstand zur ersten, sowie die durchlaufenen Produzenten mit der jeweiligen Zeit. Die Pixel eines Bildes zeigt sie nie.

| Was | Wo |
| --- | --- |
| Abonnements und Einstellungen | `%APPDATA%\LumiScan Keryx Utilities\settings.json` |
| Log | `%LOCALAPPDATA%\LumiScan Keryx Utilities\logs\keryx-utilities.log` |

Die Ergebnisse werden nur im Arbeitsspeicher gehalten. `lost` zählt Updates, die der Broker nummeriert hat und die nicht eingetroffen sind.

## krxclient {#krxclient}

Der Kommandozeilen-Client von LumiScan Keryx. Er vertritt eine SPS: `read`, `write`, `browse`, `metadata`, `tree`, `execute`, `subscribe` und `handshake`, das einen ready/request-Handshake ausführt. Geben Sie den Broker mit `--keryx-backend` und `--keryx-url` an oder mit den Umgebungsvariablen `HDV_KERYX_BACKEND` und `HDV_KERYX_URL`.

```none
krxclient write hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/input/address hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream
krxclient write hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/input/enable true
krxclient execute hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/execute
krxclient subscribe hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/output/stream/result --count 5
```

`krxclient subscribe` zeigt einen FlatBuffers-Wert nur anhand seiner Größe: Es zeigt Ihnen, dass Ergebnisse eintreffen, nicht, was sie enthalten.

## Die Weboberfläche von ctrlX OS {#ctrlx-web-interface}

Öffnen Sie auf ctrlX OS in der Weboberfläche **Settings > Data Layer**. Sie zeigt den Baum des ctrlX Data Layer: Navigieren Sie zu `hdvisionsystems/<app>`, lesen und schreiben Sie Werte und rufen Sie Methoden auf. Siehe [ctrlX Data Layer auf ctrlX OS](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html).

# OPC UA Connector – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html

> [!NOTE]
> Auf ctrlX OS wird dieser Connector nicht verwendet: Eine ctrlX PLC auf demselben Gerät nutzt die Knoten direkt, siehe [Eine SPS anbinden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/ctrlx-data-layer.html#connecting-a-plc).

Der **LumiScan OPC UA Connector** (`lumiscan_opcua_connector`) stellt den Baum von LumiScan Keryx als OPC-UA-Adressraum dar. Eine SPS, ein SCADA-System oder ein beliebiger OPC-UA-Client liest, schreibt, ruft auf und abonniert die Knoten der Apps, ohne einen eigenen Data-Layer-Client. Der Connector leitet jede Anfrage beim Eintreffen an den Data Layer weiter; er speichert keine eigenen Werte.

Der Adressraum ist der eigene Baum des Data Layers, keine OPC UA Companion Specification wie OPC 40100 (Machine Vision).

## Endpunkt und Adressraum {#endpoint}

|   |   |
| --- | --- |
| Endpunkt | `opc.tcp://<pc>:4840`, auf jeder Netzwerkschnittstelle des PCs |
| Sicherheit | Security Policy **None**, **anonyme** Anmeldung, siehe [Sicherheit](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#security) |
| Namespace-URI | `urn:hdvisionsystems:keryx` |
| NodeId | die Data-Layer-Adresse als String-Identifier in diesem Namespace: `ns=<n>;s=hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code` |
| BrowseName | das letzte Segment der Adresse, zum Beispiel `code` |
| Wurzel | ein Objekt unter `Objects` namens `Keryx`, das `hdvisionsystems` und die anderen Ordner der obersten Ebene enthält. Mit `--root hdvisionsystems` gestartet, ist es `hdvisionsystems`; die NodeIds bleiben dieselben |

**Ermitteln Sie den Namespace-Index `n` anhand der URI** im `NamespaceArray` des Servers. Schreiben Sie keinen festen Index in Ihr Programm: Bei einem anderen Start kann er anders nummeriert sein.

| Data Layer | OPC-UA-Knoten |
| --- | --- |
| Ordner | Object (FolderType) |
| Wert | Variable (BaseDataVariableType), mit dem Zugriff, den der Knoten erlaubt |
| Methode | Method **ohne Eingangsargumente** und mit einem Ausgangsargument `Result`, zugehörig zum Objekt ihrer übergeordneten Adresse |

Der Connector durchläuft den Baum beim Start und danach alle 2 Sekunden erneut. Eine App, die später startet, ein hinzugefügtes Modul und ein verschwundener Knoten zeigen sich innerhalb von etwa 2 Sekunden. Es gibt keine Model-Change-Events: Ein Client, der sein Browse-Ergebnis zwischengespeichert hat, muss erneut browsen. Eine App, die stoppt, behält ihre Knoten im Baum; Lesezugriffe darauf liefern `BadTimeout`, dann `BadNoCommunication`, bis sich die App wieder registriert.

## Den Connector starten {#starting}

Das Installationsprogramm legt eine Verknüpfung im Startmenü an, die den Connector ohne Optionen startet: Port 4840, der gesamte Data Layer, anonym, Lesen und Schreiben.

**Starten Sie ihn nach den Apps.** Der Connector startet nie einen Broker: Ohne Broker protokolliert er den Grund, beendet sich mit Exit-Code 1, und sein Fenster schließt sich. Stoppen Sie ihn mit Strg+C. Wie die Apps ist er mit CodeMeter geschützt, siehe [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).

| Option | Bedeutung |
| --- | --- |
| `-p`, `--port <n>` | OPC-UA-Port, Standard 4840 |
| `-r`, `--root <address>` | nur diesen Teilbaum anzeigen, zum Beispiel `hdvisionsystems` |
| `--read-only` | Schreibvorgänge (`BadNotWritable`) und Methodenaufrufe (`BadNotExecutable`) ablehnen |
| `--keryx-url <url>` | der Broker, Standard `tcp://127.0.0.1:5555` |
| `--request-timeout-ms <ms>` | wie lange ein Lese- oder Schreibvorgang dauern darf, Standard 2000 |
| `--method-timeout-ms <ms>` | wie lange ein Methodenaufruf dauern darf, Standard 60000 |
| `--method-workers <n>` | Methodenaufrufe, die gleichzeitig laufen, Standard 4 |
| `--min-publishing-ms <ms>` | wie schnell eine Subscription höchstens Benachrichtigungen sendet, Standard 10 |
| `--resync-ms <ms>` | wie oft der Baum erneut durchlaufen wird, Standard 2000 |
| `--sampling-ms <ms>` | Sampling-Modus statt Event-Modus; nicht empfohlen |

`lumiscan_opcua_connector --help` listet alle Optionen auf.

## Sicherheit {#security}

**Es gibt keine.** Der Connector akzeptiert jeden Client, anonym und unverschlüsselt, und der Client kann jeden beschreibbaren Knoten schreiben und jede Methode aufrufen - einschließlich Starten und Stoppen der Kamera und Ändern von Einstellungen über `system/settings`. Behandeln Sie ihn wie einen ungeschützten Feldbus-Port:

- Betreiben Sie ihn in einem Netz, dem Sie vertrauen, etwa dem Maschinennetz zwischen PC und SPS;
- öffnen Sie TCP 4840 in der Firewall des PCs nur für die Adresse der SPS;
- für einen Client, der nur beobachtet, betreiben Sie eine zweite Instanz schreibgeschützt auf einem eigenen Port: `lumiscan_opcua_connector --root hdvisionsystems --port 4841 --read-only`.

Zertifikate, Benutzernamen und Verschlüsselung werden nicht unterstützt; ein Client, der auf einem sicheren Kanal besteht, kann sich nicht verbinden.

## Lesen, Schreiben und Typen {#types}

**Der Typ muss exakt dem des Knotens entsprechen.** Der Connector konvertiert nicht: Ein `Boolean`-Knoten nimmt einen Boolean an, nicht 0 oder 1; ein `UInt32`-Knoten nimmt UInt32 an, nicht Int32. Die meisten Probleme bei einer ersten Verbindung gehen auf einen Typ zurück, der um eine Größe abweicht.

| Knotentyp | OPC-UA-Typ | IEC 61131-3 |
| --- | --- | --- |
| bool | Boolean | `BOOL` |
| int32 | Int32 | `DINT` |
| uint32 | UInt32 | `UDINT` |
| uint64 | UInt64 | `ULINT` |
| float32 | Float | `REAL` |
| float64 | Double | `LREAL` |
| string | String | `STRING` |
| Arrays dieser Typen | derselbe Typ, eindimensional | `ARRAY [..] OF …` |
| FlatBuffers-Ergebnis, Bild | ByteString | ohne Decoder nicht verwendbar |

- Ein Lesevorgang wartet bis zu 2 Sekunden. Ein Knoten, der nicht geantwortet hat, ist für die nächsten 5 Sekunden `BadNoCommunication`.
- Ein Schreibvorgang ersetzt den gesamten Wert und wird nie wiederholt. Ein Schreibvorgang mit einer `NumericRange` wird abgelehnt (`BadWriteNotSupported`).
- Die Zeitstempel eines Werts stammen vom Connector: Der Data Layer führt keine eigene Zeit mit.
- Bauen Sie keine SPS-Logik auf FlatBuffers-Werten auf. Verwenden Sie die einfachen Knoten daneben.

## Die drei Muster aufrufen {#calls}

**Handshake**: nur Lese- und Schreibvorgänge, wie in [Handshake](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html) beschrieben. Pollen Sie im Abstand von 50 bis 100 ms.

**Execute**: Schreiben Sie die Eingaben der Methode - eine Methode hat keine Argumente, ihre Eingaben sind separate Knoten - und verwenden Sie dann den **Call**-Service mit `objectId` = der übergeordneten Adresse (zum Beispiel `…/camera1/control/trigger`) und `methodId` = der Methode (`…/camera1/control/trigger/execute`). Der Aufruf antwortet, wenn die Methode abgeschlossen ist, nach bis zu 60 Sekunden; setzen Sie das Call-Timeout Ihres Clients höher als Ihre langsamste Methode. Der Status des Aufrufs gibt an, ob die Operation ausgeführt werden konnte, siehe [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results). Lesen Sie danach `control/status/code` und die Ausgaben.

**Stream**: Abonnieren Sie den Ergebnisknoten, siehe [Subscriptions](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#subscriptions).

## Subscriptions {#subscriptions}

Legen Sie eine Subscription an und fügen Sie für den Knoten ein Monitored Item hinzu:

| Einstellung | Wert | Warum |
| --- | --- | --- |
| Publishing Interval | 10 ms oder mehr | das schnellste des Servers |
| Sampling Interval | **0** | meldet jeden Push beim Eintreffen (Event-Modus) |
| Queue Size | 10 bis 100 | mit 1 kommt nur der neueste Push an |
| DataChange Trigger | `StatusValueTimestamp` | sonst zählen zwei identische Ergebnisse als eines |
| DiscardOldest | true |   |

- Ein Knoten meldet eine Änderung, wenn die App ihn pusht; Streams tun das. Ein Wert, der zu groß ist, um gepusht zu werden, meldet sich im Event-Modus nie: Verwenden Sie dafür ein positives Sampling Interval.
- Große Werte kosten: Ein Kamerabild von 1,5 MB, alle 10 ms abgetastet, ergibt 150 MB/s für ein einziges Item. Überwachen Sie `output/image`, `…/stream/frame` oder `…/stream/result` nur, wenn Sie sie dekodieren. Für Koordinaten überwachen Sie `plain-points` von Calibration.
- Beim Start prüft der Connector, ob der Event-Modus funktioniert. Falls nicht, protokolliert er das und tastet jedes Item per Timer ab (Sampling-Modus). Erhält Ihr Client weniger Benachrichtigungen als Pushes, lesen Sie zuerst das Log des Connectors.

## OPC-UA-Statuscodes {#status}

Über die Ergebnisse eines Methodenaufrufs hinaus:

| Status | Bedeutung |
| --- | --- |
| `BadNodeIdUnknown` | falsche Adresse, Groß-/Kleinschreibung oder falscher Namespace-Index; die App läuft nicht; das Modul fehlt |
| `BadNoCommunication` | die App ist gestoppt oder hängt |
| `BadTimeout` | die App hat nicht innerhalb von 2 s (Lesen, Schreiben) bzw. 60 s (Aufruf) geantwortet |
| `BadTypeMismatch` | der Wert hat nicht den Typ des Knotens |
| `BadWriteNotSupported` | ein Schreibvorgang mit einer `NumericRange` |
| `BadNotWritable` | eine Ausgabe, oder der Connector ist schreibgeschützt |
| `BadNotExecutable` | der Connector ist schreibgeschützt |
| `BadMethodInvalid` | der Knoten ist keine Methode des Baums mehr: Browsen Sie erneut |

Nachdem eine App neu gestartet wurde, führen Sie Ihre Startsequenz erneut aus: Die Kamera ist nicht verbunden und der Stream des Cam Driver ist aus. Meldet sich ein Monitored Item nicht wieder, löschen Sie es und legen Sie es neu an.

# FAQ – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/faq.html

Kurze Antworten auf häufige Fragen zum Data Layer. Jeder Eintrag verweist auf die Seite mit den Details. Probleme und Fehlermeldungen sind unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) beschrieben.

> [!TIP]
> Jeder Eintrag hat einen festen Anker (zum Beispiel `#faq-start-broker`). Um eine Fehlermeldung zu finden, durchsuchen Sie die Seite [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) danach.

## Plattformen und Broker

### Muss ich mein Programm ändern, wenn ich von ctrlX OS auf einen PC wechsle? {#faq-same-interface}

- **Antwort:** Nein, nicht die Knotenadressen, Typen oder Aufrufmuster: Sie sind auf dem ctrlX Data Layer und bei LumiScan Keryx gleich. Was sich ändert, sind die Verbindung (eine SPS auf ctrlX OS, der OPC UA Connector auf einem PC), die Werkzeuge und die Namen der Methodenergebnisse.
- **Mehr:** [ctrlX Data Layer und LumiScan Keryx](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/platforms.html)

### Muss ich auf einem PC den Broker starten? {#faq-start-broker}

- **Antwort:** Nein. Wenn eine App startet und auf dem PC kein Broker antwortet, startet sie einen unter `tcp://127.0.0.1:5555`. Der Broker läuft weiter, wenn die Apps enden. Nur der OPC UA Connector startet nie einen: Starten Sie ihn nach den Apps.
- **Mehr:** [Der Broker](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#broker)

### Wie sehe ich mir die Knoten an? {#faq-see-nodes}

- **Antwort:** Unter Windows auf der Keryx-Seite `http://127.0.0.1:7555/`, in **LumiScan Keryx Utilities** oder mit `krxclient`. Unter Ubuntu mit `krxclient`. Auf ctrlX OS in der Data-Layer-Ansicht der Weboberfläche von ctrlX OS.
- **Mehr:** [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html)

## Funktionen aufrufen

### Soll ich den Handshake oder die Execute-Methode verwenden? {#faq-handshake-or-execute}

- **Antwort:** Verwenden Sie die Execute-Methode für Operationen innerhalb von etwa 1 s, wenn Ihr Programm warten kann. Verwenden Sie den Handshake für längere Operationen - `connect-camera`, `disconnect-camera` und `reset` des Cam Driver gibt es nur als Handshakes - oder wenn Ihr Programm nicht blockieren darf. Verwenden Sie einen Stream für kontinuierliche Verarbeitung.
- **Mehr:** [Aufrufmuster wählen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/calling-functions.html)

## Streams

### Wie liest eine SPS Stream-Ergebnisse? {#faq-stream-plc}

- **Antwort:** Stream-Ergebnisse sind FlatBuffers-Datensätze. Schalten Sie `keep-latest-output` in dem Modul ein, dessen Ergebnis Sie benötigen, und lesen Sie dessen einfache Ausgabeknoten, oder abonnieren Sie `plain-points` von Calibration.
- **Mehr:** [Neuestes Ergebnis behalten](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#keep-latest)

## OPC UA

### Kann der OPC UA Connector Verschlüsselung oder Benutzernamen verwenden? {#faq-opcua-security}

- **Antwort:** Nein. Er akzeptiert ausschließlich anonyme, unverschlüsselte Clients. Betreiben Sie ihn in einem vertrauenswürdigen Maschinennetz, öffnen Sie Port 4840 nur für die SPS, und geben Sie beobachtenden Clients eine `--read-only`-Instanz.
- **Mehr:** [Sicherheit](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#security)

## Fehlerbehebung {#troubleshooting}

Probleme und Fehlermeldungen sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html) beschrieben:

- [Eine App wartet auf den Broker (PC)](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#no-broker)
- [Eine App oder ein Modul fehlt im Baum](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#app-missing)
- [Ein Knoten ist „not found"](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#node-not-found)
- [Ein Methodenaufruf wird abgelehnt](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#refused)
- [Status `-5` (`restartRequired`) oder `ResourceUnavailable` bei jedem Aufruf](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#faq-restart-required)
- [Der Execute-Aufruf antwortet mit `Ok` (`DL_OK`), aber nichts ist passiert](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#faq-write-ok-but-failed)
- [Ein Handshake wird nicht abgeschlossen oder zeigt den falschen Ausgang](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#handshake-stuck)
- [Ein Stream liefert nichts](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#stream-nothing)
- [Stream-Ergebnisse sind veraltet oder vermischt](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-stream-results-mixed)
- [Ein OPC-UA-Client kann sich nicht verbinden](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-cannot-connect)
- [Das Fenster des Connectors schließt sich sofort](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-window-closes)
- [`Objects` ist leer oder enthält kein `hdvisionsystems`](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-objects-empty)
- [`BadNodeIdUnknown`](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-bad-node-id)
- [`BadTypeMismatch` beim Schreiben](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#faq-opcua-type-mismatch)
- [Eine Subscription erhält nur einen Wert oder verpasst Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-subscription)
- [Benachrichtigungen bleiben nach einem Neustart des Connectors oder einer App aus](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-notifications-stop)

## Support

### Wo erhalte ich Hilfe? {#faq-support}

- **Antwort:** Siehe die übergreifende [LumiScan-FAQ](https://docs.hdvisionsystems.com/de/faq.html), oder wenden Sie sich an [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com), +49 6221 6721905. Für Lizenzen: [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

# Fehlerbehebung – LumiScan Keryx

URL: https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html

Beginnen Sie mit den [Allgemeine Prüfungen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#general-checks): Sie helfen bei jedem Problem mit dem Data Layer. Suchen Sie dann Ihr Symptom in den folgenden Abschnitten und arbeiten Sie dessen Schritte der Reihe nach ab. Der letzte Abschnitt nennt, was Sie an den Support senden, wenn das Problem weiterhin besteht.

## Allgemeine Prüfungen {#general-checks}

Prüfen Sie zuerst diese Punkte:

- **Die App läuft und ist auf dem Data Layer.** Öffnen Sie auf einem PC die Keryx-Seite `http://127.0.0.1:7555/` (Windows) oder führen Sie `krxclient tree hdvisionsystems --depth 1` aus: Der Baum zeigt den Ordner `hdvisionsystems` mit einem Ordner pro laufender App. Auf ctrlX OS verwenden Sie die Data-Layer-Ansicht der Weboberfläche von ctrlX OS. Siehe [Werkzeuge](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/tools.html).

- **Alle Programme verwenden denselben Broker (PC).** Jede App nennt beim Start in ihrem Log die Broker-Adresse, die sie verwendet. Jede App, Cockpit und der OPC UA Connector müssen dieselbe Adresse verwenden. Standard ist `tcp://127.0.0.1:5555`; `--keryx-url` oder `LUMISCAN_KERYX_URL` ändert sie. Siehe [Optionen und Umgebungsvariablen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#options).

- **Die App bedient ihre Module.** Für jede App mit Modulen listet `hdvisionsystems/<app>/system/found-modules` diese auf. Ist die Liste leer, nennt `hdvisionsystems/<app>/system/status-text` den Grund.

- **Der Status des Moduls.** Cam Driver, AI Object Matching und Calibration melden ihn auf `<module>/control/status/code` und `control/status/text`: Werte unter `0` sind Fehler. Die Finder melden jede Methode auf `<method>/output/status-code` und `status-text`. Verwenden Sie die Zahlen, nicht die Texte. Siehe [Statuscodes und Ergebnisse](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html).

- **Die Adressen passen zur App-Version.** Adressen sind kleingeschrieben. In den kommenden Releases sind mehrere Knoten umgezogen, ohne Alias unter der alten Adresse: Vergleichen Sie Ihr Programm mit der **Data Layer Reference** der App-Version, die Sie einsetzen.

- **Die Logs.** Die Apps protokollieren die erste Ablehnung einer Methode und danach für dieselbe Methode und dasselbe Ergebnis höchstens eine Zeile alle zehn Sekunden.

  | Log | Wo |
  | --- | --- |
  | Eine App auf ctrlX OS | das Systemprotokoll von ctrlX OS: das Logbuch der ctrlX-Weboberfläche oder `journalctl` |
  | Der Broker unter Windows (Log, Aufzeichnungen und `broker.json`) | `C:\ProgramData\HD Vision Systems GmbH\LumiScan Keryx` |
  | Der Broker unter Ubuntu | `/tmp/lumiscan-keryx` |
  | LumiScan Keryx Utilities | `%LOCALAPPDATA%\LumiScan Keryx Utilities\logs\keryx-utilities.log` |

## Broker, Apps und Knoten {#broker-apps-nodes}

### Problem: Eine App wartet auf den Broker (PC) {#no-broker}

**Symptome**

Eine App auf einem PC protokolliert, dass sie keinen Data-Layer-Broker erreichen konnte (`could not reach a Keryx broker`), und wartet.

**Mögliche Ursachen**

- Es ist der erste Start: Der Broker braucht einige Sekunden, bis er antwortet.
- **LumiScan Keryx** ist nicht installiert.
- Das Terminal wurde vor der Installation von LumiScan Keryx geöffnet. Das Installationsprogramm setzt die Variablen `HDV_KERYX_BROKER` und `HDV_KERYX_PAGE`; ein Programm oder Terminal, das bereits geöffnet war, sieht sie nicht.
- Der automatische Start ist ausgeschaltet: `--no-keryx-autostart` oder `LUMISCAN_KERYX_AUTOSTART=0`.
- Der Broker wurde auf der Keryx-Seite mit **Shut down broker** gestoppt.
- Die Adresse ist eine `ipc://`-Adresse relativ zu einem Ordner: Keine App startet dafür einen Broker.
- Die Adresse ist die eines anderen Computers: Eine App verbindet sich nur damit und startet dort nie einen Broker.

**Diagnose**

1. Warten Sie nach dem ersten Start einige Sekunden - erwartet: Die App verbindet sich, sobald der Broker antwortet.
2. Lesen Sie die Broker-Adresse im Log der App beim Start - erwartet: die Adresse, die Sie verwenden wollen, standardmäßig `tcp://127.0.0.1:5555`.
3. Prüfen Sie, ob LumiScan Keryx installiert ist und ob Sie das Terminal nach der Installation geöffnet haben.
4. Prüfen Sie die Optionen und Umgebungsvariablen der App - erwartet: Weder `--no-keryx-autostart` noch `LUMISCAN_KERYX_AUTOSTART=0` ist gesetzt, es sei denn, Sie starten den Broker selbst.
5. Prüfen Sie, ob auf der Keryx-Seite **Shut down broker** geklickt wurde. Danach starten die Apps den Broker nicht von selbst erneut.
6. Bei einer `ipc://`-Adresse: Prüfen Sie, ob der Broker und jede App aus demselben Ordner gestartet wurden.

**Lösung**

- **Wenn es der erste Start ist:** Warten Sie. Die App verbindet sich, sobald der Broker antwortet.

- **Wenn LumiScan Keryx nicht installiert ist:**

  a. Installieren Sie zuerst LumiScan Keryx, dann die Apps. Führen Sie jedes Installationsprogramm als Administrator aus.

  b. Öffnen Sie ein **neues** Terminal und starten Sie die App erneut.

- **Wenn das Terminal vor der Installation geöffnet wurde:** Öffnen Sie ein neues Terminal und starten Sie die App erneut.

- **Wenn der automatische Start ausgeschaltet ist:** Entfernen Sie die Option oder die Variable, oder starten Sie den Broker selbst: `krxsystem --backend hdv --url <address>`.

- **Wenn der Broker heruntergefahren wurde:** Klicken Sie auf der Keryx-Seite auf **Start broker** oder öffnen Sie das LumiScan Keryx-Fenster. Auch ein von Hand gestartetes `krxsystem` oder ein Neustart des PCs startet ihn wieder.

- **Wenn die Adresse eine relative `ipc://`-Adresse ist:** Starten Sie den Broker selbst (`krxsystem --backend hdv --url <address>`) und starten Sie dann jede App aus genau diesem Ordner.

- **Wenn die Adresse die eines anderen Computers ist:** Der Betrieb von Apps auf mehreren PCs an einem Broker wird in diesem Handbuch nicht behandelt. Wenden Sie sich an den Support.

Siehe [LumiScan Keryx auf einem PC](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Meldung aus dem Log der App, der Broker-Adresse, die die App dort nennt, und dem Log des Brokers.

### Problem: Eine App oder ein Modul fehlt im Baum {#app-missing}

**Symptome**

Der Baum enthält unter `hdvisionsystems` keinen Ordner für die App, oder ein erwartetes Modul erscheint nicht auf dem Data Layer: `hdvisionsystems/<app>/system/found-modules` führt es nicht auf.

**Mögliche Ursachen**

- Die App läuft nicht.
- Die App verwendet einen anderen Broker als das Programm, mit dem Sie nachsehen (PC).
- Die Einstellungsdatei konnte nicht geladen werden.
- Die Lizenz fehlt. Auf ctrlX OS beendet sich eine App ohne gültige Lizenz kurz nach dem Start.
- Der Modulname enthält Großbuchstaben oder andere Zeichen als `a-z`, `0-9`, `-` und `_`. Cam Driver und AI Object Matching lehnen ein solches Modul ab.
- Cam Driver, AI Object Matching, Calibration: Die Moduldatei wurde mit `system/control/activate-module/execute` aktiviert, die App wurde seitdem aber nicht neu gestartet.
- Template Finder, Object Finder, Area Detector, Text Reader: Das Modul wurde mit `system/create-module/execute` angelegt und nicht gespeichert, und die App wurde seitdem neu gestartet.

**Diagnose**

1. Prüfen Sie den Baum - auf einem PC auf der Keryx-Seite oder mit `krxclient tree`; auf ctrlX OS in der Weboberfläche von ctrlX OS; erwartet: Der Ordner `hdvisionsystems` enthält einen Ordner pro laufender App.
2. Vergleichen Sie auf einem PC die Broker-Adresse im Log der App mit der Adresse von Cockpit, dem OPC UA Connector oder dem verwendeten Werkzeug - erwartet: dieselbe Adresse.
3. Lesen Sie `hdvisionsystems/<app>/system/found-modules` - erwartet: Das Modul ist aufgeführt.
4. Falls nicht, lesen Sie `hdvisionsystems/<app>/system/status-text` - erwartet: Dort steht, warum die App kein Modul bedient, meist eine Einstellungsdatei, die nicht geladen werden konnte, oder eine fehlende Lizenz.
5. Prüfen Sie den Modulnamen - erwartet: nur Kleinbuchstaben, Ziffern, `-` und `_`. Der Name stammt aus `id` in der Moduldatei (Cam Driver), aus `name` in der Moduldatei (AI Object Matching), aus dem Namen der Moduldatei (Calibration) oder aus der Modul-ID (die Finder). Siehe [Modulnamen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/addresses.html#module-names).
6. Lesen Sie auf ctrlX OS das Systemprotokoll - erwartet: keine Meldung, dass die Lizenz fehlt.

**Lösung**

- **Wenn die App nicht läuft:** Starten Sie sie und warten Sie, bis sie vollständig gestartet ist.

- **Wenn die App einen anderen Broker verwendet:** Übergeben Sie jeder App, Cockpit und dem OPC UA Connector dieselbe `--keryx-url`.

- **Wenn die Einstellungsdatei nicht geladen werden konnte:** Korrigieren Sie sie und starten Sie die App erneut. Auf einem PC sind die Einstellungen Dateien im Einstellungsordner der App (unter Windows `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\<program>\etc\<settings folder>`); die Option `--generate-settings` schreibt ein Beispiel. Siehe [Speicherorte der Dateien](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/keryx.html#files). Auf ctrlX OS laden Sie sie hoch, wie es das Handbuch der App unter **Uploading Data** beschreibt.

- **Wenn die Lizenz fehlt:** Siehe [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).

- **Wenn der Modulname ungültig ist:** Verwenden Sie Modulnamen in Kleinbuchstaben.

- **Wenn die App seit der Aktivierung nicht neu gestartet wurde:** Rufen Sie `hdvisionsystems/<app>/system/control/restart/execute` auf.

- **Wenn ein Finder-Modul nicht gespeichert wurde:**

  a. Legen Sie das Modul mit `system/create-module/execute` erneut an.

  b. Speichern Sie die Modulliste mit `system/save-current-modules/execute` und die Eingaben des Moduls mit `system/save-module-inputs/execute`.

Siehe [Einstellungen, Module und Neustart](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit dem Inhalt von `system/found-modules` und `system/status-text` sowie der Moduldatei.

### Problem: Ein Knoten ist „not found" {#node-not-found}

**Symptome**

Ein Lese-, Schreib- oder Methodenaufruf meldet, dass der Knoten nicht gefunden wurde: `NodeNotFound` (LumiScan Keryx), `DL_INVALID_ADDRESS` (ctrlX Data Layer) oder `BadNodeIdUnknown` (OPC UA). Ein Programm, das für ein früheres Release geschrieben wurde, findet einen Knoten nicht mehr, den es verwendet hat.

**Mögliche Ursachen**

- Groß-/Kleinschreibung oder Schreibweise der Adresse ist falsch. Adressen sind kleingeschrieben.
- Der Knoten ist umgezogen. In den kommenden Releases sind mehrere Knoten umgezogen, ohne Alias unter der alten Adresse, zum Beispiel der Stream des Cam Driver von `input/stream/enable` nach `control/publish/input/enable`.
- Die App startet gerade neu: Ihre Knoten verschwinden, bis sie wieder läuft.
- Das Modul fehlt, siehe [Problem: Eine App oder ein Modul fehlt im Baum](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#app-missing).

**Diagnose**

1. Vergleichen Sie die Adresse mit dem Baum - auf einem PC auf der Keryx-Seite oder aus `krxclient tree`; auf ctrlX OS in der Weboberfläche von ctrlX OS; erwartet: dieselbe Groß-/Kleinschreibung und Schreibweise.
2. Vergleichen Sie die Adresse mit der **Data Layer Reference** der App-Version, die Sie einsetzen - erwartet: Der Knoten ist dort unter dieser Adresse aufgeführt.
3. Prüfen Sie, ob die App gerade neu startet - erwartet: `system/restart-required` kann gelesen werden.

**Lösung**

- **Wenn Groß-/Kleinschreibung oder Schreibweise falsch ist:** Korrigieren Sie die Adresse.
- **Wenn der Knoten umgezogen ist:** Ändern Sie Ihr Programm auf die Adresse in der **Data Layer Reference** der App-Version, die Sie einsetzen.
- **Wenn die App gerade neu startet:** Warten Sie, bis `system/restart-required` wieder gelesen werden kann.
- **Wenn das Modul fehlt:** Siehe [Problem: Eine App oder ein Modul fehlt im Baum](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#app-missing).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Adresse, die nicht gefunden wird, und dem Ergebnis des Aufrufs.

## Funktionen aufrufen {#calling-functions}

### Problem: Ein Methodenaufruf wird abgelehnt {#refused}

**Symptome**

Ein Schreibvorgang auf einen `execute`-Knoten antwortet nicht mit `Ok` (`DL_OK`, OPC UA `Good`), sondern mit einem der Ergebnisse aus [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results), zum Beispiel `TooManyOperations`, `InvalidOperationMode`, `ResourceUnavailable` oder `Rejected`. Auf dem ctrlX Data Layer trägt ein abgelehnter Aufruf keinen Grund.

**Mögliche Ursachen**

- `TooManyOperations` (ctrlX `DL_TOO_MANY_OPERATIONS`, OPC UA `BadTooManyOperations`): Eine andere Operation desselben Moduls läuft - ein Execute, ein Handshake oder bei den Findern ein Frame eines Streams.
- `InvalidOperationMode` (ctrlX `DL_INVALID_OPERATION_MODE`, OPC UA `BadInvalidState`): Die Funktion ist nicht bereit. Ihr `ready` ist `false`, zum Beispiel weil keine Lizenz vorhanden ist, die Kamera nicht verbunden ist oder ein Stream läuft.
- `ResourceUnavailable` (ctrlX `DL_RESOURCE_UNAVAILABLE`, OPC UA `BadResourceUnavailable`): Nach einer Änderung über `system/settings` ist ein Neustart erforderlich (Status `-5`), die App wird beendet, oder ein AI-Modul hat einen Fehler.
- `Rejected` (ctrlX `DL_INVALID_VALUE`, OPC UA `BadRequestNotAllowed`): Eine Eingabe ist ungültig; nichts wurde geändert.
- `NodeNotFound` (ctrlX `DL_INVALID_ADDRESS`, OPC UA `BadNodeIdUnknown`): Ein Bild, eine Quelle, ein Modul oder der Knoten selbst wurde nicht gefunden.
- `CreationFailed` (ctrlX `DL_CREATION_FAILED`): Etwas konnte nicht geschrieben oder angelegt werden, zum Beispiel eine Datei, ein bereits vorhandenes Modul oder eine nicht verfügbare Lizenz.
- `InternalError` (ctrlX `DL_FAILED`, OPC UA `BadInternalError`): Die Operation ist fehlgeschlagen.

**Diagnose**

1. Notieren Sie das Ergebnis des Aufrufs und schlagen Sie es unter [Ergebnisse eines Methodenaufrufs](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#method-results) nach.
2. Lesen Sie das Log der App - erwartet: der Grund der Ablehnung. Die Apps schreiben ihn dorthin, weil ein abgelehnter Aufruf auf dem ctrlX Data Layer keinen trägt.
3. Cam Driver, AI Object Matching, Calibration: Lesen Sie `control/<function>/ready` zusammen mit `control/status/code` und `control/status/text`. `ready` nennt die fehlende Voraussetzung; der Statustext trägt noch die Meldung des Fehlers, der sie verursacht hat.
4. Finder: Lesen Sie `<method>/output/status-code` und `status-text`. Siehe [Ausführungsstatus der Finder](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#execution-status).

**Lösung**

- **Wenn eine andere Operation des Moduls läuft (`TooManyOperations`):** Wiederholen Sie den Aufruf. Er gelingt, sobald die laufende Operation abgeschlossen ist.
- **Wenn die Funktion nicht bereit ist (`InvalidOperationMode`):** Bringen Sie das Modul zuerst in den erforderlichen Zustand, verbinden Sie zum Beispiel die Kamera. Bloßes Wiederholen schlägt weiter fehl: Wiederholen Sie nicht in einer Schleife. `capture` des Cam Driver und `inference` von AI Object Matching sind nicht bereit, während ihr Stream läuft: Stoppen Sie zuerst den Stream, siehe [Streams und einzelne Operationen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#collisions). Das Handbuch der App nennt, wann jedes `ready` `true` ist.
- **Wenn ein Neustart erforderlich ist (`ResourceUnavailable`, Status `-5`):** Siehe [Problem: Status `-5` (`restartRequired`) oder `ResourceUnavailable` bei jedem Aufruf](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#faq-restart-required).
- **Wenn die App beendet wird oder ein AI-Modul einen Fehler hat (`ResourceUnavailable`):** Lesen Sie den Status und starten Sie die App neu, wenn erforderlich.
- **Wenn eine Eingabe ungültig ist (`Rejected`):** Korrigieren Sie die Eingabe und rufen Sie erneut auf.
- **Wenn etwas nicht gefunden wurde (`NodeNotFound`):** Prüfen Sie die Adresse und ihre Groß-/Kleinschreibung, siehe [Problem: Ein Knoten ist „not found"](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#node-not-found).
- **Wenn etwas nicht geschrieben oder angelegt werden konnte (`CreationFailed`) oder die Operation fehlgeschlagen ist (`InternalError`):** Lesen Sie das Log und den Status; dort steht der Grund.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Adresse der Methode, ihrem Ergebnis, den Werten von `ready`, `control/status/code` und `control/status/text` sowie den Log-Zeilen zur Ablehnung.

### Problem: Status `-5` (`restartRequired`) oder `ResourceUnavailable` bei jedem Aufruf {#faq-restart-required}

**Symptome**

Jedes Modul der App meldet `control/status/code` = `-5` (`restartRequired`), und seine Methoden antworten mit `ResourceUnavailable` (ctrlX `DL_RESOURCE_UNAVAILABLE`, OPC UA `BadResourceUnavailable`).

**Mögliche Ursachen**

- Die Einstellungen wurden über `system/settings` geändert. Sie werden beim nächsten Start wirksam.

**Diagnose**

1. Lesen Sie `hdvisionsystems/<app>/system/restart-required` - erwartet nach einer gespeicherten Änderung: `true`, bis die App neu startet.

**Lösung**

- **Wenn die Einstellungen über `system/settings` geändert wurden:**

  a. Rufen Sie `hdvisionsystems/<app>/system/control/restart/execute` auf. Die Knoten der App verschwinden, bis sie wieder läuft.

  b. Warten Sie, bis `system/restart-required` wieder gelesen werden kann.

  c. Führen Sie Ihre Startsequenz erneut aus: In `input/` geschriebene Werte bleiben nicht erhalten, die Kamera ist nicht verbunden und der Stream des Cam Driver ist aus. Siehe [Was bei einem Neustart erhalten bleibt](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/settings-and-modules.html#kept).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit dem Wert von `system/restart-required` und dem Inhalt von `system/settings`.

### Problem: Der Execute-Aufruf antwortet mit `Ok` (`DL_OK`), aber nichts ist passiert {#faq-write-ok-but-failed}

**Symptome**

Cam Driver, AI Object Matching, Calibration: Ein Schreibvorgang auf einen `execute`-Knoten antwortet mit `Ok` (`DL_OK`, OPC UA `Good`), aber die Operation hatte keine Wirkung.

**Mögliche Ursachen**

- Die Operation wurde ausgeführt, ist aber fehlgeschlagen. Das Ergebnis des Schreibvorgangs sagt nur aus, dass die Operation ausgeführt wurde. Ob sie erfolgreich war, steht im Modulstatus.

**Diagnose**

1. Lesen Sie direkt nach dem Aufruf `control/status/code` und `control/status/text` - erwartet: `0` (`ready`). Werte unter `0` sind Fehler.
2. Schlagen Sie den Code unter [Modulstatus](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/status-codes.html#module-status) nach. App-spezifische Codes stehen im Handbuch der jeweiligen App.

**Lösung**

- **Wenn der Status unter `0` liegt:** Beheben Sie die Ursache, die der Code nennt, korrigieren Sie zum Beispiel eine Eingabe (`-3`, `invalidInput`) oder starten Sie die App neu (`-5`, siehe [Problem: Status `-5` (`restartRequired`) oder `ResourceUnavailable` bei jedem Aufruf](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#faq-restart-required)). Rufen Sie dann erneut auf.
- Lesen Sie in Ihrem Programm nach dem Aufruf immer `control/status/code`. Siehe [Wo Eingaben, Ausgaben und Ausgang stehen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html#where).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Adresse der Methode und den Werten von `control/status/code` und `control/status/text` nach dem Aufruf.

### Problem: Ein Handshake wird nicht abgeschlossen oder zeigt den falschen Ausgang {#handshake-stuck}

**Symptome**

`ready` bleibt nach dem Request `false`; ein `capture` des Cam Driver oder eine `inference` von AI Object Matching per Handshake endet mit Status `3` (`waitingForClient`); oder ein fehlgeschlagenes `connect-camera` des Cam Driver zeigt seinen Fehler nur etwa 100 ms lang.

**Mögliche Ursachen**

- `request` ist noch `true`: Das Modul wartet darauf, dass `request` zurückfällt, so lange es dauert.
- Zwei Programme schreiben denselben `request`-Knoten, und ein Request geht verloren.
- `capture` des Cam Driver: Ein fehlgeschlagenes Capture endet mit Status `3`, nicht mit seinem eigenen Fehlercode, und `capture/ready` bleibt `false`, bis ein `reset` gelingt. Ein fehlgeschlagenes `reset`, `save` oder `load` bleibt ebenfalls bestehen, bis ein `reset` gelingt.
- `inference` von AI Object Matching: Jede Inferenz endet mit Status `3`, unabhängig von ihrem Ausgang. Nach einer fehlgeschlagenen Inferenz und solange das Modul einen Fehler hat, wird jeder Request außer `reset` ignoriert. Während der Stream läuft, ist `inference/ready` `false`, und ein Request erhält Status `100002`.
- Cam Driver: Jeder andere Fehler bleibt nur etwa 100 ms lang im Status stehen.
- Cam Driver ohne Lizenz: Jedes `ready` ist `false`, und der Status ist `-4`.

**Diagnose**

1. Folgen Sie den Schritten unter [Der Ablauf](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html#sequence), fragen Sie dabei alle 50 bis 100 ms ab, und notieren Sie den Schritt, an dem es stehen bleibt.
2. Lesen Sie `request`, nachdem `ready` `false` geworden ist - erwartet: Ihr Programm hat es wieder auf `false` gesetzt.
3. Prüfen Sie, welche Programme den `request`-Knoten schreiben - erwartet: nur eines.
4. Bei einem `capture` des Cam Driver oder einer `inference` von AI Object Matching: Lesen Sie `output/package-identifier` davor und danach - erwartet: Er ist um eins gestiegen, wenn die Operation erfolgreich war.
5. Bei einem `connect-camera` des Cam Driver: Lesen Sie `device-info/is-connected` - erwartet: `true`, wenn die Kamera verbunden ist.
6. Beim Cam Driver: Lesen Sie `control/status/code` - erwartet: nicht `-4`.

**Lösung**

- **Wenn `request` noch `true` ist:** Setzen Sie `request` auf `false`.
- **Wenn zwei Programme `request` schreiben:** Lassen Sie nur ein Programm schreiben. Ein Programm, das sich nicht mit anderen abstimmen kann, verwendet die [Execute-Methode](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/execute.html), die einen zweiten Aufruf ablehnt, solange einer läuft.
- **Wenn ein `capture` oder eine `inference` mit Status `3` endet:** So enden sie. Erkennen Sie den Erfolg an `output/package-identifier`, oder verwenden Sie die Execute-Methode: Der Status behält dann den eigenen Code der Operation. Führen Sie nach einem fehlgeschlagenen Capture `reset` aus.
- **Wenn AI Object Matching nach einer fehlgeschlagenen Inferenz Requests ignoriert:** Führen Sie `reset` aus; es wird sofort ausgeführt.
- **Wenn der Stream von AI Object Matching läuft (Status `100002`):** Stoppen Sie zuerst den Stream.
- **Wenn ein Fehler des Cam Driver nach etwa 100 ms aus dem Status verschwindet:** Prüfen Sie eine Verbindung mit `device-info/is-connected`, nicht mit dem Status.
- **Wenn der Cam Driver keine Lizenz hat (Status `-4`):** Siehe [LumiScan Lizenzierung](https://docs.hdvisionsystems.com/de/lumiscan-licensing-de/1.0.4/index.html).

Siehe [Unterschiede zwischen den Apps](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/handshake.html#differences).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Funktion, dem Schritt, an dem der Handshake stehen bleibt, und den Werten von `ready`, `request`, `control/status/code` und `output/package-identifier`.

## Streams {#streams}

### Problem: Ein Stream liefert nichts {#stream-nothing}

**Symptome**

Von einem Stream kommen keine Ergebnisse an: `output/stream/active` bleibt `false`, oder die Zähler unter `…/stream/statistics/` steigen nicht mehr. Nach einem Neustart kommen keine Bilder an.

**Mögliche Ursachen**

- Die Eingaben wurden geschrieben, aber `execute` wurde nicht aufgerufen. Die Eingaben wirken erst bei `execute`; `enable` allein zu schreiben startet nichts.
- `enable` ist `true` ohne Adresse. Der Aufruf wird abgelehnt (`Rejected`, ctrlX `DL_INVALID_VALUE`), und nichts ändert sich.
- Die `address` des Konsumenten ist nicht der Stream-Ordner des Produzenten.
- Das Modul kann nicht laufen: Lizenz, Netz nicht geladen oder Neustart erforderlich.
- Der Cam Driver wurde neu gestartet: Sein Stream und die Kameraverbindung bleiben bei einem Neustart nicht erhalten.
- `connect-camera`, `disconnect-camera` oder `reset` hat den Stream des Cam Driver gestoppt.
- Nichts triggert die Kamera. Der Cam Driver triggert die Kamera nie von selbst.
- Calibration: Ihr Abschnitt `stream` hat keinen `onEntry`-Schritt, der angibt, wie die Quelle zu lesen ist.

**Diagnose**

1. Lesen Sie an der Kamera `control/publish/output/stream/active` - erwartet: `true`.

2. Lesen Sie am Konsumenten `control/subscribe/output/stream/active` - erwartet: `true`.

3. Lesen Sie am Konsumenten `setting/stream/…` - erwartet: `enable` ist `true`, und `address` ist der Stream-Ordner des Produzenten, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`.

4. Verfolgen Sie die Kette mit den Zählern unter `…/stream/statistics/` - erwartet: Sie steigen. Der erste Zähler, der nicht steigt, zeigt, wo die Kette stehen bleibt. Siehe [Die Kette verfolgen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#counters).

   a. Der Cam Driver zählt keine `frames`: Nichts triggert die Kamera.

   b. Calibration: `failed-updates` steigt, und es erscheinen keine Punkte: Der `onEntry`-Schritt fehlt.

   c. Finder und Code Reader: `control/subscribe/output/stream/last-failure` nennt, warum das letzte Element fehlgeschlagen ist.

5. Lesen Sie `control/status/code` und das Log des Moduls, an dem die Kette stehen bleibt.

**Lösung**

- **Wenn `execute` nicht aufgerufen wurde:** Rufen Sie nach dem Schreiben der Eingaben `control/subscribe/execute` (bei einem Konsumenten) oder `control/publish/execute` (beim Cam Driver) auf. Warten Sie dann, bis `output/stream/active` `true` ist.

- **Wenn `enable` `true` ohne Adresse ist:** Schreiben Sie `control/subscribe/input/address` und rufen Sie dann `control/subscribe/execute` auf.

- **Wenn die Adresse nicht der Stream-Ordner des Produzenten ist:** Schreiben Sie den Ordner, zum Beispiel `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, und rufen Sie `execute` auf.

- **Wenn das Modul nicht laufen kann:** Beheben Sie die Ursache, die `control/status/code` und das Log nennen. Zu einem erforderlichen Neustart siehe [Problem: Status `-5` (`restartRequired`) oder `ResourceUnavailable` bei jedem Aufruf](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#faq-restart-required).

- **Wenn der Cam Driver neu gestartet wurde oder der Stream durch `connect-camera`, `disconnect-camera` oder `reset` gestoppt wurde:**

  a. Führen Sie den Handshake `connect-camera` aus.

  b. Rufen Sie `control/publish/execute` mit `enable` = `true` auf.

  c. Die Konsumenten abonnieren von selbst erneut.

- **Wenn nichts die Kamera triggert:** Prüfen Sie ihren Trigger-Modus oder rufen Sie `control/trigger/execute` auf.

- **Wenn der `onEntry`-Schritt von Calibration fehlt:** Ergänzen Sie ihn im Abschnitt `stream`. Siehe das Handbuch von Calibration.

Siehe [Stream starten und stoppen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#running).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Werten von `output/stream/active`, `setting/stream/…` und den Zählern unter `…/stream/statistics/` jedes Moduls der Kette.

### Problem: Stream-Ergebnisse sind veraltet oder vermischt {#ts-stream-results-mixed}

**Symptome**

Die Ergebnisse, die Ihr Programm liest, sind veraltet, oder Werte verschiedener Ergebnisse sind vermischt.

**Mögliche Ursachen**

- Ihr Programm hat gelesen, während ein neues Ergebnis geschrieben wurde.

**Diagnose**

1. Prüfen Sie, wie Ihr Programm die einfachen Ausgabeknoten liest - erwartet: Es liest sie, nachdem sich `output/package-identifier` geändert hat. `output/package-identifier` wird zuletzt geschrieben.

**Lösung**

- **Wenn Ihr Programm liest, während ein neues Ergebnis geschrieben wird:** Lesen Sie die Ausgaben, wenn sich `output/package-identifier` ändert, oder abonnieren Sie einen einzelnen Knoten wie `plain-points` von Calibration. Siehe [Neuestes Ergebnis behalten](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/streams.html#keep-latest).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Knoten, die Ihr Programm liest, und deren Reihenfolge.

## OPC UA Connector {#opc-ua}

### Problem: Ein OPC-UA-Client kann sich nicht verbinden {#ts-opcua-cannot-connect}

**Symptome**

Der Client kann sich nicht mit `opc.tcp://<pc>:4840` verbinden.

**Mögliche Ursachen**

- Der Connector läuft nicht: Er wurde vor dem Broker gestartet und hat sich beendet, siehe [Problem: Das Fenster des Connectors schließt sich sofort](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#ts-opcua-window-closes).
- Die Firewall des PCs blockiert TCP-Port 4840.
- Der Client besteht auf einem sicheren Kanal. Der Connector unterstützt nur Security Policy **None** und anonyme Anmeldung.
- Der Connector wurde auf einem anderen Port gestartet (`--port`).

**Diagnose**

1. Prüfen Sie, ob der Connector läuft - erwartet: Sein Fenster ist geöffnet.
2. Prüfen Sie die Firewall des PCs - erwartet: TCP 4840 ist für die Adresse der SPS oder des Clients geöffnet.
3. Prüfen Sie die Sicherheitseinstellungen des Clients - erwartet: Security Policy **None**, anonyme Anmeldung.
4. Prüfen Sie die Optionen des Connectors - erwartet: der Port, den der Client verwendet.

**Lösung**

- **Wenn der Connector nicht läuft:** Starten Sie zuerst die Apps, dann den Connector.
- **Wenn die Firewall den Port blockiert:** Öffnen Sie TCP 4840 nur für die Adresse der SPS.
- **Wenn der Client auf einem sicheren Kanal besteht:** Stellen Sie ihn auf Security Policy **None** und anonyme Anmeldung. Zertifikate, Benutzernamen und Verschlüsselung werden nicht unterstützt. Siehe [Sicherheit](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#security).
- **Wenn der Connector auf einem anderen Port läuft:** Verbinden Sie sich mit diesem Port.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Optionen des Connectors, seinem Log und der Fehlermeldung des Clients.

### Problem: Das Fenster des Connectors schließt sich sofort {#ts-opcua-window-closes}

**Symptome**

Das Fenster des OPC UA Connector schließt sich direkt nach dem Start; der Connector beendet sich mit Exit-Code 1.

**Mögliche Ursachen**

- Es läuft kein Broker. Der Connector startet nie einen Broker: Ohne Broker protokolliert er den Grund und beendet sich.
- Die `--keryx-url` des Connectors nennt einen anderen Broker als den, den die Apps verwenden.

**Diagnose**

1. Prüfen Sie, ob die Apps laufen - erwartet: Die Keryx-Seite zeigt `hdvisionsystems` mit den Apps.
2. Vergleichen Sie die `--keryx-url` des Connectors mit der Broker-Adresse, die die Apps in ihren Logs nennen - erwartet: dieselbe Adresse.
3. Lesen Sie das Log des Connectors - erwartet: der Grund, warum er sich beendet hat.

**Lösung**

- **Wenn kein Broker läuft:** Starten Sie zuerst die Apps, dann den Connector.
- **Wenn der Connector eine andere Adresse verwendet:** Übergeben Sie ihm dieselbe `--keryx-url` wie den Apps.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Optionen des Connectors und seinem Log.

### Problem: `Objects` ist leer oder enthält kein `hdvisionsystems` {#ts-opcua-objects-empty}

**Symptome**

Der Client ist verbunden, aber `Objects` ist leer oder enthält kein `hdvisionsystems`.

**Mögliche Ursachen**

- Die Apps laufen nicht.
- Die `--keryx-url` des Connectors nennt einen anderen Broker als den, den die Apps verwenden.
- Eine App wurde gerade erst gestartet: Der Connector durchläuft den Baum alle 2 Sekunden erneut.

**Diagnose**

1. Prüfen Sie, ob die Apps laufen - erwartet: Die Keryx-Seite zeigt `hdvisionsystems` mit den Apps.
2. Vergleichen Sie die `--keryx-url` des Connectors mit der Broker-Adresse, die die Apps in ihren Logs nennen - erwartet: dieselbe Adresse.
3. Browsen Sie nach etwa 2 Sekunden erneut - erwartet: Eine später gestartete App erscheint.

**Lösung**

- **Wenn die Apps nicht laufen:** Starten Sie sie.
- **Wenn der Connector eine andere Adresse verwendet:** Starten Sie ihn mit derselben `--keryx-url` wie die Apps neu.
- **Wenn eine App gerade erst gestartet wurde:** Browsen Sie erneut. Es gibt keine Model-Change-Events: Ein Client, der sein Browse-Ergebnis zwischengespeichert hat, muss erneut browsen.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Optionen des Connectors und seinem Log.

### Problem: `BadNodeIdUnknown` {#ts-opcua-bad-node-id}

**Symptome**

Ein Lese-, Schreib- oder Methodenaufruf über OPC UA antwortet mit `BadNodeIdUnknown`.

**Mögliche Ursachen**

- Die Adresse, ihre Groß-/Kleinschreibung oder der Namespace-Index ist falsch.
- Die App läuft nicht.
- Das Modul fehlt.

**Diagnose**

1. Ermitteln Sie den Namespace-Index `n` der URI `urn:hdvisionsystems:keryx` im `NamespaceArray` des Servers - erwartet: der Index, den Ihr Programm verwendet.
2. Prüfen Sie die NodeId - erwartet: `ns=<n>;s=<address>`, mit der Data-Layer-Adresse in Kleinbuchstaben, zum Beispiel `ns=<n>;s=hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code`.
3. Lesen Sie `hdvisionsystems/<app>/system/found-modules` - erwartet: Das Modul ist aufgeführt.

**Lösung**

- **Wenn der Namespace-Index falsch ist:** Ermitteln Sie ihn nach jedem Verbindungsaufbau anhand seiner URI. Schreiben Sie keinen festen Index in Ihr Programm: Bei einem anderen Start kann er anders nummeriert sein.
- **Wenn die Adresse falsch ist:** Korrigieren Sie Groß-/Kleinschreibung und Schreibweise, siehe [Problem: Ein Knoten ist „not found"](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#node-not-found).
- **Wenn die App nicht läuft oder das Modul fehlt:** Siehe [Problem: Eine App oder ein Modul fehlt im Baum](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#app-missing).

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der NodeId und dem Inhalt des `NamespaceArray` des Servers.

### Problem: `BadTypeMismatch` beim Schreiben {#faq-opcua-type-mismatch}

**Symptome**

Ein Schreibvorgang über OPC UA antwortet mit `BadTypeMismatch`.

**Mögliche Ursachen**

- Der Typ des Werts entspricht nicht exakt dem Typ des Knotens. Der Connector konvertiert nicht: Ein `Boolean`-Knoten nimmt einen Boolean an, nicht 0 oder 1; ein `UInt32`-Knoten nimmt UInt32 an, nicht Int32.

**Diagnose**

1. Ermitteln Sie den Typ des Knotens, zum Beispiel auf der Keryx-Seite (wählen Sie den Knoten aus) - erwartet: der Typ, den Ihr Client sendet, zugeordnet wie unter [Lesen, Schreiben und Typen](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#types).

**Lösung**

- **Wenn der Typ abweicht:** Senden Sie exakt den Typ des Knotens, zum Beispiel `Boolean` für Flags und `UInt32` für `queue-size`.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit der Adresse des Knotens und dem Typ, den Ihr Client sendet.

### Problem: Eine Subscription erhält nur einen Wert oder verpasst Ergebnisse {#ts-opcua-subscription}

**Symptome**

Ein Monitored Item meldet nur einen Wert oder weniger Benachrichtigungen, als die App pusht.

**Mögliche Ursachen**

- Die Einstellungen des Monitored Item weichen von den empfohlenen ab: Sampling Interval nicht `0`, eine Queue Size von 1 (nur der neueste Push kommt an) oder ein anderer DataChange Trigger als `StatusValueTimestamp` (zwei identische Ergebnisse zählen als eines).
- Der Knoten pusht nicht: Ein Wert, der zu groß ist, um gepusht zu werden, meldet sich im Event-Modus nie.
- Der Connector hat beim Start festgestellt, dass der Event-Modus nicht funktioniert, und tastet jedes Item per Timer ab.

**Diagnose**

1. Vergleichen Sie die Subscription mit [Subscriptions](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/opc-ua.html#subscriptions) - erwartet: Publishing Interval 10 ms oder mehr, Sampling Interval `0`, Queue Size 10 bis 100, DataChange Trigger `StatusValueTimestamp`, DiscardOldest `true`.
2. Lesen Sie zuerst das Log des Connectors - erwartet: keine Meldung, dass er im Sampling-Modus arbeitet.

**Lösung**

- **Wenn die Einstellungen abweichen:** Stellen Sie sie wie empfohlen ein. Verwenden Sie Sampling Interval `0` nur bei Knoten, die pushen.
- **Wenn der Knoten nicht pusht:** Verwenden Sie dafür ein positives Sampling Interval.
- **Wenn der Connector im Sampling-Modus arbeitet:** Wenden Sie sich mit seinem Log an den Support.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit den Einstellungen der Subscription und dem Log des Connectors.

### Problem: Benachrichtigungen bleiben nach einem Neustart des Connectors oder einer App aus {#ts-opcua-notifications-stop}

**Symptome**

Nach einem Neustart des Connectors erhält der Client keine Benachrichtigungen. Nach einem Neustart einer App meldet sich ein Monitored Item nicht wieder, oder Lesezugriffe liefern `BadTimeout`, dann `BadNoCommunication`.

**Mögliche Ursachen**

- Der Connector wurde neu gestartet: Die Subscriptions des Clients sind weg.
- Eine App wurde gestoppt oder neu gestartet. Eine App, die stoppt, behält ihre Knoten im Baum; Lesezugriffe darauf liefern `BadTimeout`, dann `BadNoCommunication`, bis sich die App wieder registriert. Nach dem Neustart ist die Kamera nicht verbunden und der Stream des Cam Driver ist aus.

**Diagnose**

1. Prüfen Sie, ob der Connector oder eine App zu dem Zeitpunkt neu gestartet wurde, an dem die Benachrichtigungen ausblieben.
2. Lesen Sie einen Knoten der App - erwartet: ein Wert, nicht `BadTimeout` oder `BadNoCommunication`.

**Lösung**

- **Wenn der Connector neu gestartet wurde:** Verbinden Sie sich neu und legen Sie die Subscriptions erneut an.

- **Wenn eine App neu gestartet wurde:**

  a. Warten Sie, bis sich die App wieder registriert hat.

  b. Führen Sie Ihre Startsequenz erneut aus.

  c. Meldet sich ein Monitored Item nicht wieder, löschen Sie es und legen Sie es neu an.

**Wenn das Problem weiterhin besteht**

Senden Sie die unter [Informationen für den Support](https://docs.hdvisionsystems.com/de/lumiscan-keryx-de/1.0.0/troubleshooting.html#support-information) genannten Informationen an den Support, zusammen mit dem Zeitpunkt des Neustarts und dem Log des Connectors.

## Informationen für den Support {#support-information}

Besteht das Problem weiter, wenden Sie sich an [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com), +49 6221 6721905. Für Lizenzen: [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com). Senden Sie bitte:

- die App und ihre Version;
- die Plattform: Windows 11, Ubuntu 24.04 oder ctrlX OS mit seiner Version;
- Datum und Uhrzeit des Fehlers;
- das Log der App; auf ctrlX OS aus dem Systemprotokoll (Logbuch der ctrlX-Weboberfläche oder `journalctl`);
- auf einem PC das Log des Brokers aus `C:\ProgramData\HD Vision Systems GmbH\LumiScan Keryx` (Windows) oder `/tmp/lumiscan-keryx` (Ubuntu) und, falls Sie sie verwenden, die Logs des OPC UA Connector und von LumiScan Keryx Utilities;
- den Kommunikationsstatus: die Data-Layer-Adresse, die die Apps verwenden, den Inhalt von `system/found-modules` und `system/status-text`, den Modulstatus (`control/status/code` und `text` bzw. `status-code` und `status-text` eines Finders), das Ergebnis eines abgelehnten Aufrufs und bei OPC UA den Statuscode und die Optionen des Connectors;
- die Konfiguration: die Einstellungsdateien der App (auf einem PC in `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\<program>\etc\<settings folder>`, auf ctrlX OS im Ordner der App unter `/var/snap/rexroth-solutions/common/solutions/activeConfiguration`) oder den Inhalt von `system/settings`, und auf einem PC `broker.json`.
