Impinj® ItemSense™ Reference Guide

Table of Contents

Introduction

This guide serves as reference manual for configuring the features of ItemSense, once all of its concepts and components are understood. It describes each configurable parameter and element and provides guidance on how and when to use them.

It should be used in conjunction with the API guide. When configuring a section of ItemSense, the work flow is:

  1. Navigate to the appropriate section in the API Guide.
  2. Read the description of the parameters which need to be set including what values they can be set to.
  3. Navigate to the appropriate section in the this document to provide guidance an when certain values should be used.

The ItemSense API is currently the most comprehensive method of getting access to the underlying configurable parameters of ItemSense at the beginning of each configuration section there is a table which specifies whether the configurable parameter can be accessed via the API, the IMC, or both.

Users and Roles

In ItemSense 'users' can be set up to control access and control the tasks a user can perform within the system. This is done by assigning each user a 'role'.Users can be managed both through the IMC and the API. Only users with the 'Admin' role can administer other users. This is the reason ItemSense is initially provisioned with one user:

Username: admin
Password: admindefault

Once ItemSense has been logged into for the first time (via the IMC or the API), this password should be changed to something more secure. Note: ItemSense does not force a password change but nevertheless, it is strongly recommended.

Roles

ItemSense provides a number of roles to partition access to various parts of the of the system. These are describe in the table below:

Role Description
Admin An Admin user has complete access to the system including administering other users.
DataReader A user with this role only has access to the 'items' and 'message queues' API endpoints and equivalent IMC screens
JobRunner A user with this role only has access to the 'jobs' API endpoints and IMC screens.
ConfigManager A user with this role only has access to the configuration API endpoints and IMC screens. This includes reader definitions, reader configuration and recipe configuration.

It is possible to give a single user more than one role but giving a user all the individual roles is not the same as giving them the "Admin" role. There are some actions within ItemSense which can only be done by a user with the "Admin" role. For example, accessing the IMC or administering new users can only be done by an Admin user.

To find out what sections of ItemSense a user has access to please read the API Documentation.

Authentication

Authentication is the "who is this user?" of user management. To ascertain this, the IMC requires that a user enter a valid username and password before being granted access to the rest of the management console.

To authenticate a user via the API, there are two methods which can be used:

  • HTTP Basic Authentication - This can be used with a previously set up username and password. If used with plain HTTP, HTTP Basic Authentication is inherently insecure as the username and the password are passed over wire as plain text (which has been base64 encoded). As such, this should only be used when communicating with ItemSense from within a secured network. Otherwise, HTTPS is preferred.

    In HTTP Basic Authentication the username and password is passed in one of the HTTP Header fields. This field is 'Authorization'. Its value is constructed by specifying the authorization method and a space which in this case would look like "Basic ". This is then put before the base64 encoded string of the username and password combined with a colon.

    For Example, if the default admin username and password from above is used, the final HTTP header field would look like:

    Authorization: Basic YWRtaW46YWRtaW5kZWZhdWx0

  • Token Based Authentication - ItemSense provides the ability to associate a token to a user. A token is a Universally Unique Identifier (UUID) which, when associated to the user, can be used to represent both the username and the password when authenticating. This method of authentication is only used via the API. Token based authentication is done in a similar way to 'Basic' authentication except that the value of 'Authorization' header field is the string "Token " followed by the generated token. Example:

    Authorization: Token 8fa61016-7531-4f07-a2ab-9b7046a1bbc9

Generate a Token

Tokens can be generated in one of 2 ways; either via the API or via the IMC. Using these methods it is possible to generate tokens for any user if the correct username and password of the user for which the token is being generated, is also specified.

Via the IMC, token generation is done as follows:

  1. Click on the 3 vertical dots button.
  2. Navigate to: admin -> API Keys.
    Note: the IMC name for a "Token" is "API Key".
  3. Select the username from the dropdown list.
  4. If necessary, enter the password for that user.
  5. Click on the "Generate API Key" button.

Currently, only the generation of API keys can be done via the IMC.

Via the API: it is possible to:

  • Generate tokens for a user.
  • Revoke token(s) for a user.
  • List all tokens for a user.
  • Find out which user a token is associated to.

For a full description of the API interface please refer to the API guide.

Authorization

Authorization is the "what is the user allowed to do?" of user management. In itemSense this implemented via roles.

Zone Maps

ItemSense has the concept of zones, as described in chapter 1 in the zones section. The zoneMaps endpoint (or "zone maps" section in the IMC) provides the ability to create geographic zones (that is zones which use the XY location of a tag to determine which zone a tag is in). Within ItemSense all geographic zones are part of a "zone map".

