API Reference

Introduction

ItemSense is a software platform that aggregates and transforms torrents of raw RAIN RFID data into real-time, business-driven Item Intelligence.

The platform provides REST APIs for user and system configuration, and item and reader health query; as well as an AMQP interface for item events, reader health events, and threshold transition events.

All REST API endpoints in this document are specified using a BASE_URL placeholder. To call the API, replace this placeholder with the concatenation of the hostname or IP address of the ItemSense server and the string itemsense. For example, if the ItemSense server is running at: http://itemsense.company.com, then the BASE_URL is: http://itemsense.company.com/itemsense.

System Configuration, Monitoring and Management

Users are added to the system. Users can be configured with authorization roles, which gives them access to different parts of the API.

The Health of the configured readers is monitored, either via the REST query interface, or the AMQP event queue.

Reader Software (firmware) versions can be queried and upgraded.

The Support endpoints are used to export logs and configuration, to aid troubleshooting.

RFID Configuration

RFID configuration consists of specifying Reader Definitions (one per reader) and associated Reader Configurations.

Readers (and the items that they identify, locate and track) can be associated with a Facility, a Floor and a Zone within that facility.

A Recipe specifies the association between the readers and their configurations. Many readers can share the same configuration.

A Job is used to start and stop recipes.

Item Data Query and Events

Once the readers and their configurations have been specified, and a job is running within a facility, information about the Items can be returned, either via the REST API, or by configuring and subscribing to a Message Queue.

There are REST API endpoints for the current Items, Item History and Item Threshold Transitions.

There are Item event queues for Item events and Item Threshold Transition events.

Authorization

Access to the endpoints of the APIs is restricted by the roles of the user performing the call to the API.

ItemSense users can have one or more of the following roles:

  • Admin: has access to all endpoints
  • ConfigManager: has access to all configuration endpoints
  • JobRunner: has access to all job endpoints
  • DataReader: has access to the item data endpoint

The roles of a user are configured when the user is created or updated.

In this document, specific authorizations are shown for each endpoint.

Users

ItemSense users can be created with full or limited permissions to access each API. A user’s role(s) determine which permissions they do and do not have. A user can have multiple roles. A role is one of DataReader, JobRunner, ConfigManager, Admin. Only a user with the Admin role can list and manipulate users.

Create

Create a user

Authorized Roles

Admin

HTTP Request

POST http://BASE_URL/configuration/v1/users/create

Request Body

Parameter Type Description
name String Name of the user to create.
password String Password for the user.
roles Array A set of roles to assign to the user.

Response

Parameter Type Description
name String The Username
roles Array of: String The roles corresponding to the user

Sample Code

var user = {};
user.name = "ItemSenseUser";
user.password = "1mp1njer";
user.roles = ["DataReader"];

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/users/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(user));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    user = "ItemSense",
                    password = "1mp1nj!",
                    roles = {"DataReader"}
                });

    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}




Sample Response


{
  "name":"ItemSenseUser",
  "roles":["DataReader"]
}

Create or Replace

Replace an existing user, or create a new one

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/users/createOrReplace

Request Body

Parameter Type Description
name String Name of user to create.
password
(optional)
String Password for the user. Optional during updates.
roles Array A set of roles to assign to the user.

Response

Parameter Type Description
name String The Username
roles Array of: String The roles corresponding to the user

Sample Code

var user = {};
user.name = "ItemSenseUser";
user.password = "1mp1nj!";
user.roles = ["DataReader", "Admin", "JobRunner"];

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/users/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(user));
string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    user = "ItemSense",
                    password = "1mp1nj!",
                    roles = { "DataReader",
                              "Admin",
                              "JobRunner"
                            }
                });

    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}




Sample Response


{
  "name":"ItemSenseUser",
  "roles":["DataReader"]
}

Delete

Delete a specific user.

Authorized Roles

Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/users/destroy/{username}

Parameters

Parameter Type Description
username String The name of the user to delete

Response

This endpoint returns an empty response

Sample Code


var userName = "ItemSenseUser";
var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/users/destroy/" + userName, true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));
string userName = "ItemSenseUser";

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/destroy" + userName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific user.

Authorized Roles

Admin

Http Request

GET http://BASE_URL/configuration/v1/users/show/{username}

Parameters

Parameter Type Description
username String The username of the user to retrieve

Response

Parameter Type Description
name String The name of the user
roles Array of: String The roles corresponding to the user

Sample Code

var userName = "ItemSenseUser";
var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/users/show/" + userName, true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string specificUser = "ItemSenseUser";
Uri uri = new Uri("http://BASE_URL/configuration/v1/users/show" + specificUser);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "ItemSenseUser",
    "roles": [
      "DataReader"
    ]
}

Get All

Retrieve all of the users.

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/configuration/v1/users/show

Parameters

Parameter Type Description
role String An optional role name. Only users with this role will be returned.

Response

Array of:

Parameter Type Description
name String The name of the user
roles Array of: String The roles corresponding to the user

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/users/v1/show", true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/users/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response


[
  {
    "name": "DataReader",
    "roles": [
      "DataReader"
    ]
  },
  {
    "name": "ItemSenseUser",
    "roles": [
      "DataReader"
    ]
  },
  {
    "name": "JobRunner",
    "roles": [
      "JobRunner"
    ]
  },
  {
    "name": "SuperAdmin",
    "roles": [
      "Admin"
    ]
  }
]

Get the Current User

Show the user corresponding to the API call

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/configuration/v1/users/currentUser

Response

Parameter Type Description
name String The name of the user
roles Array of: String The roles corresponding to the user

Show the User Roles

Display the list of roles that can be assigned to users

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/configuration/v1/users/roles/show

Response

Array of:

Parameter Type Description
role String A role that the user can be assigned

Authentication

Itemsense users have two options for Authenticating:

  • HTTP Basic Authentication with the user’s Itemsense Credentials
  • Token-based authentication, using our Authentication API.

To use token-based authentication for authorizing API calls, you must set the Authorization request header with the token value. For example:

Headers['Authorization'] = 'Token {"token": "128faacd-e4bb-4687-90e0-af2836b2c098"}'

If you do not have basic credentials, then a user with administrative privileges must generate a token for you.

Note: The AMQP interface does not support token-based authentication. You must use basic authentication for connecting to an AMQP queue.

Get a Token

In order to begin using the token-based authentication mechanism, you must first get a token. This call requires you (or an administrator) to supply Basic Auth credentials.

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/token/{username}

Parameters

Parameter Type Description
username String Name of user for which to create token

Response

Parameter Type Description
token String The value of the token in UUID format

Sample Response

{
  "token": "128faacd-e4bb-4687-90e0-af2836b2c098"
}

Get a Token for the current user

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/authentication/v1/token

Response

Parameter Type Description
token String The value of the token in UUID format

List Tokens

List all tokens for a specific user.

Authorized Roles

Admin

HTTP Request

GET http://BASE_URL/authentication/v1/listTokens/{username}

Parameters

Parameter Type Description
username String Name of user for which to list tokens

Response

An array of:

Parameter Type Description
authenticationToken AuthenticationToken The token
issued String Date of issue of the token in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
username String Username associated with token
lastUsed String When the token was last used in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
valid Boolean Whether the token is valid

Revoke Token

Revoke a specific authentication token.

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/revokeToken

Request Body

Parameter Type Description
token String The value of the token in UUID format

Response

This endpoint returns an empty response

Revoke Tokens

This method is used to revoke all tokens for a specific user

Authorized Roles

Admin

HTTP Request

PUT http://BASE_URL/authentication/v1/revokeTokens/{username}

Parameters

Parameter Type Description
username String Name of user for which to revoke tokens

Response

This endpoint returns an empty response

AuthenticationToken

Parameters

Parameter Type Description
token String The value of the token in UUID format

Facilities

ItemSense is capable of managing multiple physical locations. Each of these physical locations is called a “Facility”.

Each facility is independently able to run jobs, build zone maps, specify different reader definitions, and query items - though it is also possible to query items across all facilities.

Recipes, reader configurations, and users are shared across all facilities supported by the ItemSense installation.

ItemSense comes pre-loaded with one facility, called ‘DEFAULT’.

Scenarios for facilities:

ItemSense is only using one facility

No additional configuration is necessary, and the facility name will not be required for other API endpoints.

ItemSense is using multiple facilities

The following API endpoints require a facility to be specified as part of the request body:

  • Jobs
    • Start
  • Zone Maps
    • Create
    • Create or Replace
  • Reader Definitions
    • Create
    • Create or Replace

Create

Create a new facility (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/facilities/create

Request Body

Property Type Description
name String The name associated with the facility. This name is used as the identifier for retrieving, updating, and deleting a facility. It is also used as the primary identifier for a facility in other API calls, where required.

Sample Code

var facility =  { "name": "Warehouse-123" };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/facilities/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(facility));


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "Warehouse-123"

                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

{
    "name": "Warehouse-123"
}

Create or Replace

Replace an existing facility, or create a new one.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/facilities/createOrReplace

Request Body

Property Type Description
name String The name associated with the facility. This name is used as the identifier for retrieving, updating, and deleting a facility. It is also used as the primary identifier for a facility in other API calls, where required.

Sample Code

var facility =  { "name": "Warehouse-123" };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/facilities/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(facility));


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/createOrReplace");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "Warehouse-123"

                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

{
    "name": "Warehouse-123"
}

Delete

Delete a specific facility.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/facilities/destroy/{facilityName}

Parameters

Parameter Type Description
facilityName String The name of the facility to delete

Sample Code

var facilityName = "Warehouse-123";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/facilities/destroy/" + facilityName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string facilityName = "Warehouse-123";

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/destroy/" + facilityName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific facility.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/facilities/show/{facilityName}

Parameters

Parameter Type Description
facilityName String The name of the facility to retrieve

Sample Code

string facilityName = "Warehouse-123";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/facilities/show/" + facilityName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string facilityName = "Warehouse-123";

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/show/" + facilityName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "Warehouse-123"
}

Get All

Retrieve all of the facilities

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/facilities/show

Response

Array of:

Parameter Type Description
name String The name of the facility

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/facilties/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/facilities/show/");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "DEFAULT"
  },
  {
    "name": "Warehouse-123"
  }
]

Zone Maps

Zone Maps are used to divide the facility that is being monitored by ItemSense into spatial regions.

A Zone Map consists of a facility, and a set of named Zones. A Zone allocates the space within a facility in a way that is meaningful to the application (e.g. Men’s, Women’s and Shoe departments in a retail store).

Zone names do not have to be unique. If more than one zone definition has the same name as another, then the spaces of the two (or more) physical zones are combined into one logical zone (e.g. Women’s Shoes might be on the 1st floor and Women’s dresses on the 3rd floor; these could be combined into a “Women’s Clothing” zone).

It is not necessary to define zones for the entire space of a facility. ItemSense assigns tags to the zone name “FACILITY” if they are present and outside of any user-defined zones (or “ABSENT” if the tag is detected with LOW presenceConfidence).

If zones are defined, they cannot overlap in space.

When combined with a reader definition’s spatial coordinates, ItemSense provides powerful location data, such as which zone an item is in, and when an item transitions from one zone to another.

Zone Map Example

Zone Map

  {
    "name": "Contoso_Fashion",
    "facility": "DEFAULT",
    "zones": [
      {
        "name": "Womens",
        "floor": "1",
        "points": [
          {
            "x": 7.0,
            "y": 0.0,
            "z": 0.0
          },
          {
            "x": 0.0,
            "y": 6.0,
            "z": 0.0
          },
          {
            "x": 7.0,
            "y": 20.0,
            "z": 0.0
         },
         {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         },
         {
            "x": 12.0,
            "y": 11.0,
            "z": 0.0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": "1",
        "points": [
          {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
          },
          {
            "x": 28.0,
            "y": 26.0,
            "z": 0.0
          },
          {
            "x": 31.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         }
        ]
      }
    ]
  }

Zones

A Zone consists of a name, an optional floor, and a shape in space. The shape is defined by an array of points in two-dimensional* space, using the Cartesian coordinate system, measured in meters. Each point represents a vertex of the shape. They can be rectangular (requiring two points), or a more complex polygonal shape (requiring more than two points). When defining a polygon, the vertex points must be specified in an order that describes the outside of the polygon (i.e. points next to each other in the list must share an edge of the polygon).

  • The z-dimension of point property is currently set to 0 in all cases.
Property Type Description
name String The name given to the specific zone
floor
(optional)
String The name of the floor where the zone exists
points Array of Point An array of points that define the zone’s boundaries

Points

Property Type Description
x Number The x coordinate of the zone point, in meters from the 0.0,0.0 location in the monitored space.
y Number The y coordinate of the zone point, in meters from the 0.0,0.0 location in the monitored space.
z Number The z coordinate of the zone point. Z is not currently used, and defaults to 0.0 if not specified. While the z property may be omitted, it may not be specified with a null value.

Non-contiguous Zone Example

      {
        "name": "Contoso_Fashion",
        "facility": "DEFAULT",
        "zones": [
          {
            "name": "Womens",
            "floor": "1",
            "points": [
              {
                "x": 7.0,
                "y": 0.0,
                "z": 0.0
              },
              {
                "x": 0.0,
                "y": 6.0,
                "z": 0.0
              },
              {
                "x": 7.0,
                "y": 20.0,
                "z": 0.0
             }
         },
          {
             "name": "Womens",
             "floor": "2",
             "points": [
               {
                 "x": 7.0,
                 "y": 0.0,
                 "z": 0.0
               },
               {
                 "x": 0.0,
                 "y": 6.0,
                 "z": 0.0
               },
               {
                 "x": 7.0,
                 "y": 20.0,
                 "z": 0.0
              }
          }
    

Create

Create a new zone map (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/zoneMaps/create

Request Body

Property Type Description
name String The name associated with a specific zone map. This name will be used as the identifier for retrieving, updating, and deleting a zone map. It will also be used for setting the Current zone map.
facility
(optional, except if using multiple facilities)
String The name of the facility which the zone map will be associated with.
zones Array of Zone A collection of zones that define the geographic coordinates for each zone in the monitored space. Zone definitions cannot overlap.

Response

Parameter Type Description
name String The name associated with the zone map
facility String The facility with which the zonemap is associated
zones Array of: Zone The collection of zones within the zone map

Sample Code


  var zoneMap = {
        "name": "Contoso_Fashion",
        "facility": "DEFAULT",
        "zones": [
          {
            "name": "Womens",
            "floor": "1",
            "points": [
              {
                "x": 7.0,
                "y": 0.0,
                "z": 0.0
              },
              {
                "x": 0.0,
                "y": 6.0,
                "z": 0.0
              },
              {
                "x": 7.0,
                "y": 20.0,
                "z": 0.0
             },
             {
                "x": 22.0,
                "y": 18.0,
                "z": 0.0
             },
             {
                "x": 23.0,
                "y": 10.0,
                "z": 0.0
             },
             {
                "x": 12.0,
                "y": 11.0,
                "z": 0.0
             }
            ]
          },
          {
            "name": "Mens",
            "floor": "1",
            "points": [
              {
                "x": 22.0,
                "y": 18.0,
                "z": 0.0
              },
              {
                "x": 28.0,
                "y": 26.0,
                "z": 0.0
              },
              {
                "x": 31.0,
                "y": 18.0,
                "z": 0.0
             },
             {
                "x": 23.0,
                "y": 10.0,
                "z": 0.0
             }
            ]
          }
        ]
      };
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "http://BASE_URL/configuration/v1/zoneMaps/create", true);
  xhr.requestHeaders("Content-Type", "application/json");
  xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
  xhr.send(JSON.stringify(zoneMap));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/create"");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                    {
                        name = "Contoso_Fashion",
                        facility = "DEFAULT",
                        zones =
                        {
                            new
                            {
                                name = "MENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 28.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 28.0,
                                        y = 26.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 31.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    }
                                }
                            },
                            new
                            {
                                name = "WOMENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 7.0,
                                        y = 0.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 0.0,
                                        y = 6.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 7.0,
                                        y = 20.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 22.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 12.0,
                                        y = 11.0,
                                        z = 0.0
                                    }
                                }
                            }
                        }
                    });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}




