Overview

LinkSmart® Thing Publisher (LSTP) is intended to continuously expose proprietary sensor data in the OGC SensorThing format. The OGC SensorThing output is published over MQTT.

The sensor data is taken from a proprietary executable , which can be a script or a binary. The executable and a OGC based description, form a so called LSTP Thing. A LSTP Thing can be deployed to the system.

The deployment or removal of the LSTP Things is fully dynamic. The basic LSTP architecture is depicted in the following image.

LSTP uses MQTT to propagate data , so you may like to change the MQTT broker url line in the config file. The servicecatalog url parameter, allows you a registration with the LinkSmart Service Catalog. If you are not using the catalog, you may ignore this parameter.

Once you are done with configuration, you can start the binary thingpublisher. If the LSTP starts, you will see something like:

LSTP Thing archives

LSTP Things are the basic configuration structures for sensor integration and exposal. Every LSTP Thing configuration consists of two files inside an tar.gz archive. To create a LSTP Thing archive you need to create the following directory structure:

LSTP Thing archive

/sensors/
<your executable>
/things/
<your ogc sensor configuration>

The executable can be anything, a script or a binary. The executable should be cabable of writing sensor's raw data into it's stdout. Here a simple example of an LSTP conform executable :

LSTP compatible executable

#!/bin/bash
while true
do
echo "42"
sleep 2
done

Notice , that there is a loop producing continours output into the stdout. Without such a loop , the executable won't be accepted by the LSTP system.

The actual configuration of a LSTP Thing is an OGC SensorThing based json document. Here one example:

The most important fields are the name, the Sensor/description and the Sensor/metadata. The name is used as a unique string for later sensor identifcation. The Sensor/description is needed for exposure via MQTT topic. The metadata defines the name of the perviously mentioned executable. You can use whatever name and Sensor/description you like. The name of the executable should fit the file you put in to the sensors/ directory.

In case you put both files in to their respective directories, use tar to create an archive out of it. You may use the following command to create the archive:

LSTP archive creation

tar -czf example.tar.gz ./sensors ./things

There are two archive examples in the TEST/agentarchives directory. You may want to take a look at 42.tar.gz and the trng.tar.gz

Now you are ready to add an LSTP Thing archive to the running LSTP system.

LSTP API

The LSTP API is pretty straightforward. The commands allow, adding-, removing-, listing- and listing the status of Things. The API commands and responses are transfered via MQTT topics. The LSTP system by default subscribes to four topics.

An API command consists of <PREFIX>/<COMMAND> . The prefix can be changed in the thing-publisher.json file. With the default prefix the subscribed topics are:

For the responses , the client has to subscribe to the following topics:

API responses

LSTP/things
LSTP/thing/<name>

The LSTP/listthings command triggers a response in a form of a json list of all installed Things. The client has to subscribe to the LSTP/things topic to recieve the list.

Here an example of such a response :

LSTP/things response example

{
"name": "Sensor 01",
"name": "Sensor 02",
"name": "Sensor 03",
}

For adding a new thing to the system. The LSTP/addthingarchive command has to be called (). The payload of the MQTT will be the LSTP Thing archive. You can use a mqtt client of your choice , in case you are using the mosquitto client , adding an archive may looks like this:

Adding LSTP archive via mosquitto_pub

mosquitto_pub -t "LSTP/addthingarchive" -f temperature.tar.gz

Once the new Thing is installed, LSTP will send a status update change. The client has to subscribe to LSTP/thing/<name> . The message will looks like:

In the upper example , fields Temperature and fixed sensor come from the OGC json description. The first one represents the name tag and the second the description from the Sensor subsection.

When you have trouble deploying your archive, check the logs. One of the requirements for the executable is continous output to the stdout. If the executable is not printing data in to the stdout , it won't be deployed. The timeout for this is configured via thing-publisher.json

Change the "validatetimer": 8 accordingly to your needs. The default timers is set to 8 seconds.

If the client wants to get the status of the Thing an API call LSTP/thingstatus/<name> can be invoked. The client has to subscribe to LSTP/thing/<name> to recieve the status message. Again, the status message will be the previous "running" or:

LSTP/thing response example #2

{ "status" : "not available" }

To remove a Thing from the system , call LSTP/removething/<name> . The status update will be triggered once the removal is done. The client has again to subscribe to the LSTP/thing/<name> to recieve the status of the Thing