Zone maps provide a way of grouping zones together into a single collection. This collection is then associated to a facility. Only one zone map can be applied to a facility at any given time. To apply a zone map to a facility, it has to be made the "current" zone map on the facility. This can be done via the currentZoneMap API endpoint and in the IMC. Once current, a zoneMap's zones are the reported during location jobs.

Having multiple zones on a single facility allows for the possible of having different zones be active (or "current") at different times. For example, a zoneMap may be applied to a facility but if for some reason a new zone map needs to be applied to the facility, the new zone map can be created independently of the current one and made current at a prescribed time to test it's effectiveness. If the preference is for the original zone map, the original can just be made the current zone map on the facility again.

Create a zone map:

Config Name via IMC via API
name Yes Yes
facility Yes Yes
zones Yes Yes

name

A name for the zone map. This should be set to something describing what the collection of zones is for.

facility

This is the name of an existing facility the zone map should be associated with. Therefore, the target facility must be created before a zone can be created.

zones

This is the collection of zones that define the geographic coordinates for each zone in the monitored space.

A zone has:

Config Name via IMC via API
name Yes Yes
floor Yes Yes
points Yes Yes

Name - This is the name applied to the zone. It is the string that will be added to a tag report when ItemSense detects that a tag is in this zone. Therefore, consideration has to be given to what zone name will be meaningful to an upstream system but also fit the character rules ItemSense has defined. Zone names can contain:

  • Any character in the range a-z, capital or lower case
  • Any number 0-9z
  • One or more of the following characters: * _ : -

Note that spaces are not allowed in the zone name.

Floor - As a facility can have multiple floors, it is necessary to specify which floor a zone is on. This name should aligned with the floor name applied to the reader definitions on the same floor.

Points - This is a collection of XY coordinates which define the points of a the polygon which represents the zone. On each floor an origin point is selected and the xArray gateway placement values (in the readerDefinition) are specified based on the xArray's relative position to that origin point. The same consideration must be given to the points of the zone. In a zone, the X and Y values must be specified. It is possible to specify the Z value but as this isn't actually used by ItemSense it isn't mandatory (and can't be specified via the IMC, only the API). All points are in meters.

A zone must have 3 or more points and be specifed in a circular way i.e. either in a clockwise or anti-clockwise way. For example:

  • This square is good: (10,5), (5,5), (5,0), (10,0)

  • This is bad: (10,5), (10,0), (5,5), (5,0)

With the bad example, ItemSense will use the first 3 points to create a triangle and see the last point as an outlier. It will then raise an error stating that this isn't a valid polygon.

Note: Zone definitions cannot overlap unless they are on different floors.

Reader Definition

The reader definitions tell ItemSense about the readers it can connect with. There is one reader definition for each reader. To be able to connect with a reader, ItemSense first needs to know what type of reader it is and its IP address. A reader definition also allows for the placement of the reader within a facility based on cardinal X Y coordinates. One facility can have many readers defined within it but a single reader can only be defined within one facility.

Config Name via IMC via API
Name Yes Yes
Address Yes Yes
Type Yes Yes
Reader Zone Yes Yes
Antenna Zone Yes Yes
facility Yes Yes
Placement - X position Yes Yes
Placement - Y position Yes Yes
Placement - Z position Yes Yes
Placement - Yaw position Yes Yes
Placement - Pitch position No Yes
Placement - Roll position No Yes
Placement - Floor Yes Yes

Name

This is the name of the reader definition and is used to identify a single reader definition entity. The name of the reader can be anything meaningful but it is common just to name the definition the same as the reader itself. E.g. "Speedwayr-11-A2-AB" or "Xarray-11-42-DD".

Address

This is the IPV4 ip address of the reader. This is set via DHCP and so is only known when the reader is attached to the network. To find the IP address of the reader, connect to the same network the reader (or a network with active routes defined to the reader network) and run the 'ping' command with the reader name.

The reader name can be intuited by taking the reader name followed by the 4th, 5th and 6th octets of the reader's MAC address all separated by dashes ('-'). The MAC address of the reader can usually be found on reader itself. It will look similar to the following:

00:16:25:11:34:AF

The 4th, 5th and 6th octets have been highlighted.

The reader name format is as follows:

readername-4th-5th-6th

Examples of this would be:

speedwayr-11-a2-ab

Or:

xarray-11-42-dd

An example of the final ping command would be:

$ ping speedwayr-11-a2-ab
PING speedwayr-11-a2-ab.impinj.com (10.200.25.34): 56 data bytes
64 bytes from 10.200.25.34: icmp_seq=0 ttl=63 time=0.358 ms
64 bytes from 10.200.25.34: icmp_seq=1 ttl=63 time=0.424 ms

From this it can be seen that a reader has responded to the ping command and has the IP address of 10.200.25.34.

Type

