Introduction

This guide serves as reference manual for configuring the features of Impinj 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 Documentation. When configuring a section of Impinj 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 are assigned roles that control the user's access to the system. Users can be added and managed through both the IMC and the API. Only users in the Admin role can administer other users. ItemSense is initially provisioned with one user in the Admin role:

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. ItemSense does not force a password change, but it is strongly recommended.

The roles that ItemSense provides are described in the following table.

Role	Description
Admin	User has complete access to the system including administering other users.
DataReader	User has access to the items and the message queues API endpoints. However, both have been deprecated. For access to the the Broker/Event Publisher API endpoints that supersede them, use the ConfigManager role instead.
JobRunner	User has access to the jobs API endpoints.
ConfigManager	User has access to the configuration API endpoints. This includes reader definitions, reader configurations, and recipe configurations.

It is possible to assign a single user more than one role, but assigning a user all individual roles is not the same as assigning the Admin role. Some actions within ItemSense are allowed only by the Admin role. For information about what parts of ItemSense a user can access, see the API Documentation.

Authentication

Authentication confirms the identity of a user. It answers the question, who is this user. The IMC and the API use different authentication methods.

To authenticate a user, the IMC requires a user to 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 that can be used:

• HTTP basic authentication: This can be used with a previously set up username and password. HTTP basic authentication is inherently insecure as the username and the password are passed over the wire as plain text that is base64-encoded. As such, HTTP basic authentication should be used only when communicating with ItemSense from within a secured network. Otherwise, HTTPS is preferred. HTTP basic authentication is specified in HTTP Authentication: Basic and Digest Access Authentication.

  In HTTP basic authentication, the username and password are passed in the Authorization HTTP header field. Its value is constructed by specifying the authorization method followed by 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 administrator username and password are 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 is associated with the user to represent both the username and the password when authenticating. Token-based authentication is done in a similar way to basic authentication except that the value of the Authorization header field is the string "Token " followed by a JSON key value pair with string "token" as the key and the token as the value. For example:

        Authorization: Token {"token": "8fa61016-7531-4f07-a2ab-9b7046a1bbc9"}

Generate a Token

Tokens can be generated 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 are specified.

Via the IMC, token generation is done as follows:

1. Click on the three vertical dots in the upper right corner of the IMC.
2. Navigate to admin -> API Keys. The IMC name for a token is "API Key".
3. Select the username from the drop-down list.
4. If necessary, enter the password for that user.
5. Click on the Generate API Key button.

The generation of API keys is the only token-related task that 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.

A user is authenticated in an AMQP registration via HTTP basic authentication. The AMQP interface does not support token-based authentication.

Authorization

Authorization verifies the permissions that a user is granted. It answers the question, what is the user allowed to do. ItemSense uses roles to set the user's permissions.

Zones and Zone Maps

A zone is a two-dimensional area of space within a facility. A zone map is a grouping of the zones within 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. Once current, the zones in a zone map are reported during location jobs.

Having multiple zones in a single facility allows different zones to be active (or current) at different times. For example, if 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 its effectiveness. If the preference is for the original zone map, the original can just be made the current zone map on the facility again.

A zone map has the following properties:

Property	Set via IMC	Set 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 are in the zone map. Each zone is defined by a name, the floor, and a set of points.

A zone has the following properties:

Property	Set via IMC	Set 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 is added to a tag report when ItemSense detects that a tag is in this zone. A name that is meaningful to a downstream system should be used. Zone names can contain:

• Any character in the range a-z, uppercase or lowercase
• Any digit 0-9
• One or more of the following characters: * _ : -

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 X-Y 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. The Z value is not used by ItemSense. All points are in meters.

A zone is defined by three or more points, which must be specified in a circular way. In other words, the points must be specified either in a clockwise order or in a counterclockwise order. For example, to define a square:

• Valid definition: (3,0), (3,4), (11,4), (11,0)

• Invalid definition: (3,0), (3,4), (11,0), (11,4)

