Settings on the Data Layer

Data Layer

LumiScan Calibration offers its functions on the Data Layer under hdvisionsystems/lumiscan-calibration.

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

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

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

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

LumiScan Calibration shows the settings it was started with on the Data Layer, on hdvisionsystems/lumiscan-calibration/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-calibration/system/control/restart/execute restarts it. The system node of all LumiScan applications is described in Settings, Modules and Restart.

Where a result below has one name only, such as DL_OK or DL_CREATION_FAILED, it is the name on the ctrlX Data Layer; LumiScan Keryx reports the same result under its own name, see Results of a method call.

What the node shows

settings holds one JSON document, as text:

  • the application settings file, lumiscan-calibration.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-calibration.schema.json",
  "meta": { ... },
  "modules": [
    {
      "$file": "example.json",
      "$schema": "schemas/lumiscan-calibration-module.schema.json",
      "transform": {
        "name": "PlanarProjectionExample",
        "relativePathToTiff": "example.tiff",
        ...
      }
    }
  ],
  "system": { ... }
}

Comments in the files are not shown.

The node shows the files as the application read them at start. A module’s reset reads its module file again, and the node then shows that file as it was read.

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-calibration.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 has to load, and each changed module configuration file has to load its lookup table and its stream section, as a reset would. A lookup table that does not exist is refused. 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-calibration/system/restart-required is true;

  • hdvisionsystems/lumiscan-calibration/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 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-calibration/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 (ctrlX Data Layer) or Rejected (LumiScan Keryx) when it refused, and DL_CREATION_FAILED when a file could not be written. For example, to add the module conveyor:

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

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

  3. Call hdvisionsystems/lumiscan-calibration/system/control/restart/execute.

Restarting the application

hdvisionsystems/lumiscan-calibration/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-calibration/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.