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 https://developer.impinj.com.
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.
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');
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
is-tool load -i 10.200.90.177 itemsense-config.json
is-tool load -i 10.200.90.177 --addpassword itemsense-config.json
is-tool convert -t to2016r6 itemsense2016r4-config.json
is-tool convert -t threshold itemsense2016r4-config.json
is-tool clear -i 10.200.90.177
is-tool remove -i 10.200.90.177 itemsense-config.json
is-tool set -i 10.200.90.177 itemsense-config.json
is-tool help
or
is-tool save --help
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.
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.
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.
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:
- The antennaConfiguration name
11-F0-0A-center
is specified as theantennaConfigurationId
value. - 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.
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 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
.
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.
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.
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.
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');
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.
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.
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.
isToolLib.clear(itemsense);
Where: itemsense - is an instance of an itemSense connection object as provided by the itemsense-node package.
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.
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 totrue
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 totrue
tells is-tool to set a password on t user being loaded.
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.
- Fork the repository.
- Create your feature branch:
git checkout -b my-new-feature
- Make changes and added test cases for changes.
- Run tests:
npm run tests
- 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. - Lint:
npm run linter
- Commit your changes:
git commit -am 'Add some feature'
- Push to the branch:
git push origin my-new-feature
- Submit a pull request.
This tool uses the Apache v2.0 license. See the LICENSE file.