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

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:

    Result Meaning What to do

    DL_TOO_MANY_OPERATIONS

    The camera is busy with another operation right now.

    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.

    Nothing. Retrying does not help.

  • Whether the operation succeeded is reported on <camera name>/control/status/code and <camera name>/control/status/text, exactly as with the handshake. A successful write therefore only means the operation ran — always check the status code afterwards. 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

capture

The camera is connected and no capture fault is latched. 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.

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.