Troubleshooting

This page describes problems with LumiScan Aztec Code Reader and how you solve them. Start with the general checks, then find your symptom below: each problem lists its symptoms, the possible causes, a diagnostic procedure and the resolution. Problems of the Data Layer itself are described in Data Layer troubleshooting, licence problems in Licensing troubleshooting.

General checks

  1. Read the application log. The application log is the ctrlX OS system log (ctrlX OS) or the console output of the app (PC). The reader writes the reason there when a run fails, when control/subscribe/execute or control/unsubscribe/execute is refused, when the source of the image stream cannot be subscribed to (the first failure), when frames cannot be read (at most one line every 5 seconds), and when a value in its settings file cannot be used.

  2. Check the addresses. All nodes are directly under hdvisionsystems/lumiscan-aztec-code-reader/; the reader has no modules. Addresses are lower case. Expected: your PLC or client uses exactly these addresses, as listed in the Data Layer Reference.

  3. Check the image source. The application that publishes the image node, normally LumiScan Cam Driver, must run on the same ctrlX CORE or ctrlX IPC (ctrlX OS) or be connected to the same LumiScan Keryx broker as the reader (PC, see LumiScan Keryx on a PC). Expected: the node named in input/image-address provides data, width, height and pixel-type.

  4. Check whether a run failed. This reader publishes no status-code or status-text node. A failed run leaves output/results untouched, holding the previous run’s codes. Read output/results before and after the run and compare, or check the log. See How do I know whether a run failed?.

  5. Check the settings file of the image stream. The reader keeps its stream settings in aztec-code-reader.json in the application’s configuration directory:

    Platform Configuration directory

    ctrlX OS

    /var/snap/rexroth-solutions/common/solutions/activeConfiguration/lumiscan-aztec-code-reader

    PC (Windows)

    %APP_RESOURCE_DIR%\etc\lumiscan-aztec-code-reader; without APP_RESOURCE_DIR, C:\ProgramData\HD Vision Systems GmbH\LumiScan Vision Suite\lumiscan-aztec-code\etc\lumiscan-aztec-code-reader

    The file is read once, at the start of the application: changes made to it by hand take effect at the next start. A value that cannot be used is ignored, and logged; a file that is not valid JSON is ignored, and logged. See Kept in the settings file.

Problem: The reader shuts down during start-up

Symptoms

On ctrlX OS, the reader stops shortly after it starts. Its nodes under hdvisionsystems/lumiscan-aztec-code-reader disappear from the Data Layer.

Possible causes

  • The ctrlX licence SWL-W-XCx-AZTECCRDSxHDVSx-V1NN is not available on the ctrlX OS device on which the reader runs. The licence is checked for up to ten seconds during start-up; if none becomes available, the reader shuts down.

Diagnostic procedure

  1. Open the ctrlX OS system log - expected: the reason for the shutdown. The system log names the missing licence.

  2. Check the licences in the License Manager of ctrlX OS - expected: the ctrlX licence SWL-W-XCx-AZTECCRDSxHDVSx-V1NN is available on the device on which the reader runs. One licence seat covers the reader. The Advanced licence SWL-W-XCx-AZTECCRDAxHDVSx-V1NN is not needed to start: without it, the reader runs with Standard functions.

Resolution

  • If the ctrlX licence is missing:

    1. Buy the licence SWL-W-XCx-AZTECCRDSxHDVSx-V1NN in the ctrlX Store.

    2. Activate it in the License Manager of ctrlX OS on the device on which the reader runs. Follow the Bosch Rexroth documentation for ctrlX OS.

    3. Start the reader again. Expected: it keeps running, and its nodes are on the Data Layer.

See Licence and My ctrlX app stops shortly after starting.

If the problem persists

Send the information listed under Information for support to support, together with the lines of the ctrlX OS system log that name the licence. For licences, contact licenses@hdvisionsystems.com.

Problem: My PLC or REST client no longer finds the reader after updating to 1.1.0

Symptoms

After the update to version 1.1.0, a PLC, a REST client or a saved app state that worked before no longer reaches the reader: the nodes it addresses under hdvisionsystems/lumiscan-aztec-code are not found.

Possible causes

  • In 1.1.0 the base path changed from hdvisionsystems/lumiscan-aztec-code to hdvisionsystems/lumiscan-aztec-code-reader, the name the other code readers already use. Anything addressing the old path must be repointed.

