Integrating LumiScan into Your Application

You end with your own program capturing an image with the Cam Driver and reading a Template Finder result. Seven steps; each one ends with Done when and points to the next.

The examples assume the apps are installed and a camera is configured - steps 1 to 4 of Your First Industrial Vision Application. The LumiScan apps have no SDK of their own: every function is a node of the Data Layer, so any client that can read, write and call Data Layer or OPC UA nodes can use them.

Your progress - tick off each step as you finish it

Step 1 of 7 - Choose the interface

1 Interface · 2 Nodes · 3 Connect · 4 Call · 5 Handshake · 6 Results · 7 Errors

Your program runs Interface Notes

on the ctrlX device (an app of its own)

ctrlX Data Layer client

as any ctrlX app does, for example one built with the ctrlX AUTOMATION SDK

on a PC or another machine in the network

OPC UA, through the LumiScan OPC UA Connector

any OPC UA client library, any language; the apps run on a PC with LumiScan Keryx

in a script or a test

krxclient, the command line client of LumiScan Keryx

read, write, execute, subscribe, handshake, browse

The node addresses and call patterns are the same on ctrlX OS and on a PC, so the logic you write does not depend on the platform. See ctrlX Data Layer and LumiScan Keryx.

Done when: you know which client your program uses.
Next: Step 2 - Find the nodes

Step 2 of 7 - Find the nodes

1 Interface ✓ · 2 Nodes · 3 Connect · 4 Call · 5 Handshake · 6 Results · 7 Errors

Every address has the same shape:

hdvisionsystems/<app>/<module>/<folder>/...   the nodes of one module (a camera, a finder module, ...)
hdvisionsystems/<app>/system/...              what concerns the whole app
types/hdvisionsystems/<app>/<type>            the FlatBuffers types the app publishes

<folder> is control/ (the functions and the module status), input/, output/ or setting/. An execute method keeps its own inputs and outputs under its function, for example hdvisionsystems/lumiscan-template-finder/module-1/find-template/input/…​ and …​/output/result.

The nodes of an app are listed in the Data Layer Reference of its manual; look at the live tree in the Data Layer view of the ctrlX OS web interface or, on a PC, on http://127.0.0.1:7555/. See Addresses and Modules.

Done when: you have found hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute and hdvisionsystems/lumiscan-template-finder/module-1/find-template/execute in the tree.
Next: Step 3 - Connect

Step 3 of 7 - Connect

1 Interface ✓ · 2 Nodes ✓ · 3 Connect · 4 Call · 5 Handshake · 6 Results · 7 Errors

  • OPC UA: start the OPC UA Connector after the apps. Endpoint opc.tcp://<pc>:4840, security policy None, anonymous. Look up the namespace index of urn:hdvisionsystems:keryx in the server’s NamespaceArray - never hard-code it. A node’s NodeId is its Data Layer address: ns=<n>;s=hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code.

  • krxclient: it connects to the broker on tcp://127.0.0.1:5555; set another one with --keryx-url or HDV_KERYX_URL.

  • ctrlX Data Layer client: connect to the Data Layer of the device as your SDK describes.

The OPC UA Connector has no authentication or encryption. Run it on a network you trust and open TCP 4840 in the firewall for your client’s address only. See Security.

Done when: your program reads hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code.
Next: Step 4 - Call a function

Step 4 of 7 - Call a function

1 Interface ✓ · 2 Nodes ✓ · 3 Connect ✓ · 4 Call · 5 Handshake · 6 Results · 7 Errors

Operations that finish within about 1 s are execute methods: write the inputs (separate nodes), then call execute; the call returns when the operation is done.

krxclient execute hdvisionsystems/lumiscan-cam-driver/camera1/control/capture/execute
krxclient read    hdvisionsystems/lumiscan-cam-driver/camera1/control/status/code
krxclient write   hdvisionsystems/lumiscan-template-finder/module-1/find-template/input/template-name screw
krxclient execute hdvisionsystems/lumiscan-template-finder/module-1/find-template/execute
krxclient read    hdvisionsystems/lumiscan-template-finder/module-1/find-template/output/status-code

With OPC UA, call the method with the Call service: objectId is the parent address (…​/camera1/control/capture), methodId the execute node. Set the client’s call timeout above your slowest method; the connector waits up to 60 s.

Check both outcomes: the result of the call says whether the operation could run at all, the status node whether it succeeded. See Execute Methods.

Done when: your program captures an image and runs a search.
Next: Step 5 - Run a long operation as a handshake

Step 5 of 7 - Run a long operation as a handshake

1 Interface ✓ · 2 Nodes ✓ · 3 Connect ✓ · 4 Call ✓ · 5 Handshake · 6 Results · 7 Errors

Operations that can take longer - connecting a camera, a reset, an inference - are handshakes, so that nothing blocks: wait for ready = true, set request = true, wait for ready = false, set request back to false, then check the status and the outputs. Poll at 50 to 100 ms.

In a script, krxclient handshake runs this sequence for you, see krxclient.

Which pattern a function uses is in the app’s Data Layer Reference; the rules are in Choosing a Pattern and Handshake.

Done when: your program connects the camera itself (hdvisionsystems/lumiscan-cam-driver/camera1/device-info/is-connected = true).
Next: Step 6 - Read results and receive every image

Step 6 of 7 - Read results and receive every image

1 Interface ✓ · 2 Nodes ✓ · 3 Connect ✓ · 4 Call ✓ · 5 Handshake ✓ · 6 Results · 7 Errors

  • Plain values - numbers, booleans, strings, arrays - are read directly. Build your logic on them.

  • Structured results and images are FlatBuffers; their schemas are on the Data Layer under types/hdvisionsystems/<app>/…​. Decode them with the FlatBuffers library of your language.

  • Every image, without a call per image: let the processing app subscribe to the camera’s stream and subscribe your program to the app’s result node (OPC UA: a subscription on that node):

    krxclient write     hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/input/address hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream
krxclient write     hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/input/enable true
krxclient execute   hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/execute
krxclient subscribe hdvisionsystems/lumiscan-template-finder/module-1/control/subscribe/output/stream/result --count 5

Image streams are experimental in the current releases. See Streams and Addresses and Modules.

Done when: your program reads the Template Finder result for an image.
Next: Step 7 - Handle errors

Step 7 of 7 - Handle errors

1 Interface ✓ · 2 Nodes ✓ · 3 Connect ✓ · 4 Call ✓ · 5 Handshake ✓ · 6 Results ✓ · 7 Errors

  • A refused call (Rejected on LumiScan Keryx, DL_INVALID_VALUE on the ctrlX Data Layer, an OPC UA status code through the connector) means the operation did not run - nothing was queued.

  • A call that ran can still fail: read the module’s control/status/code, or the finder’s <method>/output/status-code, after every call.

  • A module runs one operation at a time: a call while another one runs is refused as busy (TooManyOperations, ctrlX DL_TOO_MANY_OPERATIONS). Retry it once the running operation has finished.

The codes and their meaning: Status Codes and Results; when something does not work: Troubleshooting.

Done when: your program reacts to a refused call and to a failed operation - it is integrated.

What next

  • All nodes of an app: the Data Layer Reference in its manual, linked from the overview page.

  • Everything about the interface: LumiScan Keryx.