# LumiScan Cam Driver 2.2.1.10 – complete documentation

> All pages of the LumiScan Cam Driver 2.2.1.10 manual (language: en) by HD Vision Systems GmbH, in navigation order. Each page starts with a level-1 heading followed by its URL; cite that URL. Manual: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/

# Description – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/description.html

The LumiScan Cam Driver connects Ethernet-enabled, GenICam-compliant cameras to a ctrlX CORE or ctrlX IPC (ctrlX OS) or to a PC, and makes their images and camera functions available through the Data Layer: the ctrlX Data Layer on ctrlX OS, LumiScan Keryx on a PC. The node addresses are the same on both.

What is the same for every LumiScan app - how addresses are built, the handshake, execute and stream call patterns, status codes, settings and tools - is described in the [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html) manual. This manual covers only what is specific to LumiScan Cam Driver; the pages of this manual describe its own nodes.

It handles camera discovery, connection, image acquisition, and basic camera configuration. Camera parameters such as exposure time, pixel format, and other supported GenICam features can be accessed through the application configuration and Data Layer.

> [!NOTE]
> The available camera features depend on the camera model and its GenICam implementation. Some functions may not be available for every camera.

## Where Images Can Be Accessed

Each configured camera publishes its acquired image through the Data Layer.

For example:

```
hdvisionsystems/lumiscan-cam-driver/camera1/output/image
```

The image node provides the image data together with information such as its width, height, and pixel type.

Other LumiScan applications can use this Data Layer address as their image source. The image data can also be accessed directly by applications that support the corresponding Data Layer interface.

## Streaming Images

From v2.3.0, a camera can also stream its images: after `<camera name>/control/publish/execute`, the Cam Driver publishes every image the camera delivers on `<camera name>/control/publish/output/stream/frame` for a subscriber, instead of one image per capture request. The images come as the camera is triggered: by hardware, by `control/trigger/execute`, or continuously. This feature is experimental. See [Streaming Images (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html).

## Modules

A **module** represents one configured camera.

Each module defines which camera is used and contains the camera-specific configuration, such as:

- Camera identification
- Connection settings
- Acquisition settings
- Camera features and parameters
- Data Layer addresses for control, status, and image output

Each module has its own Data Layer address and operates independently from the other configured cameras.

For example:

```
hdvisionsystems/lumiscan-cam-driver/camera1
hdvisionsystems/lumiscan-cam-driver/camera2
```

This allows one LumiScan Cam Driver installation to connect and manage multiple cameras, with each camera using its own module and configuration.

# Requirements – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html

- One of:
  - ctrlX OS: a ctrlX CORE with the ctrlX Data Layer
  - a PC with Windows 11 or Ubuntu 24.04 and LumiScan Keryx
- Ethernet-enabled, GenICam-compliant camera
- Camera power supply, either via PoE or an external power supply

> [!NOTE]
> The application has been tested with selected cameras from Basler, Baumer, IDS, LUCID Vision Labs, Hikvision, and Balluff.

> [!IMPORTANT]
> GenICam implementations can vary between manufacturers and camera models. Therefore, some functions might be unavailable or behave differently with untested cameras. Verify all required functions before deployment.

For the Data Layer on each platform, see [ctrlX Data Layer and LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/platforms.html).

## Licence {#licence}

How LumiScan Cam Driver is licensed depends on where you bought it and where it runs:

| Bought from | Runs on | Licensing |
| --- | --- | --- |
| HD Vision Systems | Windows 11 or Ubuntu 24.04 | The licence is held on your LumiScan Key. It is a one-time purchase and needs no renewal.<br><br>[Licensing path: bought from HD Vision Systems](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-hdvs.html) |
| ctrlX Store | Windows 11 | The licence is held in ctrlX WORKS. The LumiScan Key is required in addition; it protects the software against reverse engineering.<br><br>[Licensing path: ctrlX Store, Windows](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-ctrlx-windows.html) |
| ctrlX Store | ctrlX OS (ctrlX CORE or IPC) | ctrlX licence `SWL-W-XCx-CAMDRIVERxHDVSx-V2NN`, one licence per connected camera.<br><br>[Licensing path: ctrlX Store, ctrlX OS](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/path-ctrlx-os.html) |

Each device on which LumiScan Cam Driver runs at the same time needs its own LumiScan Key. Keys can be exchanged between devices.

How to install CodeMeter Runtime and how to request, renew and move licences is described in [LumiScan Licensing](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/index.html).

On ctrlX OS, the application shuts down shortly after starting if the licence is missing; the reason is written to the system log.

> [!NOTE]
> Up to and including v2.1.0, all licences must be installed together and appear as one Cam Driver V2 entry covering all cameras. Separate entries cause a licence error. From v2.2.0 onward, separately installed licences are also supported. See [Release Notes: v2.2.0](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-2-0-2026-08-05.html).

# How To: Connect a GenICam Camera to ctrlX CORE – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/connect-a-genicam-camera.html

This guide connects an Ethernet camera that follows the GenICam standard (GigE Vision) to a ctrlX CORE and takes it as far as a captured image on the ctrlX Data Layer. It uses only the ctrlX web interface.

When you have finished:

- the camera has a fixed IP address in the network of the ctrlX CORE,
- LumiScan Cam Driver has a module for the camera and finds it,
- the camera is connected, and every capture puts an image on the Data Layer,
- captured images can optionally be saved to internal storage, a USB storage device, an SD card or a network share.

## Before you start {#prerequisites}

**Hardware**

- ctrlX CORE, for example ctrlX CORE X3 or X7
- GenICam-compliant Ethernet camera (GigE Vision)
- Engineering PC with a browser
- Shielded Ethernet cables (foil shielded twisted pair)
- Optional: an Ethernet switch that supports jumbo frames

**Software and licences**

- LumiScan Cam Driver installed on the ctrlX CORE, with a licence for each camera, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html)
- The configuration tool of the camera manufacturer, to set the camera’s IP address

## How it fits together {#overview}

LumiScan Cam Driver is configured with two kinds of files and controlled entirely through the Data Layer:

- `lumiscan-cam-driver.json`, the **application settings**, lists the camera modules to load in `modules` and holds the settings of the device, such as logging and image storage.
- One **module file** per camera, for example `camera1.json`, names the camera by its serial number and sets its exposure time and pixel format. Its `id` becomes the module’s name on the Data Layer: `hdvisionsystems/lumiscan-cam-driver/<id>/…`.

Every operation of a module - connect, capture, save - sits under `hdvisionsystems/lumiscan-cam-driver/<id>/control/<operation>/`. It is started either with the ready/request handshake or, for most operations, with a single write to `execute`. See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html) and [General Concept of Handshake](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html).

The settings files are read only when the application starts. Restart LumiScan Cam Driver after every change to them.

## Step 1 - Set up the network {#step-1-network}

1. Give the camera a fixed IP address with the manufacturer’s configuration tool:
   - Set a static (persistent) IP address, for example `192.168.1.21`, subnet mask `255.255.255.0`.

   - Switch off DHCP and Auto IP (link local).

     The address must lie in the subnet of the ctrlX CORE port the camera will use. If the camera is already connected to the ctrlX CORE but in the wrong subnet, you can also set its address from there, see [Setup Camera IP Address](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html).

2. Connect the camera, the ctrlX CORE and the engineering PC. Two topologies are possible - all three on one switch, or the camera directly on the ctrlX CORE. Both are described in [Hardware Setup for ctrlX X3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html).

3. Give the engineering PC an unused address in the same subnet, for example `192.168.1.123`. Do not use the address of the ctrlX CORE port; on a ctrlX CORE X3, XF10 has `192.168.1.1`.

4. In the ctrlX web interface, open **Settings > Network Interfaces** and select the port the camera is connected to.

5. Check the static IPv4 address of the port and switch off DHCP.

6. Under **Advanced settings**, set **MTU** to `8000` or `9000`, and click **Save**.

   ![ctrlX network interface settings with the static IP address and the MTU field highlighted](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-network.png)

   *Figure 1. Network interface of the ctrlX CORE with static IP address and MTU*

> [!NOTE]
> Images are large, so the camera sends them in jumbo frames. Without a large MTU - on the ctrlX CORE port, and on every switch in between - captures fail with status code `-10004` (`couldNotCaptureImage`). See [MTU Size Change](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#mtu-size-change).

## Step 2 - Configure LumiScan Cam Driver {#step-2-settings}

1. In the ctrlX web interface, go to **Home > Manage app data** and click **Open file view**.

   ![Manage app data with the Open file view button highlighted](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-file-view.png)

   *Figure 2. Opening the file view of the app data*

2. Open the folder `lumiscan-cam-driver`. It holds the application settings, the module files, and the folders `schemas` and `images`.

3. Create the module file for your camera, for example `camera1.json`. The easiest way is to copy the example module file the application installed, then change these values:
   ```json
   {
     "id": "camera1",
     "serial": "LX123456",
     "exposureTimeUS": 4321,
     "pixelFormat": "RGB8"
   }
   ```
   - `id` - the module’s name on the Data Layer. Only lower-case letters, digits, `-` and `_`, unique across all modules.

   - `serial` - the camera’s serial number, as printed on the camera or shown by the manufacturer’s tool.

   - `exposureTimeUS` - exposure time in microseconds.

   - `pixelFormat` - `RGB8` or `Mono8`.

     Keep the `$schema` and `meta` entries of the example file. All parameters are described in [Camera Example File Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html).

4. Open `lumiscan-cam-driver.json` and enter the module file in the `modules` list:
   ```json
   "modules": [
     "camera1.json"
   ]
   ```

   Each file in the list must exist, and no two modules may use the same camera serial number.

   ![lumiscan-cam-driver.json opened in the file view of the ctrlX web interface](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-app-settings.png)

   *Figure 3. Application settings with the list of module files*

5. Click **Save**, then restart LumiScan Cam Driver: **Settings > Apps**, select **LumiScan Cam Driver** and click **Restart**.

> [!TIP]
> The settings can also be read and changed on the Data Layer, on `hdvisionsystems/lumiscan-cam-driver/system/settings`. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html).

## Step 3 - Check that the camera is found {#step-3-detection}

Open **Settings > Data Layer** in the ctrlX web interface and go to `hdvisionsystems/lumiscan-cam-driver/system`. The cameras found in the network are listed in:

- `found-camera-serials`
- `found-camera-ip-addresses`
- `found-camera-mac-addresses`
- `found-camera-modules`

The lists are in the same order, so the first serial belongs to the first IP address and the first MAC address.

![Data Layer browser showing the found-camera nodes under lumiscan-cam-driver/system](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-found-cameras.png)

*Figure 4. Cameras found by LumiScan Cam Driver*

Expected: the serial number from your module file is listed, with an IP address in the subnet of the ctrlX CORE port. Below `hdvisionsystems/lumiscan-cam-driver`, a folder with your module’s `id` exists.

If the camera is missing, check the cabling and the subnet first. If the module folder is missing, read `system/settings`: a module file that could not be read is shown there with the reason.

## Step 4 - Connect the camera {#step-4-connect}

Connecting takes several seconds, so it is only offered as a handshake. Use these nodes:

```
hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/ready
hdvisionsystems/lumiscan-cam-driver/camera1/control/connect-camera/request
```

1. Wait until `ready` is `true`.
2. Set `request` to `true`.
3. Wait until `ready` is `false`: the application has seen the request.
4. Set `request` back to `false`.
5. Check `hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected`.

Expected: `is-connected` is `true`. The camera is connected and ready to capture.

![Data Layer browser with the connect-camera ready and request nodes and device-info/is-connected highlighted](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-connect.png)

*Figure 5. Connect-camera nodes and the connection state*

> [!NOTE]
> Check the connection with `is-connected`, not with the status code. A failed connection shows `-10000` on `control/status/code` for about 100 ms only, then `0` again.

## Step 5 - Capture an image {#step-5-capture}

The simplest way is one write to the `execute` method:

1. Write to `hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute`. The write returns when the capture has finished.
2. Read `hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code`.

Expected: the status code is `0`, and `output/package-identifier` has grown by one. The image is now on

```
hdvisionsystems/lumiscan-cam-driver/camera1/output/image
```

with its `data`, `width`, `height` and `pixel-type`. Other LumiScan applications read it from this address.

![Data Layer browser with the capture nodes and output/image with data](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-capture.png)

*Figure 6. Capture nodes and the image output*

You can also capture with the handshake on `control/capture/ready` and `control/capture/request`. A failed capture then ends at status code `3`; see [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).

> [!TIP]
> `output/image` holds raw sensor data. To look at the image, open LumiScan Cockpit, or switch on `camera1/input/preview/enable` to get a PNG on `camera1/output/preview/encoded-data` after each capture (from v2.1.0).

## Step 6 - Save captured images (optional) {#step-6-save}

Images are saved only when a storage is configured. It is set in the `system` section of `lumiscan-cam-driver.json`. For the application’s internal storage:

```json
"system": {
  "storage": {
    "type": "Internal",
    "parameters": {
      "rootPath": "images"
    }
  }
}
```

A relative `rootPath` is a folder inside the application’s own directory. For a USB storage device or an SD card, use its mount path, for example `/media/sdb1/myCapturedImages`. For a Windows shared folder, use the type `Samba`. All options are described in [Storage settings](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings) and [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files).

![lumiscan-cam-driver.json with the storage section highlighted](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-genicam-storage.png)

*Figure 7. Storage configured in the application settings*

1. Save the file and restart LumiScan Cam Driver.
2. Connect the camera (step 4) and capture an image (step 5).
3. Write to `hdvisionsystems/lumiscan-cam-driver/camera1/control/save/execute`.

Expected: the status code is `0`, and the image appears as a PNG file in the storage folder, by default in a sub-folder named after the camera.

## Result {#result}

