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 Impinj ItemSense can fulfill many use cases. For example, ItemSense can discover an item’s identity and location, which can then be used to manage a retail store inventory or to locate items within a medical facility.

Impinj 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 is a global alliance promoting the universal adoption of UHF RFID technology, comparable to other wireless technology organizations such as the Wi-Fi 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:

  • An integrated circuit (IC), which stores information about the tag and processes the RF signals it receives
  • 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.

Regulatory Regions

Regulations in different countries apply restrictions on the UHF frequencies that can be used, the power at which they are transmitted, and the durations of the allowable signals. Impinj manufactures and certifies readers specific to each supported regulatory region.

Impinj ItemSense can manage the following regulatory regions:

  • United States (FCC)
  • Europe (ETSI)
  • Japan
  • China
  • Singapore


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


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 Search Mode 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 that are of interest. To ensure that 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.

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.


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 xArray readers 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 xArray readers
    When multiple xArray readers 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 determines 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] Reader Mode 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 and 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 computeWindow periods 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 section 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; see Overhead Offset Arrangement for more details. 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 the number of tagged items simultaneously crossing a threshold, the speed of the items as they move across a threshold, and the cost of the reader arrangement.

Overhead Offset Arrangement

An overhead offset arrangement is typically used with multiple, adjacent thresholds, as the most efficient way to maximize coverage. In this arrangement, each reader is positioned between two thresholds and each threshold is configured to use two readers.

Each reader is configured with two of four possible configurations.

  • xArray Offset Left and xArray Offset Left End cover the left side of the threshold.
  • xArray Offset Right and xArray Offset Right End cover the right side of the threshold.

Each tag in the overhead offset arrangement is read by two xArray readers as it moves through a threshold. However, unlike readers placed in a side-by-side arrangement, readers placed in an overhead offset arrangement can fill two roles, as shown in the image below. In that image, Reader B is used twice, both to cover Threshold 1 from the right and to cover Threshold 2 from the left.

The exception is that a reader positioned at the end of a line of thresholds/readers is used only once, configured either as xArray Offset Right End or as xArray Offset Left End. Again, this is illustrated in the image below.

Reader configuration for xArray overhead offset

Laying out infrastructure

ItemSense simplifies the management of an RFID infrastructure. There is a small set of terms which are used to help group together related readers, such as a set of xArray readers, 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.


A facility currently represents the largest area concept, and single or multiple facilities may be defined within ItemSense. Although analogous to a physical building, the user has final determination of what constitutes a facility in their deployment, and 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.

ItemSense comes with a single, pre-defined facility, named DEFAULT. Readers added to an instance of ItemSense must be defined with a valid facility, either DEFAULT or a name assigned by the user.


One facility can have many floors associated with it, each floor representing a level within the facility. Note that floors are not defined as distinct entities within ItemSense, nor are they 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.

If a floor name is not specified, or if the placement configuration within the reader definition is not specified, the floor name defaults to the facility name. If, however, the floor name is specified, the reader definition exists on that floor within the given facility. In either case, readers are given a floor name as part of their placement and are part of a facility.

The reader's floor or facility definition can be updated via the createOrReplace API.


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. If the antenna is not assigned a zone name, its zone name defaults to the reader zone name.

    The primary advantage of an antenna zone is that it can be defined on any type of reader. However, the zone size 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 only 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 xArray gateways are not available. Geographic zones require XY locations to be calculated, which is a capability currently limited to the xArray gateway, and without which Geographic zones cannot be used.
  • When an xArray cannot be placed where you want to place it. There are some cases where an xArray cannot be placed where it is 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 xArray readers and non-xArray readers are part of the same job. As the xArray reader supports Inventory mode but a non-xArray reader, such as the Speedway reader, doesn'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 the shape of the room. Thin rooms or rooms with low ceiling heights are not ideal environments for xArray readers. 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 determining whether a tag has transitioned or is just sitting on a zone boundary.
  3. Between two adjacent zones, a transition zone can be introduced. This is a new zone which represents a border between the zones on either side of it. For example, between a zone named "Zone A" and a zone named "Zone B," a third zone is introduced, 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 that 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: 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.


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 a 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.


