---
title: "Initializing the Camera"
product: "LumiScan Cam Driver"
component: "lumiscan-cam-driver"
version: "2.2.1"
display_version: "2.2.1.10"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html"
---

# Initializing the Camera – LumiScan Cam Driver

## Data Layer {#data-layer}

LumiScan Cam Driver offers its functions on the Data Layer under `hdvisionsystems/lumiscan-cam-driver`.

On ctrlX OS (ctrlX CORE or ctrlX IPC), LumiScan Cam Driver uses the [ctrlX Data Layer](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/ctrlx-data-layer.html).

On a PC with Windows 11 or Ubuntu 24.04, LumiScan Cam Driver uses [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/keryx.html).

The node addresses, types and call patterns are the same on both. LumiScan Cam Driver offers:

- [ready/request handshakes](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/handshake.html)
- [execute methods](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/execute.html)
- a [stream](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html) that publishes its results (experimental)

How addresses are built, how to call functions, the status codes and the tools are described in [LumiScan Keryx](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/index.html).

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