Overview

The RTA Agent is a lightweight, cross-platform, stand-alone console application designed to manage and persist RTA (Real-Time-Alert) configurations on connected Zebra scanners.

The application allows you to assign distinct configurations to individual scanners, which are applied automatically as soon as the designated scanner is plugged in.

Key Features

• Persistent Configuration: Automatically re-applies RTA settings after a scanner power cycle.
• Plug-and-Play: Detects newly connected scanners and applies configurations on the fly.
• Device-Specific Settings: Assign unique configurations based on a scanner's model or serial number.
• Flexible Deployment: Runs as a background process or as a visible console application for easy debugging.
• Cross-Platform Support: Compatible with various operating systems.

Prerequisites

• A supported Zebra scanner connected over USB and configured in a host-controllable mode (USB-SNAPI, USB-IBMHH, USBIBM-TT). Scanners in pure USB-HID-Keyboard mode cannot be managed and will be ignored by the agent.
• The Zebra CoreScanner driver must be installed and running on the host:
  • Windows: CoreScanner service.
  • Linux: CoreScanner daemon.
• Network access is not required.

How to Receive Real Time Alerts Data

For more information on how to receive RTA Alerts, please refer to Real Time Alerts (RTA) User Guide.

Installation

Install on Windows

The RTA Agent is distributed as a .zip archive containing two essential files:

• RTAAgent.exe: Executable application.
• RTAAgent-Config.xml: The configuration file where all RTA settings are defined.

To install the agent, copy these two files from the zip archive into a dedicated folder on your system (e.g. : C:\Program Files\RTAAgent).

Note: The folder must be writable by the user running the agent if log output is enabled.

Install on Linux

The RTA Agent is distributed as a .zip archive containing two essential files:

• RTAAgent: Executable application.
• RTAAgent-Config.xml: The configuration file where all RTA settings are defined.

No installation is required. Copy these two files from the zip archive into a dedicated folder on your system (e.g., /usr/share/zebra-scanner/rta-agent/).

Running the RTA Agent

Running the RTA Agent on Windows

The RTA Agent is executed via the command line.

1. Open a command prompt or terminal.
2. Navigate to the directory where you saved RTAAgent.exe.
3. Run the executable: RTAAgent.exe

By default, the agent will start as a background process without a visible window. To view live logs, see the Command-Line Arguments section below.

Additionally, users can automatically start this tool by adding this to the Startup folder/Task Manager in Windows.

Running the RTA Agent on Linux

The RTA Agent is executed via the command line.

1. Open the terminal.
2. Navigate to the directory where you saved RTAAgent.
3. Run the executable: ./RTAAgent

By default, the agent will start as a background process without a visible window. To view live logs, see the Command-Line Arguments section below.

Additionally, to start the agent automatically, add an entry to one of the following:

• A cron @reboot job, e.g.:

  
  @reboot /usr/share/zebra-scanner/rta-agent/RTAAgent
  
  

• /etc/rc.local (where supported by the distribution).
• A systemd unit file (recommended on modern distributions).

Core Behavior

On startup the RTA Agent:

1. Loads and validates RTAAgent-Config.xml from the same directory as the executable.
2. Enumerates all scanners currently reported by the CoreScanner process.
3. For each scanner, selects the highest-priority matching <device-rtaconfig> block (see Configuration Priority Logic).
4. Applies the corresponding RTA event settings to that scanner.
5. Continues running and watches for scanner connect/disconnect events.

Handling Scanner Connections

When a scanner is connected (a Plug-and-Play event), the RTA Agent:

1. Reads the new scanner's serial number and model number.
2. Walks the <device-rta-configurations> list and selects the first entry that matches according to the priority rules in Configuration Priority Logic.
3. Applies the matched <rta-configuration> block.
4. Logs success or failure for the device.

A scanner that does not match any rule is left untouched.

Updating Configurations

To modify RTA settings, edit RTAAgent-Config.xml and restart the RTA Agent. The agent does not currently watch the file for changes at runtime.

Logging

• In console mode (-s / -show) the same messages are also written to stdout in real time.

The RTA-Config.xml File

All settings for the RTA Agent are controlled through an XML file named RTA-Config.xml. This file allows you to define default, model-specific, and serial number-specific configurations.

Sample RTA-Config.xml:

<?xml version="1.0" encoding="UTF-8"?>
<!-- RTA Agent Configuration File -->

