Impinj® ItemSense™ User Guide

Table of Contents

Introduction

Impinj ItemSense™ is a software platform that simplifies management and monitoring of RAIN RFID infrastructure by providing a graphical user interface (GUI) and simple-to-use APIs.

The functionality of ItemSense can fulfill many use cases. For example, ItemSense can discover an item’s identity and location, which can be used to manage a retail store inventory or to locate items within a medical facility.

ItemSense has the ability to:

  • Define RAIN RFID readers and organize them into logical groups
  • Monitor the health of the readers
  • Discover the identify and location of tagged items and track them
  • Capture configuration into storable units
  • Apply a predefined configuration to the readers during the execution of jobs
  • Collect tag data and make it available for use by upstream applications

These capabilities and how to use them are discussed in this document along with some concepts.

RAIN RFID

RAIN RFID is a global alliance promoting the universal adoption of UHF RFID technology, comparable to other wireless technology organizations such as the WiFi Alliance and Bluetooth SIG. RAIN uses the GS1 UHF Gen2 protocol which ISO/IEC has standardized as 18000-63. The word RAIN, which is an acronym derived from RAdio frequency IdentificatioN, is intended to emphasize the link between UHF RFID and cloud computing, as RFID-based data can be stored, managed and shared via the Internet.

Tags, readers and gateways

An RFID tag is the device that allows an item to be tracked once it is attached to an item. A tag is made up of two parts:

  1. An integrated circuit (IC), which stores information about the tag and processes the RF signals it receives
  2. An antenna, which receives and transmits RF signals

A reader, when paired with one or more antennas, can send and receive information to and from RAIN-compliant tags.

A gateway comprises a reader and one or more antennas integrated together into a single device. The Impinj xArray® gateway can perform extra functions like the calculation of tag locations, which ItemSense is able to utilize and augment with data from adjacent xArray gateways deployed within the same RFID infrastructure.

Throughout this User Guide the terms reader and gateway shall sometimes be used interchangeably. Nevertheless, the distinction between the two terms should be understood.

Capabilities

ItemSense supports the primary capabilities of RFID including inventory, real-time presence detection, and location.

Inventory

In RFID, an inventory is the act of performing a read of all the tags within the field of view of all the gateways or readers used by ItemSense. During this read, the details about the tags in the field of view are discovered. These details typically include the Electronic Product Code (EPC) which is conventionally a unique product code encoded into the EPC memory of the tag IC.

An inventory is performed by using a special searchMode which tells the tag to stop communicating with the reader once the tag has been read. One by one, each tag is read and silenced until all readable tags have been read. Silencing tags once they are read reduces signal interference. Less interference enables the reader to communicate more effectively thereby allowing a higher percentage of tags in an area to be read.

Reading tags in an area is probabilistic rather than deterministic. This means that performing two inventories on the same set of tags within the same area using the same Inventory settings, might yield different results. This is due to RF communication being influenced by many transient factors. Describing these goes beyond the scope of this guide. However, some of the primary factors which determine reader quality and consistency are:

  • Number of tags being read simultaneously
  • Distance the tag is from the reader
  • Strength of the RF signal from the reader
  • Interference from other RF signals
    This could be from other RF equipment in or near the reader. This is especially so if those devices are operating on the same or similar frequencies and channels as RAIN RFID readers.
  • RF reflections
    Some surfaces (like metal) in a room can cause RF signals to bounce off them.
  • Material (or substrate) to which the tag is applied
    Some materials can absorb RF which weakens a tag's ability to both receive and transmit RF.
  • Angle of the tag to the reader
    This is rotation of the tag around the X or Y axis (also known as roll and pitch).
  • Orientation of the tag
    This is the position of the tag rotated around the Z axis. Also known as the Yaw. This is important depending on the type of antenna used. Circularly polarized antennas are not affected by the orientation of the tag.
  • Predefined mode of the reader
    This is specified by the Reader Mode property of the reader configuration. Slower reader modes can tolerate more RF interference.
  • Length of time spent inventorying
    A reader or gateway is more likely to find hard-to-read tags when more time is spent inventorying.

ItemSense can control the configuration of each reader it manages. As such, the reader configuration used by a reader when performing an Inventory of tags can be tailored to the reader's environment. ItemSense provides full control of a reader. For example, it can set Gen-2 parameters such as Session, Search Mode, transmit power, antenna sequence, tag population, and enable/disable antennas.

Each of these parameters can be used to ensure that a reader picks up only tags which are of interest. To ensure only tags of interest are read, the following 3 steps can be considered:

  • Adjust the transmit power of the reader or gateway. This lowers the field of view of the gateway so that its read area is more constrained.
  • Disable antennas completely. If the above step doesn't constrain the field of view enough or the gateway is positioned near a RF reflective surface, it may be necessary to disable all antennas near that reflective surface, thus minimizing the amount and effect of reflections.
  • Use a Gen-2 EPC filter. Within RAIN RFID it is possible to configure the readers to only select tags whose EPC (or indeed values in other memory banks) conform to a specific prefix. This is useful when the tags of interest within the field of view of the reader all share common values within the tag memory banks.

Once a tag has been read, ItemSense will enrich the tag report with other information it knows about the tag before (optionally) storing the tag report in its internal database ready for querying at some later point.

Note: The database in ItemSense is not intended to be a long-term store of tag reports but more of an intermediary database which can be queried for select tag reports. This is typically done by a "connector" application which might then send tag reports on to other applications to fulfill business specific use cases or a connector could write the tag report to a long-term data store.

For more information about performing an inventory of tags, please refer to the Gateway Deployment guide which can be found on the support website.

Real-Time Presence Detection

The real-time presence detection function within ItemSense is very similar to the inventory function except that a different searchMode is used so that the tags are never silenced. They are continuously read, thus allowing an application to have real-time knowledge about a whether a tag is in a particular area. Since no tags are silenced in this mode, fewer tags can be monitored in real-time than can be inventoried.

Location

Another primary use case supported by ItemSense is determining tag location.

Initial XY position of a tag is calculated by the Impinj xArray gateway. Multiple xArrays can calculate XY positions for the same tag. ItemSense can combine this data to enhance the location accuracy of the tag. ItemSense will then use the calculated locations of tags to generate configurable custom events based on movements of the tag.

These events could be:

  • When a tag has moved a specific distance
  • When it has crossed a geographic threshold known as a zone boundary

The location of a tag cannot be calculated with 100% accuracy; there will be some error between a tag's calculated position and its actual position so the tag’s estimated location will vary with each calculation. This is known as jitter, because it causes a tag's location to apparently pop around. The greater the error, the greater the jitter.

Location accuracy and the amount of jitter depend on many factors. These are typically:

  • Number of xArrays
    When multiple xArrays calculate XY positions for the same tag, ItemSense can increase the number of readings for that tag and use this data to provide a more accurate location estimate (i.e. reducing jitter).
  • Distance of tag from the center of an xArray
    An xArray can provide a better determination of a tag's position if the tag is close to the antenna. (However, the tag must be at least one meter from the xArray.) The xArray makes a determination of a tag's position based on the number of times a tag's RF signal is received by each antenna. The further away from the xArray a tag is, the greater the error margin in the calculated position of the tag. In other words, the further the tag is from the center of an xArray, the greater the jitter.
  • Reflections in an environment
    Certain materials (or substrates) can reflect a tag's backscatter, which affects the transmission of the tag's response to a reader.
  • Absorption of RF
    Similar to the above point, certain substrates can absorb backscatters from tags causing them to be read by an xArray less frequently than what is optimum for calculating its position.
  • Predefined mode of the reader
    This is specified by the Reader Mode property of the reader configuration. Calculating the position of a tag requires as many reads possible of that tag. The reader mode affects the data rate of the communication between the antenna and the tag. The faster the reader mode, the better. However, fast reader modes are more affected by the RF environment.
  • Speed of the tag as it moves
    If the tag is moving then the count of reads by each antenna will be reduced. The faster the movement of the tag, the fewer the reads making it more difficult to calculate an accurate XY position resulting in higher jitter. The more static a tag, the better the final calculation of its location. The jitter caused by a moving tag can be mitigated by increasing the computeWindow in ItemSense set in a recipe. The computeWindow is the time span over which the xArray and ItemSense aggregates tag reads used for a location calculation. A tag's location is only calculated at the end of the computeWindow. Longer computeWindows produce more accurate tag positions but the longer the computeWindow the longer it will take to calculate the position of a tag.