ItemSense allows the type of reader to by defined. Currently 4 types can be specified:

  • XARRAY
  • XPORTAL
  • SPEEDWAY
  • XSPAN
  • UNKNOWN - This, as an option, is only selectable via the API interface. However, in the IMC it is possible to not select any type which is the effectively the same thing.

Currently, the 'type' parameter is only used to help qualify data. For example, antenna zones can only be defined on SPEEDWAY or XPORTAL reader types. Similarly, ItemSense will only calculate XY coordinates of tags when XARRAY is selected as the reader type.

Reader Zone

This parameter is optional. When not specified, ItemSense will set this value to be the same as the name parameter defined on the reader definition.

The value provided here is used during an Inventory job as the zone name in a tag report. It is reported when a tag was read by a reader's antenna on which no Antenna Zones have been defined.

Antenna Zone

This is the name reported by the reader in tag report whenever a particular antenna reads a tag. Each antenna can be given a different name and names can be shared across antennas.

Antenna zones are defined by specifying an antenna number and the zone name to attach to it. The antenna number is an integer while the antenna name is a string. If a tag is read by an antenna which doesn't have a zone name assigned to it then the Reader Zone name shall be listed in the tag report instead.

The following is an example tag report which is received when either querying for the item history via the API or when listening to a queue. In this example, ItemSense has a reader defined with 2 antennas attached to it. The reader has been given the Reader Zone name of "readerZoneName" and one of the antennas has been given the name "antennaRight":

{
  "epc": "200011606000020573A2749E",
  "tagId": "000000000000",
  "fromZone": "readerZoneName",
  "fromFloor": null,
  "toZone": "antennaRight",
  "toFloor": null,
  "fromFacility": "DEFAULT",
  "toFacility": "DEFAULT",
  "fromX": 0,
  "fromY": 0,
  "toX": null,
  "toY": null,
  "observationTime": "2016-09-07T00:00:02.148Z[Etc/UTC]"
}

This event shows that a tag has moved from the antenna which didn't have a zone name assigned to it which means the "fromZone" field is listed as "readerZoneName", and then moved to be read by the antenna which has the name "antennaRight" assigned to it.

Facility

This parameter is used to specify an existing facility for the reader to be part of. Via the IMC, this parameter doesn't need to be specified as it's selected at the top of the reader definition page and is applied to all definitions on that page.

Placement

The paramenters for placement are:

  • x - distance in meters from the origin point along the x axis.
  • y - the distance in meters from the origin point along the y axis.
  • z - the difference, in meters, between the height of the reader and the average height of the tags from the floor.
  • yaw - The angle, in degrees, that the xArray is rotated about its Z axis.
  • pitch - The angle, in degrees, that the xArray is tilted about its X axis.
  • roll - The angle, in degrees, that the xArray is tilted about the Y axis.
  • floor - The name of the floor on which the reader is placed. This name could be just numeric characters.

These 7 parameters can be logically split into 4 sub sets.

The first set (the X and Y parameters) is for telling ItemSense where an xArray is positioned on a floor relative to an origin point. All xArrays on a floor must be position relative to the same origin point otherwise location accuracy will be severely hampered.

The second set actually only contains one parameter; the Z value. To find the average height of the tags be read by the xArray, the use case should be considered. If a retail shop floor is being monitored, the height of the tag as its hanging on a rack should be measured. If the use case is to track patient movements around a hospital, the height of the tag should be the distance from an average height patient's wrist to the floor. Note that is is possible for different xArrays to have different Z values but only one may be specified per xArray.

The third set (the yaw, pitch and roll) concerns the orientation of the xArray. It is possible that not all xArrays in a facility face the same direction when this happens it is necessary pick one xArray to set the direction of the positive Y axis. This will correspond to the side of the xArray on which the lights are placed. From here all the other xArrays should be oriented. If a second xArray is a quarter turn anti-clockwise, this should be set as -90 (when looking down from above) and so on. The pitch and roll are for use cases where the xArray isn't mount above and parallel to a floor.

The following picture gives a few more examples on how to position the X, Y and Yaw values. These yaw value examples are from the perspective of looking down at the floor from above.

A sequence diagram to show how Reader Agent registration works.

The forth set actually only contains one parameter; the floor name. This name is used in a few places:

  1. It is used in the tag report as the name of floor on which the tag was read.
  2. The name here should match the name specified in a Zone Map when the reader is on the same floor to which the Zone Map applies.
  3. During tag data aggregation for location calculations. If an xArray is on a different floor to a tag, the reads from that xArray are not used in the tag location calculation.

This placement information is critical for allowing ItemSense to calculate the location relative to the same origin point as tags read by other xArrays in a facility.

Note: This parameter can't be defined on a Speedway reader as this is the only reader which can have antennas on different floors.

Facilities Management

