HTTP Service

HTTP SERVICE

Introduction

This service offers the option to send events (reads, gpi, etc) using an HTTP request.


How it works

The HTTP Service has an internal queue (buffer like) that receives all internal events.

A dedicated execution thread awaits for incoming data in the buffer before sending data out. The send logic works as follow:


Besides the queue logic, there is a timer (TTL) for every unique EPC to filter repetitions of the same EPCs. It works as follows:


The logic defined before creates the following conditions:


Events

Possible events are:

Possible requests are:

It supports HTTP/HTTPS and Basic Authentication

Configuration

In order to enable and configure this service go to the system tab and in the Services drop-down select HTTP_SERVICE

Required fields are marked with *

Connection

The connection options are:

HTTP Request

The HTTP requests options are:

JSON config*

This is a JSON List of Maps, each Map with the following elements:

The javascript expression is evaluated with an injected context filled with real time data

Correct escaping of " and ' inside the body expression is the most difficult part.

Additional care is required when escaping characters.

Before entering the JSON config in the device it is recommendable to double check it's correctly formed by using a JSON validator like this one: https://jsonlint.com/

Before validating the JSON format please delete all tabulations and row jumps. You can do this by searching "\n" and "\t" in a text editor and deleting them.

Templates for typical use cases.

Possible events

The available context injected into the body javascript expression depends on the EVENT TYPE

TAG_READ context

Available context variables are

getUTC() and getUTCFormatted() are avilable starting at AdvanNet-2.3.16

In previous versions, the methods getTime() and getTimeFormatted() use UTC values.

getSKU() and getSerial() are available starting at AdvanNet-2.3.17_02

Events context

All other events share the same context variables

Send options

The send options are:

Inventory tag TTL is applied only on TAG_READ events.

It has no effect for other events: ADPY_PAYMENT, TAG_ALARM, etc.

To reduce the frequency of repeated events (other than TAG_READ), please change them in the ReadMode page settings (RF & Antenna options).

Basic authentication

The basic authentication options are:

Advanced JSON conf

This setting allows to configure additional parameters:

An example of a JSON conf is

{"debug":true,"debugTransport":true}

Another example could be

{"debug":true,"customHeaders":[{"header":"headerName1:headerValue1"},{"headerName2":"h2:headerValue2"]}}

Persist settings

Once the current settings seems to work as desired, please do not forget to persist system settings using the "Save current" button at the top.

Utiltites

encodeURI

It is possible to use the javascript method encodeURI

For example, to encode the full body part

[{

  "event":"TAG_READ",

  "path":"'/to/my/url'",

  "body":"

    var body='reader_name=\"AdvanReader 150\"&';

    body+='mac_address=\"'+ctx_devmac+'\"&';

    body+='line_ending=&';

    body+='field_delim=,&';

    body+='field_names=antenna_port,epc,first_seen_timestamp,peak_rssi&';

    body+='field_values='+ctx_tags[0].getAntenna()+',\"'+ctx_tags[0].getEPC()+'\",'+ctx_tags[0].getTime()+','+ctx_tags[0].getEPC();

    body+=encodeURI(body);

 "

}]

Examples

application/xml

Send inventory dta in xml format.

The JSON string is as follows.

[{

"event":"TAG_READ",

"path":"'/to/my/url'",

"body":"

var body='<read no=\"'+ctx_tags.length+'\" id=\"'+ctx_devid+'\" ip=\"'+ctx_devip+'\" mac=\"'+ctx_devmac+'\">';

var i=0;

for(i=0;i<ctx_tags.length;i++){

body+='<tag epc=\"'+ctx_tags[i].getEPC()+'\" port=\"'+ctx_tags[i].getAntenna()+'\" t=\"'+ctx_tags[i].getTimeFormatted()+'\" rssi=\"'+ctx_tags[i].getRSSI()+'\" />';

}

body+='</read>';

"

}

]

application/x-www-form-urlencoded (I)

This will only work in AdvanNet-2.3.15_06 or higher