To correctly position a tag on a floor, ItemSense needs the XY coordinates (in meters) of each xArray on the floor, relative to a chosen origin point (0,0). For more information on how to do this, please refer to the Gateway Deployment guide which may be found on the support website.

Threshold Monitoring

Threshold monitoring detects when an item has crossed a point, or threshold, and the direction in which the item was moving when it crossed. The threshold is typically a border between areas of a facility. Threshold monitoring allows items to be tracked as they move through the supply chain. In a typical scenario, a loading dock in a warehouse can be monitored to track items going into or out of the warehouse.

Threshold IN and OUT

When an item crosses a threshold, the item's tag is read and a transition event is generated to record the item's transition from one area to another. These events can be collected via the API or put in a queue to be consumed by a client. An event includes the following information.

  • Name of the threshold that is crossed
  • Unique identifier of the threshold
  • Time of day that the transition occurs
  • Direction, in or out, the item is moving as it crosses the threshold
  • Electronic product code (EPC) of the item's tag
  • Calculated confidence level that the item made the transition

Setting up a threshold to be monitored requires a reader and some configuration in ItemSense. Some parameters such as threshold name, IN and OUT directions, and other necessary details are defined by the user in ItemSense. In a usual scenario, many tagged items simultaneously cross a threshold; however, only a limited number of tags can be read at a time. To limit the number of tags read, an EPC filter is set to distinguish between the tags of different types of items thereby allowing the undesired tag readings to be filtered out. For example, if a tagged pallet is loaded with tagged cartons and each carton contains individually tagged items, an EPC filter can filter out all tags except the pallet tags. See the threshold setup for instructions.

Readers must be positioned near a threshold in one of three arrangements:

  • Overhead — A reader is centered directly above the threshold
  • Side-by-side — A reader is placed on each side of the threshold facing inwards
  • Overhead offset — A reader is placed above the threshold at each edge

For threshold monitoring, the reader must be either an xSpan gateway or an xArray gateway, depending on the reader arrangement. Either type of gateway can be used in the overhead or side-by-side arrangements, but the overhead offset arrangement requires an xArray gateway.

When choosing a reader arrangement, two factors to consider are the dimensions of the threshold and the number of adjacent thresholds. A single overhead reader can cover a ten-foot-wide threshold. An additional overhead reader can be added if a threshold is wider than ten feet. A side-by-side reader can be double-stacked on either side of the threshold to increase coverage. An overhead offset reader can cover two adjacent thresholds. The following figure shows the three reader arrangements for threshold monitoring.

Reader arrangements for threshold monitoring

Another factor to consider is the position of the tag on an item. When tags are positioned on top of an item, the overhead arrangement must be used. Either the side-by-side or overhead offset arrangement can be used when tags are positioned on the side of an item.

Additional factors to consider when choosing a reader arrangement for threshold monitoring are: number of tagged items simultaneously crossing a threshold; speed of the items as they move across a threshold; cost of a particular reader arrangement.

Laying out infrastructure

ItemSense simplifies the management of an RFID infrastructure. There are a small set of terms which are used to help group together related readers, like a set of xArrays for example, into a given physical area. It also allows for the enrichment of tag reports based on knowledge ItemSense has about the reader which reads the tag. For example, if a reader in facility "Building 1" and on floor "12" read the tag, then this information can be added to the tag report and used by an application to perform business logic based on that information. The terms used to map a physical infrastructure include facility, floor, and zone.

Facility

A facility currently represents the largest area concept, analogous to a physical building. One or multiple facilities may be defined within ItemSense. The user must specify a name when defining a facility, either via the HTTP API or through the ItemSense Management Console. This is the facility's primary (and only) identifier.

Floor

One facility can have many floors associated with it, each floor representing a level within the facility. Floors aren't technically defined as distinct entities within ItemSense, and aren't directly associated with a facility. Instead, floors are tied to facilities via a reader's placement value which is part of the readerDefinition profile for the reader. Simply put, readers are given a floor name as part of their placement and readers are also part of a facility.

Zone

ItemSense supports the concept of a zone, which is a named area of a facility. For example, a retail store floor plan may be divided into constituent departments. When ItemSense is configured with zones, tag data is presented with an additional “zone” field that identifies the specific zone on a specific floor in which ItemSense read a tag. Zones are tied to a floor in facility via zone configuration i.e. a zone can be part of a facility and a floor.

A zone should break up the space in a facility in a way that is meaningful way (e.g. Men’s, Women’s and Shoe departments in a retail store). Zone names do not have to be unique. If more than one zone definition has the same name, then the spaces of the two (or more) physical areas in a facility are combined into one logical zone (e.g. Women’s Shoes might be on the 1st floor and Women’s dresses on the 3rd floor; these could be combined into a “Women’s Clothing” zone). However, Zones cannot be layered such that the same physical space could be given more than one Zone name.

It is not necessary to define zones for the entire space in a facility. When ItemSense reads a tag, it gives the tag the zone name "FACILITY" if the tag is outside of any defined zones. The zone name "ABSENT" is given to a tag that has not been read for a defined period.

There are two types of zones; antenna zones and geographic zones.

  • Antenna Zone - An antenna zone is defined by the field of view of an antenna attached to a reader or a gateway. Anything read by that antenna is determined to be in an antenna zone. An antenna zone can have a string name associated with it. This string name augments the ItemSense tag report to reflect the antenna zone in which the tag was read.

    The primary advantage of an antenna zone is that it can be defined on any type of reader. However, the zone size is depends on RF environment and reader power. The size of the zone becomes smaller with a decrease in the power of the reader. As a result, antenna zones can be somewhat non-deterministic. To mitigate the variability, test the targeted space thoroughly to determine the correct power for the use case.

    Antenna zones are defined within the reader definition.

  • Geographic Zones - A geographic zone represents a fixed area of physical space. A geographic zone consists of a name, a facility, an optional floor name, and a set of Cartesian coordinates to define its shape. Each coordinate specifies a vertex of the shape. The vertices must be in an order that describes the polygon’s borders (i.e. points next to each other in the list must share an edge of the polygon). Each XY increment represents 1 meter of physical space. Zones are defined in meters but can be specified down to the centimeter (0.01m).

    Geographic zone sizes are fixed. They are not affected by the RF environment or by the reader's RF signal power. They can span multiple readers or be within the field of view of single reader. ItemSense requires a tag's estimated XY coordinates to determine whether it's in a particular geographic zone. Currently, only the Impinj xArray gateway can utilize geographic zones using Location Mode.

    Geographic Zones within ItemSense are created within a zone map. A Zone Map is used to group together one or more geographic zones. Many Zone Maps may be defined but on one at a time may be applied to a facility.

Zone Usage Practices

Antenna Zones Vs. Geographic Zones

Generally, if accurate control of the shape and size of a zone is a priority, it is better to use Geographic Zones over Antenna Zones. This is because Geographic Zones:

  • Allow for zones to be drawn which accurately reflect a physical space such as "Men's Department".
  • Utilize multiple readers in an RFID infrastructure. Geographic Zones are agnostic of the readers. This means if one reader isn't available, the zone still persists.
  • Use Location mode, which means an XY location of an item can be provided along with zone information.

