Contents

Introduction



The ItemSense Management Console (IMC) is a graphical user interface (GUI) for Impinj ItemSense that runs on the ItemSense server and is accessed with a web browser. It allows you to:

  • complete the initial setup of ItemSense
  • define and configure the RAIN RFID readers
  • define zone maps, recipes, and jobs, which are required for an ItemSense data collection session
  • view the data results from a data collection session
  • monitor the health of the readers.
  • track the health of the host machine that runs ItemSense.

Supported Browsers

The following browsers are currently supported:

  • Latest Google Chrome
  • Latest Mozilla Firefox
  • Latest Apple Safari

Provision ItemSense for the First Time

Prerequisites

Before provisioning ItemSense for the first time:

  • Install an ItemSense server
  • Deploy RAIN RFID gateways
  • Configure the network

Connect to ItemSense

This procedure is required only once, the first time you access ItemSense.

To connect to ItemSense:

  1. Type http://<server IP>:3010 into the address line of a web browser and press Enter.
    The following dialog appears.

    Initial page after connecting to server displays Instance ID field and Regulatory Region field.

  2. Enter either your ItemSense UUID or your ItemSense ID.
    If you do not know either of these values, please contact support@impinj.com
  3. Select your Regulatory Region from the drop-down menu.

Click the SUBMIT button to continue.

Log In to ItemSense

The first time you connect to ItemSense through the IMC, your ItemSense instance will take a few seconds to register itself. Once this is complete, you can log in to ItemSense.

By default, the ItemSense server administrator has a username of admin with the password of admindefault.

Enter the username and password of the ItemSense server administrator, then click the LOG IN button.

The log in screen, with Username and Password fields, and a LOG IN button below.

Complete the Tour

After you log in for the first time, the IMC guides you through a six-step set-up tour for ItemSense.

The Welcome to the Tour Dialog with a Begin Tour button.

The tour walks you through the following steps:

  1. Change Admin Password (optional but recommended)
  2. Create a Facility
  3. Create a Scanner Configuration
  4. Discover Readers
  5. Register Readers

Dialog box for entering credentials of a reader.

The Tour Complete dialog indicates that the tour is complete and ItemSense has been provisioned.

Tour complete dialog. Text, This completes the tour. For more information please see the Impinj ItemSense documentation at platform.impinj.com.

Monitor Reader Health



The overall health of the reader is displayed as Healthy or Unhealthy, under Status on the Readers Definitions page.

ItemSense Reader Health

To view more detail, click on the Name of the reader.

Details include five status fields, which display a status of Healthy, Warning, or Failure:

In general, a status of Warning or Failure indicates the following:

  • Connection status: there is a problem with the health and monitoring channel between the reader and ItemSense
  • Throughput status: the reader is accumulating data faster than it can send data to ItemSense
  • Clock synchronization status: the reader cannot synchronize with its time provider (e.g. its NTP server)
  • Software status: the reader has received invalid input or has encountered either an internal configuration error or a software error
  • Hardware status: a low-level error has occurred on the reader

ItemSense Reader Health Categories

A category shows WARNING when a condition that affects reader health has occurred at a low enough frequency that it is not considered an error. A category shows FAILED when a condition that affects reader health has occurred at a higher frequency.

A status returns to healthy in the absence of conditions affecting reader health being reported to ItemSense.

Track Host Health



The IMC enables you to track and display the health of the host machine that is running ItemSense. To access this feature, from the navigation menu, click More | ItemSense Host Health.

More Menu with Host Health Option

The browser will navigate to a page that shows the current health state of the host machine and past health history. Four separate aspects of host health are tracked, as shown in the image below:

Host Health Annotated Page

  1. Current Host Server Health status badge: Healthy or Error. If the running average of the host system CPU Usage or Memory Available metrics exceed the configured limits, this status badge will display an Error state. The default limits are 95% for CPU usage and 1GB of available memory, over a 5-minute time window, but these values can be customized if needed.

  2. Most Recent Events list: a time-ordered list of significant host health events, with the most recent events at the top of the list. This list is updated whenever a significant event begins or ends. Some events are instantaneous (beginning and ending at the same time), but most have a duration, with different start and end times. Times are listed in UTC format. If an event has a start time but has not ended, the end time will be represented with dashes (“---“). Events are remembered from the time that the system was installed.

  3. CPU Usage chart: tracks system CPU usage within the last hour, measured as a percentage. The measured metric is system CPU usage, not just process CPU usage, so it is affected by any software running on the host, including ItemSense. The chart is updated every 10 seconds.

  4. Memory Available chart: tracks the amount of host memory available within the last hour, measured in megabytes. This available memory is shared by all software running on the host, including ItemSense. The chart is updated every 10 seconds.

Error Events

When one or both of the measured system metrics exceed the prescribed limits over the specified time window (5 minutes by default), the Host Server Health badge will change to an Error state and a new event will be added to the Most Recent Events list, as shown in the following diagram:

Host Health Error Condition Start

The event will be listed with a start time, but the end time will be displayed as dashes (“---“) to indicate that the event is still in effect.

As metric values are continually sampled and added to the running average, the average may fall below the prescribed limit. If this happens, the error state is terminated, and a new event will be added to indicate both the start and end times for the error state. If there are no other error states in progress, the Host Server Health badge will return to the Healthy indication.

Host Health Error Condition End

Customizing Error State Limits

