---
title: "FAQ"
description: "Frequently asked questions about LumiScan Cam Driver - camera and network setup, configuration files, image storage, execute methods, image stream and licensing, with links to troubleshooting."
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/faq.html"
---

# FAQ – LumiScan Cam Driver

Short answers to common questions about LumiScan Cam Driver. Each entry links to the page with the details. Problems and error messages are described in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html).

> [!TIP]
> Each entry has a fixed anchor (for example `#faq-licence-v2`). To find an error message, search the [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html) page for it.

## Requirements and setup

### Which cameras can I use, and how many per installation? {#faq-supported-cameras}

- **Answer:** The Cam Driver runs on a ctrlX CORE (ctrlX OS, with the ctrlX Data Layer) or on a PC with Windows 11 or Ubuntu 24.04 (with LumiScan Keryx), and needs an Ethernet-enabled, GenICam-compliant camera, powered via PoE or an external power supply. The node addresses are the same on both platforms. It has been tested with selected cameras from Basler, Baumer, IDS, LUCID Vision Labs, Hikvision and Balluff; GenICam implementations vary, so verify all required functions before deployment. From v2.0.0, one installation can operate several cameras: each camera is a module with its own configuration and Data Layer address (for example `hdvisionsystems/lumiscan-cam-driver/camera1`), and each connected camera needs its own licence.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html), [Description](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/description.html), [ctrlX Data Layer and LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/platforms.html)

### How do I connect a camera to a ctrlX CORE X3? {#faq-x3-network-topology}

- **Answer:** (ctrlX OS) The manual describes two topologies. After either one, assign the camera a unique IP address and test packet delay values until image acquisition is stable.
  - Shared Ethernet switch: camera, engineering computer and port XF10 on a switch that supports jumbo frames. XF10 uses `192.168.1.1`, so do not assign that address to the camera or the computer.
  - Direct connection: camera directly on XF10, engineering computer on XF51. Give XF51 a static IPv4 address in a different subnet from XF10 (for example `192.168.42.203`) and note it, because ctrlX WORKS might not discover the X3 automatically.