However, there are cases where using an Antenna zone is more appropriate. These could be:

  • When xArrays gateways are not available. Geographic zones require XY locations to be calculated which is a capability currently limited to the xArray gateway. Without which, Geographic zones cannot be used.
  • When xArrays can’t be placed where you want them for coverage. There are some cases where xArrays cannot be placed where they are required for complete coverage of a certain area. This could be, for example, because the building in which the xArray would otherwise be placed already has other infrastructure (such as venting or piping) there.
  • When there are too many tags for Location mode. This is typically when ItemSense receives over 10,000 tag reports per second. More tag reports are generated when there is an "active" tag population i.e. when tags are actively moving. These limits put an implicit restriction on the amount of tags which can be accurately tracked simultaneously. This is because calculating a location requires many readings of each tag. If a larger amount of tags requires tracking than is possible by a single gateway, an antenna zone may be used.
  • When a contained space such as a set of shelves or a cabinet needs to be monitored.
  • When xArrays and non-xArrays are part of the same job. As xArrays support Inventory mode but non-xArray readers (like a Speedway reader) don't support location mode, it is only possible to use Inventory mode when non-xArray readers are part of a job. Only Antenna Zones are supported in inventory mode.
  • When an xArray can’t be used due to shape of the room. Thin rooms or rooms with low ceiling heights are not ideal environments for xArrays. It is often possible to get better item positioning with a well placed antenna attached to a Speedway reader combined with an Antenna Zone.
Geographic Zone Best Practices

It is possible for jitter to occur when monitoring the XY position of a tag. As the Geographic Zone feature uses the XY position of a tag to determine which zone a tag is in, it may be affected by jitter. If a tag is on a zone border, the tag can be seen to flip flop between one zone and an adjacent zone. Querying the Items table will reveal this is happening as it will show a tag changing zones quickly. This will also cause many zone change events to be generated in the Item History table or on a message queue. There are a few ways that this can be mitigated:

  1. Ensure a tag doesn't rest closer than the average jitter distance to a zone boundary. A rule of thumb for this is about 1.5 meters.
  2. If a tag is moving across a zone boundary, when it is near the boundary the zone flip-flopping between zones can occur but will stop again when it moves away from the zone boundary. In an upstream system which consumes tag events, a time-based buffer can be implemented to store several tag events before making a determination about whether a tag has transitioned or is just sitting on a zone boundary.
  3. In between two adjacent zones, a transition zone can be introduced. This is a new zone which represents a border between zones either side of it. For example, imagine two zones, "Zone A" and "Zone B". In between these zones a third zone is introduced which is called "Zone A or B". If tag jitter is around 1.5 meters then this zone should be at least 3 meters wide. The benefit of this extra zone is that when a tag flips between "Zone A" and "Zone A or B", it is definitely in Zone A and not in Zone B. However, the logic to determine this must be implemented in the upstream system which gathers the zone change data.
  4. Adjust the minimumMovementInMeters parameter in a location recipe. This parameter prevents location changes being report if they are below a certain distance. If possible, always set this value to just above the average jitter amount. For example, if the average jitter of tags is 1.5 meters then this value can be set to 1.7 meters. This would almost eliminate jitter. However, doing this also reduces fine grain location tracking so using the attribute is a balance between how detailed the tracking of tag is required versus how stable the tag reports should be.
Antenna Zone Best Practices

When Antenna zones overlap each other, ItemSense can perform zone disambiguation to determine which Antenna zone contains a tag. To help ensure the accuracy of this, antenna zones should overlap as little as possible. Use a combination of antenna type, antenna position, and reader RF signal power to confine the antenna's field of view to the exact area needing to be monitored.

A drawback of using Antenna Zones is that they don't provide an XY position of a tag. In addition to this, if the Antenna zone is associated with a Speedway reader, there will not be floor information for the tag as it is not possible to set the placement attribute on a Speedway reader. The reason for this is, unlike gateway readers, that the antennas attached to a Speedway could be on different floors or in different locations thus the placement information of the reader provides no insight to where a tag was read. However, it is possible to add this information to a tag report by employing a strong Antenna zone naming convention. The name of the Antenna zone is defined per antenna so antenna specific information can be embedded into the Antenna zone name. A suggested format could be:

LOCATIONNAME-FLOOR-XY_POSITION

Where:

  • LOCATIONNAME - a meaningful name describing the area being monitored
  • FLOOR - the name of the floor on which the antenna is situated
  • XY_POSITION - the position at the center of the space being monitored

Example: cabinet1-12-2.1_3.5

This information is then provided in a tag report in the zone field and made available to upstream consumers of the data. Upstream systems can then parse the zone name to extract the position information.

Security

The following security measures are used for the Impinj platform, which comprises RFID readers, ItemSense software, and other hardware components.

  • It is expected that the Impinj platform is deployed on the premises behind a firewall so that the system is not exposed to an external network.
  • Each reader has a one-to-one connection with a single instance of ItemSense and communication between the reader and ItemSense is over HTTPS. See the Reader Agent section for details.
  • Each reader is password-protected. The default password of a reader can be changed by using the RShell command, config, as described in the RShell Reference Manual (can be downloaded from the Impinj Support Portal).
  • A user is authenticated in API calls, AMQP registration, and communication with the IMC, as described in the Authentication section of the Reference Guide.
  • User roles are used to control access to various parts of the system, as described in the Users and Roles section of the Reference Guide.

Configuration Model

Reader Definitions

Reader Definitions hold ItemSense's knowledge about all the readers it manages in an RFID infrastructure. Each definition is a profile of a single reader. This includes:

  • IP address of the reader
  • Eleven-digit serial number (xxx-xx-xx-xxxx) of the reader
  • Name assigned by Impinj to the reader. For example: xArray-11-41-D9
  • Reader type, which ItemSense uses to provide reader-specific functionality and to validate reader configurations
  • Reader placement, specified by X-Y coordinates and angle
  • Reader zone, which ItemSense uses as the default zone for a tag that isn't part of an antenna zone
  • Antenna zones, which specify the mapping between a zone and an antenna of the reader
  • Features, such as Antenna Hub, that are enabled on the reader

Reader Configuration Profiles

Reader configuration profiles allow a user to capture set of configuration parameters. This provides the ability to define the ideal configuration for a reader and save it for subsequent use. This profile can be given a meaningful name which typically describes the intended use of the configuration e.g. "Warehouse1-deepscan-inventory". ItemSense provides default configurations out of the box. These defaults provide the typical settings for performing location or inventory jobs.

Recipes

The term "recipe" associates the reader definitions with the appropriate reader configurations for a given use case. It’s comparable to a cooking recipe, which provides both ingredients and instructions for creating a food item.

Recipes should be created when:

  • The kind of operations ItemSense is needed to perform are understood.
  • The necessary reader configurations to run that operation has been defined.
  • The reader definitions for the readers, on which the operation will be run, have been created.

In ItemSense, Recipes map reader configurations onto individual reader definitions, and specify other parameters relating to the intended operation. A default reader configuration may be applied to all readers within the facility unless overridden by a specific reader configuration.

Jobs

Once a recipe has been defined it must be run. This is done as part of a job. A job can be scheduled to start after a set delay. This is particularly useful when performing inventories of tags as it gives the tags a chance to failover to back to their previous state. The duration of a job must also be set.

When a job is run, many actions take place within ItemSense. The following are the steps of a typical successful job run:

  1. ItemSense is told to start a job.
  2. ItemSense waits for the duration specified in the startDelay.
  3. Once the job start duration has passed, ItemSense passes each reader their configuration as specified in the Recipe.
  4. If the configuration passed to this reader is correct for the reader, the job will now be in the "RUNNING" state which means each reader is performing its requested task.
  5. Tag data is received by ItemSense from each reader.
  6. Depending on the type of job being run, ItemSense will then:
    • Aggregate location data from multiple readers
    • Add zone information to the tag data.
    • Add facility and floor information to the tag data.
    • Begin tag presence expiry timers.
  7. ItemSense will now calculate any events (like a zone transition) based on the new information about the tag.
  8. Make the tag data available in the Items table. This is optional and can be set before starting the job.
  9. Make the tag data available in the Item History table. This is optional and can be set before starting the job.
  10. Publish events on any configured event queue. This is optional and can be set before starting the job.

