---
title: "Integrating LumiScan into Your Application"
description: "For software developers: connect your own program to the LumiScan vision apps - choose the interface, find the nodes, call a function, run a handshake, read results, receive every image, handle errors."
product: "LumiScan Documentation"
component: "ROOT"
language: "en"
url: "https://docs.hdvisionsystems.com/en/getting-started/integrating.html"
---

# Integrating LumiScan into Your Application – LumiScan Documentation

You end with your own program capturing an image with the Cam Driver and reading a Template Finder result. Seven steps; each one ends with **Done when** and points to the next.

The examples assume the apps are installed and a camera is configured - steps 1 to 4 of [Your First Industrial Vision Application](https://docs.hdvisionsystems.com/en/getting-started/first-application.html). The LumiScan apps have no SDK of their own: every function is a node of the Data Layer, so any client that can read, write and call Data Layer or OPC UA nodes can use them.

**Your progress - tick off each step as you finish it**

- [1. Choose the interface](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-1)
- [2. Find the nodes](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-2)
- [3. Connect](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-3)
- [4. Call a function](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-4)
- [5. Run a long operation as a handshake](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-5)
- [6. Read results and receive every image](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-6)
- [7. Handle errors](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-7)

## Step 1 of 7 - Choose the interface {#step-1}

| Your program runs | Interface | Notes |
| --- | --- | --- |
| on the ctrlX device (an app of its own) | ctrlX Data Layer client | as any ctrlX app does, for example one built with the ctrlX AUTOMATION SDK |
| on a PC or another machine in the network | OPC UA, through the LumiScan OPC UA Connector | any OPC UA client library, any language; the apps run on a PC with LumiScan Keryx |
| in a script or a test | `krxclient`, the command line client of LumiScan Keryx | `read`, `write`, `execute`, `subscribe`, `handshake`, `browse` |

The node addresses and call patterns are the same on ctrlX OS and on a PC, so the logic you write does not depend on the platform. See [ctrlX Data Layer and LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/platforms.html).

**Done when:** you know which client your program uses.\
**Next:** [Step 2 - Find the nodes](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-2)

## Step 2 of 7 - Find the nodes {#step-2}

Every address has the same shape:

```
hdvisionsystems/<app>/<module>/<folder>/...   the nodes of one module (a camera, a finder module, ...)
hdvisionsystems/<app>/system/...              what concerns the whole app
types/hdvisionsystems/<app>/<type>            the FlatBuffers types the app publishes
```

`<folder>` is `control/` (the functions and the module status), `input/`, `output/` or `setting/`. An execute method keeps its own inputs and outputs under its function, for example `hdvisionsystems/lumiscan-template-finder/module-1/find-template/input/…` and `…/output/result`.

The nodes of an app are listed in the **Data Layer Reference** of its manual; look at the live tree in the Data Layer view of the ctrlX OS web interface or, on a PC, on `http://127.0.0.1:7555/`. See [Addresses and Modules](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/addresses.html).

**Done when:** you have found `hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute` and `hdvisionsystems/lumiscan-template-finder/module-1/find-template/execute` in the tree.\
**Next:** [Step 3 - Connect](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-3)

## Step 3 of 7 - Connect {#step-3}

- **OPC UA:** start the OPC UA Connector after the apps. Endpoint `opc.tcp://<pc>:4840`, security policy **None**, anonymous. Look up the namespace index of `urn:hdvisionsystems:keryx` in the server’s `NamespaceArray` - never hard-code it. A node’s NodeId is its Data Layer address: `ns=<n>;s=hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code`.
- **krxclient:** it connects to the broker on `tcp://127.0.0.1:5555`; set another one with `--keryx-url` or `HDV_KERYX_URL`.
- **ctrlX Data Layer client:** connect to the Data Layer of the device as your SDK describes.

> [!WARNING]
> The OPC UA Connector has no authentication or encryption. Run it on a network you trust and open TCP 4840 in the firewall for your client’s address only. See [Security](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html#security).

**Done when:** your program reads `hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code`.\
**Next:** [Step 4 - Call a function](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-4)

## Step 4 of 7 - Call a function {#step-4}

Operations that finish within about 1 s are **execute methods**: write the inputs (separate nodes), then call `execute`; the call returns when the operation is done.

```shell
krxclient execute hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute
krxclient read    hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code
krxclient write   hdvisionsystems/lumiscan-template-finder/module-1/find-template/input/template-name screw
krxclient execute hdvisionsystems/lumiscan-template-finder/module-1/find-template/execute
krxclient read    hdvisionsystems/lumiscan-template-finder/module-1/find-template/output/status-code
```

With OPC UA, call the method with the **Call** service: `objectId` is the parent address (`…/camera1/control/capture`), `methodId` the `execute` node. Set the client’s call timeout above your slowest method; the connector waits up to 60 s.

**Check both outcomes:** the result of the call says whether the operation could run at all, the status node whether it succeeded. See [Execute Methods](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html).

**Done when:** your program captures an image and runs a search.\
**Next:** [Step 5 - Run a long operation as a handshake](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-5)

## Step 5 of 7 - Run a long operation as a handshake {#step-5}

Operations that can take longer - connecting a camera, a reset, an inference - are **handshakes**, so that nothing blocks: wait for `ready` = `true`, set `request` = `true`, wait for `ready` = `false`, set `request` back to `false`, then check the status and the outputs. Poll at 50 to 100 ms.

In a script, `krxclient handshake` runs this sequence for you, see [krxclient](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/tools.html#krxclient).

Which pattern a function uses is in the app’s Data Layer Reference; the rules are in [Choosing a Pattern](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/calling-functions.html) and [Handshake](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html).

**Done when:** your program connects the camera itself (`hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected` = `true`).\
**Next:** [Step 6 - Read results and receive every image](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-6)

## Step 6 of 7 - Read results and receive every image {#step-6}

- **Plain values** - numbers, booleans, strings, arrays - are read directly. Build your logic on them.
- **Structured results and images** are FlatBuffers; their schemas are on the Data Layer under `types/hdvisionsystems/<app>/…`. Decode them with the FlatBuffers library of your language.
- **Every image, without a call per image:** let the processing app subscribe to the camera’s stream and subscribe your program to the app’s result node (OPC UA: a subscription on that node):
  ```shell
  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
  ```

Image streams are experimental in the current releases. See [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html) and [Addresses and Modules](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/addresses.html).

**Done when:** your program reads the Template Finder result for an image.\
**Next:** [Step 7 - Handle errors](https://docs.hdvisionsystems.com/en/getting-started/integrating.html#step-7)

## Step 7 of 7 - Handle errors {#step-7}

- A refused call (`Rejected` on LumiScan Keryx, `DL_INVALID_VALUE` on the ctrlX Data Layer, an OPC UA status code through the connector) means the operation did not run - nothing was queued.
- A call that ran can still fail: read the module’s `control/status/code`, or the finder’s `<method>/output/status-code`, after every call.
- A module runs one operation at a time: a call while another one runs is refused as busy (`TooManyOperations`, ctrlX `DL_TOO_MANY_OPERATIONS`). Retry it once the running operation has finished.

The codes and their meaning: [Status Codes and Results](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html); when something does not work: [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html).

**Done when:** your program reacts to a refused call and to a failed operation - it is integrated.

## What next

- All nodes of an app: the **Data Layer Reference** in its manual, linked from the [overview page](https://docs.hdvisionsystems.com/en/index.html).
- Everything about the interface: [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html).