As mentioned in the Concepts chapter, a facility is analogous to a physical building. A facility has to be defined in ItemSense before any readers can be defined. This is the reason the ItemSense Management Console the user the option to ensure that at least one facility has been defined on initial set up. If the user chooses not to create their own facility then ItemSense will use the facility name "DEFAULT" for all readers.

Readers cannot be moved directly from one facility to another. If a reader needs to be moved to another facility then it first must be deleted from its initial facility and then re-added to the new facility.

In the IMC, facilities are managed under the "facilities" tab.

Reader Configuration

The reader configuration defines how a reader will be utilized when running a job. In ItemSense reader configurations are independent entities from reader definitions which are both managed and stored separately. They are applied to a reader via a recipe. There are a set of common properties which can be set in a reader configuration definition but also, to simplify configuring the reader for a particular job, some properties change depending on the operation this the reader configuration definition is for.

The configurable properties are:

Common

Config Name Set via IMC Set via API
Name Yes Yes
Operation Yes Yes
Reader Mode Yes Yes
Transmit Power Yes Yes
Filter Yes Yes
Session Yes Yes

Inventory Specific

Config Name Set via IMC Set via API
Search Mode Yes Yes
Tag Population Estimate Yes Yes
Polarization Yes Yes
Antennas Yes Yes
Channel Config Yes Yes

Location Specific

Config Name Set via IMC Set via API
Disabled Antennas Yes Yes

Name

This is the name of the reader configuration definition and is used to identify a single reader configuration entity. It is a good practice to specify the intent of the particular configuration definition. For example, "Inventory-Dense-Speedway". This conveys that the configuration profile is intended to perform an inventory job, in a dense reader environment and is for the Speedway reader.

Operation

This is the operational mode of the reader. It has the following options:

  • INVENTORY - Configure the reader for an Inventory job. This is used for both standard inventory as well as real-time presence detection.
  • LOCATION - Configure the reader for an Location job. When selected, this will change the parameters which can be modified within the reader configuration definition. This is because performing a Location job requires certain reader configuration settings to always be set so to simplify this the reader definition
  • DO_NOTHING - disable the reader

Reader Mode

There are many parameters which can be set in an RAIN compliant reader in order to optimize throughput; these can include: data rates, modulation type (both reader-to-tag and tag-to-reader), bit encoding, pulse widths and other air protocol particulars. In fact there are over 128 combinations of settings on a typical RAIN RFID reader when all the variables factored in. It is for this reason that a number of predefined reader modes have already been defined. These cover almost all reading scenarios.

A couple of points are important to note regarding reader mode settings:

  1. Not all modes are available on all models or in all regions.
  2. As a rule, there is an inverse relationship between data rate and sensitivity/interference tolerance. Higher data rates generate, and are more susceptible to, interference whereas lower data rates cause less interference and are more tolerant of it.
Reader Mode Data Rate Positive Negative
MAX_THROUGHPUT 640 kbps (FCC), 436kbps (ETSI), using FM0 encoding Highest data rate. Prone to collisions. Lowest sensitivity.
HYBRID 320kbps (FCC), 218kpbs (ETSI), using Miller subcarrier=2
DENSE_READER_M4 68.5kbps (FCC), 80kpbs (ETSI), using Miller subcarrier=4 Good for when there are a large number of readers in an environment.
DENSE_READER_M8 21.33kbps (FCC), 80kpbs (ETSI), using Miller subcarrier=8 Most immune to interference (from other readers or elsewhere). Best sensitivity. Lowest data rate.
MAX_MILLER Data rates: 160kbps (FCC), using Miller subcarrier=4 Good compromise of speed and sensitivity. Usually the default setting on most readers.
DENSE_READER_M4_TWO Faster forward link than Mode 2 (only ETSI, China, India, Japan, Korea, and So. Africa)
AUTOSET_DENSE_READER (aka AutoPilot) Dynamically optimizes tag read and data rates based in the RF environment. Suited to a dense reader environments. Tags might be transient due to outlying tags being read in some modes over others.
MODE_1002 (aka AutoPilot Static) Dynamically optimizes tag read and data rates based in the RF environment. Good for finding the weakest tags. Tag population has to be relatively static.
MODE_1003 (aka AutoPilot Static Fast) Same as MODE_1002 except that it performs at a higher data rate. Tag population also has to be relatively static except that this mode is better suited to an RF environment which is known to be good.
MODE_1004 Same as MODE_1002 except that it favors reading weaker tags. Hence, this mode is better for more difficult RF environments. Slower than read rate than MODE_1002.

Note:

  • MAX_MILLER mode is not available in all regions.
  • A "dense" reader area is defined as more than half the available channels are predominantly occupied.
  • Due to the limited amount of available channels in certain regions (like ETSI for example), some regions only allow Dense reader modes.

The AutoPilot modes work by automatically changing the reader settings based on the number of readers (or RF interferers) in the environment. When the number of readers increases beyond a certain threshold the reader will switch from a non-Dense Reader Mode setting to a Dense Reader Mode setting.

