Documentation Powered by ReDoc

SensAPI (1.0)

Download OpenAPI specification:Download

This document defines the supported REST API methods for the SensArray Enterprise and SensArray Core products. These interfaces are supported for both http (port 80) and https (port 443) connections.

Response Codes There are three general classes of errors that can occur when interacting with the reader through the SensAPI REST interfaces.

  • Response code 400 is returned when the JSON payload is malformed. This might be mismatched braces, improperly nested structures, misspelled field names, and, in some cases, missing data fields.
  • Response code 404 is returned when the data content is wrong. This is typically caused by data out of range, wrong data types, and missing required data fields.
  • Response code 501 indicates that the interface is not implemented. This is most likely caused by a misspelling in the REST path.

If you have trouble debugging a 400 or 404 error code, capture the output response body. The returned text provides more specific information about the error.

Data Types

This API handles data values somewhat loosely. A data value, regardless of whether it is a string, an integer, or a boolean (true/false) value can be enclosed in quotes or not. As an example, for an integer field, you can enter "0" or 0. For string fields, you are only required to enclose the string in quotes when there are embedded spaces. So you can enter a reader name as MyReaderName or "MyReaderName", but you would need to include the quotes in the case of "My Reader Name". There are a few other restrictions on numbers and boolean values. Neither of these types should include embedded spaces before or after the value inside the quotes. For example, " 0", "0 ", "true ", and " false" would all be invalid. Also, for numbers, any leading 0 will be invalid (unless the value is actually 0). So "0" is valid, but "00", "01", and "025.6" would all fail.

String fields that represent control values, and boolean values are treated as case insensitive. So for the Sessions parameter under the RAIN settings, "S1" and "s1" are both valid. S1 and s1 without the quotes are also valid. Similarly, True, true, TRUE, "True", etc. are all valid boolean values.

Automatic Save

There are a number of REST POST requests in the SensAPI that automatically save the associated configuration data to make it persistent when the reader is rebooted. Other POST requests require that the reader/save request be made to make the configuration values persistent. The purpose of this is to allow the developer to change antenna settings and RFID settings, validate that they work as expected, then finally explicitly save them when the desired configuration is achieved. It also allows the developer to use either a reboot or a reader/restore request to roll the configuration back to its previous settings.

The POST requests in the following sections are not automatically saved:

  • Antenna
    • Power
    • Sequence
    • Dwell Time
  • RAIN
    • RF Mode
    • Q Algorithm
    • Select settings
    • Advanced RF settings

The POST requests that result in automatic saves are:

  • Profile/RFID
  • Reader/Reader name
  • SSL/Key
  • SSL/Certificate
  • EPIC/Customer Key

Also, the HTTP DELETE requests for SSL and EPIC will result in an automatic save.

One last note on this. If any of the automatic save requests are made after the non-automatic ones, all of the settings are saved regardless of which command group they fall into. This may change in the future, but you should keep this in mind when you are configuring your reader.

Authentication

Bearer

The token required to be provided with the Bearer authorization is the 8 digit serial number of the reader.

Security Scheme Type API Key
Header parameter name: Authorization

Antenna

Requests in this section are used to set and retrieve power levels for each antenna as well as the sequence for switching between antennas during an inventory process. The REST application can also set the time interval that tags are read by each antenna until moving on to read on the next one in the sequence.

Get ALL power levels

Get the power levels for all antennas.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Set power ALL levels

Set the power levels for reading and writing for ALL antennas.

Authorizations:
Bearer
Request Body schema: application/json
Array ()
antenna_id
number [ 0 .. 3 ]

ID (0-3) of the antenna for setting the power levels

read_power
number [ 5 .. 31.5 ]

Power level for read operations in dBm. Decimal values within the acceptable range (5 to 31.5) are truncated to the nearest 0.5 dBm.

write_power
number [ 5 .. 31.5 ]

Power level for write operations in dBm. Decimal values within the acceptable range (5 to 31.5) are truncated to the nearest 0.5 dBm.

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Get power level

Get the power level for a given antenna.

Authorizations:
Bearer
path Parameters
id
required
number

Then antenna ID numbered 0-3.

