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