Troubleshooting

This page first lists the general checks that help with every problem. Start with them. Then find your symptom in the categories below: each problem lists its symptoms, possible causes, a diagnostic procedure and the resolution. The last section lists what to send to support.

General checks

Configuration

LumiScan Calibration uses:

  • an application configuration file (lumiscan-calibration.json) that references

  • one or more module configuration files (<module name>.json), each naming a TIFF file.

The configuration files can be found under:

  • On ctrlX OS: Manage App Data > active > lumiscan-calibration

  • On a PC (Windows): %APP_RESOURCE_DIR%\etc\lumiscan-calibration, or without APP_RESOURCE_DIR C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-calib\etc\lumiscan-calibration

Their content is also shown on the Data Layer, on hdvisionsystems/lumiscan-calibration/system/settings. A module file that could not be read appears there with an "$error" that says why. See Settings on the Data Layer.

Restart LumiScan Calibration after changing lumiscan-calibration.json. After changing a module configuration file or its TIFF file, a reset of the module (control/reset) is enough.

For more information about the configuration files, see Application Settings File and Module Configuration File.

Status of the application and its modules

  • hdvisionsystems/lumiscan-calibration/system/found-modules lists the modules the application serves. hdvisionsystems/lumiscan-calibration/system/status-text is "Initialized" once it serves its modules, or says why it serves none.

  • hdvisionsystems/lumiscan-calibration/<module name>/control/status/code and .../control/status/text report the outcome of the last function. An error status stays until the next request. The meaning of each value is listed in Status Code Values.

  • Status -5 (restartRequired) means that the settings were changed on the Data Layer: restart the application with hdvisionsystems/lumiscan-calibration/system/control/restart/execute. See Settings on the Data Layer.

Logs

If an issue cannot be resolved using the checks described below, review the log. Each module writes why it could not load its files or start its stream.

  • ctrlX OS: the ctrlX OS system log. Read it in the Logbook of the ctrlX web interface, or with journalctl. See ctrlX Data Layer on ctrlX OS.

  • PC: the output of LumiScan Calibration in its console.

Data Layer

For problems with the Data Layer itself, see Data Layer troubleshooting.

Modules and addresses

Problem: A calibration module does not appear in the Data Layer

Symptoms

  • There is no node hdvisionsystems/lumiscan-calibration/<module name> for a module you configured, and hdvisionsystems/lumiscan-calibration/system/found-modules does not list it.

  • No module appears at all, or the application itself is missing from the Data Layer.

Possible causes

  • The module configuration file is not listed under modules in lumiscan-calibration.json. A listed module appears even when its file cannot be loaded.

  • The module is looked for under the wrong name. Its name is the name of its file without .json, in lower case. The name in the module’s transform block does not change it.

  • lumiscan-calibration.json was changed, but the application was not restarted.

  • lumiscan-calibration.json lists no module.

  • The application stopped at start, for example because lumiscan-calibration.json is not valid JSON, or (ctrlX OS) because the licence is missing.

Diagnostic procedure

  1. Read hdvisionsystems/lumiscan-calibration/system/found-modules - expected: the module’s name.

  2. Check modules in lumiscan-calibration.json - expected: the module configuration file is listed.

  3. Look for the module under the name of its file without .json, in lower case.

  4. Read hdvisionsystems/lumiscan-calibration/system/status-text - expected: "Initialized". Otherwise it says why the application serves no module, for example when lumiscan-calibration.json lists no module.

  5. If the application itself is missing from the Data Layer, read the log (see Logs) - it says why the application stopped at start.

Resolution

  • If the file is not listed: add the file name to the modules list of lumiscan-calibration.json, then restart LumiScan Calibration. See Adding New Module.

  • If you looked under the wrong name: use the name of the file without .json, in lower case: hdvisionsystems/lumiscan-calibration/<module name>.

  • If lumiscan-calibration.json was changed without a restart: restart LumiScan Calibration, for example with hdvisionsystems/lumiscan-calibration/system/control/restart/execute.

  • If the application stopped at start: correct lumiscan-calibration.json as the log says, then start the application again. If the log names a missing licence, see Requirements.

If the problem persists

Send the information listed under Information for support to support, together with the content of system/status-text and system/found-modules, and lumiscan-calibration.json.

Problem: Data Layer addresses under lumiscan-cam-calibration no longer work

Symptoms

Addresses that start with hdvisionsystems/lumiscan-cam-calibration/…​ no longer work.

Possible causes

  • From v1.2.1, the application’s Data Layer name changed from lumiscan-cam-calibration to lumiscan-calibration.

Diagnostic procedure

  1. Check the version of LumiScan Calibration - the change applies to v1.2.1 and later.

  2. Check the addresses your program or PLC uses - expected: they start with hdvisionsystems/lumiscan-calibration/.

Resolution

  • If the addresses still use the old name: update all addresses to hdvisionsystems/lumiscan-calibration/…​. See Release Notes: v1.2.1.

