Execute a Method

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.

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

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

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.

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:

"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

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:

Result Meaning What to do

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

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.

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.

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.

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

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

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

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.

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.

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

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.