Initializing the Camera

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.

Table 1. Table 2: Functionality Addresses
Functionality Permission Address

Capture

Read-Only

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

Writable

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

Write-Only (method)

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

Save

Read-Only

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/save/ready

Writable

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/save/request

Write-Only (method)

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

Load

Read-Only

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/load/ready

Writable

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/load/request

Write-Only (method)

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

Remove

Read-Only

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/remove/ready

Writable

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/remove/request

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

Writable

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/list-images/request

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

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

Writable

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/disconnect-camera/request

Reset

Read-Only

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/reset/ready

Writable

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/reset/request

Status

Read-Only

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/code

Read-Only

hdvisionsystems/lumiscan-cam-driver/<camera name>/control/status/text

Set Camera IP

Read-Only

hdvisionsystems/lumiscan-cam-driver/system/force-ip/ready

Writable

hdvisionsystems/lumiscan-cam-driver/system/force-ip/request
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.

Connection Steps

  1. Start, connected to camera:

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

    2. Check XXX/connect-camera/ready = True

      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.

        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.

        If is false, prerequest is not met or no camera is found.
        Check whether camera ip is in the same local network as ctrlX.
        If XXX/capture/ready = False:

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

      • Check status code for more information.

        If XXX/capture/ready = True:

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

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

        3. Contact HD Vision Systems.

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

    4. Check XXX/connect-camera/ready = False

      If the CamDriver application hasn‘t seen that the variable has changed:

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

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

      3. Contact hdvisionsystems.

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

    6. Check XXX/status/code (Camera) = 0 (ready)\* ----→ Camera is initialized, and ready to capture image

  2. Capture image

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

    2. Check XXX/capture/ready = True

    3. Set XXX/capture/request = True

    4. Check XXX/capture/ready = False

      \* The meaning of all status code values is explained in the Status Code Values table.

    5. Set XXX/capture/request = False

    6. Check XXX/status/code (Camera) = 0 ---→ Capture image is successful

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

  3. Disconnect Camera

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

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

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

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

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

    6. Check XXX/status/code (Camera) = 0 ---→ Camera is disconnected

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

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)

  • using a Samba server (Windows shared folder) (from LumiScan CamDriver 1.0.1 onwards)

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:

  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

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

  1. You can configure the camdriver app to use this path as described in the Section Application Settings Content Example

To configure an external Samba storage folder:

  1. Select the folder you want to share.

  2. Right-click it.

  3. Select Properties.

  1. In the dialog box select For data exchange and confirm by clicking on mount

  2. The path for your storage device is shown in the right-hand column (e.g. /media/sdb1). Note down that path.

path
mountDataExchange

  1. Select the Sharing tab.

  2. Go to Advanced Sharing.

    ex storage 3
    ex storage 1

  3. Create a Windows or Samba user account with a password.

    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.

  4. Click Apply.

  5. Click OK.

  6. Close Advanced Sharing window.

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

    To create an account:

    1. Click Permissions

    2. Add user

    3. Configure permissions for this specific user.

      ex storage 4
      ex storage 5
      After creating an external shared storage, you must make the appropriate changes to the lumiscan-cam-driver.json settings. See Section Storage settings for more information on how to do this.
      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.

  8. Restart the program.

  9. Call Connect Camera.

  10. Call Capture.

  11. Call Save.

Loading Images

To load image files, follow these steps:

  1. Set up storage: Complete steps 1–10 in the Section 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.

For additional information on simulation mode, refer to Camera Example File Content Example, which explains the id field.

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 to acknowledge the start of the function).

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

-4

"missingLicense"

Make sure you have the correct license installed. See Requirements.

-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. * Check the MTU size setup in the ctrlX web page settings. It should be set to 8000 or 9000.\*
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).

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

MTU Size Change

\* For information on how to change the MTU size, see next section 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
    s11
    s3ninterf
    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

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

  1. Expand Advanced Settings.

    s4nix12
    s5

  2. Enter the value you want to use in the MTU window (check status code -10004 in Status Code Values).

  3. Click Save to confirm.

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

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

GenICam features

To edit GenICam features:

  1. Ensure that the camera you wish to configure is connected as described in Connection Steps.

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

s6
s7

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

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

  1. Access ctrlX X3, settings/NetworkInterfaces/XF10

    1. Set General/MTU to 8000

    2. IPv4/DHCP disable

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

    4. Click save