Responses

Response samples

Content type
application/json
{
  • "read_power": 5,
  • "write_power": 5
}

Set power level

Set the power level for reading and writing for an antenna.

Authorizations:
Bearer
path Parameters
id
required
number

Then antenna ID numbered 0-3.

Request Body schema: application/json
read_power
required
number [ 5 .. 31.5 ]

Power level for read operations in dBm. Decimal values within the acceptable range (5 to 31.5) are truncated to the nearest 0.5 dBm.

write_power
required
number [ 5 .. 31.5 ]

Power level for write operations in dBm. Decimal values within the acceptable range (5 to 31.5) are truncated to the nearest 0.5 dBm.

Responses

Request samples

Content type
application/json
{
  • "read_power": 5,
  • "write_power": 5
}

Get the antenna sequence order

Returns an array of antenna ids that specifies the currently configured antenna read order.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "Single Antenna Example": [
    ],
  • "Multiple Antenna Example": [
    ]
}

Set the antenna sequence

Set the sequence that the antennas will be read in. For a single antenna, this should be a single element specifying the antenna to be used. For multiple antennas, it is a JSON array (comma separated entries) specifying what antennas to read on and in what order.

Note that the reader will read for a time interval specified by the antenna dwell time, then move on to the next antenna in the sequence. When the end of the sequence is reached, the reader will continue reading on the first reader in the antenna sequence visiting each antenna cyclically.

Authorizations:
Bearer
Request Body schema: application/json
Array ()
integer [ 0 .. 3 ]

The ID of the antenna

Responses

Request samples

Content type
application/json
{
  • "Single Antenna Example": [
    ],
  • "Multiple Antenna Example": [
    ]
}

Get the antenna dwell time

Retrieve the currently configured antenna dwell time in milliseconds.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "dwell_time": 0
}

Set the antenna dwell time

Set the antenna dwell time in milliseconds. The antenna dwell time is the time interval that the reader spends reading tags on a specific antenna before moving on to read on the next antenna in the antenna sequence.

Authorizations:
Bearer
Request Body schema: application/json
dwell_time
required
integer [ 50 .. 65535 ]

The antenna dwell time in milliseconds.

Responses

Request samples

Content type
application/json
{
  • "dwell_time": 50
}

EPIC

SensThys provides the capability to encode the EPCs of tags using an error correction scheme that is decoded by the reader before reporting the tag information to the REST application.

The requests in this section allow the REST application to upload a customer-specific key for the decoding process along with commands for enabling the decoding process and checking on the status of the EPIC configuration.

Click here for more information about EPIC.

Get EPIC configuration

Get the EPIC configuration.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "mode": 0,
  • "enabled": true,
  • "key_loaded": true,
  • "customer_no": "string",
  • "codec": "string"
}

Set the EPIC status

This request is used to specify the EPIC level that the reader uses when handling EPIC encoded tags. It also allows the user to enable or disable EPIC decoding.

Note that at least one of these fields must be specified when sending this request. Also, EPIC decoding cannot be enabled until an EPIC customer key has been loaded into the reader.

Authorizations:
Bearer
Request Body schema: application/json
mode
integer [ 0 .. 7 ]

The EPIC mode to utilize. Currently, only level 0 is supported. Levels 1 through 7 are reserved for future use.

enabled
boolean

Flag to enable EPIC

Responses

Request samples

Content type
application/json
{
  • "Enable EPIC decoding"": [
    ]
}

Set the EPIC customer key

Send an EPIC customer key to the reader and save it as part of the current configuration. Note that this does not result in EPIC decoding being activated. Enabling EPIC decoding must be done explicitly using the /epic set status request.

Note that the HTTP GET message for the /epic/key endpoint returns a 501 (unimplemented) status. The EPIC customer key is considered private so cannot be recovered directly from the reader.

Authorizations:
Bearer
Request Body schema: text/plain

The EPIC key file contents

string

Responses

Remove installed EPIC key

Remove any saved EPIC customer key. Deleting a customer key will also result in EPIC decoding being disabled.

Authorizations:
Bearer

Responses

Inventory