The term "recipe" associates the reader definitions with the appropriate reader configurations for a given use case. It is 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.


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 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 calculate any events (like a zone transition) based on the new information about the tag.
  8. ItemSense will make the tag data available in the Items table. This is optional and can be set before starting the job.
  9. ItemSense will make the tag data available in the Item History table. This is optional and can be set before starting the job.
  10. ItemSense will 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 the 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 the 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.

If connectivity cannot be established with one or more readers during the job starting phase, ItemSense retries for a period of 4-5 minutes (depending on RDE initialization time) before giving up and failing the job.

If connectivity is established with all readers within that period, then ItemSense connects to the reader and the job starts.

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 duration 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 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 hours 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 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. This has been deprecated; it is still present in the table for backwards compatibility but is always set to the literal string 'HIGH'.

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.

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 as follows:

ItemSense API

The ItemSense API is a REST-like API used both to configure ItemSense and attached readers, and to configure mechanisms for retrieving collected item data. 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, 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.

For more specific information, please see the ItemSense API Guide.

ItemSense Management Console (IMC)

The IMC 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
  • Tag item history
  • Reader health
  • Event queues

For more detailed information on the IMC, please refer to the ItemSense Management Console Guide.

Event Message Queues

Rather than send a request for data at specified intervals, you can configure a message queue to notify you when a particular event occurs. To create a message queue, you define your event broker, then configure event publishers that will send messages to that broker. Event publishers can be reconfigured even after the job begins running. It can take up to 30 seconds for ItemSense to see the changes.

A message queue is useful when:

  • You want to be notified of changes to tags in real-time.
  • The network traffic of a short polling interval isn't acceptable.
  • You prefer to get notification of changes to tags rather than calculate deltas for each poll.

Event Message Queues can be implemented using the ItemSense Event API, which can be accessed directly or through the IMC. To access message queues through the IMC, from the top navigation bar, click More | Event Configuration. This will take you to the Publishers page. From there you can configure your publishers, or click the Brokers tab to configure your broker.

ItemSense provides support for event messaging through a variety of mechanisms:


  • Sending events to an external, user-provided AMQP or MQTT message broker. (This is recommended for high-volume tag deployments.)
  • Sending events to a user-specified URL using Webhook invocations.
  • The retrieval of events, by the user application, from AMQP and MQTT queues that are provided through an ItemSense built-in message broker.

Not Recommended: Retrieving events through the ItemSense Items API, which has been deprecated as of 2.1.0.


Following is a brief overview of how ItemSense interacts with the protocols to create message queues. It is expected that you will have a working knowledge of these protocols, as an in-depth exploration of their functionality is beyond the scope of this documentation. We have, however, included links to outside resources for your convenience.


  • ItemSense supports AMQP version 0.9.1.
  • Every message sent by ItemSense to the AMQP broker will have a routing key.
  • If you specify a prefix or suffix, the values will be combined with the type of message.
  • If you specify a full routing key, the full routing key will take precedence. All messages sent to the broker by the publisher will contain the full routing key rather than the prefix, suffix, or event type.
  • If using the internal AMQP broker, you cannot specify an exchange with an "impinj" prefix.
  • If connecting to an external broker, it is assumed you have already created the exchange.
  • The connection to an external exchange will be passive.
  • In order to connect to the ItemSense built-in broker, users must have either the DataReader or Admin role and supply their credentials from an account created within ItemSense.
  • We highly recommend that when using the Internal Broker with an AMQP Publisher, exchange declarations by the client should be passive. Although possible, active exchange declarations on the internal broker must match the parameters used by ItemSense or ItemSense will fail.

Other resources:


  • ItemSense supports MQTT version 3.1.1.
  • Every message that ItemSense sends to MQTT will have a topic, which the broker uses to filter messages for each connected client.
  • If you specify a prefix or suffix, the values will be combined with the type of message.
  • If you specify a full topic, the full topic will take precedence. All messages sent to the broker by the publisher will contain the full topic rather than the prefix, suffix, or event type.
  • The internal MQTT broker supports QoS levels 0 and 1 only.
  • In order to connect to the ItemSense built-in broker, users must have either the DataReader or Admin role and supply their credentials from an account created within ItemSense.