- **More:** [Hardware Setup for ctrlX X3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#overview)

### How do I set the IP address of a camera? {#faq-set-camera-ip}

- **Answer:** Use the force-IP function under `hdvisionsystems/lumiscan-cam-driver/system/force-ip/`. It also works when the camera is not detected normally (for example because its subnet does not match the ctrlX CORE or the PC), as long as it is reachable over the same network connection.
  - Read the camera’s MAC address from `system/found-camera-mac-addresses` (same position in the list as its serial in `system/found-camera-serials`).
  - Set `gateway`, `ip`, `subnet` and the camera’s MAC address.
  - Wait until `ready` is true, set `request` to true, then back to false.
  - When `ready` is true again, `system/found-camera-ip-addresses` shows the new address. If it does not, use the camera supplier’s program to set the IP.
- **More:** [Setup Camera IP Address](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html), [Force IP configuration of camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#force-ip-configuration-of-camera)

## Configuration

### Where are the configuration files, and how do I add a camera? {#faq-config-files}

- **Answer:** `lumiscan-cam-driver.json` holds the application settings and lists the camera configuration files to load; each further file (for example `camera_example.json`) configures one camera.
  - On ctrlX OS: in the ctrlX OS web interface, open **Home** > **Manage app data**, select **File View** from the three-dot menu and open the `lumiscan-cam-driver` folder. To add a camera, copy an existing camera file (three dots > **COPY**), give it a new name, enter that name in the list of camera configuration files in `lumiscan-cam-driver.json`, and restart the application.
  - On a PC: the files are ordinary files in the folder the Cam Driver reads its settings from; the Cam Driver names it when you write an example with `--generate-settings`. On Windows this is `%APP_RESOURCE_DIR%\etc\lumiscan-cam-driver`, or by default `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver`. Copy a camera file under a new name, enter it in `lumiscan-cam-driver.json` and restart the Cam Driver.
  - On both: `system/settings` shows and changes the files on the Data Layer, and `system/control/create-module` and `activate-module` add a camera module; then restart with `system/control/restart/execute`.
- **More:** [Setup Camera Configuration](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/setup-camera-configuration.html#edit-with-built-in-website), [Creating New Camera Settings Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/creating-new-camera-settings-files.html), [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)

### Which settings does a camera configuration file contain? {#faq-camera-parameters}

- **Answer:** `inputFileType` must be `camera-configuration`. The camera settings are `id` (must be unique across all camera settings; it is the module’s name on the Data Layer and may contain only lower-case letters, digits, `-` and `_`), `serial` (a serial containing `simulation` makes the camera simulated), `exposureTimeUS`, `pixelFormat` (`RGB8` or `Mono8`), `timestampSource` (`Camera` or `System`; from v2.0.0 the camera timestamp is the default) and, optional and experimental, `stream.tag`. Parameters can be overridden on the Data Layer under `…/input/`. Restart the application after changing the file.
- **More:** [Camera Example File Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html)

### How do I change other GenICam features of the camera? {#faq-genicam-features}

- **Answer:** Connect the camera, then edit the nodes under `hdvisionsystems/lumiscan-cam-driver/<camera name>/features`. Their names, values, permissions and descriptions come directly from the camera; refer to the camera vendor’s documentation. Values are written directly to the camera, so take care with network settings. This feature is marked experimental: values are not cached, and setting them repeatedly (for example from a PLC) can cause camera instability and a performance penalty. A value written to a feature node is lost when the camera is connected again; a feature file listed in the module’s `cameras[].featureFiles` is applied each time the camera is connected.
- **More:** [GenICam features](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#genicam-features), [For the highest frame rate: TriggerOverlap](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#trigger-overlap), [Release Notes: v2.0.0](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-0-0-2026-06-02.html)

### How do I save images internally, on USB/SD card or on a Samba share? {#faq-image-storage}

- **Answer:** Add a `storage` block to the `system` section of `lumiscan-cam-driver.json` and restart the application. Without it, **Save** does nothing.
  - `type`: `Null`, `Internal` (internal storage; on ctrlX OS also a USB storage device or SD card) or `Samba` (Windows shared folder).
  - `Internal`: `rootPath`. A relative path stores in the application’s internal directory. On ctrlX OS, a path starting with the mounted device path (for example `/media/sdb1/myCapturedImages`) stores on that device; USB/SD devices must use FAT32 or EXT4 and be mounted under **Settings** > **Storage Devices**.
  - `Samba`: `ip`, `remotePath`, `domain` (`""` if there is none), `username`, `password`. The password is stored in clear text, so do not use a regular user account.
  - From v2.2.0, `unifiedStorage` (default `false`: one folder per camera) set to `true` makes all cameras use the storage folder directly.
- **More:** [Storage settings](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings), [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files)

## Operation

### Should I use the execute method or the ready/request handshake? {#faq-execute-or-handshake}

- **Answer:** Both lead to the same result. From v2.1.0, `capture`, `save`, `load`, `remove` and `list-images` can be started with one write to `<camera name>/control/<operation>/execute`, which returns when the operation has finished; from v2.3.0, `trigger` is offered as an `execute` method only. `connect-camera`, `disconnect-camera` and `reset` have no `execute` node and must use the handshake. Only one process may write `request` at a time, and in both cases you check `control/status/code` and `control/status/text` afterwards. Handshake steps:
  - Wait until `ready` is true.
  - Set `request` to true, and wait until `ready` changes to false: the application has seen the request.
  - Set `request` to false, wait for the operation to finish and read its outcome on `control/status/code`.
  - A failed `capture` through the handshake ends at status `3` (`waitingForClient`), not at its own error code, and `capture/ready` stays false until a `reset` succeeds. `capture/execute` keeps the capture’s own code.
- **More:** [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#choosing-between-the-two), [When a Functionality Runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html#when-a-functionality-runs), [Handshake](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html)

### Where do I find the captured image, and how can I view it? {#faq-image-output}

- **Answer:** The image is published on `hdvisionsystems/lumiscan-cam-driver/<camera name>/output/image` together with width, height and pixel type, regardless of how the capture was started. This is raw sensor data that most viewers cannot display. From v2.1.0, switch on `<camera id>/input/preview/enable` to get a PNG on `<camera id>/output/preview/encoded-data` after each successful capture or load; `<camera id>/input/preview/scale` (0.0 to 1.0) makes it smaller. Compare `output/package-identifier` to check that the preview belongs to the latest image. To receive every image the camera delivers, use the experimental image stream on `<camera name>/control/publish/output/stream/frame` (from v2.3.0).
- **More:** [Description](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/description.html), [Streaming Images (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html), [Release Notes: v2.1.0](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-1-0-2026-07-17.html)

### How does simulation mode work? {#faq-simulation-mode}

- **Answer:** Give the camera a `serial` that contains `simulation` (for example `simulation`); the module then does not search for or connect to a real camera. Whether a camera is simulated depends on its serial, not on its `id`. Calling **Capture** loads an image from the configured storage folder and advances to the next image for the next capture. Since v2.0.0, the images are taken from `images/<camera id>` instead of `images` (move existing images before updating), and the folder is scanned on connection, so calling `list-images` is not needed. From v2.2.0, `unifiedStorage` set to `true` uses the storage folder directly.
- **More:** [Loading Images](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#loading-images), [Camera Example File Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html), [Release Notes: v2.0.0](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-0-0-2026-06-02.html)

### How do I receive every image instead of one per capture? {#faq-image-stream}

- **Answer:** From v2.3.0, use the experimental image stream. Connect the camera, set its features (for the highest frame rate, `TriggerOverlap` not `Off`), subscribe to `<camera name>/control/publish/output/stream/frame`, set `control/publish/input/enable` to `true` and call `control/publish/execute`. The Cam Driver does not trigger the camera by itself: images come on a hardware trigger, on `control/trigger/execute`, or continuously with the trigger mode off. While the stream runs, `capture` is not available; after the stream stops, the camera is connected again, which takes about two seconds on the camera we tested.
- **More:** [Running a stream](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#running-a-stream), [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html)

## Troubleshooting {#troubleshooting}

Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html):

- [A configured camera does not appear in the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-camera-not-in-data-layer)
- [Modules answer no request, and the status is -5 "restartRequired"](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-restart-required)
- ["No valid license found, please purchase one. If you do have one, please try to restart ctrlX"](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-missing-license)
- [A physically connected camera is not detected](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-camera-not-detected)
- [The camera does not connect (status -10000 "failedToConnectToCamera")](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-failed-to-connect-to-camera)
- [Image capture fails or is unreliable (status -10004 "couldNotCaptureImage")](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-could-not-capture-image)
- [A write to execute answers "DL_TOO_MANY_OPERATIONS" or "TooManyOperations"](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-dl-too-many-operations)
- [A write to execute answers "DL_INVALID_OPERATION_MODE", or capture keeps being refused](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-dl-invalid-operation-mode)
- [Images are not saved (status -10006 "saveImageFailed" or -10005 "noImageTaken")](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-save-image-failed)
- [Images do not match expectations](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#ts-images-not-as-expected)
- [Capture is refused while the image stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-capture-refused-streaming)
- [The image stream delivers no images, or fewer than expected](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#ts-stream-missing-images)

## Licensing and support

### Which licence do I need, and why does my old licence no longer work? {#faq-licence-v2}

- **Answer:** From v2.0.0, the Cam Driver needs the licence `SWL-W-XCx-CAMDRIVERxHDVSx-V2NN`; version 1 keys do not work. You need one licence per connected camera. On ctrlX OS (ctrlX CORE or IPC), a licence bought in the ctrlX Store is a ctrlX licence and needs no LumiScan Key. For other purchase routes, see the Licensing FAQ.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html#licence), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

### Where can I find more answers or get support? {#faq-support}

- **Answer:** See the site-wide [LumiScan FAQ](https://docs.hdvisionsystems.com/en/faq.html), and for questions about the Data Layer itself the [Data Layer FAQ](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/faq.html). Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **More:** [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)