LumiScan Keryx on a PC

On ctrlX OS the apps use the ctrlX Data Layer instead: see ctrlX Data Layer on ctrlX OS.

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

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.

Installing on Windows

  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

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 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

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:

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

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

  • 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

  • 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.