If the problem persists

Send the information listed under Information for support to support, together with the addresses that do not work.

Transforming points

Problem: transform/ready stays false, and the status is -2

Symptoms

  • control/transform/ready stays false.

  • control/status/code is -2 (invalidSetting).

  • control/transform/execute answers DL_INVALID_OPERATION_MODE.

  • A running stream publishes NaN for every point.

Possible causes

  • The module has no lookup table: its module configuration file or the TIFF file it names could not be loaded, for example because the TIFF file is missing.

  • The module configuration file has invalid or missing parameters, including its stream section. A malformed stream section is a malformed module file, for example stream mode without a source (enable set to true and no address), a step of another kind, or a key of a step written at the top of the section instead of in onEntry.

  • The licence is not available. The status is then -4 (missingLicense), and the module runs no function until the licence is back.

Diagnostic procedure

  1. Read control/status/code - -2: a file could not be loaded; -4: the licence is missing.

  2. Read the log (see Logs) - it says why the files could not be loaded, and names a malformed key.

  3. Check that the TIFF file named by relativePathToTiff exists beside the module configuration file.

  4. Check the module configuration file for invalid or missing parameters, including its stream section.

Resolution

  • If a file could not be loaded (status -2): correct the files and reset the module. The module does not keep transforming with the old table, so that a corrected file is never mixed with an outdated one. See Reloading the settings.

    1. Correct the module configuration file or the TIFF file.

    2. Reset the module (control/reset). No restart is needed.

    3. Check that control/status/code is 0 and control/transform/ready is true.

  • If the licence is missing (status -4): install the licence SWL-W-XCx-CALIBRATExHDVSx-V2NN. On ctrlX OS, the application shuts down shortly after starting if the licence is missing. See Requirements.

If the problem persists

Send the information listed under Information for support to support, together with the module configuration file, the name of its TIFF file and the log lines of the failed load.

Problem: The application does not react to a request

Symptoms

After you set XXX/control/<function name>/request to true, XXX/control/<function name>/ready does not change to false, or the function does not run. XXX is hdvisionsystems/lumiscan-calibration/<module name>.

Possible causes

  • More than one process writes the request node. The behaviour is then undefined, because the application can miss a request.

  • request was not set back to false. The module waits for request to fall for as long as it takes.

  • Your program uses another Data Layer version than the application.

Diagnostic procedure

  1. Check which programs write XXX/control/<function name>/request - expected: only one process.

  2. After setting request to true, read ready - expected: false (the module has seen the request).

  3. After setting request back to false, read ready - expected: true again when the function has finished.

  4. Check the Data Layer version your program uses - expected: the same as the application.

Resolution

  • If more than one process writes request: make sure only one process accesses XXX/control/<function name>/request at a time. A program that cannot coordinate with others can use the execute method instead (XXX/control/<function name>/execute), which refuses a second call while one runs.

  • If request was not set back: set request to false after ready has changed to false. See Running a function.

  • If the Data Layer versions differ: use the same Data Layer version as the application.

If the problem persists

Contact HD Vision Systems with the information listed under Information for support, together with the function you request and the values of ready, request and control/status/code.

Problem: The transformed coordinates do not match the image

Symptoms

The transformed coordinates do not correspond to the expected positions.

Possible causes

  • An axis is inverted.

  • The required origin is not defined correctly. The calibration does not define the application-specific reference point automatically.

  • Units are mixed, such as millimeters and pixels, in the application and connected systems.

  • The configured TIFF file does not belong to the camera and calibrated plane in use.

  • A point lies outside the lookup table. It gives a value from the edge of the table, without an error.

Diagnostic procedure

  1. Move an object in a known direction and observe how the coordinates change - expected: each coordinate changes in the expected direction.

  2. Check the reference point - expected: the origin your application needs is defined.

  3. Check the units of the application and connected systems - expected: the same units throughout.

  4. Check relativePathToTiff in the module configuration file - expected: the TIFF file for the camera and calibrated plane in use.

  5. Check the input points - expected: within the image the lookup table was made for.

Resolution

  • If an axis is inverted: a coordinate changes in the opposite direction. Send the observed and the expected direction to support (see Information for support).

  • If the reference point is not defined: define the origin your application needs. The calibration does not do this automatically.

  • If units are mixed: use consistent units throughout the application and connected systems.

  • If the wrong TIFF file is configured: configure the TIFF file for the camera and calibrated plane in use, then reset the module (control/reset).

  • If points lie outside the lookup table: keep the points within the image the table was made for.

If the problem persists

Send the information listed under Information for support to support, together with some input points, the coordinates you get and the coordinates you expect.

Streams (experimental)

Problem: The stream does not start

Symptoms

control/subscribe/output/stream/active stays false after control/subscribe/execute was called with control/subscribe/input/enable set to true.