Sample Response

{
    "name": "Contoso_Fashion",
    "facility": "DEFAULT",
    "zones": [
      {
        "name": "Womens",
        "floor": "1",
        "points": [
          {
            "x": 7.0,
            "y": 0.0,
            "z": 0.0
          },
          {
            "x": 0.0,
            "y": 6.0,
            "z": 0.0
          },
          {
            "x": 7.0,
            "y": 20.0,
            "z": 0.0
         },
         {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         },
         {
            "x": 12.0,
            "y": 11.0,
            "z": 0.0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": "1",
        "points": [
          {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
          },
          {
            "x": 28.0,
            "y": 26.0,
            "z": 0.0
          },
          {
            "x": 31.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         }
        ]
      }
    ]
  }

Create or Replace

Replace an existing zone map, or create a new one

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/zoneMaps/createOrReplace

Request Body

The same as the Create Request Body

Response

The same as Create Response

Sample Code

  var zoneMap =  {
       "name": "Contoso_Fashion",
       "facility": "DEFAULT",
       "zones": [
         {
           "name": "Womens",
           "floor": "1",
           "points": [
             {
               "x": 7.0,
               "y": 0.0,
               "z": 0.0
             },
             {
               "x": 0.0,
               "y": 6.0,
               "z": 0.0
             },
             {
               "x": 7.0,
               "y": 20.0,
               "z": 0.0
            },
            {
               "x": 22.0,
               "y": 18.0,
               "z": 0.0
            },
            {
               "x": 23.0,
               "y": 10.0,
               "z": 0.0
            },
            {
               "x": 12.0,
               "y": 11.0,
               "z": 0.0
            }
           ]
         },
         {
           "name": "Mens",
           "floor": "1",
           "points": [
             {
               "x": 22.0,
               "y": 18.0,
               "z": 0.0
             },
             {
               "x": 28.0,
               "y": 26.0,
               "z": 0.0
             },
             {
               "x": 31.0,
               "y": 18.0,
               "z": 0.0
            },
            {
               "x": 23.0,
               "y": 10.0,
               "z": 0.0
            }
           ]
         }
       ]
     };
  var xhr = new XMLHttpRequest();
  xhr.open("PUT", "http://BASE_URL/configuration/v1/zoneMaps/createOrReplace", true);
  xhr.requestHeaders("Content-Type", "application/json");
  xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
  xhr.send(JSON.stringify(zoneMap));




string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/create"");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                    {
                        name = "Contoso_Fashion",
                        facility = "DEFAULT",
                        zones =
                        {
                            new
                            {
                                name = "MENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 28.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 28.0,
                                        y = 26.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 31.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    }
                                }
                            },
                            new
                            {
                                name = "WOMENS",
                                floor = "0",
                                points = {
                                    {
                                        x = 7.0,
                                        y = 0.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 0.0,
                                        y = 6.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 7.0,
                                        y = 20.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 22.0,
                                        y = 18.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 23.0,
                                        y = 10.0,
                                        z = 0.0
                                    },
                                    {
                                        x = 12.0,
                                        y = 11.0,
                                        z = 0.0
                                    }
                                }
                            }
                        }
                    });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

The same as the Create Sample Response

Delete

Delete a zone map.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/zoneMaps/destroy/{zoneMapName}

Parameters

Parameter Type Description
zoneMapName String The name of the zone map to delete

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/zoneMaps/destroy/" + zoneMapName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));
string zoneMapName = "Contoso_Fashion";

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/destroy/" + zoneMapName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific zone map.

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/zoneMaps/show/{zoneMapName}

Parameters

Parameter Type Description
zoneMapName String The name of the zone map to retrieve

Response

Parameter Type Description
name String The name associated with the zone map
facility String The facility with which the zonemap is associated
zones Array of: Zone The collection of zones within the zone map

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/zoneMaps/show/" + zoneMapName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string zoneMapName = "Contoso_Fashion";

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/show/" + zoneMapName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}



Sample Response

{
    "name": "Contoso_Fashion",
    "facility": "DEFAULT",
    "zones": [
      {
        "name": "Womens",
        "floor": "1",
        "points": [
          {
            "x": 7.0,
            "y": 0.0,
            "z": 0.0
          },
          {
            "x": 0.0,
            "y": 6.0,
            "z": 0.0
          },
          {
            "x": 7.0,
            "y": 20.0,
            "z": 0.0
         },
         {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         },
         {
            "x": 12.0,
            "y": 11.0,
            "z": 0.0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": "1",
        "points": [
          {
            "x": 22.0,
            "y": 18.0,
            "z": 0.0
          },
          {
            "x": 28.0,
            "y": 26.0,
            "z": 0.0
          },
          {
            "x": 31.0,
            "y": 18.0,
            "z": 0.0
         },
         {
            "x": 23.0,
            "y": 10.0,
            "z": 0.0
         }
        ]
      }
    ]
  }

Get All

Show all of the configured zone maps

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/zoneMaps/show

Response

Array of:

Parameter Type Description
name String The name associated with the zone map
facility String The facility with which the zonemap is associated
zones Array of: Zone The collection of zones within the zone map

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/zoneMaps/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");





string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/zoneMaps/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

 [{
     "name": "Contoso_Fashion",
     "facility": "DEFAULT",
     "zones": [
       {
         "name": "Womens",
         "floor": "1",
         "points": [
           {
             "x": 7.0,
             "y": 0.0,
             "z": 0.0
           },
           {
             "x": 0.0,
             "y": 6.0,
             "z": 0.0
           },
           {
             "x": 7.0,
             "y": 20.0,
             "z": 0.0
          },
          {
             "x": 22.0,
             "y": 18.0,
             "z": 0.0
          },
          {
             "x": 23.0,
             "y": 10.0,
             "z": 0.0
          },
          {
             "x": 12.0,
             "y": 11.0,
             "z": 0.0
          }
         ]
       },
       {
         "name": "Mens",
         "floor": "1",
         "points": [
           {
             "x": 22.0,
             "y": 18.0,
             "z": 0.0
           },
           {
             "x": 28.0,
             "y": 26.0,
             "z": 0.0
           },
           {
             "x": 31.0,
             "y": 18.0,
             "z": 0.0
          },
          {
             "x": 23.0,
             "y": 10.0,
             "z": 0.0
          }
         ]
       }
     ]
   }]

Get Current

Show the current zone map for the given facility

AuthorizedRoles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/control/v1/currentZoneMap/show/{facilityName}
Parameter Type Description
facilityName
(optional, except if using multiple facilities)
String The name of the facility for which to retrieve the current zone map.

Response

Parameter Type Description
status One of:
WAITING_FOR_ZONE_MAP,
RUNNING,
FAILED,
COMPLETE
The status of the zone map
name String The name of the zone map

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/control/v1/currentZoneMap/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/currentZoneMap/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Responses

Without a value currently set:

{
  "name": null,
  "status": "WAITING_FOR_ZONE_MAP"
}

With a value currently set:

{
  "name": "Contoso_Fashion",
  "status": "COMPLETE"
}

Update Current

Select a specific zone map to apply.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/control/v1/currentZoneMap/select/{zoneMapName}
Parameter Type Description
zoneMapName String The name of the zone map to apply

Response

Parameter Type Description
name String The name associated with the zone map
facility String The facility with which the zonemap is associated
zones Array of: Zone The collection of zones within the zone map

Sample Code

var zoneMapName = "Contoso_Fashion";

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/currentZoneMap/select" + zoneMapName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string zoneMapName = "Contoso_Fashion";

Uri uri = new Uri("http://BASE_URL/control/v1/currentZoneMap/select" + zoneMapName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}



Sample Responses


{
  "name": "Contoso_Fashion",
  "status": "COMPLETE"
}

Clear Current

Reset the current zone map for the given facility.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/control/v1/currentZoneMap/clear/{facilityName}

Parameters

Parameter Type Description
facilityName
(optional, except if using multiple facilities)
String The name of the facility for which to clear the current zone map.

Sample Code



var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/control/v1/currentZoneMap/clear", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/currentZoneMap/clear");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}



Sample Response

204 No Content

Reader Definitions

Reader Definitions are used to define a reader for use with ItemSense. Each reader definition specifies a single reader.

Placement Configuration

A Placement Configuration provides ItemSense with the information that it needs to position a reader relative to the space that is being monitored and to ensure that the tag locations reported by the reader are relative to the same space. It is not required to specify the placement of any reader; if a placement is specified, then certain fields are required, depending on the reader type, as specified in the table below. Specifying a placement for an XARRAY will allow it to fulfill LOCATION use-cases, and for all reader types can be used to enhance output data.

For an XARRAY gateway, the placement includes a precise location in three-dimensional space. For all readers, the placement may include a floor, which will be applied to all tag reads from the reader.

Placement Configurations are an important component of the reader definition. They allow ItemSense to accurately position inventoried RFID tags within the space monitored by the xArray reader(s). There are three sets of parameters: the floor; the x, y, and z parameters that define to ItemSense where an xArray reader center point is located within the monitored space; the yaw, pitch, and roll parameters that define the orientation of the xArray reader around its center point, as defined in the diagram below:

Reader Configuration

Parameter Type Allowed For Reader Types Required for Reader Types Description Notes
x Number XARRAY, XSPAN, XPORTAL XARRAY, XSPAN, XPORTAL The x-axis offset, in meters, of the reader from the (0,0) location in the monitored space
y Number XARRAY, XSPAN, XPORTAL XARRAY, XSPAN, XPORTAL The y-axis offset, in meters, of the reader from the (0,0) location in the monitored space
z Number XARRAY, XSPAN, XPORTAL XARRAY, XSPAN, XPORTAL The average distance between the height of the xArray and the height of the tags
yaw Number XARRAY, XSPAN, XPORTAL XARRAY, XSPAN, XPORTAL The angle, in degrees, that the xArray is rotated about its Z axis
pitch Number XARRAY, XSPAN, XPORTAL None The angle, in degrees, that the xArray is tilted about its X axis This property is ignored and is not used by ItemSense
roll Number XARRAY, XSPAN, XPORTAL None The angle, in degrees, that the xArray is tilted about its Y axis This property is ignored and is not used by ItemSense
floor String All Readers SPEEDWAY The number or name of the floor on which the reader is installed Once this is set on a reader, it cannot be set to null, nor can the placement itself be set to null.

Create

Create a new reader definition (but do not replace an existing one)

Note that groups are created implicitly as a property of the reader definition. So if, for example, you specify the name “storeroom” as a group on three readers, those three readers are now part of one “storeroom” group.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/readerDefinitions/create

Request Body

Parameter Type Description
name String The name associated with the reader definition. If not provided, will default to the address.
address String The IP address or the hostname of the reader
groups
Array of: String The groups with which this reader is associated
type
One of:
XARRAY,
XSPAN,
XPORTAL,
SPEEDWAY,
UNKNOWN
The type of reader
readerZone String The spot zone with which to associate this reader
antennaZones Map[int,string] A map of antenna-to-spot-zone associations. If not specified, antenna is allocated to the readers spot zone
facility String The facility with which the reader is associated
placement PlacementConfig The placement of the reader
labels
Array of: String A list of configurable strings associated with the reader
agentIdentifier String Internal use only

Response

Parameter Type Description
name String The name that identifies the reader definition
serialNumber String The serial number of the reader
address String The IP address or the hostname of the reader
groups Array of: String The groups with which this reader is associated
type One of:
XARRAY,
XSPAN,
XPORTAL,
SPEEDWAY,
UNKNOWN
The type of reader
readerZone String The spot zone with which to associated this reader
antennaZones Map[int,string] A list of antenna-to-spot-zone associations. If not specified, antenna is allocated to the readers spot zone
facility String The facility with which the reader is associated
placement PlacementConfig The placement of the reader
labels Array of: String A list of string tags associated with the reader
features Map[Feature, ReaderFeatureStatus] See Configure Feature
agentIdentifier String Internal use only

Sample Code

var readerDefinition =  {
                           name: "xarray-11-30-0D",
                           address: "xarray-11-30-0D.impinj.com",
                           groups: [ "ceiling", "closet" ],
                           type: "XARRAY",
                           placement: {
                             x: 4.3,
                             y: 6.65,
                             z: 2.68,
                             yaw: 30,
                             pitch: 0,
                             roll: 90,
                             floor: 1
                         }
                      };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/readerDefinitions/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerDefinition));


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "xarray-11-32-34",
                    address = "xarray-11-32-34.impinj.com",
                    groups = new string[] { "ceiling", "closet" },
                    type = "XARRAY",
                    placement = new
                    {
                        x = 4.3,
                        y = 6.65,
                        z = 2.68,
                        yaw = 30,
                        pitch = 0,
                        roll = 90,
                        floor = 1
                    },
                    labels = null,
                    readerZone = "xarray-11-32-34.impinj.com",
                    antennaZones = null
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

{
  "name": "xarray-10-D9-41",
  "agentIdentifier": "xarray-10-D9-41",
  "address": "xarray-10-D9-41.impinj.com",
  "groups": [ "ceiling", "closet" ],
  "type": "XARRAY",
  "placement": {
    "x": 4.3,
    "y": 6.65,
    "z": 2.68,
    "yaw": 30,
    "pitch": 0,
    "roll": 90,
    "floor": 1
  },
  "features": {},
  "labels": null,
  "readerZone": "xarray-10-D9-41",
  "antennaZones": null
}

Create or Replace

Replace an existing reader definition, or create a new one.

Note: When changing the reader’s facility as part of a reader definition update, an internal consistency issue within ItemSense requires the name of the readerZone to change, as well as the names of any antennaZones.

Similarly, when changing the reader’s placement’s floor as part of a reader definition update, the names of the readerZone and antennaZones must change. Furthermore, once a reader has a floor assigned to it, it is prohibited to remove the floor (which occurs when the floor property is set to null, or the placement itself is set to null).
It is permissible to change the floor to a different, non-null value.

Calls to this API endpoint fail if the facility or floor is changed and the names of the zones are not modified.

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/readerDefinitions/createOrReplace

Request Body

The same as the Create Request Body

Response

The same as the Create Response

Sample Code