The following diagram shows how ItemSense interprets these definitions. Interpretation of the valid definition is shown on the left.

.

With the invalid definition, ItemSense uses the first three points to create a triangle and sees the last point as an outlier. It then raises an error stating that this isn't a valid polygon.

Zone definitions cannot overlap unless they are on different floors.

Reader Definition

The reader definition provides details about a reader that is connected to ItemSense. There is one reader definition for each reader. One facility can have many readers defined within it but a single reader can be defined in only one facility. In the typical ItemSense usage, a reader definition is created automatically by the reader discovery process initiated by the IMC; however, a reader definition can be added manually.

A reader definition has the following properties:

Property	Set via IMC	Set 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. For example, "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 reader network or connect to a network with active routes defined to the reader network. Once connected, run the ping command with the reader's name.

The reader's name can be intuited by taking the reader model followed by the 4th, 5th, and 6th octets of the reader's MAC address, each octet separated by dashes ('-'): readername-4th-5th-6th. The MAC address of the reader is found on the reader itself. It looks similar to the following:

00:16:25:11:34:AF

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

Examples of names: speedwayr-11-a2-ab and xarray-11-42-dd

An example of the ping command for the speedwayr reader:

$ 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

The ping response from this reader specifies the reader's IP address as 10.200.25.34.

Type

ItemSense allows the type of reader to by defined. There are four types: XARRAY, XPORTAL, SPEEDWAY, XSPAN, and UNKNOWN. The UNKNOWN type can be set only via the API interface. In the IMC, not selecting any type is equivalent to specifying the UNKNOWN type.

The type property is only used to help qualify data. For example, antenna zones can only be defined on SPEEDWAY or XPORTAL reader types. Similarly, ItemSense calculates only X-Y coordinates of tags when XARRAY is selected as the reader type.

Reader Zone

This parameter is optional. When not specified, ItemSense sets this value to be the same as the name property of the reader definition. The value of this property 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.

The following is an example tag report which is received either when querying for the item history via the API or when listening to a queue. In this example, ItemSense has a reader defined with two antennas attached to it:

