---
title: "FAQ"
description: "Frequently asked questions about LumiScan QR Code Reader - image source and pixel formats, reading codes, the result, failed runs, the image stream, Standard and Advanced licences."
product: "LumiScan QR Code Reader"
component: "lumiscan-qr-code-reader"
version: "1.0.0"
display_version: "1.0.0.5"
latest_version: true
language: "en"
url: "https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/faq.html"
---

# FAQ – LumiScan QR Code Reader

Short answers to common questions and error messages for LumiScan QR Code Reader. Each entry links to the page with the details.

> [!TIP]
> Search this page for the exact error message. Each entry has a fixed anchor (for example `#faq-failed-run`).

## Requirements and setup

### Which codes does the reader read? {#faq-what-codes}

- **Answer:** It reads QR codes, the 2D symbology with a square finder pattern in three corners. Every code found in the image is reported; there is no limit of one per run. No template, reference picture, training step or configuration is needed: you give the reader the address of an image and call `execute`.
- **More:** [Description](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/description.html)

### Which image source does the reader need? {#faq-image-source}

- **Answer:** The reader does not talk to a camera itself. It reads the image node named in `input/image-address`, published by another application on the same Data Layer - on ctrlX OS the **same ctrlX CORE or ctrlX IPC** (remote Data Layer access is not supported), on a PC the same LumiScan Keryx broker - normally LumiScan Cam Driver, for example `hdvisionsystems/lumiscan-cam-driver/camera1/output/image`. The node must provide `data` (raw, uncompressed uint8 pixel data), `width`, `height` and `pixel-type` (GenICam pixel format name). Give the address of the image node itself, not of its `data` child: the reader appends `/data`, `/width`, `/height` and `/pixel-type`.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html), [Reading a Code](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-a-code.html)

### Which pixel formats are supported? {#faq-pixel-formats}

- **Answer:** `Mono8`, `Mono12`, `RGB8`, `RGB12`, `BGR8`, `BGR12`, `Bayer_GR8`, `Bayer_RG8`, `Bayer_GR12` and `Bayer_RG12`. The name is matched without regard to case, and the underscore may be left out of the Bayer names (`BayerGR8` and `bayer_gr8` are the same format). Bayer images are converted to colour before the search. Any other pixel format is refused, and the run produces no result. The image data must be at least `width x height x bytes-per-pixel` bytes for the declared format; a shorter buffer is refused.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html)

## Reading codes

### How do I read a code? {#faq-read-code}

- **Answer:** All paths are relative to `hdvisionsystems/lumiscan-qr-code-reader`.
  - Write the address of the image node to `input/image-address`. It is remembered, so set it again only when the image source changes.
  - Write an empty value to the `execute` method. The call is blocking and returns when the search has finished.
  - Read `output/results`: it holds every QR code found in that image.
- **More:** [Reading a Code](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-a-code.html)

### What does a result entry contain? {#faq-result-fields}

- **Answer:** `output/results` is a flatbuffer (`CodeDetectResultArray.results`) with one entry per code: `center` (a `Point2f` with `x` and `y` in image pixels), `text` (the decoded contents), `score` (how confident the read is) and `polygons` (the corner points outlining the code). On ctrlX OS, over the ctrlX REST API the numbers come back quoted, as strings, so parse them as numbers. `center` and `text` are always present; `polygons` may be absent for an entry, which means no outline was given, not an error.
- **More:** [The Result](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/the-result.html)

### How do I know whether a run failed? There is no `status-code` node. {#faq-failed-run}

- **Cause:** This reader publishes no `status-code` or `status-text` node and echoes no identifier. A run fails if the image cannot be read: no address set, an address that does not resolve, a missing or short `data` buffer, or an unsupported pixel format. A failed run leaves `output/results` untouched, still holding the previous run’s codes.
- **Solution:** Check the application log, where the reason is written (the ctrlX OS system log on ctrlX OS, the console output of the app on a PC), or read `output/results` before and after the run and compare.
- **More:** [Reading a Code](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-a-code.html), [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/datalayer-reference.html)

### Can I tune the detection, set a region of interest or create modules? {#faq-no-settings}

- **Answer:** No, not in this version. `input/parameter` carries no settings (its `DetectionParameters` table is empty), so writing to it changes nothing; the image stream does not read it either. There is no region of interest: every run searches the whole image. There are no modules: one reader per installation, at a single base path. There is also no result image; use LumiScan Cockpit to see the codes.
- **More:** [Data Layer Reference](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/datalayer-reference.html)

