General Concept of Handshake

The communication process in the LumiScan AI Object Matching application is based on the general concept of handshake. The naming convention for handshake parameters usually consists of the functionality and the names -ready or -request.

The handshake works the same on the ctrlX Data Layer and on LumiScan Keryx. Its general rules are described in Handshake; this page describes how AI Object Matching follows it and where it differs.

Table 1. General Concept of Handshake: Address
Address Description

<parent address>/<functionality name>/ready

Read-Only, controlled by our app to indicate whether the relevant functionality is allowed to be executed.

<parent address>/<functionality name>/request

Writable. It is used by user to trigger our application to execute relevant functionality.

Functionality Execution

To avoid repeating the entire address, in this section the invariant part containing the parent address and the variable functionality name (inference, reset) have been replaced by XXX.

Thus, the address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/ready will be written as XXX/ready.

Accordingly, the address: hdvisionsystems/lumiscan-ai-object-matching/<network name>/control/inference/request will be written as XXX/request.

In order to execute a functionality, you need to run the following steps (see also image Functionality Execution Steps):

  1. Wait until XXX/ready is set to True.

  2. Set XXX/request to True.

    Make sure there is only one process is accessing XXX/request at a time.

    The result of execution is undefined when:

    1. ProcessA set XXX/request to True.

    2. ProcessB set XXX/request to False without considering ProcessA.

    3. Our application might therefore miss XXX/request from ProcessA.

  3. Wait until XXX/ready changes to False: the application has seen the request.

  4. Set XXX/request to False.

  5. Wait until XXX/ready is True again: the functionality has finished.

  6. Read control/status/code and the results.

Functionality Execution Steps
%% The ready/request handshake. Rendered by Mermaid in the browser; edit and preview at https://mermaid.live
sequenceDiagram
  autonumber
  participant C as Client (PLC or program)
  participant M as Module
  M-->>C: ready = true: the function can be started
  C->>M: request = true
  M-->>C: ready = false: the request was seen
  C->>M: request = false
  Note over M: runs the function
  M-->>C: ready = true: the function has finished
  C->>M: read control/status/code and output/

When a Functionality Runs

Not every functionality waits for XXX/request to fall before it starts:

Table 2. When each functionality runs
Functionality Runs status/code at the end

inference

At once, as soon as the application sees the request. status/code is 2 (running) while it runs, then 3 (waitingForClient) while the application waits for XXX/request to fall.

3, whether the inference succeeded or not. See Outcome of an Inference.

reset

At once, without waiting for XXX/request to fall. It runs again on every cycle while XXX/request stays True.

0

list-result-files, load, save, save-result-image, remove

After XXX/request has fallen. status/code is 2 from the request until they finish.

0, or an error (below 0)

While the module is in error, it ignores every request but reset. XXX/ready still shows True, but the request is never acknowledged: XXX/ready does not fall. Request reset.

While the image stream runs, inference/ready is False. An inference requested anyway sets status/code to 100002 (StreamActive) and is not acknowledged.

Outcome of an Inference

An inference requested through the handshake ends at status/code 3, whatever its outcome. Tell the outcome by hdvisionsystems/lumiscan-ai-object-matching/<network name>/output/package-identifier: it grows by one with every successful inference, and only then.

If it did not grow, the inference failed. Either:

  • the image could not be read: there was no image, or it was empty. Provide an image and request the inference again; or

  • the inference itself failed. The module is then in error and ignores every request but reset (see above). Request reset, and check the application log for the cause.

To read the outcome directly, start the inference with control/inference/execute instead. status/code then keeps it: 0, 100001 or -1. See Execute a Method.