---
title: "Handshake"
description: "The ready/request handshake of the LumiScan apps - addresses, the sequence a client follows, the module's status during it, the rules, and how the Cam Driver and AI Object Matching differ."
product: "LumiScan Keryx"
component: "lumiscan-keryx"
version: "1.0.0"
display_version: "1.0.0.7"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html"
---

# Handshake – LumiScan Keryx

The handshake is for an operation that can take longer than about 1 s, or that a client must start without waiting for it. Client and module take turns on two nodes, `ready` and `request`. Nobody waits inside a call: the client polls, and the module answers through nodes.

The Cam Driver, AI Object Matching and Calibration offer handshakes.

## Addresses {#addresses}

| Address | Type | Meaning |
| --- | --- | --- |
| `<module>/control/<function>/ready` | bool, read-only | set by the module: `true` when the function can be started |
| `<module>/control/<function>/request` | bool, writable | set by the client to start the function |
| `<module>/control/status/code` | int32, read-only | the module’s status, one for all its functions. See [Status Codes and Results](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html) |
| `<module>/control/status/text` | string, read-only | the same as text, for people - use the code in program logic |
| `<module>/input/…` | writable | the function’s inputs, written before the request |
| `<module>/output/…` | read-only | its results |
| `<module>/output/package-identifier` | read-only | counts finished operations: a new value means new outputs |

`<module>` is `hdvisionsystems/<app>/<module name>`, for example `hdvisionsystems/lumiscan-calibration/plane1/control/transform/request`.

## The sequence {#sequence}

1. Wait until `control/<function>/ready` is `true`.
2. Write the function’s inputs.
3. Set `control/<function>/request` to `true`.
4. Wait until `ready` is `false`: the module has seen the request.
5. Set `request` to `false`.
6. Wait until `ready` is `true` again: the function has finished.
7. Read `control/status/code` and the results under `output/`. `output/package-identifier` has grown by one.

Poll at 50 to 100 ms.

## What the module shows {#module-states}

As Calibration runs it:

| Step | `ready` | `request` | `status/code` |
| --- | --- | --- | --- |
| Idle | `true` | `false` | `0` ready, or the last error |
| The client requests | `true` | `true` |   |
| The module acknowledges | `false` | `true` | `3` waitingForClient |
| The client confirms; the function runs | `false` | `false` | `2` running |
| Done | `true` | `false` | `0`, or an error (below `0`) |

## Rules {#rules}

- **Only one program writes a `request` node.** Two programs writing it independently can lose a request. A program that cannot coordinate with others uses the [execute method](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html), which refuses a second call while one runs.
- **The module waits for `request` to fall, for as long as it takes.** There is no timeout: a `request` still `true` afterwards would be read as a new request.
- **A handshake and an execute method of the same module share one lock.** While a handshake runs, an execute call of the same module answers that it is busy.

## How the apps differ {#differences}

Calibration follows the sequence exactly. The Cam Driver and AI Object Matching differ in ways a PLC program must know:

| App | Difference |
| --- | --- |
| Cam Driver | `capture` starts as soon as the request is seen, without waiting for `request` to fall. A **failed capture ends at status `3`**, not at its own error code, and `capture/ready` stays `false` until a `reset` succeeds. A failed `reset`, `save` or `load` also stays until a `reset` succeeds. Any other error stays on the status for about 100 ms only: check a connection with `device-info/is-connected`, not with the status. Without a licence every `ready` is `false` and the status is `-4`. |
| AI Object Matching | `inference` starts as soon as the request is seen and **ends at status `3` whatever its outcome**; only `output/package-identifier`, which grows on success alone, tells that it succeeded. After a failed inference, and while the module has an error, every request but `reset` is ignored. `reset` runs at once. While the stream runs, `inference/ready` is `false` and a request gets status `100002`. |

To read the outcome of a Cam Driver `capture` or an AI `inference` directly, use its execute method: the status then keeps the operation’s own code.