---
title: "Execute a Method"
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/lumiscan-camdriver/execute-a-method.html"
---

# Execute a Method – LumiScan Cam Driver

Every camera operation lives under the same address: `hdvisionsystems/lumiscan-cam-driver/<camera name>/control/<operation>/`.

Most operations can be started in **two different ways**, and both lead to the same result:

- Write to the **`execute`** method node. This runs the operation once and only returns when it has finished. It is a single write, so no state has to be tracked in your program.
- Use the **ready/request handshake**. This starts the operation and returns immediately, leaving your program to watch the `ready` signal to learn when the operation has finished. See [General Concept of Handshake](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/general-concept-of-handshake.html).

The handshake works for every operation except `trigger`. The `execute` method is available for most, but not all of them.

**Table 1. Ways to start each operation**

| Operation | `execute` | ready/request |
| --- | --- | --- |
| `capture` | Yes | Yes |
| `save` | Yes | Yes |
| `load` | Yes | Yes |
| `remove` | Yes | Yes |
| `list-images` | Yes | Yes |
| `connect-camera` | No | Yes |
| `disconnect-camera` | No | Yes |
| `reset` | No | Yes |
| `trigger` | Yes | No |

> [!NOTE]
> Connect, disconnect and reset are deliberately not offered as `execute` methods. They can take several seconds, because they set up or tear down the full connection to the camera, and `reset` disconnects and connects again. A waiting method call would usually give up before the camera reports success, and would then report a failure for an operation that actually worked. Please use the ready/request handshake for those three.

## Software Trigger {#software-trigger}

`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/trigger/execute` sends the camera a software trigger, but only while the camera is in software trigger mode. In any other mode, such as a hardware trigger or free run, it does nothing and still answers `DL_OK`. The camera must be connected; until it is, the call answers `DL_INVALID_OPERATION_MODE`. There is no ready/request handshake for it: a trigger is over at once.

It is not a capture. The image goes wherever the camera’s acquisition delivers it: to the image stream while that runs. Outside a stream, the image waits in the camera’s queue (**number-of-images-in-queue**), and the next capture takes it unless the module file sets `clearBufferBeforeCapture`.

