Data Services for RFID Developer Guide

Overview

Data Services for RFID provides cloud-based management, control, and RFID tag data collection for Zebra's FX series RFID readers (FX7500, FX9600). Data Services for RFID enables connectivity to the cloud platform to provide IOT capabilities to the reader. Once connected to the cloud, the readers can be managed and controlled using a REST API interface via the cloud. The reader tag data is also pushed to the cloud to be consumed by the cloud service.

The Data Services for RFID package includes three APIs that provide native cloud access for transmitting tag read events.

   Event Subscription for receiving RFID tag information and events via webhook subscriptions

   Analytics and Reporting for RFID for storing and retrieving decoded tag data in the Zebra Savanna cloud

   Device Management for RFID for remotely setting up, receiving alerts from and monitoring the functions and health of RFID readers

These APIs are all available in the Data Services for RFID package. Contact your account manager for information on accessing this package. 

System Components

The Data Services for RFID system has the following components.

  1. Cloud Service
  2. Cloud Agent
  3. Radio Control

Data Services for RFID enables cloud connectivity from the FX Reader to the Zebra Data Services proprietary cloud platform. Zebra Data Services empowers the user to build secure, scalable digital services with ease and speed. This solution aggregates and analyzes data from multiple edge devices and services, creating data-powered environments to provide real-time guidance and insights. For more information on Zebra Data Services click here.

Cloud Service

The Cloud Service exposes a REST API interface that can be used to manage, configure, and read tag data from RFID readers.

Cloud Agent

The Cloud Agent is the component responsible for connecting to the Zebra Data Services and performing the actions that are requested by the REST APIs.  The Cloud Agent also collects the tag data from Radio Control and pushes them out on the data interface.

Radio Control

Radio Control configures, controls, and maintains a connection to the RFID radio. Radio Control receives the tag read events from the radio and sends them to the Cloud Agent which in turn passes it onto the data interface.

 

Operating Modes

Cloud Connect provides the ability to configure the radio to different modes of operation that optimize the radio configuration based on intended use case. Once configured, the mode can be started using the “start” REST API and will continue to operate until the “stop” REST API is called. The following modes are supported in the cloud connect.

  1. Simple
  2. Inventory
  3. Portal
  4. Conveyor

Simple

Simple mode configures the radio to read and report all unique tags in the field of view of the radio. By default, the radio will attempt to read tags on all antennas. This can be adjusted using the “antennas” object when setting the mode.

By default, the radio will report all unique tags. This can be adjusted using the “filter” object when setting the mode. The filter object includes a filter match type (prefix, suffix or regex) and a filter operation type (include or exclude).

Inventory

Inventory mode configures the radio to read tags and report all unique tags for each antenna on a periodic interval. Additional meta-data (i.e. peak RSSI and number of reads for each antenna during the interval) is reported. By default, the radio will attempt to read tags on all antennas. This can be adjusted using the “antennas” object when setting the mode.

By default, the radio will report all unique tags once. This can be adjusted using the “filter” object when setting the mode. The filter object includes a filter match type (prefix, suffix or regex) and a filter operation type (include or exclude).

By default, the radio will report tags every second. This can be adjusted using the “interval” object when setting the mode. 

Portal

Portal mode configures the radio to report all unique tags that pass by each antenna immediately following a GPI event. The GPI event signals the beginning of the read period. As soon as the GPI event triggers the radio, the radio continues to read tags until no new unique tags are read for a configurable stop interval. Once the radio stops reading tags, it waits for the next GPI event to start the process again. 

By default, the radio will attempt to read tags on all antennas. This can be adjusted using the “antennas” object when setting the mode.

By default, the radio will report all unique tags once. This can be adjusted using the “filter” object when setting the mode. The filter object includes a filter match type (prefix, suffix or regex) and a filter operation type (include or exclude).

By default, the radio waits for a LOW signal on GPI 1. This can be adjusted using the “startTrigger” object when setting the mode.

By default, the radio continues to read until no new unique tags have been read for 3 seconds. This can be adjusted using the “stopInterval” object when setting the mode.

Conveyor

Conveyor mode configures the radio to read tags and report all unique tags for each antenna.