<rta-agent-config version="1.0">

    <!-- Device-specific RTA configurations -->
    <device-rta-configurations>

        <!-- Default configuration (no serial, no model) -->
        <device-rtaconfig name="all_scanners">
            <device-info serial-number="" model-number="" />
            <rta-configuration>
                <!-- Default RTA configuration for any device -->
                <rtaevent_list>
                    <rtaevent>
                        <id>38004</id>
                        <stat>7</stat>
                        <onlimit>Not set</onlimit>
                        <offlimit>Not applicable</offlimit>
                    </rtaevent>
                    <rtaevent>
                        <id>38001</id>
                        <stat>7</stat>
                        <onlimit>Not set</onlimit>
                        <offlimit>Not applicable</offlimit>
                    </rtaevent>
                </rtaevent_list>
            </rta-configuration>
        </device-rtaconfig>

        <!-- Model-specific configuration (model only, no serial) -->
        <device-rtaconfig name="model_specific">
            <device-info serial-number="" model-number="DS*" />
            <rta-configuration>
                <!-- Model-specific RTA configuration -->
                <rtaevent_list>
                    <rtaevent>
                        <id>38004</id>
                        <stat>7</stat>
                        <onlimit>Not set</onlimit>
                        <offlimit>Not applicable</offlimit>
                    </rtaevent>
                </rtaevent_list>
            </rta-configuration>
        </device-rtaconfig>

        <!-- Serial-specific configuration (with serial number) -->
        <device-rtaconfig name="serial_specific">
            <device-info serial-number="19145523080701" model-number="DS2208*" />
            <rta-configuration>
                <!-- Device-specific RTA configuration -->
                <rtaevent_list>
                    <rtaevent>
                        <id>38004</id>
                        <stat>7</stat>
                        <onlimit>Not set</onlimit>
                        <offlimit>Not applicable</offlimit>
                    </rtaevent>
                    <rtaevent>
                        <id>38001</id>
                        <stat>7</stat>
                        <onlimit>Not set</onlimit>
                        <offlimit>Not applicable</offlimit>
                    </rtaevent>
                </rtaevent_list>
            </rta-configuration>
        </device-rtaconfig>

    </device-rta-configurations>

</rta-agent-config>

XML Tag Description

The configuration file combines two layers:

Outer wrapper tags (defined by the RTA Agent itself – documented here):

Table 1: Outer Wrapper Tags

Tag	Attributes	Description
<rta-agent-config>	version	Root element. version is the config schema version; currently 1.0.
<device-rta-configurations>		Container for one or more <device-rtaconfig> entries.
<device-rtaconfig>	name	A single rule. name is a free-form, human-readable label used only in logs.
<device-info>	serial-number, model-number	Match criteria for this rule. Empty string "" or * means "any". model-number supports a trailing wildcard (see Using Wildcards).
<rta-configuration>		Container for the RTA settings to apply when the rule matches.

RTA event tags – Description (mirror Zebra's RTA / RSM model – see 4.4 for canonical references):

Table 2: RTA Event Tags

Tag	Description
<rtaevent_list>	List of RTA events to configure on the scanner.
<rtaevent>	A single RTA event configuration.
<id>	RTA event/attribute number (e.g. 38001, 38004).
<stat>	Statistic / trigger type for the event (e.g. 7 = "value above max").
<onlimit>	Threshold at which the alert is raised. Use Not set to leave the limit unchanged on the scanner.
<offlimit>	Threshold at which the alert is cleared. Use Not applicable for events that have no off-limit.

List of Supported Real Time Alerts

Configuration Priority Logic

The agent applies configurations based on a three-tier priority system. Rules with higher priority will override rules with lower priority.

Table 3: Configuration Priority Logic

Priority	Rule	Description
1 (Highest)	Serial Number Match	If a scanner's serial number matches the serial-number attribute in a <device-info> tag, this configuration is applied. It overrides all other rules.
2 (Medium)	Model Number Match	If no serial number is defined, the agent checks for a matching model-number. This rule overrides the default configuration. (including wildcards).
3 (Lowest)	Default Configuration	This configuration is applied if both the serial-number and model-number attributes are empty ("") or set to *. Acts as the base setting for all otherwise-unmatched scanners.

Using Wildcards

The model-number attribute supports the use of a wildcard character (*) to match a pattern. The wildcard can only be used at the end of the value.

• Exact Match: model-number="DS8178-SR0F007ZZWW" will only apply to scanners with that exact model number.
• Wildcard Match: model-number="DS8*" will apply to all scanners whose model number begins with "DS8" (e.g., "DS8178", "DS8108").

Available Arguments

You can modify the agent's execution behavior with the following arguments:

Table 4: Command-Line Arguments

Argument	Alias	Description
-s	-show	Prevents the console window from hiding. The agent runs as a foreground process and displays live log output, which is useful for debugging.

The method of stopping the agent depends on how it was launched.

Background Mode (Default)

Windows:

1. Open Task Manager.
2. Go to the Processes or Details tab.
3. Locate RTAAgent.exe.
4. Right-click and select End Task.

Linux:

kill <pid>

Console Mode (launched with -s)

1. Click on the console window where the agent is running.
2. Press Ctrl + C to terminate the process.

Common Issues

Table 5: Troubleshooting

Symptom	Likely cause	Action
Agent exits immediately	RTAAgent-Config.xml missing or malformed	Run with -s and review the parse error printed onto the console.
Scanner detected but RTA settings not applied	Scanner is in USB-HID-Keyboard mode	Switch the scanner to Manageable Host Mode Ex : SNAPI or IBMHH/TT (see the Product Reference Guide).
No scanners detected	CoreScanner service/daemon not running	Start the CoreScanner runtime, then restart the RTA Agent.
Settings revert after unplug/replug	Agent not running, or no rule matches the scanner	Confirm the agent is running and that a <device-rtaconfig> rule matches the scanner's serial/model.