For more information on how to set this parameter, please refer to the Performance Expectations chapter in the Gateway Deployment Guide on the support portal.

Transmit Power

This is the transmit power in dBm the reader should use when performing an operation. There are many factors to consider when selecting a transmit power. Common things to consider are:

  • Regulatory restrictions of the region the reader is operating in.
  • The gain of the antennas being used with the reader.
  • The cable loss between the reader and the antenna.
  • The area the reader needs to cover. If the field of view of the reader has to be tightly controlled so, for example, the reader doesn't read tags that it isn't required to, then this transmit power can be reduced.

The first step in deciding what to set the reader transmit power to is find out what maximum power is allowed according to regulatory body of the region. The first three bullets above are used when calculating this and are further explained below.

Regulatory Power Restrictions

Throughout the world there are different standards which regulate the use of RFID (and indeed, most wireless communications). The two most prominent regulations are FCC and ETSI. When selecting the transmit power it is important the the value selected produces a Radiated Power from the antenna which falls within the amount allowed by the regulatory commission of the operating area. The follow points should also be considered when calculating this. Regulations usually give Maximum Output Radiated Power in Watts (W). To convert this to dBm the following formula can be used:

dBm = 10 log (power in milliwatts)

For example, FCC specifies 4W as maximum allowed radiated power. To convert this to dBm:

4W = 4000mW = 10 log(4000) = 36 dBm

When calculating a maximum transmit power to set a reader at, it is important to note whether the regulatory maximum transmit power was specified in ERP (effective radiated power) or EIRP (effective isotropic radiated power). ERP is in reference to a dipole antenna whereas EIRP is in reference to an Isotropic antenna. An Isotropic antenna is a theoretical antenna which radiates energy equally in all directions (as a perfect sphere.)

Antenna Gain

The gain refers to how much the antenna focuses the RF beam emitted from the antenna and thus increasing the radiated power. The gain is normally given in dBi on an antenna datasheet which is the gain in reference to an Isotropic antenna. If the regulatory Maximum Output Radiated Power was specified in EIRP then the dBi value can be used when calculating the maximum reader output power. However, if the regulatory Maximum Output Radiated Power was specified in ERP, which references a dipole antenna, then the dBi value needs to be converted to dBd. This ensures like for like values are used when making a transmit power calculation. To do this the following formula can be used:

dBd = dBi - 2.15

Cable Loss

This is usually specified on the cable data sheet as loss in dB per meter.

Maximum Reader Output Power Example

The following formula can be used when calculating the maximum allowed reader output power by the regulatory body for a region:

Maximum Radiated Output Power (dBm EIP or dBm EIRP)
+
Cable Loss (dB)
-
Antenna Gain (dBi or dBd)
=
maximum allowed reader output power (dBm)

The following example is for calculating the maximum allowed reader output power in the ETSI region.

Attribute Unit Value
Maximum Radiated Output Power dBm ERP 33
Cable Loss for 4 meters of cable dB 4m x 0.5 dB/m = 2
Antenna Gain dBd 8 dBi - 2.15 = 6dBm (rounded)
maximum allowed reader output power dBm 29dBm

Transmit Power for xArrays

The above calculations are not necessary when using ItemSense with an xArray as the maximum power limits within each region are known to ItemSense. This allows ItemSense to prevent the selection of an incorrect power level for that region.

Antennas

A list of antennas which should be used by the reader for an operation. At least one antenna needs to be specified.

Filter

This field allows for specify a filter the reader should apply to the tags it inventories. A filter can be be placed on any value in any memory bank within the tag. To create a reader based filter three values need to be selected. These are the memory bank, pointer, and the tag mask. Only one filter can be set per reader configuration.

Memory Bank

Within a tag there is usually 4 memory banks (although the user memory bank is specified as optional in RAIN RFID standard). The following table shows how to reference a particular memory bank:

Memory Bank Number Memory Region Name
0 Reserved
1 EPC
2 TID
3 User

Pointer

This is a bit offset to the exact place in memory where the filter mask should start. For example, it is common to filter on an EPC but the EPC doesn't start at bit zero in the EPC memory bank. Before the EPC itself is the 16-bit CRC and the 16-bit PC. This means the the actual EPC starts on bit 32 so to filter on the EPC a pointer value of 32 (to skip bits 0-31) would be required.

Tag Mask

This is a hexadecimal string of characters which will be matched against specifoed position in TAG memory.

Session

The RAIN standard allows for up to four sessions (each with its own 'A' or 'B' state flag); these sessions serve two purposes:

  1. They determine how often a tag will respond to a "select 'A' state tag" query from the reader.
  2. They allow for multiple readers to conduct independent inventories.