Send inventory data in as a POST form

The JSON string is as follows.

[{

  "event":"TAG_READ",

  "path":"'/to/my/url'",

  "body":"

    var body='reader_name=\"AdvanReader 60\"&';

    body+='mac_address=\"'+ctx_devmac+'\"&';

    body+='line_ending=&';

    body+='field_delim=,&';

    body+='field_names=antenna_port,epc,first_seen_timestamp,peak_rssi&';

     body+='field_values='+ctx_tags[0].getAntenna()+',\"'+ctx_tags[0].getEPC()+'\",'+ctx_tags[0].getTime()+','+ctx_tags[0].getEPC();

   

 "

}

]

Always enable the send one by one.

Leaving the send one by one disabled may cause inventory data not be be uploaded

Define the header in the Advanced JSON conf as follows

{"Content-type":"application/x-www-form-urlencoded"}

 

application/x-www-form-urlencoded (II)

Similar example to the previous one but with multi-line parameters

This will only work in AdvanNet-2.3.15_06 or higher

Send inventory data in as a POST form

The JSON string is as follows.

[{

  "event":"TAG_READ",

  "path":"'/to/my/url'",

  "body":"

    var body='reader_name=\"Reader 1\"&';

    body+='mac_address=\"'+ctx_devmac+'\"&';

    body+='line_ending=&';

    body+='field_delim=,&';

    body+='field_names=antenna_port,epc,first_seen_timestamp,peak_rssi';

var i=0;

     for(i=0;i<ctx_tags.length;i++){

        body+='&field_values='+ctx_tags[0].getAntenna()+',\"'+ctx_tags[0].getEPC()+'\",'+ctx_tags[0].getTime()+','+ctx_tags[0].getEPC();

     }

 "

}

]

Define the header in the Advanced JSON conf as follows

{"Content-type":"application/x-www-form-urlencoded"}



Complete example

This is a complete example provided as a starting point when your configuration does not work. This might be due to 3 factors:

As the AdvanNet firmware bug is the least common source of problems, it is compulsory to check whether the problem is caused by one of the first 2 factors.

Then, in order to ensure that Keonn firmware is working as intended, you must test it against a real HTTP server meant for developing purposes, we recommend:

webhook.site

Alternatively it is possible to use a python script

Local HTTPServer in python:

In the attachment/downloads section at the bottom of the page you can download a tiny python script that you can run to set up a local http server that will receive the POST requests from the reader and will print them onscreen for you to check. The server listens in the port 8080 by default but can be changed by passing it as argument.

To run the script just type python httpServer.py <port number> on your terminal console of choice and you'll see the post requests onscreen

If you don't have python you can install it following these instructions: https://wiki.python.org/moin/BeginnersGuide/Download

Validate HTTP Server

Once the HTTP server is ready, test it.

We assume we are using webhook.site

Open a terminal and execute

curl -X POST -d"fizz=buzz" https://webhook.site/2500a2e2-d84a-4c1e-8761-d1c7160d163d

Check the webhook.site, you should see something like the following. Notice a request fizz=buzz has been received.

At this point AdvanNet can be configured.

Make sure the ReadMode generates TAG_READ events

Configure HTTP Service


[{

   "event":"TAG_READ",

   "path":"'/2500a2e2-d84a-4c1e-8761-d1c7160d163d'",

   "body":"

     var body='reader_name=\"AdvanReader 160\"&';

     body+='mac_address=\"'+ctx_devmac+'\"&';

     body+='line_ending=&';

     body+='field_delim=,&';

     body+='field_names=antenna_port,epc,first_seen_timestamp,peak_rssi&';

     body+='field_values='+ctx_tags[0].getAntenna()+',\"'+ctx_tags[0].getEPC()+'\",'+ctx_tags[0].getTime()+','+ctx_tags[0].getEPC();"

}]

Test complete example


If after following the whole process it is still not possible to receive any HTTP POST at your  webhook.site URL, please contact to support@keonn.com for further help. 

FAQ