Go to websiteGet a demo

Zebra / RFID IoT Connector

This document provides a guide to using the Zebra class, a powerful interface for controlling and receiving data from Zebra Fixed RFID readers (e.g., FX7500, FX9600). The class leverages Zebra's modern IoT Connector (ZIOTC) service, which runs on the reader and communicates data over standard IoT protocols like MQTT.

Architecture Overview 🗺️

The Zebra class is designed to be the final piece in a larger data pipeline. It doesn't communicate with the reader directly over a serial or proprietary connection. Instead, it interacts with Heisenware's internal MQTT message broker, subscribing to topics that the reader's ZIOTC service publishes to, and publishing commands back to the reader.

The flow is as follows:

Zebra RFID Reader -> Zebra IoT Connector (on-reader service) -> Heisenware MQTT Broker -> Your Application (using this Zebra class)

Important MQTT Topic Configuration ⚠️

For this class to function, you must configure the ZIOTC service on the reader's web interface (under Communication > Zebra IoT Connector) to use specific topic suffixes. The topics you configure must match the ones used by this class, which are constructed as follows:

  • Request Topic: <Your Base Topic>/control-req

  • Management Event Topic: <Your Base Topic>/management-event

  • Data Event Topic: <Your Base Topic>/data-event

create

Creates an instance of the Zebra IoT connector interface, which will then connect to the MQTT broker to communicate with a specific reader.

Parameters

  • baseTopic: The root MQTT topic for the target reader, as configured in its ZIOTC settings. This is required.

Example

# baseTopic
<account>/zebra/atr7000/12345

getVersion

Retrieves the reader's firmware and hardware version information.

Output

An object containing version details.

getNetwork

Retrieves the reader's current network configuration (IP address, MAC address, etc.).

Output

An object containing network details.

getConfig

Retrieves the reader's entire configuration.

Output

An object containing the full configuration.

getStatus

Retrieves the reader's current operational status.

Output

An object containing status details.

getLed

Retrieves the current state of the reader's status LED.

Output

An object describing the LED's color and state.

getMode

Retrieves the reader's current tag reading mode.

Output

An object describing the mode and its parameters.

getLogConfiguration

Retrieves the reader's logging configuration.

Output

An object containing logging details.

setLed

Controls the reader's status LED.

Parameters

  • color: The desired color. Can be off, red, amber, or green.

  • seconds: The duration in seconds for the LED to be in this state.

  • flash: A boolean indicating if the LED should flash.

Example

# color
green
# seconds
5
# flash
true

setMode

Sets the tag reading mode and antenna transmit power.

Parameters

  • options: An object containing the mode configuration.

    • type: The reading mode. Can be SIMPLE, INVENTORY, PORTAL, CONVEYOR, or CUSTOM.

    • transmitPower: An array of integers specifying the power for each antenna (max 30).

Example

# options
type: INVENTORY
transmitPower: [25, 25, 25, 25]

Understanding Reader Modes

The type parameter in setMode is crucial for optimizing reader performance:

  • SIMPLE: The most basic mode. It reads and reports every unique tag it sees. Good for simple "is this tag present?" applications.

  • INVENTORY: Optimized for taking stock. The reader periodically reports a list of all unique tags seen during an interval, along with metadata like read counts and signal strength (RSSI).

  • PORTAL: Designed for dock doors or checkpoints. The reader typically waits for an external trigger (e.g., a motion sensor) to start reading and reports the batch of tags that passed through.

  • CONVEYOR: Optimized for items moving on a conveyor belt, accurately capturing tags that are in view for only a short period.

  • CUSTOM: Allows for fine-grained control over low-level radio parameters for advanced scenarios.

start

Commands the reader to start reading RFID tags. Tag data will be sent via data events.

stop

Commands the reader to stop reading RFID tags.

onHeartbeatEvent

Registers a handler to be notified of periodic heartbeat events from the reader, which indicate it is still online.

Parameters

  • name: A unique name for this handler.

  • handler: The callback function that will receive the heartbeat event object.

Example

# name
heartbeat_checker
# handler
<callback>

onErrorEvent

Registers a handler to be notified of any error events reported by the reader.

Parameters

  • name: A unique name for this handler.

  • handler: The callback function that will receive the error event object.

Example

# name
error_logger
# handler
<callback>

onDataEvent

Registers a handler to receive RFID tag data. This is the primary method for getting tag reads and includes options for filtering and aggregating data.

Parameters

  • name: A unique name for this data handler.

  • handler: The callback function that will receive the tag data.

  • options: An optional object to configure data handling.

    • scanDuration: Time in ms to collect unique tags before reporting them in a single batch. 0 reports tags immediately.

    • clearAfter: Time in ms of inactivity after which the internal list of seen tags is cleared.

    • aggregate: If true, reports a batch of unique tags seen during the scanDuration. If false, reports every single tag read immediately.

    • antenna: If set to an integer, only tags read by that specific antenna will be reported.

Example: Immediate Reporting

# name
immediate_reporter
# handler
<callback>
# options
aggregate: false

Example: Aggregated Reporting

This will collect all unique tags seen in a 2-second window and then fire the handler with the complete list.

# name
batch_reporter
# handler
<callback>
# options
scanDuration: 2000
aggregate: true

clearData

Manually clears the internal cache of seen tags for a specific data handler. This is useful for starting a fresh reading session without waiting for the clearAfter timeout.

Parameters

  • name: The name of the onDataEvent handler to clear.

Example

# name
batch_reporter

Output

Returns true on success.

Last updated