IoT Open Tech
Home
  • Platform
  • Modules
  • Devices
Guides
Changelog
Home
  • Platform
  • Modules
  • Devices
Guides
Changelog
  • Getting started
    • API Access
    • Connect Gateway
    • Quick start
  • Integrations

    • Grafana plugin
    • Node-RED
    • Node-RED (MQTT)
    • SNMP Integration
    • Monitoring Plugin
    • Google Assistant
  • Gateways

    • Cisco IXM LoRa
      • Cisco IXM - Common Packet Forwarder
      • Cisco IXM - LoRa Packet forwarder
    • Inteno Firmware upgrade
    • Tektelic Kona Micro GW
    • LORIX One LoRa Gateway
      • LORIX One - LORIX OS
      • LORIX One - Legacy Image
    • Milesight LoRa Gateway
      • Milesight LoRa gateway with Semtech Packet Forwarder
    • Multitech LoRa Gateway
    • Raspberry Pi
    • Signal K Marine Server

Quick start

Prerequisites

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

Initial steps

Get hold of an 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:

HeaderValue
Content-Typeapplication/json
AuthorizationBasic XXXXXXXXX

Authentication is done with HTTP Basic auth, using any username and your API key as password (XXXXXXXXX above is username:api-key base64-encoded). 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 do not need to be connected to a device we can start by creating a function directly and use it to collect data.

Functions are 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 an object with a value in the system "my-test". The rest of the topic is decided by the integration.

Sending real-time data on MQTT

Connecting and listening for messages

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

NameValue
hostthe IoT Open URL
port8883
cleanSessiontrue (default in mosquitto tools)
usernamemy-integration
password{API-KEY}
client-idunique (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.

Last updated:
Prev
Connect Gateway