Zebra RFID IoT
The Zebra RFID IoT connector (ZebraRfidIot) controls and receives data from Zebra fixed RFID readers (such as the FX7500, FX9600, or ATR7000). Instead of managing direct physical serial wires or proprietary connections, the connector exchanges structured events and commands asynchronously over the platform's internal MQTT broker by communicating with the Zebra IoT Connector (ZIOTC) service running locally on the reader.
This connector requires instance creation before you can send commands and receive events.
Architecture and setup
The communication line links the physical hardware reader directly to your App flows through an intermediary messaging loop:
Zebra RFID Reader → Zebra IoT Connector (On-Reader Service) → Platform MQTT Broker → Your App Flow
To establish communication, configure the ZIOTC service interface using the reader's local web administration console (located under communication > Zebra IoT Connector) to append uniform topic suffixes matching these paths:
Management Event Topic:
<Base Topic>/m-evtData Event Topic:
<Base Topic>/d-evtManagement Request Topic:
<Base Topic>/m-reqControl Request Topic:
<Base Topic>/c-req
If your reader firmware requires explicit response topic declarations, add these routes:
Management Response Topic:
<Base Topic>/m-resControl Response Topic:
<Base Topic>/c-res
Connection management
create
Creates a Zebra IoT connector instance for a specific reader, identified by its base MQTT topic. The base topic is required.
Parameters
baseTopic
The root MQTT topic of the target reader, as configured in its ZIOTC interface settings.
string
Output
Returns the name of the created instance.
Example
isConnected
Queries whether the underlying MQTT communication channel to the broker layer is open and active.
Parameters
None.
Output
Returns true if the communication link is operational, or false if it is not.
delete
Removes the instance and all registered listeners.
Irreversible action
Deleting an instance removes its configuration. To communicate with the device again, you must create a new instance.
Parameters
None.
Output
Returns true upon removal.
Reader status and configuration
The functions in this section and in Control and operations send a command to the reader and throw an error if the reader does not respond within 6 seconds.
getVersion
Retrieves the hardware and system firmware version details reported by the connected reader.
Parameters
None.
Output
Returns an object containing hardware and firmware version metadata.
getNetwork
Retrieves the current network interface settings running on the reader.
Parameters
None.
Output
Returns an object containing active network parameters, including local IP addresses and MAC addresses.
getConfig
Retrieves the operational parameter configuration block currently deployed to the reader.
Parameters
None.
Output
Returns an object containing the active configuration settings of the reader.
getStatus
Queries the active status of the physical reader hardware.
Parameters
None.
Output
Returns an object detailing diagnostic hardware conditions and state parameters.
getLed
Queries the color state configuration displayed on the reader's status indicator LED.
Parameters
None.
Output
Returns an object detailing the active LED color and visualization status.
getMode
Retrieves the tag scanning mode configuration currently running on the device.
Parameters
None.
Output
Returns an object containing the active scan mode and its parameters.
getLogConfiguration
Queries the system logging rules and level configurations mapped to the reader.
Parameters
None.
Output
Returns an object detailing active logging levels and event metrics.
Control and operations
setLed
Sets the status color displayed on the physical reader's indicator LED.
Parameters
color
The target color value to apply (off, red, amber, or green).
string
seconds
The duration in seconds for the color state to remain active.
integer
flash
Forces an intermittent flashing animation when set to true.
boolean
Output
Returns true when the reader confirms the command.
Example
setMode
Configures the reader's operational mode, including antennas, filters, and metadata collection. See Tracking mode selection for choosing the right type.
Parameters
options
type
The mode of operation: SIMPLE, INVENTORY, PORTAL, CONVEYOR, CUSTOM, or DIRECTIONALITY.
string
modeSpecificSettings
Mode-specific settings (such as inventorySettings or portalSettings).
object
environment
The operating environment: LOW_INTERFERENCE, HIGH_INTERFERENCE, VERY_HIGH_INTERFERENCE, AUTO_DETECT, or DEMO. Default HIGH_INTERFERENCE.
string
antennas
An array of antenna port integers to use. Uses all ports if omitted.
array
filter
A tag ID filter object (such as an EPC prefix). No filter if omitted.
object
transmitPower
The transmit power in dBm, as a single number or an array of numbers. Default 27 (36 dBm EIRP for ATR).
any
antennaStopCondition
Stop condition(s) for antennas, as a single object or an array. Defaults to a single inventory round.
any
query
Gen2 query parameters.
object
selects
Gen2 select parameters: an array of select objects (applied to all antennas) or an array of arrays (one per antenna).
array
delayAfterSelects
The duration in milliseconds (0 to 65) to wait after the final select before issuing a query.
integer
accesses
Gen2 access commands (read, write, lock, kill): an array of commands or an array of arrays (one per antenna).
array
delayBetweenAntennaCycles
An object defining a delay between antenna cycles if no tags are read.
object
tagMetaData
An array of metadata to report: strings such as ANTENNA, RSSI, PHASE, CHANNEL, SEEN_COUNT, PC, XPC, CRC, EPC, TID, USER, MAC, HOSTNAME, TAGURI, EPCURI, partial reads such as EPC[1,3-5], or objects such as { userDefined: ... }.
array
radioStartConditions
An object controlling when the radio starts inventorying after a start command.
object
radioStopConditions
An object controlling when an ongoing operation completes.
object
reportFilter
An object controlling when and how often a tag is reported. Cannot be set in INVENTORY mode.
object
rssiFilter
An object filtering tags by RSSI threshold. FX9600 only.
object
beams
An array of beam objects to use. ATR7000 only.
array
Output
Returns true when the reader confirms the configuration. Throws an error if type is missing.
Examples
Example 1: Basic inventory polling configuration
Example 2: Triggered portal filtering configuration
start
Instructs the remote reader to start radio sweeps and stream tag records over data event channels.
Parameters
None.
Output
Returns true when the reader confirms the command.
stop
Instructs the remote reader to halt active radio polling sweeps and pause incoming tag data streams.
Parameters
None.
Output
Returns true when the reader confirms the command.
Event listeners
onHeartbeatEvent
Registers a listener for the periodic heartbeat events of the reader, which indicate that it is still online.
Parameters
listener
The callback evaluated on every heartbeat. Receives the heartbeat event object.
callback
Output
Returns the string subscribed to confirm listener registration.
Example
onErrorEvent
Registers a listener for error events reported by the reader.
Parameters
listener
The callback evaluated on every error event. Receives the error event object.
callback
Output
Returns the string subscribed to confirm listener registration.
Example
onDataEvent
Registers a named handler that receives RFID tag data. This is the primary way of getting tag reads and includes options for aggregating and filtering the data.
Parameters
name
A unique name identifying this data handler.
string
handler
The callback receiving the tag data and the message count. With aggregation, it receives an array of unique tag messages; without, the single message. After the clearAfter interval of inactivity it fires again with an empty result and count 0.
callback
options
scanDuration
The time in milliseconds to collect unique tags before the callback fires with the batch. Set to 0 to deliver every read instantly. Default 0.
integer
clearAfter
The time in milliseconds of inactivity after which the internal list of seen tags clears automatically. Set to 0 to never clear. Default 10000.
integer
aggregate
Reports a batch of unique tags seen during scanDuration when true, or every single read immediately when false. Default true.
boolean
antenna
If set, only tags read by this antenna port are reported.
integer
Output
Returns the string subscribed to confirm listener registration.
Examples
Example 1: Streaming data delivery without aggregation
Example 2: Compiled window aggregation
This collects all unique tags seen in a 2-second window and then fires the handler with the complete batch:
clearData
Clears the internal cache of seen tags for a specific data handler, without waiting for the clearAfter interval. The handler fires once with an empty result.
Parameters
name
The name of the onDataEvent handler to clear.
string
Output
Returns true, including when no handler with that name exists.
Example
removeDataListener
Unregisters a data listener and clears its pending timers.
Parameters
name
The name of the data listener to remove.
string
Output
Returns the string unsubscribed, or not found if no listener with that name exists.
Example
Tips and tricks
Tracking mode selection
SIMPLE: Sends a data event immediately for every tag read. Use this for real-time presence detection.INVENTORY: Groups reads into periodic batch summaries with statistics. Use this for counting assets.PORTAL: Links with physical sensors to track tag bursts. Use this for doorways and logistics checkpoints.CONVEYOR: Optimizes for high-speed line sweeps where tags pass in fractions of a second.CUSTOM: Allows fine-grained control over low-level radio parameters for advanced scenarios.
Last updated
Was this helpful?