Troubleshooting

The app configuration (lumiscan-cam-driver.json) defines which camera modules are loaded.

Each camera configuration (for example camera_example.json) represents one camera.

A failed capture through the handshake ends at status 3 (waitingForClient), not at its own error code. control/capture/execute keeps the capture’s own code. See When a Functionality Runs.

A failed capture, reset, save or load is latched: its status stays until a reset succeeds. Any other error stays on control/status/code for about 100 ms only.

Check whether a camera is connected with <camera name>/device-info/is-connected, not with the status.

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 the Cam Driver in its console.

The camera configuration is missing, invalid, or not referenced correctly in lumiscan-cam-driver.json. The camera module is then not loaded.

The module’s id contains characters other than lower-case letters, digits, - and _.

The file was changed, but the application was not restarted. The Cam Driver reads its files only at start.

The whole application is missing from the Data Layer, for example because the licence is missing (ctrlX OS) or the application uses another broker (PC).

If the camera configuration is missing, invalid or not referenced: correct the app configuration and the camera configuration so that they reference each other correctly.

If the id has invalid characters: write the id that the log names (for example Camera1 → camera1), then restart the application. See Camera Example File Content Example.

If the application is missing from the Data Layer: on ctrlX OS, see Problem: "No valid license found, please purchase one. If you do have one, please try to restart ctrlX". For a PC and for other Data Layer causes, see An app or a module is missing from the tree.

control/status/code is -5 (restartRequired) on every module.

hdvisionsystems/lumiscan-cam-driver/system/restart-required is true.

Every execute method of a module answers DL_RESOURCE_UNAVAILABLE (ResourceUnavailable on LumiScan Keryx), and the ready signals are false.

A running image stream stops.

The settings were changed on the Data Layer (system/settings, activate-module, deactivate-module). Until the next start, the application runs with settings that are no longer those of its files.

A changed file could not be saved: the write answered DL_CREATION_FAILED. Files changed before it stay changed, so the application requires a restart all the same.

If the settings were changed on the Data Layer:

If a write answered DL_CREATION_FAILED: correct the files, then restart the application as above.

control/status/code is -4 (missingLicense) with the text No valid license found, please purchase one. If you do have one, please try to restart ctrlX.

On ctrlX OS, the application stops shortly after starting.

From v2.2.0, the application logs a warning and shuts down when a licence is lost.

No valid licence is installed, or not enough for the configured cameras: you need one licence per connected camera.

A version 1 key is installed. From v2.0.0, the Cam Driver needs the licence SWL-W-XCx-CAMDRIVERxHDVSx-V2NN.

Up to and including v2.1.0: the licences were installed separately. Only the first Cam Driver V2 entry is read.

If no licence or not enough licences are installed: install one licence SWL-W-XCx-CAMDRIVERxHDVSx-V2NN per connected camera. See Requirements.

If a version 1 key is installed: replace it with a V2 licence. Version 1 keys do not work from v2.0.0.

If the licences were installed separately (v2.1.0 and earlier): install all licences together, so that the Licenses page shows one Cam Driver V2 entry covering all cameras, or update to v2.2.0, which also supports separately installed licences.

For other purchase routes and licence problems, see the Licensing FAQ and Licensing troubleshooting.

The camera is not connected to the ctrlX CORE or the PC, or (ctrlX OS) not to a supported ctrlX port.

The camera is not powered, either externally or via PoE.

The IP addresses of the ctrlX CORE or the PC and of the camera are not configured correctly: the camera IP must be in the same local network.

Duplicate IP addresses exist in the network.

If the camera is not connected or not powered: connect it to the ctrlX CORE or the PC (on ctrlX OS, to a supported ctrlX port) and power it. For a ctrlX CORE X3, see Hardware Setup for ctrlX X3.

If the IP address is wrong: set it with the force-IP function under hdvisionsystems/lumiscan-cam-driver/system/force-ip/. It also works when the subnet of the camera does not match the ctrlX CORE or the PC, as long as the camera is reachable over the same network connection. See Setup Camera IP Address.

If duplicate IP addresses exist: give each device a unique IP address. On a ctrlX CORE X3, 192.168.1.1 is used by XF10: do not assign it to the camera or the computer.

After the connect-camera handshake, /hdvisionsystems/lumiscan-cam-driver/<module>/device-info/is-connected stays false.

control/status/code shows -10000 (failedToConnectToCamera) for about 100 ms only, then 0 again, with the camera still not connected.

The camera is not detected, see Problem: A physically connected camera is not detected.

The camera was unplugged and plugged back in.

The Ethernet configuration, such as buffer sizes and jumbo frames, does not match the camera specifications.

A PC on the same switch is accessing the camera at the same time. Parallel access can interfere with camera communication.

More than one process writes connect-camera/request, so the application misses the request.

If the camera is not detected: follow Problem: A physically connected camera is not detected.

If the camera was unplugged and plugged back in (from v2.1.0): run the reset handshake, which reports failedToConnectToCamera until it succeeds, then run connect-camera. connect-camera has no execute method: use the handshake on /hdvisionsystems/lumiscan-cam-driver/<module>/control/connect-camera/request. See Connection Steps.

If the connection still fails:

If a PC accesses the camera at the same time: stop that access.

If the application does not see the request: make sure that only one process accesses connect-camera/request at a time, and that you use the same Data Layer version as the camera application.

capture/execute leaves control/status/code at -10004 (couldNotCaptureImage).

Through the handshake, a failed capture ends at status 3, and capture/ready stays false until a reset succeeds.

Images cannot be triggered reliably.

The camera is disconnected.

Communication fails because of poor connection quality.

