Blog

Blog

Broetchen API released!

The LinkSmart® team is proud to announce Broetchen API. Major releases are maintained to ensure that the involved services are interoperable, well documented and ready to use. Services of a major release work standalone but can also be integrated into a consistent LinkSmart® platform deployment.

Broetchen API is the first major release of next generation LinkSmart®. It includes the basic services for setting up device abstraction, service provisioning, time-series data storage and stream mining/learning functionalities. Broetchen API works seamlessly with the SenML data model.

Figure 1. LinkSmart Platform components. Green ones are released.

Device Gateway (≥1.1.0)

Documentation

Release Notes

  • Pluggable devices support
  • Natively compiled for major platforms and architectures, including arm linux
  • No modification/re-compilation/re-deployment of the DGW for a new device
  • Exposure of device capabilities as network services by declaration/configuration
  • Payload agnostic device exposure

Service Catalog (≥2.2.6)

Documentation

Release Notes

  • Exposes RESTful API for:
    • Registering and updating Services (also MQTT support)
    • Browsing the Service Catalog entries
    • Retrieving information about specific Services
    • Filtering Services

Historical Datastore (≥0.4.2)

Documentation

Release Notes

  • All three APIs fully implemented:
    • Registry API: Registry of sensor meta-data and details regarding sensor data storage and aggregation
    • Data API: Submission and retrieval of raw sensor measurements
    • Aggregation API: Retrieval of aggregated sensor measurements
  • Grafana Plugin

IoT Agents (≥1.7.0)

Documentation

Release Notes

  • Learning Agent & Data Processing Agent
  • Three APIs fully implemented
    • Stream Mining API (Statement API)
    • Learning API (CEML API)
    • IO API.
  • The Statement and CEML APIs are CRUD and JSON based, while the IO are write-only (for Input) or read-only (for Output). The APIs are implemented as HTTPS RESTful and MQTT.



FROST vs GOST

Here we compare two major OGC SensorThings implementations:

  •  GOST: Release V0.5 (docker release on 05-Mar-2018) 
  •  FROSTRelease V1.6 (docker release on 05-Mar-2018)



FeatureFROSTGOSTRemarks
LicenseLGPLMIT
LanguageJavaGolang
Incubator

Geodan
https://www.geodan.nl/

Fraunhofer IOSB 


Compliance to OGCFROST fully is compliant
Docker image sizes582MB14.2MB
Memory usage idle463.1MiB13.7MB
Storage BackendPostgreSQL 

PostgreSQL 

Plans to support storage providers such as MongoDB 


Clustering (Scalability etc)Not supportedNot supported

The goal of this Hackaton is to become familiar with several LinkSmart components and at the same time, create something useful. 

In the following steps we will setup the DHT Adafruit Library and LinkSmart Device Gateway on a Raspberry Pi 3 in order to read measurements from a DHT22 sensor and publish them in SenML format to a MQTT broker. 

1) Setup the DHT Library

  1. Install the latest stable Docker for debian-stretch (armhf). 
    1. Follow the instructions here (Tip: stretch>jessy>wheezy). Too lazy to follow instructions? Skip to step c.
    2. Optional: Post-installation (Manage Docker as a non-root user), so that docker commands run without sudo

    3.  Click here to expand...

      If you didn't go through steps a and b. Run the following commands:

      # Update the apt package index:
      $ sudo apt-get update
      # Install packages to allow apt to use a repository over HTTPS:
      $ sudo apt-get install \
           apt-transport-https \
           ca-certificates \
           curl \
           gnupg2 \
           software-properties-common
      # Add Docker’s official GPG key:
      $ curl -fsSL https://download.docker.com/linux/$(. /etc/os-release; echo "$ID")/gpg | sudo apt-key add -
      # Set up the stable repository:
      $ echo "deb [arch=armhf] https://download.docker.com/linux/$(. /etc/os-release; echo "$ID") \
           $(lsb_release -cs) stable" | \
          sudo tee /etc/apt/sources.list.d/docker.list
      # Update the apt package index:
      $ sudo apt-get update
      # Install the latest version of Docker CE:
      $ sudo apt-get install docker-ce
      # (Post Installation) Add your user to the docker group:
      $ sudo usermod -aG docker $USER

      Log out and log in. Then to verify that Docker CE is installed correctly, run the hello-world image. This command downloads a test image and runs it in a container. When the container runs, it prints an informational message and exits.

      $ docker run armhf/hello-world



  2. Create and enter the directory structure

    mkdir -p /home/pi/dgw 
    cd /home/pi/dgw
  3. Download Adafruit_DHT_SenML.py. This script reads temperature and humidity values from a DHT sensor and prints the measurements in SenML format. (You need appropriate drivers to run it)

    wget https://code.linksmart.eu/projects/LS/repos/linksmart-iot-hackatons/raw/iot-hackaton-2018-part1/Adafruit_DHT_SenML.py
  4. Use the following command to download an image with DHT drivers and runs it once. The command tries to read from a DHT22 sensor with data pin connected to GPIO 4 and SenML basename bn/. Remove these arguments to see usage instructions.

    docker run --privileged -v $(pwd):/home --entrypoint=python --rm farshidtz/adafruit_dht Adafruit_DHT_SenML.py 22 4 bn/

    The SenML output should be similar to:

    {"bn": "basename/", "e": [{"v": 21.0, "u": "Cel", "t": 1514631068, "n": "Temperature"}, {"v": 21.0, "u": "%RH", "t": 1514631068, "n": "Humidity"}]}

    If you didn't get an output similar to that, go back and figure out what went wrong.

