---
title: "How To: Connect a GenICam Camera to ctrlX CORE"
description: "Step by step from an unpacked GigE Vision camera to a captured image on the ctrlX Data Layer - network, settings files, connection, capture and saving."
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/how-tos/connect-a-genicam-camera.html"
---

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

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