The REST API requests in this section are used for reading the data on tags. You can also use the inv/filter endpoint to set up a mask that the inventory process uses during select operations to limit the set of tags the reader is reading to the subset defined by the filter.

The requests /inv/start and /inv/stop are used as a pair. Start initiates a standard RFID inventory process. Stop terminates that process and returns a list of EPCs and associated data to the requesting application. Using this pair of requests allows for maximum flexibility for the REST application to determine what triggers the inventory process to be considered finished. Note that /inv/start can be called multiple times once the inventory has started to poll for tags read since the previous start request. If your application simply needs to read for a fixed period of time, the /inv/timed endpoint accomplishes this with a single request.

Finally, the /inv/rdbank command supports the ability to read specific data from the different data banks that are present on RFID tags.

Start an inventory

Start running the inventory process. This will continue until the inv/stop command is issued. If an existing inventory is running when the start command is issued, tags saved in the internal tag buffer will be reported in the reply. The inventory process that is running will continue.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Stop an inventory

Stop the currently running inventory process. Any tags remaining in the internal reader buffer will be reported in the body of the response.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Start a timed inventory

Start running a timed inventory process. This will continue for the specified time frame.

Authorizations:
Bearer
query Parameters
timeframe
integer

The timeframe to run the inventory process in milliseconds.
If the parameter is left off then a default timeframe of 10 seconds will be used.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Read the contents of a specific data bank

Read the contents of the specified data bank. Note that data can be read in chunks of at most 16 words (32 bytes). If more data is present and needs to be read, read in chunks of at most 16 words with appropriate starting offsets for each read, then concatenate the data to get the full contents.

Authorizations:
Bearer
query Parameters
antenna_id
required
integer

Then antenna ID to use for reading the tag data bank numbered 0-3

access_pwd
string
Default: "0x00000000"

The access password

bank
integer
Enum: 0 1 2 3

The data bank to filter on:

  • 0 - reserved
  • 1 - EPC
  • 2 - TID
  • 3 - User Memory
start
integer [ 0 .. 255 ]
Default: 0

The word address where the read should begin

length
integer [ 1 .. 16 ]
Default: 6

Number or words (16 bits) to read

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get the currently set inventory filter

This request retrieves the current inventory filter that is being used during tag reads.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "bank": 0,
  • "start": 0,
  • "length": 6,
  • "mask": "string"
}

Set a filter for inventory operations

Note that the mask is set up with very fine grain. The start location within the tag bank and the length are specified at the bit level. To select a tag with a specific TID, the bank would be set to 2, the start would be set to 0, and the length would be set to 96 for a typical tag. The byte string 'mask' would contain the 12 bytes of the TID.

Note that the inventory filter is not persistent. The filter will be lost when the reader reboots, so must be reloaded as part of any reader setup where tag filtering is being utilized.

Authorizations:
Bearer
Request Body schema: application/json
bank
required
number
Enum: 0 1 2 3

The data bank to filter on:

  • 0 - reserved
  • 1 - EPC
  • 2 - TID
  • 3 - User Memory
start
required
number
Default: 0

The bit address to start with

length
required
any
Default: 6

Number of bits in the mask

mask
required
string

Mask to utilize

Responses

Request samples

Content type
application/json
{
  • "bank": 0,
  • "start": 0,
  • "length": 6,
  • "mask": "string"
}

Remove any existing filters that may be in place

Authorizations:
Bearer

Responses

RAIN

The requests in this section provide the ability to set up the RFID reader parameters as needed to optimize the ability of the REST application to read tags in different environments.

Get the RF Mode settings

Request the currently configured RF mode of the reader.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "rfmode": 1,
  • "est_tag_pop": 0
}

Set the RF Mode

This request sets the current RF mode to be used by the reader when reading tags.

Authorizations:
Bearer
Request Body schema: application/json
rfmode
required
number
Enum: 1 3 4

The RF Mode of the reader:

  • 1 - Sensitive
  • 3 - Fast
  • 4 - Expresso
est_tag_pop
number

Estimated tag population used by Expresso mode. This field is required when setting the RF Mode to 4 (Expresso). It should not be sent for the other RF Modes.

Responses

Request samples

