MQTT Service

MQTT SERVICE

Introduction

This service offers the option to send data generated in a device to MQTT brokers.

Possible events are:

• TAG_READ events: as generated from inventory operations

• AdvanPay events:

  • TAG_ADPY_PAYMENT

  • TAG_ADPY_RETURN

  • TAG_ADPY_READ

• EAS events

  • TAG_ALARM

  • TAG_ALARM_ANTENNA_1

  • TAG_ALARM_ANTENNA_2

  • TAG_ALARM_ANTENNA_3

  • TAG_ALARM_ANTENNA_4

• [2.3.18-11+] SYSTEM_TIMER events

  • SYSTEM_1MINUTE_TIMER

  • SYSTEM_5MINUTE_TIMER

  • SYSTEM_10MINUTE_TIMER

  • SYSTEM_30MINUTE_TIMER

  • SYSTEM_60MINUTE_TIMER

• Other

  • TAG_ADDED

  • TAG_REMOVED

  • [2.5.3-04+] TAG_DIRECTION

  • [2.5.3-04+] GPI

Configuration

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

Required fields are marked with *

Connection

The connection options are:

• Broker*: examples of broker string connections are

  • tcp://192.168.1.43:1883

  • ssl://test.mosquitto.org:8883

• Client ID*: identifier of the MQTT client .

• QOS: MQTT Quality of Service

• Authentication Method (+Advannet 2.10.2)

  • No Authorization

  • Password

  • SAS Token

  • X.509 Certificate
    To be able to use a certificate, please contact support@keonn.com.

• Connection timeout (s): time in seconds before aborting a connection attempt

• Transport timeout (s): time in seconds to throe an error on a read/write operation

MQTT payload

• JSON config*: JSON list of maps that define the MQTT payload message format.

Details on the required format can be seen in the JSON config chapter.

Send options

The send options are:

• Send one by one: options are

  • true: in case of TAG_READ, it sends each reads in a different request

  • false: in case of TAG_READ, may send several reads in the same request

• Inventory tag TTL: in case of TAG_READ, do not send the same combination of EPC+antenna if they a previous match is found in the defined time window.

• Re-send: in case of error connections, re-enqueue again the events for later sent

  • The queue for inventory data has a capacity of 32768 items

  • The queue for events data has a capacity of 16384 items

  • Items can be in the queue for a maximum of 10 minutes, in case they cannot be sent in that time they are removed permanently.

Advanced JSON conf

This setting allows to configure additional parameters:

• debug: to enable additional debug information

• debugTransport: to enable debug information on the request/response data

• cleanSessionFlag: the value of the Clean Session flag (default= true)

• retainFlag: the value of the Retain flag (default= false)

An example of JSON is

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

Other advanced config

These options require SSH access. Please request SSH access if required.

1. With the SSH credentials, lo into the system

2. Locate the active AdvanNet directory.

3. Download file $ADVANNET/META-INF/connectors.xml

4. Change the file connectors.xml

Possible changes are:

• <com.keonn.MQTTService.MaxRetryTimeSecs>: maximum MQTT queue waiting time of the data to be sent.

The configuration options must be defined at the beginning of the file. For example:

<?xml version='1.0' encoding='utf-8'?>

