Contents

This document describes the installation process for Impinj ItemSense. Impinj ItemSense 2018r1 software is provided in a setup package file with a name similar to itemsense-0.1.XXX-setup.run Beginning with ItemSense-2.0.3, the setup package file name will be similar to itemsense-2.0.3+XXX-setup.run.

Earlier versions of ItemSense, including ItemSense 2017r1, were provided in an archive file format with a name similar to is.IT-BTIC-BUT.0.1.XXX.tar.bz2. Where the process differs, there are links referring to the Legacy Installation Guide.

Introduction

The Impinj ItemSense software is provided in a setup package for customers who are installing the software within their company-managed network. The package contains a number of files, but the primary components are delivered as a series of docker containers.

The following section describes the process for installing ItemSense using the setup package.

Installation Prerequisites

Before starting the ItemSense installation process, the following steps must be completed:

  • Obtain an ItemSense Instance ID from your Impinj representative.
  • Download the ItemSense setup package from the link in the welcome email.
  • Install the following software on the server where ItemSense will be installed:
    • Linux operating system with ONLY these specific versions:
    • Ubuntu version 16.04 or version 18.04, with the latest kernel version for that distribution
    • Centos version 7 with the latest kernel version for that distribution
    • Docker, version 18.09.2 or later
    • Docker Compose, version 1.23.2 or later
  • Ensure that all of the RAIN RFID readers are configured with an NTP server. See Clock Synchronization and NTP Configuration for more details.
  • Ensure that the user installing ItemSense is a valid Linux user. Make a note of this user's login name and password as you will need it for most support-related procedures.
  • The setup package will require approximately 3GB of temporary space to extract the compressed images. Ensure that the target directory has at least this amount of free space available.
  • Ensure that the host has the required ItemSense ports open. See Requirements for more details.
  • If you are installing ItemSense 2018r2 or earlier, please be aware that the aufs storage driver configured by default on some Docker releases has been observed to cause failures under load. The newer overlay2 storage driver is recommended. To check which Docker storage driver you have, execute the "docker info" command. If the reported value for "Storage Driver" is "aufs", you must first uninstall any previous version of ItemSense, if it exists, then uninstall Docker and reinstall with the "overlay2" driver option. (If necessary, your configuration for a previous version of ItemSense can be exported and then imported into the new setup.) For more information about Docker storage drivers and storage driver configuration, please refer to the online documentation at the Docker website.

Install ItemSense

Pre-checks

Run the following commands in a terminal on the target server to confirm if the server is in the correct state to begin installation:

  1. Check that nothing is listening on port 80, 3010, 443 or 5672.

    For example, this command should not show any output:

          sudo ss -tlnp | grep ':80\W\\|:3010\W\\|:443\W\\|:5672\W'

  2. If this is a clean install and not an upgrade from an earlier ItemSense version, check that no previous docker images already exist.

          sudo docker images

    If this command shows that some ItemSense docker images already exist, follow the Uninstall Itemsense Via Automated Process or the Uninstall Itemsense Via Manual Process instructions below to remove them.

  3. Check that docker is installed and is at the version specified in Installation Prerequisites:

          docker -v

    Example output:

          Docker version 18.09.2, build 23cf638

  4. Check that docker-compose is installed and is at the version specified in Installation Prerequisites:

          docker-compose -v

    Example output:

          docker-compose version 1.23.2, build c7bdf9e

  5. Check that there is at least 8GB of available disk space:

          df -h ~

    Details:

    • The setup package itself will require 500MB of space. This package can potentially be removed once the installation is complete
    • The setup package will require approximately 1GB of temporary space to extract the compressed images. This space will be reclaimed automatically at the end of the installation
    • The initial installation consumes approximately 1.5GB of space but will grow over time as ItemSense data and logs are written to disk

    See our Resource Requirements Guide for more information about System Requirements.

Installation Instructions

To install ItemSense-2.1.0, you will need to have already downloaded the setup package. This file will be named similar to the following: itemsense-2.1.0+XXX-setup.run

