Thingsboard Documentation

Documentation for using Thingsboard IoT Platform.

Getting Started

Introduction

The goal of this guide is for you to collect and visualize some IoT device data using Thingsboard. This guide will let you:

Setup and Requirements

If you don’t have access to a running Thingsboard instance, use either Live Demo or Installation Guide to fix this.

Demo account

All Thingsboard installations are equipped with demo account that simplifies first user experience. This demo account contains several pre-provisioned devices, dashboards, rules and plugins installed. Please note that you are free to delete this account in production deployment.

You can use Thingsboard device emulators to simulate real-life devices and play-around with server-side APIs, data visualization and processing logic.

We will use this emulators in advanced tutorials, however, the for the purpose of this guide, we will just use pre-provisioned tenant administrator account.

Login as a tenant administrator

The first step is to login to administration Web UI.

If you are using local Thingsboard installation you can login to administration Web UI using default account:

If you are using Live Demo you can login to Live Demo server using Tenant Administrator account (the one that you created during sign-up).

image

Provision your device

Open Devices panel and click on “+” button in the bottom-right corner of the page.

image

Populate and save device name (for example, “SN-001”). It will be referred to later as $DEVICE_NAME. Device names must be unique. Populating device name based on unique serial number or other device identifier is generally a good idea. Click “Add” button will add corresponding device card to the panel.

image

Manage device credentials

Click on the “device card” we have created in the previous step. This action will open “device details” panel.

Click on the “manage credentials” button on the top of the panel. This action will open popup window with device credentials.

image

Device credentials window will show auto-generated device access token that you can change. Please save this device token. It will be referred to later as $ACCESS_TOKEN.

image

Congratulations! You have just provisioned your first device! Now you can push some data from this device to Thingsboard for visualization and analysis.

Pushing data from the device

In order to simplify this guide, we will push data using MQTT, CoAP or HTTP protocol from your local PC. Please refer to samples for advanced examples of for various hardware platforms.

Client-side libraries installation

Install preferred MQTT (Mosquitto or MQTT.js), CoAP (CoAP.js) or HTTP (cURL) client using following commands.

resources/node-mqtt.sh
# Assuming you have Node.js and NPM installed on your Windows/Linux/MacOS machine
npm install mqtt -g
resources/mosquitto-ubuntu.sh
sudo apt-get install mosquitto-clients
resources/mosquitto-macos.sh
brew install mosquitto-clients
resources/node-coap.sh
sudo npm install coap-cli -g
resources/curl-ubuntu.sh
sudo apt-get install curl
resources/curl-macos.sh
brew install curl

Sample data files

Create some folder to store all necessary files for this tutorial. Download to this folder or create the following data files:

Please note that data in this files is basically in key-value format. You can use your own keys and values. See MQTT, CoAP or HTTP protocol reference for more details.

resources/attributes-data.json
{"firmware_version":"1.0.1", "serial_number":"SN-001"}
resources/telemetry-data.json
{"temperature":21, "humidity":55.0, "active": false}

Pushing data using MQTT, CoAP or HTTP

Download the following files to previously created folder according to the preferred client:

If you are using shell script (*.sh) make sure that it is executable:

chmod +x *.sh

Before executing script don’t forget to:

Finally execute corresponding *.sh or *.bat script to push data to the server.

Below are tabs with content of provided scripts.

resources/mqtt-js.sh
#!/bin/sh

# Set Thingsboard host to "demo.thingsboard.io" or "localhost"
export THINGSBOARD_HOST=demo.thingsboard.io

# Replace YOUR_ACCESS_TOKEN with one from Device credentials window.
export ACCESS_TOKEN=YOUR_ACCESS_TOKEN

# Read serial number and firmware version attributes
ATTRIBUTES=$( cat attributes-data.json )
export ATTRIBUTES

# Read timeseries data as an object without timestamp (server-side timestamp will be used)
TELEMETRY=$( cat telemetry-data.json )
export TELEMETRY

# publish attributes and telemetry data via mqtt client
node publish.js
resources/mqtt-js.bat
@echo off

