General Concept of Handshake

The communication process in the LumiScan CamDriver 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 for every operation except trigger. Most operations can also be started with a single write to their execute node — see Execute a Method for a comparison of the two ways.

Each operation has a <parent address>/<functionality name>/ready node (read-only, set by the application: true when the functionality may be started) and a <parent address>/<functionality name>/request node (writable, set by you to start it). The general handshake - its addresses, sequence and rules - is described in Handshake. This page describes how the Cam Driver follows it.

Functionality Execution

To avoid repeating the entire address, in this section the invariant part containing the parent address and the variable functionality name (capture, connect-camera, disconnect-camera) have been replaced by XXX.
Thus, the address: hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/ready will be written as XXX/ready.

Accordingly, the address: hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/request will be written as XXX/request.

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.

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

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

  2. Set XXX/request to True.

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

  4. Set XXX/request to False.

  5. Wait for the functionality to finish, and read its outcome: see the table below.

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

Only one request is served at a time, in this order: reset, connect-camera, disconnect-camera, save, capture, load, list-images, remove.

Table 1. When each functionality runs
Functionality Runs At the end

capture

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

Success: status/code 0, capture/ready True, and output/package-identifier has grown by one.
Failure: status/code stays 3, not the capture’s error code, and capture/ready stays False until a reset succeeds.

connect-camera, disconnect-camera, reset, save, load, list-images, remove

After XXX/request has fallen. status/code is 3 until then, and 2 while it runs.

status/code 0, or an error (below 0).

A failed capture, reset, save or load is latched: its status stays until a reset succeeds. (A save before anything was captured, -10005, is not latched.) Any other error stays on status/code for about 100 ms only, then 0 replaces it. So check whether the camera is connected with hdvisionsystems/lumiscan-cam-driver/<camera name>/device-info/is-connected, not with the status.

To read the outcome of a capture directly, use control/capture/execute instead. The status then keeps the capture’s own code. See Execute a Method.