### How can I see the codes drawn on the image? {#faq-see-results}

- **Answer:** Open LumiScan Cockpit. It lists the reader as a view named `qr-code` and draws a rectangle around each code, labelled with the decoded text and the score. A code that was located but not decoded has no text and is labelled with its score alone. Cockpit does not draw the results of the image stream yet.
- **More:** [The Result](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/the-result.html)

### How long does a read take? {#faq-timing}

- **Answer:** Reading is synchronous: the write to `execute` returns when the search has finished. How long that takes depends on the image size, since the whole image is searched on every run.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html)

## Image stream (experimental)

### How do I read the codes in every frame of a camera stream? {#faq-stream-setup}

- **Answer:** Use the image stream (experimental). Only `control/subscribe/execute` applies its inputs: writing an input alone changes nothing. All paths are relative to `hdvisionsystems/lumiscan-qr-code-reader`.
  - Make sure the Cam Driver’s stream runs (`hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active` is `true`).
  - Write the camera’s stream folder, for example `hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream`, to `control/subscribe/input/address`.
  - Subscribe to `control/subscribe/output/stream/result`.
  - Set `control/subscribe/input/enable` to `true`, then write to `control/subscribe/execute`. The results arrive once `control/subscribe/output/stream/active` is `true`.
- **More:** [Reading Codes on an Image Stream](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-codes-on-an-image-stream.html#setting-up), [Streams](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/streams.html)

### Where is the reader’s settings file? {#faq-settings-file}

- **Answer:** `qr-code-reader.json` is in the application’s configuration directory: on ctrlX OS `/var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-qr-code-reader`; on a PC (Windows) `%APP_RESOURCE_DIR%\etc\lumiscan-qr-code-reader`, or without `APP_RESOURCE_DIR` `C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-qr-code\etc\lumiscan-qr-code-reader`. On a PC, `lumiscan-qr-code --generate-settings <folder>` writes an example. The file is read once, at the start of the application.
- **More:** [Kept in the settings file](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/reading-codes-on-an-image-stream.html#saving)

## Troubleshooting {#troubleshooting}

Problems and error messages are described step by step in [Troubleshooting](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html):

- [The reader shuts down during start-up](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#faq-app-stops-after-start)
- [`output/results` is an empty array](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#faq-empty-result)
- [`control/subscribe/execute` answers `Rejected` (ctrlX `DL_INVALID_VALUE`) or `CreationFailed` (ctrlX `DL_CREATION_FAILED`)](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#faq-stream-refused)
- [The stream runs, but no results arrive, or `failed-frames` grows](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#faq-stream-no-results)
- [After a restart the reader streams again by itself](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/troubleshooting.html#faq-stream-restart)

## Licensing and support

### Standard or Advanced licence - which one does the reader use? {#faq-standard-advanced}

- **Answer:** If an Advanced licence is available, the application uses it automatically. If none is available, it runs with Standard functions rather than refusing to start.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html#licence), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

### Which licence do I need? {#faq-licence}

- **Answer:** One licence seat covers the reader, since there is one reader per installation. Purchase routes:
  - Bought from HD Vision Systems: the licence is on a LumiScan Key (Windows 11 or Ubuntu 24.04). One LumiScan Key is needed per device running the software at the same time; keys can be exchanged between devices.
  - Bought in the ctrlX Store for Windows 11: ctrlX WORKS plus a LumiScan Key.
  - Bought in the ctrlX Store for ctrlX OS (ctrlX CORE or IPC): a ctrlX licence, no key.
- **More:** [Requirements](https://docs.hdvisionsystems.com/en/lumiscan-qr-code-reader/1.0.0/lumiscan-qr-code-reader/requirements.html#licence), [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)

### Where can I find more answers or get support? {#faq-support}

- **Answer:** See the site-wide [LumiScan FAQ](https://docs.hdvisionsystems.com/en/faq.html), and for the Data Layer on both platforms the [Data Layer FAQ](https://docs.hdvisionsystems.com/en/lumiscan-keryx/1.0.0/faq.html). Contact HD Vision Systems customer success at [customer.success@hdvisionsystems.com](mailto:customer.success@hdvisionsystems.com) or +49 6221 6721905; for licences, [licenses@hdvisionsystems.com](mailto:licenses@hdvisionsystems.com).
- **More:** [Licensing FAQ](https://docs.hdvisionsystems.com/en/lumiscan-licensing/1.0.4/faq.html)