Other resources:


  • Webhooks should not be used for configurations that produce more than 500 tag reports a second. MQTT and AMQP are more scalable.
  • It is important to factor in network latency and HTTP response time when using a webhook. If the receiving webhook is slow, the ItemSense message buffer will overflow and data may be lost.
  • Every message sent by ItemSense to the WEBHOOK broker will specify a path.
  • If you specify a prefix or suffix, these values will be combined with the type of message as the path.
  • If you specify a full path, that path will take precedence. All messages sent to the broker by the publisher will contain the full path rather than a prefix, suffix, or event type.
  • The authentication type can be Digest or Basic .
  • If "QUERY_PARAM" is specified when messages are sent to the web server, a query parameter named "messageType" will be appended to the HTTP POST Request URL. For example: ""
  • We will attempt to utilize an HTTP persistent connection.
  • Every post will be JSON, containing a collection of messages.
  • Each post will contain messages of one "type" only.

Other resources:


You can set filters either through the Event Configuration section of the IMC or through the Events API 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:

  • Request 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. Only those messages that meet the filters specified in the queue setup request are posted.

ItemSense allows you to limit the messages posted to a queue by configuring filters at queue setup. You can filter by three event types:

  • Item
  • Health
  • Threshold

Following are brief summaries of each type. For more specific detail, please refer to the ItemSense API Guide.

Item Events

When configured for Item Events, ItemSense will post a message to the queue for each of the following Item types:

  • Item
  • Job Name Prefixes
  • From Zone
  • To Zone
  • EPC Prefix
  • From Facility
  • To Facility
  • Zone Transitions

Health Events

When configured for Health Events, ItemSense will post a message to the queue for each of the following Health types:

  • ITEM

Threshold Events

When configured for Threshold Events, ItemSense will post a message to the queue for each of the following parameters:

  • EPC Prefix
  • Threshold
  • Job Name Prefixes
  • Direction

Internal Queues

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

  • Once a client has requested that a queue be created, ItemSense will create it immediately. It will be marked as durable with a timer of 60 minutes. While a client is connected, no timer is set. The queue will be deleted if no client has been connected for 60 minutes. When a client disconnects, the timer starts from zero again. Messages will be held in memory until a client connects or a queue is deleted.
  • A queue can be given a deliveryMode parameter that will persist messages to disk. In the case of an outage, this guarantees that no messages will be lost. This will affect system performance due to messages being written to disk.
  • Messages are persisted inside the docker container. These messages will persist if the container is stopped and started but not if the composition is brought up and down.
  • If multiple clients each need to receive the same event messages, a separate queue for each client must be created.
  • If multiple clients connect to the same queue, each client will receive messages in 'round-robin' fashion beginning with the client that connected first.

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 be broken up into the physical sections described above. Once that has been done, it's possible to define an 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 event-based message queues.
  9. Monitor health of the readers via event-based message queues.
  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.


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 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
    • Set receiveSensitivityInDbm to filter out tag reads. This allows rejection of unwanted reports from distant tags when higher transmit power levels are in use. Values from -70 dBm to -30 dBm are accepted. If no value is specified, it defaults to -80 dBm, which disables the filtering.
    • 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 names to reader configuration names 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.


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. If you want this job to run indefinitely, set the durationSeconds to 0


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.

The following diagram shows the configuration of xArray antennas. Threshold xArray Antenna Configuration

The following diagram shows the configuration of xSpan antennas. Threshold xSpan Antenna Configuration

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
  • Set custom profile data specifying system behavior. If not specified, defaults will be used.
  • If desired, enable iteration data logging, used in tuning. It is disabled by default.

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 known 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.

Tag Heartbeat Duration

A change event is defined as either a zone change or a location change over the minimum movement threshold. Heartbeat Duration determines how often ItemSense publishes to the message brokers, or the item and history tables, if the tag is observed but its zone or location has not changed since the last published event. The purpose of Heartbeat Duration is to suppress the amount of unnecessary published records returned during a job run.

