Skip to content
This repository has been archived by the owner on Oct 29, 2020. It is now read-only.

Home

Jump to bottom
Farshid Tavakolizadeh edited this page Oct 29, 2020 · 2 revisions

LinkSmart Thing Publisher (LSTP) is intended to continuously expose proprietary sensor data in the OGC SensorThings format. The OGC SensorThings 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.

The Thing Publisher exposes an MQTT based API. The API consist four commands :

  • List all Things
  • Add new Thing
  • Remove a Thing
  • Status of a Thing

Summary

  • Start LSTP as described in Getting Started section
  • Create an LSTP Thing archive (LSTP Thing archives)
  • Deploy your archive via LSTP API (LSTP API)

Getting Started

LSTP is available for linux/amd64 and linux/arm. You can download the latest version here. The latest build can be found under Artifacts. Go there , choose your platform and download the package. Once untared , you may have to change the configuration file. The configuration is stored in conf/thing-publisher.json . Here you see a default thing-publisher.json file

thing-publisher.json

{
  "id": "LSTP",
  "description": "Linksmart ThingPublisher",
  "broker": "tcp://localhost:1883",
  "servicecatalog": "http://localhost:8082",
  "prefix": "LSTP/",
}

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 started

2017/10/20 15:26:43 ****************************************
2017/10/20 15:26:43 Linksmart ThingPublisher v 1.0.0-SNAPSHOT
2017/10/20 15:26:43 ****************************************
2017/10/20 15:26:43 [loadConfig] Using config file:  /home/carlos/TEST/LSTP-TEST/conf/thing-publisher.json
2017/10/20 15:26:43 [LSTPConfig] ID                           :  LSTP
2017/10/20 15:26:43 [LSTPConfig] Description                  :  Linksmart ThingPublisher
2017/10/20 15:26:43 [LSTPConfig] MQTT Broker URL              :  tcp://localhost:1883
2017/10/20 15:26:43 [LSTPConfig] Prefix                       :  LSTP/
2017/10/20 15:26:43 [LSTPConfig] Validate timer               :  8
2017/10/20 15:26:43 [LSTPConfig] UUID generation              :  false
2017/10/20 15:26:43 [LSTPConfig] Add Thing Archive (MQTT-API) :  addthingarchive
2017/10/20 15:26:43 [LSTPConfig] List Things       (MQTT-API) :  listthings
2017/10/20 15:26:43 [LSTPConfig] Remove Thing      (MQTT-API) :  removething
2017/10/20 15:26:43 [LSTPConfig] Thing Status      (MQTT-API) :  thingstatus
2017/10/20 15:26:43 [loadThings] working dir:  /LSTP-TEST/agents/
2017/10/20 15:26:43 [loadThings] scanning dir:  /LSTP-TEST/agents/
2017/10/20 15:26:43 [loadThings] sub-directories found :  0
2017/10/20 15:26:43 [startQuarantine] Quarantine started.
2017/10/20 15:26:43 [startQuarantine] waiting for new quarantine candidates...
2017/10/20 15:26:43 [startDropzone] Dropzone started.
2017/10/20 15:26:43 [startDropzone] watching directory :  /LSTP-TEST/dropzone
2017/10/20 15:26:43 [Publisher] Using MQTT broker:  tcp://localhost:1883
2017/10/20 15:26:43 [Publisher] Connected to :  tcp://localhost:1883
2017/10/20 15:26:43 [Publisher] Status Publisher started.
2017/10/20 15:26:43 [Publisher] Payload Publisher started.
2017/10/20 15:26:43 [startSubscriber] Subscriber connected to :  tcp://localhost:1883
2017/10/20 15:26:43 [startSubscriber] Subscriber started

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 capable of writing sensor's raw data into its 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 continuous 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 SensorThings based json document. Here one example:

OGC SensorThings description

{
  "name": "Temperature",
  "description": "constant temperature",
  "properties": {
    "Case Used": "demonstration"
  },
  "Datastreams": [{
    "name": "Answer",
    "description": "Empty",
    "unitOfMeasurement": {
      "name": "Degree",
      "symbol": "Celsius"
    },
    "Sensor": {
      "name": "Temperature Sensor",
      "description": "fixed sensor",
      "encodingType": "application/json",
      "metadata": "temperature.sh"
    }
  }]
}

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 identification. 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 transferred via MQTT topics. The LSTP system by default subscribes to four topics.

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

API commands

LSTP/listthings
LSTP/addthingarchive
LSTP/thingstatus/<name>
LSTP/removething/<name>

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 receive 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 ((star)). 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/ . The message will looks like:

LSTP/thing response example

{ "status" : "running" }

Also LSTP will start exposing data from the executable via OGC SensorThings MQTT payload. Here one example of:

OGC SensorThings MQTT payload

LSTP/Datastreams(Temperature)/fixed sensor {"result":"20.0","phenomenonTime":"2017-10-19T11:34:45Z"}

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 continuous 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/ can be invoked. The client has to subscribe to LSTP/thing/ to receive 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/ . The status update will be triggered once the removal is done. The client has again to subscribe to the LSTP/thing/ to receive the status of the Thing

Source Codes

Visit Github

  • Optionally a LSTP Thing archive can be added to the system by simply copying it into the dropzone/ directory.

Originally written by Karl Catewicz.

Clone this wiki locally