The RAIN RFID reader will select which session is to be used within the tag, each of these tag session's inventory flags can be independently set to 'A' or 'B'. Each session has different tag persistence properties. Depending on the use case, one session type might be more applicable than the other.

The 4 sessions options are:

  • 0 - The inventoried flag is set to 'B' state but once it has left the field of view it will immediately revert back to the A state.
  • 1 - In Single Target mode with Session set to '1' the tag will be read and then moved to the 'B' state. After some period of time (which, as previously mentioned, is known as "persistence") the tag will revert back to the 'A' state and be read again. This is done even when the tag remains in the field of view of the reader. This persistence value is defined in the RAIN standard as being between 500ms and 5 seconds; again it cannot be expressly set, only approximated. The persistence value will vary depending on the tag IC (Integrated Circuit) manufacturer and even specific tag IC model. For example, the Impinj Monza S1 persistence is approximately 1 second. So, if we set the reader for Single Target Session 1, we will see a Monza tag being read around every second; if the tag uses a different IC it may be some other value between 500ms and 5 seconds.
  • 2 - The tag will be read once then switch to the 'B' state and remain quiet the entire time it is in the read field. This is because the reader, when in SINGLE_TARGET mode, will only select 'A' state tags. Once the tag leaves the read field, a RAIN RFID compliant tag will have a persistence time of a minimum of 2 seconds with no maximum defined. In reality, tags revert back to the 'A' state about 45 seconds to a minute after leaving the read field. However, as with session 1, this can vary across both IC manufacturer and model, and can't be user defined.
  • 3 - Same behavior as session 2.

Search Mode

This parameter specifies the type of RFID search mode the reader should use. To understand search modes it is important to understand the concepts of "states", "sessions" and "persistence". While this guide is not intended to be the definitive resource on how these work (as the EPC GEN 2 specification itself is best for that) it is important that these concepts are framed.

State

Each RAIN compliant tag has two states: 'A' and 'B'. The 'A' state is default when the tag powers up (or after the 'B' state times out). These states are essentially flags which when raised (i.e. when in 'B' state) indicates the tag has already been inventoried.

Persistence

Persistence pertains to how long a tag remains in the 'B' state. Once the RFID reader inventories a tag, the flag state in the tag is changed from 'A' to 'B' - how long the tag stays in the 'B' state before reverting back to the 'A' state is called "persistence". It is important to realize that exact persistence times cannot be set by the user; they can only be approximated according to the Search Mode and Session. Different sessions have a different persistence time. Please see the section on setting the "session" configuration parameter for more information.

Knowing the above key search mode concepts provides some context around the different search modes which can be selected. These are:

  • READER_SELECTED - This allows the reader to select the Search Mode depending on the session selected.
  • SINGLE_TARGET - The reader only selects all ‘A’ state tags then moves them all into the ‘B’ state (unless session 0 is selected). This allows tags to stay quiet once they are inventoried. This mode is good for high population, dynamic environments and high-throughput applications where a reduction in repeated tag observations is preferred. Persistence (and by extension, the session) is an important factor to consider when selecting SINGLE_TARGET. Used when performing deep stock inventory counts, where as many tags as possible need to be counted.
  • DUAL_TARGET - The reader selects all ‘A’ tags then moves all ‘A’ tags into ‘B’. Reader then selects all ‘B’ tags then moves them all back into the ‘A’ state. The process is then repeated. In other words, no tags are actually silenced because they are selected by the reader no matter what state they are in. Persistence, and so session type, is not a factor when using DUAL_TARGET mode. This mode is good for low to medium tag counts or low-throughput applications where repeated tag observation is preferred i.e. readers behaving as gateways or when determining the location of tags. This mode is always used for location use cases and for realtime tag presence detection. These modes require as many tag reads as possible to work so tags should never be silenced like there are when using SINGLE_TARGET.
  • TAG_FOCUS - This is also known as "single target with suppression" or "S1 boost". This is like SINGLE_TARGET with session 2 in that the tag will stay in the 'B' state while within the read field but once the tag has left the read field, it will have a persistence time like session 1. An example of a good use case for this mode would be when a population of tags is moved through a portal/dock door and then a short time later (less than 30 seconds) the same population of tags goes through another dock door and needs to be inventoried both times.

Tag Population Estimate

When a reader communicates with a single tag population it uses a special algorithm to communicate with each individual tag one by one. This process is call Singulation or "Slotted ALOHA". The "Tag Population Estimate" is the expected tag population within the field of view of the reader or gateway. It is used to give guidance to the singulation algorithm. Generally speaking, the better the tag population estimate, the more efficiently the singulation algorithm will run.

Polarization

This parameter is used internally by ItemSense. A user of ItemSense will see no affect from the setting of this parameter.

Antennas

