Impinj® ItemSense™ Installation Guide

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

Table of Contents

Introduction

The ItemSense software is provided as an archive file format for customers who are 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
  • Ensure that all of the RAIN RFID readers are configured with an NTP server. See Clock Synchronization and NTP Configuration for more details.

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

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 2017r1, 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 installer script with the argument "install" or "upgrade" depending on the type of installation you are performing. 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 install

    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

Upgrade ItemSense

Upgrade from 2016r6 to 2017r1 Side-by-Side

A side-by-side upgrade is characterized by standing up a separate instance of ItemSense and running a migration script to copy over configuration. This is the preferred method for upgrading ItemSense as it minimizes the chances of errors. However, it comes with the limitation that any historical Item data will not be maintained.

Prerequisites

  1. ItemSense 2016r6 Build 174 has been installed and is up and running.
  2. ItemSense 2017r1 has been installed (according to the installation steps above) and is up and running

Instructions

  1. Install the is-tool Node package. The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool This tool can be installed on any host that has network access to both instances of ItemSense. For the purposes of these instructions is-tool will be installed on a different host than either of the ItemSense instances.

    $ npm install -g is-tool

  2. Use is-tool to save the configuration from the 2016r6 instance.

    $ is-tool save -i TARGET_SERVER -u admin -p admindefault

    No file specified to save. generating a filename.
    Connecting to ItemSense: {"username":"admin","password":"admindefault","itemsenseUrl":"http://TARGET_SERVER/itemsense"}
    Wrote: is-save-2017-07-26T16:50:30.772Z.json
    
  3. Use is-tool to load the saved configuration to the 2017r1 instance.

    $ is-tool load is-save-2017-07-26T16\:50\:30.772Z.json -i TARGET_SERVER-2 -u admin -p admindefault

    Reading is-save-2017-07-26T16:50:30.772Z.json
    Loading configuration...
    Loading facilities
    Loading readerDefinitions
    Loading readerConfigurations
    Loading recipes
    Loading zoneMaps
    Loading users
    
  4. At this point all configuration has been migrated to the 2017r1 instance but the readers are still provisioned against the 2016r6 instance. You will need to go through the provisioning flow to associate the defined readers with the new 2017r1 instance.

    • Add a network
      • Find a network to add by looking at the Address field of a reader definition
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • readers→scanner→discover readers
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered and upgraded and you can start running jobs.

Upgrade from 2016r6 to 2017r1 In-Place

An in-place upgrade is characterized by installing the new release of ItemSense over the top of an existing instance. This is a riskier procedure but does have the advantage of allowing you to retain historical Item and Item History data. If retaining historical data is not a concern for you then please follow the instructions for a side-by-side upgrade.

Prerequisites

  1. ItemSense 2016r6 Build 174 has been installed and is up and running.