The state of a job can be queried via the HTTP API or seen in the IMC. The information shown includes metadata about the job (e.g. start time, duration), any errors which have occurred during the job and the current status of the job.

It is often necessary for an application to perform different actions based on the current job status. This field represents the state of the job. A job, throughout its lifecycle, goes through several states. The following diagram shows how a job transitions between each state: A state diagram showing all the states a job can be in

The jobs states are:

  • WAITING: Once a job has been requested to start, the job waits for the period specified in the job start delay. If the start delay is 0 then the job will instantly transition to the INITIALIZING state.
  • INITIALIZING: The job manager initializes within ItemSense and waits for the RDE to start. ItemSense sets an initialization timer to 1 minute. If there is some problem starting the tag data manager (called the Reader Data Engine or RDE), ItemSense will reset the initialization timer and retry. It will do this up to 4 times. If the RDE still hasn't started, an error is raised and job goes to the STOPPING state. Otherwise, ItemSense will send each reader its configuration and wait for an acknowledgment.
  • STARTING: The job is in this state until either each reader has acknowledged the job start or a reader hasn't responded to the job start. If all readers don't acknowledge the job start, then the job moves to the STOPPING state. Otherwise, the job duration timer is now started and the job moves to the RUNNING state.
  • RUNNING: ItemSense will stay in this state until the job has run for the requested duration, at which point the job moves to the STOPPING state. If the RDE fails while in the RUNNING state, the job moves to the RESTARTING_RDE state.
  • RESTARTING_RDE: ItemSense will attempt to restart the RDE up to four times. If the RDE still hasn't started, an error is raised and job goes to the STOPPING state. Otherwise, the job goes back to the RUNNING state.
  • STOPPING: When entering this state ItemSense will attempt to stop any running readers and shut down the RDE. Once all readers have responded, the job moves to the STOPPED state.
  • STOPPED: The job is complete.

Job Best Practices

There are some behaviors and best practices which are useful to know, and should be considered, when using ItemSense's job feature:

  • When querying for data, it is good practice to check if a job is running - If no job is running, the data can be stale which can impact data quality for a use case. Also, when starting a job, ensure that the job makes it all the way to a running state without errors.

  • Always ensure a job has completely stopped - This can be done either via the IMC or by querying the job status API for a job status of "STOPPED".

  • Always monitor a job for errors - As it is possible for various types of errors to occur during a job, a job must be monitored for errors.

  • To implement constant real-time monitoring, jobs with infinite durations are preferred - However, there are some caveats to this. When a reader, which is part of a job, drops from the job (due to it either going down or losing network connectivity etc.), it will be not automatically re-added to the job when it comes back up. To successfully use the the infinite job run feature of ItemSense, a job monitor is required to detect when a reader has dropped, determine when it's available again and restart the job when it is.

  • If constant jobs aren't required, implement a job scheduler - This scheduler should start and stop jobs. It should also handle starting one-off jobs at a scheduled time as well as repeat jobs which need to be started at the same time every hour, day, week etc.. This allows for jobs to be configured to solve multiple use cases over a 24-hour period. In retail, this could be a deep scan inventory outside of store and real time location during store hours.

  • If starting multiple single-target session 2 or 3 inventory jobs back to back, remember to allow time for the tags to de-energize - When using single target session 2 or 3, tags are put in their "B" state which means they aren't able to be inventoried. They don't revert back to their a state until after a certain amount of time. For more information about this refer to the Reference Guide. The job start interface has a startDelay which allows for a job to be started after a certain wait time. This delay should be greater than the tag persistence time of the tags being used.

  • Readers need to be instructed to stop by ItemSense - If a job has been started by ItemSense but then ItemSense or its host goes down, the reader shall continue to run the job until it is either rebooted or ItemSense comes back up and issues a stop command. Stopping the ItemSense Docker container will not stop a reader from running a job. When ItemSense comes back up it will continue the job from the time it went down. For example, if a 120 second job was started and after 30 seconds itemSense goes down for a period of time, when ItemSense is restarted, the job will continue for another 90 seconds.

    If an ItemSense restart occurs during a job, an error message is be displayed in the IMC and in the response to a job status request. This error message indicates that the RDE will need to be restarted. This is just an informational message as ItemSense does this automatically. There also may be HTTP_FAILURE health events which the readers will generate when ItemSense goes down and forward to ItemSense when the connection is restored. If all the readers are communicating with ItemSense and the job is in the RUNNING state, the job is working correctly and no action needs to be taken. Otherwise, the connection errors need to be diagnosed and the job should be restarted. Please see the Health Monitoring section for more information about how health events work.

Items Table

This is the table within ItemSense that holds the known details of an individual tag at the time it is read. There is one entry in this table per EPC read by ItemSense. The table also holds the facility name and the observation time (which in the API is called lastModifiedTime). If the tag is continuously being read (i.e. a job is running and the tag is present), the lastModifiedTime is updated on an interval specified by tagHeartbeatDuration. If a job is not running, the lastModifiedTime shall be updated next time a job is run.

In addition to the parameters mentioned above, if running an inventory recipe:

  • The zone field will be updated with the antenna zone name. If no antenna zones have been defined, this will be the readerZone parameter from within the readerDefinition of the reader which read the tag.

If running a location recipe on an xArray:

  • The xLocation and yLocation fields will be updated.
  • The zone information will be updated with geographic zone name. If no geographic zones have been defined then this field shall be set to the literal string 'FACILITY'.

Each tag report has a presenceConfidence parameter. For ItemSense 2016r6, this has been deprecated; it is still present in the table for backwards compatibility. However, it is always set to the literal string 'HIGH'.

For information on how to filter the query to the Items table, refer to the Items section in the Reference Guide.

Item Table Size

The Items table can have up to three days' worth of item data, depending on the size of the hard drive attached to the server on which ItemSense is run. The following table describes when each table size will be available:

Percentage full Days of Records
0% 3 days
90% 2 days
99% 1 day

As an example, the top line in this table can be read as: If the hard disk is between 0% and 90% full, ItemSense will store up to three days' worth of Item data. Data older than 3 days will be removed.

ItemSense will check the size of the table on three-hour intervals. All table pruning is performed silently.

Item History Table

The Item History Table effectively captures movement events for tags. By default, the table captures changes to the following fields:

  • Zone
  • Facility
  • Floor
  • X Location
  • Y Location

The Item History table record captures the "from" and "to" value for each of these parameters. For example, there are a fromX and toX parameters or fromZone and toZone. Note that location information will not be populated for Inventory jobs.

In addition to the above fields, this table also captures the EPC and the observation time of the tag. It is typically used to track the history of tag movements within a monitored facility.

For information on how to filter a query to the Items History table, refer to the Items section in the Reference Guide.

Item History Table Size

The Items History table can have up to 180 days' worth of item data. This is dependent on the size of the hard drive on which ItemSense is run. The following table describes when each table size will be available.

Percentage full Days of Records
0% 180 days
25% 150 days
50% 120 days
75% 90 days
85% 60 days
90% 30 days
95% 14 days
99% 7 days

As an example, this table can be read as: If the hard drive is between 25% and 50% full, ItemSense will store up to 150 days worth of Item History data. Between 50% and 75%, ItemSense will store up to 120 days' worth of data, and so on.

ItemSense will check the size of the table on three-hour intervals. All table pruning is performed silently.

Interacting with ItemSense

A user can interact with ItemSense by using one of the following:

  • ItemSense Management Console (IMC) graphical user interface (GUI)
  • Open source client libraries
  • HTTP REST APIs
  • AMQP message queues

These methods of interaction are discussed in the sub-sections of this section.

ItemSense Management Console (IMC)

This is a web-based GUI application that provides a clean graphical interface to almost all of ItemSense's functionality including (but not limited to):

  • Reader Management
  • User management
  • Job control
  • View Tag Item History
  • Reader Health Monitoring

Right now, the IMC provides a graphical interface to most, but not all, of the full API. It is effectively an administration console; only a user with 'Admin' privileges can access the IMC. Please see roles for more information on the possible ItemSense user privileges.