{
  "epc": "200011606000020573A2749E",
  "tagId": "000000000000",
  "fromZone": *[READER_NAME]*,
  "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 specifies an existing facility for the reader. In the IMC, the facility that is selected at the top of the reader definition page applies to all definitions on that page.

Placement

The parameters 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 seven parameters can be logically split into four subsets.

The X and Y parameters indicate to ItemSense where an xArray is positioned on a floor relative to an origin point. All xArrays on a floor must be positioned relative to the same origin point, otherwise location accuracy will be severely hampered. The Z parameter specifies the average height of the tags to be read by the xArray. The manner in which the tag is used must be considered when specifying the average height. For example, if a retail shop floor is being monitored, the height of the tag as it is 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. It is possible for different xArrays to have different Z values but only one may be specified per xArray.

The third set (pitch, roll, and yaw) concerns the rotation of the xArray about the X, Y, and Z axes. It is possible that not all xArrays in a facility face the same direction. Therefore, it is necessary to pick one xArray to set the direction of the positive Y axis. This direction corresponds 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 counterclockwise, this should be set as -90 (when looking down from above) and so on. The pitch and roll are used when the xArray is not 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.

.

The fourth subset contains only one parameter; the floor name. This name is used in a few places:

• It is used in the tag report as the name of floor on which the tag was read.
• 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.
• 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.

Restrictions on reader definition parameter updates

When changing the reader's facility as part of a reader definition update, an internal consistency issue within ItemSense requires the name of the readerZone to change, as well as the names of any antennaZones.

When changing the reader's placement's floor as part of a reader definition update, the names of the readerZone and antennaZones must change. Furthermore, once a reader has a floor assigned to it, the floor cannot be removed (which occurs when the floor property is set to null, or the placement itself is set to null). It is permissible to change the floor to a different, non-null value.

ItemSense enforces the restrictions above. Calls to the associated API endpoint fail and the IMC prohibits (and displays an informative warning) when such configuration changes are attempted.

Facilities Management

A facility is analogous to a physical building. A facility must be defined in ItemSense before any readers can be defined. If the user chooses not to create a facility, ItemSense uses 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, 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

A reader configuration defines how a reader is utilized when running a job. Reader configurations are independent from reader definitions, which are managed and stored separately. A reader configuration is applied to a reader via a recipe. A reader configuration has common properties and operation-specific properties.

A reader configuration has the following common properties:

Property	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

The following properties apply to the INVENTORY operational mode:

Property	Set via IMC	Set via API
Search mode	Yes	Yes
Tag population estimate	Yes	Yes
Polarization	Yes	Yes
Antennas	Yes	Yes
Channel Configuration	Yes	Yes
RF Power Sweep Configuration	Yes	Yes

The following properties apply to the LOCATION operational mode:

Property	Set via IMC	Set via API
Disabled Antennas	Yes	Yes

The following properties that apply to the THRESHOLD operational mode:

Property	Set via IMC	Set via API
Search mode	Yes	Yes
Tag population estimate	Yes	Yes
Polarization	Yes	Yes
RF Power Sweep Configuration	Yes	Yes

Name

This is the name of the reader configuration. It is a good practice to specify the intent of the particular configuration definition. For example, "Inventory-Dense-Speedway". This conveys that the configuration is for an inventory job that uses a Speedway reader in a dense reader environment.

Operation

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

• INVENTORY: Use the reader to perform an inventory of tags. The inventory can be standard or real-time presence detection.
• LOCATION: Use the reader to determine the location of tags.
• THRESHOLD: Use the reader to detect movement of tags across a threshold.
• 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. There are over 128 combinations of settings on a typical RAIN RFID reader. Several reader modes have been predefined to cover almost all reading scenarios.

Reader Mode	Data Rate	Positive	Negative
MAX_THROUGHPUT	640 kbps (FCC), 436kbps (EU1), using FM0 encoding	Highest data rate.	Prone to collisions. Lowest sensitivity.
HYBRID	320kbps (FCC), 218kpbs (EU1), using Miller subcarrier=2
DENSE_READER_M4	68.5kbps (FCC), 80kpbs (EU1), using Miller subcarrier=4	Good for when there are a large number of readers in an environment.
DENSE_READER_M8	21.33kbps (FCC), 80kpbs (EU1), 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 EU1, China, India, Japan, Korea, South 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.

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

• Not all modes are available on all models or in all regions.
• There is an inverse relationship between data rate and sensitivity to interference. Higher data rates are more susceptible to interference whereas lower data rates are more tolerant of it.
• A dense reader area is defined as an area in which more than half the available channels are predominantly occupied.
• Some regions allow only dense reader modes because of the limited number of available channels in certain regions (EU1, for example).

The AutoPilot modes automatically change the reader settings based on the number of readers in the environment. When the number of readers increases beyond a certain limit, the reader switches from a non-dense reader mode to a dense reader mode.

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

Transmit Power

This is the power, in dBm, that radiates from the reader's antenna when performing an operation. Some common factors to consider when selecting the transmit power are:

• Regulatory restrictions of the region in which the reader is operating
• 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. For example, if the field of view of the reader has to be tightly controlled so that the reader doesn't read certain tags, the transmit power can be reduced.

The regulatory restrictions, antenna gain, and cable loss are further explained below.

Maximum Output Radiated Power

Throughout the world there are different standards which regulate the use of RFID. The two most prominent regulations are FCC and EU1. The selected value for transmit power must be within the range allowed by the regulatory commission of the operating area. Regulations usually state the maximum output radiated power in watts (W). To convert this to dBm, the following formula is 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

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 data sheet which is the gain in reference to an isotropic antenna. If the regulatory maximum output radiated power is specified as effective isotropic radiated power (EIRP), the dBi value is used when calculating the maximum reader output power. However, if the regulatory maximum output radiated power is specified as effective radiated power (ERP), which references a dipole antenna, the dBi value must be converted to dBd. To convert dBi to dBd, the following formula is used:

dBd = dBi - 2.15

Cable Loss

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

Calculation of Maximum Allowed Reader Output Power

The following formula is used to calculate the maximum Impinj Speedway reader output power allowed by a region's regulatory agency:

maximum allowed reader output power (dBm) = 
            cable loss (dB) - antenna gain (dBi or dBd)
            + maximum radiated output power (dBm EIP or dBm EIRP)

The following example shows the calculation of the maximum reader output power for the EU2 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

Maximum Transmit Power for Gateways

The Impinj Gateway's maximum transit power settings are different than those for the Impinj Speedway. Each Gateway has its own phased antenna array, and each antenna has a different gain, so the Gateway adjusts the power output to each antenna to maintain a consistent power transmission.

For this reason, Gateways do not accept a transmit power setting that is greater than 30dBm, regardless of region. However, each Gateway contains the setting of the maximum power transmission allowed by each region, so a 30dBm setting does not necessarily set the reader output power to 30dBm. Instead, it sets the the power to the maximum allowed output allowed by region, according to the Gateway's region setting.

So, for instance, the FCC allows a maximum transmission power of 32.5dBm; a 30dBm setting on a Gateway in that region translates to 32.5dBm, a 29dBm setting sets the Gateway transmission power to 31.5 dbm (one dBm less), and so on.

Disabled Antennas

A comma-separated list of integers representing antenna IDs of a reader. The antennas identified in this list are disabled.

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

A tag usually has four 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 that 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 is matched against the specified 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 responds to a "select 'A' state tag" query from the reader.
2. They allow for multiple readers to conduct independent inventories.

The RAIN RFID reader selects which session is to be used within the tag. The inventory flags in each tag session 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 four session options are:

• 0: The inventoried flag is set to 'B' state but once it has left the field of view it immediately reverts back to the A state.
• 1: In Single Target mode with Session set to '1' the tag is read and then moved to the 'B' state. After some period of time, which is known as persistence, the tag reverts 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 used for location use cases and for real-time 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.
• SINGLE_TARGET_BTOA: The reader selects tags in the 'A' state. This search mode is also known as "single target reset inventory". This mode is used when a set of tags is in the 'B' state, perhaps because of a previous inventory.
• DUAL_TARGET_WITH_BTOASELECT: This search mode is an optimized version of the DUAL_TARGET search mode. This mode is faster and, therefore, preferable over the DUAL_TARGET search mode. This mode is used for real-time presence detection.

Tag Population Estimate

This property is not used for normal operation and should not be set by the user.

Polarization

This property is not used for normal operation and should not be set by the user.

Antennas

This parameter is only available for Inventory reader configurations. It is a comma-separated list of integers representing antenna IDs of a reader. The order of the antenna IDs in the list determines the order in which the antennas are used during a job.

For example:

38, 52, 46, 48

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

• The gateway is placed near a reflective surface which is causing interference.
• 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 that should be used in a given area requires experimentation and reasonable knowledge of RF and the factors that 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 causes 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.

Channel Configuration

Due to regulatory requirements in some regions, a frequency hopping spread spectrum (FHSS) is used to rapidly switch among frequency channels, using a pseudorandom sequence every 200 milliseconds. In other regions, specific frequencies are required. This Channel Configuration section is never used in FHSS regions. It provides control of the specific channels used in regions where channel management has to be considered.

For example, the EU1 region restricts transmissions by permitting less power, fewer channels, and less bandwidth per channel than that granted the FCC region. Consequently, if two or more active readers are in close proximity, system design is crucial. The channels to use, the physical placement of antennas, and how the reader's operation 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. The EU1 regulations permit 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 is important, where possible, to ensure more than one channel is selected.

2. If there is more than one reader in close proximity that is operating at the same time, 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 and 866.9 MHz), and reader B using channels 2 and 4 (866.3 and 867.5 MHz).

