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 and Item History. Or this data can be accessed via an AMQP Item Events queue.

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.

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
username String Username associated with token
lastUsed String When the token was last used
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 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,
            "y": 0,
            "z": 0
          },
          {
            "x": 0,
            "y": 6,
            "z": 0
          },
          {
            "x": 7,
            "y": 20,
            "z": 0
         },
         {
            "x": 22,
            "y": 18,
            "z": 0
         },
         {
            "x": 23,
            "y": 10,
            "z": 0
         },
         {
            "x": 12,
            "y": 11,
            "z": 0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": 1,
        "points": [
          {
            "x": 22,
            "y": 18,
            "z": 0
          },
          {
            "x": 28,
            "y": 26,
            "z": 0
          },
          {
            "x": 31,
            "y": 18,
            "z": 0
         },
         {
            "x": 23,
            "y": 10,
            "z": 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)
Number or String The number or 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 location in the monitored space.
y Number The y coordinate of the zone point, in meters from the 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 if not specified.

Non-contiguous Zone Example

      {
        "name": "Contoso_Fashion",
        "facility": "DEFAULT",
        "zones": [
          {
            "name": "Womens",
            "floor": 1,
            "points": [
              {
                "x": 7,
                "y": 0,
                "z": 0
              },
              {
                "x": 0,
                "y": 6,
                "z": 0
              },
              {
                "x": 7,
                "y": 20,
                "z": 0
             }
         },
          {
             "name": "Womens",
             "floor": 2,
             "points": [
               {
                 "x": 7,
                 "y": 0,
                 "z": 0
               },
               {
                 "x": 0,
                 "y": 6,
                 "z": 0
               },
               {
                 "x": 7,
                 "y": 20,
                 "z": 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,
                "y": 0,
                "z": 0
              },
              {
                "x": 0,
                "y": 6,
                "z": 0
              },
              {
                "x": 7,
                "y": 20,
                "z": 0
             },
             {
                "x": 22,
                "y": 18,
                "z": 0
             },
             {
                "x": 23,
                "y": 10,
                "z": 0
             },
             {
                "x": 12,
                "y": 11,
                "z": 0
             }
            ]
          },
          {
            "name": "Mens",
            "floor": 1,
            "points": [
              {
                "x": 22,
                "y": 18,
                "z": 0
              },
              {
                "x": 28,
                "y": 26,
                "z": 0
              },
              {
                "x": 31,
                "y": 18,
                "z": 0
             },
             {
                "x": 23,
                "y": 10,
                "z": 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,
                                        y = 18,
                                        z = 0
                                    },
                                    {
                                        x = 28,
                                        y = 26,
                                        z = 0
                                    },
                                    {
                                        x = 31,
                                        y = 18,
                                        z = 0
                                    },
                                    {
                                        x = 23,
                                        y = 10,
                                        z = 0
                                    }
                                }
                            },
                            new
                            {
                                name = "WOMENS",
                                floor = 0,
                                points = {
                                    {
                                        x = 7,
                                        y = 0,
                                        z = 0
                                    },
                                    {
                                        x = 0,
                                        y = 6,
                                        z = 0
                                    },
                                    {
                                        x = 7,
                                        y = 20,
                                        z = 0
                                    },
                                    {
                                        x = 22,
                                        y = 18,
                                        z = 0
                                    },
                                    {
                                        x = 23,
                                        y = 10,
                                        z = 0
                                    },
                                    {
                                        x = 12,
                                        y = 11,
                                        z = 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,
            "y": 0,
            "z": 0
          },
          {
            "x": 0,
            "y": 6,
            "z": 0
          },
          {
            "x": 7,
            "y": 20,
            "z": 0
         },
         {
            "x": 22,
            "y": 18,
            "z": 0
         },
         {
            "x": 23,
            "y": 10,
            "z": 0
         },
         {
            "x": 12,
            "y": 11,
            "z": 0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": 1,
        "points": [
          {
            "x": 22,
            "y": 18,
            "z": 0
          },
          {
            "x": 28,
            "y": 26,
            "z": 0
          },
          {
            "x": 31,
            "y": 18,
            "z": 0
         },
         {
            "x": 23,
            "y": 10,
            "z": 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,
               "y": 0,
               "z": 0
             },
             {
               "x": 0,
               "y": 6,
               "z": 0
             },
             {
               "x": 7,
               "y": 20,
               "z": 0
            },
            {
               "x": 22,
               "y": 18,
               "z": 0
            },
            {
               "x": 23,
               "y": 10,
               "z": 0
            },
            {
               "x": 12,
               "y": 11,
               "z": 0
            }
           ]
         },
         {
           "name": "Mens",
           "floor": 1,
           "points": [
             {
               "x": 22,
               "y": 18,
               "z": 0
             },
             {
               "x": 28,
               "y": 26,
               "z": 0
             },
             {
               "x": 31,
               "y": 18,
               "z": 0
            },
            {
               "x": 23,
               "y": 10,
               "z": 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,
                                        y = 18,
                                        z = 0
                                    },
                                    {
                                        x = 28,
                                        y = 26,
                                        z = 0
                                    },
                                    {
                                        x = 31,
                                        y = 18,
                                        z = 0
                                    },
                                    {
                                        x = 23,
                                        y = 10,
                                        z = 0
                                    }
                                }
                            },
                            new
                            {
                                name = "WOMENS",
                                floor = 0,
                                points = {
                                    {
                                        x = 7,
                                        y = 0,
                                        z = 0
                                    },
                                    {
                                        x = 0,
                                        y = 6,
                                        z = 0
                                    },
                                    {
                                        x = 7,
                                        y = 20,
                                        z = 0
                                    },
                                    {
                                        x = 22,
                                        y = 18,
                                        z = 0
                                    },
                                    {
                                        x = 23,
                                        y = 10,
                                        z = 0
                                    },
                                    {
                                        x = 12,
                                        y = 11,
                                        z = 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,
            "y": 0,
            "z": 0
          },
          {
            "x": 0,
            "y": 6,
            "z": 0
          },
          {
            "x": 7,
            "y": 20,
            "z": 0
         },
         {
            "x": 22,
            "y": 18,
            "z": 0
         },
         {
            "x": 23,
            "y": 10,
            "z": 0
         },
         {
            "x": 12,
            "y": 11,
            "z": 0
         }
        ]
      },
      {
        "name": "Mens",
        "floor": 1,
        "points": [
          {
            "x": 22,
            "y": 18,
            "z": 0
          },
          {
            "x": 28,
            "y": 26,
            "z": 0
          },
          {
            "x": 31,
            "y": 18,
            "z": 0
         },
         {
            "x": 23,
            "y": 10,
            "z": 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,
             "y": 0,
             "z": 0
           },
           {
             "x": 0,
             "y": 6,
             "z": 0
           },
           {
             "x": 7,
             "y": 20,
             "z": 0
          },
          {
             "x": 22,
             "y": 18,
             "z": 0
          },
          {
             "x": 23,
             "y": 10,
             "z": 0
          },
          {
             "x": 12,
             "y": 11,
             "z": 0
          }
         ]
       },
       {
         "name": "Mens",
         "floor": 1,
         "points": [
           {
             "x": 22,
             "y": 18,
             "z": 0
           },
           {
             "x": 28,
             "y": 26,
             "z": 0
           },
           {
             "x": 31,
             "y": 18,
             "z": 0
          },
          {
             "x": 23,
             "y": 10,
             "z": 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 the reader with the information that it needs to position itself 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.

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

Reader Configuration

Parameter Type Description
x Number The x-axis offset, in meters, of the reader from the (0,0) location in the monitored space.
y Number The y-axis offset, in meters, of the reader from the (0,0) location in the monitored space.
z Number The average distance between the height of the xArray and the height of the tags.
yaw Number The angle, in degrees, that the xArray is rotated about its Z x axis.
pitch Number The angle, in degrees, that the xArray is tilted about its X axis
roll Number The angle, in degrees, that the xArray is tilted about the Y axis.
floor
(optional)
Number or String The number or name of the floor on which the reader is installed

Create

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

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
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
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
agentIdentifier String Internal use only

Sample Code

var readerDefinition =  {
                           name: "xarray-11-30-0D",
                           address: "xarray-11-30-0D.impinj.com",
                           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",
                    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",
  "type": "XARRAY",
  "placement": {
    "x": 4.3,
    "y": 6.65,
    "z": 2.68,
    "yaw": 30,
    "pitch": 0,
    "roll": 90,
    "floor": 1
  },
  "labels": null,
  "readerZone": "xarray-10-D9-41",
  "antennaZones": null
}

Create or Replace

Replace an existing reader definition, or create a new one

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",
                           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",
                    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",
    "type": "XARRAY",
    "placement": {
      "x": 4.3,
      "y": 6.65,
      "z": 2.2,
      "yaw": 30,
      "pitch": 0,
      "roll": 90,
      "floor": 1
    },
    "labels": 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",
    "type": "XARRAY",
    "placement": {
      "x": 8.1,
      "y": 5.65,
      "z": 2.68,
      "yaw": 30,
      "pitch": 0,
      "roll": 90,
      "floor": 1
    },
    "labels": null,
    "readerZone": "xarray-11-30-0D",
    "antennaZones": null
  }
]

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,
DO_NOTHING,
NORMAL(deprecated)
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
The RFID search mode

Only available when the reader operation=INVENTORY or NORMAL(deprecated)

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 or NORMAL(deprecated)
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 or NORMAL(deprecated)
antennas Array of Integers Array of integers defining which antenna ports that readers will use

Only available when the reader operation=INVENTORY or NORMAL(deprecated)
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 or NORMAL(deprecated)
reportConfig
(optional)
Report Configuration Defines the parameters which will be included with each tag inventory report

Only available when the reader operation=NORMAL(deprecated)

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.

Report Configuration

Property Type Description
tidIncluded
(optional)
Boolean Include the tag identifier (TID) in tag inventory reports
peakRssiIncluded
(optional)
Boolean Include the peak Return Signal Strength Indicator (RSSI) metric in tag inventory reports
phaseAngleIncluded
(optional)
Boolean Include phase angle information in tag inventory reports
dopplerFrequencyIncluded
(optional)
Boolean Include Doppler frequency information in tag inventory reports
channelIncluded
(optional)
Boolean Include the transmit channel frequency in tag inventory reports

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.

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

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

type
(required)
One of: LOCATION
INVENTORY
LLRP(deprecated)
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"
}
reportingInterval
(optional)
One of:
0
1
2
3
4
5
6
10
12
15
20
30
60
The frequency in seconds with which readers report tag data to ItemSense. Higher values produce more accurate results, but show changes more slowly. Also, shorter reportingIntervals can only support smaller tag populations due to the computational power required on the reader.
Note: 0 is a special value that actually represents a reporting interval of 0.5 seconds. It may only be used on LOCATION-type recipes.
Note: only certain reader modes (see below) support a reportingInterval shorter than 3 seconds. An error will occur when trying to create a recipe with a short reportingInterval with a reader configuration that does not support that reportingInterval.

Default=5

Minimum reportingIntervalReader Modes
0MAX_THROUGHPUT, HYBRID, MAX_MILLER, MODE_1004
3DENSE_READER_M4, DENSE_READER_M8, DENSE_READER_M4_TWO, AUTOSET_DENSE_READER, MODE_1002, MODE_1004
computeWindow
(optional)
Integer The time window during which the state of the tag is calculated. Must be greater than or equal to reportingInterval.

In LOCATION mode, this is the rolling time window over which the location of the tag is calculated by the reader from multiple RFID tag reads. The location accuracy is improved by increasing the number of times a tag is read, but this must be balanced against the required response time.

In INVENTORY mode, when the RFID searchMode is DUAL_TARGET, the value of computeWindow dictates the period over which multiple reader reports are “smoothed” by ItemSense. For example, if a single tag is read by multiple antennas, ItemSense calculates which antenna has reported the most reads.

Default=20 when operation=INVENTORY; and 10 when operation=LOCATION
tagHeartbeatMinutes
(optional)
Integer deprecated - use tagHeartbeatDuration instead.

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 the number of minutes between heartbeat updates.

Set either this or tagHeartbeatDuration. Setting both will produce an error upon saving the recipe.
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.

Set either this or tagHeartbeatMinutes. Setting both will produce an error upon saving the recipe.
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)
Number 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
The following parameters apply only to the deprecated LLRP Recipe type
presencePipelineEnabled
(optional)
Boolean Flag used to enable or disable ItemSense’s ability to detect the absence of tags. This should be set to true if you are using a readerConfiguration that configures the readers to use the DUAL_TARGET search mode and false if the SINGLE_TARGET search mode is used.
locationReportingEnabled
(optional)
Boolean Flag used to enable or disable ItemSense’s location based algorithm, which is used for calculating an RFID tag’s location. By default location reporting is enabled, but should be disabled when using the GATEWAY zone model.
zoneModel
(optional)
Enum Declares whether to use the geographically-declared zone map or the zones declared by antennas for Gateway Readers. If not specified, defaults to ‘GEOGRAPHIC’. The Options are:
  • GEOGRAPHIC : Uses zones declared by the current zone map
  • GATEWAY: Uses the zones declared by antennas for Spot Readers
locationUpdateIntervalInSeconds
(optional)
Number (When locationReportingEnabled is true) The time resolution (in seconds) for item movement
historyWindowSizeInCycles
(optional)
Number The number of cycles worth of data to cache
computeWindowSizeInCycles
(optional)
Number The frequency of calculation updates, expressed in cycle counts
computeWindowTimeInSeconds
(optional)
Number The frequency of calculation updates, expressed in time
locationAggregationModel
(optional)
One of:BY_TIME
BY_CYCLES
Whether the overall location information is calculated across a period of time, or a number of cyles

Sample Code

var body = {
    "name": "MY_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "READER_CONFIGURATION",
    "tagHeartbeatMinutes": 1,
    "tagExpiryDuration": "7",
    "minimumMovementInMeters": "1.5",
    "computeWindow": "10",
    "reportingInterval": "5",
};

xhr.open("POST", "/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"}
    },
    tagHeartbeatMinutes = 1,
    tagExpiryDuration = 7,
    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",
    "tagHeartbeatMinutes": 1,
    "tagExpiryDuration": "7",
    "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",
    "tagHeartbeatMinutes": 1,
    "tagExpiryDuration": "3",
    "computeWindow": "2",
    "reportingInterval": "1",
};

xhr.open("PUT", "/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",
    tagHeartbeatMinutes = 1,
    tagExpiryDuration = "3",
    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",
    "tagHeartbeatMinutes": 1,
    "tagExpiryDuration": "3",
    "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",
  "tagHeartbeatMinutes": 1,
  "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", "/configuration/v1/recipes/show", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(/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",
    "tagHeartbeatMinutes": 1,
    "tagExpiryDuration": null,
    "readerConfigurations": {},
    "computeWindow": 20,
    "reportingInterval": 5
  },
  {
    "name": "LOCATION_RECIPE",
    "type": "LOCATION",
    "readerConfigurationName": "IMPINJ_LocationConfig",
    "tagHeartbeatMinutes": 1,
    "tagExpiryDuration": null,
    "readerConfigurations": {},
    "minimumMovementInMeters": 1,
    "computeWindow": 10,
    "reportingInterval": 5
  }
]

Jobs

An ItemSense job runs a recipe to generate item data.

Start a Job

Start a job

Authorized Roles

JobRunner, Admin

HTTP Request

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

Request Body

Property Type Description
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 Integer The number of seconds for which ItemSense should execute this job. If zero, 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
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
playbackLoggingEnabled *
(optional)
Boolean When enabled, this flag creates a log file of tag reports received from the reader
presenceLoggingEnabled *
(optional)
Boolean When enabled, this flag creates a log file of tag-based presence calculation data
reportToFileEnabled *
(optional)
Boolean Flag used for logging tag movement to a file. Defaults to false

Response

Parameter Type Description
id String The ID of the job in UUID format
status
One of:
WAITING,
INITIALIZING,
STARTING,
RUNNING,
STOPPING,
STOPPED
The status of the job
readerNames Array of: String The collection of readers to which the job applies
connectionType String The connection type. Currently only “LLRP” is supported
creationTime String The time the job was created in ISO 8601 format
lastActivityTime String The time of last activity in ISO 8601 format
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
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
message String The job error message

Sample Code

var job =  {
               recipeName: "IMPINJ_BasicLocation",
               durationSeconds: 60,
               playbackLoggingEnabled: false,
               presenceLoggingEnabled: false
             };
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",
                durationSeconds = 60,
                playbackLoggingEnabled = false,
                presenceLoggingEnabled = false
                });
    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"
  ],
  "connectionType": "LLRP",
  "creationTime": "2016-06-28T17:27:20.106Z[Etc/UTC]",
  "lastActivityTime": "2016-06-28T17:27:20.106Z[Etc/UTC]",
  "activeDuration": "PT0S",
  "errorOccurred": false,
  "errors": [],
  "maxErrors": 5,
  "stopReason": null,
  "facilities": [
    {
      "name": "HOME"
    }
  ],
  "job": {
    "recipeName": "RECIPE1",
    "durationSeconds": 100,
    "playbackLoggingEnabled": null,
    "presenceLoggingEnabled": null,
    "startDelay": "PT1M",
    "reportToDatabaseEnabled": null,
    "reportToMessageQueueEnabled": null,
    "reportToFileEnabled": null,
    "facility": "HOME"
  },
  "instanceMetadata": null,
  "lastHeartbeatTime": null,
  "startAttempts": 0
}