var readerDefinition =  {
                           name: "xarray-11-30-0D",
                           address: "xarray-11-30-0D.impinj.com",
                           groups: [ "ceiling", "closet" ],
                           type: "XARRAY",
                           placement: {
                             x: 4.1,
                             y: 3.65,
                             z: 1.68,
                             yaw: 30,
                             pitch: 0,
                             roll: 90,
                             floor: 1
                         }
                       };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/readerDefinitions/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerDefinition));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    name = "xarray-11-32-34",
                    address = "xarray-11-32-34.impinj.com",
                    groups = new string[] { "ceiling", "closet" },
                    type = "XARRAY",
                    placement = new
                    {
                         x = 4.1,
                         y = 3.65,
                         z = 1.68,
                         yaw = 30,
                         pitch = 0,
                         roll = 90,
                         floor = 1
                    },
                    labels = null,
                    readerZone = "xarray-11-32-34.impinj.com",
                    antennaZones = null
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

The same as the Create Sample Response

Delete

Delete a specific reader definition

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/readerDefinitions/destroy/{readerDefinitionName}

Parameters

Parameter Type Description
readerDefinitionName String Name of the reader definition to be deleted

Response

The same as the Create Response

Parameter | Type | Description

Sample Code

var readerName = "xarray-11-30-0D";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/readerDefinitions/destroy/" + readerName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/destroy/" + readerName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Get a specific reader definition

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/show/{readerDefinitionName}

Parameters

Parameter Type Description
readerDefinitionName String The name of the reader definition to retrieve

Response

The parameters returned in the response are the same as those specified in the Create Request Body

Sample Code

var readerName = "xarray-11-30-0D";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/show/" + readerName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/show/" + readerName);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

The same as the Create Sample Response

Get All

This method is used to retrieve all of the reader definitions

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/show

Response

Array of objects whose properties are defined by the Create Request Body

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/show", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));



Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "xarray-10-D9-41",
    "agentIdentifier": "xarray-10-D9-41",
    "address": "xarray-10-D9-41.impinj.com",
    "groups": [ "ceiling", "closet" ],
    "type": "XARRAY",
    "placement": {
      "x": 4.3,
      "y": 6.65,
      "z": 2.2,
      "yaw": 30,
      "pitch": 0,
      "roll": 90,
      "floor": 1
    },
    "labels": null,
    "features": null,
    "readerZone": "xarray-10-D9-41",
    "antennaZones": null
  },
  {
    "name": "xarray-11-30-0D",
    "agentIdentifier": "xarray-11-30-0D",
    "address": "xarray-11-30-0D.impinj.com",
    "groups": [ "ceiling", "closet" ],
    "type": "XARRAY",
    "placement": {
      "x": 8.1,
      "y": 5.65,
      "z": 2.68,
      "yaw": 30,
      "pitch": 0,
      "roll": 90,
      "floor": 1
    },
    "labels": null,
    "features": {},
    "readerZone": "xarray-11-30-0D",
    "antennaZones": null
  }
]

Groups

Retrieve the superset of elements (group names) assigned to any reader definition groups property. For example, given these readers with these defined groups:

readerDefinition1.groups = [‘storeroom’, 'dressingroom’]
readerDefinition2.groups = ['storeroom’, 'ceiling’]
readerDefinition3.groups = ['ceiling’]

A call to this endpoint would return:

['storeroom’, 'dressingroom’, 'ceiling’]

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/groups

Response

Array of strings

Sample Code

var xhr = new XMLHttpRequest();

xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/groups", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/groups");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  "ceiling",
  "closet"
]

Configure Feature

Some readers support features that can be configured for specific uses, e.g. to enable an Antenna Hub on a Speedway reader.

A call to this endpoint produces a status of ACCEPTED(202) and a response HTTP header for “Location”, which is a URL used to get the status of the new configuration request.

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/readerDefinitions/{readerDefinitionName}/featureChanges

Parameters

Parameter Type Description
readerDefinitionName String The name of the reader on which to configure the feature.

Request Body

Parameter Type Description
feature
One of:
ANTENNA_HUB
The name of the feature to confiure.
action
One of:
ENABLE,
DISABLE
The configuration action to perform.

Sample Code

var readerName = "xarray-11-dd-ef";
var featureRequest =  {
                           feature: "ANTENNA_HUB",
                           action: "ENABLE"
                      };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(featureRequest));


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));
string readerName = "xarray-11-dd-ef";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                   feature: "ANTENNA_HUB",
                   action: "ENABLE"
                });
    sw.Write(data);
}

Sample Response

202 Accepted

Get Feature Status

Get the status of a specific feature on a reader.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/{readerDefinitionName}/featureChanges/{feature}

Parameters

Parameter Type Description
readerDefinitionName String The name of the reader whose feature information is to be returned.
feature One of:
ANTENNA_HUB
The feature whose status on that reader is to be returned.

Response

Parameter Type Description
status One of:
ENABLED,
DISABLED
The last known status of the feature reported by this reader. If the requestStatus is CONFIGURING or ERROR, this field should not be trusted to reflect the current state of the feature.
statusLastUpdated String The last time the reader reported the status of the feature to ItemSense in ISO-8601 format, e.g. “2017-05-02T15:35:01.560Z”.
requestStatus One of:
IDLE,
INITIALIZING,
CONFIGURING,
ERROR
The status of the most recent request to change the status of the feature. IDLE means that there is no current request, and the last request, if there was one, completed successfully. INITIALIZING indicates that there is a request preparing to configure. CONFIGURING means there is an active request in progress, and ERROR means the last request failed.
requestStatusLastUpdated String The last time a request to change the status of this feature updated the requestStatus or null if there has never been one, in ISO-8601 format, e.g. “2017-05-02T15:35:01.560Z”.
requestTargetStatus One of:
null,
ENABLED,
DISABLED
The target status of the current request to change the status of the feature, if the request is CONFIGURING or in ERROR (null if there is no active request)
message
(optional)
String A message with more details on the status of the current or most recent request to change the status of the feature.

Sample Code

var readerName = "xarray-11-30-0D";
var feature = "ANTENNA_HUB";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges/" + feature, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";
string feature = "ANTENNA_HUB";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges/" + feature);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "status": "DISABLED",
  "statusLastUpdated": "2017-05-02T15:35:01.560Z",
  "requestStatus": "IDLE",
  "requestStatusLastUpdated": null
}

Get Active Feature Request Status

Get the status of active feature requests on a reader. Active requests are those where the feature status is CONFIGURING or ERROR.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/readerDefinitions/{readerDefinitionName}/featureChanges

Parameters

Parameter Type Description
readerDefinitionName String The name of the reader definition whose feature information is to be returned.

Response

A map of feature names to feature status objects, represented as an object where the field names correspond to valid feature names and the value is the same as the response from the feature status request.

Sample Code

var readerName = "xarray-11-30-0D";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string readerName = "xarray-11-30-0D";

Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/" + readerName + "/featureChanges");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "ANTENNA_HUB": {
    "status": "DISABLED",
    "statusLastUpdated": "2017-05-01T10:13:14Z",
    "requestStatus": "ERROR",
    "requestStatusLastUpdated": "2017-05-05T16:33:42Z",
    "message": "Reader failed to execute the configuration request"
  }
}

Reader Configurations

A Reader Configuration defines how a RAIN™ RFID reader will be utilized when a job is running. This configuration includes properties that control what Reader Mode is being executed, and what Session it is using. For a full list and description of configuration properties, please view the section Reader Configuration Details .

Create Reader Configuration

Create a new reader configuration (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/readerConfigurations/create

Request Body

Property Type Description
name String The name identifying the reader configuration
operation
One of:
INVENTORY,
LOCATION,
THRESHOLD,
DO_NOTHING
The operation that the reader performs. Reader is disabled if set to DO_NOTHING.
configuration ReaderConfigDetails The details of the reader configuration

Sample Code

var readerConfiguration = {
                              name: "LOCATION_WITH_FILTER",
                              operation: "LOCATION",
                              configuration: {
                                readerMode: "MODE_1002",
                                session: 2,
                                filter: {
                                  tagMask: 3034
                                }
                              }
                            };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/readerConfigurations/create", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerConfiguration));

// Encode credentials
string encodedCredentials = ...
var readerConfiguration = new
            {
                name = "LOCATION_WITH_FILTER",
                operation = "LOCATION",
                configuration = new
                {
                    readerMode = "MODE_1002",
                    session = 2,
                    filter:
                    {
                        tagMask: 3034
                    }

                }
            };
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "LOCATION_WITH_FILTER",
  "configuration": {
    "readerMode": "MODE_1002",
    "session": 2,
    "filter": {
      "memoryBank": 1,
      "pointer": 32,
      "tagMask": "3034"
    }
  },
  "operation": "LOCATION"
}

Update Reader Configuration

Update an existing configuration, or create a new one if it does not already exist

Authorization Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/readerConfigurations/createOrReplace

Request Body

The same as the Create Request Body.

Sample Response

var readerConfiguration = {
                              name: "IMPINJ_InventoryConfig",
                              operation: "INVENTORY",
                              configuration: {
                                readerMode: "MODE_1002",
                                searchMode: "DUAL_TARGET",
                                session: 1,
                                tagPopulationEstimate: 500,
                                antennas: [
                                  45,
                                  16,
                                  35,
                                  14,
                                  49,
                                  36,
                                  2,
                                  31,
                                  18,
                                  29,
                                  48,
                                  19,
                                  46,
                                  3,
                                  33,
                                  52,
                                  15,
                                  50,
                                  13,
                                  32,
                                  1,
                                  51,
                                  30,
                                  17,
                                  47,
                                  20,
                                  34,
                                  4
                                ]
                              }
                            };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/readerConfigurations/createOrReplace", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerConfiguration));

// Encode credentials
string encodedCredentials = ...
var readerConfiguration = new
            {
                name = "IMPINJ_InventoryConfig",
                operation = "INVENTORY",
                configuration = new
                {
                    readerMode = "MODE_1002",
                    searchMode = "DUAL_TARGET",
                    session = 1,
                    tagPopulationEstimate = 500,
                    antennas = {
                        45,
                        16,
                        35,
                        14,
                        49,
                        36,
                        2,
                        31,
                        18,
                        29,
                        48,
                        19,
                        46,
                        3,
                        33,
                        52,
                        15,
                        50,
                        13,
                        32,
                        1,
                        51,
                        30,
                        17,
                        47,
                        20,
                        34,
                        4
                    }
                }
            };


Uri uri = new Uri("http://BASE_URL/configuration/v1/readerDefinitions/create");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "IMPINJ_InventoryConfig",
  "operation": "INVENTORY",
  "configuration": {
    "readerMode": "MODE_1002",
    "searchMode": "DUAL_TARGET",
    "session": 1,
    "tagPopulationEstimate": 500,
    "transmitPowerInDbm": null,
    "antennas": [
      45,
      16,
      35,
      14,
      49,
      36,
      2,
      31,
      18,
      29,
      48,
      19,
      46,
      3,
      33,
      52,
      15,
      50,
      13,
      32,
      1,
      51,
      30,
      17,
      47,
      20,
      34,
      4
    ],
    "filter": null,
    "channelConfig": null
  }
}

Delete Reader Configuration

Delete a reader configuration

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/readerConfigurations/destroy/{readerConfigurationName}

Parameters

Parameter Type Description
readerConfigurationName String The name of the reader configuration to be deleted

Sample Code

var readerConfigurationName = "IMPINJ_LocationConfig";

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/readerConfiguration/destroy/" + readerConfigurationName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
string readerConfigurationName = "IMPINJ_LocationConfig";
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerConfigurations/destroy/" + readerConfigurationName);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get Reader Configuration

Retrieve a specific reader configuration

AuthorizedRoles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerConfigurations/show/{readerConfigurationName}

Parameters

Parameter Type Description
readerConfigurationName String The name of the reader configuration to be retrieved

Response

The same as the Create Request Body.

Sample Code

var readerConfigurationName = "IMPINJ_LocationConfig";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerConfiguration/show/" + readerConfigurationName, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
string readerConfigurationName = "IMPINJ_LocationConfig";
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerConfigurations/show/" + readerConfigurationName);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "MY_LOCATION",
  "configuration": {
    "readerMode": "MODE_1002",
    "session": 2,
    "filter": null
  },
  "operation": "LOCATION"
}

Get All Reader Configurations

Retrieve all of the reader configurations

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/readerConfigurations/show

Response

Array of Create Reader Configuration Request Body.

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/readerConfiguration/show, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri("http://BASE_URL/configuration/v1/readerConfigurations/show");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "IMPINJ_LocationConfig",
    "configuration": {
      "readerMode": "MODE_1002",
      "session": 2,
      "filter": null
    },
    "operation": "LOCATION"
  },
  {
    "name": "IMPINJ_GatewayConfig",
    "configuration": {
      "readerMode": "MODE_1002",
      "session": 2,
      "searchMode": "DUAL_TARGET",
      "tagPopulationEstimate": null,
      "transmitPowerInDbm": null,
      "polarization": null,
      "antennas": [
        1,
        2,
        3,
        4
      ],
      "filter": null,
      "channelConfig": null
    },
    "operation": "INVENTORY"
  },
  {
    "name": "IMPINJ_InventoryConfig",
    "configuration": {
      "readerMode": "MODE_1002",
      "session": 2,
      "searchMode": "SINGLE_TARGET",
      "tagPopulationEstimate": null,
      "transmitPowerInDbm": null,
      "polarization": null,
      "antennas": [
        45,
        16,
        35,
        14,
        49,
        36,
        2,
        31,
        18,
        29,
        48,
        19,
        46,
        3,
        33,
        52,
        15,
        50,
        13,
        32,
        1,
        51,
        30,
        17,
        47,
        20,
        34,
        4
      ],
      "filter": null,
      "channelConfig": null
    },
    "operation": "INVENTORY"
  }
]

Data Definitions

Reader Configuration Details

Property Type Description
readerMode
(required)
One of:
  • MAX_THROUGHPUT
  • HYBRID
  • DENSE_READER_M4
  • DENSE_READER_M8
  • MAX_MILLER
  • DENSE_READER_M4_TWO
  • AUTOSET_DENSE_READER
  • MODE_1002
  • MODE_1003
  • MODE_1004
The RFID reader mode

For more information on reader modes, please see this article
session
(required)
One of: 0, 1, 2, 3 The RFID session

When operation=LOCATION, must be 2 or 3
searchMode (required) One of:
  • READER_SELECTED
  • SINGLE_TARGET
  • DUAL_TARGET
  • TAG_FOCUS
  • SINGLE_TARGET_BTOA
  • DUAL_TARGET_WITH_BTOASELECT
The RFID search mode

Only available when the reader operation=INVENTORY

For more information on sessions and search modes, please see this article
filter
(optional)
Filter Configuration Tag filter definition
tagPopulationEstimate
(optional)
Integer An estimate of the number of tags in the field of view of the readers. This value will be used to set the starting ‘Q’ value in the UHF Gen2 RFID inventory protocol

Only available when the reader operation=INVENTORY
transmitPowerInDbm
(optional)
Number The transmit power, in dBm to use for each of the selected antenna ports.
polarization *
(optional)
Boolean This flag tells the reader to use an antenna’s ID in polarized format. These IDs will show up in the antennaId field of the tag report data.

By default xArrays support antenna numbers 1-52. Both horizontal and vertical polarizations of a beam map to the same antenna ID.

* With polarization enabled, then tag reads on the horizontal polarization will have an offset of 1000 applied (1001-1052). Tag reads on the vertical polarization will have an offset of 2000 applied (2001-2052).

Only available when the reader operation=INVENTORY
antennas Array of Integers Array of integers defining which antenna ports that readers will use