This guide will not provide a walk-through of the IMC but will describe the concepts and parameters which the IMC exposes. For more information on the IMC, refer to the IMC Guide.

HTTP REST API

This is the primary method of interfacing with ItemSense. It is a standards-based HTTP REST API which exposes a number of endpoints used to both configure ItemSense and query for tag data. To facilitate this, the API is divided into the following sections:

Endpoint Description
authentication Used to manage access tokens to ItemSense.
configuration Used to configure various parts of ItemSense including, reader definitions, recipes, zone maps, SNMP and facilities.
control Used to manage jobs including start a job, stopping a job and querying for running jobs. It is also used to control software updates on the readers.
data Used for querying tag data including the current status of a tag as well as the history of events around a tag.
health Used to for querying the current status of a reader as well as the history of health status change events.

API Browser

ItemSense uses a third-party tool call Swagger to provide a browser for ItemSense's HTTP REST API. It allows a user to understand and interact with the API without the need for writing code.

The Swagger interface is split into two parts:

  1. Configuration, which can be accessed via the following URL:

    http://your-ip-or-dn/itemsense/swagger

    This allows a user to test, provision and understand all the configurable parts of ItemSense.

  2. Data, which can be accessed via the following URL:

    http://your-ip-or-dn/itemsense/data/swagger

    This allows a user to query for item history data and set up message queues.

This guide references the configuration in a conceptual manner that equally applies to any of the configuration methods. Except where noted, all of these methods offer the same functionality and parameters.

Event Message Queue

Instead of querying the API for the Item data, Item History or Reader Health information, a client may want to be notified when a particular event happens rather than send a request for data on an interval. A message queue could be used when:

  • A client needs to be notified of changes to tags in real-time.
  • The network traffic of a short polling interval isn't acceptable.
  • It is preferable for a client to be told of changes to tags rather than calculate deltas each poll for data thus simplifying client logic.

ItemSense supports AMQP version 0.9.1 to provide a message queuing facility. These can be set up via the HTTP API. Through the API it is possible to specify the events the client is interested in receiving by setting filter parameters within the body of an HTTP POST request message. Once received and parsed ItemSense will set up the queue based on the parameters in the request message and reply with details about the queue:

  • AMQP Server URL
  • Queue ID

The client will use these parameters in the reply to connect to the queue and begin waiting for ItemSense to post messages onto the queue. These messages will only be the messages which meet the filters specified in the queue setup request.

The message queues provided by ItemSense have the following behavioral properties:

  • Once a client has requested a queue be created ItemSense will create it immediately. It will then set a timer of 60 minutes which once expired ItemSense will clean up the queue if no client has connected to it within those 60 minutes. Once a client connects, no timer is set. When a client disconnects, the timer starts from zero again.
  • If multiple clients each need to receive the same event messages then a separate queue for each client need to be created.
  • If multiple clients connect to the same queue then each client shall receive messages in 'round-robin' fashion beginning with the client which connected first.

Items Events

ItemSense provides two areas for messaging. The first is for tagged-item events. These events have the same structure as an entry in the Item History table. Anytime a change to one of the attributes in Items History occurs for a particular EPC, a message for the event can be posted onto a message queue. However, it is possible to limit the messages posted to a queue by specifying some filter parameters at queue setup time.

It's possible to limit by:

  • EPC - this is when only a particular EPC is of interest.
  • from zone - for when only movements from a particular zone are of interest.
  • to zone - for when only movements to a particular zone are of interest.
  • from facility - for when only movements from a particular facility are of interest.
  • to facility - for when only movements to a particular facility are of interest.
  • distance - for when only when a tag has changed location by a specific distance.

It is possible to combine these parameters. For example, it is possible to say only notify me when this specific EPC has transitioned from zone X to zone Y within facility Z.

Health Events

The second type of message queue ItemSense provides is the health event message queue. Once configured ItemSense will post a message on to the queue every time one of the 5 health statuses for a monitored reader changes. Like the Item Events queue, it is possible to filter, during queue setup time, what events ItemSense should post to the queue.

Building Configuration

No matter which method is used to configure ItemSense, it is helpful to first think about the RFID infrastructure that ItemSense is going to manage and how it should to be broken up into the physical sections described above. Once that has been done it's possible to define actual configuration within ItemSense.

To configure a new ItemSense, follow these steps:

  1. Configure users with the appropriate roles.
  2. Add the required facilities.
  3. Divide the facilities into zones (if applicable). If a geographic zone is required, then create a Zone Map for the zones and give the Zone Map a floor to which it should be applied.
  4. Add a reader definition for each deployed RAIN RFID gateway. This can be done manually or via the network scanner within the IMC.
  5. Establish and understand what tag data needs to be collected based on the use case being fulfilled.
  6. Add the appropriate reader configurations and recipes to collect the tag data established in the step above.
  7. Configure and start jobs to perform these operations.
  8. Query tag data via the query-based API, or received tag data via event-based message queues.
  9. Monitor health of the readers via the query-based health API, via event-based message queues, or via SNMP traps.
  10. Update firmware on the readers when necessary using the software management API.

Each configurable resource (i.e. recipes, reader configurations etc.), the operations that can be performed on that resource, and the returned parameters associated with each operation, are fully defined in the API documentation.

The sections below give configuration guidelines for the most common use cases fulfilled by ItemSense. These values may require tuning for a particular installation.

ItemSense does ship with several default reader and recipe configurations, which may be used for many applications.

For more information on how to set each parameter, refer to the Reference Guide.

Inventory

Goal: to perform an inventory data on a set of static items

Reader Configuration Parameters

  • Set operation to INVENTORY
  • In the configuration sub-section:
    • Set readerMode to MODE_1002 if the readers are well spaced, and to MODE_1004 if the readers are densely spaced. Both of these reader modes will automatically adapt the actual reader mode used to the environment. See the Reader Mode section in the Reference Guide for more information.
    • Set searchMode to SINGLE_TARGET
    • Set session to 2 or 3. Adjacent readers can use different session values to improve inventory accuracy
    • Set antennas according to the type of reader
    • If in a fixed frequency regulatory region (such as ETSI), set channelConfig to desired frequencies of operation. Adjacent readers can use alternating ETSI channels to avoid interference and improve inventory accuracy
  • If inventorying a large number of tags, set tagPopulationEstimate to 32
  • If inventorying a small number of tags, set tagPopulationEstimate to 4

Recipe Parameters

  • Set type to INVENTORY
  • If all readers have the same configuration, then set readerConfigurationName to this configuration.
  • If different readers require different settings, create a map of reader to readerConfiguration in the readerConfigurations parameter
  • Leave the reportingInterval at its default of 5 seconds
  • Leave the computeWindow at its default of 20 seconds

Job Parameters

  • Set the recipeName to the recipe defined in the above step
  • If there is more than one facility defined, set the facility to the one in which this job will run
  • Set the durationSeconds to the required length of the inventory job. The longer the duration of the job, the more tags are likely to be inventoried.

Location

Goal: to track dynamic items within a facility

Reader Configuration Parameters

  • Set operation to LOCATION
  • In the configuration sub-section:
    • Set readerMode to MODE_1002 if the readers are well spaced, and to MODE_1004 if the readers are densely spaced. Both of these reader modes will automatically adapt the actual reader mode used to the environment.
    • Set session to 2 or 3. Adjacent readers can use different session values to improve inventory accuracy

Recipe Parameters

  • Set type to LOCATION
  • If all readers have the same configuration, then set readerConfigurationName to this configuration.
  • If different readers require different settings, create a map of reader to readerConfiguration in the readerConfigurations parameter
  • Set reportingInterval
  • Set computeWindow to a value that is larger than reportingInterval. However, a longer computeWindow will also slow down the response time to location changes.
  • Set minimumMovementInMeters to equal the amount of movement above which needs to be reported. The lower this value, the more precision there is in the location data, but this comes at the expense of system load and possibly extra jitter.