Stop a Job

Stop a 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

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

Retrieve all of the jobs and their status

Authorized Roles

JobRunner, Admin

HTTP Request

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

Parameters

Parameter Type Description
startedBefore UTC Time Filter to jobs that have been started before the given time, such as “2014-01-07T22:46:00”, value parsed as UTC
startedAfter UTC Time Filter to jobs that have been started after the given time, such as “2014-01-07T22:46:00”, value parsed as UTC
lastActivityBefore UTC Time Filter to jobs that have the last activity time before the given time, such as “2014-01-07T22:46:00”, value parsed as UTC
lastActivityAfter UTC Time Filter to ZonedDateTimeParam that have the last activity time after the given time, such as “2014-01-07T22:46:00”, value parsed as UTC
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 two endpoints; one to show items and another to show the history of items.

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
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 will be returned. Represented in ISO 8601 format.
toTime
(optional)
String Items which were updated before this time will be returned. Represented in ISO 8601 format.
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)

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",
         "xLocation":6.3,
         "yLocation":9.2,
         "zLocation":0,
         "zone":"ZONE1",
         "facility":HOME,
         "presenceConfidence":"HIGH",
         "lastModifiedTime":"2016-02-23T00:38:42Z"
      },
      {
         "epc":"300833B2DDD9000500010004",
         "tagId":"000000000000",
         "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 String A hexadecimal string representing an EPC prefix of an item. Only the items with EPCs that start with this prefix will be returned
fromZone String A string zone identifier, such as “Men’s Department”. This parameter identifies the zone that the item moved out of.
toZone String A string zone identifier, such as “Men’s Department”. This parameter identifies the zone that the item moved into.
fromFacility String A string facility identifier, such as “Seattle Location”. This parameter identifies the facility that the item moved out of.
toFacility String A string facility identifier, such as “Seattle Location”. This parameter identifies the facility that the item moved into.
fromTime UTC String Events which occurred on or after this time will be returned, such as “2014-01-07T22:46:00”, value parsed as UTC
toTime UTC String Events which occurred before this time will be returned, such as “2014-01-07T22:46:00”, value parsed as UTC
epcFormat 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 Boolean Will restrict results to items that moved zones, defaults to true
minDistanceMoved Number Will restrict results to items that moved more than the minimum distance supplied (in meters).
pageMarker 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 Integer The number of records to return per query. The maximum value of this parameter is 1000.
alwaysIncludePageMarker 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",
         "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",
         "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
}

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
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.