This parameter is only available for Inventory reader configurations. It is an array of comma separated list of integers representing antenna IDs. This parameter gives the user the means to specify not just which antennas should be used by the reader or gateway during a job but also which order they should be used in.

For example:

38, 52, 46, 48

Specifying these 4 antenna IDs in the antenna parameter means that only these 4 antennas (of an xArray) will be used during a job. It also means that the xArray will enable these antennas in the specified order.

Under normal operation all antennas of a reader or gateway should be enabled. This will ensure maximum coverage of a given area. However, it certain scenarios it is necessary to disable certain antenna beams. This is normally done when:

  1. The gateway is placed near a reflective surface which is causing interface and multipath.
  2. There is an over-deployment of xArrays in a given area such that they cause interference with one another.

To find the optimal set of antennas which should be used in a given area requires experimentation and reasonable knowledge of RF and the factors which affect it.

A little bit of care has to be taken when setting this value. Most of the other values in the configuration profile are common across reader types (particularly for an Inventory reader configuration profile) so when setting them, little consideration has to be given to the reader the configuration is intended for. This is not the case for the antenna parameter. The listed antenna IDs cannot be greater than the number of antennas available on the reader.

For example the following antenna configuration will cause an error when it is applied to a standard Speedway reader (without an antenna hub attached):

1, 2, 3, 4, 5

This is because the Speedway reader doesn't support more than 4 antennas by default. Note that ItemSense 2016r6 doesn't support the optional antenna hub which can be attached to a Speedway reader to increase the number of antennas which may be attached to it to 32.

Channel Configuration

In some regions specific frequencies should be used by a reader. Other regions a frequency hopping spread spectrum (FHSS) is used to rapidly switch among frequency channels using a pseudorandom sequence every 200 milliseconds. This Channel Configuration section is never used in FHSS regions but provides control of the channels used in regions where channel management has to be considered.

Using the ETSI region as an example, there are a small amount of channels, less power and less bandwidth per channel when compared to the FCC region. If there are more than two active readers in close proximity careful consideration must be given to the design of the system. Which channels to use, separation of antennas, angle of antennas and how operation of the reader is triggered are all variables that can affect the effectiveness of the RAID RFID solution. To get the most out of the available channels some best practices can be applied:

  1. It is always best to use all four channels when possible. However, due to reader proximity, this is not always possible. In this situation, try to have readers which are in close proximity to each other all operate on different channels. See point 2. ETSI regulations permits transmitting on a single channel for a defined period of time; 4 seconds if tags are being read and only one second if no tags are being read. If these limits are breached then the reader must stop transmitting for a period of 100ms. The reader ensures it complies with the regulations automatically, therefore it’s important, where possible, to ensure more than one channel is selected.
  2. If there is more than one reader in close proximity that will be operating at the same time then use alternate output channels. This is often necessary when two readers are used to create a portal (i.e. two readers facing each other to monitor the space in between), when two dock door portals are in close proximity or when multiple xArrays are monitoring an overlapping floorspace.

An example of an alternate channel strategy would be having reader A use channels 1 and 3 (865.7 & 866.9 MHz), and reader B using channels 2 and 4 (866.3 & 867.5 MHz).

If this separation of channels is not designed into the system, When readers are actively transmitting, there is a 25% chance that each reader will be transmitting at the same time on the same channel; thereby increasing the chance of interference and with it the chance of not reading tags.

There are two parameters which help control the channels a reader will use; Channel Index and Tx Frequency in Mhz. Note that the parameters are mutually exclusive and both can not be set simultaneously.

Channel Index

For RFID readers operating in regions with fixed frequency regulatory requirements, the Channel Index is used to define a single frequency channel for the reader to operate in.

Low Level Reader Protocol (LLRP) has a frequency table that maps a channel number to list of available frequencies. The channel to frequency mapping for a region must be known to be able to correctly select the intended channel frequency.

For example, RAIN RFID readers for the ETSI region has the following list of available channels:

Channel Frequency
1 865.70 Mhz
2 866.30 Mhz
3 866.90 Mhz
4 867.40 Mhz

Using this parameter, only one channel may be selected for a reader.

Tx Frequencies in Mhz

To allow more than one frequency channel to be used, the txFrequenciesInMhz (reader as "Transmit Frequencies in MegaHertz") allows for the definition of a custom frequency hop table. The table can only include frequencies that are allowed by the reader’s region, but frequencies can be defined in any order including repeating and/or omitting frequencies. For example, based on the ETSI frequencies above, an ETSI frequency hop table might be defined as [865.7, 866.3, 866.9, 867.5], which will prompt the reader to only hop to these frequencies, in this order.

Or, to define the alternate channel strategy mentioned above:

  • Reader A: [865.7, 866.9]
  • Reader B: [866.3, 867.5]

Recipe Configuration