When the setup package file has been obtained:

  1. Copy the file to the target server. The following is an example of copying the file from a Linux host to the target server.

          scp itemsense-2.1.0+XXX-setup.run USERNAME@TARGET_SERVER:.

    Where: USERNAME is replaced with the user on the target server. TARGET_SERVER is replaced with the hostname or IP address of the server on which you intend to install ItemSense.

  2. When the file transfer to the target server is complete, log on to the target server and navigate to the location where you placed the file. If you followed the command above, the file will be in the home directory of the user used to transfer the file on to the target server.

  3. Make the setup package file executable with the following command:

          chmod +x itemsense-2.1.0+XXX-setup.run

  4. From the same directory as the ItemSense setup package, run the setup package with the argument "install".

          sudo ./itemsense-2.1.0+XXX-setup.run install

    As of ItemSense 2.1.0, Impinj provides the option to choose the location at which ItemSense is installed. At the start of the Installation, you will be prompted to:

    • Press enter to accept the default directory provided by ItemSense
    • Provide an absolute path to the directory in which you will install ItemSense
    • Type "exit" to quit


    The default path is /opt, which creates the installation directory, /opt/impinj/itemsense/2_1_0. If you choose to create your own directory, be aware that ItemSense appends the path, impinj/itemsense/2_1_0, to your location during installation.

    You will be asked to confirm if you would like to continue with the installation. Select y to continue with the installation or n to back out of the installation.

    Example output:

    [user@localhost~]$ sudo ./itemsense-2.1.0+XXX-setup.run install
    INFO: Host: Ubuntu 16.04.6 LTS
    INFO: Docker storage driver: overlay2
    INFO: Confirmed Impinj ItemSense host has 4 cores available.
    Please choose a path for Impinj ItemSense 2.1.0 or press enter to use the default value or type "exit" to quit.
    Path [/opt]: /newPath
    About to install Impinj ItemSense into path "/newPath".  The following directories will be created "impinj/itemsense/2_1_0"
    Ready to proceed (y/n)? y
    INFO: Generating compose file: /newPath/impinj/itemsense/2_1_0/itemsense-prod.yml
    INFO: Unpacking docker images
    Loaded image: isreg/imc:2.1.0.737
    
    ...
    
    INFO: Unpacking firmware images
    
    ...
    
    Creating 2_1_0_isv2_1      ... done
    
    ...
    
    INFO: Installation action complete using path: /newPath/impinj/itemsense/2_1_0
    INFO: Setting permissions on /newPath/impinj/itemsense/2_1_0/containers
    INFO: Waiting up to 120 seconds for the Impinj ItemSense services to initialize and respond
    Testing service endpoints [=>                                                  ]
    Testing service endpoints [=>                                                  ]
    Testing service endpoints [==>                                                 ]
    Testing service endpoints [===>                                                ]
    Testing service endpoints [====>                                               ]
    Testing service endpoints [=====>                                              ]
    Testing service endpoints [======>                                             ]
    Testing service endpoints [======>                                             ]
    14/120s
    INFO: IPv4 and IPv6 connectivity to all Impinj ItemSense services successfully established!
    INFO: ItemSense endpoints test passed
    INFO: Waiting up to 30 seconds for the Impinj ItemSense Management Console (IMC) to initialize and respond
    Testing IMC endpoint [=>                                                  ] 0/30s
    INFO: Found IMC HTTP endpoint
    INFO: To open the Impinj ItemSense Management Console and complete the setup process,
      open a supported web browser and browse to http://<server IP>:3010.
      For more information, consult the ItemSense Management Console section on the
      Impinj Developers Portal at https://platform.impinj.com/site/developer/itemsense.
    INFO: Impinj ItemSense install operation complete at path /newPath/impinj/itemsense/2_1_0
    


    In a browser, navigate to the IMC using the server IP address or host name and port 3010: http://TARGET_SERVER:3010/

Upgrade ItemSense

Upgrade Using Separate Hosts

