Getting Started with LumiScan Keryx

In this guide you try LumiScan Keryx on a Windows PC, without a camera and without a PLC. LumiScan Cam Driver with a simulated camera provides the nodes; you are the client - first by hand on the Keryx page, then with the command line client krxclient, which works exactly as a PLC would.

When you have finished, you have:

  1. started the broker and looked at the tree,

  2. read values and written one,

  3. connected the camera with a ready/request handshake - by hand and with one command,

  4. taken an image with an execute method and checked the result,

  5. disconnected the camera again.

What you learn here works the same for every LumiScan app, on a PC and on ctrlX OS. The concept is explained in What Is LumiScan Keryx?.

This guide uses a Windows PC. On ctrlX OS, follow How To: Test with Example Images Instead of a Camera in the Cam Driver manual: it connects a simulated camera and takes an image in the ctrlX OS web interface, where the Data Layer view does what the Keryx page does here.

Before you start

  • A PC with Windows 11.

  • LumiScan Keryx and LumiScan Cam Driver installed: Keryx first, each installer as administrator. See Installing on Windows.

  • A licence for LumiScan Cam Driver: CodeMeter Runtime installed and the LumiScan Key plugged in, see LumiScan Licensing.

  • Optional: a few PNG images, to give the simulated camera something to deliver in step 6.

Open a new terminal (Command Prompt or PowerShell) after the installation, so that it knows the settings the Keryx installer made. If krxclient is not found, run it from the installation folder of LumiScan Keryx.

On Ubuntu 24.04 all krxclient commands are the same. The Keryx page and its window are part of the Windows installation only.

Step 1 - Start Keryx and open the Keryx page

  1. Start LumiScan Keryx from the Windows Start menu.

    A window opens with the Keryx page. If no broker runs yet, starting LumiScan Keryx starts it.

  2. Look at the tree. Without any app it is still empty: Keryx itself provides no nodes - the apps do.

The same page is available in any browser on this PC at http://127.0.0.1:7555/.

Done when: the Keryx page shows that the broker runs.

Step 2 - Start an app with a simulated camera

The Cam Driver writes example settings with one simulated camera. A camera whose serial number contains simulation needs no hardware.

  1. Write the example settings into a work folder:

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

    The Cam Driver writes lumiscan-cam-driver.json, the module file lumiscan-cam-driver-example-module.json and their schemas, names the folder it reads its settings from, and ends.

  2. Open the module file and check that id is camera1 and serial is simulation. If the id differs, use your id instead of camera1 in all addresses below.

  3. Copy the files into the settings folder the Cam Driver named, by default C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver.

  4. Start the Cam Driver:

    lumiscan-cam-driver

    Leave the terminal open: it shows the Cam Driver’s messages.

On the Keryx page the tree now has the folder hdvisionsystems with lumiscan-cam-driver in it.

Done when: hdvisionsystems/lumiscan-cam-driver/system/found-modules lists camera1, and the folder hdvisionsystems/lumiscan-cam-driver/camera1 exists.

Step 3 - Read values

On the Keryx page: open hdvisionsystems/lumiscan-cam-driver/camera1/control/status and select code. The page shows its value, its type and what may be done with it. 0 means ready.

With krxclient: open a second terminal and read the same node:

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

krxclient prints the value together with its type, as JSON. Three more commands help you find your way around:

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 lists the children of a folder, metadata shows what a node is and what may be done with it, tree prints a whole branch.

Done when: krxclient read shows the status code 0.

Step 4 - Write a value

Inputs are nodes that you write before you call a function. As an example, switch on the preview of the camera module, a PNG of each new image:

On the Keryx page: select hdvisionsystems/lumiscan-cam-driver/camera1/input/preview/enable, set it to true in its editor, and confirm.

With krxclient:

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

krxclient write takes the type of the node’s current value; a value that does not fit the type is refused before anything is sent.

Add the nodes you follow to the watch list of the Keryx page. It shows their values as they change, which is useful in the next step.

Done when: hdvisionsystems/lumiscan-cam-driver/camera1/input/preview/enable reads true.

Step 5 - Connect the camera with a handshake

Connecting a camera can take several seconds, so it is a handshake: you and the app take turns on two nodes, ready (set by the app) and request (set by you).

By hand, on the Keryx page

Put these nodes on the watch list:

  • 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

Then:

  1. Check that ready is true: the app can start the function.

  2. Set request to true: you ask for it.

  3. Watch ready turn false: the app has seen the request. The status code shows 3 (waiting for you).

  4. Set request back to false: you confirm. The app now connects the camera.

  5. Watch is-connected turn true, and the status code return to 0.

After a successful connection, connect-camera/ready stays false - the camera is already connected. Check the result with is-connected, not with ready.

With one command

krxclient handshake runs the same sequence the way a PLC does. To try it, first disconnect the camera - also a handshake - and then connect it again:

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

Each handshake prints the status code and text at the end. With --trace handshake.jsonl it writes every change of ready and of the status, with the time, into a file - a record of what the app did when.

Done when: hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected is true.

Step 6 - Take an image with an execute method

Taking an image is quick, so it is an execute method: one write, answered when the work is done.

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

On the Keryx page, the same method has an Invoke button.

Always check two things:

  1. Could the call run? krxclient exits with 0 when the app accepted the call, 1 when Keryx refused it - for example because the camera is not connected - and 2 on a timeout.

  2. Did it succeed? The status code is 0, and output/package-identifier has grown by one. The image is now on hdvisionsystems/lumiscan-cam-driver/camera1/output/image, with its width, height and pixel-type.

A simulated camera plays the images from its storage folder, one per capture. If the folder is empty, the capture fails: the status code is below 0, and control/status/text says why. That is a useful exercise in itself. To get images, put a few PNG files into the sub-folder camera1 of the storage folder that system/storage in lumiscan-cam-driver.json names - add a storage if there is none - restart the Cam Driver and connect again. How To: Test with Example Images Instead of a Camera shows the same on ctrlX OS; the settings are the same on a PC.

Done when: you have called capture/execute and read its outcome on control/status/code.

Step 7 - Tidy up

  1. Disconnect the camera:

    krxclient handshake hdvisionsystems/lumiscan-cam-driver/camera1/control/disconnect-camera --status hdvisionsystems/lumiscan-cam-driver/camera1/control/status

  2. Stop the Cam Driver with Ctrl+C in its terminal.

The broker keeps running; the next app you start uses it again.

What you did

You did On the Keryx page With krxclient - and in a PLC or program

Read a value

select the node

krxclient read; a PLC reads the OPC UA or ctrlX Data Layer node

Write a value

the node’s editor

krxclient write; a PLC writes the node

Run a handshake

set request, watch ready

krxclient handshake; a PLC sets request and polls ready every 50 to 100 ms

Call an execute method

Invoke

krxclient execute; over OPC UA, a method call

What next