REM Set Thingsboard host to "demo.thingsboard.io" or "localhost"
set THINGSBOARD_HOST=demo.thingsboard.io

REM Replace YOUR_ACCESS_TOKEN with one from Device credentials window.
set ACCESS_TOKEN=YOUR_ACCESS_TOKEN

REM Read serial number and firmware version attributes
set /p ATTRIBUTES=<attributes-data.json

REM Read timeseries data as an object without timestamp (server-side timestamp will be used)
set /p TELEMETRY=<telemetry-data.json

REM publish attributes and telemetry data via mqtt client
node publish.js
resources/publish.js
var mqtt = require('mqtt');

console.log('Connecting to: %s using access token: %s', process.env.THINGSBOARD_HOST, process.env.ACCESS_TOKEN);

var client  = mqtt.connect('mqtt://'+ process.env.THINGSBOARD_HOST,{
    username: process.env.ACCESS_TOKEN
});

client.on('connect', function () {
    console.log('Client connected!');
    client.publish('v1/devices/me/attributes', process.env.ATTRIBUTES);
    console.log('Attributes published!');
    client.publish('v1/devices/me/telemetry', process.env.TELEMETRY);
    console.log('Telemetry published!');
    client.end();
});
resources/mosquitto.sh
#!/bin/sh

# Set Thingsboard host to "demo.thingsboard.io" or "localhost"
THINGSBOARD_HOST="demo.thingsboard.io"
# Replace YOUR_ACCESS_TOKEN with one from Device credentials window.
ACCESS_TOKEN="YOUR_ACCESS_TOKEN"
# Publish serial number and firmware version attributes
mosquitto_pub -d -h "$THINGSBOARD_HOST" -t "v1/devices/me/attributes" -u "$ACCESS_TOKEN" -f "attributes-data.json"
# Publish timeseries data as an object without timestamp (server-side timestamp will be used)
mosquitto_pub -d -h "$THINGSBOARD_HOST" -t "v1/devices/me/telemetry" -u "$ACCESS_TOKEN" -f "telemetry-data.json"
resources/coap-js.sh
# Publish serial number and firmware version attributes
cat attributes-data.json | coap post coap://$THINGSBOARD_HOST/api/v1/$ACCESS_TOKEN/attributes
# Publish timeseries data as an object without timestamp (server-side timestamp will be used)
cat telemetry-data.json | coap post coap://$THINGSBOARD_HOST/api/v1/$ACCESS_TOKEN/telemetry
resources/curl.sh
# Publish serial number and firmware version attributes
# replace $THINGSBOARD_PORT with 8080 (in case of local installation) or 80 (in case of live-demo).
curl -v -X POST -d @attributes-data.json http://$THINGSBOARD_HOST:$THINGSBOARD_PORT/api/v1/$ACCESS_TOKEN/attributes --header "Content-Type:application/json"
# Publish timeseries data as an object without timestamp (server-side timestamp will be used)
# replace $THINGSBOARD_PORT with 8080 (in case of local installation) or 80 (in case of live-demo).
curl -v -X POST -d @telemetry-data.json http://$THINGSBOARD_HOST:$THINGSBOARD_PORT/api/v1/$ACCESS_TOKEN/telemetry --header "Content-Type:application/json"

Observe device data on the Web UI

Once you execute commands listed above you should see attributes and latest telemetry data in corresponding device detail tabs.

image

image

Create new dashboard to visualize the data

The easiest way to create new dashboard is to select device attributes and show them on widget

image

Once you click on “Show on widget” button, you will see a “widget preview” panel where you can

image

Let’s add our first widget to new dashboard named “SN-001 Dashboard”

image

Let’s also add widget to visualize temperature

image

Click Show on widget and select Digital gauges bundle. Use carousel to select thermometer widget as shown below.

image

Please note that in this case we will add widget to already existing dashboard. We will also select “Open dashboard” option to see results of our work.

image

Finally, we are able to see our new dashboard. Now we can edit the dashboard to

image

Next steps

Explore guides related to main Thingsboard features:

Your feedback

Don’t hesitate to star Thingsboard on github to help us spread the word. If you have some questions about this sample - post it on the forum.