2) Deploy Device Gateway

We'll use the DHT library container (from previous step) to run Device Gateway. The goal is to execute the Python script that reads the measurements and expose the SenML output over networking protocols.

  1. Download Device Gateway (device-gateway-linux-arm) and make it executable. Deployment instructions on wiki: https://docs.linksmart.eu/display/DGW.  

  2. Configure Device Gateway:

    1.  Configure the DGW service. Modify (replace <name> with the device hostname e.g. linksmart-cyan and <linksmart-broker> with the broker endpoint) and place in /home/pi/dgw/conf/device-gateway.json

      {
        "id": "",
        "description": "Example Gateway",
        "publicEndpoint": "http://fqdn-of-the-host:8080",
        "http": {
          "bindAddr": "0.0.0.0",
          "bindPort": 8080
        },
        "protocols": {
          "REST": {
            "location": "/rest"
          },
          "MQTT": {
            "url": "tcp://<linksmart-broker>:1883",
            "prefix": "<name>-dgw-",
            "offlineBuffer": 10000
          }
        }
      }
    2. Configure the device agent. Modify (replace <name>s with the device hostname, e.g. linksmart-cyan) and place in /home/pi/dgw/conf/devices/dht22.json

      With the following configuration, Device Gateway executes the Python script every 120 seconds and exposes the resulting data over two protocols:

      1. MQTT: Publishes the sensor data to the given topic. The MQTT broker was configured in step a.

      2. REST: Exposes a REST endpoint to GET the latest collected data. The HTTP server was configured in the step a. E.g for getting data: curl http://<hostname>:8080/rest/dht22/measurements  
      {
        "name": "dht22",
        "description": "This sensor measures Temperature and Humidity.",
        "resources": [
          {
            "type": "Resource",
            "name": "measurements",
            "agent": {
              "type": "timer",
              "interval": 120,
              "dir": null,
              "exec": "python /home/dgw/Adafruit_DHT_SenML.py 22 4 <name>/"
            },
            "protocols": [
              {
                "type": "MQTT",
                "methods": [
                      "PUB"
                ],
                "pub_topic": "LS/v2/DGW/<name>/senml"
              },
              {
                "type": "REST",
                "methods": [
                  "GET"
                ],
                "content-types": [
                  "application/senml+json"
                ]
              }
            ]
          }
        ]
      }


  3. Run the container:

    It should be in priviledged mode in order to access Raspberry Pi GPIO.

    cd /home/pi/dgw
    docker run --privileged -v $(pwd):/home/dgw --entrypoint=/home/dgw/device-gateway-linux-arm --rm farshidtz/adafruit_dht --conf /home/dgw/conf/device-gateway.json


If there were no errors, make a container that starts after boot and runs in detached mode (background):

docker run --privileged -v $(pwd):/home/dgw --entrypoint=/home/dgw/device-gateway-linux-arm -p 8080:8080 --name dgw_dht --restart=unless-stopped --log-opt max-size=10m -d farshidtz/adafruit_dht --conf /home/dgw/conf/device-gateway.json

Refer to docker run reference to understand the given arguments.


3) Try it out

  • Subscribe to the correct topic at the broker with the endpoint configured in DGW configuration.
  • Get latest measurement from the REST endpoint. The path comes from the names in device agent configuration. e.g. curl http://localhost:8080/dht22/measurements


Continue with other hackathons