is-tool

Synopsis

is-tool is a command line tool and small set of library functions to perform helpful tasks against Impinj ItemSense®. The command line aspect of is-tool is essentially an interface to the library functions.

The command line tool performs the following primary tasks:

• Stores all ItemSense configuration into a file in JSON format.
• Loads ItemSense configuration from a file.
• Converts configuration file formats.
• Replace existing configuration.
• Delete specified configuration.
• Remove all configuration.

• This tool is under active development and may contain bugs. It is presented as-is, a configuration helper tool for ItemSense. If bugs are found, please raise an Issue.*
  For more information about ItemSense, check out http://developer.impinj.com.

Getting Started

Prerequisites

As is-tool is a Node.js based tool, to run it you will need both NPM and Node.js installed on your system. Both can be downloaded from here (installing the Node.js gives you both the npm and node commands). Any NodeJs version above 8.9.4 is required.

Installation

To install is-tool as a command line tool from an NPM repository run:

npm install -g is-tool

The tool should now be accessible from any location by the installation user.

To use the library functions provided by is-tool just include the tool in your package.json file as dependency. Example:

"is-tool": "^0.2.0"

Then import the library into your project. Example:

const isToolLib = require('is-tool');

Command Line Example

The following are examples on how to use the command line tool. A more complete description of each task is below.

Save Config

is-tool save -i 10.200.90.177 itemsense-config.json

Load Config

is-tool load -i 10.200.90.177 itemsense-config.json

Convert Format

is-tool convert -t to2016r6 itemsense2016r4-config.json

is-tool convert -t threshold itemsense2016r4-config.json

Clear All Config

is-tool clear -i 10.200.90.177

Remove Config

is-tool remove -i 10.200.90.177 itemsense-config.json

Set Config

is-tool set -i 10.200.90.177 itemsense-config.json

Help

is-tool help

or

is-tool save --help

Usage

Command Line

The command line tool git-style sub-tasks in the format of:

is-tool <task>

Each of these sub-tasks have their own help menu which shows the task specific options.

Save

This command dumps all ItemSense configuration to a fill specified file. If no filename is given then one is generated.

Usage: is-tool save [options] [file]

Options	Description
[file]	The filename to write the configuration to. If not specified, is-tool will create a file in the current directory in the format of is-save-.json
-h, --help	Output usage information for the task
-i --ip <ipaddr>	ItemSense IP address from which to save the configuration.
-u --user <user>	An ItemSense username for an admin level user.
-p --pass <pass>	ItemSense password for the above user.

The IP address is mandatory but username and password are optional. If they are not specified, is-tool will use the ItemSense default administration username and password.

Load

This command loads configuration from a specified file.

Usage: is-tool load [options] <file>

Options	Description
<file>	The filename to read configuration from.
-h, --help	Output usage information for the task
-i --ip <ipaddr>	ItemSense IP address from which to save the configuration
-u --user <user>	An ItemSense username for an admin level user
-p --pass <pass>	ItemSense password for the above user
-f --facility <pass>	Name of new facility in which to add readers

The IP address is mandatory but username and password are optional. If they are not specified, is-tool will use the ItemSense default administration username and password.

Special Handling for Users

The load command will not load users that already exist in the system. Note that this check is done based on the name attribute of the user. Even if the user has a different set of roles or a different password, as long as the name of the loaded user matches the name of a user in the system, it will not be loaded in.

Threshold AntennaConfigurationId Name Replacement

There is some special handling performed when using is-tool to load new antennaConfigurations and thresholds in the same object/file. AntennaConfigurations are keyed on id which is generated by ItemSense when a new antennaConfiguration is loaded. Thresholds reference an antennaConfiguration using this id value. However, there is no way to know what this value will be until after the antennaConfiguration has been loaded into ItemSense.

To specify both antennaConfigurations and thresholds in a single object, is-tool allows the antenna configuration name to be specified instead of the antennaConfigurationId.

For example:

{
  "antennaConfigurations": [
    {
      "out": [
        {
          "antennaId": 7
        }
      ],
      "name": "11-F0-0A-center",
      "in": [
        {
          "antennaId": 6
        }
      ]
    }
  ],
  "thresholds": [
    {
      "name": "myThreshold",
      "facility": "DEFAULT",
      "readerArrangement": "OVERHEAD",
      "readers": {
        "xSpan-11-F0-0A": {
          "antennaConfigurationId": "11-F0-0A-center"
        }
      }
    }
  ]
}

In the above example:

1. The antennaConfiguration name 11-F0-0A-center is specified as the antennaConfigurationId value.
2. Once the antennaConfiguration is loaded, the allocated ID is used to replace "11-F0-0A-center" as the antennaConfigurationId value before the threshold is loaded.

Special Handling for Configs Keyed on ID

As antennaConfigurations and thresholds use an id field as the primary identifier but also require the name field to be unique, is-tool load will perform different behaviour depending on what is in the configuration being loaded and what already exists in ItemSense. The table below describes the actions taken by is-tool in each scenario to load the configuration. The table columns are:

• Has ID - The configuration being loaded contains the ID field.
• ID Exists - ID in configuration being load already exists in ItemSense.
• Name Exists - Name in configuration being loaded already exists in itemSense.
• Behaviour - The resultant actions is-tool will perform.

Has ID	ID Exists	Name Exists	Behaviour
No	No	No	Send a create request
No	No	yes	Copy id from existing record with the same name into config being loaded and send update request
Yes	No	No	Remove the id field from the config being loaded and send create request
Yes	No	Yes	Copy id from existing record with the same name into config being loaded and send update request
Yes	Yes	No	Remove id from config being loaded and send create request
Yes	Yes	Yes	No special action taken, is-tool just sends an update request

Convert

Convert an ItemSense config files. Either convert a configuration file from ItemSense 2016r4 to 2016r6 format or convert ItemSense Threshold prototype format to ItemSense 2017r1 threshold format.

Usage: is-tool convert [options] <file>

Options	Description
[file]	The filename to read configuration from.
-t --converttype	The conversion type, one of 'to2016r6' or 'threshold'.
-f --facility	The name of the facility in which the converted thresholds should belong. Only applies when converttype of threshold is used.

The output file containing the converted configuration will be placed in the same location as the input file except that it's name will have "-converted" appended to it.

So is-save-r4.json becomes is-save-r4-converted.json.

Clear

This command removes all configuration from an ItemSense instance. The default behavior is to preserve the Impinj default configuration but this can be overridden with the completeclear flag.

Usage: is-tool clear [options]

Options	Description
-h, --help	Output usage information for the task
-i --ip <ipaddr>	ItemSense IP address from which to save the configuration.
-u --user <user>	An ItemSense username for an admin level user.
-p --pass <pass>	ItemSense password for the above user.
-c --completeclear	Remove everything including Impinj Defaults.

The IP address is mandatory but username and password are optional. If they are not specified, is-tool will use the ItemSense default administration username and password.

Remove

This command removes all configuration specified in a file. If the specified configuration isn't present in the ItemSense instance then it will be silent ignored. The configuration file takes the same format as what it produce by the save command. However, each configuration block only need to contain the name attribute. The other attributes are ignore.

Example:

{
  "readerConfigurations": [
    {
      "name": "SPEEDWAY_2"
    },
    {
      "name": "SPEEDWAY_4"
    }
  ]
}

Usage: is-tool remove [options] <file>

Options	Description
<file>	The filename containing the configuration to remove.
-h, --help	Output usage information for the task
-i --ip <ipaddr>	ItemSense IP address from which to save the configuration
-u --user <user>	An ItemSense username for an admin level user
-p --pass <pass>	ItemSense password for the above user

The IP address is mandatory but username and password are optional. If they are not specified, is-tool will use the ItemSense default administration username and password.

Set

This command is effectively a combination of the clear and load commands. While the load command adds configuration to existing configuration, the set command effectively sets all ItemSense configuration to what is specified in the configuration file. It does this by first removing all configuration from ItemSense before loading the configuration specified in the configuration file. As with the clear command, the default behavior is to preserve the Impinj default configuration but this can be overridden with the completeclear flag.