Recipes allow for the pairing of readers to previously defined reader configurations. That is, it allows the user to specify which reader configuration should to be mapped to an individual reader for a job. This means if a job is running which involves a number of readers, each requiring a different set of configuration (perhaps because there is a mix of Speedway, xPortal and xArrays), then all of the configuration to reader mappings can be specified and saved under one recipe. It is also possible to specify some of the ItemSense data aggregation settings via the recipe configuration. Once all the recipe has been set up it can be saved under a meaningful name.

The configurable properties are:

Common

Config Name Set via IMC Set via API
Name Yes Yes
Type Yes Yes
Reader Configuration Name Yes Yes
Reader Configurations Yes Yes
Reporting Interval Yes Yes
Compute Window Yes Yes
Tag Expiry Duration Yes Yes
Tag Heartbeat in Minutes No Yes
Tag Heartbeat Duration No Yes

Location

Config Name Set via IMC Set via API
Minimum Movement In Meters Yes Yes

Name

This is the name of the recipe which can be selected when running a job.

Type

This is the type of connection to the reader that ItemSense will use.

  • LOCATION - For use with readerConfigurations which have operation set to LOCATION.
  • INVENTORY - For use with readerConfigurations which have operation set to INVENTORY.

Reader Configuration Name

In the IMC this field is actually called "Default Configuration" due to this configuration being used if no other configuration is specified in via the "Reader Configurations" property.

If no default reader configuration should be applied to the readers then this value can be set to a "DO_NOTHING" reader configuration i.e. set to a reader configuration with the operation type set to "DO_NOTHING". If this is done, the Reader Configurations property must be used.

Reader Configurations

This is a list of reader definition to reader configuration mappings. Multiple mappings can be specified. In the IMC, there are dropdown lists which allow the user to select from the existing reader definitions and configurations. Via the API, a mapping is just a key value pair in JSON. The following is an example of the format:

"readerConfigurations": {
  "xArray-11-41-d9": "IMPINJ_Deep_Scan_Inventory",
  "SpeedwayR-11-A2-AB": "IMPINJ_Deep_Scan_Inventory_Spwy"
},

When specifying reader configuration mappings via the API, the key can either be the specific reader 'name' or a reader 'type'. This makes it possible, for example, to map a configuration to all readers of the same type.

"readerConfigurations": {
  "XARRAY": "IMPINJ_Deep_Scan_Inventory"
}

Reporting Interval

This parameter is the interval by which each reader agent will send its tag reports to ItemSense Core.

When the recipe type is set to INVENTORY, the reportingInterval has an added function. ItemSense will use all the tag data sent by the reader agents in a report to count the number of tag reads per antenna on the reader. ItemSense use tag counts per antenna to determine which antenna zone a tag is in. This means that the larger this value is set to, the great number of tag reads in a report and the better ItemSense is at determining which antenna zone a tag is in. The trade off is that the bigger the window the longer it will take for antenna zone transitions to occur.

Compute window

This parameter is used to specify a time in seconds over which tag reports should be aggregated.

When the recipe type is set to INVENTORY, the compute window isn't used.

When the recipe type is set to LOCATION, the compute window is the window over which to average the tag location data. In general, the larger the compute window, the more accurate the reported tag location will be. However, the larger compute window the longer the delay between a tag actually moving and the reported location for that tag. Generally speaking, the more movement the read tags are likely to do, the smaller the compute window should be. This will produce more frequent XY position updates for each tag. If the tags are likely to be still, a higher compute window can produce a more accurate tag location, although this location will be updated less frequently.

For more information about how the compute window works, please refer to the Gateway Deployment guide which can be found on the support website.

Minimum Movement in Meters

This parameter is only available when the recipe type is LOCATION.

ItemSense is able to calculate the difference in meters between each report XY tag location. The value of this parameter is the minimum distance a tag should move before it is reported.

Depending on the environment, the reported tag raw tag locations can change frequently. Even if the tag is static. This is known as jitter. The minimumMovementInMeters can be used to tell ItemSense to ignore jitter within a certain radius. This means only "significant", defined as any movement greater than this parameter value, movements are reported.

What value this parameter should be set to is based on the following considerations:

  • How "clean" the RF environment is. Environments with little RF noise can produce less tag location jitter. The smaller the jitter, the smaller this parameter can be set to.
  • The required location accuracy. If small movements need to be tracked and the RF environment allows for it, this parameter should be set to a smaller value.
  • When tags do move, by how much do they move? This parameter should always be less than that amount.

This parameter can be set to 0 which means that all calculated XY locations are stored and processed which can produce a large amount of tag data. Setting this parameter to 0 significantly reduces the number of tags which can be tracked simultaneously by an ItemSense instance. It is generally better practice to set minimumMovementInMeters to as large a value as the use case requirements can tolerate.