Data Definitions

Item

Parameter Type Description
epc String The EPC of the item
tagId String The ID of the tag that was read
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 UTC format

ItemEvent

Parameter Type Description
epc String The EPC of the tag for which the event occurred
tagID String The ID of the tag for which the event occurred
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 UTC format

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
lastReboot String The time at which the reader was last re-booted in ISO-8601 format
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.2.240-338",
    "Firmware": "5.8.1.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", "/health/v1/readers", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(/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.2.240-338",
      "Firmware": "5.8.1.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.2.240-338",
      "Firmware": "5.8.1.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
    }
  }
]

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
toTime String The end of the query time period in ISO-8601 format
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", "/health/v1/events", true)
// Set authorization headers
xhr.send(body)
var body = {
    "types": ["LIFECYCLE"]
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(/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.2.240-338\",\"Firmware\":\"5.8.1.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", "/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(/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 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
See Code Details

HealthEvent

Parameter Type Description
eventTime String The time of the event in ISO 8601 format
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 READER_COMMAND HardwareStatus Generated when any LLRP reader command does not return a successful status reply
9 READER_EXCEPTION HardwareStatus Asynchronous notification from the reader (reported via LLRP) of an uncategorized error condition
10 READER_RESTART HardwareStatus Reader closed LLRP connection unexpectedly and the agent could not re-open it
11 UPGRADE_STATUS HardwareStatus When the upgrade (agent or firmware) process encounters any kind of error, or times out
12 CHECKSUM SoftwareStatus Checksum failure of either CAP or firmware image
13 COMMAND_NOT_FOUND SoftwareStatus Agent is sent an unknown command by ItemSense
14 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)
15 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
16 FILE_SYSTEM SoftwareStatus Any file system error within the agent process (usually due to full or corrupted file system)
17 INVALID_SET_VARIABLE SoftwareStatus Agent is sent an invalid variable set command by ItemSense (type, range etc)
18 UNMARSHAL SoftwareStatus ItemSense sent invalid or corrupted data
19 LLRP SoftwareStatus 1. Invalid RF configurations are specified by ItemSense
2. Invalid LLRP packet was sent to the agent by the reader
20 PROVISIONING SoftwareStatus 1. Invalid provisioning settings
2. Provisioning module failed to start (http server failed to start)
21 READER_CONNECTION SoftwareStatus Failed to open or close the LLRP connection, or to receive a message over LLRP
22 CRASH SoftwareStatus The agent crashed and the reader is about to reboot
23 REBOOT None Communicates the previous reboot reason. (Note: This event does not contribute to bad health status)
24 HEALTH_RESET None Is a signal used when computing reader status, to indicate ItemSense should disregard all health events older than this one
25 KNOWN None Any other exception that is expected by the Agent but not by ItemSense, including unknown SNMP events from the reader
26 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
updated String The time at which the image was updated
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.8.1.240",
                "imageType": "FIRMWARE_SPEEDWAY",
            },
            "imageName": "octane-5.8.1.240.upg",
            "checksum": "076dae4e1c37037a42e37d012014ad62",
        },
    "description": "Octane v5.8.1.240",
    "created": "2016-09-06T18:21:08.000+0000",
    "updated": "2016-09-06T18:21:08.000+0000",
    "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