Diagnostic procedure

  1. Check the addresses that your PLC, your REST client or the saved app state uses - expected: they start with hdvisionsystems/lumiscan-aztec-code-reader/.

  2. Read a node at the new base path, for example hdvisionsystems/lumiscan-aztec-code-reader/input/image-address - expected: the node is found.

Resolution

  • If the client still uses the old base path:

    1. Repoint everything that addresses hdvisionsystems/lumiscan-aztec-code: a PLC, a REST client, a saved app state.

    2. Change only the prefix to hdvisionsystems/lumiscan-aztec-code-reader. The node names below the application are unchanged.

    3. Read or write a node at the new address again. Expected: the node is found.

See Description, Release Notes: v1.1.0 and A node is "not found".

If the problem persists

Send the information listed under Information for support to support, together with the address your client uses and the answer it gets.

Problem: output/results is an empty array

Symptoms

After execute returns, output/results holds an empty array: CodeDetectResultArray.results has no entry. In the image stream, a result on control/subscribe/output/stream/result has an empty results array.

Possible causes

  • The image holds no Aztec code. An empty output/results is not an error: it means the image was read successfully and contained no Aztec code. A run that found nothing publishes an empty array rather than an error.

  • The code is not an Aztec code. The reader reads Aztec codes, the compact 2D symbology with a bullseye finder pattern at its centre. Data Matrix codes, QR codes and linear barcodes are read by its sibling applications.

  • input/image-address names an image node that does not show the code. Each run reads the entire current contents of the image node named there.

  • The last run failed, and the empty array is the result of an earlier run. A failed run leaves output/results untouched. 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.

Diagnostic procedure

  1. Read the application log for the time of the run - expected: no failure. A failed run writes its reason there: the ctrlX OS system log (ctrlX OS) or the console output of the app (PC).

  2. Read input/image-address - expected: the address of the image node of the camera that sees the code, for example hdvisionsystems/lumiscan-cam-driver/camera1/output/image.

  3. Check the type of the code - expected: an Aztec code, with a bullseye finder pattern at its centre.

Resolution

  • If the image holds no Aztec code: nothing is wrong with the reader. Call execute again when the image node holds a picture with the code.

  • If the code is not an Aztec code: use the sibling application for its symbology: LumiScan DMC Reader, LumiScan QR Code Reader or LumiScan Barcode Reader. They work the same way.

  • If input/image-address names another image node:

    1. Write the address of the right image node to input/image-address. It is the address of the image node itself, not of its data child. The address is remembered.

    2. Write an empty value to execute. Expected: output/results holds an entry per code.

  • If the last run failed: remove the reason the log names: set input/image-address, correct an address that does not resolve, or make the image source deliver complete data in a supported pixel format (see Requirements). Then write an empty value to execute again. Expected: the log shows no failure for this run.

See Reading a Code and The Result.

If the problem persists

Send the information listed under Information for support to support, together with the value of input/image-address, the width, height and pixel-type of that image node, and the symbology of the code.

Problem: control/subscribe/execute answers Rejected (ctrlX DL_INVALID_VALUE) or CreationFailed (ctrlX DL_CREATION_FAILED)

Symptoms

A write to control/subscribe/execute (or to control/unsubscribe/execute) answers Rejected (ctrlX DL_INVALID_VALUE) or CreationFailed (ctrlX DL_CREATION_FAILED) instead of Ok (ctrlX DL_OK). Nothing changed: setting/stream/ still shows the values applied before.

Possible causes

  • Rejected / DL_INVALID_VALUE from control/subscribe/execute: stream mode without an address, or a queue size outside 1 to 64.

  • Rejected / DL_INVALID_VALUE from control/unsubscribe/execute: the address is not the source, or there is no source.

  • CreationFailed / DL_CREATION_FAILED: the settings file aztec-code-reader.json could not be written, for example because it is not valid JSON.