The default error state limits are 95% system CPU Usage and 1GB of Memory Available, measured over a default time window of 5 minutes for both. These values should be effective for installations that are running on the recommended server hardware configurations, but they can be customized if needed.

Host Health limits can be set in the config.yml file that is stored on disk under the installation directory:

[installation directory]/impinj/itemsense/[version]/containers/is-health/config/config.yml

The file is text-based and provides several settings to the service that monitors system health on the host. There are four fields involved in setting the error limits, as shown in the following image:

Host Health Configuration File

To update the health warning limits on the host:

  1. Stop any currently running jobs
  2. Navigate to the configuration file location, [installation directory]/impinj/itemsense/[version]/containers/is-health/config/config.yml
  3. Make the file writable: sudo chmod 666 config.yml
  4. Open the file in your editor of choice
  5. Optionally change the value for cpu:max:, using integer values from 1-100
  6. Optionally change the value for cpu:duration:max, using ISO 8601 duration format
  7. Optionally change the value for memory:free:min, using integer values for megabytes
  8. Optionally change the value for memory:free:duration:max, using ISO 8601 duration format
  9. Save the file changes
  10. Navigate to the base ItemSense installation directory
  11. Bring down and then bring up all ItemSense services: sudo docker-compose -f itemsense-prod-3.yml down sudo docker-compose -f itemsense-prod-3.yml up -d

Re-register Readers



It may be necessary to re-register a reader if the reader loses contact with ItemSense. Re-registering a reader can also be done as a troubleshooting step if the reader in question is displaying a bad health status that has not resolved for some time.

To re-register a reader:

  1. From the landing page, click the Registration tab.
  2. Click either the Choose Networks or the Enter Hostname or IP Lists button.
  3. Either select the network(s) you want OR enter the IP or Hostname.
  4. Click the DISCOVER READERS button.
  5. Select the desired readers and click the REGISTER SELECTED READERS button.

    Reader re-registration

Selected Readers

After the reader is re-registered, it may take up to ten minutes for the reader to show up as healthy on the IMC and health API endpoints. This is because ItemSense must see the reader in a healthy state for a certain period of time before the reader can be considered fully healthy again.

Administration



To perform administration tasks, click More on the navigation bar at the top of the page, then click Admin Panel.

Administration

A panel will be displayed with options for resetting ItemSense, network scanner configuration, and software management.

Administration Panel

Update Reader Firmware

  1. On the Admin Home page, click the Software Management icon or tab. Click the Start New Update button to access the Update Software page.
  2. In the Image Type field, select either Reader Firmware or ItemSense Agent.
  3. In the Max Parallel Readers field (optional), enter the maximum number of readers that can upgrade in parallel. This defaults to 10 if left blank. The Version field upgrades automatically according to Image Type selected.
  4. Under Select Readers To Update, click the arrow to the right side of a facility name to view a list of all readers within a particular facility. For each facility, check the box to the left of each reader that you want to update.
  5. Click the Submit button to start the update process.

Software Update Select Readers In Facilty

Reset Configuration and Data

On the Admin Home page, click on the Reset ItemSense icon or tab. On that tab there are buttons to Clear Item Data and Factory Reset.

Factory Reset

After the factory reset completes, the browser window returns to the ItemSense provisioning flow. The ItemSense Instance ID and Regulatory region are required at that point.

Restarting Readers



To restart a reader, navigate to the "Reader | Definitions" tab and click the Restart button for each reader you want restarted. The Restart button is also visible on the individual Reader Definition Summary page.

Regulatory Regions



ItemSense supports the following regulatory regions:

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

The region is configured at installation time.

When a new reader configuration is added, the management console validates that the configuration is valid for the configured region.

The following configuration reader configuration elements vary by region:

Configurable Channel Frequencies

In EU1 and EU2 regions only, individual channel frequencies can be configured. The following channels can be enabled, as well as their hopping sequence.

Channel EU1 EU2
1 865.7MHz 916.3 MHz
2 866.3MHz 917.5 MHz
3 866.9MHz 918.7 MHz
4 867.5MHz NA

Reader Modes

In FCC regions, AUTOSET_DENSEREADER_TWO mode is not available.

In EU1, Japan and China regions, MAX_MILLER mode is not available.

Maximum Antenna Power

*In China, the maximum antenna power is 32.5dBm. *In EU1, the maximum antenna power is 31.5dBm. *In EU2, the maximum antenna power is 33.5dBm. *In FCC, the maximum antenna power is 32.5dBm. *In Japan, the maximum antenna power is 30dBm. *In Singapore, the maximum antenna power is 32.5dBm.

Visualization

Threshold Monitoring

Threshold monitoring visualization can be used to configure and tune threshold transition configuration.

You can view live item transitions, and tune the configuration to verify that the correct data is being produced by ItemSense.

Live Transition Data

This data can be filtered by EPC prefix, observation start and end time, and the transition direction.

Live Transition Filtering

There are two different levels of aggregation of this data:

*Transitions from all thresholds associated with a specific running job *Transitions from a single threshold

Transitions From All Thresholds Associated With a Specific Running Job

  1. Navigate to the Jobs` tab in the top navigation bar
  2. Locate the specific job of interest under Active Jobs
  3. Click on the icon circled below to navigate to live transitions for that job

Job Transition Navigation

Transitions From a Single Threshold

  1. Navigate to the Thresholds tab.
  2. Locate the threshold of interest
  3. If the threshold is running a job, click on the icon circled below to navigate to the live transition for that threshold


Threshold Transition Navigation