- The camera has a fixed IP address and is found by LumiScan Cam Driver.
- The camera module is configured and connected.
- Every capture puts a new image on `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- Captured images can be saved to the configured storage.

## Next steps {#next-steps}

- Look at the images and results in LumiScan Cockpit.
- Evaluate the image with another LumiScan application: point its image address at `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`.
- Set camera features such as gain or trigger mode under `camera1/features`, see [GenICam features](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#genicam-features).
- Problems with detection, connection or capture: see [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html).

# How To: Test with Example Images Instead of a Camera – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/test-with-example-images.html

A **simulated camera** is a camera module of LumiScan Cam Driver that does not talk to a camera. Each capture loads the next image from a folder instead. To the other LumiScan applications it looks exactly like a real camera: the image appears on the same Data Layer nodes.

Use it to set up and test an evaluation - a code reader, LumiScan Template Finder, LumiScan AI Object Matching - with known example images, before the camera is installed or without stopping the line.

When you have finished, a module named `simulation` delivers your example images, one per capture, on `hdvisionsystems/lumiscan-cam-driver/simulation/output/image`.

## Before you start {#prerequisites}

- LumiScan Cam Driver installed on the ctrlX CORE, with a licence, see [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html)
- Example images as PNG files, ideally taken with the camera and lighting that will be used later
- A browser with access to the ctrlX web interface

## How it fits together {#overview}

Whether a camera module is simulated depends on its `serial`: a serial that contains `simulation` makes the module play images from the storage folder rather than search for a camera. The `id` is free.

The images are taken from the storage folder configured in `lumiscan-cam-driver.json`, in a sub-folder named after the module’s `id`: `images/simulation` for the settings in this guide. When the camera is connected, the module scans this folder; each capture then loads the next image.

> [!NOTE]
> Since v2.0.0, the images are taken from the sub-folder `<id>`, not from the storage folder itself. If `unifiedStorage` is set to `true` in the system settings (from v2.2.0), the storage folder itself is used.

## Step 1 - Create the module file {#step-1-module}

1. In the ctrlX web interface, go to **Home > Manage app data** and click **Open file view**.

   ![Manage app data page of the ctrlX web interface with the Open file view button](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-simulation-file-view.png)

   *Figure 1. Manage app data with the Open file view button*

2. Open the folder `lumiscan-cam-driver`.

3. Create the file `simulation.json`, for example as a copy of the example module file, with these values:
   ```json
   {
     "id": "simulation",
     "serial": "simulation"
   }
   ```

   Keep the `$schema` and `meta` entries of the example file.

   ![Module file in the file view with the serial simulation](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/howto-simulation-module-file.png)

   *Figure 2. Module file of a simulated camera: the serial contains simulation*

4. Open `lumiscan-cam-driver.json` and add `simulation.json` to the `modules` list:
   ```json
   "modules": [
     "simulation.json"
   ]
   ```

5. Check that `system` holds a storage, for example the internal storage:
   ```json
   "storage": {
     "type": "Internal",
     "parameters": {
       "rootPath": "images"
     }
   }
   ```

   See [Storage settings](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings).

## Step 2 - Upload the example images {#step-2-images}

1. In the file view of `lumiscan-cam-driver`, open the storage folder, `images` for the settings above.
2. Create a sub-folder named exactly like the module’s `id`: `simulation`.
3. Upload the example images into this folder.

The first capture loads the first image of the folder. For larger amounts of images, upload them with WebDAV, see [Uploading Data](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/uploading-data.html).

## Step 3 - Restart LumiScan Cam Driver {#step-3-restart}

Under **Settings > Apps**, select **LumiScan Cam Driver** and click **Restart**. The application reads its settings files only at start.

Expected: under `hdvisionsystems/lumiscan-cam-driver`, a folder `simulation` exists.

## Step 4 - Connect and capture {#step-4-capture}

Values on the Data Layer can be set in the ctrlX web interface under **Settings > Data Layer**, or by another application, for example a PLC program.

1. Connect the simulated camera with the handshake on `hdvisionsystems/lumiscan-cam-driver/simulation/control/connect-camera`: wait until `ready` is `true`, set `request` to `true`, wait until `ready` is `false`, set `request` to `false`.
2. Check that `simulation/device-info/is-connected` is `true`.
3. Write to `hdvisionsystems/lumiscan-cam-driver/simulation/control/capture/execute`.

Expected: `simulation/control/status/code` is `0`, and the first example image is on `hdvisionsystems/lumiscan-cam-driver/simulation/output/image`. Each further capture loads the next image.

> [!TIP]
> To see which image is loaded, open LumiScan Cockpit. It shows the image of the module `simulation` like that of a real camera.

## Step 5 - Use the images in another application {#step-5-use}

Point the image address of the evaluating application at the simulated camera:

```
hdvisionsystems/lumiscan-cam-driver/simulation/output/image
```

For LumiScan DMC Reader, for example, this is `input/image-address`; for LumiScan AI Object Matching, `externalImagePath` in the module file. To change to the real camera later, change only this address, or replace the module’s `serial` with that of the camera.

## Result {#result}

- LumiScan Cam Driver has a simulated camera, `simulation`.
- Each capture loads the next example image onto `hdvisionsystems/lumiscan-cam-driver/simulation/output/image`.
- Other LumiScan applications can be set up and tested with these images, without camera hardware.

More on simulation mode: [FAQ: How does simulation mode work?](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/faq.html#faq-simulation-mode) and [Loading Images](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#loading-images).

# Setup Camera IP address – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html

1. Make sure you only use one camera module and set serial to **simulation**

2. Restart LumiScan-Cam-Driver

3. You can see all found camera under `hdvisionsystems/lumiscan-cam-driver/system/found-camera-serials`

4. Find the camera serial you want to set

   i.e. GX030303 in above image. It present as first element in the list.

5. Copy the MAC address for corresponding camera.

   i.e. GX030303 is first serial, so we copy first MAC address

6. Set the following parameters (all parameters are described in [Table 4: Force IP Configuration](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#force-ip-configuration-of-camera)):

   a. gateway: 192.168.50.1

   b. macAddress: 00:0C:8D:60:76:5F

   c. ip: 192.168.50.2

   d. subnet: 255.255.255.0

7. Once above parameters are set, follow the [handshake convention](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html) to call force-ip

   a. Wait until ready = true. This node is read-only and is set by the application.

   b. Set request = true

   c. Set request = false

Once ready is back to true, you should be able to see the value from node system/found-camera-ip-addresses has changed.

If not, then please refer to supplier‘s program to set camera IP.

![simulation](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/simulation.png)

![found serials](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/found-serials.png)

![found macs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/found-macs.png)

# Execute a Method – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html

Every camera operation lives under the same address: `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/<operation>/`.

Most operations can be started in **two different ways**, and both lead to the same result:

- Write to the **`execute`** method node. This runs the operation once and only returns when it has finished. It is a single write, so no state has to be tracked in your program.
- Use the **ready/request handshake**. This starts the operation and returns immediately, leaving your program to watch the `ready` signal to learn when the operation has finished. See [General Concept of Handshake](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html).

The handshake works for every operation except `trigger`. The `execute` method is available for most, but not all of them.

**Table 1. Ways to start each operation**

| Operation | `execute` | ready/request |
| --- | --- | --- |
| `capture` | Yes | Yes |
| `save` | Yes | Yes |
| `load` | Yes | Yes |
| `remove` | Yes | Yes |
| `list-images` | Yes | Yes |
| `connect-camera` | No | Yes |
| `disconnect-camera` | No | Yes |
| `reset` | No | Yes |
| `trigger` | Yes | No |

> [!NOTE]
> Connect, disconnect and reset are deliberately not offered as `execute` methods. They can take several seconds, because they set up or tear down the full connection to the camera, and `reset` disconnects and connects again. A waiting method call would usually give up before the camera reports success, and would then report a failure for an operation that actually worked. Please use the ready/request handshake for those three.

## Software Trigger {#software-trigger}

`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/trigger/execute` sends the camera a software trigger, but only while the camera is in software trigger mode. In any other mode, such as a hardware trigger or free run, it does nothing and still answers `DL_OK`. The camera must be connected; until it is, the call answers `DL_INVALID_OPERATION_MODE`. There is no ready/request handshake for it: a trigger is over at once.

It is not a capture. The image goes wherever the camera’s acquisition delivers it: to the image stream while that runs. Outside a stream, the image waits in the camera’s queue (**number-of-images-in-queue**), and the next capture takes it unless the module file sets `clearBufferBeforeCapture`.

While the image stream runs, a camera without a software trigger mode - a simulated camera playing a folder of images, or a plugin camera without `TriggerSoftware` - is fired by its own trigger instead: each call gives one image on `control/publish/output/stream/frame`. See [Triggering the camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#triggering).

Software trigger mode means the camera’s trigger mode is on and its trigger source is software. The Cam Driver reads both in the camera’s own spelling, the same way it sets them when it connects: for example `On` or `Triggered`, and `Software` or `SoftwareTrigger`. GenICam’s `On` and `Software` apply for a camera that cannot list its values.

The command that fires the trigger is the camera’s own: GenICam’s `TriggerSoftware`, or `SoftwareTrigger` on a camera that names it so. When the camera is in software trigger mode but has neither command, or refuses it, the status becomes `-10012` (`softwareTriggerFailed`).

A camera that names its command, its trigger mode or source, or their values differently is given its own names in the application settings file. Add a feature mapping under `featureMappings`, and name it by the camera’s `featureMappingId`:

```json
"cameras": [
    { "cameraId": "camera1", "serial": "200900623", "driverId": "default", "featureMappingId": "acme" }
],
"featureMappings": [
    {
        "id": "acme",
        "features": { "TriggerSoftware": "FireTrigger" },
        "values": { "TriggerSource_Software": "SW" }
    }
]
```

Under `features`, the key is the common feature (`TriggerSoftware`, `TriggerMode`, `TriggerSource`, …), and the value is the camera’s name for it. Under `values`, the key is the common value (`TriggerSource_Software`, `TriggerMode_On`, …), and the value is the camera’s entry for it. The schema lists the keys. A mapped name is tried first. When the camera does not have it, the Cam Driver logs a warning and uses its built-in names. A `featureMappingId` that names no mapping stops the Cam Driver at start, with an error that names it. An unknown key makes the settings file unreadable: the Cam Driver logs an error that names the key and the valid ones, and runs without cameras.

## Calling execute {#calling-execute}

To run an operation, write to its `execute` node, for example:

`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/capture/execute`

The write returns once the operation has finished. Two results have to be kept apart:

- **Whether the operation could be started at all** is reported by the write itself. A rejected write is never queued, and the result says why. The table uses the names of the ctrlX Data Layer; LumiScan Keryx on a PC reports the same results as `TooManyOperations`, `InvalidOperationMode` and `ResourceUnavailable`, see [Results of a method call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#method-results):

  | Result | Meaning | What to do |
  | --- | --- | --- |
  | `DL_TOO_MANY_OPERATIONS` | The camera is busy with another operation right now, or the image stream is starting or stopping. | Retry. The same write succeeds once the running operation finishes. |
  | `DL_INVALID_OPERATION_MODE` | The operation’s `ready` signal is `false`, so the camera is in a state where this operation cannot run — for example `capture` while the camera is not connected. | Do not retry blindly; it will keep failing. Bring the camera into the required state first, see [When is an operation ready](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#when-is-an-operation-ready). |
  | `DL_RESOURCE_UNAVAILABLE` | The application is shutting down, or the settings were changed on the Data Layer and a restart is required (`status/code` `-5`). | Shutting down: nothing, retrying does not help. Restart required: restart the application, see [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#restart-required). |

- **Whether the operation succeeded** is reported on `<camera name>/control/status/code` and `<camera name>/control/status/text`. A successful write therefore only means the operation ran — always check the status code afterwards. Unlike the handshake, `capture/execute` leaves a failed capture’s own code there; through the handshake, a failed capture ends at `3`. The meaning of each value is listed in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#status-code-values).

Results appear on the same output nodes in both cases, so a captured image can be read from `<camera name>/output/image` whichever way the capture was started.

## When is an operation ready {#when-is-an-operation-ready}

`execute` checks the very same `<operation>/ready` signal the handshake uses, and refuses to run while it is `false`. The signal is not a formality — most operations depend on something that has to happen first:

| Operation | `ready` is true when |
| --- | --- |
| `capture` | The camera is connected, no capture fault is latched, **and** the image stream is not running. A failed capture (for example a timeout) latches the fault and keeps `capture/ready` false until a `reset` succeeds — so a camera that captured once and then failed will keep refusing every later `capture/execute`. The image stream holds `capture/ready` false only while it runs and while the camera reconnects after it (about two seconds on the camera we tested); see [Capture while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#capture-while-streaming). |
| `save` | An image is available, that is after a successful `capture` or `load`. It is false right after the application starts. |
| `load`, `remove` | `<camera name>/output/image-files` is not empty. Run `list-images` first, or save an image. |
| `list-images` | Always. |

Since `connect-camera` and `reset` are only available through the handshake, a program that uses `execute` exclusively can never reach the state `capture` needs. Connect (and recover from a latched fault) through the handshake, then use `execute` for the day-to-day operations.

> [!TIP]
> When an `execute` is refused, read `<operation>/ready` together with `<camera name>/control/status/code` and `.../status/text`. `ready == false` names the missing precondition, and the status text still carries the message from the fault that caused it.

## Choosing which way to use {#choosing-between-the-two}

Use **`execute`** when your program can wait for the operation to finish. It is the simpler option: one write, and the operation is done when the write returns.

Use the **ready/request handshake** when:

- the operation is `connect-camera`, `disconnect-camera` or `reset`, which offer no `execute` method,
- your program must not block while the camera is working, or
- you already have a working program built on the handshake. The handshake is unchanged and keeps working, so there is no need to rewrite it.

# General Concept of Handshake – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html

The communication process in the LumiScan CamDriver application is based on the general concept of handshake. The naming convention for handshake parameters usually consists of the **functionality** and the names **-ready** or **-request**.

The handshake works for every operation except `trigger`. Most operations can also be started with a single write to their `execute` node — see [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html) for a comparison of the two ways.

Each operation has a `<parent address>/<functionality name>/ready` node (read-only, set by the application: `true` when the functionality may be started) and a `<parent address>/<functionality name>/request` node (writable, set by you to start it). The general handshake - its addresses, sequence and rules - is described in [Handshake](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html). This page describes how the Cam Driver follows it.

## Functionality Execution {#functionality-execution}

> [!NOTE]
> To avoid repeating the entire address, in this section the **invariant part** containing the parent address and the **variable functionality name** (capture, connect-camera, disconnect-camera) have been replaced by **XXX**.\
> Thus, the address: **`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/ready`** will be written as **XXX/ready**.

Accordingly, the address: **`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/request`** will be written as **XXX/request**.

> [!NOTE]
> Make sure there is only one process is accessing XXX/request at a time.\
> The result of execution is **undefined when**:

a. ProcessA set XXX/request to True.

b. ProcessB set XXX/request to False without considering ProcessA.

c. Our application might therefore miss XXX/request from ProcessA.

In order to execute a functionality, you need to run the following steps (see also [Functionality Execution Steps](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html#functionality-execution-steps)):

1. Wait until XXX/ready is set to **True**.
2. Set XXX/request to **True**.
3. Wait until XXX/ready changes to **False**: the application has seen the request.
4. Set XXX/request to **False**.
5. Wait for the functionality to finish, and read its outcome: see the table below.

**Functionality Execution Steps**

```mermaid
%% The ready/request handshake. Rendered by Mermaid in the browser; edit and preview at https://mermaid.live
sequenceDiagram
  autonumber
  participant C as Client (PLC or program)
  participant M as Module
  M-->>C: ready = true: the function can be started
  C->>M: request = true
  M-->>C: ready = false: the request was seen
  C->>M: request = false
  Note over M: runs the function
  M-->>C: ready = true: the function has finished
  C->>M: read control/status/code and output/