Diagnostic procedure

  1. Read the answer of the method call - expected: Ok or DL_OK. Rejected or DL_INVALID_VALUE points to an input, CreationFailed or DL_CREATION_FAILED to the settings file.

  2. Read the application log - expected: the reason for the refusal. On the ctrlX Data Layer a refused call carries no reason; the reader writes it to its log.

  3. After a refused control/subscribe/execute, read control/subscribe/input/enable, control/subscribe/input/address and control/subscribe/input/queue-size - expected: an address whenever enable is true, and a queue size from 1 to 64.

  4. After a refused control/unsubscribe/execute, compare control/unsubscribe/input/address with setting/stream/address - expected: the same address. A / at either end does not count.

  5. After CreationFailed or DL_CREATION_FAILED, open aztec-code-reader.json in the configuration directory (see General checks) - expected: a valid JSON file.

Resolution

  • If stream mode has no address: write the camera’s stream folder, for example hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream, to control/subscribe/input/address, then write to control/subscribe/execute again. Expected: Ok or DL_OK.

  • If the queue size is outside 1 to 64: write a value from 1 to 64 to control/subscribe/input/queue-size, then write to control/subscribe/execute again. Expected: Ok or DL_OK.

  • If the address to drop is not the source: write the address that setting/stream/address shows to control/unsubscribe/input/address, then write to control/unsubscribe/execute again. If setting/stream/address is empty, there is no source to drop.

  • If the settings file could not be written:

    1. Correct aztec-code-reader.json so that it is valid JSON. On a PC, lumiscan-aztec-code --generate-settings <folder> writes an example to start from.

    2. Write to control/subscribe/execute again. Expected: Ok or DL_OK, and setting/stream/ shows the new values.

      Changes made to the file by hand take effect at the next start of the application.

See Changing the source and Results of a method call.

If the problem persists

Send the information listed under Information for support to support, together with the answer of the method call, the values of the inputs of control/subscribe (or control/unsubscribe/input/address) and aztec-code-reader.json.

Problem: The stream runs, but no results arrive, or failed-frames grows

Symptoms

After control/subscribe/execute, no result arrives on control/subscribe/output/stream/result, or the counter control/subscribe/output/stream/statistics/failed-frames grows.

Possible causes

  • The reader’s stream does not run: the inputs of control/subscribe were written, but control/subscribe/execute was not called. Writing an input alone changes nothing.

  • No frames arrive from the source: the Cam Driver’s stream does not run, or control/subscribe/input/address is not the camera’s stream folder. The Cam Driver’s stream is not kept across a restart of the Cam Driver.

  • The source cannot be subscribed to. The reader then tries it again every 5 seconds while the stream runs.

  • Frames arrive but cannot be read, for example frames in a pixel format the reader does not support, or frames whose pixels do not fill the size they give.

  • Results are published, but your client does not subscribe to control/subscribe/output/stream/result. A read of the node returns only the latest result.

Diagnostic procedure

  1. Read control/subscribe/output/stream/active - expected: true. If it is false, read setting/stream/enable and setting/stream/address - expected: true and the camera’s stream folder.

  2. Read hdvisionsystems/lumiscan-cam-driver/<camera name>/control/publish/output/stream/active - expected: true.

  3. Read control/subscribe/output/stream/statistics/received-frames twice, a few seconds apart - expected: the value grows. The counters are updated about four times a second while the stream runs.

  4. Read statistics/failed-frames and control/subscribe/output/stream/last-failure - expected: failed-frames does not grow, and last-failure is empty. last-failure says why the last frame that could not be read failed; it is emptied when the stream starts.

  5. Read statistics/processed-frames - expected: the value grows. Each processed frame has a result published on control/subscribe/output/stream/result.

  6. Read the application log - expected: no failure to subscribe to the source, and no failed frames.

