---
title: "OPC UA Client Integration Guide"
product: "LumiScan VGR"
component: "lumiscan-vgr-de"
version: "1.8.4"
display_version: "1.8.4.6"
latest_version: true
language: "de"
url: "https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/api/opcua/opc-ua-client-integration-guide.html"
---

# OPC UA Client Integration Guide – LumiScan VGR

> [!NOTE]
> Die API-Referenz ist nur auf Englisch verfügbar, da sie aus den englischen Quellcode-Kommentaren generiert wird. Technische Begriffe (Klassennamen, Methoden, Parameter) bleiben unverändert.

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

Probleme bei OPC-UA-Aufrufen sind Schritt für Schritt unter [Fehlerbehebung](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#opc-ua) beschrieben:

- Aufrufe laufen in ein Timeout, oder `BadResourceUnavailable`: [OPC-UA-Aufrufe schlagen mit `BadTimeout` oder `BadResourceUnavailable` fehl](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#faq-opcua-timeout)
- `OPERATION_MODE_INVALID`: [OPC-UA-Methoden liefern `OPERATION_MODE_INVALID`](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#ts-opcua-operation-mode-invalid)
- `ID_DOES_NOT_EXIST`, oder die Arrays `Possible*` sind veraltet: [Eine Funktion liefert `ID_DOES_NOT_EXIST`](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#ts-id-does-not-exist)
- Objektanzahlen sind nach `ComputeObjects` 0: [Es werden keine Objekte erkannt (Objektanzahl `0`)](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#ts-no-objects-detected)
- `GripBestResult` liefert `RESULTS_EMPTY`: [`RESULTS_EMPTY` wird zurückgegeben](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#faq-results-empty)
- `CameraTemperature` ist `-273.1528`: [`CameraTemperature` ist `-273.1528`](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#ts-opcua-camera-temperature)
- `Shutdown` hat keine Wirkung: [`Shutdown` hat keine Wirkung](https://docs.hdvisionsystems.com/de/lumiscan-vgr-de/1.8.4/troubleshooting.html#ts-opcua-shutdown-no-effect)

---