--- title: "Getting Started with LumiScan Keryx" description: "Try LumiScan Keryx in about 30 minutes, without a camera - start the broker, look at the tree, read and write nodes, run a handshake by hand and with krxclient, call an execute method." 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/getting-started.html" --- # 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?](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/what-is-keryx.html). > [!NOTE] > This guide uses a Windows PC. On ctrlX OS, follow [How To: Test with Example Images Instead of a Camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/latest/how-tos/test-with-example-images.html) 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 {#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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html#installing). - A licence for LumiScan Cam Driver: CodeMeter Runtime installed and the LumiScan Key plugged in, see [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/index.html). - 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. > [!TIP] > 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 {#step-1} 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 {#step-2} 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: ```shell 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: ```shell 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 {#step-3} **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: ```shell 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: ```shell 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 {#step-4} 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:** ```shell 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. > [!TIP] > 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 {#step-5} 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 {#step-5-by-hand} 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`. > [!NOTE] > 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 {#step-5-krxclient} `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: ```shell 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 {#step-6} Taking an image is quick, so it is an **execute method**: one write, answered when the work is done. ```shell 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`. > [!NOTE] > 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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/latest/how-tos/test-with-example-images.html) 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 {#step-7} 1. Disconnect the camera: ```shell 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 {#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 {#next} - Use the apps from a PLC: [OPC UA Connector](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html) on a PC [Connecting a PLC](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html#connecting-a-plc) on ctrlX OS. - Receive every image without a call per image: [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html). - The rules of each pattern: [Handshake](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html) and [Execute Methods](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html). - What the status codes mean: [Status Codes and Results](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html). - A complete application with camera, part search and PLC: [Your First Industrial Vision Application](https://docs.hdvisionsystems.com/en/getting-started/first-application.html).