IoT Open Tech

# Quick start

# Prerequisites

  • You will need to have a registered account in IoT Open.
  • Some knowledge about REST API:s and how to use them.
  • Knowledge about the basic IoT Open components and the data models referenced here.

# Initial steps

Get hold of a API key that can be used to authenticate in both APIs and MQTT by following this guide.

Install mosquitto-clients in your OS or find an alternative MQTT Client.

Create an installation in the web interface by following the first steps in this guide.

# Headers and authentication

All API requests are sent with the following headers:

Header Value
Content-Type application/json
Authentication Basic: XXXXXXXXX

Authentication is using any username and your API-key as password. The same is used in MQTT with the addition of client-id that is used to identify the client. This should be something unique and is set automatically when using the mosquitto tools.

# Creating a function

Since functions does not need to be connected to a device we can start by creating a function directly and use it to collect data.

Functions is created by using the FunctionX (opens new window) endpoint. The following data is sent as a POST request.

{
    "installation_id": 1234,
    "type": "temperature",
    "meta": {
      "name": "My temperature",
      "topic_read": "obj/my-test/stockholm/temperature",
      "format": "%.1f °C"
    }
  }

The topic defined here is later used to send data to the API. This topic specifies that we have a object with value in the system "my-test". The rest of the topic is decided by the integration.

# Sending realtime data on MQTT

# Connecting and listening for messages

The following parameters are used to connect to the MQTT bus:

Name Value
host the IoT Open URL
port 8883
cleanSession true (default in mosquitto tools
username my-integration
password {API-KEY}
client-id unique (mosquitto tools provides this)

To subscribe to your installation in our message bus you first need to find the Client-ID that your installation uses. This is done on the settings page of the installation in IoT Open then run the following command.

mosquitto_sub -t "<client-id>/#" -u my-integration -P <API-KEY> -p -8883 --capath /etc/ssl/certs -h <Lynx URL> -v

Leave this running in a terminal for now.

Since we use encrypted MQTT we need to specify the ca-path for certificates.

# Sending a message

The data to send is formatted like this:

{
  "timestamp": 1567159120,
  "value": 23.2
}

Sending is done with the mosquitto_pub command:

mosquitto_pub -t "<client-id>/obj/my-test/stockholm/temperature" -u my-integration -P <API-KEY> p -8883 --capath /etc/ssl/certs -h <Lynx URL> -m '{"timestamp": 1567159120, "value": 23.2}'

If everything worked as expected there should now be data in the other terminal and in Lynx. Try sending a couple of data-points with different timestamps.

# Visualizing data

The system automatically logs all values from MQTT so that they can be visualized later. The basic interface in the Lynx Web-UI can be used to get a text log of the reported values.

For further study or graphing see the grafana guide.

← Grafana plugin →