Job Parameters

  • Set the recipeName to the above recipe
  • If there is more than one facility, set the facility to the one in which this job will run
  • Set the durationSeconds to the required length of the location job. You might want this job to run indefinitely, in which case, set the durationSeconds to 0

Threshold

Goal: to track items moving across a threshold

Reader Configuration Parameters

  • Set operation to THRESHOLD
  • Set configuration.readerMode to MAX_THROUGHPUT
  • Set configuration.session to 2 or 3. Adjacent readers should use different session values to improve accuracy

Antenna Configuration Parameters

  • Set name of the new antenna configuration
  • Each antenna configuration has an optional side of LEFT or RIGHT. This should be empty if is not applicable
  • Each antenna configuration has two sets of antennas. These are called in and out and represent the side of the threshold that the individual antenna is facing. All antennas which need to monitor the "in" side of the threshold need to be assigned to the "in" set and likewise for the "out" set.

Threshold configuration Parameters

  • Set the name of the threshold
  • Set the facility of the threshold, this must be the same as the facility defined for the reader
  • Set the readerArrangement property reflecting the physical arrangement of the readers and threshold:
    • SIDE_BY_SIDE, OVERHEAD, OVERHEAD_OFFSET, CUSTOM (Impinj internal R&D uses only)
  • Set the map of readers to the antenna configuration(s) already defined as part of the antenna configuration

Recipe Parameters

  • Set type to THRESHOLD
  • Set the threshold IDs of the thresholds you have created that you wish to use for this configuration. If none are specified, all thresholds will be used
  • If all readers have the same configuration, then set readerConfigurationName to this configuration.
  • If there are multiple reader configurations with different settings, then create a map of these in readerConfigurations

Job Parameters

  • Set the recipeName to the above recipe
  • If you have more than one facility, set the facility to the one in which this job will run
  • Set the durationSeconds to the required length of the location job. You might want this job to run indefinitely, in which case, set the durationSeconds to 0

Multizone per Reader

Goal: to use one reader with multiple antennas to locate items within different zones

Reader Definition

  • Map each antenna of the reader to a zone name using the antennaZones parameter

Reader Configuration Parameters

  • Set operation to INVENTORY
  • Set configuration.readerMode to MODE_1002, which will automatically adapt the communication frequencies to the environment
  • Set configuration.searchMode to DUAL_TARGET
  • Set configuration.session to 2 or 3
  • Set configuration.antennas according to the type of reader
  • If in a fixed frequency regulatory region (such as ETSI), set configuration.channelConfig to desired frequencies of operation
  • If inventorying a large number of tags, set tagPopulationEstimate to 32
  • If inventorying a small number of tags, set tagPopulationEstimate to 4

Recipe Parameters

  • Set type to INVENTORY
  • Assuming there is just one reader, then set readerConfigurationName to the reader configuration above
  • Assuming there are a limited number of tags, set reportingInterval to a low value. e.g. 1 (second)
  • Set computeWindow to a value that is larger than reportingInterval. This is the window over which reads from different antennas will be disambiguated

Job Parameters

  • Set the recipeName to the above recipe
  • If you have more than one facility, set the facility to the one in which this job will run
  • Set the durationSeconds to the required length of the location job. You might want this job to run indefinitely, in which case, set the durationSeconds to 0

Filter for specific EPCs

Goal: to improve RFID performance by filtering on only know EPCs

This configuration can be used for any operation type.

Reader Configuration Parameters

  • Set the tagMask of the filter parameter to the hex value of the EPC prefix that you want to filter on e.g. 3034. By default, this will filter on EPCs that have this prefix. You can make this filtering more general by setting a different memoryBank and/or bit pointer into memory.

Absence Detection using Tag Expiration

Goal: to detect when an item is no longer within the RFID "field of view"

This configuration is valid only when performing a location operation or a dual-target inventory operation.

One of the attributes describing a tag event, recorded in the Item History table, is the zone in which the tag is currently seen. This can be a geographic zone, antenna zone or the default zone of the reader which read the tag (which is set on the reader definition). This zone information is provided when a tag is read. When a tag ceases to be read, an event is added to the Item History table stating that the tag has moved to the zone "ABSENT".

To define when the tag should expire (that is, when ItemSense should report that a tag has transitioned to the ABSENT zone), there is the tagExpiryDuration parameter which is part of the recipe configuration. This allows the ItemSense user to specify, in seconds, how long a tag can be out of the field of view before it is reported as being in the zone ABSENT. However, the transition to the ABSENT zone isn't exactly tagExpiryDuration amount of seconds after the tag left the reader's field of view. This is because tagExpiryDuration is used along with the computeWindow and the reportingInterval, all three parameters together affect when the transition to ABSENT occurs.

The reportingInterval is how often ItemSense core receives an update from the reader containing all the read tags since the last update. The computeWindow specifies how long reads should be collated before being reported. This means that it is only once a computeWindow has finished does the tag expiration timer for a particular tag start and as such, the computeWindow must be longer than the reporting interval.

Note: The computeWindow and the reportingInterval are only used when running a LOCATION recipe for calculating tag expiration and XY location of a tag. For an INVENTORY recipe, only the reportingInterval is used.

To be able to use tagExpiryDuration effectively it’s helpful to understand how the value is being used in conjunction with these other 2 parameters. Imagine that we have a LOCATION job running with the following parameters set in the recipe:

  • tagExpiryDuration: PT9S
  • computeWindow: 10
  • reportingInterval: 5

The tagExpiryDuration is set to 9 seconds (specified as ISO8601 format), the computeWindow is 10 seconds and the reportingInterval is 5 seconds. During this job, tag A is read and then immediately disappears from the field of view of the reader. The following timeline diagram shows what happens between the time the tag has been read and when ItemSense declares that the tag is absent, the compute windows and the reporting intervals are shown.

A timeline example to show how tag expiration works.

The job starts at t=0, tag A is seen by the gateway at time t=2 seconds, and is then instantaneously removed from the field of view and never seen again. In the diagram, we can see that because of the compute window and reporting interval configuration, tag A is actually reported as present at t=5, and reported again at t=10, so the expiration timer actually doesn't start until t=10. This means that tag A is eventually reported absent at t=19, which is only 9 seconds after it was last seen but a full 17 seconds after it left the field of view.

The process described above is almost exactly the same for an INVENTORY job except that the tag expiration timer starts at the end of each reporting interval instead of each compute window.

The more work the readers are doing, that is, the more tags they are reading, the longer it can take to calculate the tag expiration. This may add a few seconds on to the time the tag is declared ABSENT by ItemSense.

Recipe Parameters

  • Set the tagExpiryDuration to a value greater than the reportingInterval. The smaller the value the quicker the response time, but the larger the load on the system.

Note that absence detection via tag expiration only generates ABSENT events after the antennas of the reader have completed one cycle time. This value is dependent on the number of tags in the field of view. For large numbers of tags, the reader must "warm up" in this way before it can perform absence detection.

Running jobs simultaneously in the same facility

Goal: to run more than one job at a time in one facility

To do this, the job will need to know what readers to use in the current facility. You can do this by giving readers a group as part of the reader definition. Then a job can be told use a group or groups of readers.

Note: Running multiple jobs in the same facility is supported only for jobs running Threshold recipes. Jobs running other recipe types must be run one at a time in a facility.

Reader Definition Parameters

  • Set or append a group to the groups property to one or many reader definitions such as dressing_room
  • Set or append a group to the groups property to one or many reader definitions such as warehouse

Job Parameters

  • Start a job appending the created group dressing_room to the ReaderGroups property
  • Start a job appending the created group warehouse to the ReaderGroups property

As long as no readers are in both groups, you'll now have two jobs running, each using a subset of your readers.

Initial Setup