Content type
application/json
{
  • "rfmode": 1,
  • "est_tag_pop": 0
}

Get the Q Algorithm parameters

Request the Q algorithm and associated starting Q value. This will also return the minimum Q and maximum Q values for the dynamic search algorithm.

NOTE: SCHEMA CHANGED.
Top-level JSON object wrapper was eliminated.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "Dynamic Q Example": {
    },
  • "Static Q Example": {
    }
}

Set the Q Algorithm parameters

Set the Q algorithm (static or dynamic) and the Q starting value. For dynamic Q, you might also set the minimum and maximum values that the algorithm can search through.

NOTE: SCHEMA CHANGED.
Top-level JSON object wrapper was eliminated moving to full release.

Authorizations:
Bearer
Request Body schema: application/json
algo_type
required
string
Enum: "static" "dynamic"

Q Algorithm type

start_q
required
number [ 0 .. 15 ]

Start Q for dynamic search algorithm or Q value used for static search. For dynamic search must be between min_q and max_q

min_q
number [ 0 .. 15 ]

Minimum Q value for dynamic search algorithm. Must be less than max_q value. Min_q is required when setting the Q Algorithm to 'dynamic'. Min_q should not be specified when setting the Q Algorithm to 'static'.

max_q
number [ 0 .. 15 ]

Maximum Q value for dynamic search algorithm. Must be greater than min_q value. Max_q is required when setting the Q Algorithm to 'dynamic'. Max_q should not be specified when setting the Q Algorithm to 'static'.

Responses

Request samples

Content type
application/json
{
  • "Dynamic Q Example": {
    },
  • "Static Q Example": {
    }
}

Get the Select settings

Retrieve the current query and select sessions along with other parameters are used for controlling what states tags are to be selected into and subsequently read from.

NOTE: SCHEMA CHANGED.
Top-level JSON object wrapper was eliminated.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "select_session": "S0",
  • "query_session": "S0",
  • "select_action": "000",
  • "query_target": "A",
  • "sel_flag": "All"
}

Set the Select settings

Set the query and select session along with other select parameters for controlling what states tags are to be selected into and subsequently read from.

NOTE: SCHEMA CHANGED.
Top-level JSON object wrapper was eliminated.

Authorizations:
Bearer
Request Body schema: application/json
select_session
string
Enum: "S0" "S1" "S2" "S3"

Select session

query_session
string
Enum: "S0" "S1" "S2" "S3"

Query session

select_action
string
Enum: "000" "001" "010" "011" "100" "101" "110" "111"

Select action

query_target
string
Enum: "A" "B" "Dual"

Select target

sel_flag
string
Enum: "All" "~SL" "SL"

Sel flag

Responses

Request samples

Content type
application/json
{
  • "select_session": "S0",
  • "query_session": "S0",
  • "select_action": "000",
  • "query_target": "A",
  • "sel_flag": "All"
}

Get the advanced RF settings

Retrieve the advanced RFID control parameters.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "drm_active": true,
  • "select_setup": {
    }
}

Set the advanced RF settings

Set advanced RFID control parameters. Any unspecified field will retain its already configured value. (However, see note under error responses.)

NOTE: SCHEMA CHANGED.
Top-level JSON object wrapper was eliminated.

Authorizations:
Bearer
Request Body schema: application/json
drm_active
boolean

Turn Dense Reader Mode (DRM) on or off

object

Settings for controlling when and how many selects to perform

Responses

Request samples

Content type
application/json
{
  • "drm_active": true,
  • "select_setup": {
    }
}

Profile / RFID

This REST request provides a means for a standardized collection of RAIN parameters to be loaded and saved as a group. This command is particularly useful for configuring readers in a standardized way when deploying them into a relatively "uniform" environment.

Get all RFID settings

COMING SOON