<aliases>

    <load-order-scope>default</load-order-scope>

    <load-order>20000</load-order>

    <CONFIGURATION>

        <com.keonn.MQTTService.MaxRetryTimeSecs>86400</com.keonn.MQTTService.MaxRetryTimeSecs>

        <com.keonn.device.IgnoreUserConfigMac>true</com.keonn.device.IgnoreUserConfigMac>

        <logger>net.ihg.util.log.DummyLogger</logger>

        <com.keonn.advannet.manager.refreshIdPeriod>2000</com.keonn.advannet.manager.refreshIdPeriod>

        <com.keonn.advannet.manager.refreshMonitorPeriod>400</com.keonn.advannet.manager.refreshMonitorPeriod>

        <com.keonn.rest.aliasfile.AdvanNetCSVS>/home/keonn/csvs/data.csv</com.keonn.rest.aliasfile.AdvanNetCSVS>

        <com.keonn.rest.aliasfile.AdvanNetCSVSDir>/home/keonn/csvs/</com.keonn.rest.aliasfile.AdvanNetCSVSDir>

        <com.keonn.rest.aliasfile.AdvanNetConfFiles>/home/keonn/kernel/module/app.AdvanNet/META-INF,/root/.advannet/</com.keonn.rest.aliasfile.AdvanNetConfFiles>

        <com.keonn.rest.aliasfile.AdvanNetLog>/var/log/AdvanNet-kernel.log</com.keonn.rest.aliasfile.AdvanNetLog>

        <com.keonn.rest.aliasfile.AdvanNetLog2>/run/log/AdvanNet-kernel.log</com.keonn.rest.aliasfile.AdvanNetLog2>

        <com.keonn.rest.aliasfile.AdvanNetLogDir>/home/keonn/logs/,/var/log/</com.keonn.rest.aliasfile.AdvanNetLogDir>

        <com.keonn.rest.aliasfile.AdvanNetLogDir2>/run/log/</com.keonn.rest.aliasfile.AdvanNetLogDir2>

    </CONFIGURATION>
...

5. Verify the modified version is a valid XML file

6. Upload modified version

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.

JSON config

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

• event: fully qualified name of the event we want to use

• topic: topic where messages will be sent to

• body: javascript expression that defines a variable named body. 

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

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

Possible examples of a JSON config entry are

Example 1:

