Page tree

Get started by adding some pages to this space. Create page.

Skip to end of metadata
Go to start of metadata


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.



The Thing Publisher exposes an MQTT based API. The API consist ofour 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 avialable 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",
  "prefix": "LSTP/",
}

LSTP uses MQTT , so you may like to change the broker URL line in the config file.

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 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:

OGC SensorThing 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 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:

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

LSTP/thing response example
{ "status" : "running" }

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

OGC SensorThing 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 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



Source Codes

Visit LinkSmart® ThingPublisher Code



 (star) Optionaly a LSTP Thing archive can be added to the system by simply coping it into the dropzone/ directory.

  • No labels