Resolution

  • If the reader’s stream does not run:

    1. Write the camera’s stream folder to control/subscribe/input/address.

    2. Set control/subscribe/input/enable to true.

    3. Write to control/subscribe/execute. Expected: Ok or DL_OK, then control/subscribe/output/stream/active is true.

  • If the Cam Driver’s stream does not run: start it, see the Cam Driver manual, Streaming Images. Its stream is not kept across a restart: after every start of the Cam Driver, connect the camera and call its control/publish/execute with enable = true. The reader’s stream can be started before the Cam Driver’s stream; results arrive once frames do.

  • If the address is not the camera’s stream folder: write the folder, for example hdvisionsystems/lumiscan-cam-driver/camera1/control/publish/output/stream, to control/subscribe/input/address and write to control/subscribe/execute. The reader reads the folder’s frame node. Expected: received-frames grows.

  • If the source cannot be subscribed to: make sure the Cam Driver runs and publishes the stream folder named in control/subscribe/input/address. While the stream runs, the reader tries the source again every 5 seconds; for the same address you do not need to execute again.

  • If frames cannot be read: read control/subscribe/output/stream/last-failure for the reason. Make sure the frames use a supported pixel format: Mono8, Mono12, RGB8, RGB12, BGR8, BGR12, Bayer_GR8, Bayer_RG8, Bayer_GR12 or Bayer_RG12 (see Requirements). Expected: failed-frames stops growing.

  • If processed-frames grows but your client receives nothing: subscribe to control/subscribe/output/stream/result to receive each result. Or set control/subscribe/input/keep-latest-output to true and write to control/subscribe/execute: the reader then also writes each stream result to output/results. krxclient subscribe hdvisionsystems/lumiscan-aztec-code-reader/control/subscribe/output/stream/result --count 5 shows that results arrive; it shows a flatbuffer by its size only.

A frame with no Aztec code gives a result with an empty results array, see Problem: output/results is an empty array. See also Reading the statistics and A stream delivers nothing.

If the problem persists

The image stream is experimental. On ctrlX OS, it has not been verified on Linux, on the ctrlX Data Layer, or with a real camera. On a PC, it has been tested on Windows with LumiScan Keryx and simulated images only; it has not been verified with a real camera. Send the information listed under Information for support to support, together with the values of control/subscribe/output/stream/active, control/subscribe/output/stream/last-failure, the counters under control/subscribe/output/stream/statistics/ and setting/stream/, and the value of the Cam Driver’s control/publish/output/stream/active.

Problem: After a restart the reader streams again by itself

Symptoms

After a restart of the application, control/subscribe/output/stream/active is true and results arrive on control/subscribe/output/stream/result, although your program has not executed anything.

Possible causes

  • The reader starts as it was. This is intended: control/subscribe/execute and control/unsubscribe/execute save what they apply in the stream member of aztec-code-reader.json. After a restart the reader subscribes to the same source and, when stream.enable is true, starts its stream at once.

  • stream.enable was set to true in aztec-code-reader.json by hand. true starts the stream at the start of the application.

Diagnostic procedure

  1. Read setting/stream/enable and setting/stream/address - they show what was applied last, as the settings file keeps it. Expected, if the reader should not stream after a start: setting/stream/enable is false.

  2. Open aztec-code-reader.json in the configuration directory (see General checks) - expected, if the reader should not stream after a start: stream.enable is false or left out.

Resolution

  • If the reader should not stream after a start: set control/subscribe/input/enable to false, then write to control/subscribe/execute. This stops the stream now and is saved in aztec-code-reader.json, so the reader starts out of stream mode next time. The frame being read is finished first. Expected: control/subscribe/output/stream/active is false, and setting/stream/enable is false.

  • If the reader should not keep the source either: write the address that setting/stream/address shows to control/unsubscribe/input/address, then write to control/unsubscribe/execute. Stream mode ends with it. Expected: setting/stream/address is empty.

See Kept in the settings file.

If the problem persists

Send the information listed under Information for support to support, together with aztec-code-reader.json and the values of setting/stream/.

Information for support

If a problem persists, send this information to support:

  • Software version: the version of LumiScan Aztec Code Reader you run. The files the image stream keeps in settings-history/ in the configuration directory record it as software.version.

  • Platform: ctrlX OS (ctrlX CORE or ctrlX IPC) and its ctrlX OS version, or a PC with Windows 11 or Ubuntu 24.04.

  • Data Layer: the ctrlX Data Layer (ctrlX OS) or LumiScan Keryx (PC). On a PC, also the broker address the reader uses; each app names it in its log at start.

  • Log: the application log from the time of the error: the ctrlX OS system log (ctrlX OS) or the console output of the app (PC).

  • Time: the date and time of the error.

  • Communication status: the answer of a refused method call (for example Rejected or DL_INVALID_VALUE), and the node values that the problem entry asks for.

  • Configuration files: aztec-code-reader.json and the files in settings-history/ from the configuration directory (see General checks).

Contact HD Vision Systems customer success at customer.success@hdvisionsystems.com or +49 6221 6721905; for licences, licenses@hdvisionsystems.com.