Instead of publishing every time the tag is observed, ItemSense publishes only if an event has taken place or if no change has taken place but the Heartbeat Duration has been reached. It can be set via the Recipes API or on the Recipes tab in the IMC. If not set, it defaults to five minutes.

The diagram below illustrates how Tag Heartbeat Duration works. To fully understand what is happening, keep in mind that “reporting interval” means how frequently, in seconds, the reader sends a tag report to ItemSense Core. The illustration can be described as follows:

  1. The job begins and the tag is reported.
  2. Every 60 seconds, while the tag is in the field of view, the reader reports on the tag status.
  3. At 5 minutes, no change events have triggered ItemSense to publish a report, but because the Tag Heartbeat Duration has been set to five minutes, ItemSense publishes that record and the Tag Heartbeat Duration resets.
  4. At 12 minutes, a change event occurs and ItemSense publishes it.
  5. At 17 minutes, five more minutes have passed since the last report but no change events have occurred, so the Tag Heartbeat Duration triggers ItemSense to publish a report. This happens again five minutes later, at 22 minutes.

Tag Heartbeat Duration

In summary, a report is published only if a tag was observed by the reader and either a change event has occurred (zone change or movement beyond the minimum threshold) since the last published event, or the heartbeat interval has elapsed since the last published event.

Tag Expiration Duration

The Tag Expiration Duration is optional. If set, it determines the time interval between the last time a tag has been observed and the time that ItemSense publishes it as Absent. Its goal is to eliminate, or greatly reduce, false publications of missing tags.

To understand Tag Expiration Duration, you must first understand Tag Heartbeat Duration. Like Tag Heartbeat duration, Tag Expiration Duration is only valid when performing a location operation or a dual-target inventory operation. Unlike Target Heartbeat Duration, it is optional. If not set, tag absence detection is disabled.

The following two examples demonstrate how Tag Expiration Duration works with Tag Heartbeat Duration. These examples are meant only to provide an overview and are relatively basic, involving one tag and one reader. The first example illustrates a straightforward situation, in which no records are published until the tag is recognized as Absent. The second is slightly more complicated, demonstrating more interplay between Tag Heartbeat Duration and Tag Expiration Duration. Both examples use the following parameters:

  • Reporting interval: 60 seconds
  • Tag Heartbeat Duration: five minutes
  • Tag Expiration Duration ten minutes

Tag Expiration Duration Example #1

  1. The job starts at 0.
  2. Every 60 seconds, while the tag is in the field of view, the reader records the tag status.
  3. No event occurs, so at five minutes and again at ten minutes, Tag Heartbeat Duration triggers ItemSense to publish a report.
  4. At 12 minutes, the tag disappears from the field of view. (This is not considered an event so is recorded but not published).
  5. For the next ten minutes, the tag is no longer observed, so ItemSense is never triggered to publish.
  6. At 22 minutes, Tag Expiration Duration recognizes that the tag has been missing for the duration set by the user (in this example, ten minutes).
  7. At 22 minutes, ItemSense publishes the tag as moving to Absent. It is reported absent as of 12 minutes, because this is when it was first recorded as missing from the field of view.

Tag Heartbeat Duration Example #1

Tag Expiration Duration Example #2

This example and the illustration that accompanies it illustrate a somewhat more complex scenario.

  1. The job starts at 0.
  2. Every 60 seconds, while the tag is in the field of view, the reader records the tag status.
  3. At three minutes, the tag disappears. (This is not considered an event so is recorded but not published).
  4. At five minutes, the tag is not observed, so ItemSense doesn’t publish. It is well within the expiration duration, so is not yet considered Absent.
  5. At six minutes, the tag reappears. Its reappearance is not counted as a change because it falls within the Tag Expiration Duration, but does trigger ItemSense to publish a Tag Heartbeat Duration report because more than five minutes have passed without an event since the last published report.
  6. At 11 minutes, because no change event has taken place, the Tag Heartbeat Duration triggers a published report again.
  7. An event occurs at 12 minutes, triggering a ItemSense to publish. This also resets the Heartbeat Duration timer.
  8. The tag disappears from the field of view again at 14 minutes.
  9. For the next ten minutes, the tag is no longer observed, so no report is triggered.
  10. At 24 minutes Tag Expiration Duration recognizes that the tag has been missing for the Tag Expiration Duration (in this example, ten minutes).
  11. At 24 minutes, ItemSense publishes a report of the tag moving to Absent. It is reported Absent as of 14 minutes, because this is when it was first recorded as missing from the field of view.

