OPC UA Client Integration Guide

This document describes how to connect to and operate the LumiScan VGR OPC UA server. Because OPC UA is self-describing, clients can browse the available nodes and methods directly. This guide covers the configuration settings and call patterns clients must follow to integrate reliably.

Client Configuration & Execution Behavior

Due to physical hardware operations (camera triggers, robot communication) and heavy computational tasks (neural network inference), clients must respect the following execution constraints:

  • Execution Time & Call Timeouts: Many methods take significantly longer than standard PLC operations.

    • Typical execution time: 3 to 10 seconds.

    • Recommended client call timeout: At least 15 seconds.

    • Failure to configure this timeout will result in client-side errors such as BadTimeout or transport disconnects.

  • Concurrency: The server processes one method at a time. Parallel or concurrent method calls are not supported and will be rejected with BadResourceUnavailable.

Connection Profile

Property Value

Endpoint

opc.tcp://<host>:4840

Security Policy / Mode

None (anonymous, unauthenticated)

Authentication

None (Anonymous login)

Max. simultaneous clients

2 (additional connection attempts will be refused)

Recommended Session Timeout

10s (adjust up or down based on your polling interval)

Note: The server currently requires no authentication. Ensure it is accessible only within your plant network perimeter.

Address Space Layout

All nodes are hosted under Objects/LumiScanVGR (namespace index 1).

Manufacturer

Child object: LumiScanVGR/Manufacturer

Variable Type Access Description

Name

String

Read

Manufacturer name.

Address

String

Read

Manufacturer address.

Version

Child object: LumiScanVGR/Version

Variable Type Access Description

Version

String

Read

Version string of the running software build.

GitRevision

String

Read

Commit hash of the running build.

BuildTime

String

Read

Build timestamp of the running build.

Capability Catalogs

These arrays are populated at server startup from the project configuration. If hardware IDs are added or changed, the server must be restarted to reflect them.

Variable Type Access Description

PossibleCameras

String[]

Read

All configured camera IDs.

PossiblePipelines

String[]

Read

All configured pipeline IDs.

PossibleRobots

String[]

Read

All configured robot IDs.

Live Configuration

These nodes are updated on every read and reflect the current active selections.

Variable Type Access Description

ActiveCamera

String

Read

Currently active camera.

ActivePipeline

String

Read

Currently active pipeline/recipe.

ActiveRobot

String

Read

Currently active robot definition.

Method Reference

All methods return their status as the first output argument ReturnCode (type String). See Return Codes for all possible values.

Method Input Arguments Output Arguments Description

ExecuteSimpleRecipe

CameraId (String), PipelineId (String), RobotId (String)

ReturnCode

Convenience method. Runs the full capture-and-grip sequence using the IDs supplied by the client. Passing an empty string reuses the last known ID for that parameter — explicitly providing all IDs is strongly recommended.

ExecuteRecipe

RecipeId (String)

ReturnCode

Convenience method. Runs the full capture-and-grip sequence using a pre-configured server-side recipe identified by RecipeId. Recipe IDs and their associated camera/pipeline/robot combinations are defined in the LumiScan VGR project configuration. Empty strings are not allowed.

SetOperationMode

Mode (Byte)

ReturnCode

Switches the server between IDLE (0), AUTOMATIC (1), MANUAL (2), and SHUTDOWN (3). All other methods are only accepted in AUTOMATIC mode.

GetOperationMode

—

ReturnCode, Mode (Byte), ModeName (String)

Returns the current operation mode as a numeric value and a human-readable name.

SetActiveCamera

ActiveCamera (String)

ReturnCode

Selects the camera for subsequent operations.

SetActivePipeline

ActivePipeline (String)

ReturnCode

Selects the vision pipeline/recipe for subsequent captures.

SetActiveRobot

ActiveRobot (String)

ReturnCode

Selects the robot definition used to express grip poses.

SetupSystem

—

ReturnCode

Initializes all hardware and software resources. Must be called at least once after the application starts.

ResetCamera

CameraId (String, optional)

ReturnCode

Performs a deep reset of the specified camera. Pass an empty string to reset all cameras.

Shutdown

—

ReturnCode

Placeholder — not yet implemented. Has no effect on the running process.

CaptureImage

—

ReturnCode

Acquires a fresh image from the active camera.

GetCameraTemperature

—

ReturnCode, CameraTemperature (Double)

Returns the current temperature of the active camera in °C. Returns -273.1528 when the value is unavailable — treat this as "unknown".

ComputeObjects

—

ReturnCode, NumObjects2D (Byte), NumObjects3D (Byte)

Runs object detection on the last captured image. Returns the number of detected 2D and 3D objects (capped at 255).

GetBestResult

—

ReturnCode, GripPointPose (Float[7])

Returns the highest-ranked grip pose from the most recent detection. Use for inspection or simulation without consuming the result.

GripBestResult

—

ReturnCode, GripPointPose (Float[7])

Returns the next grip pose in ranked order and advances the internal iterator. Call repeatedly to step through all candidates.

GetReport

ParamId (Byte), ArgByte (Byte), ArgFloat (Float), ArgString (String)

ReturnCode, ValueByte (Byte), ValueInt (Int32), ValueFloat (Float), ValueString (String)