These instructions explain how to stand up a separate instance of ItemSense and run a migration script to copy over the configuration. Note that historical item, health, and job data will be lost using this upgrade method. If you need to retain your historical item data across the upgrade, then please follow the instructions for Upgrade on the Same Host.

Side-by-Side Prerequisites

  • Your current ItemSense build has been installed and is up and running on TARGET_SERVER_XXX.
  • ItemSense-2.1.0 has been installed according to the Installation instructions, and is up and running on TARGET_SERVER_YYY

Side-by-Side Upgrade Instructions

As of ItemSense 2018r2, the configuration migration is executed through the ItemSense Management Console (IMC).

  1. In a browser on TARGET_SERVER_XXX, navigate to the IMC using the server IP address or host name and port 3010:

  2. From the landing page navigation menu, click More | Configuration Import/Export. This will take you to the Configuration Migration page.

  3. Click the Export Configuration button.

  4. Select and copy the exported configuration, including both the beginning and ending brackets.

  5. Navigate to the IMC Configuration Migration page on TARGET_SERVER_YYY.

  6. Click in the Import Configuration text box and paste the content you copied.

  7. Select Overwrite and click the Import Configuration button.

After upgrading ItemSense, you must also upgrade your Reader Agent and Firmware. You can do this from within the ItemSense Management Console (IMC).

  1. On the navigation bar, click More | Admin Panel.
  2. Click Software Installation.
  3. For Software to Install, select Reader Agent
  4. For Version to Install, select the latest version of the reader agent.
  5. Select Reader Firmware, and select the latest version of the reader firmware.

Upgrade on the Same Host

This installs the new release of ItemSense over an existing instance.

In-Place Prerequisites

  • The Impinj ItemSense setup package has been obtained
  • Your current ItemSense build is up and running on TARGET_SERVER. ItemSense 2018r2 Limited Availability and any later builds are valid.
  • Docker, version 18.09.2 or later
  • Docker Compose, version 1.23.2 or later

In-Place Upgrade Instructions

  1. (Optional) As a precaution, backup your configuration and database.

    1. From the IMC navigation menu, click More | Configuration Import/Export
    2. On the Configuration Import/Export page, click the Export Configuration button.
    3. Select and copy the exported configuration, including both the beginning and ending brackets.
    4. Backup the ItemSense database. The database is stored in: ~/containers/is-db

            sudo cp -r ~/containers/is-db ~/IS_DB_BACKUP

  2. Copy the ItemSense setup package file to the target server. The following is an example of copying the file from a Linux host to the target server.

          scp itemsense-2.1.0+XXX-setup.run USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME should be replaced with the designated user on the target server
    • TARGET_SERVER should be replaced with the hostname or IP address of the server on which ItemSense will be installed

  3. When the file transfer to the target server has completed, log on to the target server and navigate to the location where you placed the file. If you followed the command above, the file will be in the home directory of the designated user.

  4. Make the setup package file executable:

          chmod +x itemsense-2.1.0+XXX-setup.run

  5. From the same directory as the ItemSense setup package, run the setup package with the argument "upgrade".

ItemSense 2.1.0 allows you to configure the maximum number of records you want to retain, in addition to the previous feature that retained records based on their age. The types of records affected by this new feature are:

  • items
    • item history
    • threshold transitions
    • task
    • health

The config.yml file provided with ItemSense 2.1.0 contains default values for maxAge and maxCount that have been performance tested and are recommended by Impinj. However, if applied, these new defaults can result in the loss of older data. During the upgrade, you will be warned about this feature and required to make a choice to:

  • Proceed using the recommended maximum row counts (y)
  • Proceed with the feature disabled (n)
  • Abort

To avoid losing data, we provide an alternative config.yml, in which you can customize the settings or effectively disable the new feature. For more information about these files and how they allow you to customize ItemSense, see Configuration and Logging Files.

If you are at all uncertain, please abort the upgrade and contact Impinj Customer Support.

As of ItemSense 2.1.0, Impinj provides the option to choose the location at which ItemSense is installed. At the start of the Installation, you will be prompted to:

  • Press enter to accept the default directory provided by ItemSense,
  • Provide an absolute path to the directory in which you will install ItemSense, or
  • Type "exit" to quit

The default path is /opt, which creates the installation directory, /opt/impinj/itemsense/2_1_0. If you choose to create your own directory, be aware that ItemSense appends the path, impinj/itemsense/2_1_0, to your location during installation.

You will be asked to confirm if you would like to continue with the installation. Select y to continue with the installation or n to back out of the installation.

Example output:

Path [/opt]: /MyDir
About to install Impinj ItemSense into path "/MyDir".  The following directories will be created "impinj/itemsense/2_1_0"
Ready to proceed (y/n)? y
INFO: Removing old Impinj ItemSense backups (if any)
INFO: Stopping and removing previous installation

INFO: Removing container images from local docker registry
INFO: ...Removing isreg/is-proxy:0.1.1
Untagged: isreg/is-proxy:0.1.1

...

INFO: ...Removing isreg/is-mariadb:10.0.28-3
Untagged: isreg/is-mariadb:10.0.28-3

...

INFO: ...Removing isreg/is-ntp:0.0.3
Untagged: isreg/is-ntp:0.0.3

...


INFO: ...Removing rabbitmq:3.7.8-alpine
Untagged: rabbitmq:3.7.8-alpine

...

INFO: ...Removing isreg/imc:2.0.1.5
Untagged: isreg/imc:2.0.1.5

...

INFO: ...Removing isreg/isv2:0.0.89-4ca42257
Untagged: isreg/isv2:0.0.89-4ca42257

...

INFO: ...Removing isreg/itemsense:2.0.3_34-caf860cf
Untagged: isreg/itemsense:2.0.3_34-caf860cf

...

INFO: Copying data from your old Impinj ItemSense installation.  Depending on the size of your database, this can be a lengthy process.
INFO: Re-integrating previous data files for migration
INFO: Importing reader agent SSL certificates from previous installation
INFO: Restoring IMC config data
INFO: Setting permissions on /MyDir/impinj/itemsense/2_1_0/containers
INFO: Generating compose file: /MyDir/impinj/itemsense/2_1_0/itemsense-prod.yml
INFO: Unpacking docker images
Loaded image: isreg/imc:2.1.0.743
Loaded image: isreg/is-mariadb:2.1.1
Loaded image: isreg/is-ntp:0.0.3
Loaded image: isreg/is-proxy:0.2.1
Loaded image: isreg/isv2:0.0.108-a0f0d84b
Loaded image: isreg/itemsense:2.1.0_1661-26c6a4de
Loaded image: rabbitmq:3.7.8-alpine
INFO: Unpacking firmware images
INFO: Installing nginx container configuration
INFO: Installing rabbitmq container configuration
INFO: Installing Impinj ItemSense support tools
INFO: Starting the new docker composition
Creating network "2_1_0_itemsense" with driver "bridge"
Creating 2_1_0_isv2_1      ... done
Creating 2_1_0_imc_1       ... done
Creating 2_1_0_itemsense_1 ... done
Creating 2_1_0_is-ntp_1    ... done
Creating 2_1_0_is-db_1     ... done
Creating 2_1_0_is-rabbit_1 ... done
Creating 2_1_0_nginx_1     ... done
INFO: Installation action complete using path: /MyDir/impinj/itemsense/2_1_0

...

INFO: Database migrations started.  Depending on the size of your database, this can be a lengthy process.
  Interrupting this may corrupt Impinj ItemSense and render your system unusable.
  Please allow the process to complete normally. If you believe it is taking too long, contact support.
INFO: Data migrations completed.
INFO: Migrating TLS settings from previous installation
INFO: Checking for previous TLS settings
INFO: Upgrading and Restoring Impinj ItemSense config store
INFO: Removing temporary files
...

INFO: upgrade action complete
INFO: Setting permissions on /MyDir/impinj/itemsense/2_1_0/containers
INFO: Waiting up to 120 seconds for the Impinj ItemSense services to initialize and respond

...

INFO: Found IMC HTTP endpoint
INFO: To open the Impinj ItemSense Management Console and complete the setup process,
  open a supported web browser and browse to http://<server IP>:3010.
  For more information, consult the ItemSense Management Console section on the
  Impinj Developers Portal at https://platform.impinj.com/site/developer/itemsense.
INFO: Impinj ItemSense upgrade operation complete at path /MyDir/impinj/itemsense/2_1_0


At this point all configuration has been migrated to the new instance but the readers are still provisioned against the old instance. You will need to go through the provisioning flow to associate the defined readers with the new instance.

  1. Add a network
    1. Find a network to add by looking at the Address field of a reader definition
    2. In the navigation menu, click More | Admin Panel.
    3. Click Scanner Configuration
  2. Register readers
    1. From the Definitions page, click the Scanner tab. This will take you to the SCANNER page.
    2. Click the DISCOVER READERS button.
    3. Select only the readers flagged with the triangle exclamation point
    4. Click the REGISTER SELECTED READERS button
  3. Upgrade reader firmware
    1. Return to the Definitions" page. In the navigation menu, click *More | Admin Panel**.
    2. Click SOFTWARE INSTALL.
    3. Under Software Installation, Software to Install, select Reader Firmware.
    4. Select your set of readers to update
    5. Click START INSTALLATION.

The readers are now registered, upgraded, and ready to start jobs. If the upgrade was successful, remove the backups:

      sudo rm -rf ~/IS_DB_BACKUP
      rm is-<filename>

Upgrade Earlier Versions of ItemSense

If you are runnning a version of ItemSense that is older than 2018r2, please contact Impinj support.

Uninstall ItemSense via Automated Process

For ItemSense build 2017r1 or older, refer to the Legacy Installation Guide.

To uninstall ItemSense via the automated process, follow these steps:

  1. Go to the directory where you put the ItemSense installer file.

  2. Run the installer with the remove subcommand to remove the ItemSense software:

          sudo ./itemsense-2.1.0+XXX-setup.run remove

    Example output:

    
    [issupport@localhost ~]$ sudo ./itemsense-2.1.0+XXX-setup.run remove
    Verifying archive integrity...  100%   All good.
    
    ItemSense 2.1.0 Build 1661 Setup Package  100%
    
    ...
    
    About to completely remove Impinj ItemSense containers, backups, and data from path /opt/impinj/itemsense/2_1_0.
    Ready to proceed (y/n)? y
    INFO: Stopping and removing containers
    Stopping 2_1_0_is-rabbit_1 ... done
    Stopping 2_1_0_isv2_1      ... done
    Stopping 2_1_0_itemsense_1 ... done
    Stopping 2_1_0_imc_1       ... done
    Stopping 2_1_0_nginx_1     ... done
    Stopping 2_1_0_is-ntp_1    ... done
    Stopping 2_1_0_is-db_1     ... done
    Removing 2_1_0_is-rabbit_1 ... done
    Removing 2_1_0_isv2_1      ... done
    Removing 2_1_0_itemsense_1 ... done
    Removing 2_1_0_imc_1       ... done
    Removing 2_1_0_nginx_1     ... done
    Removing 2_1_0_is-ntp_1    ... done
    Removing 2_1_0_is-db_1     ... done
    Removing network 2_1_0_itemsense
    INFO: Removing container images from local docker registry
    INFO: ...Removing isreg/is-proxy:0.2.1
    Untagged: isreg/is-proxy:0.2.1
    
    …
    
    INFO: ...Removing isreg/is-mariadb:10.0.28-3
    Untagged: isreg/is-mariadb:10.0.28-3
    
    …
    
    INFO: ...Removing isreg/is-ntp:0.0.3
    Untagged: isreg/is-ntp:0.0.3
    
    …
    
    INFO: ...Removing isreg/is-rabbitmq-runit:3.6.15-alpine
    Untagged: isreg/is-rabbitmq-runit:3.6.15-alpine
    
    …
    
    INFO: ...Removing isreg/imc:1.0.523
    Untagged: isreg/imc:1.0.523
    
    …
    
    INFO: ...Removing isv2:0.0.59-e740b050
    Untagged: isv2:0.0.59-e740b050
    
    …
    
    INFO: ...Removing isreg/itemsense:master-7850a
    Untagged: isreg/itemsense:master-7850a
    
    …
    
    INFO: Impinj ItemSense remove operation complete at path...
    
    

Uninstall ItemSense via Manual Process

To manually uninstall ItemSense, follow these steps:

  1. Check that nothing is listening on port 80, 3010, 443 or 5672. For example, the following command should not show any output:

          sudo docker ps

    If you see seven containers listed like the following:

    CONTAINER ID        IMAGE                                   COMMAND                  CREATED             STATUS              PORTS               NAMES
    165601415c7e        isreg/is-proxy:0.1.0                    "/bin/sh -c /bin/d..."   13 minutes ago      Up 13 minutes                           issupport_nginx_1
    63d6bb6e4287        isreg/is-mariadb:10.0.28-3              "docker-entrypoint..."   13 minutes ago      Up 13 minutes                           issupport_is-db_1
    0c704cc5a15a        isv2:0.0.59-e740b050                    "/opt/itemsense/i..."   13 minutes ago      Up 13 minutes                           issupport_isv2_1
    8f09717bf79c        isreg/itemsense:master-7850a            "/sbin/my_init"          13 minutes ago      Up 13 minutes                           issupport_itemsense_1
    411dd4d4b572        isreg/is-rabbitmq-runit:3.6.15-alpine   "docker-entrypoint..."   13 minutes ago      Up 13 minutes                           issupport_is-rabbit_1
    5fdf343d83ca        isreg/imc:1.0.523                       "/etc/sv/is-webapp..."   13 minutes ago      Up 13 minutes                           issupport_imc_1
    b88c7e88fc27        isreg/is-ntp:0.0.3                      "/bin/sh /usr/loca..."   13 minutes ago      Up 13 minutes                           issupport_is-ntp_1
    

    Then navigate to the installation directory of ItemSense and run:

          sudo docker-compose -f itemsense-prod.yml down

    Example output:

    Stopping issupport_nginx_1     ... done
    Stopping issupport_is-db_1     ... done
    Stopping issupport_isv2_1      ... done
    Stopping issupport_itemsense_1 ... done
    Stopping issupport_is-rabbit_1 ... done
    Stopping issupport_imc_1       ... done
    Stopping issupport_is-ntp_1    ... done
    Removing issupport_nginx_1     ... done
    Removing issupport_is-db_1     ... done
    Removing issupport_isv2_1      ... done
    Removing issupport_itemsense_1 ... done
    Removing issupport_is-rabbit_1 ... done
    Removing issupport_imc_1       ... done
    Removing issupport_is-ntp_1    ... done
    


  2. Remove the containers directory and the itemsense-prod.yml file from the installation directory.

          sudo rm -rf containers/
          sudo rm -f itemsense-prod.yml

  3. Find the ItemSense docker images

          sudo docker images

    Example output:

    REPOSITORY                TAG                                 IMAGE ID            CREATED             SIZE
    isreg/itemsense           2.1.0_1661-26c6a4de                 452fbdaede7d        6 days ago          421MB
    isreg/imc                 2.1.0.743                           92db33343fb7        6 days ago          131MB
    isreg/isv2                0.0.108-a0f0d84b                    1bfe9846efa9        2 weeks ago         122MB
    isreg/is-mariadb          2.1.1                               22e7e735e86c        3 weeks ago         200MB
    isreg/is-proxy            0.2.1                               661688be09b6        5 weeks ago         16.9MB
    rabbitmq                  3.7.8-alpine                        b84c00eb4aee        8 months ago        46.8MB
    isreg/is-ntp              0.0.3                               ca74798da8b8        12 months ago       4.5MB
    


  1. Remove the ItemSense docker images.

          sudo docker rmi IMAGEID

    Where IMAGEID is the IMAGE ID listed in your output for step 4 above. Example output:

    Untagged: isreg/is-mariadb:10.0.28-3
    Deleted: sha256:b46cf84d5e294a0953254ca5e06e5aaac3752a9d366667671dcb3a7bdf23cb53
    Deleted: sha256:0d1e183a06690ee796292e74e57b0a24b13a2b068c1a4b3793af31e18e51cef6
    Deleted: sha256:cb28cd83346263cb6edb1f6f056c1b575b7d4013ffee8527144c4ef2950d32ce
    Deleted: sha256:5671e0f4505e12a9217c13f5dc4353b5cc25a3bff58591ea884addb200f63a9f
    Deleted: sha256:120c9add60e3fa4f42d3dbc465d6e783c94ba8a08f32de2985856c01e8038c92
    Deleted: sha256:b5a9489a383edacf6330dbc1e53a727f421b824778bfca65e0f69911bba7df8e
    Deleted: sha256:80c44837b8b4f546ccd99a8e348c65cd39610fbc2f9c4701388a8b3afca6fb0a
    Deleted: sha256:baa7a423070394fed311ccc47b6e6450a828062d8014cdb894cf8358e7dc67e7
    Deleted: sha256:d7852a97e12d6c3d318ec4af1a65c5898b55fdc3600430b3fa0fa807fb1bcc23
    Deleted: sha256:d5a98345467828bd6cfbebbddb88ed64b2b84304155774317505fdc389c62960
    Deleted: sha256:7f6799f430961cfd0adb6af81aa60bb66a7c42da081a5a844b2a6ec96f94c996
    Deleted: sha256:e85bddc133b6addb199a81941cf9f9a580d226180fccd71eac0c6c89dcc653ec
    Deleted: sha256:ca76ebbabd672ad4c5dd8ce3659dcd0794df9b11329359aa74d9461f15a47844
    Deleted: sha256:a3928699dfa0d33e65f302e3176d054aec7a50bbe5c2e7e0b53a68541b89dac5
    Deleted: sha256:23672a5ac8fb00f5963174353f4fea163a43b23b7814ba3d7efb8cf9803f7010
    Deleted: sha256:9042efb93af5246dbc36ffd103a8b87e8d39e797e06656fb5df053ca77378eb9
    Deleted: sha256:c08bac17c414ebfb8d22b46b79d4c1fc41d16a4452c924c306cbec673d215d43
    Deleted: sha256:30499d7d4e67556242cabe7be7b1bac2a94d7ff00972c6236475858a91b4b2a7
    Deleted: sha256:b6ca02dfe5e62c58dacb1dec16eb42ed35761c15562485f9da9364bb7c90b9b3
    

Uninstall is now complete.

Clock Synchronization and NTP Configuration

The integrity of ItemSense's item data relies heavily on network clock synchronization. If a reader's clock is more than ten seconds out of sync with the ItemSense host's clock, that reader's reports will be ignored and a health event will be triggered (See the Health API) in the Impinj API Reference.

In order for readers to generate reliable reports, all of the readers being utilized in a job must be synchronized with each other and with ItemSense. Prior to collecting tag data from ItemSense for the first time, you should ensure that all of the RAIN RFID reader clocks are configured to synchronize with an NTP server.

If your network does not automatically provide an NTP source, you have a number of options to ensure that all reader clocks are configured to synchronize with an NTP server. The easiest method is through the ItemSense Management Console (IMC). The following steps install an NTP server on the host running ItemSense and configure the readers to use that host as their NTP source.

  1. Connect to ItemSense via the ItemSense Management Console at: http://TARGET_SERVER:3010.
  2. From the Home Page menu bar, click More|NTP Reader Sync.
  3. Click the NTP Reader Sync toggle button to enable or disable reader synchronization.

Alternatively, you can use the following instructions to manually configure each reader and the ItemSense host to use an external NTP server.

Configure a Reader to Use an external NTP Server

Perform the following steps to configure a reader to use an external NTP server:

  1. Log in to the reader RShell command prompt using SSH.
  2. Disable NTP:

          config network ntp disable

  3. (Optional) Prevent the reader from dynamically configuring its NTP servers through DHCP:

          config network ntp dynamicservers disable

  4. Delete any configured NTP servers:

          config network ntp delall

  5. Add the external NTP server hostname or IP address:

          config network ntp add <NTP Server hostname or IP>

  6. Re-enable NTP:

          config network ntp enable

  7. Check that the reader synchronizes (this can take a little while):

          show network ntp

Configure ItemSense to Use Encrypted TLS Communications for HTTPS, AMQPS, and MQTTS

You can install your own certificate in the ItemSense server to secure communication between your clients and ItemSense. The only prerequisite is a valid certificate and its corresponding private key. The two files must be accessible to the utility script that enables https, amqps, and mqtts in ItemSense.

A utility script named enable_tls.sh in the itemsense_support folder helps you safely install your certificate.

Assuming the certificate files, my-cert.crt and my-cert.key, are stored in the itemsense_support folder, the following command sets ItemSense to https, amqps, and mqtts:

      sudo ${BASE_LOCATION}/impinj/itemsense/2_1_0//itemsense_support/enable_tls.sh ./my-cert.crt ./my-cert.key

The script asks you whether you want to proceed. If yes, the script switches ItemSense to https, amqps, and mqtts.

Impinj ItemSense supports TLS 1.1, TLS 1.2, and TLS 1.3. Following are basic settings to set your host firewall for specific configurations, whether running in TLS or in non-TLS mode.

Configure Ports to Use HTTP

Port Setting Use
80/tcp enable API
443/tcp enable Must be enabled for readers to connect, whether using HTTP or HTTPS. In both cases, readers connect via HTTPS.
1883/tcp enable MQTT
3010/tcp enable ItemSense Management Console (IMC)
5672/tcp enable AMQP
123/udp enable NTP

Configure Ports to Use HTTPS

Port Setting Use
80/tcp disable API
443/tcp enable Readers connect to ItemSense via HTTPS in either case
1883/tcp disable MQTT
3010/tcp enable ItemSense Management Console (IMC) -- HTTPS
5671/tcp enable AMQPS
5672/tcp disable AMQP
8883/tcp enable MQTTS
123/udp enable NTP

Configure Ports to Migrate from HTTP to HTTPS

Port Setting Use
80/tcp disable API
1883/tcp disable MQTT
5671/tcp enable AMQPS
5672/tcp disable AMQP
8883/tcp enable MQTTS

Tailor the Communication Protocols

If you need to tailor communication protocols to be encrypted and/or to redirect http to https, you can find more script options by executing:

      sudo ${BASE_LOCATION}/impinj/itemsense/2_1_0/containers/itemsense_support/enable_tls.sh --advanced-help

Revert to HTTP, AMQP, and MQTT

If you encounter any problems setting up ItemSense to https, amqps and mqtts you can switch ItemSense back to http, amqp and mqtt with the following command:

      sudo ${BASE_LOCATION}/impinj/itemsense/2_1_0/itemsense_support/enable_tls.sh disable

Configuration and Logging Files

With ItemSense 2.1.0, the config.yml and logback.xml files have been externalized to make them more accessible to users. These files can be found at:

      {BASE_LOCATION}/impinj/itemsense/2_1_0/containers

To edit these files, you must first escalate the permissions using either chmod, chmod +x config.yml or sudo, sudo gedit config.yml.

The log configuration file, logback.xml, manages ItemSense system log files and is a useful diagnostic tool when working with Impinj Support. It is important to note that incorrect changes to the format of this file could cause a loss of logging altogether. ItemSense will still run, but it could affect your system's performance and disk usage.

The most common use of the config.yml file is management of the pruning configurations. This file contains default values for maxAge and maxCount that have been tested and are recommended by Impinj to preserve performance. However, if you have a large quantity of data in your previous ItemSense installation, applying these new default values may result in the loss of older data. To avoid this, you can set the maxCount values to the largest possible value, which effectively disables pruning.

Be aware that if incorrect changes are made to config.yml, ItemSense will not run.