Instructions

  1. Install the is-tool Node package. The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool This tool can be installed on any host that has network access to both instances of ItemSense. For the purposes of these instructions is-tool will be installed on a different host than either of the ItemSense instances.

    $ npm install -g is-tool

  2. Use is-tool to save the configuration from the 2016r6 instance. (Just in case the upgrade fails)

    $ is-tool save -i TARGET_SERVER -u admin -p admindefault

    No file specified to save. generating a filename.
    Connecting to ItemSense: {"username":"admin","password":"admindefault","itemsenseUrl":"http://TARGET_SERVER/itemsense"}
    Wrote: is-save-2017-07-26T16:50:30.772Z.json
    
  3. Consider also backing up the ItemSense database. All the database configuration is stored in: <ItemSense home folder>/containers/is-db/var/lib/mysql

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

  4. Take note of the registered networks for scanning, as these won't be migrated.

    • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Write down any networks you want to move over
  5. Upgrade the existing docker containers using the 2017r1 install script:

    sudo ./install_is_containers.sh upgrade

    INFO: Checking for existence of cat...Found
    INFO: Checking for existence of exit...Found
    INFO: Checking for existence of curl...Found
    INFO: Checking for existence of grep...Found
    INFO: Checking for existence of cd...Found
    INFO: Checking for existence of pwd...Found
    INFO: Checking for existence of mkdir...Found
    INFO: Checking for existence of mv...Found
    INFO: Checking for existence of cp...Found
    INFO: Checking for existence of chmod...Found
    INFO: Checking for existence of sleep...Found
    INFO: Checking for existence of rm...Found
    INFO: Checking for existence of sed...Found
    Ready to proceed (y/n)? y
    INFO: Upgrading Itemsense
    INFO: Found existing 2016r6 installation
    INFO: Stopping and removing previous installation
    Stopping itemsense_itemsense_1 ... done
    Stopping itemsense_is-db_1 ... done
    Removing itemsense_itemsense_1 ... done
    Removing itemsense_is-db_1 ... done
    Removing network itemsense_default
    
    ...
    
    INFO: 20: Sending query to imc endpoint
    INFO: ...Found imc endpoint
    INFO: install_is_containers.sh complete
    
  6. At this point all configuration has been migrated to the 2017r1 instance but the readers are still provisioned against the 2016r1 instance. You will need to go through the provisioning flow to associate the defined readers with the new 2017r1 instance.

    • Add a network
      • Add the networks made note of earlier
      • Go to the Scanner Configuration page of the IMC: (three dots in upper right)→Admin→Scanner config
    • Register readers
      • readers→scanner→discover readers
      • Select only the readers flagged with the triangle exclamation point
      • Click on "REGISTER SELECTED READERS"
    • Upgrade reader firmware
      • (three dots in upper right)→Admin and then selected the "SOFTWARE UPDATES" tab
      • Select "Reader Firmware" under "Software to Install"
      • Select your set of readers to update
      • Click "START INSTALLATION"
    • Now the readers are registered and upgraded and you can start running jobs.
  7. If the upgrade failed in any way:

    • You can remove the existing install and then reinstall:

      $ sudo ./install_is_containers.sh remove $ sudo ./install_is_containers.sh install

    • If the install still fails, you may need to remove the instance while purging the data:

      sudo ./install_is_containers.sh remove -p sudo ./install_is_containers.sh install

    • Follow the steps defined as part of: ItemSense Side-by-Side starting at step 3.

  8. If the upgrade was successful, cleanup the backups created:

    sudo rm -rf ~/IS_DB_BACKUP rm is-save*

Upgrade from 2016r4 to 2016r6

Prerequisites

  • Impinj Support (support@impinj.com) has provided the ItemSense key file

Backup data

  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
    

Backup configuration

  1. Install the is-tool Node package. The is-tool has its own set of documentation and prerequisites that can be found here: https://www.npmjs.com/package/is-tool This tool can be installed on any host that has network access to the ItemSense instance.

    $ npm install -g is-tool

  2. Use is-tool to save the configuration from the 2016r4 instance.

    $ is-tool save -i TARGET_SERVER -u admin -p admindefault

    No file specified to save. generating a filename.
    Connecting to ItemSense: {"username":"admin","password":"admindefault","itemsenseUrl":"http://TARGET_SERVER/itemsense"}
    Wrote: is-save-2017-07-26T16:50:30.772Z.json
    

Installation

  1. Place the ItemSense key file in your ~/.ssh/ directory, where ~ is the home directory of the user performing the upgrade

  2. Copy the installation archive to the ItemSense server

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

  3. Continue from step 2 of the Install Instructions section above

Migrate data

  1. Use is-tool to convert your 2016r4 data to 2016r6 format

$ is-tool convert -i TARGET_SERVER is-save-2017-07-26T16:50:30.772Z.json

  1. Load the converted config into the upgraded ItemSense server

$ is-tool load -t TARGET_SERVER is-save-2017-07-26T16:50:30.772Z-converted.json

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:

    • IP_ADDRESS_RANGE is the range of the addresses which should be handed out to the docker managed networks. Example: 192.168.111/24
    • IP_ADDRESS_GATEWAY is 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 is the home directory of the user used when installing ItemSense.
  • DATE is 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.