Retrieve the full RFID profile to be used as the reader configuration during inventory processing. This interface combines the individual interfaces /stapi/v0/antenna/* and /stapi/v0/rain/*.

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "antenna_setup": {
    },
  • "rain": {
    }
}

Set all RFID settings

COMING SOON

Setup the full RFID profile to be used as the reader configuration during inventory processing. This interface combines the individual interfaces /stapi/v0/antenna/* and /stapi/v0/rain/*.

Authorizations:
Bearer
Request Body schema: application/json
object

Antenna power and sequence settings

object

RAIN settings

Responses

Request samples

Content type
application/json
{
  • "antenna_setup": {
    },
  • "rain": {
    }
}

Reader

There are several types of requests supported in this section:

  • General parameters of the reader can be requested. These include firmware versions, reader ids, etc.
  • The reader name can be set and requested
  • The reader can be rebooted
  • The reader's configuration settings can be saved, restored and reset as needed.

Get reader information

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "model": "string",
  • "seral_no": "string",
  • "build_no": "string",
  • "version": "string",
  • "rest_version": "string"
}

Get the reader name

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "name": "SensArray Enterprise #41"
}

Set the reader name

Set the name of the reader.

Authorizations:
Bearer
Request Body schema: application/json
name
required
string

The name of the reader

Responses

Request samples

Content type
application/json
{
  • "name": "SensArray Enterprise #41"
}

Response samples

Content type
application/json
{
  • "name": "SensArray Enterprise #41"
}

Reboot the reader

Reboot the reader.

Authorizations:
Bearer

Responses

Save reader settings

Save reader settings.

Authorizations:
Bearer

Responses

Restore reader settings

Restore the reader settings from the values saved in flash memory.

Authorizations:
Bearer

Responses

Reset reader to factory settings

Restore the reader settings to the factory defaults

Authorizations:
Bearer

Responses

SSL

Many of the applications that utilize this REST API will need a private key and certificate to operate. When the reader is controlled through the REST interface, the reader is acting as a server. Consequently, to communication with the reader using https (port 443) a private key and associated server certificate need to be loaded and saved to the reader. SensThys support self-signed certificate/key pairs along with certificates and keys that can be purchased from certificate authorities, including wild card certificates.

Get the current SSL configuration

Authorizations:
Bearer

Responses

Response samples

Content type
application/json
{
  • "self_signed": {
    }
}

Remove any existing certificates and go back to default self signed

Authorizations:
Bearer

Responses

Set the SSL certificate to utilize.

This request uploads and saves the SSL certificate needed to validate a secure TLS communication channel between the REST application and the reader.

The certificate that is uploaded needs to be the correct one associated with the private key that is uploaded with the ssl/key request.

Note: The reader must be rebooted for a newly loaded certificate/key set to be activated. Until the reboot, the previously loaded certificate and key are used for securing the communications between the reader and the REST application.

Authorizations:
Bearer
Request Body schema: text/plain

The contents of the certificate. Cert should be in the PEM format.

string

Responses

Set the SSL key to utilize.

This request uploads and saves the SSL privae key needed to validate a secure TLS communication channel between the REST application and the reader.

The private key that is uploaded needs to be the correct one associated with the certificate that is uploaded with the ssl/cert request.

Note: The reader must be rebooted for a newly loaded certificate/key set to be activated. Until the reboot, the previously loaded certificate and key are used for securing the communications between the reader and

Authorizations:
Bearer
Request Body schema: text/plain

The contents of the key. Key should be in the PEM format.

string

Responses

Reader / Update

Update the reader firmware

COMING SOON

Update the reader firmware through communication with a web server. This command specifies the url path on the server that provides the update service and a field indicating whether the bootloader firmware or the main application firmware is being updated.

This command will cause the reader to enter into a new state where it will be unable to communicate with the host REST-based application. The response will be a redirect command to the reader settings request.

The update process may take some time to complete, so how to provide user feedback during that time interval needs to be considered.

Authorizations:
Bearer
Request Body schema: application/json
server_hostname
required
string

This field specifies the URL of the server that is providing the update service. This should include the http: or https: prefix to let the reader know what protocol to use in connecting.

firmware_type
required
string
Enum: "bootloader" "application"

This specifies whether the bootloader or the main application firmware is to be updated

version
string

This option is provided for future use where a specific version of the firmware needs to be loaded for application compatibility, new feature testing, or installing a prior revision.

Leaving this option out will trigger installation of the latest version.

Responses

Request samples

Content type
application/json
{}