Load, Save and Delete ItemSense configuration
npm install is-toolis-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.
npm and node commands). Any NodeJs version above 8.9.4 is required.``bash`
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:js`
const isToolLib = require('is-tool');
The following are examples on how to use the command line tool. A more complete description of each task is below.
is-tool save -i 10.200.90.177 itemsense-config.json
$3
is-tool load -i 10.200.90.177 itemsense-config.json
$3
is-tool convert -t to2016r6 itemsense2016r4-config.json
is-tool convert -t threshold itemsense2016r4-config.json
$3
is-tool clear -i 10.200.90.177
$3
is-tool remove -i 10.200.90.177 itemsense-config.json
$3
is-tool set -i 10.200.90.177 itemsense-config.json
$3
is-tool help
or
is-tool save --help
Usage
$3
The command line tool git-style sub-tasks in the format of:
is-tool
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:
|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 \ |ItemSense IP address from which to save the configuration.|
| -u --user \ |An ItemSense username for an admin level user. |
| -p --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:
|Options|Description|
|--------|------------|
|\|The filename to read configuration from.|
| -h, --help |Output usage information for the task|
| -i --ip \ |ItemSense IP address from which to save the configuration|
| -u --user \ |An ItemSense username for an admin level user |
| -p --pass \ |ItemSense password for the above user |
| -f --facility \ |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
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:
`js
{
"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
is specified as the antennaConfigurationId value.
1. 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 loaded 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|Overwrite id in record being loaded with id from existing record with the same name and send 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] |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
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 \ |ItemSense IP address from which to save the configuration.|
| -u --user \ |An ItemSense username for an admin level user. |
| -p --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
attribute. The other attributes are ignore.Example:
`js
{
"readerConfigurations": [
{
"name": "SPEEDWAY_2"
},
{
"name": "SPEEDWAY_4"
}
]
}
`
Usage: |Options|Description|
|--------|------------|
|\|The filename containing the configuration to remove.|
| -h, --help |Output usage information for the task|
| -i --ip \ |ItemSense IP address from which to save the configuration|
| -u --user \ |An ItemSense username for an admin level user |
| -p --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
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] |Options|Description|
|--------|------------|
|\|The filename containing the configuration to remove.|
| -h, --help |Output usage information for the task|
| -i --ip \ |ItemSense IP address from which to save the configuration|
| -u --user \ |An ItemSense username for an admin level user |
| -p --pass \ |ItemSense password for the above user |
| -f --facility \ |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.
$3
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:
js
const isToolLib = require('is-tool-lib');
`#### Save
The save function looks like the following:
js
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:
js
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 in the correct form. This tool also accepts the configuration export created using itemsense-viztool-js.Example of the format:
`js
{
"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:
js
isToolLib.convert(object);
`
or
js
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
js
isToolLib.clear(itemsense);
`
Where:
itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package.#### Remove
js
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
js
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:
* - (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.
`js
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:
*
*
*
*
*
* Contributing
1. Fork the repository.
1. Create your feature branch:
1. Make changes and added test cases for changes.
1. Run tests:
1. Verify coverage: Note; this produces a coverage/ directory in the base folder which will contain coverage results which can be displayed in a browser.
1. Lint: npm run linter
1. Commit your changes:
1. Push to the branch: This tool uses the Apache v2.0 license. See the LICENSE file.