Getting Started

Docker is a container tool which provides kernel level virtualization for Linux. LinkSmart® project already has IoT Data-Processing Agent container image in a registry, ready to run. This tutorial aims to help with getting started using Docker.

If you are already familiar with the project, you can just run it with [docker-compose](https://docs.docker.com/compose/) without going through the rest of the steps.

# Download the compose file curl https://code.linksmart.eu/projects/LA/repos/data-processing-agent/raw/docker-compose-gs.yml -o docker-compose.yml # Running docker-compose up

1) MQTT Broker

First, an up and running MQTT Broker is required:

docker run -d --name mqtt-broker -p 1883:1883 -p 9001:9001 eclipse-mosquitto

2) Data-Processing Agent

Now we can run the agent linking to the broker. Environment variables can be set to configure the agent.

docker run -d --name agent -p 8319:8319 --link mqtt-broker -e "connection_broker_mqtt_hostname=mqtt-broker" -e "api_events_mqtt_topic_incoming_Observation=/testing/#" linksmart/agent:latest

Here the agent is configured to connect to mqtt-broker container by setting connection_broker_mqtt_hostname variable. It is also subscribed to OGC SensorThings Observation messages for /testing/# topic coming to the broker. (see the default configuration file for all parameters).

Since the REST API is exposed to the host machine, REST endpoints can be called from the host machine. The API documentation with an UI is hosted on localhost:8319/swagger-ui.html. You can go ahead and try it out on your browser.

3) Using the agent

We are going to publish some dummy messages to mqtt-broker in order to demonstrate data-processing capabilities:

docker run -d --name mqtt-client --link mqtt-broker aksakalli/mqtt-client publish

The same container will be also used to show all messages (topic #) arriving to the MQTT broker with this command:

docker exec -it mqtt-client sub -t "#" -h mqtt-broker -v

After that, this terminal session will start to receive demo OGC SensorThings Observation messages like:

{
  "Datastream":{  
    "@iot.id":1
  },
  "result":42,
  "resultTime":"2017-08-17T15:43:59Z"
}

Let's open a new terminal to add a new statement in order to get a number of messages arriving to MQTT broker in last 60 seconds.

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{
  "name":"count",
  "statement": "select count(*) from Observation().win:time(60 sec)"
}' 'http://localhost:8319/statement/'

After inserting this query, the agent will start to publish the query result to the broker as the following format:

{
   "@iot.id":"40c86297-2421-4e54-9a2e-5fef2f300e6e",
   "featureOfInterest":{
      "@iot.id":"6c35493a2b937829c9815c39e23af964bc84e5430a7dc104c700bbc0de2b59e3",
      "description":"count(*)",
      "observations":[
         {

         },
         {

         }
      ],
      "@iot.selfLink":"http://linksmart.eu/v1.0/FeatureOfInterest(6c35493a2b937829c9815c39e23af964bc84e5430a7dc104c700bbc0de2b59e3)",
      "[email protected]":"FeatureOfInterest(6c35493a2b937829c9815c39e23af964bc84e5430a7dc104c700bbc0de2b59e3)/Observations"
   },
   "datastream":{
      "@iot.id":"276f2948-c252-491b-9b93-8268383fdd92",
      "observations":[
         {

         }
      ],
      "sensor":{
         "@iot.id":"276f2948-c252-491b-9b93-8268383fdd92",
         "datastreams":[
            {

            }
         ],
         "@iot.selfLink":"http://linksmart.eu/v1.0/Sensor(276f2948-c252-491b-9b93-8268383fdd92)",
         "[email protected]":"Sensor(276f2948-c252-491b-9b93-8268383fdd92)/Datastreams"
      },
      "thing":{
         "@iot.id":"276f2948-c252-491b-9b93-8268383fdd92",
         "datastreams":[
            {

            }
         ],
         "@iot.selfLink":"http://linksmart.eu/v1.0/Thing(276f2948-c252-491b-9b93-8268383fdd92)",
         "[email protected]":"Thing(276f2948-c252-491b-9b93-8268383fdd92)/Datastreams",
         "[email protected]":"Thing(276f2948-c252-491b-9b93-8268383fdd92)/HistoricalLocations",
         "[email protected]":"Thing(276f2948-c252-491b-9b93-8268383fdd92)/Locations"
      },
      "@iot.selfLink":"http://linksmart.eu/v1.0/Datastream(276f2948-c252-491b-9b93-8268383fdd92)",
      "[email protected]":"Datastream(276f2948-c252-491b-9b93-8268383fdd92)/Observations",
      "[email protected]":"Datastream(276f2948-c252-491b-9b93-8268383fdd92)/Sensor",
      "[email protected]":"Datastream(276f2948-c252-491b-9b93-8268383fdd92)/ObservedProperty",
      "[email protected]":"Datastream(276f2948-c252-491b-9b93-8268383fdd92)/Thing"
   },
   "phenomenonTime":"2017-08-17T16:17:35.919+0000",
   "result":120,
   "@iot.selfLink":"http://linksmart.eu/v1.0/Observation(40c86297-2421-4e54-9a2e-5fef2f300e6e)",
   "[email protected]":"Observation(40c86297-2421-4e54-9a2e-5fef2f300e6e)/FeatureOfInterest",
   "[email protected]":"Observation(40c86297-2421-4e54-9a2e-5fef2f300e6e)/Datastream"
}

The result which is published for the statement is 120. It is also possible to access all statement objects over the rest API:

curl -X GET --header 'Accept: application/json' 'http://localhost:8319/statement/'