Node.js API-wrapper library for Impinj ItemSense
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


A simple Node.js API-wrapper library for Impinj's ItemSense.
For more information about ItemSense, check out


$ yarn add itemsense-node

Note: We recommend Yarn as the dependency manager for javascript projects. You are free to use NPM or Yarn interchangeably, but using Yarn protects against version drift of a project's dependencies, which NPM struggles with.


Each itemsense-node API request returns a promise that will resolve when the operation has been completed. For more information about promises, check out the npm package request-promise.

Basic Usage

var ItemSense = require('itemsense-node');	 // Require itemsense-node package to get started

var itemsenseConfig = {};  // Create itemsense config json object, or read one in
itemsenseConfig.username = 'admin';
itemsenseConfig.password = 'admindefault';
itemsenseConfig.itemsenseUrl = '';

var itemsense = new ItemSense(itemsenseConfig); // Instantiate new ItemSense instance

// Run a sample request
itemsense.items.get().then(function(response) {

Table of Contents

  1. ItemSense Configuration
  2. Authorization Tokens
  3. Users
  4. Facilities
  5. Zone Maps
  6. Current Zone Map
  7. Reader Definitions
  8. Reader Configurations
  9. Thresholds
  10. Threshold Antenna Configuration
  11. Recipes
  12. Jobs
  13. Message Queue
  14. Items
  15. Health
  16. Software Updates
  17. Settings
  18. Support
  19. Consuming Message Queues

ItemSense Configuration

Property Description
itemsenseUrl The base URL for your itemsense instance. e.g.
authToken The authorization token for your itemsense instance. Users have the option of either providing an auth token or username and password for itemsense credentials
username The username for your itemsense credentials. This will be used to encode your requests with a basic auth header. This is optional if you are instead providing an authToken.
password The password for your itemsense credentials. This will be used to encode your requests with a basic auth header. This is optional if you are instead providing an authToken.

Authorization Tokens

For information about token authentication, visit

itemsense.authentication.getToken(username) // creates a token for given user

itemsense.authentication.validateToken(id) // validates a specific token id

itemsense.authentication.getAllTokens(username) // retrieves all tokens available for a specific user

itemsense.authentication.revokeToken(token) // revokes a token

itemsense.authentication.revokeAllTokens(username) // revokes all tokens available for a specific user


For information about users, visit

itemsense.users.get(username) // returns a user object based on username

itemsense.users.getAll() // returns all of the users for an itemsense instance

itemsense.users.create(user) // creates a user

itemsense.users.update(user) // updates a user


For information about facilities, visit

itemsense.facilities.get(facilityName) // returns a facility object based on the name

itemsense.facilities.getAll() // returns all of the facilities for an itemsense instance

itemsense.facilities.create(facilityName) // Create a new facility (but do not replace an existing one)

itemsense.facilities.createOrReplace(facilityName) // Replace an existing facility in the store, or creates a new one

itemsense.facilities.update(facilityName) // Aliases .createOrReplace()

Zone Maps

For information about zone maps, visit

itemsense.zoneMaps.get(zoneMapName) // returns a zone map object based on the name

itemsense.zoneMaps.getAll() // returns all of the zone maps for an itemsense instance

itemsense.zoneMaps.create(zoneMap) // creates a zone map

itemsense.zoneMaps.update(zoneMap) // updates a zone map

Current Zone Map

itemsense.currentZoneMap.get(facilityName) // returns the current zonemap for a specific facility

itemsense.currentZoneMap.update(zoneMapName) // updates/sets the current zone map

itemsense.zoneMaps.clear(facilityName) // clears the current zone map value

Reader Definitions

For information reader definitions, visit

itemsense.readerDefinitions.get(readerDefinitionName) // returns a reader definition object based on the name

itemsense.readerDefinitions.getAll() // returns all of the reader definitions for an itemsense instance

itemsense.readerDefinitions.create(readerDefinition) // creates a reader definition

itemsense.readerDefinitions.update(readerDefinition) // updates a reader definition

itemsense.readerDefinitions.delete(readerDefinitionName) // deletes a reader definition based on the name

itemsense.readerDefinitions.groups() // returns an array of all configurationed group names

itemsense.readerDefinitions.getAllFeatures(readerName) //Get the status of all the features of a reader

itemsense.readerDefinitions.setFeature(readerName) //Set the status of a single feature of reader

itemsense.readerDefinitions.getFeature(readerName, featureName) //Get the status of a single feature of reader

Reader Configurations

For information about reader configurations, visit

itemsense.readerConfigurations.get(readerConfigurationName) // returns a reader configuration object based on the name

itemsense.readerConfigurations.getAll() // returns all of the reader configurations for an itemsense instance

itemsense.readerConfigurations.create(readerConfiguration) // creates a reader configuration

itemsense.readerConfigurations.update(readerConfiguration) // updates a reader configuration

itemsense.readerConfigurations.delete(readerConfigurationName) // deletes a reader configuration based on the name


For more information on Thresholds, visit

// Get an array of all the threshold configuration objects
// embed - (optional) An object to specify which JSON objects should be embedded
//         in the threshold response object. Currently, only
//         'antennaConfiguration'.
//         Example: { embed: ['antennaConfiguration'] }

// Get a single threshold configuration object
// embed - (optional) Same as for getAll method above.
itemsense.thresholds.get(thresholdId, embed)

// Create a threshold

// Update an existing thresold
itemsense.thresholds.update(thresholdId, thresholdConfigObject)

// Remove a threshold

Threshold Antenna Configurations

For more information on Threshold Antenna Configurations, visit

//Get all the configured Threshold Antenna Configurations

//Get a single configured Threshold Antenna Configuration

//Create a new Threshold Antenna Configuration

//Update an existing Threshold Antenna Configuration
itemsense.antennaConfigurations.update(antennaConfigurationId, antennaConfOjbject)

//Delete an exiting configured Threshold Antenna Configuration


For information about recipes, visit // returns a recipe object based on the name // returns all of the recipes for an itemsense instance // creates a recipe // updates a recipe // deletes a recipe based on the name


For information about jobs, visit // returns a job object based on the id // returns all of the jobs for an itemsense instance // starts a job // stops a job based on the id // retrieves the job stats for a specific job

Message Queue

Deprecated: This functionality was moved to Items. For information about message queues, visit

itemsense.messageQueue.configure(messageQueue) // configures the message queue


For information about items, visit

itemsense.items.get(queryParams) // Retrieves items from ItemSense, takes in an option query params object

itemsense.items.getHistory(queryParams) // Retrieves item history records from ItemSense, takes in an optional query params object

itemsense.items.configureQueue(filter, options) // Configure a queue to receive item event messages with the given filter and options


For information about transitions, visit

itemsense.transitions.get(queryParams) // Retrieves transition events from ItemSense, takes in an optional query params object

itemsense.transitions.configureQueue(filter, options) // Configure a queue to receive transition event messages which match the given filter and options


For information about Reader Health, visit // Retrieves health events from ItemSense, accepts an optional query object, options) // Configure a queue to receive health event messages with the given filter and options // Get status for all current readers // Get status for a given reader. Accepts string readerID.

Software updates

For information about Software Update Functionality, visit

itemsense.softwareImages.get(imageType, imageName) // Download a software image

itemsense.softwareUpgrades.getAll() // Returns the ids for all the upgrade jobs

itemsense.softwareUpgrades.get(upgradeInstanceId) // Returns the status of a specific upgrade job

itemsense.softwareUpgrades.start(upgradeData) // Adds and schedules a new upgrade task

itemsense.softwareUpgrades.stop(upgradeInstanceId) // Cancels a specific upgrade job

itemsense.softwareUpgrades.trigger(upgradeData) // Injects a dummy upgrade task for a reader

itemsense.softwareVersions.createOrReplace(readerSoftwareVersionData ) // Update a software version metadata record (no policy enforcement)

itemsense.softwareVersions.destroy(imageType, softwareVersionId) // Remove a specific VersionInfo by ImageType and VersionId

itemsense.softwareVersions.list(imageType) // Show all versions of an ImageType by VersionPolicy

itemsense.softwareVersions.get(imageType, softwareVersionId) // Show a specific VersionIno by ImageType and VersionId

itemsense.softwareVersions.update(versionPolicyObj) // Update the version policy for a reader software version

Settings - SNMP

For information about SNMP Settings, visit

itemsense.settings.get() // Returns the current SNMP settings

itemsense.settings.configure(settingsObject) // Updates SNMP settings based on a configuration object

itemsense.settings.disable() // Disables SNMP and deletes any configuration


For information about the Support endpoints, visit


Get all the configuration elements within an ItemSense instance in tar.gz format.

// Get all of ItemSense's configuration as a tar.gz file

The writeLocation parameter is an optional string which when specified, provides a path (and file name) to which the configuration tar.gz file should be written. Once written a resolved promise is returned containing a success message. If there is an error when writing to the specified location, a rejected promise is returned containing a description of the error.

If writeLocation isn't specified the raw binary tar.gz blog of data is returned in a resolved Promised which the caller must handle.


Get the logs of ItemSense in tar.gz format.

itemsense.logs.get(queryParamsObject, writeLocation);

A javascript object may be passed containing the keys from, to and extended. A description of what these keys do can be found in the API document linked above.

For a description of the writeLocation parameter, see the Configuration section above.

Consuming Message Queues

For resources that expose message queues (health, transitions and items), we provide a configureAndSubscribe helper to facilitate consuming new messages. Call it just like you would the configureQueue method. It returns a promise that resolves to an event emitter.

This object will emit data events as new messages are sent on the queue, or error events if there are issues with the connection:

itemsense.items.configureAndSubscribe(filter, options).then(queue => {
  queue.on('data', data => console.log("A js object: ", data) );
  queue.on('error', err => console.log(err) );
  // The messages contents are provided as a pre-parsed json object.

The queue object will also emit status events as it proceeds with configuring and connecting to the AMQP service. You can use these to help debug or track the progress of the connection:, options).then(queue => {
  queue.on('status', msg => console.log(msg) );
  // This will broadcast:
  // 'connection': a connection has successfully been established to the AMQP server
  // 'queue': a queue has successfully been opened
  // 'listening': a subscription to the queue has successfully been established, we are now listening for data

Alternatively, the queue object will also emit "connection lifecycle" events as it proceeds with configuring and connecting to the AMQP service:, options).then(queue => {
  queue.on('connectionEstablished', connectionObject => console.log('Connected!') );
  queue.on('queueEstablished', amqpQueueObject => console.log('Queue Established!') );
  queue.on('listening', () => console.log('Listening for Data!') );

Note that:

  • On connectionEstablished, the event handler is passed the AMQP Connection object.
  • On queueEstablished, the event handler is passed the raw AMQP Queue object.
  • On listening, nothing is passed to the event handler.