Only available when the reader operation=INVENTORY
disabledAntennas Array of Integers Array of integers defining which antennas that the readers will not use. This is helpful in situations when the reader is located very close to an obstruction and location accuracy could be improved by disabling the antenna(s) facing that obstruction.

Only available when the reader operation=LOCATION)
channelConfig
(optional)
Channel Configuration Defines any fixed frequency channel configurations that the readers will use. This option is only for use with readers certified for use in a regulatory region that supports the use of fixed frequencies.

Only available when the reader operation=INVENTORY

Filter Configuration

Property Type Description
tagMask
(required)
String A hexadecimal value on which to filter tags
memoryBank
(optional)
Integer The RFID tag memory region to base a tag filter on, based on the following:
Memory Bank #Tag Memory Region
0Reserved
1EPC
2TID
3User

Defaults to 1
pointer
(optional)
Integer A pointer to the bit in memory from which to start the filter. For example, bits 0-31 of EPC memory are used to store the tag CRC and PC Word. To filter on the EPC value of a specific tag, it would therefore be necessary to start the filter on bit 32.

Defaults to 32

Channel Configuration

Property Type Description
channelIndex Integer For RFID readers operating in regions with fixed frequency regulatory requirements, channelIndex is used to define a single frequency for the reader to operate in. This is a one-based integer value into the Low Level Reader Protocol (LLRP) frequency table that points to the position of a frequency in the list of available frequencies. You must already know the channels that are available for your region. For example, RAIN RFID readers for the ETSI region have the following list of available channels:
LLRP Channel NumberCenter Frequency (MHz)
1865.70 MHz
2866.30 MHz
3866.90 MHz
4867.50 Mhz
txFrequenciesInMhz Array of Numbers For RAIN RFID readers operating in regions with frequency-hopping regulatory requirements, txFrequenciesInMhz is used to define a custom frequency hop table. The table can only include frequencies that are allowed by the reader’s region, but frequencies can be defined in any order including repeating and/or omitting frequencies. For example, based on the ETSI frequencies above, an ETSI frequency hop table might be defined as [865.7, 866.3, 866.9, 867.5], which will prompt the reader to hop only in these frequencies, in this order.

Threshold

A Threshold defines how a collection of readers will be utilized when a threshold job is running.

Create

Create a new threshold configuration (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/thresholds

Request Body

Property Type Description
name string The name of the threshold
facility string The facility that contains the threshold
readerArrangement
One of:
SIDE_BY_SIDE,
OVERHEAD,
OVERHEAD_OFFSET,
CUSTOM
The arrangement of readers around the threshold
readers Key Value List A map of reader definiton names and an object with a single property of antennaConfigurationId for specifiying what antenna configuration to use

Sample Code

var threshold = {
                  "name": "THRESHOLD",
                  "facility": "DEFAULT",
                  "readerArrangement": "SIDE_BY_SIDE",
                  "readers": {
                    "reader_name_one": {
                      "antennaConfigurationId": 1
                    },
                    "reader_name_two": {
                      "antennaConfigurationId": 2
                    }
                  }
               };
;
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/thresholds", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(threshold));

// Encode credentials
string encodedCredentials = ...
var threshold = {
                  "name": "THRESHOLD",
                  "facility": "DEFAULT",
                  "readerArrangement": "SIDE_BY_SIDE",
                  "readers": {
                    "reader_name_one": {
                      "antennaConfigurationId": 1
                    },
                    "reader_name_two": {
                      "antennaConfigurationId": 2
                    }
                  }
               };

Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1
    },
    "reader_name_two": {
      "antennaConfigurationId": 2
    }
  }
}

Replace

Update an existing threshold

Authorization Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/thresholds/{thresholdID}

Request Body

The same as the Create Request Body. But with an additional ID property

Sample Response

var readerConfiguration = {
                            "id": 1,
                            "name": "THRESHOLD",
                            "facility": "DEFAULT",
                            "readerArrangement": "SIDE_BY_SIDE",
                            "readers": {
                              "reader_name_one": {
                                "antennaConfigurationId": 1
                              },
                              "reader_name_two": {
                                "antennaConfigurationId": 2
                              }
                            }
                          };

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/thresholds/1", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(readerConfiguration));

// Encode credentials
string encodedCredentials = ...
var readerConfiguration = {
                            "id": 1,
                            "name": "THRESHOLD",
                            "facility": "DEFAULT",
                            "readerArrangement": "SIDE_BY_SIDE",
                            "readers": {
                              "reader_name_one": {
                                "antennaConfigurationId": 1
                              },
                              "reader_name_two": {
                                "antennaConfigurationId": 2
                              }
                            }
                          };


Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/1");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(readerConfiguration);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1
    },
    "reader_name_two": {
      "antennaConfigurationId": 2
    }
  }
}

Delete

Delete a threshold configuration

Note: When deleting a threshold, any existing transition data stored about the threshold will also be removed

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/threshold/{thresholdID}

Parameters

Parameter Type Description
thresholdID Integer The id of the threshold to be deleted

Sample Code

var thresholdID = 1;

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/thresholds/" + thresholdID, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int thresholdID = 1;
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/" + thresholdID);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific threshold configuration

AuthorizedRoles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds/{thresholdID}

Parameters

Parameter Type Description
thresholdID Integer The ID of the threshold configuration to be retrieved
embed
(optional)
The string
antennaConfiguration
Entity or entities to embed as whole objects within the response, in addition to just the ID that could be used to reference the object. This functions identically in the Get All and Get APIs. Currently, only one legal value exists for this parameter.
For more details, see the Response and Sample Response sections.

Response

The same as the Create Request Body, but with an additional ID property. If embed entities were requested, those will be embedded in the response.

antennaConfiguration embed

When the antennaConfiguration embed is requested using the embed query parameter, the response object will contain the entire antennaConfiguration object adjacent to the antennaConfigurationId. See Sample Response.

Sample Code

var thresholdID = 1;

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/" + thresholdID, true);
// To request the antennaConfiguration embed, add the query parameter:
// xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/" + thresholdID + "?embed=antennaConfiguration", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int thresholdID = 1;
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/" + thresholdID);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1
    },
    "reader_name_two": {
      "antennaConfigurationId": 2
    }
  }
}

With antennaConfiguration embed

{
  "id": 1,
  "name": "THRESHOLD",
  "facility": "DEFAULT",
  "readerArrangement": "SIDE_BY_SIDE",
  "readers": {
    "reader_name_one": {
      "antennaConfigurationId": 1,
      "antennaConfiguration": {
        "id": 1,
        "name": "left_configuration_name",
        "side": "LEFT",
        "in": [
          {"antennaId": 1},
          {"antennaId": 3}],
        "out": [
          {"antennaId": 2},
          {"antennaId": 4}]
      }
    },
    "reader_name_two": {
      "antennaConfigurationId": 2,
      "antennaConfiguration": {
        "id": 2,
        "name": "right_configuration_name",
        "side": "RIGHT",
        "in": [
          {"antennaId": 5},
          {"antennaId": 7}],
        "out": [
          {"antennaId": 6},
          {"antennaId": 8}]
      }
    }
  }
}

Get All

Retrieve all of the threshold configurations

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds

Parameters

Parameter Type Description
embed
(optional)
The string
antennaConfiguration
Entity or entities to embed as whole objects within the response, in addition to just the ID that could be used to reference the object. This functions identically in the Get All and Get APIs. Currently, only one legal value exists for this parameter.
For more details, see the Response and Sample Response sections.

Response

Array of Create Threshold request bodies with the ID property. If embed entities were requested, those will be embedded in the response.

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds", true);
// To request the antennaConfiguration embed, add the query parameter:
// xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds?embed=antennaConfiguration", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "id": 1,
    "name": "threshold_one",
    "facility": "DEFAULT",
    "readerArrangement": "SIDE_BY_SIDE",
    "readers": {
      "reader_name_one": {
        "antennaConfigurationId": 1
      },
      "reader_name_two": {
        "antennaConfigurationId": 2
      }
    }
  },
  {
    "id": 2,
    "name": "threshold_two",
    "facility": "DEFAULT",
    "readerArrangement": "SIDE_BY_SIDE",
    "readers": {
      "reader_name_one": {
        "antennaConfigurationId": 1
      },
      "reader_name_two": {
        "antennaConfigurationId": 2
      }
    }
  }
]

Threshold Antenna Configuration

An antenna configuration defines how a given reader’s antennas should be utilized for a particular threshold

Create

Create a new threshold antenna configuration (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/thresholds/antennaConfigurations

Request Body

Property Type Description
name string The name of the antenna configuration.
side
(optional*)
One of:
LEFT,
RIGHT
The side of the threshold that the antenna is positioned on. *If it is on neither side (e.g. above the threshold) this property should be null or absent.
readerType
(optional)
One of:
XARRAY,
XSPAN,
XPORTAL
Threshold antenna configurations can be specific to reader types. If defined, this field can be helpful for assigning configurations to specific reader types. Note that while it is possible to set a readerType of SPEEDWAY, this is not a supported configuration for this feature
readerArrangement
(optional)
One of:
SIDE_BY_SIDE,
OVERHEAD,
OVERHEAD_OFFSET,
CUSTOM
Threshold antenna configurations can be specific to reader arrangements. If defined, this field can be helpful for assigning configurations to specific threshold arrangements.
in array of objects A collection of antenna objects that point to the inside of the threshold.
out array of objects A collection of antenna objects that point to the outside of the threshold.
ignored
(optional)
array of objects A collection of antenna objects where the antennas are enabled on the reader, but their reads will be ignored. This is useful in order to help synchronize cycle durations across readers that may otherwise have differing enabled antenna counts.
In a request, providing null, an empty list, or omitting the property are all equivalent ways of specifying no antennas to ignore.
In a response, either the property will be absent or the value will be a nonempty list (it will never be null or an empty list).

Sample Code

var antennaConfiguration = {
                             "name": "configuration_name",
                             "side": "LEFT",
                             "readerType": "XARRAY",
                             "readerArrangement": "OVERHEAD",
                             "in": [
                               {
                                 "antennaId": 1
                               },
                               {
                                 "antennaId": 3
                               }
                             ],
                             "out": [
                               {
                                 "antennaId": 2
                               },
                               {
                                 "antennaId": 4
                               }
                             ]
                           };

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(antennaConfiguration));

// Encode credentials
string encodedCredentials = ...
var antennaConfiguration = {
                             "name": "configuration_name",
                             "side": "LEFT",
                             "readerType": "XARRAY",
                             "readerArrangement": "OVERHEAD",
                             "in": [
                               {
                                 "antennaId": 1
                               },
                               {
                                 "antennaId": 3
                               }
                             ],
                             "out": [
                               {
                                 "antennaId": 2
                               },
                               {
                                 "antennaId": 4
                               }
                             ]
                           };

Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(antennaConfiguration);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
 "id": 1,
 "name": "configuration_name",
 "side": "LEFT",
 "readerType": "XARRAY",
 "readerArrangement": "OVERHEAD",
 "in": [
   {
     "antennaId": 1
   },
   {
     "antennaId": 3
   }
 ],
 "out": [
   {
     "antennaId": 2
   },
   {
     "antennaId": 4
   }
 ]
}

Replace

Update an existing threshold antenna configuration

Authorization Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/{antennaConfigurationID}

Request Body

The same as the Create Request Body. But with an additional ID property

Sample Response

var antennaConfiguration = {
                             "id": 1,
                             "name": "configuration_name",
                             "side": "LEFT",
                             "readerType": "XARRAY",
                             "readerArrangement": "OVERHEAD",
                             "in": [
                               {
                                 "antennaId": 1
                               },
                               {
                                 "antennaId": 3
                               }
                             ],
                             "out": [
                               {
                                 "antennaId": 2
                               },
                               {
                                 "antennaId": 4
                               }
                             ]
                          };

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/1", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(antennaConfiguration));

// Encode credentials
string encodedCredentials = ...
var antennaConfiguration = {
                                 "id": 1,
                                 "name": "configuration_name",
                                 "side": "LEFT",
                                 "readerType": "XARRAY",
                                 "readerArrangement": "OVERHEAD",
                                 "in": [
                                   {
                                     "antennaId": 1
                                   },
                                   {
                                     "antennaId": 3
                                   }
                                 ],
                                 "out": [
                                   {
                                     "antennaId": 2
                                   },
                                   {
                                     "antennaId": 4
                                   }
                                 ]
                              };


Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/1");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(antennaConfiguration);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
 "id": 1,
 "name": "configuration_name",
 "side": "LEFT",
 "readerType": "XARRAY",
 "readerArrangement": "OVERHEAD",
 "in": [
   {
     "antennaId": 1
   },
   {
     "antennaId": 3
   }
 ],
 "out": [
   {
     "antennaId": 2
   },
   {
     "antennaId": 4
   }
 ]
}

Delete

Delete a threshold antenna configuration

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/threshold/antennaConfiguration/{antennaConfigurationID}?replacementId={replacementId}

Parameters

Parameter Type Description
antennaConfigurationID Integer The id of the antenna configuration to be deleted
replacementId
(optional)
Integer The id of an antenna configuration to use as a replacement for the one being deleted, passed as a query parameter

Sample Code

var antennaConfigurationID = 1;
var replacementId = 2;

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID + "?replacementId=" + replacementId, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int antennaConfigurationID = 1;
int replacementId = 2;

Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID + "?replacementId=" + replacementId);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get

Retrieve a specific threshold antenna configuration

AuthorizedRoles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/{antennaConfigurationID}

Parameters

Parameter Type Description
antennaConfigurationId Integer The ID of the antenna configuration to be retrieved

Response

The same as the Create Request Body. But with an additional ID property

Sample Code

var antennaConfigurationID = 1;

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
int antennaConfigurationID = 1;
Uri uri = new Uri("http://BASE_URL/configuration/v1/thresholds/antennaConfiguration/" + antennaConfigurationID);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
 "id": 1,
 "name": "configuration_name",
 "side": "LEFT",
 "readerType": "XARRAY",
 "readerArrangement": "OVERHEAD", 
 "in": [
   {
     "antennaId": 1
   },
   {
     "antennaId": 3
   }
 ],
 "out": [
   {
     "antennaId": 2
   },
   {
     "antennaId": 4
   }
 ]
}

Get All

Retrieve all of the threshold antenna configurations

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/thresholds/antennaConfigurations

Response

Array of Create Antenna configuration request bodies with the ID property.

Sample Code


var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/thresholds/antennaConfigurations", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri("http://BASE_URL/configuration/v1/antennaConfigurations");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
   "id": 1,
   "name": "configuration_name",
   "side": "LEFT",
   "readerType": "XARRAY",
   "readerArrangement": "OVERHEAD", 
   "in": [
     {
       "antennaId": 1
     },
     {
       "antennaId": 3
     }
   ],
   "out": [
     {
       "antennaId": 2
     },
     {
       "antennaId": 4
     }
   ]
  },
  {
   "id": 2,
   "name": "configuration_name_2",
   "side": "LEFT",
   "readerType": "XARRAY",
   "readerArrangement": "OVERHEAD", 
   "in": [
     {
       "antennaId": 5
     },
     {
       "antennaId": 8
     }
   ],
   "out": [
     {
       "antennaId": 6
     },
     {
       "antennaId": 9
     }
   ]
  }
]

Recipes

Recipes map reader configurations onto individual reader definitions, as well as specifying other parameters relating to the type of operation that the recipe specifies.