```

## When a Functionality Runs {#when-a-functionality-runs}

Only one request is served at a time, in this order: `reset`, `connect-camera`, `disconnect-camera`, `save`, `capture`, `load`, `list-images`, `remove`.

**Table 1. When each functionality runs**

| Functionality | Runs | At the end |
| --- | --- | --- |
| `capture` | At once, as soon as the application sees the request: it does not wait for XXX/request to fall. `status/code` is `2` (running) while it runs, then `3` (waitingForClient) while the application waits for XXX/request to fall. | Success: `status/code` `0`, `capture/ready` **True**, and `output/package-identifier` has grown by one.<br> **Failure: `status/code` stays `3`**, not the capture’s error code, and `capture/ready` stays **False** until a `reset` succeeds. |
| `connect-camera`, `disconnect-camera`, `reset`, `save`, `load`, `list-images`, `remove` | After XXX/request has fallen. `status/code` is `3` until then, and `2` while it runs. | `status/code` `0`, or an error (below `0`). |

A failed `capture`, `reset`, `save` or `load` is latched: its status stays until a `reset` succeeds. (A `save` before anything was captured, `-10005`, is not latched.) Any other error stays on `status/code` for about 100 ms only, then `0` replaces it. So check whether the camera is connected with `hdvisionsystems/lumiscan-cam-driver/<camera name>/device-info/is-connected`, not with the status.

To read the outcome of a capture directly, use `control/capture/execute` instead. The status then keeps the capture’s own code. See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html).

# Streaming Images (Experimental) – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html

> [!IMPORTANT]
> The image stream is **experimental** (from v2.3.0). Its nodes may still change. Use it for evaluation, and verify it with your camera before relying on it.

`capture` delivers one image per request, and each request waits until its image has arrived. On the camera we tested this gives about 34 images per second, well below what the camera itself can deliver: the next exposure cannot start before the previous image has been read out and sent.

The image stream works the other way round. While it runs, the Cam Driver publishes **every** image the camera delivers on `<camera name>/control/publish/output/stream/frame`. Your program subscribes to that node and is sent each image as it arrives - with its size, its pixel format and where it came from, see [What each frame carries](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#frames).

The stream is switched on and off by one function, `control/publish`: set its inputs, then call `control/publish/execute` to apply them. See [Running a stream](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#running-a-stream).

The general stream concept - producers, consumers and the lineage of their results - is described in [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html). This page describes the Cam Driver’s stream.

The Cam Driver does not trigger the camera by itself. An image comes when the camera is triggered - by a signal on its trigger input, or by `control/trigger/execute` - or, with the camera’s trigger mode off, as fast as the camera runs. See [Triggering the camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#triggering).

**Table 1. What a subscriber receives**

| Data Layer | Images delivered to a subscriber of `control/publish/output/stream/frame` |
| --- | --- |
| ctrlX Data Layer (ctrlX OS) | Every image, in order, as soon as it is published, whatever the subscription’s publish interval. Images are dropped only when the Data Layer falls far behind. |
| LumiScan Keryx (PC) | Every image, in order. The Data Layer drops images only when a subscriber falls far behind. |

Each frame carries its number in the stream, so a subscriber sees a dropped image as a gap. A read of `control/publish/output/stream/frame` always returns the latest image.

## Addresses {#addresses}

All addresses below start with `hdvisionsystems/lumiscan-cam-driver/<camera name>/`. They follow the rule of every `execute` method: the method owns its nodes, `control/publish/execute`, `control/publish/input/…` and `control/publish/output/…`.

**Table 2. The method and its inputs**

| Address | Type | Default | Meaning |
| --- | --- | --- | --- |
| `control/publish/execute` | method |   | Applies the inputs below together. Writing an input alone changes nothing. Returns at once: the stream starts or stops within the Cam Driver’s next cycle, and `control/publish/output/stream/active` says when it runs. Refused with `DL_RESOURCE_UNAVAILABLE` while the Cam Driver shuts down, or after its settings were changed on the Data Layer (`system/restart-required`). Refused with `DL_CREATION_FAILED` when a changed `tag` cannot be saved: nothing changes then. |
| `control/publish/input/enable` | bool | `false` | `true` runs the stream while the camera is connected; `false` stops it. |
| `control/publish/input/keep-latest-output` | bool | `false` | `true` copies every streamed image to `output/image` as well: `data`, `width`, `height`, `pixel-type` and `timestamp` (the time the image arrived), and then increases `output/package-identifier` by one, as `capture` does. Each copy takes time, which slows a fast stream down. Applied to a running stream without restarting it. See [Capture while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#capture-while-streaming). |
| `control/publish/input/tag` | string | `stream.tag` of the module configuration file, or empty | The tag on the module’s images: the camera’s step in their lineage carries it, and so do the results of every application that processes them. Empty: the camera name, for example `camera1`. Give it another, for example the station the camera looks at, to see that in every result. Applied to a running stream without restarting it. See [The tag](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#tag). |

What `execute` applied is not saved, except the tag: after the Cam Driver starts, the stream is off until `control/publish/execute` is called with `enable` `true`.

**Table 3. The method’s outputs, under `control/publish/`**

| Address | Type | Meaning |
| --- | --- | --- |
| `output/stream/active` | bool | `true` while the stream runs. |
| `output/stream/frame` | flatbuffers (`stream_image`) | Each streamed image: the pixels, their size and format, and the image’s lineage. Subscribe to it to receive the images. See [What each frame carries](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#frames). |
| `output/stream/width`, `output/stream/height` | uint64 | Size of the streamed images in pixels, for browsing. Each frame carries its own. |
| `output/stream/pixel-type` | string | Pixel format of the streamed images, for browsing. Each frame carries its own. |
| `output/stream/statistics/…` | uint64 | Counters of the current or last stream, see [Reading the statistics](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#statistics). |

**Table 4. Beside the method**

| Address | Type | Meaning |
| --- | --- | --- |
| `setting/settings-hash` | string | The hash of the settings the images are taken with, as 16 hex digits. See [The settings hash](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#settings-hash). |
| `setting/stream/tag` | string | The tag `control/publish/execute` applied last, as the images carry it. Empty: the images carry the camera name. |

### The tag {#tag}

A changed `control/publish/input/tag` is saved in the module configuration file, as `stream.tag`, before `control/publish/execute` applies it, the rest of the file as it was. So the images carry it after a restart too, and `control/publish/input/tag` starts with it. If the file cannot be written, `control/publish/execute` answers `DL_CREATION_FAILED`, and neither the tag nor the other inputs change. An unchanged tag is not saved, so a module whose file cannot be written still streams.

The tag is not part of the settings hash: it names the images, it does not change them.

## Triggering the camera {#triggering}

Each trigger the camera receives gives one image on `control/publish/output/stream/frame`. Set the camera’s trigger mode before you start the stream, through its feature nodes under `features` or in a feature file.

| Images come | Camera settings | What to do |
| --- | --- | --- |
| On a hardware trigger | `TriggerMode` `On`, `TriggerSource` a trigger input, for example `Line0` | Send a pulse to the trigger input for each image. |
| On request | `TriggerMode` `On`, `TriggerSource` `Software` | Call `control/trigger/execute` once for each image. The Cam Driver sends the camera’s software trigger, as hdv’s feature mapping names it. |
| Continuously | `TriggerMode` `Off` | Nothing. The camera delivers as fast as it runs, or at its `AcquisitionFrameRate` where that is enabled. |

A camera without a software trigger mode - a simulated camera playing a folder of images, or a plugin camera without `TriggerSoftware` - takes one image for each call to `control/trigger/execute` as well.

`control/trigger/execute` answers when the trigger has been sent, not when its image has arrived. A camera that is still busy with the previous image can ignore a trigger without reporting it, see [For the highest frame rate: TriggerOverlap](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#trigger-overlap).

### For the highest frame rate: TriggerOverlap {#trigger-overlap}

With the GenICam feature `TriggerOverlap` set to `Off`, a camera takes the next image only once the previous one has been read out, and it ignores a trigger that comes earlier. An overlap lets the next exposure start while the previous image is still read out or sent, which raises the frame rate the camera reaches.

**To stream at the highest frame rate, `TriggerOverlap` must not be `Off`.** Set it to an overlap your camera supports - `PreviousFrame` or `ReadOut`, see its documentation - in a feature file of the camera module, one feature per line:

```none
TriggerOverlap PreviousFrame
```

List the file in the module’s `cameras[].featureFiles`. The Cam Driver applies it each time it connects the camera, before acquisition starts, so it holds for `capture` as well. A feature node under `features` works too, but some cameras refuse trigger features while they acquire, and the value is lost when the camera is connected again.

## What each frame carries {#frames}

`control/publish/output/stream/frame` holds a FlatBuffers table of type `stream_image`, registered on the Data Layer as `types/hdvisionsystems/lumiscan-cam-driver/stream_image`. Its compiled schema is installed as `bfbs/stream_image.bfbs`.

| Field | Meaning |
| --- | --- |
| `image.data` | The pixels, row after row, without padding. |
| `image.width`, `image.height` | The image size in pixels. |
| `image.pixel_type` | The pixel format, for example `Mono8`. |
| `lineage.steps` | Where the image came from. For a camera image this is one step, the camera’s own:<br><br>\* `producer`: the camera’s address, `hdvisionsystems/lumiscan-cam-driver/<camera name>`. \* `tag`: the module’s tag, `setting/stream/tag`, or the camera name when it is empty. See [The tag](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#tag). \* `run`: when the stream started, in microseconds since 1970. Each start of the stream is a new run. \* `sequence`: the image’s number in the run, from 1. A gap means images were lost on the way. \* `external_id`: the camera’s own frame number (the GigE Vision block id). A gap here without a gap in `sequence` means images were lost between the camera and the Cam Driver. \* `time_us`: when the image was published, in microseconds since 1970. \* `settings_hash`: the settings the image was taken with, see [The settings hash](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#settings-hash). |

The applications that process the stream - AI Object Matching, Calibration - copy the lineage of what they receive and add a step of their own, with their own tag. Their results therefore still name the camera image they came from, by `producer`, `run` and `sequence`, and each step says by its `tag` which module made it.

## The settings hash {#settings-hash}

`setting/settings-hash` and the `settings_hash` of each frame identify the settings the camera works with. The hash changes when one of them changes:

- the module settings and the feature files, as the camera was connected with;
- every camera feature written while the camera is connected, for example `ExposureTime` through `input/exposure-time` or a feature node under `features`, with the value the camera accepted;
- the Cam Driver’s version.

Settings that only affect how images are transported, such as the timeout or the packet size, do not change the hash. The first time a hash appears, the Cam Driver writes the settings it stands for to `settings-history/<camera name>-<hash>.json` in its configuration folder, so a hash found in a result can be looked up later.

> [!NOTE]
> A camera takes the images that are already on their way with the old settings. The images that arrive right after a feature was written can carry the new hash although they were taken before the change.

### What the hash does not tell {#settings-hash-limits}

- **That, not what.** A frame carries the hash only. A different hash says that something the images are taken with changed, not what changed. To find out, compare the two files in `settings-history` that the hashes name, by hand. The files are on the device the Cam Driver ran on.
- **Only what goes through the Cam Driver.** The hash follows a feature node under `features`, `input/exposure-time`, and the settings and feature files the camera was connected with. It does not follow values the camera changes by itself: with `ExposureAuto` on, the hash follows the `ExposureAuto` setting, not the exposure times the camera picks.

> [!IMPORTANT]
> That the hash follows a camera feature change has so far been tested only in unit tests, with a stand-in for the camera, not with a real camera. Until it has been, do not rely on the camera’s settings hash alone to show that a camera feature changed.

## Running a stream {#running-a-stream}

1. Connect the camera with the `connect-camera` handshake. See [Connection Steps](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#connection-steps).
2. Set the camera features you need, such as the exposure time, the trigger mode and `TriggerOverlap`, **before** starting the stream. See [Triggering the camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#triggering).
3. Subscribe to `control/publish/output/stream/frame`.
4. Set `control/publish/input/enable` to `true`, and `control/publish/input/keep-latest-output` to `true` if you also want each image on `output/image`.
5. Call `control/publish/execute`, and wait until `control/publish/output/stream/active` is `true`.
6. Trigger the camera. Each image arrives on `control/publish/output/stream/frame`.
7. To stop, set `control/publish/input/enable` to `false` and call `control/publish/execute` again. `control/publish/output/stream/active` turns `false` within the next cycle.
8. Before capturing again, wait until `control/capture/ready` is `true`. See [After the stream](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#after-the-stream).

Good to know:

- The inputs take effect only on `execute`, all together. A program can therefore set them in any order, and nothing changes half-way.
- What `execute` applied stays until the next `execute`: the stream runs for as long as `enable` was applied `true` and the camera is connected. Applied while the camera is disconnected, the stream starts as soon as the camera is connected.
- `connect-camera`, `disconnect-camera` and `reset` stop a running stream. If `enable` was applied `true`, the stream starts again once the camera is connected.
- If the stream cannot start, `control/publish/output/stream/active` stays `false` and the reason is written to the log. It is not retried until `control/publish/execute` is called again.
- A camera ignores triggers that come faster than it can take images, without reporting it. If `statistics/frames` grows more slowly than the number of triggers you sent, trigger less often or set an overlap, see [For the highest frame rate: TriggerOverlap](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#trigger-overlap).
- The exposure time on `input/exposure-time` and the inter-packet delay are not applied while the stream runs. Change camera features only while the stream is stopped.

## Capture while the stream runs {#capture-while-streaming}

The stream and `capture` use the camera in different ways, so they never run at the same time:

- `control/capture/ready` is `false` while the stream runs, so a program using the handshake waits.
- `control/capture/execute` answers `DL_INVALID_OPERATION_MODE` while the stream runs, and `DL_TOO_MANY_OPERATIONS` while the stream is starting or stopping. Do not retry `DL_INVALID_OPERATION_MODE` in a loop. Stop the stream and wait for `capture/ready` instead. See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html).
- A capture request that reaches the Cam Driver while the stream runs is refused with status `-3` (`invalidInput`), with the text "capture refused: the image stream (experimental) is active". It does **not** latch a fault, so no `reset` is needed.
- A stream that is switched on while a capture runs starts once that capture has finished. It never cuts a capture short.

Streamed images are published on `control/publish/output/stream/frame`. They reach `output/image` only while `keep-latest-output` is applied `true`: then each one replaces the image there, and `output/package-identifier` counts it as it counts a capture, continuing from the last capture’s number. `save` keeps saving the last image taken with `capture` or `load`, also then.

## After the stream {#after-the-stream}

While streaming, the camera delivers its images in a different acquisition mode from the one `capture` uses. To switch back, the Cam Driver disconnects the camera and connects it again when the stream stops, applying every connection setting as `connect-camera` does. `capture/ready` turns `true` once that has finished. Until then, `capture/execute` answers `DL_TOO_MANY_OPERATIONS`.

Starting and stopping therefore take different times. On the camera we tested:

| Step | Took | Mostly spent on |
| --- | --- | --- |
| Starting the stream | about 0.35 s | Switching the camera’s acquisition mode. |
| Stopping the stream, until `capture/ready` is `true` again | about 2.2 s | Connecting the camera again: opening the device (about 0.8 s) and reading all of its GenICam features for the Data Layer (about 0.8 s). |

So switch between streaming and capturing as rarely as you can. A program that needs single images while streaming can 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.

## Measured frame rates {#measured-frame-rates}

These figures were measured with a LUCID PHX016S (1440 x 1080, Mono8, exposure 1 ms) and LumiScan Keryx on one PC. They show the order of magnitude only: your camera, exposure time, network and Data Layer decide what you reach.

They were measured while the Cam Driver still triggered the camera itself, at a fixed rate. A hardware trigger or a continuously running camera is expected to give the same. Triggering with `control/trigger/execute` adds one method call per image; that has not been measured yet.

| Method | Images per second delivered |
| --- | --- |
| `capture/execute` in a loop | about 34 |
| Stream, `TriggerOverlap` `Off` | up to 63, every image delivered |
| Stream, `TriggerOverlap` `PreviousFrame` | up to 66, every image delivered |
| What the camera itself can deliver (`AcquisitionFrameRate`) | 71.7 |

## Reading the statistics {#statistics}

The counters, under `control/publish/output/stream/statistics/`, start from zero each time the stream starts, and are updated about four times a second while it runs.

| Counter | Meaning |
| --- | --- |
| `elapsed-ms` | Milliseconds since the stream started, measured by the Cam Driver. Divide a counter by it for a rate. |
| `frames` | Complete images the camera delivered. |
| `incomplete-frames` | Images the camera delivered incomplete. They are not published. |
| `lost-frames` | Images that never reached the Cam Driver, counted from gaps in the camera’s frame numbers. |
| `published-frames` | Images written to `control/publish/output/stream/frame`. |

# Initializing the Camera – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html

## 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).

## Addresses {#addresses}

Each operation offers a `ready` and a `request` node for the handshake. Most operations also offer an `execute` node, which runs the operation with a single write. See [Execute a Method](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html).

**Table 1. Table 2: Functionality Addresses**

| Functionality | Permission | Address |
| --- | --- | --- |
| Capture | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/capture/ready` |
| Capture | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/capture/request` |
| Capture | Write-Only (method) | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/capture/execute` |
| Save | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/save/ready` |
| Save | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/save/request` |
| Save | Write-Only (method) | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/save/execute` |
| Load | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/load/ready` |
| Load | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/load/request` |
| Load | Write-Only (method) | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/load/execute` |
| Remove | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/remove/ready` |
| Remove | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/remove/request` |
| Remove | Write-Only (method) | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/remove/execute` |
| List Images | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/list-images/ready` |
| List Images | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/list-images/request` |
| List Images | Write-Only (method) | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/list-images/execute` |
| Connect Camera | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/ready` |
| Connect Camera | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/request` |
| Disconnect Camera | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/disconnect-camera/ready` |
| Disconnect Camera | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/disconnect-camera/request` |
| Reset | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/reset/ready` |
| Reset | Writable | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/reset/request` |
| Status | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/code` |
| Status | Read-Only | `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/text` |
| Set Camera IP | Read-Only | `hdvisionsystems/lumiscan-cam-driver/system/force-ip/ready` |
| Set Camera IP | Writable | `hdvisionsystems/lumiscan-cam-driver/system/force-ip/request` |

> [!NOTE]
> Connect Camera, Disconnect Camera and Reset have no `execute` node. They can take several seconds, so a waiting method call would usually give up before the camera reports success. Please use the ready/request handshake for those three.

The addresses of the experimental image stream, all under `<camera name>/control/publish/`, are listed in [Streaming Images](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#addresses).

## Connection Steps {#connection-steps}

1. Start, connected to camera:

   a. Prerequest: camera is physically connected but is not yet connected in software (XXX/connect-camera/ready = False)

   b. Check XXX/connect-camera/ready = True
      > [!NOTE]
      > If there is no image captured (package-id is zero), **save/ready** is **false**.
      - If no new image is captured between two Save function calls, the program will still send the same file with the same filename.\*

      - If the setting is correct and an image has already been captured, the program sends the image to the configured server.

        \\\*Currently, the image is named:\
        **\<camera_serial>\_\<time stamp in seconds>.<6-digit in seconds>.png**.
        > [!NOTE]
        > To avoid repeating the entire address, in this section the **invariant part** containing the parent address has been replaced by **XXX**.\
        > Thus, the address: **`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/ready`** will be written as **XXX/connect-camera/ready**.

        Accordingly, the address: **`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/connect-camera/request`** will be written as **XXX/connect-camera/request**.
        > [!NOTE]
        > If is false, prerequest is not met or **no camera is found.\
        > Check whether camera ip is in the same local network as the ctrlX CORE or the PC.**
        > [!NOTE]
        > If XXX/capture/ready = False:

      - Camera could be in error state, not started or still capturing image.

      - Check status code for more information.
        > [!NOTE]
        > If XXX/capture/ready = True:

        i. Make sure that only one process is accessing XXX/connect-camera/request at a time.

        ii. Check that you are using the same datalayer version as the camera application.

        iii. Contact HD Vision Systems.

   c. Set XXX/connect-camera/request = True

   d. Check XXX/connect-camera/ready = False
      > [!NOTE]
      > If the CamDriver application hasn‘t seen that the variable has changed:

      i. Make sure that only one process is accessing XXX/connect-camera/request at a time.

      ii. Check that you are using the same data layer version as the camera application.

      iii. Contact hdvisionsystems.

   e. Set XXX/connect-camera/request = False

   f. Check `<camera name>/device-info/is-connected` = True ----→ Camera is initialized, and ready to capture image
      > [!NOTE]
      > Do not rely on XXX/status/code here. A failed connection shows `-10000` for about 100 ms only; then the status is `0` (ready) again, with the camera still not connected.

2. Capture image

   a. Prerequest: Camera is started (XXX/connect-camera/ready = False)

   b. Check XXX/capture/ready = True

   c. Set XXX/capture/request = True

   d. Check XXX/capture/ready = False. The capture is already running.

      \\\* The meaning of all status code values is explained in the [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#status-code-values) table.

   e. Set XXX/capture/request = False

   f. Check XXX/status/code (Camera) = 0 ---→ Capture image is successful
      > [!NOTE]
      > A failed capture leaves XXX/status/code at `3` (waitingForClient), not at its error code, and XXX/capture/ready stays False until a reset succeeds. To read the capture’s error code, capture with `control/capture/execute` instead. See [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).

   g. Image captured, you can access it at address `hdvisionsystems/lumiscan-cam-driver/<camera name>/output/image`

3. Disconnect Camera

   a. Prerequest: Camera is started and is not capturing (XXX/disconnect-camera/ready = True (internally it checks XXX/connect-camera/ready = False, XXX/capture/ready = True))

   b. Check XXX/disconnect-camera/ready = True

   c. Set XXX/disconnect-camera/request = True

   d. Check XXX/disconnect-camera/ready = False

   e. Set XXX/disconnect-camera/request = False

   f. Check `<camera name>/device-info/is-connected` = False ---→ Camera is disconnected

   g. The camera is released. To use it again, run Connect Camera.

## Saving Image Files {#saving-image-files}

The following options are available for storing images captured with the camdriver:

- Internally on system storage
- USB storage device or SD card attached to the device (only supports FAT32 or EXT4 file systems) (from LumiScan CamDriver 1.2.0 onwards) (ctrlX OS)
- using a Samba server (Windows shared folder) (from LumiScan CamDriver 1.0.1 onwards)

> [!NOTE]
> Please be aware that no images will be saved if the setting has not been configured, or has been configured incorrectly.

**To configure a USB storage device or an SD card (ctrlX OS):**

1. **Attach the storage device or insert the SD card**
2. **Log in to the ctrlX OS website**
3. **Select Settings**
4. **Select Storage Devices**
5. **Select the storage device that you have connected and wish to use from the list.**
6. **Click on the mount option**

> [!NOTE]
> If the storage device does not use a FAT32 or EXT4 file system, you will not be able to mount it. Instead you will be given the option to format the drive using either of these file systems. Note that this will delete all existing data from the storage device.

![mount](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/mount.png)

7. **In the dialog box select** **`For data exchange`** **and confirm by clicking on mount**
8. **The path for your storage device is shown in the right-hand column (e.g.** **`/media/sdb1`****). Note down that path.**

![path](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/path.png)

![mountDataExchange](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/mountDataExchange.png)

9. **You can configure the camdriver app to use this path as described in the Section** [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html)

To configure an external **Samba** storage folder:

1. Select the folder you want to share.

2. Right-click it.

3. Select **Properties.**

4. Select the **Sharing** tab.

5. Go to **Advanced Sharing.**

   ![ex storage 3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/ex_storage_3.png)

   ![ex storage 1](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/ex_storage_1.png)

6. Create a Windows or Samba user account with a password.
   > [!NOTE]
   > To access the shared folder, you need a Windows or Samba user account with a password. **For security reasons, please do not use your regular user profile**.\
   > The application currently only supports storing the password in clear text.

7. Click **Apply**.

8. Click **OK.**

9. Close **Advanced Sharing** window.

10. Verify that you can access to the folder with the configured user account.

    To create an account:

    a. Click **Permissions**

    b. Add user

    c. Configure permissions for this specific user.

       ![ex storage 4](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/ex_storage_4.png)

       ![ex storage 5](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/ex_storage_5.png)
       > [!NOTE]
       > After creating an external shared storage, you must make the appropriate changes to the **lumiscan-cam-driver.json** settings. See Section [Storage settings](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings) for more information on how to do this.
       > [!NOTE]
       > After restarting the program, check if there is an image in the shared folder. If there isn‘t one, check the log for incorrect settings information.

11. Restart the program.

12. Call **Connect Camera**.

13. Call **Capture**.

14. Call **Save**.

## Loading Images {#loading-images}

To load image files, follow these steps:

1. **Set up storage: Complete steps 1–10 in the Section** [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files) **to configure the storage location for image loading.**
2. **Execute Connect Camera.**
3. **Use the List Image command to view stored images.**
4. **Set** **`input/image-index`** **to specify the desired image.**
5. **Execute Load to transfer the image into the data layer.**
   - **Simulation mode: If enabled, calling Capture will load an image from the configured storage folder and automatically advance to the next image for the next Capture command.**

> [!NOTE]
> For additional information on simulation mode, refer to [Camera Example File Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html), which explains the **id** field.

## Status Code Values {#status-code-values}

The current status of a camera module is published on `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/code` as a number, and on `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/text` as the matching name. It reports the outcome of the last operation, whether that operation was started with the handshake or with an `execute` method.

**Table 2. Table 3: Status Code Values Description**

| Status Code Number | String | Meaning |
| --- | --- | --- |
| 0 | "ready" | The last functionality is successfully executed, the application is ready to execute the next functionality. |
| 1 | "settingUp" | The module or function is still setting up. |
| 2 | "running" | The function is currently running. |
| 3 | "waitingForClient" | Waiting for the client (usually for XXX/request to fall). Also the end of a capture requested through the handshake that failed: see [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). |
| -1 | "undefinedError" | Something went wrong and we did not create a special error code for it. |
| -2 | "invalidSetting" | The supplied settings file could not be loaded. |
| -3 | "invalidInput" | One of the input fields was not valid, or a capture was requested while the image stream runs. The second case latches no fault: stop the stream and capture again. See [Capture while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#capture-while-streaming). |
| -4 | "missingLicense" | Make sure you have the correct license installed. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html). |
| -5 | "restartRequired" | The settings files were changed on the Data Layer: restart the application. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#restart-required). |
| -10000 | "failedToConnectToCamera" | There was a problem connecting to the camera, please make sure the camera is connected. |
| -10001 | "pixelFormatNotSupported" | Invalid pixel format: Pixel type typo, or camera doens‘t support this type of pixel format. |
| -10002 | "couldNotSetPixelType" | The pixel format couldn‘t be set. Camera is still running, please stop and set again. |
| -10003 | "couldNotSetExposureTime" | Exposure time is out of range. Please check with the camera supplier for the permissible range of values. |
| -10004 | "couldNotCaptureImage" | There may be several causes of this problem: \* The camera may be disconnected, please reconnect. If it happens often, it may be a communication failure due to poor connection quality. \* Please make sure to use „Foil Shielded Twisted Pair“ cable. \* ctrlX OS: Check the MTU size setup in the ctrlX web page settings. It should be set to 8000 or 9000.\\\*<br> If you cannot change MTU size, switch to Ethernet port that supports large MTU size. (p.s. since 1.16 or 1.18 ctrlX supports changing MTU). \* PC: Check the MTU size (jumbo frames) setup of the network adapter the camera is connected to. It should be set to 8000 or 9000. |
| -10005 | "noImageTaken" | There is no image to work with yet. Capture an image before saving it. |
| -10006 | "saveImageFailed" | Check, if: \* **ip**, **username**, **password** are correctly configured in the setting, \* ip is reachable from the ctrlX CORE or the PC \* whether your samba (shared folder) has enough free space |
| -10007 | "loadImageFailed" | The selected image file could not be loaded. Check that the file is still present and readable in the storage folder. |
| -10008 | "noImageToLoad" | There is no image in the storage folder to load. Use List Images to check what is stored. |
| -10009 | "imageIndexOutOfRange" | The value of **index-of-image-to-load** does not refer to an existing image. Use List Images to check how many images are stored. |
| -10010 | "removeImageFailed" | The selected image file could not be removed. Check that the storage folder is writable. |
| -10011 | "producerInitFailed" | The GenTL producer could not be started. Check that the producer configured for this camera is installed and that its path is correct. |
| -10012 | "softwareTriggerFailed" | `control/trigger/execute` found the camera in software trigger mode, but the camera has neither `TriggerSoftware` nor `SoftwareTrigger` (nor the name its feature mapping gives), or refused it. See [Software Trigger](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#software-trigger). |

## MTU Size Change (ctrlX OS) {#mtu-size-change}

This section applies to ctrlX OS. On a PC, set the MTU size (jumbo frames) in the settings of the network adapter the camera is connected to.

\\\* For information on how to change the MTU size, see next section [MTU Size Change](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#mtu-size-change).

To change the camera‘s MTU size:

1. Log in to the ctrlX OS website.

2. Go to **Home.**

3. Select **Settings.**

4. Select **Network Interfaces.**

   ![s1](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s1.png)

   ![s11](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s11.png)

   ![s3ninterf](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s3ninterf.png)
   > [!NOTE]
   > The number of the currently used Ethernet port can be found next to the port entry on the ctrlX device. In this example, it is going to be XF12.

   ![xf12](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/xf12.png)

5. Select the currently used Ethernet port of your ctrlX device.

7. Expand **Advanced Settings.**

   ![s4nix12](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s4nix12.png)

   ![s5](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s5.png)

8. Enter the value you want to use in the MTU window (check status code **-10004** in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#status-code-values)).

9. Click **Save** to confirm.

10. A report confirming the change appears on the screen.

11. Once the changes have been saved, you can close the program.

## GenICam features {#genicam-features}

To edit GenICam features:

a. Ensure that the camera you wish to configure is connected as described in [Connection Steps](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#connection-steps).

b. In `hdvisionsystems/lumiscan-cam-driver/<cameraname>/features`, you will find a set of subnodes containing nodes. These correspond to GenICam feature categories and the individual features contained within them. The names, values, edit permissions and descriptions of these nodes are passed directly from the camera in question. This means that you can refer to the descriptions presented in the user interface.

For further information about these features, please refer to the documentation provided by your camera vendor.

## Force IP configuration of camera {#force-ip-configuration-of-camera}

![s6](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s6.png)

![s7](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/s7.png)

The IP configuration of a camera can be set to specific values. This is particularly useful if the current configuration is incorrect. The method described here can be applied even when the camera is not normally connected or detected, as long as it remains accessible through the same network connection.

Such a situation may occur when the camera’s configured subnet ID does not match the subnet ID of the ctrlX CORE or the PC. (The subnet ID is a part of the configured IP address. The subnet mask defines which portion of the IP address represents the subnet ID.)

The Data Layer addresses relevant for forcing a camera’s IP configuration can be found under: `hdvisionsystems/lumiscan-cam-driver/system/force-ip/`

The individual nodes are listed in the table 4.

To force the IP configuration of a camera:

1. Set the desired IP address, gateway, and subnet mask, as well as the MAC address of the camera.
2. Set the request signal to **true**, then back to **false**.

This process is analogous to the [General Concept of Handshake](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html).

> [!NOTE]
> when editing these values, they are written directly to the camera. Take care when editing values related to the camera‘s network connectivity, as this could result in a loss of connection. Be aware that changing these values can affect how images are taken.

> [!NOTE]
> When the camdriver app connects to a camera, it also sets the camera to acquisition mode. This affects which nodes can be written to.

**Table 3. Table 4: Force IP configuration of camera**

| Name | Description |
| --- | --- |
| gateway | The default gateway the camera will be set to |
| ip | The static IP address the camera will be set to |
| mac address | The MAC address of the camera. This address is used to identify the correct camera. |
| subnet | The subnet mask the camera will be set to |
| request | The request signal; to start the forcing the ip set it to true and then to false again |
| ready | The ready signal, it indicates that a reaquest can be made or that it is in progress. |

## Scenario 1 Connect Camera, Computer, ctrlX X3 via switch {#scenario-1-connect-camera-computer-ctrlx-x3-via-switch}

This scenario applies to ctrlX OS (ctrlX CORE X3). See also [Hardware Setup for ctrlX X3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html).

1. Access ctrlX X3, `settings/NetworkInterfaces/XF10`

   a. Set **General/MTU** to 8000

   b. **IPv4/DHCP** disable

   c. **IPv4/Address**, make sure 192.168.1.1 (should already exist by default)

   d. Click **save**

# Hardware Setup for ctrlX X3 – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html

This chapter applies to ctrlX OS only: it describes how to connect a camera to a ctrlX CORE X3.

## Overview {#overview}

The ctrlX X3 and camera can be connected using either of the following network topologies:

| Scenario | Topology | Considerations |
| --- | --- | --- |
| [Scenario 1: Shared Ethernet switch](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#scenario-1-shared-switch) | The camera, engineering computer, and ctrlX X3 are connected through an Ethernet switch. | This topology makes the ctrlX X3 easier to discover and maintain. The Ethernet switch must support jumbo frames. The camera driver’s packet delay might require adjustment. |
| [Scenario 2: Direct camera connection](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#scenario-2-direct-camera) | The camera is connected directly to XF10. The engineering computer is connected to XF51. | This topology can provide a more stable camera connection. However, the ctrlX X3 might not be discovered automatically by ctrlX WORKS. Record the static address assigned to XF51. |

## Scenario 1: Connect Through a Shared Ethernet Switch {#scenario-1-shared-switch}

1. Verify that the Ethernet switch supports jumbo frames.

2. Connect the camera, the engineering computer, and port XF10 of the ctrlX X3 to the Ethernet switch, as shown below.

   ![x3 2](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x3_-_2.png)

3. Configure the Ethernet adapter of the engineering computer with an unused address in the XF10 subnet.

   For example:
   ```
   IP address: 192.168.1.123
   Subnet mask: 255.255.255.0
   ```
   > [!IMPORTANT]
   > The ctrlX X3 uses `192.168.1.1` on port XF10. Do not assign `192.168.1.1` to the camera or engineering computer. Each device must have a unique IP address.

4. Continue with [Complete the Camera Setup](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#complete-camera-setup).

## Scenario 2: Connect the Camera Directly to XF10 {#scenario-2-direct-camera}

In this topology, the camera is connected directly to XF10 and the engineering computer uses XF51 for maintenance access.

> [!NOTE]
> This topology can provide a more stable camera connection. However, the ctrlX X3 might not be discovered automatically by ctrlX WORKS through XF51. Record the static XF51 address so that you can access the controller directly in a browser.

1. Open the following page on the ctrlX X3:

   `Settings > Network Interfaces > XF51 > IPv4`

2. Add a static IPv4 address for XF51 and save the configuration.

   For example:
   ```
   IP address: 192.168.42.203
   Subnet mask: 255.255.255.0
   ```
   > [!IMPORTANT]
   > Configure XF51 on a different subnet from XF10. XF10 uses the `192.168.1.0/24` network, so an address from the `192.168.42.0/24` network can be used for XF51. Do not configure both interfaces with `192.168.1.1`, or place both interfaces in the same subnet.

   ![x 6](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x_-_6.png)

3. Connect the camera directly to port XF10.

4. Connect the engineering computer to port XF51.

5. Configure the Ethernet adapter connected to XF51 with an unused address in the same subnet as XF51.

   For example:
   ```
   IP address: 192.168.42.123
   Subnet mask: 255.255.255.0
   ```

6. Open `192.168.42.203` in a browser to access the ctrlX X3.

   ![x 7](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x_-_7.png)

7. Continue with [Complete the Camera Setup](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#complete-camera-setup).

## Complete the Camera Setup {#complete-camera-setup}

After completing either network scenario, perform the following steps:

1. Follow [Set Up the Camera IP Address](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html) to assign the camera a unique IP address.
2. Configure the LumiScan CamDriver using either the Data Layer or the ctrlX X3 settings interface.

### Configure Through the Data Layer

![x 4](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x_-_4.png)

![x 3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x_-3.png)

### Configure Through Settings

![x 5.1](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x_-_5.1.png)

![x 5.2](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/x_-_5.2.png)

### Adjust the Packet Delay

The appropriate packet delay depends on the selected network topology, the camera, and the network equipment.

Test different packet delay values and select a value that provides stable image acquisition without dropped packets or communication interruptions. Record the selected value as part of the installation configuration.

# Setup Camera Configuration – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/setup-camera-configuration.html

The Cam Driver is configured with two kinds of files:

- **`lumiscan-cam-driver.json`** contains the application settings. Here you can specify configuration files for the camera you want to use.
- **`<extra file name>`** (here as example: camera_example.json) contains the configuration of one camera. You can configure the camera-relevant parameters here.

On ctrlX OS you edit them in the ctrlX OS website, on a PC in a text editor.

## Edit with Built-In Website (ctrlX OS) {#edit-with-built-in-website}

1. Log in to the ctrlX OS website.
2. Go to **Home.**
3. Select **Manage app data.**

3. Click the three dots and select **File View.**

   ![2a](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/2a.png)

   ![1a](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/1a.png)
   > [!NOTE]
   > See also [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html)

4. Go to the relevant application folder.

5. There are two files by default (You can add new files later).
   - **`lumiscan-cam-driver.json`** contains application settings. Here you can specify configuration files for the camera you want to use.
   - **`<extra file name>`** (here as example: camera_example.json) contains configuration for one camera. You can configure camera relevant parameter here.

6. Left-clicking on the desired filename will automatically open the JSON Settings window.

![2files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/2files.png)

![configurations](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/configurations.png)

![3a](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/3a.png)

The settings of the LumiScan CamDriver application are located in the **`lumiscan-cam-driver.json`**, and it is here that you should configure the general settings of the camera.\
An example of such settings is shown below.

The description of the parameters mentioned above can be found in the following [Table 5: Application Settings File: JSON Settings Description](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html).

## Edit the Files on a PC {#edit-on-a-pc}

On a PC the settings are files in the folder the Cam Driver reads its settings from (see [Uploading Data](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/uploading-data.html#on-a-pc)). Open them in any text editor, preferably one that checks JSON against the schemas in the `schemas` folder. Restart the Cam Driver after saving.

See also [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html).

# Application Settings Content Example – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html

> [!NOTE]
> If you don‘t want to set the parameters each time you connect to the camera, you can set the camera to a specific configuration by specifying its name.

```json
{
    "meta": {
        "inputFileType": "LumiScan-CtrlX-Cam-Driver",
        "inputFileVersion": "0.0.1",
        "targetMachine": "CtrlX7",
        "programName": "lumiscan-cam-driver",
        "programVersion": "0.0.1"
    },
    "configurations": [
        "camera_example.json"
    ],
    "system":{
        "debug": true,
        "logLevel": "INFO"
    }
}
```

**Table 1. Table 5: Application Settings File: JSON Settings Description**

| Parameter | Description |
| --- | --- |
| meta | Place to set meta information: inputFileType and inputFileVersion are required. |
| inputFileType | IIn this case it must be: `LumiScan-CtrlX-Cam-Driver` |
| inputFileVersion | Currently, only version 0.0.1 is supported. |
| targetMachine | Optional. Enter the name of the machine in use here to indicate that the current application configuration is being used for this particular machine. |
| programName | Optional. This parameter indicates by which application the current file is used. In this case: `lumiscan-cam-driver` |
| programVersion | Optional. Currently used program version. |
| configurations | This is a list of camera configuration files.<br> Camera serials should not be duplicated. |
| system | Setup of the configuration related to the device the Cam Driver runs on (ctrlX CORE or PC). |
| debug | Shows detailed message of i/o of datalayer. Possible values: **`true`** or **`false`** |
| logLevel | Change log level, possible values are: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF. |

```json
{
    "meta": {
        "inputFileType": "LumiScan-CtrlX-Cam-Driver",
        "inputFileVersion": "1.0.1",
        "targetMachine": "CtrlX7",
        "programName": "lumiscan-cam-driver",
        "programVersion": "1.0.1"
    },
    "configurations": [
        "camera_example.json"
    ],
    "system": {
        "debug": true,
        "logLevel": "TRACE",
        "storage": {
            "type":"Samba",
            "parameters": {
                "ip": "192.168.31.93",
                "remotePath": "temp",
                "domain": "domainname",
                "username": "username",
                "password": "password"
            }
        }
    }
}
```

## Storage settings {#storage-settings}

The JSON settings also determine where captured images are stored. To configure these settings, add new parameters to the system section. The example below shows a configuration that stores images on Samba storage. See [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files) for information on setting up such storage. The added settings are shown in red.

Use the following settings to configure a USB storage device or SD card (ctrlX OS). Note that the beginning of the path must match the one shown to you earlier when you set up the storage device, as explained in [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files).

```json
           “storage“:{
                “type“:“Internal“,
                “parameters“: {
                    “rootPath“: “/media/sdb1/myCapturedImages“
                }
            }