If this separation of channels is not designed into the system, 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. Any interference affects a reader's ability to accurately read tags.

There are two parameters which help control the channels that a reader uses; 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 EU1 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 (read 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 EU1 frequencies above, an EU1 frequency hop table might be defined as [865.7, 866.3, 866.9, 867.5], which will prompt the reader to hop only 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]

RF Power Sweep

Use this parameter to configure Impinj-specific RF Power Sweep operation. When this parameter is present in either the INVENTORY or the THRESHOLD Reader Configuration, the reader performs each inventory operation - transitioning tags from one state to another (A to B or B to A) - at multiple power levels starting at or above the minimumPowerLevel, in increments of powerLevelStepSize, ending with the maximum power level specified by transmitPowerInDbm. For example, if the minimumPowerLevel is specified as 25.5 dBm and the transmitPowerInDbm is 30 dBm, with powerLevelStepSize set to 2 dBm, each inventory operation will be performed at power levels 26 dBm, 28 dBm, and 30 dBm, in that order. Note: This custom parameter requires expert knowledge and is intended for Impinj internal use only.

Minimum Power Level

The minimum power level that the RF Power Sweep will start at before incrementing. It must be specified in 0.25 dB increments and be less than the value of transmitPowerInDbm.

Power Level Step Size

The step size that the power will increment by when applying RF Power Sweep. It must be specified in 0.25 dB increments.

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.