[{

"event":"TAG_READ",

"topic":"'/to/my/topic'",

"body":"

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

var i=0;

for(i=0;i<ctx_tagno;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>';

"

}

]

Example 2:

[{

"event":"TAG_READ",

"topic":"'/to/my/topic'",

"body":"

var body='{';

body+='\"devid\": \"'+ctx_devid+'\",';

body+='\"devip\": \"'+ctx_devip+'\",';

body+='\"devmac\": \"'+ctx_devmac+'\",';

body+='\"reads\": [';

for(i=0;i<ctx_tagno;i++)

{

body+='{';

body+='\"EPC\": \"'+ctx_tags[i].getEPC()+'\",';

body+='\"TID\": \"'+ctx_tags[i].getTID()+'\",';

body+='\"Antenna\": \"'+ctx_tags[i].getAntenna()+'\",';

body+='\"URI\": \"'+ctx_tags[i].getURI()+'\",';

body+='\"RSSI\": \"'+ctx_tags[i].getRSSI()+'\",';

body+='\"UTC time\": \"'+ctx_tags[i].getUTC()+'\",';

body+='\"Time stamp of the read with the local TimeZone offset\": \"'+ctx_tags[i].getTime()+'\",';

body+='\"Formatted UTC time\": \"'+ctx_tags[i].getUTCFormatted()+'\",';

body+='\"Formatted time of the read with the local TimeZone offset\": \"'+ctx_tags[i].getTimeFormatted()+'\"';

body+='}';

if(i< ctx_tagno - 1){

body+=',';

}

}

body+=']';

body+='}';

"

}]

Example 3:

[{

"event":"TAG_ALARM",

"topic":"'/topic/tag_alarm'",

"body":"

var body='{';

body+='\"type\": \"'+ctx_type+'\",';

body+='\"devid\": \"'+ctx_devid+'\",';

body+='\"devip\": \"'+ctx_devip+'\",';

body+='\"devmac\": \"'+ctx_devmac+'\",';

body+='\"epc\": \"'+ctx_epc+'\",';

body+='\"uri\": \"'+ctx_uri+'\"';

body+='}';

"

},

{

"event":"TAG_ADPY_PAYMENT",

"topic":"'/topic/tag_payment'",

"body":"

var body='{';

body+='\"type\": \"'+ctx_type+'\",';

body+='\"devid\": \"'+ctx_devid+'\",';

body+='\"devip\": \"'+ctx_devip+'\",';

body+='\"devmac\": \"'+ctx_devmac+'\",';

body+='\"epc\": \"'+ctx_epc+'\",';

body+='\"uri\": \"'+ctx_uri+'\"';

body+='}';

"

}]

Example 4:

[{

 "event":"GPI",

 "topic":"'name.of.my.topic'",

 "body":"var body=ctx_devid+','+ctx_devip+','+ctx_devmac+','+ctx_type+','+ctx_subtype;"

}]

Possible events

• TAG_READ events: as generated from inventory operations

• AdvanPay events:

  • TAG_ADPY_PAYMENT

  • TAG_ADPY_RETURN

  • TAG_ADPY_READ

• EAS events

  • TAG_ALARM

  • TAG_ALARM_ANTENNA_1

  • TAG_ALARM_ANTENNA_2

  • TAG_ALARM_ANTENNA_3

    • TAG_ALARM_ANTENNA_4

  • [2.3.18-11+] SYSTEM_TIMER events

    • SYSTEM_1MINUTE_TIMER

    • SYSTEM_5MINUTE_TIMER

    • SYSTEM_10MINUTE_TIMER

    • SYSTEM_30MINUTE_TIMER

    • SYSTEM_60MINUTE_TIMER

• Other events

  • TAG_ADDED

  • TAG_REMOVED

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

TAG_READ context

Available context variables are

• ctx_devid: device ID

• ctx_devip: device IP

• ctx_devmac: device MAC address expressed as 6b:31:58:87:a2:3c

• ctx_tags: this is an array containing all reads. Every entry has the following method

  • ctx_tags[i].getEPC(): the hexadecinal read EPC

  • ctx_tags[i].getSKU(): the TAG EPC SKU if the tag encoding is known

  • ctx_tags[i].getSerial(): the TAG EPC SKU serial if the tag encoding is known

  • ctx_tags[i].getTID(): the hexadecimal read TID (may be empty)

  • ctx_tags[i].getPhase(): the integer phase of the read

  • ctx_tags[i].getAntenna(): the integer antenna port

  • ctx_tags[i].getMux1(): the integer level one mux (may be 0)

  • ctx_tags[i].getMux2(): the integer level two mux (may be 0)

  • ctx_tags[i].getURI(): the read URI of the EPC (may be empty)

  • ctx_tags[i].getRSSI(): the integer read RSSI value

  • ctx_tags[i].getUTC(): as the Unix UTC time stamp of the read

  • ctx_tags[i].getTime(): as the Unix time stamp of the read with the local TimeZone offset

  • ctx_tags[i].getUTCFormatted(): as the formatted UTC time of the read expressed as yyyyMMddHHmmss.SSS

  • ctx_tags[i].getTimeFormatted(): as the formatted time of the read the local TimeZone offset expressed as yyyyMMddHHmmss.SSS

• ctx_tagno: this is the length of the ctx_tags array

Other events context

All other events share the same context variables

• ctx_devid: device ID

• ctx_devip: device IP

• ctx_devmac: device MAC address expressed as 6b:31:58:87:a2:3c

• ctx_type: the event type

• ctx_subtype: the event sub-type. For example the alarm type.

• ctx_epc: the event EPC (may be empty)

• ctx_sku: the event EPC SKU in case theEPC encoding is known (may be empty)

• ctx_serial: the event EPC SKU serial in case the EPC encoding is known (may be empty)

• ctx_uri: the event EPC URI (may be empty)

• ctx_utc_timestamp: UTC Unix timestamp

• ctx_timestamp: UTC with local time zone Unix time

• [2.3.18-11+] ctx_devstatus: device status [connected, running...]

Examples

application/xml

Send inventory data in xml format.

The JSON string is as follows.

[{

"event":"TAG_READ",

"topic":"'/to/my/topic'",

"body":"

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

var i=0;

for(i=0;i<ctx_tagno;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>';

"

}

]