When ItemSense has been installed started for the first time it will not be usable from any interface until some initial setup has been performed by the user. This initial set has to be done via the IMC. Once logged in, the user is taken through a 6 step wizard:

  1. Change the default admin password.
  2. Define a new facility. ItemSense comes with the facility "default" but the user is required to make another.
  3. Set up a network. This requires entering a name for the network and ether a Class C IP address or CIDR subnet. This class address can either be of a reader on the intended network or just an IP address which on same the class c network as the readers. It is possible to create multiple networks. Note: Each Class C network which will have readers, will need to be defined separately.
  4. Scan the networks defined in step 3 for Impinj readers and gateways. This can take a little while. The more networks defined in step 3, the longer this scan will take. This will produce a list of reader which can be selected. The selected readers will be registered during the next step. Click on the "Register Readers" when right readers have been selected.
  5. Reader are now being provisioned, that is, the Reader Agent is being installed on to the selected readers and they are being associated with this instance of ItemSense
  6. Ready to go. After this step, ItemSense will be ready to use via all interfaces.

Reader Agent

ItemSense is made up of three different components. There is the IMC, the ItemSense Core and the Reader Agent. The ItemSense Core is the central piece of ItemSense. It coordinates all of ItemSense's functions. From communicating with the readers and monitoring health, to managing jobs, storing tag reports and exposing tag data via the HTTP REST API. ItemSense Core doesn't connect directly to the reader's LLRP (Low Level Reader Protocol) port, it communicates with the third component of ItemSense, the Reader Agent.

The different components of ItemSense.

The Reader Agent is installed onto the reader itself into the Customer Access Partition (CAP), the space reserved on all Impinj Readers and Gateways for third party application to be installed on the reader. This means that no other CAP application can be used on a reader managed by ItemSense.

Apart from registration, ItemSense Core doesn't ever initiate communication with the reader. All communication with the reader is done through the Reader Agent. Reader Agent to ItemSense Core communication is done using a tailored purpose-built protocol called ISAP (ItemSense Agent Protocol). The protocol itself is implemented within the body of HTTPS POST request messages which are sent from the Reader Agent to ItemSense Core. These messages will contain the tag data read by the reader as well as health information on the reader itself. ItemSense Core controls the reader by issuing commands in the response to the POST requests. These commands typically include setting reader configuration or starting and stopping jobs.

Reader Agent Registration

Readers can only be associated to one instance of ItemSense Core at a time. Installing the Reader Agent onto the reader and associating the Reader to ItemSense Core is referred to as registering the reader. This function is performed by the IMC.

First step within the IMC is to define a class-C subnet by specifying an IP address on that subnet. Once this is defined, a scan for Impinj RAIN RFID readers can be performed. When the scan is complete, the readers which need to be managed by ItemSense can be selected by the user and the installation and the registration of the Reader Agent can be performed. To do this, click on the “scanner” button at the top of the readerDefinitions page in the IMC. This will navigate to the ”Discover Readers” page which provides the option to scan the network for Impinj readers. If a reader definition already exists for a discovered reader, the IMC will mark this reader with a small exclamation point(!).

Click on the “register selected readers” button and the installation and registration of the Reader Agent will begin.

This is a two-step process. The Reader Agent file is uploaded to the reader and then the reader is rebooted begin the installation of the Reader Agent. Once the reboot is complete and the Reader Agent is installed and running, it is in a state where it hasn’t been assigned to any ItemSense Core instance. At this point the IMC will send the Reader Agent information about how to communicate with the ItemSense core including:

  • ItemSense Core IP address - this is the IP address used to navigate to the IMC used when registering.
  • API Key - this is effectively the same as an authentication token except that during registration the token is generated by the IMC.
  • IS Core Certificate - This is a self-sign certificate used for the HTTPS communication from the Reader Agent to the ItemSense Core.
  • Reader ID - This is a moniker which is used by the Reader Agent to identify itself when it sends updates to ItemSense Core.

Note: A reader has a one to one connection with a single ItemSense Core. This means that the reader will need to be re-registered if it needs to be associated with a different ItemSense Core. This is done by creating a reader definition in the new ItemSense IMC, either manually or using the network scan tool, and then following the process outlined in the previous slide to register the reader with that new ItemSense instance.

All this needs to be done via the IMC. For this reason, to allow registration of the reader, the IMC requires the following ports to be open in any firewall which sits between the ItemSense Core and the reader:

  • Outbound HTTPS port 443 from the reader. This for ISAP, as mentioned earlier.
  • Inbound HTTP port 80 to the reader. For reader discovery.
  • SSH port 22 for managing the CAP through RSHELL (for tasks like re-register the Reader Agent).
  • Port 51505 – This Reader Agent listens on this when it has been installed but not assigned to any ItemSense instance.

The IMC will send the registration information to this port via HTTPS. Once the Reader Agent has been assigned to an ItemSense Core instance, the Reader Agent will stop listening on this port.

To provide a little more clarity, the following sequence diagram shows the four main sections of what happens when a reader is registered with an ItemSense Core instance. It shows the messages sent between ItemSense and the reader within each section; the four sections are reader discovery, Reader Agent install, reader registration, and reader check in. This flow is really managed by the IMC as the Reader Agent installation can only be done via the IMC.

A sequence diagram to show how Reader Agent registration works.

  1. During network scanning, the IMC sends out HTTP GET messages to the network. When it receives an HTTP response, which is usually a 401 UNAUTHORIZED, this tells the IMC that there is a web service listening,
  2. This time IMC sends out the HTTP GET message with the reader credentials which allows the reader to authorize the request and respond with it’s webpage. This contains a lot of details about the reader which the IMC uses to create a reader definition.
  3. Now the IMC has the reader details it will upload the ItemSense Reader Agent to the reader.
  4. The reader is rebooted which causes the Reader Agent to be installed.
  5. The IMC will then poll the reader to see if has finished rebooting. It does this by sending HTTP GET messages to the reader. When the reader is available again the Reader registration can happen.
  6. When the Reader Agent has started, but hasn’t been associated to any ItemSense instance, it will start listening on port 51505. This is the Reader Agent registration port. First, the IMC double checks that this port listening.
  7. Once the IMC has confirmed this, it will send the details which the Reader Agent will need to speak to ItemSense Core. Things like the ItemSense IP it should use, the HTTPS certificate, the ID of the Reader.
  8. At this point the Reader Agent stops listening on port 51505 and is now able to send updates to ItemSense about its health status and tag data.

Health Status Monitoring

ItemSense provides several features to make the management of an RFID network as simple and straightforward as possible. The first is by providing a user the ability to create a "profile" within ItemSense of each reader ItemSense is required to manage. This profile is called the readerDefinition in the ItemSense HTTP API. Once a reader has been registered, ItemSense is able to receive health updates about that reader. This health status can be queried via the HTTP API and also be seen in the reader definition in the IMC.

All Communication between the ItemSense Agent and the ItemSense Core is implemented using a tailored purpose-built protocol called ISAP (ItemSense Agent Protocol). The protocol itself is implemented within the body of HTTPS messages. For health, the way it works is that every second the Reader Agent will check in with ItemSense Core. It does this by sending the ItemSense core an HTTP POST message. The body of this message contains the health events generated since last check in and tag data if a job is being performed. The response contains commands from ItemSense to the reader, for example, reader configuration. This is not accessible directly by users and the reader check-in interval isn't configurable. The check-in interval is set to 1 second.

Via the API it is possible to query information for the health of the RFID infrastructure being monitored by ItemSense. The health information which can be queried for has been split into two sections:

  • Current State of a reader or set of readers.
  • History of health events.

A health event occurs when a compromise of a reader's health status is detected. Examples of health events: errors from the LLRP interface, reader clock going unsynchronized, various software faults etc. Information that is recorded by the event:

  • The time the event occurred
  • The name of the reader that triggered the event
  • The type of event, of which there are seven
  • A string code providing more details about the event and why it was raised

Health information is available via the following interfaces:

  • API – Via ItemSense's HTTP REST API, reader state and the history of health events may be queried.
  • Message queue – Connected clients can be notified of health events via a message queue. It is possible to set up queues with various filters so that only specific events are put onto the queue.
  • IMC – An individual reader's state can be monitored next to the reader definition. However, the history of health events cannot be searched for within the IMC.
  • SNMP – An SNMP trap or inform message can be sent to a configured destination whenever a health status changes on any monitored reader.

