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
- Start LSTP as described in Getting Started section
- Create an LSTP Thing archive (LSTP Thing archives)
- Deploy your archive via LSTP API (LSTP API)
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
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:
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 :
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:
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.
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:
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 :
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:
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:
Also LSTP will start exposing data from the executable via OGC SensorThing MQTT payload. Here one example of:
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:
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
Optionaly a LSTP Thing archive can be added to the system by simply coping it into the dropzone/ directory.