---
title: "LumiScan Keryx on a PC"
description: "LumiScan Keryx on Windows 11 and Ubuntu 24.04 - its broker, address and ports, automatic start, the Keryx page, files, options and environment variables."
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/keryx.html"
---

# LumiScan Keryx on a PC

> [!NOTE]
> On ctrlX OS the apps use the ctrlX Data Layer instead: see [ctrlX Data Layer on ctrlX OS](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html).

**LumiScan Keryx** is the Data Layer of HD Vision Systems for PCs. It offers the same interface as the ctrlX Data Layer; the name comes from the Greek *kēryx*, the herald.

On a PC the LumiScan apps exchange their data through LumiScan Keryx. One program, the **broker**, connects them: every app registers its nodes there, and every client - another app, Cockpit, the OPC UA Connector, your program - reads, writes and calls through it.

## The broker {#broker}

|   |   |
| --- | --- |
| Program | `krxsystem`, part of **LumiScan Keryx** |
| Default address | `tcp://127.0.0.1:5555`. The broker also uses the next port, 5556, for its notifications |
| Reachable from | this PC only (`127.0.0.1`): the broker has no authentication |
| One per PC | All apps of one installation use the same broker |

**You normally do not start the broker yourself.** When an app starts and no broker answers on this PC, it starts `krxsystem` as a separate process. Several apps started together start one broker. The broker keeps running when the apps end, and the apps start it again if it stops. Providers register again and subscriptions are renewed by themselves once the broker answers.

The first start is slower: the broker takes a few seconds to answer. An app that starts in that time logs that it is waiting for the broker, and connects as soon as it answers.

The **OPC UA Connector** is the exception: it never starts a broker. Start it after the apps, see [OPC UA Connector](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/opc-ua.html).

## Installing on Windows {#installing}

1. Install **LumiScan Keryx** first, then the apps.
2. Run each installer as administrator. To reinstall the same version, uninstall the old one first: an installer only accepts a higher version.
3. Open a **new** terminal before you start an app from the command line.

The LumiScan Keryx installer sets two machine-wide environment variables, `HDV_KERYX_BROKER` and `HDV_KERYX_PAGE`. They tell every app which broker program to start and which program shows the Keryx page. A program or terminal that was already open does not see them. Without them, an app starts the `krxsystem` beside its own program.

## The Keryx page {#data-layer-page}

Every broker comes with a web page that shows its tree: `http://127.0.0.1:7555/` for the default broker (the broker’s port + 2000). Starting **LumiScan Keryx** opens the same page in a window, and starts the broker if none runs.

- Select a node to see its value, type and permissions.
- A writable node has an editor, and a method has an **Invoke** button.
- A watch list follows values as they change.
- **Shut down broker** stops the broker. The apps keep running and wait: they do not start it again until you click **Start broker**, open the LumiScan Keryx window, start a `krxsystem` by hand, or restart the PC.

The LumiScan Keryx window and the Keryx page are part of the Windows installation.

## Starting the apps {#start-order}

Start the apps in any order. Wait until each has finished starting before you rely on its nodes. Start the OPC UA Connector last.

Check the start on the Keryx page (Windows) or with `krxclient tree hdvisionsystems --depth 1`: the tree shows the folder `hdvisionsystems` with one folder per running app. For each app that has modules, `hdvisionsystems/<app>/system/found-modules` lists them. If a list is empty, `hdvisionsystems/<app>/system/status-text` says why - most often a settings file that could not be loaded, or a missing licence.

To stop an app, press Ctrl+C in its console. The broker keeps running.

## Where the files are {#files}

| What | Where |
| --- | --- |
| Programs | the installation folder chosen in the installer (`Program Files`) |
| Settings of an app | `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\<program>\etc\<settings folder>`, or `%APP_RESOURCE_DIR%\etc\<settings folder>` when the environment variable `APP_RESOURCE_DIR` is set. The settings folder of each app is named in its manual |
| Broker log, records and settings (`broker.json`) | `C:\ProgramData\HD Vision Systems GmbH\LumiScan Keryx` |

On Ubuntu the broker keeps its log, records and settings in `/tmp/lumiscan-keryx`.

Every app that has settings writes an example of them into a folder of your choice, and ends:

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

It never overwrites a file. Edit the example, copy it into the settings folder and start the app.

## Options and environment variables {#options}

The same options work for every app.

| Option or variable | Effect |
| --- | --- |
| `--keryx-url <address>` | The broker to use. Default `tcp://127.0.0.1:5555`. Pass the same address to every app, to Cockpit and to the OPC UA Connector |
| `LUMISCAN_KERYX_URL` | The same, for every program on the PC. The option wins |
| `--no-keryx-autostart`, `LUMISCAN_KERYX_AUTOSTART=0` | The app does not start a broker. Start one yourself: `krxsystem --backend hdv --url <address>` |
| `HDV_KERYX_BROKER`, `HDV_KERYX_PAGE` | Set by the LumiScan Keryx installer: the broker program and the page program |

Each app names the broker address it uses in its log at start.

## Addresses other than the default {#several-brokers}

- **Another port**: `tcp://127.0.0.1:<port>`. Each port is its own broker, started by the first app that needs it. A broker takes its port and the next one, so two brokers need ports at least two apart. Its Keryx page is on the port + 2000.
- **A local socket**: `ipc://<name>`. A relative name is relative to the folder a program starts in: start the broker yourself and start every app from that same folder.
- **Another PC**: an address of another computer is only connected to, never started. The broker listens on this PC only unless its settings say otherwise, and it has no authentication. Running apps on several PCs against one broker is not covered by this manual.

## Good to know {#limits}

- Values carry no timestamp of their own: an app that needs one publishes it in a node or inside the result.
- A new subscriber gets no initial value. Read the node once, then subscribe.
- A method call that is repeated after a timeout can run twice.