Tag Heartbeat Duration Example #2


Again, these are fairly simple examples of Tag Heartbeat and Tag Expiration durations and how they interact. A few takeaways:

  • The Tag Heartbeat Duration determines when a record is published only if no event occurs.
  • By itself, the disappearance of a tag is not considered a change event and ItemSense does not publish it as such. It does not become a change event and published as Absent until/unless it remains outside the field of view for the entire Time Expiration Duration.
  • The tag is reported Absent at the end of the expiration duration, but the time reported is the time it first disappeared. So, as in the case of our examples, if a tag disappears at 12 minutes and the expiration duration is ten minutes, at 22 minutes ItemSense publishes that it disappeared at 12 minutes.

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

When running multiple simultaneous jobs, it is important to ensure that each reader is used by only one job. Attempting to use a reader in more than one job will result in a job failing to start. For a threshold recipe, the readers to use are specified on each threshold configuration.

To use only a subset of readers in a job running a non-threshold recipe, it may be helpful to use reader groups. This can be done by giving readers a group as part of the reader definition, then telling a job to use one or more readerGroups when starting it.

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 must 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 either 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. -> Each Class C network that has 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.

The 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, you can select the readers that need to be managed by ItemSense, and the installation and registration of the Reader Agent can be performed. To do this, click on the DISCOVER READERS button at the bottom of the Readers Scanner page in the IMC. 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: 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: used by Reader Agent for listening 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 its 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.

Reader Health Events

The Reader Agent checks in with ItemSense once per second by sending an HTTP POST message to ItemSense. The body of this message contains the health events that have occurred since the last check-in. The body also includes tag data if a job is being performed. The response from ItemSense contains commands to the reader.

Examples of health events are errors from the LLRP interface, the reader clock going unsynchronized, and software faults. Each individual health event has the following properties:

  • eventTime: The time the event occurred
  • readerName: the name of the reader from which the event occurred
  • type: type of event. All events are one of seven types.
  • code: a code generated by the Reader Agent which represents the health event, e.g., ReaderException or ReaderRestartError.
  • args: 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 provide to ItemSense support if necessary.

Health Status Monitoring

Once a reader has been registered, ItemSense is able to provide health updates about that reader to a client. The health of the reader is determined when ItemSense processes the health events generated by the reader. Once determined, the reader's health is reflected by several reader properties in the ItemSense reader definition. When a reader's health status changes, ItemSense itself generates an event.

The following diagram depicts the general communications involved in monitoring reader health.

Getting reader health information via the API and message queue

A reader's health information is available from ItemSense via the following interfaces:

  • HTTP REST API: allows the reader health and the history of health events to be queried.
  • Message queue: allows connected clients to 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.
  • ItemSense Management Console (IMC): allows the reader health to be monitored in a GUI. However, the history of health events cannot be searched within the IMC.

Reader Health Properties

The health of a reader is reflected by the value of eight reader properties. These properties are displayed in the reader definition in the IMC and correspond to similarly named fields returned by the Reader endpoint of the Health API.

The Health Status property in the IMC or the state field in the API specifies the general operational state of the reader. It has the following possible values:

  • AWAITING_AGENT: The reader is known to ItemSense, but ItemSense has not received any health updates from the reader, possibly because the Reader Agent has not been installed yet.
  • IDLE: The reader is fully configured but performing no operations, such as running jobs or updating software.
  • RUNNING_JOB: A job is currently active on the reader.
  • UPDATING_FIRMWARE: The reader firmware or the reader agent is in the process of being updated.
  • NOT_RESPONDING: The reader not checked in with ItemSense recently. This could be due to network latency or reader disconnection from the network.