For a recipe to be valid, it must have its readerConfigurationName field set, and/or a list of of reader hostnames and reader configurations in the readerConfigurations field. If an entry exists in the readerConfigurationName field only, then the reader configuration identified by this field will be applied to every defined reader.

If an entry exists in both fields, then the entry in the readerConfigurations field takes precedence.

All recipes share some common properties, but other properties vary by the recipe type. These variations are specified below.

Create Recipe

Create a new recipe (but do not replace an existing one)

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/configuration/v1/recipes/create

Request Body

Common properties:

Parameter Type Description
name
(required)
String The name of the recipe

type
(required)
One of: LOCATION
INVENTORY
THRESHOLD
The type of recipe

readerConfigurationName
(required)
String The name of the default reader configuration to use. The operation attribute of the referenced reader configuration must either match the type attribute of the recipe or be DO_NOTHING

readerConfigurations
(optional)
Key Value List A map of reader definition names to reader configuration names. These override the configuration given in readerConfigurationName for the specified reader definitions. The operation attribute of any referenced reader configurations must either match the type attribute of the recipe or be DO_NOTHING
e.g.
{"xarray-11-22-33.impinj.com":"Example_ReaderConfiguration",
"xarray-44-55-66.impinj.com":"Another_ReaderConfiguration"}

Location Recipes:

Parameter Type Description
tagHeartbeatDuration
(optional)
String This is used to control how frequently the lastModifiedTime of a tag is updated when the tag is read but has not moved. Set with a string in ISO 8601 format. representing the time interval between heartbeat updates. Example = “PT10”, Minimum = “PT1M”, Default = “PT5M”
tagExpiryDuration
(optional)
String A string in ISO 8601 format. representing the time interval between the last time ItemSense detected a tag, and the tag being marked ABSENT.

If this parameter is not set, ABSENCE detection via tag expiration is disabled.

If set, this parameter must be greater than the reportingInterval.

This parameter is only available for certain combinations of reader configuration parameters: those that allow ItemSense to receive sufficient data to determine whether a tag has indeed gone absent.

Allowable combinations:
  • configuration.operation=LOCATION
  • configuration.operation=INVENTORY and configuration.searchMode=DUAL_TARGET
Forbidden combinations:
  • configuration.operation=INVENTORY and configuration.searchMode=SINGLE_TARGET
minimumMovementInMeters
(optional)
Decimal Minimum distance a tag must move for a change in location to be reported. Only valid when type is set to LOCATION. When set to 0 (the minimum value for this parameter, any location change is reported

Default=1, Minimum=0, Resolution=0.5
computeWindow
(optional)
Integer Amount of time in seconds that an EPC is kept in memory for location calculations. Must be greater than or equal to reportingInterval. Greater values will reduce noise and increase location accuracy, lesser values will increase responsiveness, Default = 10
reportingInterval
(optional)
Integer
(0 or divisor of 60.)
Frequency in seconds with which the location calculation is performed. Greater values will reduce system load, while lesser values will report changes more quickly. Zero will effectively result in a reporting interval of 500ms. Default = 5

Inventory Recipes:

Parameter Type Description
tagHeartbeatDuration
(optional)
String This is used to control how frequently the lastModifiedTime of a tag is updated when the tag is read but has not moved. Set with a string in ISO 8601 format. representing the time interval between heartbeat updates. Example = “PT10”, Minimum = “PT1M”, Default = “PT5M”
tagExpiryDuration
(optional)
String A string in ISO 8601 format. representing the time interval between the last time ItemSense detected a tag, and the tag being marked ABSENT.

If this parameter is not set, ABSENCE detection via tag expiration is disabled.

If set, this parameter must be greater than the reportingInterval.

This parameter is only available for certain combinations of reader configuration parameters: those that allow ItemSense to receive sufficient data to determine whether a tag has indeed gone absent.

Allowable combinations:
  • configuration.operation=LOCATION
  • configuration.operation=INVENTORY and configuration.searchMode=DUAL_TARGET
Forbidden combinations:
  • configuration.operation=INVENTORY and configuration.searchMode=SINGLE_TARGET
computeWindow
(optional)
Integer Internal use only.
reportingInterval
(optional)
Integer
(Divisor of 60.)
Frequency in seconds with which the inventory calculation is performed. Greater values will reduce system load, while lesser values will report changes more quickly. Default = 5

Threshold Recipes:

Parameter Type Description
thresholdIds
(optional)
List The collection of threshold identifiers to use for this recipe. If omitted, empty, or null, when this recipe is used in a job, all thresholds in the job’s facility will be used. example = [1, 4]
profile
(optional)
String Custom profile data specifying system behavior. If not specified, defaults will be used. Use only under Impinj guidance.
iterationDataLogEnabled
(optional)
boolean Enables or disables the logging of iteration data for use in tuning. Defaults to disabled (false).

Sample Code

var body = {
    "name": "MY_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "READER_CONFIGURATION",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT7M",
    "minimumMovementInMeters": "1.5",
    "computeWindow": "10",
    "reportingInterval": "5",
};

xhr.open("POST", "http://BASE_URL/configuration/v1/recipes/create", true)
// Set authorization headers
xhr.send(body)
var body = {
    name = "MY_RECIPE",
    readerConfigurationName = "READER_CONFIGURATION",
    readerConfigurations = new Dictionary<string, string>(){
        {"xarray-11-22-33.impinj.com", "Example_ReaderConfiguration"},
        {"xarray-44-55-66.impinj.com", "Another_ReaderConfiguration"}
    },
    tagHeartbeatDuration = "PT5M",
    tagExpiryDuration = "PT7M",
    minimumMovementInMeters = 1.5,
    computeWindow = 10,
    reportingInterval = 5,
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/recipes/create");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
// Encode credentials and add to request header
request.Method = "POST";
request.ContentType = "application/json";
using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(recipe);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "name": "MY_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "READER_CONFIGURATION",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT7M",
    "minimumMovementInMeters": "1.5",
    "computeWindow": "10",
    "reportingInterval": "5",
}

Update Recipe

Replace an existing recipe, or create a new one

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/recipes/createOrReplace

Request Body

The same as the Create Recipe Request Body.

Sample Code

var body= {
    "name": "InventoryRecipe",
    "type": "INVENTORY",
    "readerConfigurationName": "INVENTORY_READER_CONFIG",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT7M",
    "computeWindow": "2",
    "reportingInterval": "1",
};

xhr.open("PUT", "http://BASE_URL/configuration/v1/recipes/createOrReplace", true)
// Set authorization headers
xhr.send(body)
// Encode credentials
string encodedCredentials = ...
var recipe = {
    name = "InventoryRecipe",
    type = "INVENTORY,
    readerConfigurationName = "INVENTORY_READER_CONFIG",
    tagHeartbeatDuration = "PT5M",
    tagExpiryDuration = "PT3M",
    computeWindow = "2",
    reportingInterval = "1"
};

Uri uri = new Uri("http://BASE_URL/configuration/v1/recipes/createOrReplace");
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response for RecipeInventory

{
    "name": "InventoryRecipe",
    "type": "INVENTORY",
    "readerConfigurationName": "INVENTORY_READER_CONFIG",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": "PT3M",
    "computeWindow": "2",
    "reportingInterval": "1",
}

Delete Recipe

Delete a specific recipe from the store

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/recipes/destroy/{recipeName}

Path Parameters

Parameter Type Description
recipeName String The name of the recipe to delete

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("DELETE", "http://BASE_URL/configuration/v1/recipes/destroy/MY_RECIPENAME", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/recipes/destroy/MY_RECIPENAME);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "DELETE";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Show Recipe

Show a specific recipe

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/recipes/show/{recipeName}

Path Parameters

Parameter Type Description
recipeName String The name of the recipe to retrieve

Sample Code

// var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/recipes/show/MY_RECIPENAME", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/recipes/show/MY_RECIPENAME);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "name": "NEW_RECIPE_CONFIG",
  "type": "LOCATION",
  "readerConfigurationName": "IMPINJ_LocationConfig",
  "tagHeartbeatDuration": "PT5M",
  "tagExpiryDuration": "PT20S",
  "readerConfigurations": {},
  "minimumMovementInMeters": null,
  "computeWindow": 20,
  "reportingInterval": 5
}

Show Recipes

Show all configured recipes

Authorized Roles

ConfigManager, Admin, JobRunner

HTTP Request

GET http://BASE_URL/configuration/v1/recipes/show

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/recipes/show", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/recipes/show);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "name": "INVENTORY_RECIPE",
    "type": "INVENTORY",
    "readerConfigurationName": "IMPINJ_InventoryConfig",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": null,
    "readerConfigurations": {},
    "computeWindow": 20,
    "reportingInterval": 5
  },
  {
    "name": "LOCATION_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "IMPINJ_LocationConfig",
    "tagHeartbeatDuration": "PT5M",
    "tagExpiryDuration": null,
    "readerConfigurations": {},
    "minimumMovementInMeters": 1,
    "computeWindow": 10,
    "reportingInterval": 5
  }
]

Jobs

An ItemSense job runs a recipe to generate item data.

Start a Job

When a job is started ItemSense will attempt to use all readers in the specified facility that have not been given a configuration of “DO_NOTHING” in the recipe. If you wish to have a job use a subset of these readers you will need to specify a reader group or groups. Reader groups are defined as part of a reader’s definition. When a reader group is specified for the job, only readers that have a matching group will be used.

Authorized Roles

JobRunner, Admin

HTTP Request

POST http://BASE_URL/control/v1/jobs/start

Request Body

Property Type Description
name
(optional)
String The optional name of the job
recipeName String Which recipe to run
facility
(optional, except if using multiple facilities)
String The name of the facility which the job will be run in
durationSeconds
(optional)
Integer The number of seconds for which ItemSense should execute this job. If zero, null, or absent, then the job runs indefinitely
startDelay
(optional)
String An ISO 8601 format duration for which to delay the job’s start. If not specified, defaults to 3 minutes, “PT3M”
readerGroups
(optional)
Array of: String The set of reader groups on which to start the job
reportToDatabaseEnabled
(optional)
Boolean Flag for determining if the job should relay tag reads into the Items database. Note that if this value if false, then data is not available via the Items API. Defaults to true
reportToHistoryEnabled
(optional)
Boolean Flag for determining if the job should relay tag reads into the Item History database. Note that if this value if false, then data is not available via the Item History API. Defaults to true
reportToMessageQueueEnabled
(optional)
Boolean Flag for determining if the job should report configured queue events. Note that if this value if false, then data is not available via the Message Queue interface. Defaults to true
useOtherJobData
(optional)
Boolean Flag for determining if the job should consider data from previous or other active jobs when calculating item zone changes. Defaults to true
reportToFileEnabled *
(obsolete)
Boolean This flag is obsolete and setting it will have no effect

Response

Parameter Type Description
id String The ID of the job in UUID format
status
One of:
WAITING,
INITIALIZING,
STARTING,
RUNNING,
RESTARTING_RDE,
STOPPING,
STOPPED
The status of the job
readerNames Array of: String The collection of readers to which the job applies
failedReaderNames Array of: String The collection of readers that did not acknowledge job start
creationTime String The time the job was created in ISO 8601 format such as “2017-05-02T15:35:01.560Z”
lastActivityTime String The time of last activity in ISO 8601 format such as “2017-05-02T15:35:01.560Z”
activeDuration Integer The duration (in seconds) for which the job has been active
errorOccurred Boolean True when an error has occurred
errors Array of: JobError A list of errors associated with the job
maxErrors Integer The maximum number of errors kept
stopReason One of:
JOB_COMPLETED,
JOB_FAILED,
USER_REQUESTED_GRACEFUL,
USER_REQUESTED_ABRUPT
The reason the job was stopped
facilities Array of: String The facility associated with this job contained in an array of length 1.
job Job The configuration data associated with the job
instanceMetadata JobInstanceMetadata Internal data used by ItemSense
lastHeartbeatTime String The time of last received heartbeat in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
startAttempts Integer The number of times the system has attempted to start the job

JobError

Parameter Type Description
time String The time that the error occured in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
message String The job error message

Sample Code

var job =  {
               recipeName: "IMPINJ_BasicLocation",
               name: "Basic Location Job",
               durationSeconds: 60,
               readerGroups: [ "ceiling", "store_room" ]
             };
var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/jobs/start", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(job));


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/start");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                recipeName = "IMPINJ_BasicLocation",
                name = "Basic Location Job",
                durationSeconds = 60,
                readerGroups = new string[] { "ceiling", "store_room" }
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

{
  "id": "ebc86633-599c-4de9-8aa0-b11ffcb8bdc5",
  "status": "WAITING",
  "readerNames": [
    "READER1",
    "READER2"
  ],
  "creationTime": "2016-06-28T17:27:20.106Z",
  "lastActivityTime": "2016-06-28T17:27:20.106Z",
  "activeDuration": "PT0S",
  "errorOccurred": false,
  "errors": [],
  "maxErrors": 5,
  "stopReason": null,
  "facilities": [
    {
      "name": "HOME"
    }
  ],
  "job": {
    "name": "Basic Location Job",
    "recipeName": "RECIPE1",
    "durationSeconds": 100,
    "startDelay": "PT1M",
    "readerGroups": [ "ceiling", "store_room" ],
    "reportToDatabaseEnabled": true,
    "reportToHistoryEnabled": true,
    "reportToMessageQueueEnabled": true,
    "reportToFileEnabled": false,
    "useOtherJobData": true,
    "facility": "HOME"
  },
  "instanceMetadata": null,
  "lastHeartbeatTime": null,
  "startAttempts": 0
}

Stop a Running Job

Authorized Roles

JobRunner, Admin

HTTP Request

POST http://BASE_URL/control/v1/jobs/stop/{jobId}

Parameters

Parameter Type Description
jobId String The ID of the job to stop
graceful Boolean Whether the job should be stopped gracefully or suddenly (defaults to true)

Sample Code


var jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/jobs/stop/" + jobId, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/stop/" + jobId);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "POST";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

Get a specific Job

Retrieve a specific job and its status

Authorized Roles

JobRunner, Admin

HTTP Request

GET http://BASE_URL/control/v1/jobs/show/{jobId}

Parameters

Parameter Type Description
jobId String The ID of the job to retrieve

Response

The same as the Create Recipe Request Body.

Sample Code

var jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/control/v1/jobs/show/" + jobId, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string jobId= "9e1b45bb-1453-448a-9467-7540964b8004";

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/show/" + jobId);

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

The same as Jobs Start Sample Response

Get All Jobs

Authorized Roles

JobRunner, Admin

HTTP Request

GET http://BASE_URL/control/v1/jobs/show

Parameters

Parameter Type Description
startedBefore String Filter to jobs that have been started before the given time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
startedAfter String Filter to jobs that have been started after the given time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
lastActivityBefore String Filter to jobs that have the last activity time before the given time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
lastActivityAfter String Filter to ZonedDateTimeParam that have the last activity time after the given time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
sortBy One of:
name,
creationTime,
lastActivityTime
The property by which to sort the returned jobs. Defaults to lastActivityTime
sortOrder One of:
asc,
desc
Whether to sort the jobs in ascending or descending order. Defaults to descending
status Array Filter to jobs that match the given status, can be supplied multiple times
latest Integer Filter to latest N jobs. Defaults to 1.

Response