```

The description of the storage parameters can be found in the following [Table 6: Storage Parameters Description](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings).

**Table 2. Table 6: Storage Parameters Description**

| Parameter | Description |
| --- | --- |
| storage | If not specified, the save function will do nothing. |
| type | Type of supported external or internal storage. Possible values are **Null**, **Internal** (Internal storage; on ctrlX OS also a USB storage device or SD Card) and **Samba** (Windows shared folder) |
| rootPath | This is only used for the storage type ‚Internal‘. It specifies the location where the image files are stored. If a relative path is specified, (i.e. not starting with a /), the images will be stored in the internal directory of the LumiScan-Cam-Driver application. On ctrlX OS, if a path starting with the path of a USB storage device or SD card is specified. (e.g. `/media/sdb1/myCapturedImages`), the images will be stored on that device. |
| parameters | Here: Parameters for **Samba** type. |
| ip | Samba server IP |
| domain | Domain name of the local network.<br><br>If the server is on a domain, please check with your IT department to ensure that there is no additional firewall on the domain.<br><br>If there is no domain name, enter it as „“. |
| remotePath | The rest of the path when accessing the shared folder. (Users can access the folder directly with `//<ip>/<remotePath>`). |
| username | Username of Samba (Windows shared folder) Server |
| password | The password is stored in clear text. Therefore, it is not recommended to use a regular user to access the shared folder. |