By default, the radio will attempt to read tags on all antennas. This can be adjusted using the “antennas” object when setting the mode.

By default, the radio will report all unique tags once. This can be adjusted using the “filter” object when setting the mode. The filter object includes a filter match type (prefix, suffix or regex) and a filter operation type (include or exclude).

 

Filters

On Reader

The on-reader tag event filters work using the Mode setup as discussed above.  You can add Regex filters to the read mode to further limit the read events being output by the reader.  This will only work with the raw output and not the decoded data.  There are a number of regex testing tools availible to help you find the right sequence to use.  We found the following works well in this service: https://www.regextester.com/ 

Examples:

"filter": { "match": "prefix", "operation": "include", "value": "3034257bf400b7800004cb2f" }

Only returns tags with this value.

"filter": {"match":"regex", "value":"^3032[\\w]*|[\\w]*cb1f$", "operation":"include"}

To return a tag starting with 3034 and ending with cb2f

Event Subscription 

Webhook subscription filters on the developer portal Subscription Setup page and in the Event Subscription API utilize JQ syntax and provide the ability to set up unique endpoints depending on the data being received from the reader.  If you want all tags from a specific antena, with specific components, and/or above certain power levels, to go to different endpoints in your system, you can set that up with jq filters. In addition, the Event Subscription API provides the ability to restructure data returned with JQ Transformations.

 

Setting Up Cloud Connect

  1. Update the reader firmware to the latest version. Refer to the Zebra support page for details. 
  2. Enroll your reader as described in Enrolling the FX Reader.
  3. From the developer.zebra.com, navigate to My Data Services -> APPS and copy your Consumer Key and Consumer Secret for use later.

Note: You will need the Consumer Key and Consumer Secret for obtaining an Authorization token. 

 

Use Cases for Cloud Management for RFID 

Refer to the API Reference documentation for endpoints and parameter details. 

 

Prerequisite

Before using the Cloud Management for RFID APIs, use your Consumer Key and Consumer Secret to obtain an Authorization token from the Two-Legged Oauth endpoint in the Cloud Management for RFID Postman CollectionThe token is valid for one hour. 

 

Setting up a Reader for the First Time

Update the reader configuration

   PUT /{deviceId}/configuration 

Update the reader network configuration

   PUT /{deviceId}/network 

Update the reader operation mode 

   PUT /{deviceId}/mode 

Start the reader reading tags

   PUT /{deviceId}/start 

 

Setting up a Reader after a Restart

Update the reader operation mode 

   PUT /{deviceId}/mode 

Restart the reader

   PUT /{deviceId}/reboot 

Tag Read Example JSON

{
  "type": "RFID-read",
  "event": {
    "id": "783fea65-9e1f-483f-bba0-6d8de2f6f24f",
    "timestamp": "2020-09-19T18:28:50.736+0000",
    "deviceId": "FX7500XXXXXX",
    "data": {
      "format": "epc",
      "id": "30f4257bf400b8c000034433",
      "reads": 1,
      "rssi": -68,
      "antennaId": "1"
    }
  },
  "analytics": {
    "tenant": "ecb9XXXXXX",
    "resourceId": "30f4257bf400b8c000034433",
    "location": "FX7500XXXXXX",
    "timestamp": "2020-09-19T18:28:50.736+0000",
    "meta": {
      "type": "inventory"
    }
  },
  "decode": {
    "gs1": {
      "version": "1.0.0",
      "humanReadable": "(01)00614141007394 (21)214067",
      "elementString": "010061414100739421214067",
      "components": {
        "gtin": 614141007394,
        "serial": "214067"
      },
      "epc": {
        "hex": "30F4257BF400B8C000034433",
        "uri": "urn:epc:id:sgtin:0614141.000739.214067",
        "scheme": "sgtin",
        "components": [
          "0614141",
          "000739",
          "214067"
        ]
      },
      "tag": {
        "uri": "urn:epc:tag:sgtin-96:7.0614141.000739.214067",
        "rawUri": "urn:epc:raw:96.x30F4257BF400B8C000034433",
        "scheme": "sgtin-96"
      }
    }
  }
}