Reader Statuses

It is possible to query for the status of a single reader or multiple readers via the API. When querying a reader status, the following information is returned:

  • Reader name
  • The overall state of the reader
  • The versions of the software on the reader – FW/Agent
  • The last time ItemSense has received a message from the reader.
  • The last time the reader rebooted.
  • Current Status of each of the five monitored sub-categories.

The best way to understand what's the current state of the reader state is to look at the reader's "state" field. There are 6 possible reader states:

  • AWAITING_AGENT – This is when the reader is known to ItemSense, but ItemSense hasn’t received any health updates from the reader, possibly because the Reader Agent hasn’t been installed yet.
  • IDLE – Reported when reader is fully configured but performing no activities i.e. no jobs are running and performing no software updates.
  • RUNNING_JOB – There is a job currently active on the reader.
  • UPDATING_FIRMWARE – The firmware or the IS agent is in the process of being updated.
  • NOT_RESPONDING – reader not checked in with ItemSense recently. This could be due to network latency or reader disconnection from the network.

The state field is called "Health Status" by the IMC and is seen as field within the reader definition profile.

Monitored Health Categories

Along with the details about the overall health of a reader, ItemSense also provides statuses on five additional aspects of an individual reader. These are:

  • connectionStatus – Status of ItemSense’s ability to communicate to the Reader Agent on the reader. It is worth noting that just because ItemSense can’t communicate with the reader doesn’t mean that the reader is inactive or down.
  • throughputStatus - Status of how backed up the health and data queue events are inside the Reader Agent.
  • clockSyncStatus – Status of whether the onboard reader clock is in sync with its configured NTP server(s).
  • hardwareStatus – Status of communication with the reader through the LLRP interface.
  • softwareStatus - Status of the software layer. This status reflects the occurrence of any non-fatal error such as a file system error, a provisioning error, or an agent crash.

Each category has two fields associated with it. These are:

  • status - This the status of the category and can be one of three values: HEALTH, WARNING or FAILED.
  • code - This is the code associated to the last event received for the category within the monitored window. This is described below.

ItemSense will calculate which status value should be applied to the each of the five monitored categories every five minutes by counting all events that were received for the category within a rolling 15-minute window. It will then apply the following logic:

  • If there have been zero events in the last 15 minutes, then the category is reported as being in a HEALTHY state.
  • If there has been between 1 and 3 events in the last 15 minutes, then the category is reported as being in a WARNING state.
  • If there have been 3 or more events in the last 15 minutes, then the category is reported as being in an FAILED state.

Health Events

Every second the Reader Agent sends ItemSense Core all the different health events which have occurred since the last update. Each individual health event has the following properties:

  • eventTime - The time the event occurred.
  • readerName - This is the name of the reader which the event came from.
  • type - All events are one of 7 types.
  • code - a code generated by the Reader Agent which represents the health event. This could be something like ReaderException or ReaderRestartError.
  • args - This is a space in the health event message where additional details about the event can be specified. For example, if the event type is LIFECYLCLE and its code is REBOOT, then args might contain information such as "user initiated" to indicate why the reboot occurred. However, some of the messages seen in this section might not be immediately informative for an end user but would be great information to potentially provide to ItemSense support if necessary.

Health Message Queue

It is possible to monitor changes in health status. A queue can be created via the API interface. A queue can be created to filter health messages on:

  • A specific name of a reader.
  • A type of health event.

SNMP

Queries

ItemSense comes pre-configured with an SNMP component that responds to queries using SNMP v2 protocol and community name ItemSenseCommunity. The SNMP port is exposed by the ItemSense container at port 161, as defined by RFC1157. For ItemSense to receive SNMP queries this port will need to be open in any firewall which sits between a client and ItemSense (which runs the SNMP agent).

To test the service is running and check what can be seen when querying the SNMP port, the following can be used:

$  snmpwalk -v 2c -c ItemSenseCommunity itemsense-008.impinj.com 1.3.6.1
SNMPv2-MIB::sysDescr.0 = STRING: ItemSense Instance
SNMPv2-MIB::sysObjectID.0 = OID: SNMPv2-SMI::enterprises.25882.2.3.1
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (0) 0:00:00.00
SNMPv2-MIB::sysContact.0 = STRING: support@impinj.com
SNMPv2-MIB::sysName.0 = STRING: ItemSense
SNMPv2-MIB::sysLocation.0 = STRING:
SNMPv2-MIB::sysServices.0 = INTEGER: 64

Traps

It is possible to configure ItemSense to send SNMP trap or inform messages to an NMS (Network Management Station). Both SNMP v2c and encrypted SNMP v3 are supported.

The traps are sent by ItemSense when each of the five monitored health sub-categories change. In the trap, ItemSense will only send the status that changes. For example, if the throughput status goes from healthy to warning, a single trap will be fired and it will only contain the throughput status.

However, it is worth noting that sometimes a lot of statuses change at once which will send multiple traps almost simultaneously. An example of this would be when a reader status goes from AWAITING_AGENT to IDLE. All of the statuses of the monitored health sub-categories go from UNKNOWN to HEALTHY so a trap is sent for each one.

SNMP can only be configured via the API. Only one SNMP target can be configured at a time. SNMP configuration is split into two sections:

  • Auth Config - This is used for specifying the authentication values to be used to establish authentication and authorization between ItemSense and a target NMS. The required value change depending on whether SNMP v2 or v3 is required.
  • Trap Target Config - This is used to specify whether the SNMP message to send should be an INFORM or TRAP and details about the target NMS.

Essentially, an SNMP configuration object can be built by doing the following:

  1. Deciding if SNMP is required. SNMP functionality is enabled but creating a trapTargetConf object within ItemSense. It is disabled but assigning trapTargetConf to null. This can only be done via the API interface.
  2. Choosing if SNMP v2 or v3 is required.
    • If v2 is chosen then the communityName must be set. This is an ID/password for an NMS.
    • If v3 is chosen then authentication components must be specified. This includes the engine ID of the agent, userName, authentication key and privacy key. Reading about the SNMPv3 protocol is recommended to understand these attributes.
  3. Entering the appropriate NMS authentication information.
  4. Deciding if TRAP or INFORM messages are required.
    • TRAP messages are unacknowledged but when selected, the host name and port must be specified.
    • INFORM messages require a response from the NMS saying it received the it. The host name and port must be specified but as TRAP messages must be acknowledged, is possible to specify a timeout for how long ItemSense should wait for an acknowledgement to an INFORM message and the amount of time ItemSense retries if the INFORM message does timeout or if an error is received from the NMS for the INFORM message.

Note: ItemSense doesn't support SNMP Get requests from an NMS.

Managed Software Upgrades

ItemSense provides the ability to manage software upgrades on the readers. As many as 30 readers can be updated in a single update request. Both the Reader Agent software or the Impinj Octane™ firmware can be updated via the IMC or the API. However, the API provides more options to give the user finer control over the updates.

A user can control the upgrade by specifiying:

  • Particular readers on which to update the Reader Agent software
  • The types of readers on which to update the Reader Agent software
  • The maximum number of readers to update in parallel
  • Particular facilities where Reader Agent software will be updated on readers

Once an upgrade has been started, ItemSense provides the ability to monitor the progress. This can be done programmatically via the API or via the IMC. If an upgrade fails, an update job can be queried for error messages associated with the job. An error message might look like:

"message": "There was an error processing your request. It has been logged (ID 9e0315498ce3383b)."

The message includes an error ID that is entered in the ItemSense application logs along with additional information about the error.

Glossary

Acronym Name
IMC ItemSense Management Console
EPC Electronic Product Code
CRC Cyclic Redundancy Check
PC Protocol Control
TID Tag IDentifier
LLRP Low Level Reader Protocol
FHSS Frequency Hopping Spread Spectrum
IMC ItemSense Management Console
MAC Media Access Control
DHCP Dynamic Host Configuration Protocol