How To: Connect a GenICam Camera to ctrlX CORE

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

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

  • The configuration tool of the camera manufacturer, to set the camera’s IP address

How it fits together

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 and General Concept of Handshake.

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

  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.

  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.

  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
    Figure 1. Network interface of the ctrlX CORE with static IP address and MTU

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.

Step 2 - Configure LumiScan Cam Driver

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

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

  4. Open lumiscan-cam-driver.json and enter the module file in the modules list:

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

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.

Step 3 - Check that the camera is found

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

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
Figure 5. Connect-camera nodes and the connection state

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

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

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)

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:

"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 and Saving Image Files.

lumiscan-cam-driver.json with the storage section highlighted
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

  • 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

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

  • Problems with detection, connection or capture: see Troubleshooting.