node package manager

is-tool

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 6.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
is-tool load -i 10.200.90.177 --addpassword itemsense-config.json

Convert Format

is-tool convert -t to2016r6 itemsense2016r4-config.json
<<<<<<< HEAD
is-tool convert -t threshold itemsense2016r4-config.json
=======
is-tool convert itemsense2016r4-config.json
>>>>>>> 6e446cf2fde971d5d33f407e8e5481e2ecbc488f

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
-a --addpassword Add a default password of 'default01' to a user. Necessary when adding a new user to the system.
-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.

The --addpassword option is provided because it's not possible to get a user's password when querying for user configuration. This means if you used is-tool save to get the configuration of an ItemSense instance (including user configuration) with the intention to load it into a brand new clean ItemSense instance, a password has to be added to each user configuration before it can be loaded. This option does that for you.

Threshold AntennaConfigurtionId Name Replacement

There is some special handling performed when using is-tool to load new anntennaConfigurations and thresholds in the same object/file. AntennaConfigurations are now 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 antennaConfiguraion 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 now 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 the what is in the configuration being loaded and what already exists in ItemSense, . The table below describes the actions to take. The table columns are:

  • Has ID - The configuring being loaded contains the ID field.
  • ID Exists - ID in configurtion being load already exists in ItemSense.
  • Name Exists - Name in configuraton 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 specific 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
-a --addpassword Add a default password of 'defualt01' to a user. Necessary when adding a new user to the system. The password won't be added if the user already exists
-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. The --addpassword option is provided because it's not possible to get a user's password when querying for user configuration. This means if you used is-tool save to get the configuration of an ItemSense instance (including user configuration) with the intention to load it into a brand new clean ItemSense instance, a password has to be added to each user configuration before it can be loaded. This option does that for you.

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);

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.

Load

The load function looks like the following:

isToolLib.load(itemsense, object, facility, addPassword);

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": []
}

facility - A string name of the new facility in which to add readers. addPassword - A boolean flag which when set to true tells is-tool to set a password on t user being loaded.

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.
  • addPassword - (Optional) A boolean flag which when set to true tells is-tool to set a password on t user being loaded.

Get

This library function gets all configuration from an itemSense instance and returns the results in a promise as a java object.

isToolLib.get(itemsense)

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

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.