Generic getter for querying object counters and similar values. See Parameter IDs below.

Pose Array Layout

GripPointPose always contains exactly seven Float values:

Index Field Description

0

x

Translation X in robot coordinate system (meters)

1

y

Translation Y in robot coordinate system (meters)

2

z

Translation Z in robot coordinate system (meters)

3

rx

Rotation X (Euler / axis-angle, robot-driver dependent)

4

ry

Rotation Y

5

rz

Rotation Z

6

w

Optional fourth component (quaternion W or unused). Remains 0 when not supplied.

Interpret the pose according to your robot plug-in documentation.

Parameter IDs

Used via GetReport to query detection results.

ParamId ParamId Description Input Field ArgString Result field Description

0

GET_NUM_OBJECTS2D_TOTAL

—

ValueByte

Total number of detected 2D objects.

1

GET_NUM_OBJECTS3D_TOTAL

—

ValueByte

Total number of detected 3D objects.

2

GET_NUM_OBJECTS2D_TYPE

<Object Id>

ValueByte

Number of 2D objects matching the given class.

3

GET_NUM_OBJECTS3D_TYPE

<Object Id>

ValueByte

Number of 3D objects matching the given class.

4

GET_DEPTH_DIFFERENCE

—

ValueFloat

Thickness of gripped object

SetParameter is not supported via OPC UA.

Operation Mode

The server enforces an operation mode that must be set before most methods are usable.

Mode Value (Byte) Description

IDLE

0

Standby. Most methods rejected.

AUTOMATIC

1

Normal production mode. All methods accepted.

MANUAL

2

Local/GUI control active. Most methods rejected.

SHUTDOWN

3

Shutdown in progress.

Only SetOperationMode and GetOperationMode are accepted in any mode. All other methods return OPERATION_MODE_INVALID when the mode is not AUTOMATIC. The server starts in AUTOMATIC by default.

Recommended Call Sequence

Shortcut for standard production: Replace steps 2–6 with a single call:* ExecuteSimpleRecipe(CameraId, PipelineId, RobotId) — client provides IDs directly. + * ExecuteRecipe(RecipeId) — use a pre-configured server-side recipe(settings.json). Use the step-by-step sequence below when you need finer control, e.g. to inspect intermediate counts or repeat only the capture step.

  1. Get/Set Operation Mode — Verify the server is in AUTOMATIC. If it reports IDLE or MANUAL, call SetOperationMode before anything else.

  2. SetupSystem — Initialize hardware and load all resources. Wait for SUCCESS before continuing.

  3. SetActiveCamera / SetActivePipeline / SetActiveRobot — Define the working configuration. Required at least once per production order; skip if the previous selection is still valid.

  4. CaptureImage — Acquire the current scene.

  5. ComputeObjects — Run detection. NumObjects2D and NumObjects3D are available on SUCCESS. Repeat from step 4 if a fresh scene is required.

  6. GetBestResult — Read the highest-ranked grip pose without consuming it (useful for logging or simulation).

  7. GripBestResult — Retrieve the next executable grip pose for the robot. Call repeatedly to step through all candidates.

  8. (Optional) GripBestResult — Required for measuring object’s thickness by calling this function after robot grip the current object away.

  9. (Optional) GetReport(ParamId:4) — It will return object thickness in ValueFloat field

Read ActiveCamera, ActivePipeline, and ActiveRobot at any time to confirm which configuration is currently active.

Return Codes

Every method returns a ReturnCode string as its first output. The table below lists all possible values and their meaning.

ReturnCode Description

SUCCESS

Operation completed without errors.

UNKNOWN_ERROR

Unclassified failure. Check the server-side application log for details.

CAMERA_NOT_INITIALIZED

Camera was not initialized. Call SetupSystem first.

CAMERA_NOT_CONNECTED

Camera hardware is not reachable. Use ResetCamera or check cabling.

CAMERA_ACQUISITION_ERROR

Image acquisition failed (exposure, trigger, or transport problem).

PIPELINE_NOT_INITIALIZED

The selected pipeline is not ready. Verify SetActivePipeline succeeded.

ROBOT_NOT_INITIALIZED

Robot configuration is missing or invalid.

MISSING_DATA

Required data (image, point cloud, etc.) is not available yet.

ID_DOES_NOT_EXIST

The supplied camera/pipeline/robot/recipe ID is not known. Verify against the Possible* arrays.

MISSING_TRANSFORM

The robot-to-world transform could not be determined.

RESULTS_EMPTY

No grip candidates are available. Run ComputeObjects first.

CAMERA_HARDWARE_TRIGGER_AGAIN

Hardware trigger produced no frame. Retry CaptureImage.

CAMERA_BAD_EXPOSURETIME_SETTING

Exposure setting prevented a valid image from being acquired.

CAMERA_RESTART_REQUIRED

Camera driver/firmware requires a restart. Call ResetCamera.

OPERATION_MODE_INVALID

Method was rejected because the server is not in AUTOMATIC mode. Call GetOperationMode to check the current state, then SetOperationMode to switch back.

Troubleshooting

Problems with OPC UA calls are described step by step in Troubleshooting: