Impinj® ItemSense™ Installation Guide

This document describes the installation procedure for the Impinj® ItemSense™ software platform.

As of ItemSense 2016r6, ItemSense is delivered as a set of docker containers. These are bundled with an installation script in an archive file. This guide details the instructions for the docker container based installation.

Table of Contents

ItemSense Container-based Installation

Introduction

The ItemSense software for release 2016r6 is provided as an archive file format for customers who are interested in installing the software within their company managed network. In this archive file there are a number of files, but the primary components of ItemSense are delivered as a series of docker containers. This part of the document describes the process for installing ItemSense using the archive file.

Installing an ItemSense docker container instance is a two-step process:

  • The ItemSense archive file is copied onto the chosen server
  • The ItemSense installation script is run, which will automatically start ItemSense.

Note that this guide assumes a good grasp of the Linux command line.

Prerequisites

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

  • An ItemSense Instance ID must be requested from your Impinj representative
  • Upon receipt of your ItemSense Instance ID, download the ItemSense archive file from the link in the welcome Email.
  • The server onto which ItemSense will be installed should be prepared with the following:
    • Docker supported Linux OS installed with the latest kernel update for that distribution
    • Version 1.12 or higher of the docker tool should be installed
    • Version 1.8 or higher of the docker-compose tool should be installed

Instructions for installing docker can be found here and instructions for installing Docker Compose can be found here.

Upgrade ItemSense

If you have an existing instance of ItemSense, then the procedure to upgrade to 2016r6 is the same as to install, after the following pre-upgrade steps have been completed.

Obtain the ItemSense key file from Impinj Support (support@impinj.com) and place it in your ~/.ssh/ directory, where ~ is the home directory of the user performing the upgrade.

To use the ItemSense key file, the command at step 1 of the install procedure now becomes:

scp -i ~/.ssh/is_support1215_rsa is.IT-BTIC-BUT.0.1.93.tar.bz2 is_support@TARGET_SERVER:.

Before upgrading, it is prudent to back up the existing item database from your R4 instance. To do this run:

  1. After you have logged in, ensure you are in the ItemSense base directory. This is where the ItemSense YAML itemsense-prod-1.6.0.yml is located.

  2. Stop ItemSense.

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

    Example output:

    Stopping issupport_ItemSense_1 ... done
    Removing issupport_ItemSense_1 ... done
    
  3. Copy the entire /home/is_support/containers/itemsense/var/lib/mysql folder to a remote host. There is not enough space on the VM to store the item data backups there.

  4. Restart ItemSense.

    sudo docker-compose -f itemsense-prod-1.6.0.yml up -d

    Example output:

    Starting issupport_ItemSense_1
    

Once done continue with the ItemSense 2016r6 installation from step 2 of the Install Instructions section below.

Install ItemSense on Ubuntu

The following instructions were written for installing ItemSense onto the Ubuntu Linux distribution. It is possible to install ItemSense on a number of distributions of Linux. While many of the commands should work when installing ItemSense on a Linux distribution other than Ubuntu, it may be necessary to modify the commands slightly for your distribution.

Pre-checks

Run the following commands in a terminal on the targer 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.

    netstat -tuln | grep ':80\W.\*LISTEN\|:3010\W.\*LISTEN\|:443\W.\*LISTEN\|:5672\W.\*LISTEN'

    This command should not show any output

  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 isreg/*

    If this command shows some ItemSense docker images already exist, follow the uninstall instructions below to remove them

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

    docker -v

    Example output:

    Docker version 1.12.1, build 23cf638

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

    docker-compose -v

    Example output:

    docker-compose version 1.8.0, build 94f7016

  5. Check your kernel version is the latest recommend for your OS release. To see kernel version run:

    uname -r

    Example output:

    4.4.0-45-generic

Install Instructions

To install ItemSense 2016r6, you will need to have already downloaded the archive file. This file will be named similar to the following: is.IT-BTIC-BUT.0.1.XX.tar.bz2 As the file is roughly 1.3Gb it may take a while to download, depending on your connection.

When the archive file has been obtained:

  1. Put the file on to the target server.

    scp is.IT-BTIC-BUT.0.1.XX.tar.bz2 USERNAME@TARGET_SERVER:.

    Where:

    • USERNAME should be replaced with the user on the target server.
    • TARGET_SERVER should be replaced with the hostname or IP address of the server on which you intend to install ItemSense.
  2. When the file has complete transferring to the target server, log on to the target server and navigate to the location where you copied 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. Note: No matter where you extract the archive file to, ItemSense will always be installed to the home directory pointed to by the environment variable $HOME.

  3. From the same directory as the ItemSense archive file run the following to extract the archives contents:

    tar -xvjf is.IT-BTIC-BUT.0.1.XX.tar.bz2

    Example output:

    ./tarfile/
    ./tarfile/firmware/
    ./tarfile/firmware/firmware_speedway/
    ./tarfile/firmware/firmware_speedway/octane-5.8.1.240.upg
    ./tarfile/firmware/firmware_speedway_versions.json
    ./tarfile/firmware/cap_itemsense/
    ./tarfile/firmware/cap_itemsense/ii-cap-0.0.1.15-296.upg
    ./tarfile/firmware/cap_itemsense_versions.json
    ./tarfile/install_is_containers.sh
    ./tarfile/images/
    ./tarfile/images/is-mariadb.tar
    ./tarfile/images/is-container.tar
    ./tarfile/itemsense-prod-1.6.0.yml
    

    Note: this can take up to 2 minutes to complete, particularly the extraction of the is-container.tar file.

  4. Check that the file has extracted correctly:

    ls tarfile

    Output:

    firmware  images  install_is_containers.sh  itemsense-prod-1.6.0.yml
    
  5. Enter the tarfile directory:

    cd tarfile

  6. Run the installed script. Note: this script should be run either as the root user or with sudo. If run as the root user ItemSense will be installed in the root user's home directory (typically /root).

    sudo bash ./install_is_containers.sh

    Example output:

    INFO: Installing/Upgrading Itemsense
    INFO: Unable to locate previously supported version of ItemSense. Performing new install under /home/is_support.
    INFO: Installing new files
    INFO: Unpacking docker container images
    fe4c16cbf7a4: Loading layer [==================================================>] 128.9 MB/128.9 MB
    f1621398948b: Loading layer [==================================================>] 344.6 kB/344.6 kB
    6ebad06b3e49: Loading layer [==================================================>]  4.32 MB/4.32 MB
    1bc74a039df4: Loading layer [==================================================>] 1.536 kB/1.536 kB
    3310797b3a3e: Loading layer [==================================================>] 14.77 MB/14.77 MB
    9b57cb0de8c4: Loading layer [==================================================>] 44.03 kB/44.03 kB
    9bb3d5b8bde2: Loading layer [==================================================>]  5.12 kB/5.12 kB
    7702d916a821: Loading layer [==================================================>]  5.12 kB/5.12 kB
    4718e4c50ba4: Loading layer [==================================================>] 200.4 MB/200.4 MB
    23ff69eb2af2: Loading layer [==================================================>] 8.192 kB/8.192 kB
    c6080284fae2: Loading layer [==================================================>] 7.168 kB/7.168 kB
    78535633caa2: Loading layer [==================================================>] 1.536 kB/1.536 kB
    db4a198f9fa3: Loading layer [==================================================>] 3.584 kB/3.584 kB
    9dfe48bfe0b2: Loading layer [==================================================>]  7.68 kB/7.68 kB
    Loaded image: isreg/is-mariadb:10.0.28
    6650225473f3: Loading layer [==================================================>] 197.2 MB/197.2 MB
    724e9db35fe0: Loading layer [==================================================>] 208.9 kB/208.9 kB
    3973e2de72ae: Loading layer [==================================================>] 4.608 kB/4.608 kB
    5f70bf18a086: Loading layer [==================================================>] 1.024 kB/1.024 kB
    0cd01e86530e: Loading layer [==================================================>] 56.32 kB/56.32 kB
    1ef215608c77: Loading layer [==================================================>]   123 MB/123 MB
    ebe3fd02e7e0: Loading layer [==================================================>] 107.5 kB/107.5 kB
    416f17772e10: Loading layer [==================================================>] 1.294 GB/1.294 GB
    4a25411a26ad: Loading layer [==================================================>] 3.072 kB/3.072 kB
    47d6276e098a: Loading layer [==================================================>] 3.072 kB/3.072 kB
    5cf819b5200c: Loading layer [==================================================>] 3.072 kB/3.072 kB
    8a6bad46e220: Loading layer [==================================================>] 3.072 kB/3.072 kB
    ee83b3cb399c: Loading layer [==================================================>] 3.072 kB/3.072 kB
    c1f406273bff: Loading layer [==================================================>] 3.072 kB/3.072 kB
    20f1f7e7d0eb: Loading layer [==================================================>] 4.608 kB/4.608 kB   
    525ec7957f2f: Loading layer [==================================================>] 4.608 kB/4.608 kB
    e2367a8885bc: Loading layer [==================================================>] 6.656 kB/6.656 kB
    aee632822548: Loading layer [==================================================>] 6.656 kB/6.656 kB
    bad25e87ab04: Loading layer [==================================================>] 163.4 MB/163.4 MB
    1fc3e5a5aed7: Loading layer [==================================================>] 227.5 MB/227.5 MB
    4f26b41745e0: Loading layer [==================================================>] 623.2 MB/623.2 MB
    Loaded image: isreg/itemsense:develop-16f25
    INFO: Firmware images
    INFO: Start the new docker compose file
    Creating network "is_support_default" with the default driver
    Creating is_support_itemsense_1
    Creating is_support_is-db_1
    INFO: Installation complete
    
  7. In a browser, navigate to the IMC using the server IP address or host name and port 3010:

    http://serverIP:3010/

    Note: after ItemSense starts it can take a minute or so before the IMC will be available

Uninstall ItemSense

To uninstall ItemSense run the following:

  1. Ensure that it is not running:

    sudo docker ps

    If you see two containers listed like the following:

    CONTAINER ID        IMAGE                           COMMAND                  CREATED             STATUS PORTS                                                                                                                                            NAMES
    fcfaa6ae9323        isreg/is-mariadb:10.0.28        "docker-entrypoint.sh"   2 minutes ago       Up 2 minutes        3306/tcp                                                                                                                                         is_support_is-db_1
    1f9c1ad9a0ea        isreg/itemsense:develop-cbbdf   "/sbin/my_init"          2 minutes ago       Up 2 minutes        0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp, 4369/tcp, 0.0.0.0:3010->3010/tcp, 5671/tcp, 0.0.0.0:5672->5672/tcp, 25672/tcp, 0.0.0.0:161->5161/udp   is_support_itemsense_1
    

    Then navigate to the installation directory of ItemSense (which is your install user's home directory where the itemsense-prod-1.6.0.yml file is located) and run:

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

    Example output:

    Stopping is_support_is-db_1 ... done
    Stopping is_support_itemsense_1 ... done
    Removing is_support_is-db_1 ... done
    Removing is_support_itemsense_1 ... done
    Removing network is_support_default
    
  2. Check that nothing is listening on port 80, 3010, 443 or 5672.

    netstat -tuln | grep ':80\W.\*LISTEN\|:3010\W.\*LISTEN\|:443\W.\*LISTEN\|:5672\W.\*LISTEN'

    This command should not show any output.

  3. Remove the containers and work directory. Remove the itemsense-prod-1.6.0.yml file from the installation directory.

    sudo rm -rf containers/ work/ itemsense-prod-1.6.0.yml

  4. Find the ItemSense docker image

    sudo docker images isreg/*

    Example output:

    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    isreg/itemsense     develop-cbbdf       1d19344ef59a        4 days ago          2.474 GB
    isreg/is-mariadb    10.0.28             9624719527fa        5 days ago          340.1 MB
    
  5. 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.26
    Deleted: sha256:a508035a211d57375900f72245b393bffddbe2872137882e89ca9da2122b19bc
    Deleted: sha256:3072cba1a714165df54ed726529c4a2e0b404468ec8fa38ac5061c8e85079f40
    Deleted: sha256:efb58d19e00aeb18010fb9601c5f62f09cf610419476daaaed06ee9beae0470e
    Deleted: sha256:efabfc431d66b9b0a7859801c6dd2f7ba605641c7d05d34a43ec17f828873897
    Deleted: sha256:9ec14a42a06dfd7850171fb132321ecff0127d01301558bd600a1cd3125ee4df
    Deleted: sha256:3e0c9f3e156f9023da43a81a3895be481aaf033276f89ea43e38636b198ad1de
    Deleted: sha256:999296679db0f300dc45049abd06b5fb2fa36e9bf2bc6e36a41ac1113f20769b
    Deleted: sha256:c4ab196dba32b87c738314772804c0ec7de555813569eb9003c011a95b484960
    Deleted: sha256:9f97ab89b9ab488e27508fd6aa77b2708cff70e951b9b722f4829b9e4d04b4d3
    Deleted: sha256:a84d248cd3348a36c71d1225af4cc665e7df9e4942b65c20908d2d7503b5eb9e
    Deleted: sha256:aeb73b812583e391c7fe4c9c3eb844a5caa92ec279efc75e59b0fddb42e0d496
    Deleted: sha256:c541a7d71d798e2324344f2835d45516e5175d2ba328982e222f39d1df0f1bdf
    Deleted: sha256:eba5b35e8997700eef3477910f12fcad1785e546007c15522520f09a1a4abd08
    Deleted: sha256:247b8d8b7534f9957c42f44dcc2c53303baa1715be93d76d495543d747f895a3
    Deleted: sha256:2f71b45e4e254ddceb187b1467f5471f0e14d7124ac2dd7fdd7ddbc76e13f0e5
    

Change Default Network Address

Once ItemSense has been installed, it is possible to change its container network configuration. By default, all networks created by the docker engine will have an address range allocated to it within the 172.16.0.0/20 address range. The containers assigned to the first (and default) network created (called docker0 traditionally) will have addresses in the range 172.17.0.0/16. Containers assigned to the next network will have addresses in the range of 172.18.0.0/16. And so on. Any address in the range 172.16.0.0/20 might be problematic for a particular installation as it may cause conflicts with existing addresses within a private network occupying the same range.

However, it is possible to modify the address range used to hand out IP addresses to containers. To do this:

  1. Log into the host in which ItemSense is installed.

  2. Change to a user with 'sudo' privileges. Example:

    su - is_support

  3. Edit the docker-compose configuration file in the ItemSense home directory. Typically, this is the home directory of the user used when installing ItemSense. This should be done as a sudo user. Example command:

    sudo vi /home/is_support/itemsense-prod-1.6.0.yml
    
  4. Navigate to the bottom of the file and enter: networks: default: ipam: config: - subnet: IP_ADDRESS_RANGE gateway: IP_ADDRESS_GATEWAY Where: IPADDRESSRANGE - is the range of the addresses which should be handed out to the docker managed networks. Example: 192.168.111/24 IPADDRESSGATEWAY - the the name of the gateway address of the ranges. Typically, this is the first IP address in a network range. Example: 192.169.111.1

  5. Save the docker-compose configuration file.

  6. Now restart the containers:

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

    docker-compose -f itemsense-prod-1.6.0.yml up -d

  7. Ensure the containers restarted with an IPv4 address from the new range:

    docker network inspect issupport_default

    Example output:

    $ 00:15:02 > docker network inspect issupport_default
    [
        {
            "Name": "issupport_default",
            "Id": "c26013dcdedd1f1dd3ccc3f8d97d2c6f888733e910df0eddb32251b5eb7796ba",
            "Scope": "local",
            "Driver": "bridge",
            "EnableIPv6": false,
            "IPAM": {
                "Driver": "default",
                "Options": null,
                "Config": [
                    {
                        "Subnet": "192.168.111.0/24",
                        "Gateway": "192.168.111.1"
                    }
                ]
            },
            "Internal": false,
            "Containers": {
                "3f5a6ba0b23cd0323d8776d31a6814469c5a316065c427324e48cf8beb90ff4c": {
                    "Name": "issupport_itemsense_1",
                    "EndpointID": "246f72defdf364e571a41d8f20e24cd6735f531c85a7798a300635f3e7c2a893",
                    "MacAddress": "02:42:c0:a8:6f:03",
                    "IPv4Address": "192.168.111.3/24",
                    "IPv6Address": ""
                },
                "6d0a04a191a48d68876e8cbb02a4be2b989f69c4f7882c4f2fe529e487e09243": {
                    "Name": "issupport_is-db_1",
                    "EndpointID": "6fc529ff7abb0624e0c402fd7b7a2ecc53c66e80b3cfe9b79f3468e004a87f93",
                    "MacAddress": "02:42:c0:a8:6f:02",
                    "IPv4Address": "192.168.111.2/24",
                    "IPv6Address": ""
                }
            },
            "Options": {},
            "Labels": {}
        }
    ]
    

Note: Any changes you make to the docker-compose configuration file (itemsense-prod-x.x.x.yml) will need to be reapplied after an upgrade of ItemSense. This is because during the upgrade process the old docker-compose file will be moved to a backup location:

ITEMSENSE_HOME/.itemsense.bak/DATE/.

Where:

ITEMSENSE_HOME - Home directory of the user used when installing ItemSense.

DATA - The date the upgrade took place in the form YYYYMMDDHHmmSS e.g. 20170215003652.

Clock synchronization and NTP configuration

The integrity of ItemSense's item data relies heavily on network clock synchronization. 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.

In fact, if a reader's clock is too far out of sync with the ItemSense host's clock, that reader's reports will be ignored and a health event will be triggered (See Health API).

This means that it is necessary, prior to using ItemSense for the first time, to ensure that all of the RAIN RFID reader clocks are configured with an NTP server with which they should synchronize.

By default, all readers use DHCP to discover their NTP server. However, it is possible to add up to six statically configured NTP servers. Note that configuring the NTP server of the reader can't yet be done via ItemSense. Please refer to the Impinj RShell Reference Manual for more information on how to configure NTP on a reader. This guide can be found on support.impinj.com.

A recommended pattern is to configure the ItemSense host as an NTP server, and specify it as the NTP server for each reader (along with an appropriate backup NTP server if necessary). Then, the ItemSense server must synchronize its clock with another NTP server. This could be inside or outside the network.