Array of: Jobs Start Response

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("POST", "http://BASE_URL/control/v1/jobs/show/", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/control/v1/jobs/show");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

An array of: Jobs Start Sample Response

Items

An Item is any object fixed with an RFID tag. This API conducts item-level data queries for subsets matching supplied criteria (such as location).

The API is very simple, with just three endpoints; one to show items, another to show the history of items and the final to show when items transition through monitored thresholds.

Get Items

Query current items.

Authorized Roles

DataReader, Admin

HTTP Request

GET http://BASE_URL/data/v1/items/show

Parameters

Parameter Type Description
epcPrefix
(optional)
String A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
jobId
(optional)
String A UUID job identifier, such as “ffa29f71-f0f9-426e-9ba4-45398361dc5d”. This parameter identifies the job that last saw the item.
zoneNames
(optional)
String A comma-separated list of zone names. Only items in these zones will be returned
facility
(optional)
String A string indicating the name of a facility. Only items in this facility will be returned
presenceConfidence
(optional)
One of:
HIGH,
LOW
(deprecated) - passing either value has no effect on the query, producing the same result as not including the parameter at all.
fromTime
(optional)
String Items which were last updated on or after this time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”.
toTime
(optional)
String Items which were updated before this time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”.
epcFormat
(optional)
One of: PURE_ID
TAG
RAW
UPC12
DEFAULT
Format of the EPC string. Defaults to raw hex strings if this parameter is not specified. All the options except DEFAULT and RAW will return only results with valid encoding. DEFAULT option gives the default format for the encoding. If the EPC is not encoded correctly, then the RAW format is used
pageMarker
(optional)
String A string indicating which page of results to return. A new marker is returned after each query and can be used to fetch subsequent pages. When using a page marker, the other query parameters must be the same as those used in the previous query.
pageSize
(optional)
Integer The number of records to return per query (Max of 1000, defaults to 100)

Response

Parameter Type Description
items Array of:Item The list of currently detected items

Sample Code

var xhr = new XMLHttpRequest();
//return the next page's data 

//Note: Libraries such as JQuery.Param({pageMarker: "u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk"}) will simply handling query parameters.
var url = sprintf("http://BASE_URL/data/v1/items/show?pageMarker=%1$s", encodeURIComponent("u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk") );
xhr.open("GET", url, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

string url = String.Format("http://BASE_URL/data/v1/items/show/history?pageMarker={0}", Uri.EscapeDataString("ZmeLu/fWX4e+s1CUxOxeXrrMdV415+LcdzEnZiFeUavMkEKYzZCcwwV8CKFUcUJI") );

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(url);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";

2   
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "items":[
      {
         "epc":"111100000000000000000019",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "xLocation":6.3,
         "yLocation":9.2,
         "zLocation":0,
         "zone":"ZONE1",
         "facility":HOME,
         "presenceConfidence":"HIGH",
         "lastModifiedTime":"2016-02-23T00:38:42Z"
      },
      {
         "epc":"300833B2DDD9000500010004",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "xLocation":1.9,
         "yLocation":2.1,
         "zLocation":0,
         "zone":"ZONE2",
         "facility":"HOME",
         "presenceConfidence":"HIGH",
         "lastModifiedTime":"2016-02-23T00:37:57Z"
      }
  ],
  "nextPageMarker": "bozBcaT89jaLIuUy+gdkWm8xz8FRimZz8++6HHecp9vNvz4PLFxwZeCWAN666lTE"
}

Get Item History

Query the history of items. A historic record for an item is created each time an Item transitions from one zone to another.

Authorized Roles

DataReader, Admin

HTTP Request

GET http://BASE_URL/data/v1/items/show/history

Parameters

Parameter Type Description
epcPrefix
(optional)
String A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
jobId
(optional)
String A UUID job identifier, such as “ffa29f71-f0f9-426e-9ba4-45398361dc5d”. This parameter identifies the job that reported the change in the item.
fromZone
(optional)
String A string zone identifier, such as “Men’s Department”. This parameter identifies the zone that the item moved out of.
toZone
(optional)
String A string zone identifier, such as “Men’s Department”. This parameter identifies the zone that the item moved into.
fromFacility
(optional)
String A string facility identifier, such as “Seattle Location”. This parameter identifies the facility that the item moved out of.
toFacility
(optional)
String A string facility identifier, such as “Seattle Location”. This parameter identifies the facility that the item moved into.
fromTime
(optional)
String Events which occurred on or after this time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
toTime
(optional)
String Events which occurred before this time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
epcFormat
(optional)
One of:
PURE_ID,
TAG,
RAW,
UPC12,
DEFAULT
Format of the EPC string. Defaults to raw hex strings if this parameter is not specified. All the options except DEFAULT and RAW will return only results with valid encoding.DEFAULT option gives the default format for the encoding. If the EPC is not encoded correctly, then the RAW format is used.
zoneTransitionsOnly
(optional)
Boolean Will restrict results to items that moved zones, defaults to true
minDistanceMoved
(optional)
Number Will restrict results to items that moved more than the minimum distance supplied (in meters).
pageMarker
(optional)
String A string indicating which page of results to return. A new marker is returned after each query and can be used to fetch subsequent pages. When using a page marker, the other query parameters must be the same as those used in the previous query. When paired with the nextPageMarker field, this flag is beneficial for re-querying the same filtered data set at a later time, and expecting to only see the newest records.
pageSize
(optional)
Integer The number of records to return per query. The maximum value of this parameter is 1000. The default value is 100.
alwaysIncludePageMarker
(optional)
Boolean Always include the page marker in the query results.

Response

Parameter Type Description
history Array of: ItemEvent A list of item events filtered according to the submitted query
nextPageMarker String A string representing the place in the history where the next set of records begin
moreHistoryAvailable Boolean Whether there is more history available or this is the last set of records

Sample Code

var xhr = new XMLHttpRequest();
//return the next page's data 

//Note: Libraries such as JQuery.Param({pageMarker: "u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk"}) will simply handling query parameters.
var url = sprintf("http://BASE_URL/data/v1/items/show/history?pageMarker=%1$s", encodeURIComponent("u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk") );
xhr.open("GET", url, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

//return the next page's data
string url = String.Format("http://BASE_URL/data/v1/items/show/history?pageMarker={0}", Uri.EscapeDataString("ZmeLu/fWX4e+s1CUxOxeXrrMdV415+LcdzEnZiFeUavMkEKYzZCcwwV8CKFUcUJI") );

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(url);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "history":[
      {
         "epc":"5BBA7E85407C51D8",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "fromZone":"ZONE1",
         "toZone":"ZONE2",
         "fromFacility":DEFAULT,
         "fromFloor": "1"
         "toFacility":"DEFAULT",
         "toFloor": "1"
         "fromX":12,9,
         "fromY":10.4,
         "toX":2.4,
         "toY":2.7,
         "observationTime":"2016-02-23T00:37:16Z"
      },
      {
         "epc":"111100000000000000000019",
         "tagId":"000000000000",
         "jobId":"ffa29f71-f0f9-426e-9ba4-45398361dc5d",
         "fromZone":"ZONE2",
         "toZone":"ZONE1",
         "fromFacility":null,
         "fromFloor": "1",
         "toFacility":"DEFAULT",
         "toFloor": "1",
         "fromX":null,
         "fromY":null,
         "toX":12.2,
         "toY":10.7,
         "observationTime":"2016-02-23T00:37:16Z"
      }
  ],
  "nextPageMarker": "xjR3rD6qFcV+p3yUurz0FIMSYHqxarq6xuvgVSFvU+crHVRshQ789d5TO6UI5m9w",
  "moreHistoryAvailable": true
}

Get Item Threshold Transitions

Query the transitions of items through facility thresholds. When running with threshold transitions configured a record of each transition for each item is kept.

Authorized Roles

DataReader, Admin

HTTP Request

GET http://BASE_URL/data/v1/items/show/transitions

Parameters

Parameter Type Description
epcPrefix
(optional)
String A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned.
jobId
(optional)
String A UUID job identifier, such as “ffa29f71-f0f9-426e-9ba4-45398361dc5d”. This parameter identifies the job that reported the transition of the item.
thresholdId
(optional)
Integer A numeric threshold ID. Only items that transitioned through this threshold will be returned. If provided, thresholdName must not be used.
thresholdName
(optional)
String A string threshold name. Only items that transitioned through this threshold will be returned. If provided, thresholdId must not be used.
destination
(optional)
String A string destination identifier, such as “OUT”. This parameter identifies the destination that the item transitioned to.
facility
(optional)
String A facility name. Only transitions that occurred through thresholds in this facility will be returned. Additionally specifying a threshold (by name or by id) is allowed but not useful.
fromTime
(optional)
String Events which occurred on or after this time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”.
toTime
(optional)
String Events which occurred before this time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”.
epcFormat
(optional)
One of:
PURE_ID,
TAG,
RAW,
UPC12,
DEFAULT
Format of the EPC string. Defaults to raw hex strings if this parameter is not specified. All the options except DEFAULT and RAW will return only results with valid encoding.DEFAULT option gives the default format for the encoding. If the EPC is not encoded correctly, then the RAW format is used.
pageMarker
(optional)
String A string indicating which page of results to return. A new marker is returned after each query and can be used to fetch subsequent pages. When using a page marker, the other query parameters must be the same as those used in the previous query. When paired with the nextPageMarker field, this flag is beneficial for re-querying the same filtered data set at a later time, and expecting to only see the newest records.
pageSize
(optional)
Integer The number of records to return per query. The maximum value of this parameter is 1000. The default value is 100.
alwaysIncludePageMarker
(optional)
Boolean Always include the page marker in the query results.

Response

Parameter Type Description
transitions Array of: ItemThresholdTransitionEvent A list of item threshold transition events filtered according to the submitted query
nextPageMarker String A string representing the place in the history where the next set of records begin
moreTransitionsAvailable Boolean Whether there is are more transition records available or this is the last set of records

Sample Code

var xhr = new XMLHttpRequest();
//return the next page's data 

//Note: Libraries such as JQuery.Param({pageMarker: "u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk"}) will simply handling query parameters.
var url = sprintf("http://BASE_URL/data/v1/items/show/transitions?pageMarker=%1$s", encodeURIComponent("u9tpuBjMfPdXS9TL5ZQCmbdwfEGKfLNGzBMhJQudSdYHdhjR0/Rd6LH2ReOJ3Mhk") );
xhr.open("GET", url, true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

//return the next page's data
string url = String.Format("http://BASE_URL/data/v1/items/show/transitions?pageMarker={0}", Uri.EscapeDataString("ZmeLu/fWX4e+s1CUxOxeXrrMdV415+LcdzEnZiFeUavMkEKYzZCcwwV8CKFUcUJI") );

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(url);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";
request.ContentType = "application/json";


HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "transitions":[
    {
      "thresholdTransitionId": 1,
      "epc": "epc1",
      "jobId": "jobid1",
      "thresholdId": 1,
      "destination": "out",
      "confidence": 1,
      "creationTime": "2017-03-01T22:46:59Z"
    },
    {
      "thresholdTransitionId": 2,
      "epc": "epc2",
      "jobId": "jobid1",
      "thresholdId": 1,
      "destination": "out",
      "confidence": 1,
      "creationTime": "2017-03-01T22:48:10Z"
    },
    {
      "thresholdTransitionId": 3,
      "epc": "epc3",
      "jobId": "jobid1",
      "thresholdId": 1,
      "destination": "out",
      "confidence": 1,
      "creationTime": "2017-03-01T22:48:15Z"
    }
  ],
  "nextPageMarker": "xjR3rD6qFcV+p3yUurz0FIMSYHqxarq6xuvgVSFvU+crHVRshQ789d5TO6UI5m9w",
  "moreTransitionsAvailable": true
}

Item Data Message Queue

ItemSense provides an AMQP-based real-time event push system in addition to its REST query APIs.

A queue is configured with a specific query, then the client connects to this queue to receive messages that match the configured query.

Each parameter in the request body acts as a filtered item for that specific queue. If multiple parameters are present in the request body, queue messages will only be created if all filtered parameters are matched.

Authorized Roles

DataReader, Admin

HTTP Request

PUT http://BASE_URL/data/v1/items/queues

Request Body

Property Type Description
fromFacility String The name of a facility to monitor for tag exit events
toFacility String The name of a facility to monitor for tag entry events
fromZone String The name of the zone to monitor for tag exit events
toZone String The name of the zone to monitor for tag entry events
epc String A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
jobId String The ID of the job to monitor for tag events
distance Number The minimum distance a tag must move before a queue event (or message) is created
zoneTransitionsOnly Boolean Flag to only create queue events for tags that have transitioned between zones. Default value is true.

Sample Code

var messageQueue = {
 fromZone: "ABSENT",
 toZone: "FACILITY"
};
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/data/v1/items/queues", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(messageQueue));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

var messageQueue = new
                  {
                    fromZone = "ABSENT",
                    toZone = "FACILITY"

                  };
Uri uri = new Uri("http://BASE_URL/data/v1/items/queues");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(messageQueue);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "serverUrl": "amqp://localhost:5672/%2F",
  "queue": "1127b6d0c96f6c55d42e54b390f9a6c50fc4911b956c1a3128a2e26c3f6481cd"
}

Queue Message Data

Once a message queue has been configured, messages that match the filter criteria will be appended to the queue.

The structure of each element in the queue is the same as an ItemEvent record in the Item History list.

Threshold Data Message Queue

ItemSense provides an AMQP-based real-time event push system in addition to its REST query APIs.

A threshold queue is configured with a specific query, then the client connects to this queue to receive messages that match the configured query.

Each parameter in the request body acts as a filtered item for that specific queue. If multiple parameters are present in the request body, queue messages will only be created if all filtered parameters are matched.

Authorized Roles

DataReader, Admin

HTTP Request

PUT http://BASE_URL/data/v1/items/queues/threshold

Request Body

Property Type Description
threshold String The name of a threshold to monitor for events
jobId String The ID of the job to monitor for events

Sample Code

var messageQueue = {
 threshold: "REAR_THRESHOLD"
};

var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/data/v1/items/queues/threshold", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(messageQueue));

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

var messageQueue = new
                  {
                    threshold = "REAR_THRESHOLD"
                  };

Uri uri = new Uri("http://BASE_URL/data/v1/items/queues/threshold");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{
    string data = new JavaScriptSerializer().Serialize(messageQueue);
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "serverUrl": "amqp://localhost:5672/%2F",
  "queue": "1127b6d0c96f6c55d42e54b390f9a6c50fc4911b956c1a3128a2e26c3f6481cd"
}

Threshold Queue Message Data

Once a message queue has been configured, messages that match the filter criteria will be appended to the queue.

The structure of each element in the queue is a ItemThresholdTransitionEvent.

Data Definitions

Item

Parameter Type Description
epc String The EPC of the item
tagId String The ID of the tag that was read. Note that ItemSense does not currently provide the tagId, and the value of this field is always set to “000000000000”
jobId String The ID of the job that last saw the item
xLocation Float The x coordinate of the item’s location
yLocation Float The y coordinate of the item’s location
zLocation Float The z coordinate of the item’s location
zone String The name of the zone in which the item was read
floor String The name of the floor on which the item was read
facility String The facility in which the item was read
presenceConfidence String (deprecated) - always returns HIGH. This value should no longer be relied upon as an indication of presence confidence.
lastModifiedTime String The time at which the item was read in ISO-8601 format such as “2017-05-02T15:35:01.560Z”