Possible causes

  • control/subscribe/input/address is empty, or the queue size is not 1 to 4096: the call answers DL_INVALID_VALUE (ctrlX Data Layer) or Rejected (LumiScan Keryx).

  • The module configuration file is malformed (status -2), for example a step of stream.onEntry the module does not have, or a key of a step written at the top of the stream section.

  • A remap path does not fit the schema.

  • The change could not be saved in the module configuration file: the call answers DL_CREATION_FAILED.

  • The settings were edited on system/settings, and the application waits for a restart: the call answers DL_RESOURCE_UNAVAILABLE.

  • The licence is missing. The stream runs only while the licence is present.

Diagnostic procedure

  1. Check the answer of control/subscribe/execute - expected: DL_OK.

  2. Check control/status/code - -2: the module configuration file is malformed; the log names the key.

  3. Check setting/stream/enable and setting/stream/address - they show what the module applies.

  4. Read the log (see Logs) - the module writes why the stream could not start, for example a remap path that does not fit the schema.

Resolution

  • If the address is empty or the queue size is out of range: write the source’s folder to control/subscribe/input/address, or a queue size from 1 to 4096 to control/subscribe/input/queue-size, and call control/subscribe/execute again.

  • If the stream section is malformed or a remap path does not fit: correct the stream section and reset the module. A failed start is retried after the reset, or after stream mode is switched off and on again with control/subscribe/execute. See Configuring a stream.

  • If the call answers DL_CREATION_FAILED: the module configuration file could not be read or written. The answer and the log say why. Nothing changed.

  • If the call answers DL_RESOURCE_UNAVAILABLE: restart the application, see Status of the application and its modules.

  • If the licence is missing: see Requirements.

A source the stream cannot subscribe to does not keep it from starting: it is tried again every 5 seconds, and the first failure is in the log. See Problem: The stream runs, but no points arrive.

If the problem persists

Send the information listed under Information for support to support, together with the answer of control/subscribe/execute, the values of setting/stream/enable and setting/stream/address, and the stream section of the module configuration file.

Problem: The stream runs, but no points arrive

Symptoms

control/subscribe/output/stream/active is true, but no points, or invalid points, arrive on control/subscribe/output/stream/points or control/subscribe/output/stream/plain-points.

Possible causes

  • received-updates stays 0: the source does not change, or setting/stream/address and the step’s node name another node than intended.

  • failed-updates grows: the updates are not of the expected kind.

  • invalid-points grows with points: the points lie outside the lookup table, or the module has no table (status -2).

  • skipped-updates grows: the source updates faster than the module transforms.

Diagnostic procedure

  1. Check the counters under control/subscribe/output/stream/statistics - expected: received-updates grows, and failed-updates, invalid-points and skipped-updates stay at 0.

  2. Compare setting/stream/address and the step’s node with the node you intend - expected: the node node in the folder address, exactly as written, including the case.

  3. Read the log (see Logs) - it warns about an address that names the node twice, says when the source could not be subscribed to, and shows the first failed update.

Resolution

  • If received-updates stays 0: make the source change, or correct address and node. The module subscribes to the node node in the folder address, exactly as written, including the case. An address that still ends in the node names it twice. On the ctrlX Data Layer, an ordinary node such as a PLC array is read about every 100 ms, and changes in between are not seen; on LumiScan Keryx, writing the same values again is not an update. See What a stream receives.

  • If failed-updates grows: send updates of the expected kind. A plain stream needs a float32 or float64 array with a whole number of points; a remap stream needs a flatbuffer of the type its schema names.

  • If invalid-points grows: keep the points within the lookup table, or, if the status is -2, follow Problem: transform/ready stays false, and the status is -2.

  • If skipped-updates grows: reduce the source’s rate or the number of points per update. For short bursts, a larger queue size (control/subscribe/input/queue-size, saved as queueSize) helps. See The queue.

If the problem persists

Send the information listed under Information for support to support, together with the values of the counters under control/subscribe/output/stream/statistics and the stream section of the module configuration file.

Information for support

If a problem persists, send the following to HD Vision Systems customer success at customer.success@hdvisionsystems.com or +49 6221 6721905. For licences, contact licenses@hdvisionsystems.com.

  • The version of LumiScan Calibration.

  • The platform: ctrlX OS and its version on a ctrlX CORE or ctrlX IPC, or a PC with Windows 11 or Ubuntu 24.04 and LumiScan Keryx.

  • The log: on ctrlX OS, the ctrlX OS system log (Logbook of the ctrlX web interface, or journalctl); on a PC, the console output of LumiScan Calibration.

  • The date and time when the error occurred.

  • The Data Layer status: system/status-text, system/found-modules, and for the affected module control/status/code, control/status/text and the result that an execute call answered.

  • The configuration: lumiscan-calibration.json and the module configuration files, or the content of hdvisionsystems/lumiscan-calibration/system/settings, and the name of the TIFF file.