The MTU size of the Ethernet port (ctrlX OS) or of the network adapter (PC) is too small.

A network component does not support the required data throughput.

If the camera is disconnected: reconnect it. A failed capture is latched: run reset and then connect-camera with the handshake.

If the connection quality is poor: use a "Foil Shielded Twisted Pair" cable.

If the MTU size is too small: set it to 8000 or 9000. On ctrlX OS, if the port cannot change the MTU size, use an Ethernet port that supports large MTU sizes. See MTU Size Change.

If the network bandwidth is insufficient: make sure all network components support the required data throughput. On a ctrlX CORE X3, test different packet delay values until image acquisition is stable, see Complete the Camera Setup. Camera parameters can be adjusted using the manufacturer’s software, through the camera’s feature nodes under /hdvisionsystems/lumiscan-cam-driver/<module>/features, or in a feature file listed in the module’s cameras[].featureFiles. See GenICam features.

The camera is busy with another operation right now.

The image stream is starting or stopping. After the stream stops, the camera is connected again; until then, capture/execute answers DL_TOO_MANY_OPERATIONS.

If the camera is busy: retry. A rejected write is never queued; the same write succeeds once the running operation has finished.

If the stream is starting or stopping: wait until capture/ready is true. This takes about two seconds on the camera we tested.

A write to <camera name>/control/<operation>/execute answers DL_INVALID_OPERATION_MODE (ctrlX Data Layer) or InvalidOperationMode (LumiScan Keryx). This applies to v2.2.0 and later; earlier versions reported this case as DL_TOO_MANY_OPERATIONS.

capture/execute is refused again and again, also after the camera captured once.

capture: the camera is not connected, a capture fault is latched (after a failed capture), or the image stream runs.

save: no image is available yet.

load, remove: <camera name>/output/image-files is empty.

trigger: the camera is not connected.

If the camera is not connected, or a capture fault is latched: run reset and then connect-camera with the handshake (reset hands back a disconnected camera). Both have no execute method, so a program that uses execute only must connect, and recover from a latched fault, through the handshake.

If the image stream runs: stop it and wait until capture/ready is true, see Problem: Capture is refused while the image stream runs.

If no image is available for save: capture or load an image first.

If output/image-files is empty: run list-images or save an image first.

control/status/code is -10006 (saveImageFailed) or -10005 (noImageTaken).

Save does nothing, or there is no image in the storage folder.

noImageTaken: no image has been captured yet.

saveImageFailed: the storage cannot be written - ip, username or password in the storage settings are wrong, the IP is not reachable from the ctrlX CORE or the PC, or the shared folder has not enough free space.

Storage is not configured, or configured incorrectly: without a storage block in the system section of lumiscan-cam-driver.json, Save does nothing.

(ctrlX OS) The USB storage device or SD card is not mounted, or does not use FAT32 or EXT4.

If no image has been captured (noImageTaken): capture an image before saving.

If the storage cannot be written (saveImageFailed): correct ip, username and password, make the IP reachable, or free space in the shared folder.

If storage is not configured or configured incorrectly:

If the USB storage device or SD card is not mounted (ctrlX OS): mount it under Settings > Storage Devices with For data exchange, and start rootPath with the path shown there.

The camera settings are not saved or not applied correctly.

A value was written to a feature node under features. Such a value is lost when the camera is connected again.

The exposure time on input/exposure-time and the inter-packet delay are not applied while the image stream runs.

If the settings are not saved or not applied: if the camera supports it, export the camera configuration, for example in GenICam format, and import it into LumiScan to keep the settings consistent.

If a value written to a feature node was lost: put the feature into a feature file listed in the module’s cameras[].featureFiles. See GenICam features.

If the image stream runs: stop the stream, change the camera features, then start the stream again.

control/capture/execute answers DL_INVALID_OPERATION_MODE while the stream runs, and DL_TOO_MANY_OPERATIONS while the stream is starting or stopping.

A capture request through the handshake ends with status -3 (invalidInput) and the text capture refused: the image stream (experimental) is active.

control/capture/ready is false.

The experimental image stream runs. The stream and capture use the camera in different ways, so they never run at the same time.

The stream has just stopped, and the camera is being connected again.

If you need a capture: stop the stream. No reset is needed: the refusal latches no fault.

If you need single images while streaming: take them from control/publish/output/stream/frame instead of stopping the stream, or apply keep-latest-output and read output/image when output/package-identifier changes.

The stream does not run: the inputs were written, but control/publish/execute was not called; the stream could not start; or the Cam Driver was restarted - after a start, the stream is off.

frames stays at 0: the Cam Driver does not trigger the camera by itself.

frames grows more slowly than the number of triggers you sent: the camera ignores triggers that come faster than it can take images.

lost-frames or incomplete-frames grow: images were lost on the network.

published-frames matches frames, but your program receives fewer: your subscriber falls far behind, and the Data Layer drops images.

If the stream does not run: connect the camera, set control/publish/input/enable to true and call control/publish/execute. Do this after every start of the Cam Driver. If control/publish/output/stream/active stays false, the reason is in the log; the start is not retried until control/publish/execute is called again. See Running a stream.

If frames stays at 0: trigger the camera by hardware or with control/trigger/execute, or set its trigger mode off. See Triggering the camera.

If frames grows more slowly than the triggers: trigger less often, shorten the exposure, or set the camera’s TriggerOverlap to an overlap it supports, such as PreviousFrame, in a feature file. See For the highest frame rate: TriggerOverlap.

If lost-frames or incomplete-frames grow: check the network as described in Problem: Image capture fails or is unreliable (status -10004 "couldNotCaptureImage").

If your program receives fewer images than published-frames: make sure your subscriber handles each image quickly.