Overview
Cloud Connect for RFID provides cloud-based management, control, and RFID tag data collection for the FX series RFID readers (FX7500, FX9600). Cloud Connect 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 Cloud Connect for RFID package includes three APIs that provide native cloud access for transmitting tag read events.
Event Subscriptions 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 Zebra account team or sales partner for information on accessing this package.
Contents
Use Cases for Cloud Management for RFID
Setting up a Reader for the First Time
System Components
The Cloud Connect for RFID system has the following components.
- Cloud Service
- Cloud Agent
- Radio Control
Cloud Connect for RFID enables cloud connectivity 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.
Read Modes
Read Modes in the Data Services for RFID are designed to limit the traffic from RFID readers to the cloud. Fixed RFID readers are designed to activate and detect passive tags several times a second. Without having customized software to not only capture this data and send it somewhere, but process the flow into useful data, it can overwhelm a local network. New firmware on the RFID readers now allows users to not only send useful read data to the cloud, but also control when and how much is sent.
Read modes are a simple method to limit this traffic, but still get the needed information about when and where a tag was detected. There are different read modes to work with different use cases.
Currently we offer 3 main read modes: Simple, Inventory, and Portal modes. You can set up different modes by reader or antenna, so a single reader can function in multiple locations and use cases. You can set blocking/allowing filters on each antenna as well so you can ignore specific types of tags. You may only want to notify the system if it detects tag with specific prefix values or with rssi values over or under specific thresholds. Once the tag events are in the cloud, there are many more filters that can be applied. See the information regarding Event Subscriptions/Webhooks.
You capture the notification events from these read modes using webhooks setup with the Event Subscription Service or later using the Analytics and Reporting Query. 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 data service.
Simple Mode
Overview
Simple mode is used when you want to be notified the first time a reader detects a tag, but don’t care about how long it stays in an area or if it sees it again.
Use Cases
- Dock doors where you want to know when you are loading or unloading a truck.
- Distribution or assembly lines to ensure the products are passing through the right places to fulfil orders.
- Any time a product is moving through an area and you want to detect that it has passed checkpoints without having anything trigger it.
Configuration
Setting up read modes is simple. You can use the Device Management for RFID API /mode configuration. The body of the request to set the read mode differs for each mode. The only required filed is the mode value itself, as all other values have defaults.
{
"antennas": [ integer ], // default: all available. List numbers
// between 1-8 to correspond to the antennas
// you want to have running in this mode.
"mode": string, // simple mode should always list "simple"
"transmitPower": number // default: last set or 30 if never set.
// minimum:10, maximum:30. Allows you to
// adjust the detection strength/range. Lower
// means the antenna will not detect as far.
}Example
An example of a set read mode to Simple on antenna 1 with antenna power set to 10 (low):
curl -X PUT \
https://api.zebra.com/v2/devices/readers/FX7500XXXXXX/mode \
-H 'Content-Type: application/json' \
-H 'apikey: XXXXXX' \
-H 'cache-control: no-cache' \
-d '{
"antennas": [
1
],
"mode": "simple",
"transmitPower": 10
}'Inventory Mode
Overview
If you want to take inventory of a location, then you use Inventory mode. This will set up the reader to notify you of tags it’s detecting in a location on a scheduled timing. With Inventory Mode, a tag can be detected and notifications sent multiple times. Additional meta-data (i.e. peak RSSI and number of reads for each antenna during the interval) is reported.
Use Cases
- Warehouse or other storage location for inventory. If you have product that doesn’t move around a lot, such as a warehouse, you could set the inventory to trigger once per day or per hour. It would then send a notification for each tag detected once per hour.
- Detecting presence for internal tracking use cases, such as medications moving around a hospital or employees in an office where you want to know where something is now or where it has gone. You would need to set the scheduled detection to be much shorter, which does increase the traffic through the infrastructure and services, so there is a downside to using it this way.
Configuration
Setting up read modes is simple. You can use the Device Management for RFID API /mode configuration. The body of the request to set the read mode differs for each mode. The only required filed is the mode value itself, as all other values have defaults.
{
"antennas": [ integer ], // default: all available. List numbers
// between 1-8 to correspond to the antennas
// you want to have running in this mode.
"mode": string, // inventory mode should always list "inventory"
"interval": { // object for setting how long to wait between first
// detecting a tag and each time a notification is
// sent about it still being detected.
"unit": string, // options: "seconds", "minutes", "hours", "days".
// Default: "seconds".
"value": integer // the interval time in the unit set. Default: 1
},
"transmitPower": number // default: last set or 30 if never set.
// minimum:10, maximum:30. Allows you to
// adjust the detection strength/range. Lower
// means the antenna will not detect as far.
}
Example
An example of setting up an hourly inventory using the Device Management for RFID API /mode configuration. This will set antennas 2 and 3 to have maximum range and send tags it sees hourly.
curl -X PUT \
https://api.zebra.com/v2/devices/readers/FX7500XXXXXX/mode \
-H 'Content-Type: application/json' \
-H 'apikey: XXXXXX \
-H 'cache-control: no-cache' \
-d '{
"antennas": [
2,3
],
"interval": {
"unit": "minutes",
"value": 60
},
"mode": "inventory",
"transmitPower": 30
}'Portal Mode
Overview
This mode is set up to use the GPIO input on the reader to trigger taking an inventory of tags and sending notifications. A tag can be alerted on multiple times as long as it is in detectable range every time the GPI is triggered. 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.
Use Cases
- Automatic doors that can trigger the reader so a customer can detect products entering or leaving a location through the doors.
- Used in combination with any number of environmental sensors, from temperature to light beams. One example is a temperature sensor will trigger the port if the temperature rises above 0 in a refrigerator. The system can automatically take inventory of the effected products so they can recall/replace them due to safety factors.
Configuration
The Portal mode setup is slightly more complicated as you have to tell it what port you want to have triggering the read as well as well as how long you want to read for to detect the local tags. You can use the Device Management for RFID API /mode configuration. The body of the request to set the read mode differs for each mode. The only required filed is the mode value itself, as all other values have defaults.
{
"antennas": [ integer ], // default: all available. List numbers
// between 1-8 to correspond to the antennas
// you want to have running in this mode.
"mode": string, // portal mode should always list "portal"
"startTrigger": { // object for setting what input on the GPI ports
// will trigger the activation of reading and
// notifications.
"port": integer, // The physical GPIO port the sensor is connected to.
// Default: 1.
"signal": string // Options: "LOW", "HIGH". The voltage level to
// trigger reading on. Default: LOW
},
"stopInterval": integer, // The number of seconds to read looking for unique
// tags before stopping reading and sending
// notifications until triggered again.
"transmitPower": number // default: last set or 30 if never set.
// minimum:10, maximum:30. Allows you to
// adjust the detection strength/range. Lower
// means the antenna will not detect as far.
}
Example
The setup below will detect for 3 seconds after being triggered and send events for each tag it detects in that time.
curl -X PUT \
https://api.zebra.com/v2/devices/readers/FX7500XXXXXX/mode \
-H 'Content-Type: application/json' \
-H 'apikey: XXXXXX \
-H 'cache-control: no-cache' \
-d '{
"antennas": [
1
],
"mode": "portal",
"startTrigger": {
"port": 1,
"signal": "LOW"
},
"stopInterval": 3,
"transmitPower": 10
}'
Filters
On Reader
Overview
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/ Note that a filter on the read mode will prevent any traffic that does not meet the filter criteria from being sent to the cloud. If you wish to do more finely tuned filtering or traffic direction, there are filters that can be added to the webhook event subscription. Webhook subscriptions are handled in the cloud and filter on the decoded output.
Use Cases
- Only send tags that are from a specific manufacturer
- Do not send tags that are from employee IDs
Configuration
{
"mode": string, // The read mode. See options above.
"filter": { // object defining filters for what the reader should
// or should not send to the cloud.
"value": string, // The search key
"match": string, // Options: prefix, suffix, regex. How to search.
"operation": string // Options: include, exclude. Include means to only
// send notifications about tags that match the
// filter value. Exclude means to not send any tags
// that match the filter, but send everything else.
}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
On Webhook
The webhook subscription filters work using the JQ syntax and provide the ability to set up uniqe endpoints depending on the data being recieved. If you want all tags from a specific antena, with a 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 the subscription setup.
Setting Up Cloud Connect
- Update the reader firmware to the latest version. Refer to the Zebra support page for details.
- Enroll your reader as described in Enrolling the FX Reader.
- 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 Collection. The token is valid for one hour.
Setting up a Reader for the First Time
Update the reader configuration
Update the reader network configuration
Update the reader operation mode
Start the reader reading tags
Setting up a Reader after a Restart
Update the reader operation mode
Restart the reader
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"
}
}
}
}