updated String The time at which the image was updated
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_URLhttp://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_URLhttp://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.8.1.240",
            "imageType": "FIRMWARE_SPEEDWAY",
        },
        "imageName": "octane-5.8.1.240.upg",
        "checksum": "076dae4e1c37037a42e37d012014ad62",
    },
    "description": "Octane v5.8.1.240",
    "created": "2016-09-06T18:21:08.000+0000",
    "updated": "2016-09-06T18:21:08.000+0000",
    "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

Sample Code

var xhr = new XMLHttpRequest()
xhr.open("GET", "/control/v1/upgrades/show", true)
// Set authorization headers
xhr.send()
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(/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.8.1.240",
                "imageType": "FIRMWARE_SPEEDWAY",
            }
    },
    ...
]

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
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.8.1.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    },
    "status": "IN_PROGRESS",
    "target": {
        "type": "Facility",
        "values": ["MY_FACILITY"],
    },
    "details": {
        "readers": [
        {
            "name": "SpeedwayR-11-79-9D",
            "previousVersion": {
                "version": "5.8.1.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"
}

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.8.1.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    }
};
var xhr = new XMLHttpRequest()
xhr.open("POST", "/control/v1/upgrades/start", true)
// Set authorization headers
xhr.send(body)
var body = {
    "target": {
        "type": "Facility",
        "values": ["FAC"],
    },
    "versionIdentifier": {
        "version": "5.8.1.240",
        "imageType": "FIRMWARE_SPEEDWAY",
    }
};
// Encode credentials
string encodedCredentials = ...
Uri uri = new Uri(/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

HTTP Return Codes

ItemSense API returns the following HTTP codes:

Code Meaning
200 Request was successful
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.