> [!NOTE]
> After changing the parameters, the LumiScan CamDriver application should be restarted.

## Complete reference {#complete-reference}

Every setting of this file as its JSON Schema `lumiscan-cam-driver.schema.json` defines it, generated for version 2.2.1:

| Setting | Type | Default | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `meta` | object |   |   | **Required.** Meta information about the application and current setting. This is mainly for information purpose and not used by the application itself |
| `meta/inputFileType` | string |   | not empty | **Required.** |
| `meta/inputFileVersion` | string |   | not empty | **Required.** |
| `meta/targetMachine` | string |   | not empty | **Required.** |
| `meta/programName` | string |   | not empty | **Required.** |
| `meta/programVersion` | string |   | not empty | **Required.** |
| `modules` | string[] |   | at least 1 entry | **Required.** List of module setting files that will be loaded by the application. One camera per entry; each file is resolved next to this settings file. |
| `cameraDrivers` | object[] |   |   | GenTL producers (camera drivers) available to camera modules. Each camera references one of these by its 'driverId'. |
| `cameraDrivers[]/id` | string | `default` | not empty | **Required.** Unique id referenced by a camera module's 'driverId'. |
| `cameraDrivers[]/gentlPath` | string |   | not empty | **Required.** Path to the GenTL producer (.cti). Relative paths resolve from SNAP_COMMON; absolute paths are used as-is. For SIMULATION mode this should be a directory path. |
| `cameraDrivers[]/genTLConsumer` | string | `DEFAULT` | `DEFAULT`, `SIMULATION`, `BASLER`, `BALLUFF`, `LUCID`, `PEPPER_FUCHS` | Type of GenTL consumer. DEFAULT uses Baumer. SIMULATION loads images from directory specified in gentlPath. |
| `system` | object |   |   |   |
| `system/debug` | boolean | `false` |   | Enable debug mode for the application. |
| `system/logLevel` | string | `INFO` | `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` | Log level for the application. |
| `system/storage` | object |   |   | Configuration for storage. The storage is used to store the images when save function is called. |
| `system/storage/type` | string |   | `Samba` | **Required.** The storage is a Samba storage. |
| `system/storage/parameters` | object |   |   | Parameters for the storage. The parameters are different for each storage type. |
| `system/storage/parameters/ip` | string |   | not empty | **Required.** The IP address of the Samba server. |
| `system/storage/parameters/remotePath` | string |   | not empty | **Required.** Share name and path on the Samba server, without the leading host part. |
| `system/storage/parameters/domain` | string |   | not empty | **Required.** Windows/Samba domain or workgroup the user belongs to. |
| `system/storage/parameters/username` | string |   | not empty | **Required.** |
| `system/storage/parameters/password` | string |   | not empty | **Required.** |
| `system/unifiedStorage` | boolean | `false` |   | If true, all cameras will share the same storage folder. If false, each camera will have its own storage folder. |