ItemEvent

Parameter Type Description
epc String The EPC of the tag for which the event occurred
tagId String The ID of the tag that was read. Note that ItemSense does not currently provide the tagId, and the value of this field is always set to “000000000000”
jobId String The ID of the job that reported the change in the item
fromZone String The name of the zone from which the tag moved
toZone String The name of the zone to which the tag moved
fromFloor String The name of the floor from which the tag moved
toFloor String The name of the floor to which the tag moved
fromFacility String The name of the facility from which the tag moved
toFacility String The name of the facility to which the tag moved
fromX Float The x coordinate of the location from which the tag moved
toX Float The x coordinate of the location to which the tag moved
fromY Float The y coordinate of the location from which the tag moved
toY Float The y coordinate of the location to which the tag moved
observationTime String The time at which the event occurred in ISO-8601 format such as “2017-05-02T15:35:01.560Z”

ItemThresholdTransitionEvent

Parameter Type Description
epc String The EPC of the tag for which the event occurred
thresholdTransitionId Integer The ID of the specific transition record
jobId String The ID of the job that generated the transition record
thresholdId Integer The ID of the threshold where this transition occurred
destination String The name of the destination that the item transitioned to
confidence Float The confidence value of the transition event
creationTime String The time at which the transition was recorded in ISO-8601 format such as “2017-05-02T15:35:01.560Z”

QueuedThresholdTransitionEvent

Parameter Type Description
epc String The EPC of the tag for which the event occurred
observationTime Integer The time at which the transition was recorded in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
fromZone String The type of transition, being “IN” or “OUT” this will always be the opposite value of toZone
toZone String The type of transition, being “IN” or “OUT” this will always be the opposite value of fromZone
threshold String The name of the threshold where this transition occurred
dockDoor String Deprecated. This property duplicates the threshold property and exists for backwards compatibility only.
jobId String The ID of the job that generated the transition record
confidence Float The confidence value of the transition event

Health

A read-only interface to query reader health status

Reader

Show the health of a single reader

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

GET http://BASE_URL/health/v1/readers/{readerName}

Path Parameters

Parameter Type Description
readerName String The name of the reader

Response

Parameter Type Description
readerName String The name of the reader
state One of: AWAITING_AGENT
IDLE
RUNNING_JOB
UPDATING_FIRMWARE
NOT_RESPONDING
ERROR
The state of the reader
lastCheckin String The time at which the reader last contacted itemsense in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
lastReboot String The time at which the reader was last re-booted in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
version object The version of firmware that the reader is running
connectionStatus ConnectionStatus The status of the health and monitoring connection to the reader
throughputStatus ThroughputStatus The throughput status of the reader
clockSyncStatus ClockSyncStatus The clock sync status of the reader
hardwareStatus HardwareStatus The hardware status of the reader
softwareStatus SoftwareStatus The software status of the reader

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/health/v1/readers/MY_READERNAME", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/readers/MY_READERNAME);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "readerName": "xArray-11-4D-3D",
  "state": "IDLE",
  "lastCheckin": "2016-08-23T15:33:59.496Z",
  "lastReboot": "2016-08-23T14:41:33.378Z",
  "version": {
    "App": "0.0.1.15",
    "Firmware": "5.6.2.240"
  },
  "connectionStatus": {
    "status": "HEALTHY",
    "code": null
  },
  "throughputStatus": {
    "status": "HEALTHY",
    "code": null
  },
  "clockSyncStatus": {
    "status": "HEALTHY",
    "code": null,
  },
  "hardwareStatus": {
    "status": "HEALTHY",
    "code": null,
    "devices": null
  },
  "softwareStatus": {
    "status": "HEALTHY",
    "code": null
  }
}

Readers

Show the health of all readers

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

GET http://BASE_URL/health/v1/readers

Response

An array of: Reader Health Response

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/health/v1/readers", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/readers);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
  {
    "readerName": "xArray-11-4D-3D",
    "state": "RUNNING_JOB",
    "lastCheckin": "2016-08-23T20:08:57.771Z",
    "lastReboot": "2016-08-23T16:02:24.410Z",
    "version": {
      "App": "0.0.1.15",
      "Firmware": "5.6.2.240"
    },
    "connectionStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "throughputStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "clockSyncStatus": {
      "status": "HEALTHY",
      "code": null,
    },
    "hardwareStatus": {
      "status": "HEALTHY",
      "code": null,
      "devices": null
    },
    "softwareStatus": {
      "status": "HEALTHY",
      "code": null
    }
  },
  {
    "readerName": "xArray-11-42-2B",
    "state": "IDLE",
    "lastCheckin": "2016-08-23T20:08:57.403Z",
    "lastReboot": "2016-08-23T19:36:19.390Z",
    "version": {
      "App": "0.0.1.15",
      "Firmware": "5.8.0.26"
    },
    "connectionStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "throughputStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "clockSyncStatus": {
      "status": "HEALTHY",
      "code": null
    },
    "hardwareStatus": {
      "status": "HEALTHY",
      "code": null,
      "devices": null
    },
    "softwareStatus": {
      "status": "HEALTHY",
      "code": null
    }
  }
]

Events

Search health events

Authorized Roles

Admin, ConfigManager, DataReader, JobRunner

HTTP Request

POST http://BASE_URL/health/v1/events

Request Body

Parameter Type Description
readerNames Array of: String The set of reader names for which to query health events
types Array of: String The set of status types for which to query health events
codes Array of: String The set of status codes for which to query health events
fromTime String The beginning of the query time period in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
toTime String The end of the query time period in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
pageSize Integer The number of events to return per query
nextPageMarker String The marker of the next page to return

Response

Parameter Type Description
events Array of: HealthEvent List of reader health events
nextPageMarker String The value of the marker to supply for the next page of reader health results

Sample Code

var body = {
    "types": ["LIFECYCLE"]
};
var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/health/v1/events", true)
// Set authorization headers
xhr.send(body)
var body = {
    "types": ["LIFECYCLE"]
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/events);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
using (StreamWriter sw = new StreamWriter(request.GetRequestStream())
{
    string data = new JavaScriptSerializer().Serialize(body);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "events": [
    {
      "eventTime": "2016-08-23T14:41:33.378Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "REBOOT",
      "args": {
        "reason": "BootReason='Cold'"
      }
    },
    {
      "eventTime": "2016-08-23T14:02:46.316Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "REBOOT",
      "args": {
        "reason": "BootReason='Cold'"
      }
    },
    {
      "eventTime": "2016-08-22T22:57:55.217Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "VERSION_UPDATE",
      "args": {
        "newVersion": "{\"App\":\"0.0.1.15\",\"Firmware\":\"5.6.2.240\"}"
      }
    },
    {
      "eventTime": "2016-08-22T22:57:54.337Z",
      "readerName": "xArray-11-4D-3D",
      "type": "LIFECYCLE",
      "code": "REBOOT",
      "args": {
        "reason": "BootReason='Processor / Reboot'"
      }
    }
  ],
  "nextPageMarker": null
}

Event Queue

Configure a queue to receive health event messages with the given filter

Authorized Roles

Admin, DataReader

HTTP Request

PUT http://BASE_URL/health/v1/events/queues

Request Body

Parameter Type Description
readerName String The name of the reader to query
type One of: CONNECTION
THROUGHPUT
CLOCK_SYNC
HARDWARE_FAULT
SOFTWARE_FAULT
LIFECYCLE
UNCLASSIFIED
The type of health event to query
code String The status code to query

Response

Parameter Type Description
serverUrl String The URL of the reader health event queue
queue String The queue identifier

Sample Code

var body = {
    "readerName": "xArray-11-4D-3D",
    "type": "CONNECTION",
    "code": "NETWORK",
};
var xhr = new XMLHttpRequest()
xhr.open("PUT", "http://BASE_URL/health/v1/events/queues", true)
// Set authorization headers
xhr.send(body)
var body = {
    "readerName": "xArray-11-4D-3D",
    "type": "CONNECTION",
    "code": "NETWORK",
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/health/v1/events/queues);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "PUT";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
using (StreamWriter sw = new StreamWriter(request.GetRequestStream())
{
    string data = new JavaScriptSerializer().Serialize(body);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
  "serverUrl": "amqp://localhost:5672/%2F",
  "queue": "8913429d-d11e-404f-ab1a-9c01da4a9f0a"
}

Data Definitions

Each of the Reader Status objects has a status and a code property. When the status is HEALTHY, the code will be null. When the status is WARNING or FAILED, the code should be one of several values (see Code Details below).

ConnectionStatus

Parameter Type Description
status One of: HEALTHY
WARNING
FAILED
The status of the connection
code One of: BAD_CERTIFICATE
HTTP_FAILURE
or NETWORK
See Code Details

ThroughputStatus

Parameter Type Description
status One of: HEALTHY
WARNING
FAILED
The status of reader throughput
code One of: DROPPED_READ
REPORT_BUFFER
TAG_POPULATION_OVERFLOW
See Code Details

ClockSyncStatus

Parameter Type Description
status One of: HEALTHY
WARNING
FAILED
The status of network clock (NTP) synchronization
code One of: NTP
CLOCK_SYNC
See Code Details

HardwareStatus

Parameter Type Description
status One of: HEALTHY
WARNING
FAILED
The hardware status
code One of: READER_COMMAND
READER_EXCEPTION
READER_RESTART
UPGRADE_STATUS
See Code Details
devices Array of: DeviceStatus The status of each hardware device (e.g. all of the antennas on a reader)

DeviceStatus

Parameter Type Description
device String The hardware device e.g. a specific antenna
code String An optional string code HealthCode associated with the status

SoftwareStatus

Parameter Type Description
status One of: HEALTHY
WARNING
FAILED
The status of reader throughput
code One of: CHECKSUM
COMMAND_NOT_FOUND
CONFIG_SERVICE_SET
EXTERNAL_COMMAND
FILE_SYSTEM
INVALID_SET_VARIABLE
UNMARSHAL
LLRP
PROVISIONING
READER_CONNECTION
CRASH
AGENT_OUTDATED
See Code Details

HealthEvent

Parameter Type Description
eventTime String The time of the event in ISO 8601 format such as “2017-05-02T15:35:01.560Z”
readerName String The name of the reader
type One of:
CONNECTION
THROUGHPUT
CLOCK_SYNC
HARDWARE_FAULT
SOFTWARE_FAULT
LIFECYCLE
UNCLASSIFIED
The type of event
code String See Code Details
args Object Additional event-specific properties, often including a helpful message about the cause of the event

Code Details

Below is a listing of all valid Type and Code combinations as they can appear in Health Events and in Reader Statuses. The same codes are used in both places. Note that not every Health Event type maps to a Reader Status property, and there are no currently known codes that appear in a DeviceStatus.

# Code Reader Status Property Description
1 BAD_CERTIFICATE ConnectionStatus 1. During provisioning. If invalid certificate is supplied by the IMC when accessing the /provision endpoint. (Note that this process returns a certificate for use on the ItemSense agent channel)
2. After provisioning. If the returned certificate starts failing
2 HTTP_FAILURE ConnectionStatus Anytime ItemSense returns a non successful HTTP status code. Can also happen during provisioning, when the agent “tests” the ItemSense HTTP connection settings.
3 NETWORK ConnectionStatus Something else went wrong with the network connection. e.g. network timeout
4 DROPPED_READ ThroughoutStatus Agent data buffer overflow error
5 REPORT_BUFFER ThroughputStatus Internal agent buffer is full or nearly full (conditions are distinguished by a message on the health event)
6 TAG_POPULATION_OVERFLOW ThroughputStatus Too many tags (in direction or location mode)
7 NTP ClockSyncStatus The on-reader NTP program failed to synchronize with a time provider, implying that the timestamps on reader are unreliable. (Implies an NTP server is running on the network (internal if no Internet connection))
8 CLOCK_SYNC ClockSyncStatus An agent report was received from the reader which showed that the reader’s clock is significantly off from the server’s clock.
The report was dropped by ItemSense in order to prevent issues that occur with determining an endpoint’s latest location when readers’ clocks differ.
9 READER_COMMAND HardwareStatus Generated when any LLRP reader command does not return a successful status reply
10 READER_EXCEPTION HardwareStatus Asynchronous notification from the reader (reported via LLRP) of an uncategorized error condition
11 READER_RESTART HardwareStatus Reader closed LLRP connection unexpectedly and the agent could not re-open it
12 UPGRADE_STATUS HardwareStatus When the upgrade (agent or firmware) process encounters any kind of error, or times out
13 CHECKSUM SoftwareStatus Checksum failure of either CAP or firmware image
14 COMMAND_NOT_FOUND SoftwareStatus Agent is sent an unknown command by ItemSense
15 CONFIG_SERVICE_SET SoftwareStatus Surfaced when an error is encountered in the agent config (In practice, this is a software error, or the config file is corrupted)
16 EXTERNAL_COMMAND SoftwareStatus A program invoked in the octane firmware by the agent returned an error code, or a response that could not be processed
17 FILE_SYSTEM SoftwareStatus Any file system error within the agent process (usually due to full or corrupted file system)
18 INVALID_SET_VARIABLE SoftwareStatus Agent is sent an invalid variable set command by ItemSense (type, range etc)
19 UNMARSHAL SoftwareStatus ItemSense sent invalid or corrupted data
20 LLRP SoftwareStatus 1. Invalid RF configurations are specified by ItemSense
2. Invalid LLRP packet was sent to the agent by the reader
21 PROVISIONING SoftwareStatus 1. Invalid provisioning settings
2. Provisioning module failed to start (http server failed to start)
22 READER_CONNECTION SoftwareStatus Failed to open or close the LLRP connection, or to receive a message over LLRP
23 CRASH SoftwareStatus The agent crashed and the reader is about to reboot
24 AGENT_OUTDATED SoftwareStatus An agent report was received from the reader which did not report the reader’s time. ItemSense accepted the report, but this is potentially risky because ItemSense will not know if the reader’s clock is or becomes out of sync.
Upgrading the reader’s Agent software is highly recommended.
25 REBOOT None Communicates the previous reboot reason. (Note: This event does not contribute to bad health status)
26 HEALTH_RESET None Is a signal used when computing reader status, to indicate ItemSense should disregard all health events older than this one
27 KNOWN None Any other exception that is expected by the Agent but not by ItemSense, including unknown SNMP events from the reader
28 UNKNOWN None Anything not previously defined or expected.

Software

Reader software (firmware) can be queried and upgraded via these endpoints.

List Images

Show all versions of a specific image type

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/softwareVersions/list/{imageType}

Path Parameters

Parameter Type Description
imageType One of: FIRMWARE_SPEEDWAY
CAP_ITEMSENSE
The type of image

Response

An array of:

Parameter Type Description
versionInfo VersionInfo The version information associated with the image
description String A string describing the version
created String The time at which the image was created in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
updated String The time at which the image was updated in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
updateComment String A comment associated with the update
recordVersionNumber Integer An integer representing the update revision number

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/softwareVersions/list/FIRMWARE_SPEEDWAY", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/softwareVersions/list/FIRMWARE_SPEEDWAY);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
    {
        "versionInfo": {
            "versionIdentifier": {
                "version": "5.6.2.240",
                "imageType": "FIRMWARE_SPEEDWAY",
            },
            "imageName": "octane-5.6.2.240.upg",
            "checksum": "076dae4e1c37037a42e37d012014ad62",
        },
    "description": "Octane v5.6.2.240",
    "created": "2016-09-06T18:21:08.000Z",
    "updated": "2016-09-06T18:21:08.000Z",
    "updateComment": null,
    "recordVersionNumber": 1
    },
    ...
]

Show Image

Show a specific software image by type and version

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/softwareVersions/show/{imageType}/{version}

Path Parameters

Parameter Type Description
imageType One of: FIRMWARE_SPEEDWAY
CAP_ITEMSENSE
The type of image
version String The version of the software image

Response

Parameter Type Description
versionInfo VersionInfo The version information associated with the image
description String A string describing the version
created String The time at which the image was created in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
updated String The time at which the image was updated in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
updateComment String A comment associated with the update
recordVersionNumber Integer An integer representing the update revision number

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/configuration/v1/softwareVersions/show/FIRMWARE_SPEEDWAY/MY_VERSION", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/configuration/v1/softwareVersions/show/FIRMWARE_SPEEDWAY/MY_VERSION);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "versionInfo": {
        "versionIdentifier": {
            "version": "5.6.2.240",
            "imageType": "FIRMWARE_SPEEDWAY",
        },
        "imageName": "octane-5.6.2.240.upg",
        "checksum": "076dae4e1c37037a42e37d012014ad62",
    },
    "description": "Octane v5.6.2.240",
    "created": "2016-09-06T18:21:08.000Z",
    "updated": "2016-09-06T18:21:08.000Z",
    "updateComment": null,
    "recordVersionNumber": 1
}