The following seven properties provide status or information related to specific operations and are displayed in the reader definition in the IMC by clicking the View details link:

  • Last check-in: The last time ItemSense received a message from the reader
  • Last reboot: The last time the reader rebooted
  • Connection status: The status of ItemSense’s ability to communicate with the Reader Agent
  • Throughput status: The status of throughput in the health and data buffers inside the Reader Agent
  • Clock sync status: The status of the reader's clock synchronization with its configured NTP server(s)
  • Hardware status: The status of communication between the reader agent and the reader firmware
  • Software status: The status of the reader's software layer

Five of these properties specify the status of a specific reader function: connection, throughput, clock synchronization, hardware, and software. The possible status values are HEALTHY, WARNING, and FAILED. ItemSense sets the value of the properties when it processes the health events received from a reader. This processing is discussed below.

ItemSense Health-event Processing

ItemSense processes health events received from a reader by counting all of the health events received from the reader for the particular event type within a rolling one-minute window. Each reader function, which includes connection, throughput, clock synchronization, hardware, and software, is associated with an event type.

ItemSense determines the status of each reader function based on the following criteria:

  • If there have been zero events in the last 1 minute, the status is HEALTHY.
  • If there has been between 1 and 3 events in the last 1 minute, the status is WARNING.
  • If there have been 3 or more events in the last 1 minute, the status is FAILED.

When the status is WARNING or FAILED, an error code is provided. When the status is HEALTHY, the error code is null. Each of the five properties corresponding to reader functions has different error codes, as described in the Code Details section of the API documentation.

Health Message Queue

It is possible to monitor changes in health status. A queue can be created via the API interface to receive messages when a health event occurs. The health messages can be filtered based on:

  • A specific name of a reader
  • A type of health event
  • A queue can be given a deliveryMode parameter that will persist messages to disk. In the case of an outage, this guarantees that no messages will be lost.

The reader agent sends a health event only when the state of an event type changes. For example, if the state of the CONNECTION type health event changes from HEALTHY to FAILED, the reader agent sends the event; if the state of the CONNECTION type health event changes from FAILED to WARNING or back to HEALTHY, the reader agent sends the event. No health event is sent as long as the CONNECTION type health event remains in the same state.

Log Rotation

For most ItemSense logs, they are rotated every hour, stored for 7 days and have a maximum total size allowed (See Table Below). The oldest logs will start being deleted when the maximum total size has been surpassed.

There are a number of logs generated by ItemSense. The following is a list of the most common logs used for debugging and troubleshooting.

Service Log Rotation History Maximum Total Size Description Location
Coordinator app Hourly             168 hours 500mb General Coordinator Log: Internal state and error message information $HOME/containers/itemsense/home/itemsense/Coordinator/var/output/logs
Coordinator request Hourly 168 hours 500mb HTTP Request Log: Detailed Web Service Communication from reader agents and IMC $HOME/containers/itemsense/home/itemsense/Coordinator/var/output/logs
ItemSenseReaderDataEngine app Hourly 168 hours 200mb General Application Job Log: job related activity (e.g. Starting and Stopping) $HOME/containers/itemsense/home/itemsense/var/output/logs
ItemSenseAPIService app Hourly 168 hours 100mb General Item Query Log: Internal Data Web Service state and error message information $HOME/containers/itemsense/home/itemsense/ItemSenseAPIService/var/output/logs
ItemSenseAPIService request Hourly 168 hours 100mb HTTP Request Log: Detailed Item Data Web Service Communication $HOME/containers/itemsense/home/itemsense/ItemSenseAPIService/var/output/logs

In addition to the logs for the services above, there are also logs for RabbitMQ, NGINX and the IMC.

Service Location
RabbitMQ $HOME/containers/is-rabbit/var/log/rabbitmq/
NGINX $HOME/containers/nginx/var/log/nginx/
IMC $HOME/containers/itemsense/var/log/impinj/

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 specifying:

  • 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.
  • 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.


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