# Camera Example File Content Example – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html

> [!NOTE]
> The camera parameters can be overridden by setting the appropriate parameters in the path `…/input/` on the Data Layer.

The settings for a specific camera are located in the **`<extra file name>.json`**, here as an example named: **`camera_example.json`**.\
An example of such settings is shown below.

```json
{
    "meta": {
        "inputFileType": "camera-configuration",
        "inputFileVersion": "0.0.1",
        "targetMachine": "CtrlX7",
        "programName": "lumiscan-cam-driver",
        "programVersion": "1.0.0"
    },
    "id": "camera1",
    "serial": "LX123456",
    "exposureTimeUS": 4321,
    "pixelFormat": "RGB8"
}
```

The description of all the parameters mentioned above can be found in the t [Table 7: Camera Example JSON Settings Description](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html#).

**Table 1. Table 7: Camera Example JSON Settings Description**

| Parameter | Description |
| --- | --- |
| meta | Place to set meta information: inputFileType and inputFileVersion are required. |
| inputFileType | In this case it must be: `camera-configuration` |
| inputFileVersion | Currently, only version 0.0.1 is supported. |
| targetMachine | Optional. Enter the name of the machine in use here to indicate that the current application configuration is being used for this particular machine. |
| programName | Optional. This parameter indicates by which application the current file is used. In this case: `lumiscan-cam-driver` |
| programVersion | Optional. Currently used program version. |
| id | This is an id of current camera setting.<br> It must be **unique** across all camera settings.<br><br>It is the module’s name on the Data Layer: `hdvisionsystems/lumiscan-cam-driver/<id>/...`. Only lower-case letters, digits, `-` and `_` are allowed. A module whose id has an upper-case letter or any other character is not loaded; the log says which id to write instead (`Camera1` → `camera1`).<br><br>Whether the camera is simulated depends on its serial (one containing `simulation`), not on this id. |
| serial | Serial number of camera. |
| exposureTimeUS | Exposure time in macro seconds. |
| pixelFormat | Pixel format of the image, possible values are: RGB8, Mono8. |
| timestampSource | Source of the timestamp for each frame. **Camera** uses the timestamp provided by the camera hardware, while **System** uses the system clock of the device the Cam Driver runs on (ctrlX CORE or PC). |
| stream.tag | Optional, experimental. The tag on the images of the module’s image stream; empty or left out: the module id. `control/publish/execute` saves it here when it changes. See [The tag](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#tag). |

> [!NOTE]
> After changing the parameters, the LumiScan CamDriver application should be restarted.

> [!NOTE]
> On ctrlX OS, you can also rename the new file later by clicking the triple dots to the right of the name and selecting **Rename** from the expanded list.

## Complete reference {#complete-reference}

Every setting of this file as its JSON Schema `lumiscan-cam-driver-module.schema.json` defines it, generated for version 2.2.1:

| Setting | Type | Default | Allowed values | Description |
| --- | --- | --- | --- | --- |
| `meta` | object |   |   | **Required.** |
| `meta/inputFileType` | string |   | not empty | **Required.** |
| `meta/inputFileVersion` | string |   | not empty | **Required.** |
| `meta/targetMachine` | string |   | not empty | **Required.** |
| `meta/programName` | string |   | not empty | **Required.** |
| `meta/programVersion` | string |   | not empty | **Required.** |
| `id` | string |   | pattern `^[a-zA-Z0-9_-]+$` | **Required.** only [a-Z], [0-9], '-' and '\_' are allowed. Unique ID of the camera configuration. This is used to identify different camera on datalayer. |
| `serial` | string | `simulation` | not empty | **Required.** Serial number of the camera. Special serial 'simulation' is used for testing without camera. This is used as default value in setting. And storage setup is required to be able to load image for simulation. |
| `exposureTimeUS` | number | `10000` | 500 … 2000000 | **Required.** Exposure time in microseconds. This is used as default value on datalayer and can be overwriten by the user. |
| `pixelFormat` | string |   | `Mono8`, `RGB8`, `BGR8`, `Mono12`, `RGB12`, `BGR12`, `BayerGR8`, `BayerRG8` | **Required.** Pixel format of the camera. Use bayer format if the camera support color and faster frame rate is required. This is used as default value on datalayer and can be overwriten by the user. |
| `exportPixelFormat` | string |   | `Mono8`, `RGB8`, `BGR8`, `Mono12`, `RGB12`, `BGR12` | Pixel format of the exported image. This is used as default value on datalayer and can be overwriten by the user. |
| `packetSize` | number | `1496` | 576 … 9000 | Size of the packet in bytes, must be multiple of 8. Please confirm it matches the configured MTU of the network. Default is 1496 bytes. This is used as default value on datalayer and can be overwriten by the user. It is only writeable only before camera is connected. |
| `packetDelay_us` | number | `0` | 0 … 12449 | Delay between packets in microseconds. Default is 0 microseconds. Increase it if image is corrupted or faild to capture image. This is used as default value on datalayer and can be overwriten by the user. |
| `timeout_ms` | number | `2000` | 100 … 10000 | Timeout in milliseconds. Default is 2000 milliseconds. How long to wait for the image to be captured before giving up. This is used as default value on datalayer and can be overwriten by the user. |
| `initialFeatureFile` | string |   |   | path to feature file with \<FEATURENAME> \<FEATURE VALUE> pairs. These values will be set after connect to camera. |
| `timestampSource` | string | `Camera` | `Camera`, `System` | Source of the timestamp for each frame. 'Camera' uses the timestamp provided by the camera hardware, while 'System' uses the system clock of the ctrlX. |
| `clearBufferBeforeCapture` | boolean | `false` |   | If true, the buffer will be cleared before capture, this is useful when the camera is running in continuous mode and we want to get the latest image. |
| `driverId` | string | `default` | not empty | Id of a GenTL driver defined in the app settings 'cameraDrivers' array. Defaults to 'default' (the built-in Baumer producer). |

# Creating New Camera Settings Files – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/creating-new-camera-settings-files.html

You create a new file with camera settings by copying an existing one under a new name, and then specify the new file name in the application settings (`lumiscan-cam-driver.json`). How to do this depends on the platform.

## On ctrlX OS {#on-ctrlx-os}

You can create a new file with camera settings simply by duplicating an existing file. To do this:

1. Click the triple dots you see to the right of the file name.

2. Select **COPY**

3. The copy file window appears.

4. Set new file name.

5. Confirm with clicking on **Copy.**

6. New camera settings file is created.

7. Now you can specify the newly created file name in the application settings (lumiscan-cam-driver.json):

   ![copywindow](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/copywindow.png)

   ![cameraexample3dots](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/cameraexample3dots.png)

8. Save the changes.

   a. Left-click on the lumiscan-cam-driver.json file name.

   b. The JSON settings window will open on the right.

   c. Enter the name in the `configuration` field.

![camdriverjson](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/camdriverjson.png)

![configurationsdet](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/configurationsdet.png)

## On a PC {#on-a-pc}

You can create a new file with camera settings by copying an existing one in the settings folder under a new name. Then specify the new file name in the `configuration` field of the application settings (`lumiscan-cam-driver.json`) and restart the Cam Driver.

### Starting from an Example {#starting-from-an-example}

The Cam Driver writes an example of its settings files, together with their schemas, into a folder of your choice, and ends without starting. For example (Windows):

```shell
lumiscan-cam-driver --generate-settings C:\work\cam-driver-settings
```

Without a folder (`-g` alone) it writes into the current folder. The example is the application settings file `lumiscan-cam-driver.json` with one simulated camera, its module file `lumiscan-cam-driver-example-module.json`, and the four schemas in `schemas\` that an editor uses to check them. Existing files are never overwritten: when one of them is in the folder already, nothing is written and the Cam Driver says which.

The Cam Driver then names the folder it reads its settings from. On Windows this is by default `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver`. Edit the example, copy it there, and start the Cam Driver.

A module can also be added on the Data Layer, on ctrlX OS and on a PC: 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).

# Settings on the Data Layer – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html

## 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 `<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 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/<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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#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` 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.

# Uploading Data – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/uploading-data.html

How the settings files reach the Cam Driver depends on the platform. They can also be changed on the Data Layer on both, see [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html).

## On ctrlX OS {#on-ctrlx-os}

> [!NOTE]
> Most data can be uploaded directly through the ctrlX Web UI. Use WebDAV only when direct upload is not available or when you need to access the application folder structure.

![ctrlx web ui upload](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/ctrlx-web-ui-upload.png)

Configuration upload is optional and can be used to upload custom application settings.

1. Go to the WinSCP website.

2. Download and install the latest version of WinSCP.

3. Start WinSCP.

4. On the login page, select **WebDAV** as the **File protocol**.

5. Select **TLS/SSL** for **Encryption**.

6. Enter your **user name** and **password**.

   ![WinSCP](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/WinSCP.png)

   ![dav1](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/dav1.png)

7. Navigate to **/solutions/webdav/appdata**.

8. The application folder structure is displayed in the right panel.

You can drag and drop data and settings into the corresponding application folder.

For an example configuration, see [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html).

![dav3](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/dav3.png)

![dav2](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/dav2.png)

## On a PC {#on-a-pc}

On a PC the settings files are ordinary files. Copy them into the folder the Cam Driver reads its settings from. The Cam Driver names this folder when it writes an example of its settings, see [Starting from an Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/creating-new-camera-settings-files.html#starting-from-an-example). On Windows it is:

- `%APP_RESOURCE_DIR%\etc\lumiscan-cam-driver`, when the environment variable `APP_RESOURCE_DIR` is set;
- otherwise `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver`.

Restart the Cam Driver after changing a file. For an example configuration, see [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html).

# Troubleshooting – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html

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 {#general-checks}

### Configuration {#general-configuration}

The Cam Driver uses a two-level configuration:

- The **app configuration** (`lumiscan-cam-driver.json`) defines which camera modules are loaded.
- Each **camera configuration** (for example `camera_example.json`) represents one camera.

If a camera configuration is missing, invalid, or not referenced correctly, the camera is not loaded and does not appear in the Data Layer.

Configurations are available under:

| Platform | Location |
| --- | --- |
| ctrlX OS | `Manage App Data > active > lumiscan-cam-driver` |
| PC (Windows) | `%APP_RESOURCE_DIR%\etc\lumiscan-cam-driver`, or without `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-cam-driver\etc\lumiscan-cam-driver` |

On both platforms, `/hdvisionsystems/lumiscan-cam-driver/system/settings` shows the files as the Cam Driver read them at start. A module file that could not be read appears there with an `"$error"` that says why. The Cam Driver reads its files only at start: restart the application after you change a file. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#what-the-node-shows).

### Status of a camera module {#general-status}

Each camera module reports the outcome of its last operation on `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/code` (a number) and `.../control/status/text` (its name). The meaning of each value is listed in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#status-code-values).

- 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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html#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.

### Logs {#general-logs}

If an issue persists, check the log for additional error information:

- **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](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html).
- **PC:** the output of the Cam Driver in its console.

`logLevel` in the `system` section of `lumiscan-cam-driver.json` sets the log level: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR`, `FATAL` or `OFF`. See [Application Settings Content Example](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html).

A program that calls an `execute` method again and again while it is refused, for example `capture/execute` while the camera is busy, would write one log line per call. For each method and result, the application logs the first refusal, then at most one line every ten seconds, which says how many refusals were not logged one by one, for example "(+250 like it since the last one logged)". The `execute` result itself is still returned for every call.

### Data Layer {#general-data-layer}

For problems that concern the Data Layer itself - the broker of LumiScan Keryx, nodes that are not found, method results - see [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html) of LumiScan Keryx.

## Configuration and start {#configuration-and-start}

### Problem: A configured camera does not appear in the Data Layer {#faq-camera-not-in-data-layer}

**Symptoms**

There is no node `/hdvisionsystems/lumiscan-cam-driver/<module>` for a camera that you configured.

**Possible causes**

- 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).

**Diagnostic procedure**

1. Read `/hdvisionsystems/lumiscan-cam-driver/system/settings` - expected: the module’s content in the `modules` list. A module file that could not be read appears as `{"$file": ..., "$error": ...}`; `"$error"` says why.
2. Check that the camera configuration file is entered in the list of camera configuration files in `lumiscan-cam-driver.json` - expected: its file name is listed.
3. Check the `id` in the camera configuration file - expected: only lower-case letters, digits, `-` and `_`, and unique across all camera settings.
4. Read the log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#general-logs)) - expected: no error for the module. For an invalid `id`, the log says which id to write instead.
5. If no node `/hdvisionsystems/lumiscan-cam-driver` exists at all, the application itself is not running.

**Resolution**

- **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.
  1. Correct the files, or change them on the Data Layer through `system/settings`.
  2. Restart the application, for example with `hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute`.
  3. Check that `/hdvisionsystems/lumiscan-cam-driver/<module>` exists.
- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/camera-example-file-content-example.html).
- **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"](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-missing-license). For a PC and for other Data Layer causes, see [An app or a module is missing from the tree](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#app-missing).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of `system/settings` and the log lines from the start of the application.

### Problem: Modules answer no request, and the status is -5 "restartRequired" {#faq-restart-required}

**Symptoms**

- `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.

**Possible causes**

- 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.

**Diagnostic procedure**

1. Read `hdvisionsystems/lumiscan-cam-driver/system/restart-required` - expected: `true`.
2. Read `hdvisionsystems/lumiscan-cam-driver/system/status-text` - it says which files changed.
3. Read the log - the message is at error level.

**Resolution**

- **If the settings were changed on the Data Layer:**
  1. Call `hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute`. A `reset` does not help.
  2. Wait until `system/restart-required` can be read again. On ctrlX OS, the application ends, and ctrlX OS starts it again after about five seconds.
- **If a write answered `DL_CREATION_FAILED`:** correct the files, then restart the application as above.

See [Restart required](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html#restart-required).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of `system/status-text` and `system/settings`.

### Problem: "No valid license found, please purchase one. If you do have one, please try to restart ctrlX" {#faq-missing-license}

**Symptoms**

- `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.

**Possible causes**

- 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.

**Diagnostic procedure**

1. Read the ctrlX OS system log (see [Logs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#general-logs)) - it names the reason, the missing licence.
2. Open the **Licenses** page of ctrlX OS - expected: Cam Driver V2 licences for all connected cameras. Up to and including v2.1.0: one Cam Driver V2 entry that covers all cameras.
3. Compare the number of licences with the number of connected cameras - expected: one licence per camera.

**Resolution**

- **If no licence or not enough licences are installed:** install one licence `SWL-W-XCx-CAMDRIVERxHDVSx-V2NN` per connected camera. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html#licence).
- **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](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html) and [Licensing troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/troubleshooting.html).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the log lines that name the missing licence. For licences, contact [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).

## Camera connection {#camera-connection}

### Problem: A physically connected camera is not detected {#faq-camera-not-detected}

**Symptoms**

The camera is missing from the lists under `/hdvisionsystems/lumiscan-cam-driver/system`: `found-camera-ip-addresses`, `found-camera-mac-addresses`, `found-camera-modules` and `found-camera-serials`.

**Possible causes**

- 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.

**Diagnostic procedure**

1. Read `found-camera-serials`, `found-camera-ip-addresses`, `found-camera-mac-addresses` and `found-camera-modules` under `/hdvisionsystems/lumiscan-cam-driver/system` - expected: the camera is detected, its IP address is correct, and the serial number matches the expected device.
2. Check the cable - expected: the camera is connected to the ctrlX CORE or the PC; on ctrlX OS, to a supported ctrlX port.
3. Check the power supply - expected: the camera is powered, externally or via PoE.
4. Compare the IP address and subnet of the camera with those of the ctrlX CORE or the PC - expected: the camera is in the same local network.
5. Check the network for duplicate IP addresses - expected: each device has a unique IP address.

**Resolution**

- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#overview).
- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/setup-camera-ip-address.html).
  1. 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`).
  2. Set `gateway`, `ip`, `subnet` and the camera’s MAC address.
  3. Wait until `ready` is `true`, set `request` to `true`, then back to `false`.
  4. When `ready` is `true` again, check that `system/found-camera-ip-addresses` shows the new address. If it does not, use the camera supplier’s program to set the IP.
- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of the four `found-camera-…` lists and the network topology (switch or direct connection).

### Problem: The camera does not connect (status -10000 "failedToConnectToCamera") {#faq-failed-to-connect-to-camera}

**Symptoms**

- 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.

**Possible causes**

- The camera is not detected, see [Problem: 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 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.

**Diagnostic procedure**

1. Read `<module>/device-info/is-connected` - expected: `true` after `connect-camera`. Do not judge the connection by `control/status/code`.
2. Check that the camera appears under `/hdvisionsystems/lumiscan-cam-driver/system` - expected: its serial is in `found-camera-serials`.
3. Before the request, read `<module>/control/connect-camera/ready` - expected: `true`. If it is `false`, the precondition is not met or no camera is found: check that the camera IP is in the same local network as the ctrlX CORE or the PC.
4. After setting `connect-camera/request` to `true`, read `connect-camera/ready` - expected: `false` (the application has seen the request).
5. Check whether a PC on the same switch accesses the camera - expected: it does not.

**Resolution**

- **If the camera is not detected:** follow [Problem: 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).
- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#connection-steps).
- **If the connection still fails:**
  1. Power-cycle the camera by disconnecting it for approximately 30 seconds and reconnecting it.
  2. Verify that the camera appears in the Data Layer.
  3. Check the Ethernet configuration, such as buffer sizes and jumbo frames, according to the camera specifications.
- **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.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the camera serial number, the value of `device-info/is-connected` and the log lines of the connection attempt.

## Image capture and saving {#image-capture-and-saving}

### Problem: Image capture fails or is unreliable (status -10004 "couldNotCaptureImage") {#faq-could-not-capture-image}

**Symptoms**

- `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.

**Possible causes**

- 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.

**Diagnostic procedure**

1. Read `<module>/device-info/is-connected` - expected: `true`.
2. Check the cable - expected: a "Foil Shielded Twisted Pair" cable.
3. Check the MTU size - expected: 8000 or 9000.
   - ctrlX OS: **Settings** > **Network Interfaces** > the port in use > **Advanced Settings**.
   - PC: the MTU size (jumbo frames) of the network adapter the camera is connected to.
4. As a quick test, reduce the ROI - if image acquisition becomes more stable, the issue is likely related to network bandwidth.

**Resolution**

- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/hardware-setup-for-ctrlx-x3.html#complete-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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#genicam-features).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the content of `control/status/code` and `control/status/text`, the MTU size and the network topology.

### Problem: A write to execute answers "DL_TOO_MANY_OPERATIONS" or "TooManyOperations" {#faq-dl-too-many-operations}

**Symptoms**

A write to `<camera name>/control/<operation>/execute` answers `DL_TOO_MANY_OPERATIONS` (ctrlX Data Layer) or `TooManyOperations` (LumiScan Keryx).

**Possible causes**

- 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`.

**Diagnostic procedure**

1. Read `control/status/code` - `2` (`running`): another operation runs.
2. Read `control/publish/output/stream/active` and `control/capture/ready` - after the stream stops, `capture/ready` turns `true` once the camera is connected again.

**Resolution**

- **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.

`DL_RESOURCE_UNAVAILABLE` (`ResourceUnavailable`) is a different result: the application is shutting down - retrying does not help - or a restart is required, see [Problem: 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). See [Calling execute](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#calling-execute).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the operation you call and the result it answers.

### Problem: A write to execute answers "DL_INVALID_OPERATION_MODE", or capture keeps being refused {#faq-dl-invalid-operation-mode}

**Symptoms**

- 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.

**Possible causes**

The operation’s `ready` signal is `false`, so the camera is not in a state where the operation can run:

- `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.

**Diagnostic procedure**

1. Read `<operation>/ready` - `false` names the missing precondition.
2. Read `control/status/code` and `control/status/text` - the status text still carries the message from the fault that caused it.
3. Read `<camera name>/device-info/is-connected` - expected: `true`.
4. Read `control/publish/output/stream/active` - `true`: the image stream runs.
5. For `load` and `remove`, read `<camera name>/output/image-files` - expected: not empty.

**Resolution**

Do not retry blindly; establish the precondition first:

- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#faq-capture-refused-streaming).
- **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.

See [When is an operation ready](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#when-is-an-operation-ready).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the values of `<operation>/ready`, `control/status/code` and `control/status/text`.

### Problem: Images are not saved (status -10006 "saveImageFailed" or -10005 "noImageTaken") {#faq-save-image-failed}

**Symptoms**

- `control/status/code` is `-10006` (`saveImageFailed`) or `-10005` (`noImageTaken`).
- **Save** does nothing, or there is no image in the storage folder.

**Possible causes**

- `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.

**Diagnostic procedure**

1. Read `output/package-identifier` - if it is zero, no image has been captured, and `save/ready` is `false`.
2. Check the `storage` block in the `system` section of `lumiscan-cam-driver.json` - expected: a `type` (`Internal` or `Samba`) and its parameters. See [Storage settings](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/application-settings-content-example.html#storage-settings).
3. For `Samba`: check that `ip`, `username` and `password` are correct, that the IP is reachable from the ctrlX CORE or the PC, and that you can access the folder with the configured user account - expected: access works and the folder has free space.
4. For a USB storage device or SD card (ctrlX OS): check under **Settings** > **Storage Devices** that it is mounted - expected: its path (for example `/media/sdb1`) is the beginning of `rootPath`.
5. Read the log - it shows incorrect settings information.

**Resolution**

- **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:**
  1. Add or correct the `storage` block, see [Saving Image Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#saving-image-files).
  2. Restart the application.
  3. Call **Connect Camera**, **Capture** and **Save**, and check that an image is in the storage folder.
- **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.

A failed `save` is latched until a `reset` succeeds; a `save` before anything was captured (`-10005`) is not.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the `storage` block (the password is shown as `"*"` on `system/settings`) and the log lines of the failed save.

### Problem: Images do not match expectations {#ts-images-not-as-expected}

**Symptoms**

The captured images do not look as you expect from the camera settings.

**Possible causes**

- 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.

**Diagnostic procedure**

1. Save an image with `/hdvisionsystems/lumiscan-cam-driver/<module>/control/save/execute`, or the `save` handshake (`control/save/request`), and look at it - expected: it matches the settings.
2. Check where the camera features are set - expected: in a feature file listed in the module’s `cameras[].featureFiles`, which is applied each time the camera is connected.
3. Read `control/publish/output/stream/active` - `true`: the stream runs, and the exposure time is not applied.

**Resolution**

- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#genicam-features).
- **If the image stream runs:** stop the stream, change the camera features, then start the stream again.

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with a saved image, the camera configuration and the feature files.

## Image stream (experimental) {#image-stream}

### Problem: Capture is refused while the image stream runs {#faq-capture-refused-streaming}

**Symptoms**

- `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`.

**Possible causes**

- 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.

**Diagnostic procedure**

1. Read `control/publish/output/stream/active` - `true`: the stream runs.
2. After stopping the stream, read `control/capture/ready` - expected: `true` after about two seconds.

**Resolution**

- **If you need a capture:** stop the stream. No `reset` is needed: the refusal latches no fault.
  1. Write `false` to `control/publish/input/enable`.
  2. Call `control/publish/execute`.
  3. Wait until `control/capture/ready` is `true` again. That takes about two seconds on the camera we tested, because the camera is connected again after the stream.
- **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.

See [Capture while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#capture-while-streaming).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the values of `control/publish/output/stream/active` and `control/capture/ready`.

### Problem: The image stream delivers no images, or fewer than expected {#ts-stream-missing-images}

**Symptoms**

Your program receives no images on `control/publish/output/stream/frame`, or fewer than expected. A dropped image shows as a gap in the frame numbers (`sequence`).

**Possible causes**

- 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.

**Diagnostic procedure**

1. Read `control/publish/output/stream/active` - expected: `true`.
2. Compare the counters under `/hdvisionsystems/lumiscan-cam-driver/<module>/control/publish/output/stream/statistics`: `frames`, `lost-frames`, `incomplete-frames` and `published-frames` - expected: `frames` grows with each trigger, `lost-frames` and `incomplete-frames` stay at `0`, and `published-frames` matches `frames`.
3. Compare the `sequence` numbers your program receives - expected: no gaps.

**Resolution**

- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#triggering).
- **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](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#trigger-overlap).
- **If `lost-frames` or `incomplete-frames` grow:** check the network as described in [Problem: 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).
- **If your program receives fewer images than `published-frames`:** make sure your subscriber handles each image quickly.

See also [A stream delivers nothing](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/troubleshooting.html#stream-nothing).

**If the problem persists**

Send the information listed under [Information for support](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/how-tos/troubleshooting_cam_driver.html#support-information) to support, together with the values of the counters under `control/publish/output/stream/statistics` and how the camera is triggered.

## Information for support {#support-information}

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

- The version of LumiScan Cam Driver.
- 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 the Cam Driver.
- The date and time when the error occurred.
- The Data Layer status of the affected module: `control/status/code`, `control/status/text`, `device-info/is-connected`, and the result that an `execute` call answered.
- The camera: manufacturer, model and serial number (`system/found-camera-serials`).
- The configuration: `lumiscan-cam-driver.json`, the camera configuration files and feature files, or the content of `hdvisionsystems/lumiscan-cam-driver/system/settings`, which shows every password as `"*"`.

# FAQ – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/faq.html

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)

# v2.3.0 - not yet released – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-3-0.html

**Added:**

- **Image stream (experimental).** A camera can now stream its images instead of taking one image per capture request. `<camera name>/control/publish/execute` applies the inputs `control/publish/input/enable` and `keep-latest-output`. While the stream runs, the Cam Driver publishes every image the camera delivers on `control/publish/output/stream/frame` for a subscriber, together with its size, its pixel format and its lineage: the camera, the stream’s start and the image’s number in it. The Cam Driver does not trigger the camera by itself: an image comes on a hardware trigger, on `control/trigger/execute`, or continuously while the camera’s trigger mode is off. Triggered at a fixed rate, the camera we tested delivered every image at up to 66 images per second, against about 34 with `capture/execute`, with its `TriggerOverlap` set to `PreviousFrame` in a feature file. `keep-latest-output` also puts each image on `output/image` and counts it on `output/package-identifier`, at the cost of a copy per image. Counters under `control/publish/output/stream/statistics` show images and losses.

  Every image is delivered on either Data Layer. `setting/settings-hash` identifies the settings the images are taken with, and each frame carries it. Each frame also carries the module’s tag - the camera name, or the one `control/publish/input/tag` gives, which is saved in the module configuration file as `stream.tag` - and the applications that process the images keep it in their results' lineage. The hash says that the settings changed, not what changed; and that it follows a camera feature change has not yet been verified with a real camera.

  While the stream runs, `capture` is not available: `capture/ready` is `false`, `capture/execute` answers `DL_INVALID_OPERATION_MODE`, and a capture request ends with status `-3` without latching a fault. Stopping the stream connects the camera again, so `capture/ready` returns after about two seconds on the camera we tested. See [Streaming Images (Experimental)](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html).

- **Software trigger.** `<camera name>/control/trigger/execute` sends the camera a software trigger while it is in software trigger mode - its trigger mode on and its trigger source software, read in the camera’s own spelling - and does nothing in any other mode. The command is the camera’s own, `TriggerSoftware` or `SoftwareTrigger`. A camera in that mode without either, or refusing it, reports the new status `-10012` (`softwareTriggerFailed`). While the image stream runs, a camera without a software trigger mode - a simulated camera, or a plugin camera without `TriggerSoftware` - is fired by its own trigger instead, one image per call. See [Software Trigger](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#software-trigger).

- **Feature mappings.** A camera that names its software trigger command, its trigger mode or source, or their values differently gets its own names in the application settings file: an entry under `featureMappings`, named by the camera’s `featureMappingId`. The schema lists the keys. A mapped name the camera does not have is logged as a warning, and the built-in names are used. See [Software Trigger](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#software-trigger).

- **An example of the settings, on a PC.** `-g, --generate-settings [folder]` writes the application settings file, an example module file and their schemas into a folder (the current one by default), names the folder the Cam Driver reads its settings from, and ends. Existing files are never overwritten. See [Creating New Camera Settings Files](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/creating-new-camera-settings-files.html).

- **Settings on the Data Layer.** `hdvisionsystems/lumiscan-cam-driver/system/settings` shows the settings the application was started with: the application’s settings file, each module file inlined in its `modules` list, passwords as `***`. Writing it changes the files. The application checks the change as at start, saves it (the previous file as `.bak`), and then refuses all work until it is restarted: `restart-required`, status `-5`. `hdvisionsystems/lumiscan-cam-driver/system/control/restart/execute` restarts it. See [Settings on the Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/settings-on-the-data-layer.html).

**Bugfix:**

- **The Cam Driver started on a ctrlX CORE again.** Since it moved to the new command line, it refused the `-p 8080` its snap passes and ended at once. It accepts and ignores `-p` now, and the snap no longer passes it.
- **A program that keeps calling a refused `execute` no longer floods the log.** Each refusal was written as its own line, so a program retrying `capture/execute` while the camera was busy wrote about 11 MB of log per minute. For each method and result, the first refusal is logged, then at most one line every ten seconds, which says how many were not logged one by one.

# v2.2.0 - 2026.08.05 – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-2-0-2026-08-05.html

**Added:**

- **All cameras can now share one image folder.** A new system setting **unifiedStorage** decides where images are kept. With the default `false`, each camera stores and loads its images in its own folder named after the camera, as introduced in v2.0.0. Set it to `true` and all cameras use the storage folder directly, which is the flat layout used before v2.0.0. The setting applies both to saved images and to the images that simulation mode loads.

**Changed:**

- **A refused `execute` now says whether waiting will help.** Writing to `<camera name>/control/<operation>/execute` while the operation’s `ready` signal is `false` now answers `DL_INVALID_OPERATION_MODE`; `DL_TOO_MANY_OPERATIONS` is left to mean what it says, that the camera is busy with another operation and the same command will work in a moment. The two used to be reported alike, so a program that retries on "busy" could retry forever after, for example, capturing without being connected, saving before anything had been captured, or capturing again after a capture fault that only a `reset` clears. See [When is an operation ready](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#when-is-an-operation-ready).
- **The application now proves that it may run by actually taking its licenses.** Previously it asked the licensing service how many licenses existed on the device. That number also counts licenses another application had already taken, so the cam driver could start on a license that was not really free and then fail. It now takes the licenses it needs at startup, and refuses to start if it cannot get them, naming the license and how many were needed.
- **Licenses are renewed every 30 minutes.** If a license expires, is withdrawn, or the licensing service stops granting it, the application writes a warning naming the license and shuts down instead of continuing without a valid license. Previously a license lost while the application was running went unnoticed.

**Bugfix:**

- **Licenses that were installed separately are now all found.** The application used to look only at the first Cam Driver V2 entry that ctrlX OS reported. A device whose licenses had been installed one after another therefore appeared to have a single license, and a cam driver configured for several cameras refused to start, reporting that there were not enough licenses.
  > [!NOTE]
  > This affects **v2.1.0 and earlier**. On those versions, please install all licenses together, so that the **Licenses** page of ctrlX OS shows **one** Cam Driver V2 entry covering all cameras instead of one entry per license. If the problem occurs, the application reports the status `missingLicense` (code -4) with the text "No valid license found, please purchase one. If you do have one, please try to restart ctrlX", and stops. See [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html).
- **Shutting down is faster.** Returning each license took about five seconds, so a cam driver holding three licenses took roughly fifteen seconds longer to stop than it needed to.

# v2.1.0 - 2026.07.17 – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-1-0-2026-07-17.html

**Added:**

- **A simpler way to trigger a camera.** Every camera operation (capture, save, load, remove, list-images) can now be started with a single command under `<camera id>/control/<operation>/execute`. The command runs the operation and only returns once it has finished, so there is no need to watch for a "ready" signal and then send a "request". The results appear exactly where they did before, and the outcome is reported on `status/code` and `status/text`. The familiar ready/request handshake keeps working, so existing programs do not have to change.
  > [!NOTE]
  > Connect, disconnect and reset are deliberately not offered this way. They can take several seconds, and a waiting command would usually give up before the camera reports success. Please continue to use the ready/request handshake for those three.
  > [!NOTE]
  > If the camera is already busy with another operation, the command is rejected with `DL_TOO_MANY_OPERATIONS` instead of queuing up.

- **A viewable preview image.** Switch `<camera id>/input/preview/enable` on and every successful capture or load also publishes a ready-to-view PNG picture on `<camera id>/output/preview/encoded-data`. This is useful for checking what the camera actually sees, because the normal image output is raw sensor data that most viewers cannot display. The format is named on `<camera id>/output/preview/encoded-format` and is currently always PNG.

  The preview can be made smaller with `<camera id>/input/preview/scale` (a value between 0.0 and 1.0, 1.0 means full size). A smaller preview costs less time per cycle, at the price of less detail. Values outside the allowed range are treated as full size.

  The preview is switched off by default, and while it is off it costs no time at all. Creating a preview also never causes a capture to fail: if it cannot be produced, a warning is written to the log and the previous preview stays in place. You can tell whether a preview belongs to the latest picture by comparing `output/package-identifier`.

**Changed:**

- **Reset now proves that the camera really works.** Previously, reset only disconnected the camera. Disconnecting always succeeds — even for a camera that has been physically unplugged — so reset could report success for a camera that was in fact dead, and operators reasonably concluded it was ready to use. Reset now disconnects, connects again to prove the camera is reachable, then disconnects once more and hands back a **disconnected** camera. As before, please call `control/connect-camera` yourself afterwards. If the camera cannot be reached, reset reports `failedToConnectToCamera` and names the camera in `status/text`, and keeps reporting the problem until a reset actually succeeds. Because reset now performs a full connection test, it takes correspondingly longer than before.

**Bugfix:**

- **A camera that was unplugged and plugged back in can now be recovered without restarting the application.** Previously, the driver kept using the old connection to a camera that had left the network, and every attempt to reconnect failed until the application was restarted. Reset now searches for the camera again and retries once, which brings a re-plugged camera back. The search only happens after a connection attempt has already failed, so resetting a healthy camera does not disturb the other cameras.
- **Wrong image size for 12-bit images.** For the 12-bit formats (mono12, bayer_rg12, rgb12, bgr12), `output/image/data` claimed twice as many bytes as the picture really contains, and the extra bytes were unrelated memory contents. 8-bit formats were not affected.
- **Crash on connect in simulation mode.**
- **Simulated images from different cameras could be mixed up.** Saving the current image and loading a simulation image now use a sub-folder named after the camera, so each camera keeps its own images.

# v2.0.0 - 2026.06.02 – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v2-0-0-2026-06-02.html

**Breaking Changes:**

- A new license key is required: `SWL-W-XCx-CAMDRIVERxHDVSx-V2NN`. Version 1 keys do not work with this release.
- Simulation folder changed: Simulation will load images from `images/<camera id>` instead of `images`. If you use simulation mode, please move your existing images into the folder named after the camera before updating.

**Added:**

- **Several cameras at once.** One installation can now operate more than one camera. Please note that each connected camera needs its own license.
- **More accurate image timestamps.** The timestamp used for images now defaults to the time reported by the camera itself, which is closer to the moment the picture was actually taken. The ctrlX system clock is still available if you prefer the old behavior (see **timestampSource** in table 7).
- **Set camera IP addresses from the control system.** You no longer need a separate tool to give a camera the right network address.
- **See camera network details without a restart.** The IP and MAC addresses of the cameras found on the network are now shown directly, so checking them no longer means restarting the cam-driver.
- **Always get the newest picture.** A new camera setting, **clearBufferBeforeCapture**, discards older images still waiting in the queue so that a capture always returns a fresh one.

**Improved:**

- In simulation mode, on connection, it will scan storage folder for images. Users **don‘t need to call list-images** anymore.
- The example settings now include a sample image and use the internal storage by default, so a first test works without any preparation.
- Additional log messages make it easier to check how fast the cam-driver is running.

**Bugfix:**

- The application could take a long time to restart, because a connection was left open after it was shut down. Restarts are quick again.
- The **inter-package-delay-us** setting could still be changed after the camera was connected, where it had no effect. It is now locked once the camera is in use.

**Experimental (Use with caution):**

- User can now set GenICamFeature(Device) in datalayer under `lumiscan-cam-driver/<camera id>/features.`

> [!NOTE]
> Currently feature is not cached. If user (i.e. PLC) keep setting feature value might lead to camera instability and performance penalty.

# v1.2.0 - 2025.07.01 – LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/release-notes/v1-2-0-2025-07-01.html

**Added:**

- Support internal storage, SD Card, USB storage.
- Users can remove saved data now.
- Full control on GenICam feature. Additional parameter `initialFeatureFile` in camera.

**Improve:**

- After installation, it will update settings schema in configuration dir.
- Support Xenics Camera, remove requirement on some unnecessary GenICam features. ps. for now Our App **still expect**: **Width, Height, PixelFormat** and **DeviceSerialNumbe.**

**Bugfix:**

- High CPU usage when shutting down program if no license detected, which paralyzes CtrlX Core.

# LumiScan Cam Driver

URL: https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/index.html

|   |   |   |
| --- | --- | --- |
| ![Two GenICam cameras connected to a ctrlX CORE](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/intro/step-1.svg)<br><br>**Connect your GenICam cameras.** GigE Vision cameras on ctrlX CORE or a PC. | ![Camera image published as the node camera1/output/image](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/_images/intro/step-2.svg)<br><br>**Each image lands on the Data Layer.** Every other LumiScan app reads it from there. | Example: camera1/output/image<br><br><br><br><br><br><br>width<br>2448<br><br><br>height<br>2048<br><br><br>pixel-type<br>RGB8<br><br><br>is-connected<br>TRUE<br><br>**Capture on command.** Exposure, pixel format and trigger set per camera. |

LumiScan Cam Driver connects Ethernet cameras that follow the GenICam standard and makes their images and camera functions available on the Data Layer. It finds and connects the cameras, captures images and sets exposure time, pixel format and other GenICam features. All other LumiScan apps take their images from it, on ctrlX OS or on a PC with Windows 11 or Ubuntu 24.04.

For licensing, see [Licence](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/requirements.html#licence). Questions or an error message? See the [FAQ](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/faq.html).