While the image stream runs, a camera without a software trigger mode - a simulated camera playing a folder of images, or a plugin camera without `TriggerSoftware` - is fired by its own trigger instead: each call gives one image on `control/publish/output/stream/frame`. See [Triggering the camera](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#triggering).

Software trigger mode means the camera’s trigger mode is on and its trigger source is software. The Cam Driver reads both in the camera’s own spelling, the same way it sets them when it connects: for example `On` or `Triggered`, and `Software` or `SoftwareTrigger`. GenICam’s `On` and `Software` apply for a camera that cannot list its values.

The command that fires the trigger is the camera’s own: GenICam’s `TriggerSoftware`, or `SoftwareTrigger` on a camera that names it so. When the camera is in software trigger mode but has neither command, or refuses it, the status becomes `-10012` (`softwareTriggerFailed`).

A camera that names its command, its trigger mode or source, or their values differently is given its own names in the application settings file. Add a feature mapping under `featureMappings`, and name it by the camera’s `featureMappingId`:

```json
"cameras": [
    { "cameraId": "camera1", "serial": "200900623", "driverId": "default", "featureMappingId": "acme" }
],
"featureMappings": [
    {
        "id": "acme",
        "features": { "TriggerSoftware": "FireTrigger" },
        "values": { "TriggerSource_Software": "SW" }
    }
]
```

Under `features`, the key is the common feature (`TriggerSoftware`, `TriggerMode`, `TriggerSource`, …), and the value is the camera’s name for it. Under `values`, the key is the common value (`TriggerSource_Software`, `TriggerMode_On`, …), and the value is the camera’s entry for it. The schema lists the keys. A mapped name is tried first. When the camera does not have it, the Cam Driver logs a warning and uses its built-in names. A `featureMappingId` that names no mapping stops the Cam Driver at start, with an error that names it. An unknown key makes the settings file unreadable: the Cam Driver logs an error that names the key and the valid ones, and runs without cameras.

## Calling execute {#calling-execute}

To run an operation, write to its `execute` node, for example:

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

The write returns once the operation has finished. Two results have to be kept apart:

- **Whether the operation could be started at all** is reported by the write itself. A rejected write is never queued, and the result says why. The table uses the names of the ctrlX Data Layer; LumiScan Keryx on a PC reports the same results as `TooManyOperations`, `InvalidOperationMode` and `ResourceUnavailable`, see [Results of a method call](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/status-codes.html#method-results):

  | Result | Meaning | What to do |
  | --- | --- | --- |
  | `DL_TOO_MANY_OPERATIONS` | The camera is busy with another operation right now, or the image stream is starting or stopping. | Retry. The same write succeeds once the running operation finishes. |
  | `DL_INVALID_OPERATION_MODE` | The operation’s `ready` signal is `false`, so the camera is in a state where this operation cannot run — for example `capture` while the camera is not connected. | Do not retry blindly; it will keep failing. Bring the camera into the required state first, see [When is an operation ready](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/execute-a-method.html#when-is-an-operation-ready). |
  | `DL_RESOURCE_UNAVAILABLE` | The application is shutting down, or the settings were changed on the Data Layer and a restart is required (`status/code` `-5`). | Shutting down: nothing, retrying does not help. Restart required: restart the application, 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#restart-required). |

- **Whether the operation succeeded** is reported on `<camera name>/control/status/code` and `<camera name>/control/status/text`. A successful write therefore only means the operation ran — always check the status code afterwards. Unlike the handshake, `capture/execute` leaves a failed capture’s own code there; through the handshake, a failed capture ends at `3`. The meaning of each value is listed in [Status Code Values](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/initializing-the-camera.html#status-code-values).

Results appear on the same output nodes in both cases, so a captured image can be read from `<camera name>/output/image` whichever way the capture was started.

## When is an operation ready {#when-is-an-operation-ready}

`execute` checks the very same `<operation>/ready` signal the handshake uses, and refuses to run while it is `false`. The signal is not a formality — most operations depend on something that has to happen first:

| Operation | `ready` is true when |
| --- | --- |
| `capture` | The camera is connected, no capture fault is latched, **and** the image stream is not running. A failed capture (for example a timeout) latches the fault and keeps `capture/ready` false until a `reset` succeeds — so a camera that captured once and then failed will keep refusing every later `capture/execute`. The image stream holds `capture/ready` false only while it runs and while the camera reconnects after it (about two seconds on the camera we tested); see [Capture while the stream runs](https://docs.hdvisionsystems.com/en/lumiscan-cam-driver/2.2.1/lumiscan-camdriver/streaming-images.html#capture-while-streaming). |
| `save` | An image is available, that is after a successful `capture` or `load`. It is false right after the application starts. |
| `load`, `remove` | `<camera name>/output/image-files` is not empty. Run `list-images` first, or save an image. |
| `list-images` | Always. |

Since `connect-camera` and `reset` are only available through the handshake, a program that uses `execute` exclusively can never reach the state `capture` needs. Connect (and recover from a latched fault) through the handshake, then use `execute` for the day-to-day operations.

> [!TIP]
> When an `execute` is refused, read `<operation>/ready` together with `<camera name>/control/status/code` and `.../status/text`. `ready == false` names the missing precondition, and the status text still carries the message from the fault that caused it.

## Choosing which way to use {#choosing-between-the-two}

Use **`execute`** when your program can wait for the operation to finish. It is the simpler option: one write, and the operation is done when the write returns.

Use the **ready/request handshake** when:

- the operation is `connect-camera`, `disconnect-camera` or `reset`, which offer no `execute` method,
- your program must not block while the camera is working, or
- you already have a working program built on the handshake. The handshake is unchanged and keeps working, so there is no need to rewrite it.