Usage: is-tool set [options] <file>

Options	Description
<file>	The filename containing the configuration to remove.
-h, --help	Output usage information for the task
-i --ip <ipaddr>	ItemSense IP address from which to save the configuration
-u --user <user>	An ItemSense username for an admin level user
-p --pass <pass>	ItemSense password for the above user
-f --facility <pass>	Name of new facility in which to add readers
-c --completeclear	Remove everything including Impinj Defaults.

The IP address is mandatory but username and password are optional. If they are not specified, is-tool will use the ItemSense default administration username and password.

Library functions

All of these functions perform the same function as their command line equivalents. Also, each function returns a native promise.

To use the library it must be imported:

const isToolLib = require('is-tool-lib');

Save

The save function looks like the following:

isToolLib.save(itemsense, fileLocation, buildVersion);

Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package. fileLocation - is the location and filename for where *is-tool should write the configuration file. buildVersion - This is the itemsense version that will be embedded exported data.

Load

The load function looks like the following:

isToolLib.load(itemsense, object, facility);

Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package. object - is a javascript object which should contain 1 or more of the following keys:

• "facilities"
• "readerDefinitions"
• "readerConfigurations"
• "antennaConfigurations"
• "thresholds"
• "recipes"
• "zoneMaps"
• "users" Each of these keys should then contain an array of one or more objects of the appropriate format. The output from is-tool save is in the correct form. This tool also accepts the configuration export created using itemsense-viztool-js.

Example of the format:

{
  "facilities": [],
  "readerDefinitions": [],
  "readerConfigurations": [],
  "antennaConfigurations": [],
  "thresholds": [],
  "recipes": [],
  "zoneMaps": [],
  "users": [],
  "currentZoneMap": []
}

facility - A string name of the new facility in which to add readers.

If a configuration object already exists within ItemSense, it is updated.

Convert

The convert function looks like the following:

isToolLib.convert(object);

or

isToolLib.convert(object, facilityName);

Where: object - is a javascript object which should contain ItemSense 2016r4 formatted configuration. facilityName - is the name of the facility in which the converted thresholds should belong.

Clear

isToolLib.clear(itemsense);

Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package.

Remove

isToolLib.clear(itemsense, object);

Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package. object - is a javascript object containing the objects to be removed. The description of this object is above.

Set

isToolLib.set(itemsense, configObject)

Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package. object - is a javascript object containing the following attributes:

• configToLoad - (Mandatory) An object containing the configuration to load after the itemSense instance has been cleared.
• completeClear - (Optional) A boolean which when set to true prevents the Impinj defaults from remaining in the ItemSense instance.
• facility - (Optional) A string name of the new facility in which to add readers.

Get

This library function gets all configuration from an itemSense instance and returns the results in a promise as a java object. In order to embed version info in the exported data, get accepts a buildVersion parameter which will be directly embedded in the returned object. The library is unable to fetch this information from itemsense on it's own.

isToolLib.get(itemsense, buildVersion)

Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package.

ItemSense API Compatibility

is-tool doesn't interact with all API endpoints specified in the ItemSense API Guide. While for some endpoints this may seem understandable, for other endpoints it is not so clear. The following is a list of API endpoint sections (as denoted in the ItemSense API Guide) which is-tool does not interact with whatsoever due to them not being endpoint for gathering or setting configuration data:

• Support
• Jobs
• Health
• Items
• Software
• Authentication

Contributing

1. Fork the repository.
2. Create your feature branch: git checkout -b my-new-feature
3. Make changes and added test cases for changes.
4. Run tests: npm run tests
5. Verify coverage: npm run tests --coverage Note; this produces a coverage/ directory in the base folder which will contain coverage results which can be displayed in a browser.
6. Lint: npm run linter
7. Commit your changes: git commit -am 'Add some feature'
8. Push to the branch: git push origin my-new-feature
9. Submit a pull request.

This tool uses the Apache v2.0 license. See the LICENSE file.