Settings on the Data Layer

Data Layer

LumiScan Cam Driver offers its functions on the Data Layer under hdvisionsystems/lumiscan-cam-driver.

On ctrlX OS (ctrlX CORE or ctrlX IPC), LumiScan Cam Driver uses the ctrlX Data Layer.

On a PC with Windows 11 or Ubuntu 24.04, LumiScan Cam Driver uses LumiScan Keryx.

The node addresses, types and call patterns are the same on both. LumiScan Cam Driver offers:

How addresses are built, how to call functions, the status codes and the tools are described in LumiScan Keryx.

LumiScan Cam Driver shows the settings it was started with on the Data Layer, on hdvisionsystems/lumiscan-cam-driver/system/settings. You can read them there without access to the configuration folder, and change them there: the application checks a change, saves it to its settings files, and asks to be restarted. hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute restarts it.

For an overview of the system node across the LumiScan apps, see Settings, Modules and Restart.

What the node shows

settings holds one JSON document, as text:

  • the application settings file, lumiscan-cam-driver.json, as it was read;

  • in its modules list, each module configuration file’s content instead of the file’s name. "$file" names the file each module came from;

  • a module file that could not be read appears as {"$file": ..., "$error": ...}, where "$error" says why. That is also why the module did not start;

  • every value named password shows as "***".

For example:

{
  "$schema": "schemas/lumiscan-cam-driver.schema.json",
  "meta": { ... },
  "modules": [
    {
      "$file": "lumiscan-cam-driver-example-module.json",
      "$schema": "schemas/lumiscan-cam-driver-module.schema.json",
      "id": "camera1",
      "serial": "simulation",
      "exposureTimeUS": 6000,
      ...
    }
  ],
  "system": { ... }
}

Comments in the files are not shown.

The node shows the files as the application read them at start. The Cam Driver reads its files only at start.

Changing the settings

Read settings, change what you need, and write the whole document back. These rules apply:

  • Each module keeps its "$file". It must name one of the application’s module files: a module cannot be added here. To add one, see Adding and removing modules.

  • A module left out of modules is no longer listed in lumiscan-cam-driver.json. Its file stays where it is.

  • "***" for a password keeps the password the file has. Any other value replaces it.

  • A file whose content does not change is not written. A changed file is changed only where its content changed: comments and layout stay. A new key or list element goes after the last one there; a removed key goes with its line, a comment on that line included. Only an object that both gained and lost keys, or a list that lost an element, is written anew, without the comments inside it. The previous file is kept beside it as <file>.bak.

  • A key such as "_comment" is content like any other, so it is shown and kept.

The application checks the change before anything is written: the application settings file and each changed camera settings file have to read as the settings they stand for, with the right names and types. Whether the camera can be found, or accepts a value, shows only at the next start. An edit the check refuses, or that is not valid JSON, is answered with DL_INVALID_VALUE (ctrlX Data Layer) or Rejected (LumiScan Keryx). The reason is in the log, and nothing is written.

An edit that writes nothing answers DL_OK and changes nothing.

Restart required

A change that was saved takes effect only with the next start. Until then the application runs with settings that are no longer those of its files, so it stops working:

  • hdvisionsystems/lumiscan-cam-driver/system/restart-required is true;

  • hdvisionsystems/lumiscan-cam-driver/system/status-text says which files changed;

  • every module reports status -5 (restartRequired). It answers no request, and its ready signals are false;

  • every execute method of a module answers DL_RESOURCE_UNAVAILABLE. That includes reset, which would otherwise load part of the new settings;

  • a running image stream stops.

Only a restart ends this. A reset does not. The log has the message at error level.

Further changes are possible in the meantime. After a change, settings shows the files as saved, which is what the next start loads, not what the application runs with.

If a file could not be saved, the write answers DL_CREATION_FAILED. Files changed before it stay changed, so the application requires a restart all the same. Correct the files, then restart.

Adding and removing modules

Three methods of hdvisionsystems/lumiscan-cam-driver/system handle modules, each under control/<method>/ as control/restart is. Each takes the module’s id, the name of its file without .json, in control/<method>/input/module-id:

Method What it does

create-module

Writes the module file <module-id>.json with the JSON in control/create-module/input/content. The application checks it as it checks a changed module file. The module is not active yet, so nothing has to be restarted. An existing file is not overwritten: change it through settings.

activate-module

Adds <module-id>.json, which has to exist, to the modules list, after the application has checked the module. It runs from the next start, so the application then requires a restart (see Restart required).

deactivate-module

Takes <module-id>.json off the modules list. The file stays, so activate-module can list it again. It stops with the next start, so the application then requires a restart.

Each method reports on control/<method>/output/status-code and control/<method>/output/status-text:

Code Meaning

1

Done.

-2

The input or the module was refused: status-text says why. Nothing was written.

-6

A file could not be written.

-9

activate-module: there is no such file. deactivate-module: the module is not active.

-10

create-module: the file exists. activate-module: the module is active already.

The method answers DL_OK when it is done, DL_INVALID_VALUE when it refused, and DL_CREATION_FAILED when a file could not be written (names of the ctrlX Data Layer; LumiScan Keryx answers Ok, Rejected and CreationFailed, see Results of a method call). For example, to add the module camera2:

  1. Write the module’s JSON to hdvisionsystems/lumiscan-cam-driver/system/control/create-module/input/content and camera2 to control/create-module/input/module-id, then call control/create-module/execute.

  2. Write camera2 to control/activate-module/input/module-id, then call control/activate-module/execute.

  3. Call hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute.

Restarting the application

hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute ends the application and starts it again. It reads its settings files anew, which also applies changes made to the files by hand, and ends restart-required.

  • On ctrlX OS: the application ends, and ctrlX OS starts it again after about five seconds.

  • On a PC: the application starts itself again once it has released everything it held. It uses the same program, arguments and working folder. It is a new process, in the same console, and its output goes where the first one’s went.

The method answers DL_OK as soon as the restart has begun. The application’s nodes then disappear until it is up again: wait until hdvisionsystems/lumiscan-cam-driver/system/restart-required can be read again.

A restart is not tied to a change. It also restarts an application whose settings did not change.

JSON Schemas

The application keeps the JSON Schemas of its settings files in its schemas folder; those copies always match the installed version. The schemas of LumiScan Cam Driver 2.2.1 can also be downloaded: JSON Schemas of LumiScan Cam Driver 2.2.1.

To have an editor such as Visual Studio Code check a copy of a settings file that you edit on your PC, point its $schema entry at the published schema:

{
  "$schema": "https://docs.hdvisionsystems.com/schemas/lumiscan-cam-driver/2.2.1/lumiscan-cam-driver.schema.json",
  ...
}

Leave the $schema entry of the files on the device as the application wrote it.