FAQ

The Cam Driver runs on a ctrlX CORE (ctrlX OS, with the ctrlX Data Layer) or on a PC with Windows 11 or Ubuntu 24.04 (with LumiScan Keryx), and needs an Ethernet-enabled, GenICam-compliant camera, powered via PoE or an external power supply. The node addresses are the same on both platforms. It has been tested with selected cameras from Basler, Baumer, IDS, LUCID Vision Labs, Hikvision and Balluff; GenICam implementations vary, so verify all required functions before deployment. From v2.0.0, one installation can operate several cameras: each camera is a module with its own configuration and Data Layer address (for example hdvisionsystems/lumiscan-cam-driver/camera1), and each connected camera needs its own licence.

Requirements, Description, ctrlX Data Layer and LumiScan Keryx

Use the force-IP function under hdvisionsystems/lumiscan-cam-driver/system/force-ip/. It also works when the camera is not detected normally (for example because its subnet does not match the ctrlX CORE or the PC), as long as it is reachable over the same network connection.

Setup Camera IP Address, Force IP configuration of camera

lumiscan-cam-driver.json holds the application settings and lists the camera configuration files to load; each further file (for example camera_example.json) configures one camera.

Setup Camera Configuration, Creating New Camera Settings Files, Adding and removing modules

inputFileType must be camera-configuration. The camera settings are id (must be unique across all camera settings; it is the module’s name on the Data Layer and may contain only lower-case letters, digits, - and _), serial (a serial containing simulation makes the camera simulated), exposureTimeUS, pixelFormat (RGB8 or Mono8), timestampSource (Camera or System; from v2.0.0 the camera timestamp is the default) and, optional and experimental, stream.tag. Parameters can be overridden on the Data Layer under …​/input/. Restart the application after changing the file.

Camera Example File Content Example

Connect the camera, then edit the nodes under hdvisionsystems/lumiscan-cam-driver/<camera name>/features. Their names, values, permissions and descriptions come directly from the camera; refer to the camera vendor’s documentation. Values are written directly to the camera, so take care with network settings. This feature is marked experimental: values are not cached, and setting them repeatedly (for example from a PLC) can cause camera instability and a performance penalty. A value written to a feature node is lost when the camera is connected again; a feature file listed in the module’s cameras[].featureFiles is applied each time the camera is connected.

GenICam features, For the highest frame rate: TriggerOverlap, Release Notes: v2.0.0

Add a storage block to the system section of lumiscan-cam-driver.json and restart the application. Without it, Save does nothing.

Storage settings, Saving Image Files

Both lead to the same result. From v2.1.0, capture, save, load, remove and list-images can be started with one write to <camera name>/control/<operation>/execute, which returns when the operation has finished; from v2.3.0, trigger is offered as an execute method only. connect-camera, disconnect-camera and reset have no execute node and must use the handshake. Only one process may write request at a time, and in both cases you check control/status/code and control/status/text afterwards. Handshake steps:

Execute a Method, When a Functionality Runs, Handshake

The image is published on hdvisionsystems/lumiscan-cam-driver/<camera name>/output/image together with width, height and pixel type, regardless of how the capture was started. This is raw sensor data that most viewers cannot display. From v2.1.0, switch on <camera id>/input/preview/enable to get a PNG on <camera id>/output/preview/encoded-data after each successful capture or load; <camera id>/input/preview/scale (0.0 to 1.0) makes it smaller. Compare output/package-identifier to check that the preview belongs to the latest image. To receive every image the camera delivers, use the experimental image stream on <camera name>/control/publish/output/stream/frame (from v2.3.0).

Description, Streaming Images (Experimental), Release Notes: v2.1.0

Give the camera a serial that contains simulation (for example simulation); the module then does not search for or connect to a real camera. Whether a camera is simulated depends on its serial, not on its id. Calling Capture loads an image from the configured storage folder and advances to the next image for the next capture. Since v2.0.0, the images are taken from images/<camera id> instead of images (move existing images before updating), and the folder is scanned on connection, so calling list-images is not needed. From v2.2.0, unifiedStorage set to true uses the storage folder directly.

Loading Images, Camera Example File Content Example, Release Notes: v2.0.0

From v2.3.0, use the experimental image stream. Connect the camera, set its features (for the highest frame rate, TriggerOverlap not Off), subscribe to <camera name>/control/publish/output/stream/frame, set control/publish/input/enable to true and call control/publish/execute. The Cam Driver does not trigger the camera by itself: images come on a hardware trigger, on control/trigger/execute, or continuously with the trigger mode off. While the stream runs, capture is not available; after the stream stops, the camera is connected again, which takes about two seconds on the camera we tested.

Running a stream, Streams

From v2.0.0, the Cam Driver needs the licence SWL-W-XCx-CAMDRIVERxHDVSx-V2NN; version 1 keys do not work. You need one licence per connected camera. On ctrlX OS (ctrlX CORE or IPC), a licence bought in the ctrlX Store is a ctrlX licence and needs no LumiScan Key. For other purchase routes, see the Licensing FAQ.

Requirements, Licensing FAQ

See the site-wide LumiScan FAQ, and for questions about the Data Layer itself the Data Layer FAQ. Contact HD Vision Systems customer success at customer.success@hdvisionsystems.com or +49 6221 6721905; for licences, licenses@hdvisionsystems.com.

Licensing FAQ