--- title: "Settings on the Data Layer" product: "LumiScan Cam Driver" component: "lumiscan-cam-driver" version: "2.2.1" display_version: "2.2.1.10" latest_version: true language: "en" url: "https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html" --- # Settings on the Data Layer – LumiScan Cam Driver ## 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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html). On a PC with Windows 11 or Ubuntu 24.04, LumiScan Cam Driver uses [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html). The node addresses, types and call patterns are the same on both. LumiScan Cam Driver offers: - [ready/request handshakes](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html) - [execute methods](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html) - a [stream](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html) that publishes its results (experimental) How addresses are built, how to call functions, the status codes and the tools are described in [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html). 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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/settings-and-modules.html). ## What the node shows {#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: ```json { "$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 {#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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#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 `.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 {#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 {#adding-and-removing-modules} Three methods of `hdvisionsystems/lumiscan-cam-driver/system` handle modules, each under `control//` as `control/restart` is. Each takes the module’s id, the name of its file without `.json`, in `control//input/module-id`: | Method | What it does | | --- | --- | | `create-module` | Writes the module file `.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 `.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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#restart-required)). | | `deactivate-module` | Takes `.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//output/status-code` and `control//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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#method-results)). 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 {#restarting} `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. > [!NOTE] > A restart is not tied to a change. It also restarts an application whose settings did not change. ## JSON Schemas {#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](https://docs.hdvisionsystems.com/schemas/lumiscan-cam-driver/2.2.1/index.html). 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: ```json { "$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.