VersionInfo

Parameter Type Description
versionIdentifier VersionIdentifier The version of the software image
imageName String The name of the software image
checksum String The checksum of the image

VersionIdentifier

Parameter Type Description
version String The version of the software image
imageType One of: FIRMWARE_SPEEDWAY
CAP_ITEMSENSE
The type of image

Show Upgrades

List all of the software upgrade jobs

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/control/v1/upgrades/show

Response

An array of:

Parameter Type Description
id String Identifier of the request
upgradeRequest UpgradeRequest Details of the upgrade request
created String When the upgrade was created in ISO-8601 format such as ‘2017-05-02T15:35:56.456Z’
updated String When the upgrade was last updated in ISO-8601 format such as '2017-05-02T15:35:56.456Z’
numDevices Integer The number of devices being upgraded
isCancelled boolean Whether or not the request to upgrade has been cancelled
numFailures Integer The number of devices that have failed to upgrade

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/control/v1/upgrades/show", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/show);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

[
    {
        "id": "",
        "upgradeRequest": {
            "target": {
                "type": "Facility",
                "values": "[MY_FACILITY]",
            },
            "versionIdentifier": {
                "version": "5.6.2.240",
                "imageType": "FIRMWARE_SPEEDWAY",
            },
        "created": "2017-05-02T15:35:56.456Z",
        "updated": "2017-05-02T16:01:45.345Z",
        "numDevices": 10,
        "isCancelled": false,
        "numFailures": 0
    },
    ...
]

Show Upgrade

Show the status of a specific upgrade job

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/control/v1/upgrades/show/{upgradeInstanceId}

Path Parameters

Parameter Type Description
upgradeInstanceId String The ID of the upgrade instance to retrieve

Response

Parameter Type Description
id String The identifier of the upgrade
version VersionIdentifier The software version to which to upgrade the readers
status One of: WAITING
IN_PROGRESS
COMPLETED
FAILED
SKIPPED
The status of the upgrade
target UpgradeRequestTarget The criteria for specifying the set of readers to upgrade
details UpgradeStatusDetails The upgrade status details
elapsedTimeSeconds Integer The elapsed time of the upgrade
lastUpdatedTime String The time that the reader was last updated

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/control/v1/upgrades/show/7df1a27b-64d2-485c-9140-215c1e5b55cc", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/show/7df1a27b-64d2-485c-9140-215c1e5b55cc);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "id": "",
    "version": {
        "version": "5.6.2.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    },
    "status": "IN_PROGRESS",
    "target": {
        "type": "Facility",
        "values": ["MY_FACILITY"],
    },
    "details": {
        "readers": [
        {
            "name": "SpeedwayR-11-79-9D",
            "previousVersion": {
                "version": "5.6.2.240",
                "imageType": "FIRMWARE_SPEEDWAY"
            },
            "status": "WAITING",
            "elapsedTimeSeconds": 0,
            "lastUpdatedTime": "2016-09-06T22:27:31Z"
        },
        {
            "name": "xArray-11-3F-5F",
            "previousVersion": {
                "version": "0.0.0.0",
                "imageType": "FIRMWARE_SPEEDWAY"
            },
            "status": "IN_PROGRESS",
            "elapsedTimeSeconds": 0,
            "lastUpdatedTime": "2016-09-06T22:27:37.428Z"
      },
      {
            "name": "SpeedwayR-11-1E-13",
            "previousVersion": {
                "version": "0.0.0.0",
                "imageType": "FIRMWARE_SPEEDWAY"
            },
            "status": "WAITING",
            "elapsedTimeSeconds": 0,
            "lastUpdatedTime": "2016-09-06T22:27:31Z"
      }
    ]
  },
  "elapsedTimeSeconds": 5,
  "lastUpdatedTime": "2016-09-06T22:27:36.185Z"
}

A Note About Software Versions

In the Sample Response above, note each reader’s previousVersion property. SpeedwayR-11-79-9D shows a previous version of 5.6.2.240 (coincidentally, this is equal to the version being upgraded to in the example), while xArray-11-3F-5F and SpeedwayR-11-1E-13 show a previous version of 0.0.0.0.

This is because the version of the software running on the latter two readers had not been previously registered with ItemSense (see Software Versions). The readers had properly reported in to ItemSense with their versions of the software, but during the process of initializing the software upgrade request, the readers’ software versions were not recognized. For the purposes of this upgrade request, they were replaced by the fallback version 0.0.0.0.

This has no negative impact on the upgrade process.

Start Upgrade

Start a software upgrade

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/control/v1/upgrades/start

Request Body

Parameter Type Description
target UpgradeRequestTarget The criteria for specifying the set of readers to upgrade
versionIdentifier VersionIdentifier The software version to which to upgrade the readers
policy UpgradePolicy The upgrade policy to employ

Response

Parameter Type Description
upgradeInstanceId String Instance identifier of the upgrade

Sample Code

var body = {
    "target": {
        "type": "Facility",
        "values": ["FAC"],
    },
    "versionIdentifier": {
        "version": "5.6.2.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    }
};
var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/control/v1/upgrades/start", true)
// Set authorization headers
xhr.send(body)
var body = {
    "target": {
        "type": "Facility",
        "values": ["FAC"],
    },
    "versionIdentifier": {
        "version": "5.6.2.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    }
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/start);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
using (StreamWriter sw = new StreamWriter(request.GetRequestStream())
{
    string data = new JavaScriptSerializer().Serialize(body);
    sw.Write(data);
}
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
    "upgradeInstanceId": "7df1a27b-64d2-485c-9140-215c1e5b55cc",
}

Cancel Upgrade

Cancel a specific upgrade job

Authorized Roles

ConfigManager, Admin

HTTP Request

POST http://BASE_URL/control/v1/upgrades/stop/{upgradeInstanceId}

Path Parameters

Parameter Type Description
upgradeInstanceId String The ID of the upgrade instance to cancel

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("POST", "http://BASE_URL/control/v1/upgrades/stop/7df1a27b-64d2-485c-9140-215c1e5b55cc", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/control/v1/upgrades/stop/7df1a27b-64d2-485c-9140-215c1e5b55cc);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "POST";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

204 No Content

UpgradeRequest

Parameter Type Description
target UpgradeRequestTarget The criteria for specifying the set of readers to upgrade
versionIdentifier VersionIdentifier The software version to which to upgrade the readers
policy UpgradePolicy The upgrade policy to employ

VersionIdentifier

Parameter Type Description
version String The version of the software image
imageType One of: FIRMWARE_SPEEDWAY
CAP_ITEMSENSE
The type of image

UpgradeRequestTarget

Parameter Type Description
type One of: DEVICE
FACILITY
The criteria for selecting the set of readers to upgrade
values Array of: String The values of the criteria for selecting the set of readers to upgrade (i.e. if type = FACILITY, then a list of facility names, and if type = DEVICE, then a list of reader names)

UpgradeStatusDetails

Parameter Type Description
readers Array of: UpgradeDeviceStatus The upgrade status for each reader

UpgradePolicy

Parameter Type Description
maxParallelReaders integer The maximum number of readers upgrading at any given moment. As readers finish, ItemSense will stay at maxParallelReaders by starting the upgrade process on the next in line. Default: 10
allowedReaderTypes Array of: String The types of readers that are allowed to be upgraded. Default: [SPEEDWAY, XARRAY, XSPAN, XPORTAL]

UpgradeDeviceStatus

Parameter Type Description
name String The name of the reader
previousVersion VersionIdentifier The previous version of the reader software
status One of: WAITING
IN_PROGRESS
COMPLETED
FAILED
The status of the upgrade
elapsedTimeSeconds Integer The elapsed time of the upgrade in seconds
lastUpdatedTime String The time that the reader software was last updated

Settings - SNMP

Configure SNMP authorization and trap destination settings

Update

Update the existing SNMP settings

Authorized Roles

ConfigManager, Admin

HTTP Request

PUT http://BASE_URL/configuration/v1/settings/SNMP

Request Body

Parameter Type Description
authConfig Auth Config The authentication configuration
trapTargetConfig
(optional)
Trap Config The trap configuration

Response

Parameter Type Description
authConfig Auth Config The authentication configuration currently in use
trapTargetConfig Trap Config The trap configuration currently in use

Sample Code

var snmpSettings =  {
                       authConfig: {
                            type: "V2_COMMUNITY",
                            communityName: "foo"
                         },
                        trapTargetConfig: {
                            host: "127.0.0.1",
                            port:162,
                            timeout: "PT05",
                            retries: 2,
                            messageType: "TRAP"
                        }
                      };
var xhr = new XMLHttpRequest();
xhr.open("PUT", "http://BASE_URL/configuration/v1/settings/SNMP", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send(JSON.stringify(snmpSettings));


string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/settings/SNMP");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "PUT";
request.ContentType = "application/json";

using (StreamWriter sw = new StreamWriter(request.GetRequestStream()))
{

    //JavaScriptSerializer.Serialize method produces an equivalent to JSON.stringify()
    string data = new JavaScriptSerializer().Serialize(new
                {
                    authConfig = new
                    {
                        type = "V2_COMMUNITY",
                        communityName = "foo"
                    },
                    trapTargetConfig = new
                    {
                        host = "127.0.0.1",
                        port = 162,
                        timeout = "PT05",
                        retries = 2,
                        messageType = "TRAP"
                    }
                });
    sw.Write(data);
}

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

{
   "authConfig": {
        "type": "V2_COMMUNITY",
        "communityName": "foo"
     },
    "trapTargetConfig": {
        "host": "127.0.0.1",
        "port":162,
        "timeout": "PT05",
        "retries": 2,
        "messageType": "TRAP"
    }
}

Delete

Removes existing SNMP settings. This will stop the SNMP service within ItemSense.

Authorized Roles

ConfigManager, Admin

HTTP Request

DELETE http://BASE_URL/configuration/v1/settings/SNMP

Request Body

None

Response

None

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("DELETE", "http://BASE_URL/configuration/v1/settings/SNMP", true);
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");
xhr.send();

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/settings/SNMP");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "DELETE";
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}


Sample Response

204 No Content

Get

Retrieve current SNMP settings

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/configuration/v1/settings/SNMP

Parameters

None

Response

The properties of the response are the same as that supplied in the Update SNMP response Body.

Sample Code

var xhr = new XMLHttpRequest();
xhr.open("GET", "http://BASE_URL/configuration/v1/settings/SNMP", true);
xhr.requestHeaders("Content-Type", "application/json");
xhr.requestHeaders("Authorization", "Basic ENCODED_USERNAME_PASSWORD");

string username = "CurrentUser";
string password = "CurrentPassword";
string encodedCredentials = System.Convert.ToBase64String(System.Text.Encoding.GetEncoding("ISO-8859-1").GetBytes(username + ":" + password));

Uri uri = new Uri("http://BASE_URL/configuration/v1/settings/SNMP");

HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);

request.Headers.Add("Authorization", "Basic "+ encodedCredentials);
request.Method = "GET";

HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

using (StreamReader streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

Sample Response

{
   "authConfig": {
        "type": "V2_COMMUNITY",
        "communityName": "foo"
     },
    "trapTargetConfig": {
        "host": "127.0.0.1",
        "port":162,
        "timeout": "PT05",
        "retries": 2,
        "messageType": "TRAP"
    }
}

SNMP Settings Data Definitions

Auth Configuration

For SNMP v2

Parameter Type Description
type String Fixed to V2_COMMUNITY
communityName String Community name to authenticate with

For SNMP v3

Parameter Type Description
type String Fixed to V3_USER_PRIV. In this mode, authPriv with SHA + AES encryption is supported
engineId String ID that uniquely identifies the agent in the device
userName String User name to authenticate with
authenticationKey String Authentication key to authenticate with (minimum 8 characters)
privacyKey String Privacy key to authentication with (minimum 8 characters)

Trap Configuration

Parameter Type Description
host String IP Address of the host to send traps to
port String Port of the host to send traps to
timeout String How long to wait before a trap is present if not acknowledged (formatted as ISO-8601 duration)
retries String Number of retries to attempt (total tries will be retries + 1)
messageType String The type of message to send. One of: TRAP, INFORM

Support

Export Logs

Download an export of the ItemSense internal logs for use by Impinj customer support. By default the file downloaded will include 7 days worth of logs starting from now going backwards.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/logs

Path Parameters

Parameter Type Description
from String Filter for logs after the given time in ISO-8601 format such as “2017-03-02T15:35:01.560Z”
to String Filter for logs before the given time in ISO-8601 format such as “2017-05-02T15:35:01.560Z”
extended boolean Include extended logged data. This will include logs not filtered by the ‘from’ and 'to’ parameters

Response

A compressed tar.gz file

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/support/v1/logs?from=2014-01-07T22%3A46%3A00%2B01%3A00", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/logs?fromTime=2014-01-07T22%3A46%3A00%2B01%3A00);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();

Export Configuration

Download an export of the ItemSense internal configuration for use by Impinj customer support.

Authorized Roles

ConfigManager, Admin

HTTP Request

GET http://BASE_URL/support/v1/configuration

Response

A compressed tar.gz file

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "http://BASE_URL/support/v1/configuration", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(http://BASE_URL/support/v1/configuration);
HttpWebRequest request = (HttpWebRequest) HttpWebRequest.Create(uri);
request.Method = "GET";
request.ContentType = "application/json";
request.Headers.Add("Authorization", "Basic "+ encodedCredentials;
HttpWebResponse httpResponse = (HttpWebResponse)request.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
    var result = streamReader.ReadToEnd();
}

HTTP Return Codes

ItemSense API returns the following HTTP codes:

Code Meaning
200 Request was successful
202 Request was successful. Use the “Location” header to obtain status on the request.
204 Request was successful but there is no response body. Returned in response to delete requests.
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable – the requested format was not JSON
500 Internal Server Error – there was a problem with the server. Please try again later.
503 Service Unavailable – server offline for maintenance. Please try again later.