A recipe configuration has the following common properties:

Property	Set via IMC	Set via API
Name	Yes	Yes
Type	Yes	Yes
Reader Configuration Name	Yes	Yes
Reader Configurations	Yes	Yes

The following properties apply to the INVENTORY operational mode:

Property	Set via IMC	Set via API
Reporting Interval	Yes	Yes
Compute Window	Yes	Yes
Tag Expiry	Yes	Yes
Tag Heartbeat Duration	Yes	Yes

The following properties apply to the LOCATION operational mode:

Property	Set via IMC	Set via API
Minimum Movement In Meters	Yes	Yes
Reporting Interval	Yes	Yes
Compute Window	Yes	Yes
Tag Expiry	Yes	Yes
Tag Heartbeat Duration	Yes	Yes

The following properties that apply to the THRESHOLD operational mode:

Property	Set via IMC	Set via API
Thresholds	Yes	Yes
Iteration data logging	Thresholds	Yes
Profile	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 reader configurations which have operation set to LOCATION.
• INVENTORY: For use with reader configurations which have operation set to INVENTORY.
• THRESHOLD: For use with reader configurations which have operation set to THRESHOLD.

Reader Configuration Name (Default Configuration)

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 (Configuration Mappings)

This is a list of reader definition to reader configuration mappings. Multiple mappings can be specified. In the IMC, there are drop-down 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 specifies the frequency, in seconds, with which the reader agent sends its tag reports to ItemSense Core.

When the recipe type is set to INVENTORY, the reportingInterval has an added function. ItemSense uses all 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 takes for antenna zone transitions to occur.

Compute window

This parameter is specifies the 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 the tag location data is averaged. If the compute window is larger, the tag's reported location is more accurate. However, the reporting of a tag's location is delayed by a larger compute window. The more movement the tags are likely to do, the smaller the compute window should be. More movement produces more frequent XY position updates for each tag. If the tags are likely to be still, a larger compute window can produce more accurately reported tag locations, although the locations are 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.

Tag Expiry

A string representing the interval between the time that the tag was last detected and the time that the tag was marked absent.

Tag Heartbeat Duration

A string representing the interval between heartbeat updates. This value controls how frequently the lastModifiedTime of a tag is updated when the tag is read but has not moved.

Thresholds

A list of integers, each of which identifies a threshold to be used in the recipe. If this value is omitted, empty, or null, all thresholds in the facility are used.

Iteration Data Logging

Boolean value that enables or disables the logging of iteration data for use in tuning. The default is disabled (false).

Profile

Encrypted data specifying system behavior. This property must not be set without guidance from Impinj. When a recipe is created, ItemSense uses a default value.